[Doc-SIG] Re: reStructuredText

[David Goodger]

Hi Simon,

on 2001-07-09 5:08 PM, Simon Hefti (hefti@netcetera.ch) wrote:
> I have been reading your reStructuredText Specs and I like it a lot.

Thank you. I've copied my response to doc-sig; I hope you don't mind.

> I have a few comments:
> 
> 1) what is the reason to choose ".." as comment tag ?
> I should think that "#" would be more intuitive for most of us.

It comes from Setext. I find ".." less obtrusive than "#". Plus, it's not
just a comment marker; it handles hyperlinks, footnotes, and directives too.

> Also: is it "^..", or can comments start everywhere in the line ?

They start at the left edge of the current indentation. Indent further and
they start a block quote. They can end an indent too (correctly, of course).

> 2) If I understood this correctly, your `some text here`_ syntax
> implies that each "key" must be unique. That may not be true
> for section titles.

>From the working reStructuredText.txt (not yet on the web site), end of
"Section Structure":

    Each section title automatically generates a hyperlink target pointing
    to the section. The text of the hyperlink target is the same as that
    of the section title. See `Implicit Hyperlink Targets`_ for a complete
    description.

And further on::

    Implicit Hyperlink Targets
    ``````````````````````````
    
    Implicit hyperlink targets are generated by section titles, and may
    also be generated by extension constructs. Implicit hyperlink targets
    behave identically to explicit `hyperlink targets`_.
    
    Problems of ambiguity due to conflicting duplicate implicit and
    explicit hyperlink names are avoided because the reStructuredText
    parser follows these rules:
    
    1. Explicit hyperlink targets override any implicit targets having the
       same hyperlink name. The implicit hyperlink targets are removed,
       and level-0 system warnings are inserted.
    
    2. If two or more sections have the same title (such as "Introduction"
       subsections of a rigidly-structured document), there will be
       duplicate implicit target hyperlink names. Solution: all duplicate
       hyperlink targets are removed, and level-0 system warnings
       inserted.
    
    3. If there are duplicate explicit hyperlink target names, all
       duplicates are removed, and level-1 system warnings inserted.
    
    System warnings are inserted where target links have been removed. See
    'Error Handling' in `PEP 258`_.
    
    The parser must return a set of *unique* hyperlink targets. The
    calling software (such as the `Python Docstring Processing System`_)
    can warn of unresolvable links, giving reasons for the warnings.

> 3) how do you handle line breaks in link defitions ?

Link names are whitespace-normalized. Multiple spaces or newlines are
converted to a single space. I'll spell this out better in the spec.

I'm also toying with the idea of removing leading numbers from implicit link
names, so a section titled "3. Conclusion" can be referred to by
"Conclusion_" (i.e., without the "3.").

> Is `this is a very very very very very very very very
> very very long tag`_ a valid tag ?

Yes.

> Section title ?

The idea of multi-line section titles has come up. I've yet to be convinced
they're necessary (80 characters ought to be enough). I'm currently working
on a parser, which recognizes single-line titles; multi-line titles would be
harder to parse (both by software and by the human eye/brain).

Arguments pro/con anybody?

> 4) I guess that an "include" statement could be very
> helpful, e.g. for books, bibliography, commonly used definitions and
> so on. If you plan to delegate it to the directives, I think
> it should be a required one.

Easy enough to implement.

> 5) More directives I would whish to see:
> - TOC

Implementable.

> - glossary (in addition to footnotes)

Please elaborate. Why not just a section called "Glossary" containing a
definition list?

> 6) I like your table tag. Still, I think in some cases
> one could appreciate an additional, simplified syntax like::
> 
> +----------
> | key | value
> +----------
> | foo | bar
> | bar | long line follows here ...............................
> +----------
> 
> From my experience, most tables are very simple: one key, a few
> values.

If you're saying, let the right-hand border be optional, it's possible.
Opinions?

> 7) Also from experience, somtimes one whishes to force a line
> or page break (like the <br> tag).

Use literal blocks, or implement a directive. No obvious syntax for <br>
comes to mind. I'd be reluctant to add it anyhow (purely presentational).
This isn't XML, after all; we have to live with some limitations.

> 8) why should URLs be case insentive ? Servlet Engines
> typically are not, as well as querystrings.

URLs aren't specified as case-insensitive. Internal/indirect hyperlinks are.
All would be case-preserving regardless. Link_ and link_ and LinK_ would all
refer to the same element. The case and spacing of the processed, visible
text wouldn't be altered.

> 9) a typo: "hhere"

Wwhere? :-)

Thank you for your feedback.

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