[Doc-SIG] Re: Comments on DPS and reStructuredText

[David Goodger]

Thanks, Tony, great input!

I guess now it's *my* turn to be overwhelmed. ;-) I'll be replying to
your messages over the next few days.

BTW, the two SourceForge projects now have CVS and mailing lists set up.
Please subscribe to any or all of docstring-develop, docstring-checkins (CVS
messages), structuredtext-develop, and structuredtext-checkins. DPS mailing
lists are at:

    http://sourceforge.net/mail/?group_id=26626

reStructuredText mailing lists are at:

    http://sourceforge.net/mail/?group_id=7050

On "reST": interesting acronym. Pronounced how? As in, "to rest"? Or
as "ree-ess-tee"? I've been using RST.

on 2001-08-03 6:01 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote:
> I've attempted to write the comments up *using* reST, but I'm fairly
> sure I'll have done it wrong because I was typing rather than
> looking up reST syntax.

Mostly spot-on. Apart from the corrections below, I noticed you
sometimes added an underscore when you meant to use interpreted text.
Underscore means hyperlink.

> I *shall* be working on a "cheat sheet" or quick reference,
> for my own use if no-one else's - a *very* early version is at
> http://homepage.ntlworld.com/tibsnjoan/reST/quick_reST.html,

Very useful. Some corrections:

- "Inline Markup": ``footnote references: [5]_`` is given, but in
  footnote 4, "rep77" is the footnote label.

- "dot, dot, space":

  1. Body row 2: the internal hyperlink is wrong::

         .. _example: The ``example_`` above points to
            this target.

     It should be::

         .. _example:

         The ``example_`` above points to this target.

     Anything after the ":" on the hyperlink target is interpreted as
     a URI: "Internal hyperlink targets have empty link blocks; they
     point to the next element. Indirect hyperlink targets have an
     absolute or relative URI in their link blocks."

  2. Your footnote 6 says::

         [6] It is not clear to me whether the output formatter should
         "fold in" indirect hyperlinks in this fashion, or whether it
         should treat them just the same as internal crossreferences,
         or whether both behaviours should be choosable with a command
         line switch...

     After reading your article "Would you trust something you had to
     pay for?", both versions, I see what you mean. For "fold in", you
     mean: the normal way HTML hyperlinks work, with arbitrary text
     (typically underlined and in a different colour) fronting for the
     URI, which is not visible in the text. For the alternate, you
     mean: automatically generated footnote references and footnotes,
     the latter containing the URI as a standalone hyperlink, visible
     in the text. Let's call this alterate form, "callout".

     I see how the "callout" form would be useful. How to represent
     hyperlinks is indeed an issue for the output formatter. For HTML,
     the default would be to fold them in. Perhaps just clarify that
     the representation *is* a matter for the output formatter, and
     you're just displaying one possible representation. That applies
     to the whole page though.

     Good article, BTW.

- "Lists":

  1. Bullet lists: Item 3's "typical result" is missing some text
     (full stop after "+" to "whitespace."). It should be rendered as
     a single paragraph.

  2. Enumerated lists: "List items should be sequentially numbered,
     but need not start at 1." It may not be a good idea to start at
     anything other than 1/A/I: the output format may not support an
     arbitrary start value. I plan to generate a level-0 warning if a
     list starts with ordinal-1.

  3. Definition lists: The spec (and the parser) require blank lines
     between definition list items. This requirement could be relaxed,
     as it has been for other lists. What do you think?

> Sorry for the vast delay in producing any input - hope this helps...

Helps enormously -- thanks a lot. The more brains this stuff gets
filtered through, the better the end result will be.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net