[Doc-SIG] Re: reStructuredText
David Goodger
dgoodger@bigfoot.com
Mon, 09 Jul 2001 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