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

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:

    + Root

      + Child 1

        + Grandchild 1.1
        + Grandchild 1.2

      + Child 2

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

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.

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?

If it is important to you, I'd say start with a directive.  I'd be
glad to help you get started.

-- 
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.

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

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

Kleptomaniac, n.:
    A rich thief.
        -- Ambrose Bierce, "The Devil's Dictionary"

David Goodger (go...@us...) wrote:
> > I'd reorder this: (try command line). Try ASCII first, then UTF-8. If
> > ASCII passes, it most likely is ASCII. If not, and UTF-8 passes, it
> > most likely is UTF-8. Then try the locale's encoding.
> 
> Out of curiosity, is there any point in trying both ASCII and UTF-8?  UTF-8
> is a strict superset of ASCII, so shouldn't checking UTF-8 alone be enough
> for both?  If we don't care what the original encoding was (we just want
> Unicode text to process), does explicitly checking for ASCII buy us
> anything?

Hmm - I think checkin ASCII first would bring us the explicit knowledge
that it actually is ASCII and we could label the output as ASCII
(which might make it more compatible for older Software that doesn't
know about UTF-8 and might spew out weird errors even when it is
ASCII labelled as UTF-8).

Bye,
        Simon
-- 
      Sim...@un...       http://www.home.unix-ag.org/simon/

David Goodger <go...@us...> writes:

> Out of curiosity, is there any point in trying both ASCII and UTF-8?  UTF-8
> is a strict superset of ASCII, so shouldn't checking UTF-8 alone be enough
> for both?  If we don't care what the original encoding was (we just want
> Unicode text to process), does explicitly checking for ASCII buy us
> anything?

The answer to the last question is "no". The point in checking ASCII
specifically is that you then know that it is strictly ASCII (unless
it is iso-2022-jp, that is); if that is not interesting to know, there
is no point.

Regards,
Martin

Thanks for your reply, Martin.

> I'd reorder this: (try command line). Try ASCII first, then UTF-8. If
> ASCII passes, it most likely is ASCII. If not, and UTF-8 passes, it
> most likely is UTF-8. Then try the locale's encoding.

Out of curiosity, is there any point in trying both ASCII and UTF-8?  UTF-8
is a strict superset of ASCII, so shouldn't checking UTF-8 alone be enough
for both?  If we don't care what the original encoding was (we just want
Unicode text to process), does explicitly checking for ASCII buy us
anything?

-- 
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/

Aahz wrote:
> Note that Word is actually not the end product; they then convert to
> Frame for typesetting.  (They just do their copy-editing in Word.
> <sigh>)

Don't let it get you down.  From my experience, editors & publishers
like to keep manual control of documents, even when there are better
ways out there.  They like to fiddle.  Could be because of their
typically non-geek backgrounds and distrust of automation.

> I've made it clear to them that this is going to be a
> toolchain-based formatting system, and they haven't said anything
> about me being able to deal with Word documents.

That's good, but you may want to nail down what they *will* be sending
back to you, and what they expect you to do with it.  Could save some
grief later on.

>>> In the absence of better advice, I'm going to convert to
>>> OpenOffice's XML format, then use OpenOffice to convert to Word.

[David]
>> I found docs on the StarOffice XML spec (which is the draft for
>> OpenOffice) at http://xml.openoffice.org/.  It looks much more
>> promising than RTF.  If it's a reasonable markup -- and it appears
>> to be so -- then I don't forsee any major problems with an
>> "OpenOffice Writer" for Docutils.  Any takers?

[Aahz]
> It'll probably end up being me, either by writing a direct converter
> or by writing XSLT for the DocBook format.

I'd be wary of a "Docutils -> DocBook -> OpenOffice" chain, since it's
indirect.  An OpenOffice writer for Docutils, written in Python,
should be straightforward.  If you want to use XSLT, I think a direct
"Docutils XML -> OpenOffice" conversion would be better, because
"Docutils -> DocBook" (which is almost finished, in the sandbox) is
already quite inexact. Going indirectly would just compound the error.
 You'd need a "Docutils XML" writer, but that would be trivial; I'll
make one soon.

I must warn you that until there are definite plans to include PyXML
in Python's stdlib, we can't use XSLT in core Docutils.  This is
because Docutils aims to become part of the stdlib, and therefore
can't require 3rd-party packages.  The sandbox is always open though!
;-)

> There will definitely need to be directives in addition to
> interpreted text, for "see" and "see also" entries; it may be easier
> for now to use only directives.

I'm not following.  Could you give concrete examples (perhaps before &
after)?

>> Either way, no support for any of this is implemented yet.  Can you
>> spell out your requirements?
> 
> Yes and no.  I think I'm going to need to spend some time figuring
> out the current state of reST before I do much formal specification.

Informal would be fine.  As you write the text, see what kind of
functionality you want and share them here.  Don't worry about the
mechanics (directive or interpreted text or substitution or ...) too
much, just show a minimal "before & after" example and we'll figure it
out together.

> But if reST has some corresponding functionality for every element
> in DocBook,

It doesn't.  As Lennon Day-Reynolds wrote (Doc-SIG, June 16), "DocBook
is the 400-lb. gorilla of markup formats".  And it doesn't work the
other way either; although the Docutils DTD is relatively short and
simple, we have a few structures that DocBook doesn't.  So it goes.

> I know it can be made to work for my purposes.  (Yeah, I know that's not
> going to happen. ;-)

Docutils can be made to work regardless.

> BTW, how should one display the result of "import this"?  It's not
> an enumerated list nor a bulleted list, but it's definitely a list
> of some sort.

It could be thought of as a poem, in which case the "verse construct"
is appropriate.  You participated in the Doc-SIG thread (May 10).  See
http://docutils.sf.net/spec/notes.html#body-verse; there's a list of
alternate names at the end of the item.

It could also be thought of as a bulleted list with no bullets.  Hmm
-- gives me an idea, for another name and for a way to think of the
construct: line list.

-- 
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/

I wrote:
>> Seems that images are a pretty basic element of web pages these days; how
>> about adding a small section to docs/rst/quickstart.txt, O Original Author?

Richard Jones replied:
> Damn fine idea that :)

... and followed up with a quick checkin.  Thanks!

We sure don't get that kind of responsiveness from Micro$loth!

-- 
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/

Aahz wrote:
> I've been using .stx as the extension for my structured text files;
> should we adopt that as a standard for reST?

No, I'd rather we didn't.  I've been using plain old .txt, for the same
reason Richard gave, and because all platforms already have a .txt binding
(thus assigning an appropriate icon, and opening an appropriate application
upon double-click).  Include "human beings" in the list of "platforms" and
that's the only reason we need: instant recognition (with a pleasant
surprise hidden within).  In the past, .rtxt, .rst, .rest, and others have
been proposed, but I really don't see the need.  Specifically for .stx,
StructuredText (a la Zope) uses it sometimes, and I'd rather not create any
confusion.

You're free to do what you like for your own files, of course. ;-)

I'll add this to the FAQ (in PEP 287 -- hmm, perhaps it's time for a
separate faq.txt as well?).

-- 
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 Mon, 1 Jul 2002 13:32, Aahz wrote:
> I've been using .stx as the extension for my structured text files;
> should we adopt that as a standard for reST?

I actually use .txt, since I (see|have) no need to differentiate betwen the 
ReST-compatible text files and others.


   Richard

On Mon, 1 Jul 2002 13:10, David Goodger wrote:
> Richard Jones wrote:
> > I've just had to clear up some confusion with a workmate who thought
> > that image directives only handled PNG files!
>
> A very confused workmate indeed!

Yeah, took me ages before I cottoned on to what his problem really was! :)


> OK, a reasonable (if a tad bizarre at first) request.  Minor changes
> have been made in both reStructuredText.txt and directives.txt (I'll
> check 'em in next time I've got something substantive).  Seems that
> images are a pretty basic element of web pages these days; how about
> adding a small section to docs/rst/quickstart.txt, O Original Author?

Damn fine idea that :)


  Richard

I've been using .stx as the extension for my structured text files;
should we adopt that as a standard for reST?
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Richard Jones wrote:
> I've just had to clear up some confusion with a workmate who thought
> that image directives only handled PNG files!

A very confused workmate indeed!

> The spec only refers to PNG files, but doesn't specify anywhere that
> only PNG may be used. So maybe either there needs to be a note
> saying that the directive is format-agnostic, or perhaps the
> examples need to include the occasional JPEG...

Talk about hand-holding!  Don't they teach these hotshots how to
*extrapolate*?  ;-)

OK, a reasonable (if a tad bizarre at first) request.  Minor changes
have been made in both reStructuredText.txt and directives.txt (I'll
check 'em in next time I've got something substantive).  Seems that
images are a pretty basic element of web pages these days; how about
adding a small section to docs/rst/quickstart.txt, O Original Author?

-- 
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/

I've just had to clear up some confusion with a workmate who thought that 
image directives only handled PNG files! The spec only refers to PNG files, 
but doesn't specify anywhere that only PNG may be used. So maybe either there 
needs to be a note saying that the directive is format-agnostic, or perhaps 
the examples need to include the occasional JPEG...


   Richard

On Sun, 30 Jun 2002 10:05, Aahz wrote:
> BTW, how should one display the result of "import this"?  It's not an
> enumerated list nor a bulleted list, but it's definitely a list of some
> sort.

I believe it's prose, which has been discussed before as needed (well, some 
think just having hard line breaks would be nice, but that's inelegant :)

I've been getting some more users at ekit to use ReST for docco. They 
generally find it quite nice, but the lack of hard line breaks means that 
they often have too much whitespace where it's not wanted. I haven't actually 
looked closely at what constructs they're using - I suspect in the current 
case they're using field-list-ish structures, so I should be able to tweak 
the stylesheet for them to remove the extra whitespace if that's the case.

I've also removed the margin from footnotes to good effect. See:

   http://www.zope.org/Members/richard/docs/zope_optimisation.html

for the result. Note the footnotes are joined, rather than having ~10px 
spacing between. A bottom margin for the last footnote would probably be a 
nice tweak - but currently only Mozilla supports the last-child selector.


    Richard

Sorry for the long delay on this response, but I've been too
scatter-brained to concentrate on this.  I'm combining responses to two
separate messages.

On Tue, Jun 04, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> All right, I'm ready to get started on writing my book.
> 
> Great!  What's the title and/or subject, if you can say?  Are there
> any special features you'll need?

Working title is _Effective Python_, playing off _Effective C++_ and
_Effective Java_.  The subject should be pretty obvious if you're
familiar with those, though the emphasis will be a bit different.  If
you're not familiar with those books, it's basically a cross between a
tutorial and a reference book for the intermediate programmer, short
enough to carry around easily (targeted at 250 pages).  The final title
will change because my publisher is Manning and we don't want to look
like we're poaching on Addison-Wesley.

>> My publisher wants the document in Word format.
> 
> My condolences.

Well, if we do this right, it won't matter, since the ASCII source will
be the same.

>> I'm starting in some form of ASCII, quite likely reST.
> 
> Glad to hear it.  I (and hopefully others involved with Docutils) will
> be happy to help.
> 
> But are there any other requirements other than "Word"?  When I wrote
> a chapter on Python for Wrox [*]_, they sent me an elaborate (and
> broken) stylesheet to use.  Anything like that?  Could be significant.
> 
> .. [*] *Professional Linux Programming*, chapter 15.  My mug is at the
>    far right, second from the top.

It's not clear, but it shouldn't matter -- if I send them the correct
style tags, they should be able to handle it properly.  Note that Word
is actually not the end product; they then convert to Frame for
typesetting.  (They just do their copy-editing in Word.  <sigh>)

> Once you produce a Word document, I assume your publisher will add
> comments to the Word files and send them back to you for revision.
> (Wrox loved using Word's comment feature.)  Will your publisher
> insist on preserving the comments and revision history?  If they do
> insist on "read-write" Word files, you're screwed, and are stuck with
> Word.  If they'll accept fresh, uncommented drafts each time, then
> using a toolchain to generate Word files as a final, read-only display
> format should be feasible.  On second thought, I think you can merge
> versions of documents in Word, so you might be safe either way.

I've made it clear to them that this is going to be a toolchain-based
formatting system, and they haven't said anything about me being able to
deal with Word documents.

> [Engelbert Gruber]
>>> for going to word html might be not a bad option as word would read
>>> it as i heard. what means word actually, a word readable format is
>>> definately something different ? would rtf be word enough ?
> 
> [Aahz]
>> RTF is an old format with few features; in particular, it doesn't
>> support index tags.
> 
> If anyone cares to dig in deep, the RTF 1.6 spec is online at:
> http://msdn.microsoft.com/library/?url=/library/en-us/dnrtfspec/html/rtfspec
> .asp
> The 1.7 spec can be downloaded from:
> http://download.microsoft.com/download/Word2002/Install/1.7/W98NT42KMeXP/EN-
> US/W2KRTFSF.exe

Yeah, I've been thinking about that.  I've been informed that I'm wrong
about RTF not supporting index tags, but one advantage of using
OpenOffice as the intermediate formate is that it's editable.

>> I suspect HTML would have the same problem; I'll assume it does
>> unless someone can tell me otherwise from direct experience.
> 
> With the "class" attribute on "span" and "group" elements, HTML can
> represent literally anything, if indirectly and inelegantly.  The
> problem is, can the software *reading* the HTML (Word, in this case)
> *do* anything with this information?  Probably not.  You'll need more
> direct access to native features.

Yes, exactly.

>> In the absence of better advice, I'm going to convert to
>> OpenOffice's XML format, then use OpenOffice to convert to Word.
> 
> I found docs on the StarOffice XML spec (which is the draft for
> OpenOffice) at http://xml.openoffice.org/.  It looks much more
> promising than RTF.  If it's a reasonable markup -- and it appears to
> be so -- then I don't forsee any major problems with an "OpenOffice
> Writer" for Docutils.  Any takers?

It'll probably end up being me, either by writing a direct converter or
by writing XSLT for the DocBook format.  One problem I've discovered
with OpenOffice's "XML format" is that it isn't, really.  It's a ZIP
package of several XML documents.  Not a huge problem, but a bit
annoying.

>> What I'd really like is a DocBook-to-Word converter, but I haven't
>> seen anything like that.  If I don't get anything here, my next step
>> is to ask on comp.text.xml.
> 
> I wouldn't be surprised if DocBook-to-Word converters *do* exist.  The
> question then becomes, how to produce the DocBook?  Would you still
> use reStructuredText?  A "DocBook Writer" for Docutils shouldn't be
> too challenging.

Yes, I'm committed to starting with some kind of simple ASCII, no matter
what.  Haven't seen any evidence for DocBook-to-Word converters, and
it's definitely true that Jade's RTF converter doesn't support index
tags.

> Did that scare you off?  If not, I'm sure that together we can come up
> with a decent system.  Input from real-life usage like this is
> invaluable.  Docutils will undoubtedly benefit.

Not scared, but not sure how much I'll be able to contribute other than
feedback and the OpenOffice converter.  I'm willing to do a fair bit,
because I've had graphic evidence writing my OSCON slides how effective
structured text can be for rapid generation of formatted text.  (I used
my own structured text language and utility.)


On Mon, Jun 24, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> Do you have a mechanism for generating index entries?
> 
> I doubt Oliver's DocBook writer does, because reStructuredText and the
> rest of DocBook doesn't, yet.  You'll be needing these?

Absolutely.  If it weren't for index tags, I could probably use a lot of
other options.

> For your purposes, setting a default role of "index" may do the trick.
> If all of your index entries will appear verbatim in the text, this
> should be sufficient.  If not (e.g., if you want "Van Rossum, Guido"
> in the index but "Guido van Rossum" in the text), we'll have to figure
> out a supplemental mechanism, perhaps using substitutions.

There will definitely need to be directives in addition to interpreted
text, for "see" and "see also" entries; it may be easier for now to use
only directives.

> Either way, no support for any of this is implemented yet.  Can you
> spell out your requirements?

Yes and no.  I think I'm going to need to spend some time figuring out
the current state of reST before I do much formal specification.  But if
reST has some corresponding functionality for every element in DocBook,
I know it can be made to work for my purposes.  (Yeah, I know that's not
going to happen. ;-)

BTW, how should one display the result of "import this"?  It's not an
enumerated list nor a bulleted list, but it's definitely a list of some
sort.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

David Goodger <go...@us...> writes:

> - Try the encoding specified by a command-line option, if any.
> 
> - Try the locale's encoding.
> 
> - Try UTF-8.
> 
> - Try platform-specific encodings: CP-1252 on Windows, Mac-Roman on
>   MacOS, perhaps Latin-9 (iso-8859-15) otherwise.
> 
> Does this look right, or am I missing something?

I'd reorder this: (try command line). Try ASCII first, then UTF-8. If
ASCII passes, it most likely is ASCII. If not, and UTF-8 passes, it
most likely is UTF-8. Then try the locale's encoding.

> - Does the application have to call
>   ``locale.setlocale(locale.LC_ALL, '')``, and if so, where?  Is it OK
>   to call setlocale from within the decoding function, or should it be
>   left up to the client application?

Atleast on Solaris, you need this to get nl_langinfo to work correctly.

> - Should I use the result of ``locale.getlocale()``?  On
>   Win2K/Python2.2.1, I get this::
> 
>       >>> import locale
>       >>> locale.getlocale()
>       (None, None)
>       >>> locale.getdefaultlocale()
>       ('en_US', 'cp1252')
>       
>   Looks good so far.

No; this is broken beyond repair. On Unix, try nl_langinfo(CODESET)
(requires Python 2.2).  On Windows, try _getdefaultlocale. If either
fails, you may then fall-back to getlocale, but expect it to fail with
exceptions, and to err.

>   How can I use ``locale.getlocale()`` when it doesn't return a
>   known encoding?  Or put another way, how can I get a known
>   encoding out of ``locale.getlocale()``?

[Don't use getlocale]. If nl_langinfo gives an unknown codeset,
produce a warning message, asking the user to report that as a
bug. Keep a list of additional aliases for codesets that occur in the
wild and are aliases to known codecs, also keep a list of known
unsupported codesets (again, restrict yourself to those occurring in
the wild).

> - Does ``locale.getdefaultlocale()[1]`` reliably produce the
>   platform-specific encoding?

No.

Regards,
Martin

I'm implementing support for Unicode and encodings in Docutils, and
have some questions about locales and determining encodings.  I want
Docutils to be able to handle files using any encoding.  Having read
Skip Montanero's "Using Unicode in Python"
(http://manatee.mojam.com/~skip/unicode/unicode/) and "Introduction to
i18n" by Tomohiro KUBOTA
(http://www.debian.org/doc/manuals/intro-i18n/), I came up with the
following heuristics:

- Try the encoding specified by a command-line option, if any.

- Try the locale's encoding.

- Try UTF-8.

- Try platform-specific encodings: CP-1252 on Windows, Mac-Roman on
  MacOS, perhaps Latin-9 (iso-8859-15) otherwise.

Does this look right, or am I missing something?

My questions:

- Does the application have to call
  ``locale.setlocale(locale.LC_ALL, '')``, and if so, where?  Is it OK
  to call setlocale from within the decoding function, or should it be
  left up to the client application?
  
- Should I use the result of ``locale.getlocale()``?  On
  Win2K/Python2.2.1, I get this::

      >>> import locale
      >>> locale.getlocale()
      (None, None)
      >>> locale.getdefaultlocale()
      ('en_US', 'cp1252')
      
  Looks good so far.
  
      >>> locale.setlocale(locale.LC_ALL, '')
      'English_United States.1252'
      >>> locale.getlocale()
      ['English_United States', '1252']
  
  "1252"?  What happened to the "cp"?

      >>> s='abcd'
      >>> s.decode('1252')
      Traceback (most recent call last):
        File "<stdin>", line 1, in ?
      LookupError: unknown encoding

  How can I use ``locale.getlocale()`` when it doesn't return a
  known encoding?  Or put another way, how can I get a known
  encoding out of ``locale.getlocale()``?

- Does ``locale.getdefaultlocale()[1]`` reliably produce the
  platform-specific encoding?

Here's the decoding code I've written::

    def decode(self, data):
        """
        Decode a string, `data`, heuristically into Unicode.
        Raise UnicodeError if unsuccessful.
        """
        encodings = [self.options.input_encoding, # command-line option
                     locale.getlocale()[1],
                     'utf-8',
                     locale.getdefaultlocale()[1],]
        # is locale.getdefaultlocale() platform-specific?
        for enc in encodings:
            if not enc:
                continue
            try:
                decoded = unicode(data, enc)
                return decoded
            except UnicodeError:
                pass
        raise UnicodeError(
            'Unable to decode input data.  Tried the following encodings:'
            '%s.' % ', '.join([repr(enc) for enc in encodings if enc]))

Suggestions for improvement and/or pointers to other resources would
be most appreciated.  Thank you.

-- 
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 Goodger wrote:
> If all of your index entries will appear verbatim in the text, this
> should be sufficient.  If not (e.g., if you want "Van Rossum, Guido"
> in the index but "Guido van Rossum" in the text), we'll have to
> figure out a supplemental mechanism, perhaps using substitutions.

I've thought a bit more on this, and I came up with two possibilities:

1. Using interpreted text, embed the index entry text within the
   interpreted text::

       ... by `Guido van Rossum [Van Rossum, Guido]` ...

   The problem with this is obvious: the text becomes cluttered and
   hard to read.  The processed output would drop the text in
   brackets, which goes against the spirit of interpreted text.

2. Use substitutions::

       ... by |Guido van Rossum| ...

       .. |Guido van Rossum| index:: Van Rossum, Guido

   A problem with this is that each substitution definition must have
   a unique name.  A subsequent ``.. |Guido van Rossum| index:: BDFL``
   would be illegal.  Some kind of anonymous substitution definition
   mechanism would be required, but I think that's going too far.

Both of these alternatives are flawed.  Any other ideas?

-- 
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/

Richard Jones wrote:
> An alternative to the "role" concept, where all text marked up in
> `backquotes` is assigned a particular role, would be to extend the
> parser to handle `index me`i or similar, to make the index tagging
> explicit.

That's what `index me`:i: does (could do).  There's more syntax, but
it's there on purpose, to emphasize the role.  Without any extra
syntax it looks like a typo, and may be too subtle to notice.

The implicit role idea is that in any particular application, there's
going to be one interpreted text role that is used more than any
other.  For that one role, no explicit :role: markup is required, just
the `interpreted text` alone.  A convenience feature, but significant.
 Any other roles used will need explicit markup.

For docstrings in Python source, the implicit role will be "look up
this text as a Python identifier in the current namespace, and
automatically link to the definition of that identifier; the role
itself is determined from context: the type of the identifier."  For
Aahz's book, it might be "mark this text as an index entry".

The syntax for explicit interpreted text roles has yet to be tested in
the real world; it's still just an idea that I'm not dead-set on.  I'm
open to alternatives.  There's no real difference between `this`:role:
and  `this`<role> and `this`{role}; I chose :colons: because they're
also used for field lists, <angle> brackets are too strongly
associated with XML/SGML/HTML tags (and we'll probably see a lot of
documents *featuring* such tags as subject matter), and {braces} are
used in TeX and in ordinary text (especially technical text).  For
details of these and other alternatives considered, see
http://docutils.sf.net/spec/rst/alternatives.html#interpreted-text-roles.

-- 
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 Mon, Jun 24, 2002, David Goodger wrote:
>
> - Docutils is intended to be compatible with Python 2.0 (Python 2.1 is
>   required for the test suite because of inspect.py).  Optik is not in
>   Python yet, and never will be for Python 2.2 or earlier.  I also
>   include a pre-2.2 version of difflib.py in the test suite because we
>   use its functionality.  Such inclusions are quite common I think.

Gotcha.  Comment withdrawn in its entirety.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

On Tue, 25 Jun 2002 10:44, David Goodger wrote:
> Aahz wrote:
> > Do you have a mechanism for generating index entries?
>
> I doubt Oliver's DocBook writer does, because reStructuredText and the
> rest of DocBook doesn't, yet.  You'll be needing these?
>
> The reStructuredText mechanism most suited to index entries would be
> "interpreted text".  From the markup spec:
>
>     Text enclosed by single backquote characters is interpreted::
>
>         This is `interpreted text`.

An alternative to the "role" concept, where all text marked up in `backquotes` 
is assigned a particular role, would be to extend the parser to handle `index 
me`i or similar, to make the index tagging explicit.

Just thinking out loud here...


   Richard

Aahz wrote:
> Hrm.  Optik is going into Python 2.3 as the new command-line parser.
> Shouldn't we just use Python's CVS?  (With the obvious corollary that
> any patches go back to the Python CVS instead of doc-utils.)

I've been working on the Optik project; all patches have been fed back
to the codebase, as will any future changes.  Oliver's patch fixes an
omission in the Docutils version only; the official Optik doesn't need
it.

There are several reasons I added optik.py to Docutils:

- By including optik.py, there's no extra download & install required.

- Docutils is intended to be compatible with Python 2.0 (Python 2.1 is
  required for the test suite because of inspect.py).  Optik is not in
  Python yet, and never will be for Python 2.2 or earlier.  I also
  include a pre-2.2 version of difflib.py in the test suite because we
  use its functionality.  Such inclusions are quite common I think.

- Docutils is already using the code I added to Optik, but Greg Ward
  (Optik's architect) hasn't had time to check it in to the official
  CVS.  I decided not to wait.

- Optik itself is currently a package, but it's slated to become a
  single module in the stdlib.  The docutils/optik.py module is my
  idea of how to organize it, and took part in discussions with Greg.
  Again, I was impatient.

  But not to worry.  From the comment at the top of optik.py: "Once
  Optik itself becomes a single module, Docutils will include the
  official module and kill off this temporary fork."

Once Optik (in whatever form, known by whatever name) is in Python's
stdlib, I'll add some code to Docutils' setup.py to leave it out if
detected.

-- 
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/

Aahz wrote:
> Do you have a mechanism for generating index entries?

I doubt Oliver's DocBook writer does, because reStructuredText and the
rest of DocBook doesn't, yet.  You'll be needing these?

The reStructuredText mechanism most suited to index entries would be
"interpreted text".  From the markup spec:

    Text enclosed by single backquote characters is interpreted::

        This is `interpreted text`.

    Interpreted text is text that is meant to be related, indexed,
    linked, summarized, or otherwise processed, but the text itself is
    left alone.  The text is "tagged" directly, in-place.  The
    semantics of interpreted text are domain-dependent.  It can be
    used as implicit or explicit descriptive markup (such as for
    program identifiers, as in the `Python Source Reader`_), for
    cross-reference interpretation (such as index entries), or for
    other applications where context can be inferred.

    The role of the interpreted text determines how the text is
    interpreted.  It is normally inferred implicitly.  The role of the
    interpreted text may also be indicated explicitly, using a role
    marker, either as a prefix or as a suffix to the interpreted text,
    depending on which reads better::

        :role:`interpreted text`

        `interpreted text`:role:

    Roles are simply extensions of the available inline constructs; to
    emphasis_, `strong emphasis`_, `inline literals`_, and `hyperlink
    references`_, we can add "index entry", "acronym", "class", "red",
    "blinking" or anything else we want.

    A role marker consists of a colon, the role name, and another
    colon.  A role name is a single word consisting of alphanumerics
    plus internal hypens, underscores, and periods; no whitespace or
    other characters are allowed.

From the Docutils notes:

    Alan Jaffray suggested (and I agree) that it would be sensible to:

    - have a directive to specify a default role for interpreted text
    - allow the reST processor to take an argument for the default role
    - issue a warning when processing documents with no default role
      which contain interpreted text with no explicitly specified role

For your purposes, setting a default role of "index" may do the trick.
If all of your index entries will appear verbatim in the text, this
should be sufficient.  If not (e.g., if you want "Van Rossum, Guido"
in the index but "Guido van Rossum" in the text), we'll have to figure
out a supplemental mechanism, perhaps using substitutions.

Either way, no support for any of this is implemented yet.  Can you
spell out your requirements?

-- 
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, Jun 23, 2002, Ollie Rutherfurd wrote:
> 
> After a pretty hectic end of the week and weekend, I just got back 
> to doing a little work on the DocBook writer I've been working on.  
> I'm hoping to check-in a somewhat functional version into the 
> sandbox shortly, but when I went to use the new "choice" type
> from "optik.py" I found a little bug.
> 
> Below is a patch for this.

Hrm.  Optik is going into Python 2.3 as the new command-line parser.
Shouldn't we just use Python's CVS?  (With the obvious corollary that
any patches go back to the Python CVS instead of doc-utils.)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

On Mon, Jun 24, 2002, Ollie Rutherfurd wrote:
> 
> The main missing pieces are footnotes, citations, and all bibliography
> elements. Some footnode elements are generated, but don't work
> at all. Aside from that, most pieces should be in place -- whether
> they work correctly is another issue ;-).

Do you have a mechanism for generating index entries?
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/