[Doc-SIG] Re: reStructuredText

2001年7月09日 21:43:41 -0400

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