docutils-develop Mailing List for Docutils: Documentation Utilities (Page 422)

[Argh... I keep sending mails to the wrong adress :)]

On Mon, 08 Jul 2002 22:53:02 -0400 David Goodger
<go...@us...> wrote:

[...]

> > Ah, yes, I see what you mean. However, you still have a problem with
> > that name if you have multiple authors, so there needs to be some
> > solution for it anyway. For example, one could only allow ";" as
> > separator, although you might argue that it looks ugly. But
> > otherwise, "Kurt Vonnegut, Jr." would not be able to participate in
> > collaborations. :-)
> 
> As currently implemented, the "Authors" field can use either ";" or
> "," as separators, with ";" checked for first.  So the following would
> be parsed properly:
> 
>     :Authors: Kurt Vonnegut, Jr.; Kilgore Trout, Esq.

Ah, in that case it works very well. Hmmm... With Swedish there will still be
the same problem though, since there would not be different singular/plural
forms. The above "syntax" for names isn't used in Swedish names, but that
doesn't mean someone writing his/her name like that doesn't write Swedish
documents, so it needs to be handled there also...

Perhaps only ";" would be allowed as separator for Swedish documents? Hrm... 
I don't like that very much... :-/

---
Adam Chodorowski <ad...@ch...>

There are those who claim that magic is like the tide; that it swells
and fades over the surface of the earth, collecting in concentrated
pools here and there, almost disappearing from other spots, leaving
them parched for wonder.  There are also those who believe that if you
stick your fingers up your nose and blow, it will increase your
intelligence.
    -- The Teachings of Ebenezum, Volume VII

On Sun, 07 Jul 2002 10:29:12 -0400 David Goodger
<go...@us...> wrote:

> Adam Chodorowski wrote:
> > So apparantly ``.. Innehåll::`` is recognized as a valid directive at
> > *some* level, but later turned into a comment instead. I haven't tried
> > finding out what's wrong, yet.
> 
> I haven't had a chance to look at the code, and I won't for a few days (we
> have visitors), but I do have an idea.  Probably, the directive-detecting
> regular expression is checking for a "simple name" which is alphanumerics
> plus "-", "_", and ".".  "Alphanumerics" is probably limited to
> "[a-zA-Z0-9]", and should be expanded to cover the locale's idea of what
> letters should be, including accents.  The "å" in "Innehåll" is probably
> throwing it off.

I still haven't had time to investigate further, but it struck me that using
the current locale for this simply won't work: it needs to be determined from
the language (that docutils gets with --language). The reason is in server /
build environments where you need to build the docs correctly in a multitud of
different languages, when the locale will probably be "C". So this needs to be
controlled in some language file, I think.

On the subject of languages, how about adding a directive (or bibliographic
field) for specyfying the language used by the document? This way documents
would be self-contained, and you would not need to pass --language to docutils
to get the correct result. Something in the lines of:

.. Language: sv

or:

:Language: sv 

---
Adam Chodorowski <ad...@ch...>

Vampireware, n., a project capable of sucking the lifeblood out of anyone 
unfortunate enough to be assigned to it which never actually sees the 
light of day, but nonetheless refuses to die.
    -- Trygve Lode 

[David]
>>>> However, a simple enumerated or bulleted list will do just fine
>>>> for syntax. A directive could treat the list specially; e.g. the
>>>> first paragraph could be treated as a question, the remainder as
>>>> the answer (multiple answers could be represented by nested
>>>> lists).

[Adam]
>>> But with that aproach you have the same problem: you can only have
>>> short questions!

[David]
>> No, the question paragraph could be as long as you like.

[Adam]
> Yes, but you would not be able to have several paragraphs or other
> construct (like a table), which *might* be useful to explain the
> question more (although I agree that this is normally not the case
> for a FAQ).

In that case, extra syntax of some kind would be required (see answer
below).

>>> Wouldn't it make more sense to use a bulleted list for the
>>> questions and answers, and alternating between them (ie. the first
>>> bullet is a question, the second the answer, the third the
>>> question, and so on)?
>> 
>> No, that would be too clumsy.
> 
> Why do you think that?

Because questions and answers together form a logical unit (a "Q&A
list item").  With each question and each answer entered as individual
bullet list items, it would be hard to keep track of which is which.
You'd have to scan the contents to see if it contained question words
(why, what, etc.) or a question mark at the end.  If every "question"
list item had exactly one "answer" list item, it would be easy for the
parser to keep track, but perhaps not so easy for the reader.  Thus
the "Q" and "A" symbols that often accompany Q&A lists.

But sometimes there are questions without answers.  And sometimes
there are questions with multiple answers.  So a simple bullet list
with individual items for each question and each answer *isn't* enough
for the parser to keep track.  Both the human readers and the software
parser will need something more explicit.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

[David]
>> I think it best to leave the distinction::
>> 
>>     :Authors: Kurt Vonnegut, Jr.
>> 
>> This would look like two names.  Using ":Author:" instead makes it
>> clear.

[Adam]
> Ah, yes, I see what you mean. However, you still have a problem with
> that name if you have multiple authors, so there needs to be some
> solution for it anyway. For example, one could only allow ";" as
> separator, although you might argue that it looks ugly. But
> otherwise, "Kurt Vonnegut, Jr." would not be able to participate in
> collaborations. :-)

As currently implemented, the "Authors" field can use either ";" or
"," as separators, with ";" checked for first.  So the following would
be parsed properly:

    :Authors: Kurt Vonnegut, Jr.; Kilgore Trout, Esq.

I'll clarify this point in the docs.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Sun, 07 Jul 2002 10:29:12 -0400 David Goodger
<go...@us...> wrote:

> Adam Chodorowski wrote:
> > So apparantly ``.. Innehåll::`` is recognized as a valid directive at
> > *some* level, but later turned into a comment instead. I haven't tried
> > finding out what's wrong, yet.
> 
> I haven't had a chance to look at the code, and I won't for a few days (we
> have visitors), but I do have an idea.  Probably, the directive-detecting
> regular expression is checking for a "simple name" which is alphanumerics
> plus "-", "_", and ".".  "Alphanumerics" is probably limited to
> "[a-zA-Z0-9]", and should be expanded to cover the locale's idea of what
> letters should be, including accents.  The "å" in "Innehåll" is probably
> throwing it off.

Yes, this seems very likely. I'll have a closer look as soon as I get back
home. Thanks!

---
Adam Chodorowski <ad...@ch...>

No matter how subtle the wizard, a knife in the shoulder blades will seriously
cramp his style.
    -- McCloctnik the Lucid

Adam Chodorowski wrote:
> So apparantly ``.. Inneh=E5ll::`` is recognized as a valid directive at *so=
me*
> level, but later turned into a comment instead. I haven't tried finding o=
ut
> what's wrong, yet.

I haven't had a chance to look at the code, and I won't for a few days (we
have visitors), but I do have an idea.  Probably, the directive-detecting
regular expression is checking for a "simple name" which is alphanumerics
plus "-", "_", and ".".  "Alphanumerics" is probably limited to
"[a-zA-Z0-9]", and should be expanded to cover the locale's idea of what
letters should be, including accents.  The "=E5" in "Inneh=E5ll" is probably
throwing it off.

--=20
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Sun, 7 Jul 2002 04:44:05 +0200 Adam Chodorowski <ad...@ch...>
wrote:

> Here is a patch with language files for Swedish. 

But ofcourse I forgot to attach the actual patch itself. :) Here it is.

---
Adam Chodorowski <ad...@ch...>

Ludwig Boltzmann, who spent much of his life studying statistical mechanics, 
died in 1906, by his own hand. Paul Ehrenfest, carrying on the work, died 
similarly in 1933. Now it is our turn to study statistical mechanics.
    -- David L. Goodstein "States of Matter"

Hi.

Here is a patch with language files for Swedish. I have done some quick tests,
and there seems to be some problems with parsing of translated directives.
For example, the directive ``.. Innehåll::`` gets treated as a comment and
does not result in a table of contents being generated for some strange
reason. If I use the English version (``.. Contents::``) but with
--language=sv turned on, I get the error:

Reporter: ERROR (3) Unknown directive type "contents" at line 10.

.. Contents::

So apparantly ``.. Innehåll::`` is recognized as a valid directive at *some*
level, but later turned into a comment instead. I haven't tried finding out
what's wrong, yet.

Admonition directives seem to work fine, and so do bibliographic fields
although they get rearranged for some reason: "Författare" is put last, not
first in the generated output.

---
Adam Chodorowski <ad...@ch...>

War is Peace
Slavery is Freedom
Backspace is Delete.

On Fri, 05 Jul 2002 23:32:47 -0400 David Goodger
<go...@us...> wrote:

> Adam Chodorowski wrote:
> > I (will) have several little larger reST documents on a website and
> > I want to construct an index page with short descriptions and a link
> > to the full document. So I thought I'd simply extract the abstract /
> > introduction section of those documents for the short description on
> > the index page to avoid duplication and ease maintanence.
> > 
> > The idea is to churn through the documents twice: the first pass
> > creates the HTMl documents in full, while the second pass applies
> > this filter/transform to get the abstract and adds it to the index
> > page. 
> 
> I assume that there's more to the index file than just the abstracts
> (such as introductory material, and perhaps repeated wrappers around
> abstracts).  

It is actually a little more complex than that, since I want to do have news
items on the same page for which I intended to utilize the bibliographic
fields repeatedly (once for each news item, for since the author of each news
item can vary and definately the date). 

> I can think of several ways to do what you describe:
> 
> 1. First process each document individually, writing out each result
>    file as usual.  Then process the index file, which contains special
>    references (directives), one per document, which cause the
>    documents to be fully parsed a second time each and extract the
>    "abstract" topics and insert them into the body of the index
>    document.
> 
>    This would require some kind of "extraction" directives for the
>    index document.
> 
> 2. Store the abstracts as separate files, which are inserted into both
>    the individual documents and into the index file with "include"
>    directives (not yet implemented).
> 
>    This would require a new "include" directive (which is already on
>    the To Do list).
> 
> 3. As in (1), except process all of the individual documents in a
>    single process, storing the extracted abstracts in a list (so the
>    documents don't have to be processed a second time), and parse and
>    assemble the index file last.
> 
>    This would require a new specialized front-end, along with at least
>    a placeholder directive to locate the insertion-points for
>    abstracts.
> 
> 4. Write a full-blown templating system for Docutils.  I think
>    Python's ht2html.py is a good model: simple but effective.  Either
>    add programmability through a pre-processor like YAPTU or with
>    directives like "repeat".  Very vague ideas at this point.
> 
> Which were you thinking of?

Something along the lines of (1), although I did not intend to write the index
page in reST with special directives but rather write a script that calls the
docutils tools to generate the full documents and extract the abstracts into
files, which would then be concatenated with some extra HTML inserted
before/after and between them.

I do not like option (2) at all, since I would rather not split the document
up. One reason is that it would make it less readable as a plain text file
(unless one wrote a "plaintext" writer for docutils, but that would really be
a bit odd IMHO). 

All the other options you listed basically work fine for me. (4) is perhaps
the most tempting as a future system, but it would probably require some
substantial amount of work. For my current need it simply seems to be easier
to write some scripts and add a few filtering tools to docutils...

> > Another thing I would like to do is to either add templating support
> > to the HTML writer, or write a "fragment" HTML writer (which would
> > only write out the body of the document, so you can wrap it in your
> > own header/footer for layout (navigation bar etc)). But that's a
> > different topic. :)
> 
> The HTML writer already exposes the components, so you can just grab
> the document body (everything inside but not including <body> &
> </body>).  Use ``docutils.io.StringIO`` for the "destination_class"
> parameter of ``docutils.core.Publisher.__init__`` to avoid writing a
> file.  (Hmm, idea: NullIO class.)

Care to explain a little more? Perhaps I should take a closer look at the
relevant sources. Hmmm...

> However, the idea of custom headers & footers is what inspired the
> "decoration" element (which contains "header" & "footer" elements).
> It hasn't been fully developed yet.

Isn't that supposed to be a generic part of docutils for all kinds of writers?
I am not so interested in that, since the "decorations" that I want for my
online HTML version differ very greatly from the decorations I wish to have in
the PDF (for example) version. Perhaps I've misunderstood it though.
 
---
Adam Chodorowski <ad...@ch...>

Witness if you will Microsoft Outlook and Outlook Express, the two most
efficient virus propagation utilities ever devised by human intellectual
failure.
     -- Thomas C Greene / The Register

On Sat, 06 Jul 2002 01:06:34 -0400 David Goodger
<go...@us...> wrote:

> Adam Chodorowski wrote:
> > Actually, I meant:
> > 
> > 'author':nodes.authors,
> > 'authors':nodes.authors
> >  
> > Basically, the idea is to remove the difference between plural and
> > singular for the use for the most part (only retain it where the
> > language fits).
> 
> I think it best to leave the distinction::
> 
>     :Authors: Kurt Vonnegut, Jr.
> 
> This would look like two names.  Using ":Author:" instead makes it
> clear.

Ah, yes, I see what you mean. However, you still have a problem with that name
if you have multiple authors, so there needs to be some solution for it
anyway. For example, one could only allow ";" as separator, although you might
argue that it looks ugly. But otherwise, "Kurt Vonnegut, Jr." would not be
able to participate in collaborations. :-)


[FAQ directive]

> >> However, a simple enumerated or bulleted list will do just fine for
> >> syntax. A directive could treat the list specially; e.g. the first
> >> paragraph could be treated as a question, the remainder as the
> >> answer (multiple answers could be represented by nested lists).
> > 
> > But with that aproach you have the same problem: you can only have
> > short questions!
> 
> No, the question paragraph could be as long as you like.

Yes, but you would not be able to have several paragraphs or other construct
(like a table), which *might* be useful to explain the question more (although
I agree that this is normally not the case for a FAQ).

> > Wouldn't it make more sense to use a bulleted list for the questions
> > and answers, and alternating between them (ie. the first bullet is a
> > question, the second the answer, the third the question, and so on)?
> 
> No, that would be too clumsy.

Why do you think that?

---
Adam Chodorowski <ad...@ch...>

Chapter 1
    The story so far:
    In the beginning the Universe was created. This has made a lot of
    people very angry and been widely regarded as a bad move.

Adam Chodorowski wrote:
> Actually, I meant:
>=20
> 'author':nodes.authors,
> 'authors':nodes.authors
> =20
> Basically, the idea is to remove the difference between plural and
> singular for the use for the most part (only retain it where the
> language fits).

I think it best to leave the distinction::

    :Authors: Kurt Vonnegut, Jr.

This would look like two names.  Using ":Author:" instead makes it
clear.

>> I suppose an "authors" element could revert to "author" if it only
>> contains a single author, so yes, that's feasible.  For Swedish,
>> I'd suggest mapping a compound word like "one-author" to
>> nodes.author; that way it wouldn't be chosen accidentally but the
>> meaning would be explicit.  Like this::
>>=20
>>     'f=F6rfattare-singular':nodes.author,
>>     'f=F6rfattare':nodes.authors
>=20
> Wouldn't it be possible to leave 'f=F6rfattare-singular' out totally?
> I mean, since nodes.authors would be converted into nodes.author if
> there is only one author, 'f=F6rfattare-singular' isn't really of much
> value at all.

True.  Yes, leave it out.

> [FAQ directive]
>=20
>>> I actually have a FAQ document, where these directives would
>>> perhaps be usefull, although I have found that using section
>>> titles for the question and section contents works fine for a FAQ.
>>=20
>> That's a good idea.  Except, you can only have short questions
>> because titles can only be one line long.  Details!
>=20
> Hmmm... I read that part through, and the conclusion seems to be:
>=20
>> However, a simple enumerated or bulleted list will do just fine for
>> syntax. A directive could treat the list specially; e.g. the first
>> paragraph could be treated as a question, the remainder as the
>> answer (multiple answers could be represented by nested lists).
>=20
> But with that aproach you have the same problem: you can only have
> short questions!

No, the question paragraph could be as long as you like.

> Wouldn't it make more sense to use a bulleted list for the questions
> and answers, and alternating between them (ie. the first bullet is a
> question, the second the answer, the third the question, and so on)?

No, that would be too clumsy.

--=20
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Fri, 05 Jul 2002 22:49:15 -0400 David Goodger
<go...@us...> wrote:

> > Would it be possible to replace this with a single construct, ie.
> > always using an list of authors (if there is only one author, it
> > would be a list containing only one entry) and determine from
> > context if it is many or a single? This way, it would work for
> > Swedish and for English, since for English you can have the
> > mappings:
> > 
> > 'author':nodes.author,
> > 'author':nodes.authors
> 
> I assume you mean::
> 
>     'author':nodes.author,
>     'authors':nodes.authors
>            ^

Actually, I meant:

'author':nodes.authors,
'authors':nodes.authors
 
Basically, the idea is to remove the difference between plural and singular
for the use for the most part (only retain it where the language fits).

> I suppose an "authors" element could revert to "author" if it only
> contains a single author, so yes, that's feasible.  For Swedish, I'd
> suggest mapping a compound word like "one-author" to nodes.author;
> that way it wouldn't be chosen accidentally but the meaning would be
> explicit.  Like this::
> 
>     'författare-singular':nodes.author,
>     'författare':nodes.authors

Wouldn't it be possible to leave 'författare-singular' out totally? I mean,
since nodes.authors would be converted into nodes.author if there is only one
author, 'författare-singular' isn't really of much value at all.

> The ``docutils.transforms.frontmatter.DocInfo`` transform will need
> some work, probably in the ``extract_authors`` method.  Care to give
> it a try?  Not urgent.

I might take a look, but there are other pressing matters that feel a bit more
important right now. :)

[FAQ directive]

> > I actually have a FAQ document, where these directives would perhaps
> > be usefull, although I have found that using section titles for the
> > question and section contents works fine for a FAQ.
> 
> That's a good idea.  Except, you can only have short questions because
> titles can only be one line long.  Details!

Hmmm... I read that part through, and the conclusion seems to be:

> However, a simple enumerated or bulleted list will do just fine for syntax.
> A directive could treat the list specially; e.g. the first paragraph could
> be treated as a question, the remainder as the answer (multiple answers
> could be represented by nested lists).

But with that aproach you have the same problem: you can only have short
questions! Wouldn't it make more sense to use a bulleted list for the
questions and answers, and alternating between them (ie. the first bullet is a
question, the second the answer, the third the question, and so on)?

---
Adam Chodorowski <ad...@ch...>

FORTRAN? The syntactically incorrect statement "DO 10 I = 1.10" will parse and
generate code creating a variable, DO10I, as follows: "DO10I = 1.10"  If that
doesn't terrify you, it should.

Adam Chodorowski wrote:
> I (will) have several little larger reST documents on a website and
> I want to construct an index page with short descriptions and a link
> to the full document. So I thought I'd simply extract the abstract /
> introduction section of those documents for the short description on
> the index page to avoid duplication and ease maintanence.
> 
> The idea is to churn through the documents twice: the first pass
> creates the HTMl documents in full, while the second pass applies
> this filter/transform to get the abstract and adds it to the index
> page. 

I assume that there's more to the index file than just the abstracts
(such as introductory material, and perhaps repeated wrappers around
abstracts).  I can think of several ways to do what you describe:

1. First process each document individually, writing out each result
   file as usual.  Then process the index file, which contains special
   references (directives), one per document, which cause the
   documents to be fully parsed a second time each and extract the
   "abstract" topics and insert them into the body of the index
   document.

   This would require some kind of "extraction" directives for the
   index document.

2. Store the abstracts as separate files, which are inserted into both
   the individual documents and into the index file with "include"
   directives (not yet implemented).

   This would require a new "include" directive (which is already on
   the To Do list).

3. As in (1), except process all of the individual documents in a
   single process, storing the extracted abstracts in a list (so the
   documents don't have to be processed a second time), and parse and
   assemble the index file last.

   This would require a new specialized front-end, along with at least
   a placeholder directive to locate the insertion-points for
   abstracts.

4. Write a full-blown templating system for Docutils.  I think
   Python's ht2html.py is a good model: simple but effective.  Either
   add programmability through a pre-processor like YAPTU or with
   directives like "repeat".  Very vague ideas at this point.

Which were you thinking of?

> Another thing I would like to do is to either add templating support
> to the HTML writer, or write a "fragment" HTML writer (which would
> only write out the body of the document, so you can wrap it in your
> own header/footer for layout (navigation bar etc)). But that's a
> different topic. :)

The HTML writer already exposes the components, so you can just grab
the document body (everything inside but not including <body> &
</body>).  Use ``docutils.io.StringIO`` for the "destination_class"
parameter of ``docutils.core.Publisher.__init__`` to avoid writing a
file.  (Hmm, idea: NullIO class.)

However, the idea of custom headers & footers is what inspired the
"decoration" element (which contains "header" & "footer" elements).
It hasn't been fully developed yet.

>>> Also, I noticed that there seems to be some provision for language
>>> localization.
...
> The --language option is supposed to be used for this?

Yes.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Fri, 05 Jul 2002 19:08:29 -0400 David Goodger
<go...@us...> wrote:

> > I would like to implement a transform/filter with which you can
> > select a single section (by name or ordering) to be processed
> > further, filtering all the other ones out. This can be used for
> > extracting the abstract of a document, for example, so you can put
> > it on a separate page (with a link to the full document perhaps).

[...]
 
> Can you give us some background on what you're trying to accomplish?
> I'm not sure that a transform is what you want.  A transform modifies
> a document tree; perhaps you just want to extract part of an existing
> document tree?  Are you writing a custom Writer, such as to generate a
> multi-page web site?  Perhaps a subclass of the html4css1.py Writer?

I (will) have several little larger reST documents on a website and I want to
construct an index page with short descriptions and a link to the full
document. So I thought I'd simply extract the abstract / introduction section
of those documents for the short description on the index page to avoid
duplication and ease maintanence.  

The idea is to churn through the documents twice: the first pass creates the
HTMl documents in full, while the second pass applies this filter/transform to
get the abstract and adds it to the index page. 

Another thing I would like to do is to either add templating support to the
HTML writer, or write a "fragment" HTML writer (which would only write out the
body of the document, so you can wrap it in your own header/footer for layout
(navigation bar etc)). But that's a different topic. :)

> > Also, I noticed that there seems to be some provision for language
> > localization. Is this in a usable state and is the current API
> > reasonable stable? If so, I can contribute some code to support
> > swedish.
> 
> Usable: yes, in English.  No other language is installed yet, so I
> couldn't say.  Also, the code itself is not localized, just some
> strings for the parser to recognize and for use in generating output.

Yes, that's basically what I need (to have the generated string in the output
documents localized, like "Table of Contents"). I don't really care if the
docutils programs are localized themselves.  

> Stable API: that depends on whether or not it works.  It hasn't really
> been tested properly; just my first stab.  I imagine it will need some
> work, but that can only be determined through real-life use.

The --language option is supposed to be used for this? Anyway, I'll have a
stab at implementing and testing it for swedish. Easy little task to start
with. ;-)

> I was wondering -- Chodorowski -- a good Swedish name that.

Hehehe.. :) The name is Polish. I have Polish parents, but I live (and have
always done so) in Sweden. I could probably translate it to Polish also, but
it would be a little harder for me (not to mention that I don't have a Polish
keyboard layout nor the right character set :)).

---
Adam Chodorowski <ad...@ch...>

Chapter 1
    The story so far:
    In the beginning the Universe was created. This has made a lot of
    people very angry and been widely regarded as a bad move.

Adam Chodorowski wrote:
> I would like to implement a transform/filter with which you can
> select a single section (by name or ordering) to be processed
> further, filtering all the other ones out. This can be used for
> extracting the abstract of a document, for example, so you can put
> it on a separate page (with a link to the full document perhaps).
> 
> I would greatly apreciate any directions and tips where to start
> with this.  I guess I would inherit from Transform or Filter? Can
> you (in the application using docutils) specify/add extra
> transforms/filters to be used when processing a source?

Can you give us some background on what you're trying to accomplish?
I'm not sure that a transform is what you want.  A transform modifies
a document tree; perhaps you just want to extract part of an existing
document tree?  Are you writing a custom Writer, such as to generate a
multi-page web site?  Perhaps a subclass of the html4css1.py Writer?

> Also, I noticed that there seems to be some provision for language
> localization. Is this in a usable state and is the current API
> reasonable stable? If so, I can contribute some code to support
> swedish.

Usable: yes, in English.  No other language is installed yet, so I
couldn't say.  Also, the code itself is not localized, just some
strings for the parser to recognize and for use in generating output.

Stable API: that depends on whether or not it works.  It hasn't really
been tested properly; just my first stab.  I imagine it will need some
work, but that can only be determined through real-life use.

Contributions: always welcome.  I was wondering -- Chodorowski -- a
good Swedish name that.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Hi.

I would like to implement a transform/filter with which you can select a
single section (by name or ordering) to be processed further, filtering all
the other ones out. This can be used for extracting the abstract of a
document, for example, so you can put it on a separate page (with a link to
the full document perhaps).  

I would greatly apreciate any directions and tips where to start with this. 
I guess I would inherit from Transform or Filter? Can you (in the application
using docutils) specify/add extra transforms/filters to be used when
processing a source?

Also, I noticed that there seems to be some provision for language
localization. Is this in a usable state and is the current API reasonable
stable? If so, I can contribute some code to support swedish. 

---
Adam Chodorowski <ad...@ch...>

Computers are not intelligent. They only think they are.

On Thu, 04 Jul 2002 20:38:41 -0400 David Goodger
<go...@us...> wrote:

[...]

> > I guess I should use definitionlists then, but it would be nicer
> > with "real" option lists. :)
> 
> "Real" option lists are simply two-column lists, and are only possible
> because of the distinctive option prefixes.  You don't have that
> advantage, so you might want to look into alternatives, like the
> existing definition list or table syntax, the proposed simple table
> syntax (see http://docutils.sf.net/spec/rst/problems.html#tables,
> alternatives 3-6), or the proposed "columns" directive (see
> http://docutils.sf.net/spec/notes#body-columns).

Yes, although you loose some semantic information then (the fact that it is a
list of options). Oh well, I guess I'll have to live with that... :)

---
Adam Chodorowski <ad...@ch...>

There are two major products that come from Berkeley: LSD and UNIX.
We don't believe this to be a coincidence.
    -- Jeremy S. Anderson

Adam Chodorowski wrote:
> The problem for reST is the fact that you don't *need* to have
> modifiers on the options, so it's very hard to distinguish. A
> typical description of the options in ASCII text looks like:
> 
> FILE/M/A    Two or more files to be joined.
> AS=TO/K/A    The destination file.

Given your much longer description, I'm now even less optimistic.  In
fact, I'd have to say that the syntax is not suitable for specialized
markup like option lists.

> Hmmm... How about this syntax:
> 
> FILE/M/A    : Two or more files to be joined.
> AS=TO/K/A    : The destination file.

I seem to recall...  Yes, here it is.  About a year ago on Doc-SIG,
Tony Ibbs and I were discussing option lists and definition lists, and
he proposed a similar syntax.  But I didn't go for it then, and I'm
not going for it now, sorry.  The reason being, option lists are
modeled after the --help output of Unixish command-line programs.

Also, in the case of this specific syntax, a multi-line option
description would make it look too much like a definition list::

    OPTION/A  : A multi-line option
                description.

    term : classifier
        definition

> I guess I should use definitionlists then, but it would be nicer
> with "real" option lists. :)

"Real" option lists are simply two-column lists, and are only possible
because of the distinctive option prefixes.  You don't have that
advantage, so you might want to look into alternatives, like the
existing definition list or table syntax, the proposed simple table
syntax (see http://docutils.sf.net/spec/rst/problems.html#tables,
alternatives 3-6), or the proposed "columns" directive (see
http://docutils.sf.net/spec/notes#body-columns).

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Wed, 3 Jul 2002, Adam Chodorowski wrote:

> On Tue, 02 Jul 2002 21:48:20 -0400 David Goodger
> <go...@us...> wrote:
>
> > Adam Chodorowski wrote:
> > > Is there any plan for adding a "tree" construct to reST? It would be
> > > very useful for many things, for example displaying directory
> > > trees. You could use the following syntax (if it isn't ambigous, I
> > > don't know...):
> > >
> > > + Root
> > >   +- Child 1
> > >   |  +- Grandchild 1.1
> > >   |  +- Grandchild 1.2
> > >   +- Child 2
> >
> > No plans; this is the first request I've seen.  The syntax as given
> > *is* ambiguous: the "+" looks like a bullet.  It could easily be made
> > unambiguous though (for example, use "+-" throughout).
> >
> > What's the difference between a tree and a nested list?  You could
> > simply represent it like this:
>
> [example]
>
> > The list has a little more vertical space, but contains the same
> > information.
>
> Yes, conceptually nested lists and a tree are basically the same. One problem
> with the former is exactly the extra whitespace, which makes it impractical to
> really use for larger trees.
>
> The other part is mostly about presentation: nested lists are presented quite
> differently from how I would like trees to be (like my example with lines and
> such (which is IMHO actually useful for people reading the document)). Also,
> it would be quite easy to detect "interior nodes" and "leafe nodes", and you
> could vary the output accordingly (eg. put a directory icon before the
> interior ones, file icon before leaves).
>
> > Literal blocks (ASCII art) would be an easy way to get started.
> > Depending on what processing ought to be done to the tree, this
> > may be an adequate solution.
>
> Perhaps a directive followed by nested lists would be enough. The directive
> could simply wrap the lists with "this is really a tree", so it is possible to
> make the output look different (eg. the HTML writer could wrap it in <div
> class="tree"> so you could use the stylesheet to reduce vertical spacing etc)
> from regular nested lists (which you might want to use for other things). Eg.:
>
> .. tree::
>
>    Root
>
>    + Child 1
>
>      + Grandchild 1.1
>      + Grandchild 1.2
>
>    + Child 2

tree shows this in my home

.
|-- #pico17523#
|-- CVS-RCS-HOWTO.gz
|-- DSC48kl.jpg
|-- Desktop
|   |-- Autostart
|   `-- zip
`-- zip

on nt

+---bin
|   +---arj32
|   +---hexview
|   \---mysql
+---FilZip 2000
+---Install
|   +---3com

alternative

+- Root
   +- Child 1
   |  +- Grandchild 1.1
   |  +- Grandchild 1.2
   +- Child 2

if the parser recognizes the "+-" as tree start.

ending by "\" or "`" might easy the parser.

-- 
 BINGO: Wie gehts Ihnen mit ...?
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

On Wed, 03 Jul 2002 20:29:09 -0400 David Goodger
<go...@us...> wrote:

> Adam Chodorowski wrote:
> > Basically, I would like option lists to support also AmigaOS/AROS
> > syntax in option lists. I don't know how easy that would be to add.
> 
> Can you give a link to an authoritative (& specific) reference, with
> more detail and examples?  I don't understand what an AmigaOS command
> line should contain.

Hmmm... I can't find any usefull online reference really for the syntax.
You can find a reference over all standard AmigaDOS commands at
http://www.nethkin.com/bmori/amiga/dos2.html, which contains some real
examples.

The syntax is described in quite good detail in the documentation for the
ReadArgs() library function, although you have to ignore the implementation
details while reading it. Here's is an excerpt:

"ReadArgs() parses the commandline according to a template that is
passed to it.  This specifies the different command-line options and
their types.  A template consists of a list of options.  Options are
named in "full" names where possible (for example, "Quick" instead of
"Q").  Abbreviations can also be specified by using "abbrev=option"
(for example, "Q=Quick").

Options in the template are separated by commas.  To get the results
of ReadArgs(), you examine the array of longwords you passed to it
(one entry per option in the template).  This array should be cleared
(or initialized to your default values) before passing to ReadArgs().
Exactly what is put in a given entry by ReadArgs() depends on the type
of option.  The default is a string (a sequence of non-whitespace
characters, or delimited by quotes, which will be stripped by
ReadArgs()), in which case the entry will be a pointer.

Options can be followed by modifiers, which specify things such as
the type of the option.  Modifiers are specified by following the
option with a '/' and a single character modifier.  Multiple modifiers
can be specified by using multiple '/'s."

Then comes a list of allowed modifiers. For example, the template  for the
"Join" command (which concatenates files) is "FILE/M/A,AS=TO/K/A". 
Some typical invokations (which are all equivalent) would be:

% JOIN file1 file2 AS joined
% JOIN FILE file1 file2 TO joined

The problem for reST is the fact that you don't *need* to have modifiers on
the options, so it's very hard to distinguish. A typical description of the
options in ASCII text looks like:

FILE/M/A	Two or more files to be joined.
AS=TO/K/A	The destination file.

> Given your brief description, I'm not optimistic that it can be added
> easily.  All other option syntaxes begin with some symbol: -o, +o,
> --option, /OPT.  The parser relies on these symbols to do the parsing.
> Without them, it looks like ordinary text; no distinguishing
> characteristics.

Yes, I suspected that. :-/ I guess I should use definitionlists then, but it
would be nicer with "real" option lists. :) Hmmm... How about this syntax:

FILE/M/A	: Two or more files to be joined.
AS=TO/K/A	: The destination file.

?

---
Adam Chodorowski <ad...@ch...>

Alliance, n.:
   In international politics, the union of two thieves who have
   their hands so deeply inserted in each other's pocket that they cannot
   separately plunder a third.
      -- Ambrose Bierce, "The Devil's Dictionary"

Adam Chodorowski wrote:
> Basically, I would like option lists to support also AmigaOS/AROS
> syntax in option lists. I don't know how easy that would be to add.

Can you give a link to an authoritative (& specific) reference, with
more detail and examples?  I don't understand what an AmigaOS command
line should contain.

Given your brief description, I'm not optimistic that it can be added
easily.  All other option syntaxes begin with some symbol: -o, +o,
--option, /OPT.  The parser relies on these symbols to do the parsing.
Without them, it looks like ordinary text; no distinguishing
characteristics.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Hi, it's me again with another wishitem. ;-)

Basically, I would like option lists to support also AmigaOS/AROS syntax in
option lists. I don't know how easy that would be to add. The syntax looks
something like this:

NAME/K/N  Just you normal...
BOOL/S    ...docutils option descriptions.

The "/x" appended to the option-name are "switches" describing that option,
and might be left out for some of them.

NAME      And option without any switches.

The "/x" aren't actually used by the user on the command line, but are a guide
to how they can be used (in in a way what they do). /K says that you have to
use the keyword on the command line (cannot be implicit), /N that it is a
number, /S that it is a boolean and so on. 

This should (?) be quite simply to implement, apart from the last example
which might be ambigous. 

---
Adam Chodorowski <ad...@ch...>

Du räknar så dåligt att du måste vara naken för att kunna räkna till 21.
    -- Brad S / Datormagazin

On Tue, 02 Jul 2002 21:48:20 -0400 David Goodger
<go...@us...> wrote:

> Adam Chodorowski wrote:
> > Is there any plan for adding a "tree" construct to reST? It would be
> > very useful for many things, for example displaying directory
> > trees. You could use the following syntax (if it isn't ambigous, I
> > don't know...):
> > 
> > + Root
> >   +- Child 1
> >   |  +- Grandchild 1.1
> >   |  +- Grandchild 1.2
> >   +- Child 2
> 
> No plans; this is the first request I've seen.  The syntax as given
> *is* ambiguous: the "+" looks like a bullet.  It could easily be made
> unambiguous though (for example, use "+-" throughout).
> 
> What's the difference between a tree and a nested list?  You could
> simply represent it like this:

[example]

> The list has a little more vertical space, but contains the same
> information.

Yes, conceptually nested lists and a tree are basically the same. One problem
with the former is exactly the extra whitespace, which makes it impractical to
really use for larger trees. 

The other part is mostly about presentation: nested lists are presented quite
differently from how I would like trees to be (like my example with lines and
such (which is IMHO actually useful for people reading the document)). Also,
it would be quite easy to detect "interior nodes" and "leafe nodes", and you
could vary the output accordingly (eg. put a directory icon before the
interior ones, file icon before leaves). 

> Literal blocks (ASCII art) would be an easy way to get started.
> Depending on what processing ought to be done to the tree, this
> may be an adequate solution.

Perhaps a directive followed by nested lists would be enough. The directive
could simply wrap the lists with "this is really a tree", so it is possible to
make the output look different (eg. the HTML writer could wrap it in <div
class="tree"> so you could use the stylesheet to reduce vertical spacing etc)
from regular nested lists (which you might want to use for other things). Eg.:

.. tree::

   Root

   + Child 1 
     
     + Grandchild 1.1
     + Grandchild 1.2
 
   + Child 2
 
> Some preliminary questions to answer:  What's the internal/XML
> representation to be?  What should output look like (HTML, for
> example)?  Do you know of any precedent or useful references?

Apart from how common file managers present directory structures, no. 
I am not aware if such special constructs are available in other languages
(although it wouldn't suprise me if DocBook has); people seem to do this
mostly with lower-level (hackish, if you will) drawing constructs to get the
result they want.  
 
> If it is important to you, I'd say start with a directive.  I'd be
> glad to help you get started.

It's not extremely important, but I do have a document in HTML which uses
tables and icons to present and example directory tree very neatly which I
will be converting into reST. Basically, I want the reST output look just as
good as the HTML, so I don't get any complaints. ;-) 

---
Adam Chodorowski <ad...@ch...>

Chapter 1
    The story so far:
    In the beginning the Universe was created. This has made a lot of
    people very angry and been widely regarded as a bad move.

Richard Jones wrote:
> I had some ideas about converting ASCII art to real graphics a while back. Are
> there any decently supported vector graphics packages that I can invoke from
> Python to produce a nice-looking PNG output?

Sketch?  http://sketch.sf.net/

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Wed, 3 Jul 2002 11:48 am, David Goodger wrote:
> Literal blocks (ASCII art) would be an easy way to get started.
> Depending on what processing ought to be done to the tree, this
> may be an adequate solution.

I had some ideas about converting ASCII art to real graphics a while back. Are 
there any decently supported vector graphics packages that I can invoke from 
Python to produce a nice-looking PNG output?


    Richard