[Doc-SIG] RE: reStructuredText
David Goodger
dgoodger@bigfoot.com
Fri, 20 Jul 2001 18:29:12 -0400
on 2001-07-20 2:17 AM, Garth T Kidd (garth@deadlybloodyserious.com) wrote:
> If reading my email in reStructuredText 0.2.2 is driving anyone nuts,
> please let me know.
Looks OK to me! :-) New in the spec and parser (which will be posted to the
web site this weekend) is implicit hyperlink targets in titles, so you could
use titles instead of ".. _internal hyperlink targets:".
> Multiply-indirect hyperlinks? Interesting idea. I don't know
> if it's worth the trouble though.
>
> Collapsing multiply indirect links seems clean and trivial. Why not? :)
But is the gain worth the added complexity?
> That said, it's not necessarily *important*, so feel free to leave it
> in the pile of features labelled "Garth can code these if he wants
> them so bloody badly."
Consider it so left. And it's good to hear the Queen's English.
[Summary of Garth's coding attitude:]
> * If it's easier to change the code's behaviour than change the
> users' behaviour, change the code.
>
> * Writing dirty, ugly code is harder than changing user behaviour.
So write clean code! :>
> * If it's not obvious whether the code is going to be clean or not,
> I'll find out by trying to write it.
Sounds reasonable.
> Howabout we nail down how to hand a block of text to a directive, and
> then leave messy stuff like doing something unusual mid-paragraph to
> application-specific directives. If it turns out to be mind-blowingly
> popular, it can be factored in later.
Yes. The parser currently *parses* directives just fine, but doesn't
actually *do* anything with them yet. I'll have to code up a directive or
two to see what they'll need. Any suggestions?
> I keep forgetting the extra indents. Just to confirm::
>
> - list item
>
> new paragraph in list item::
>
> literal block in list item
>
> .. outdented comment to force the end of the literal block
>
> block quote in list item
>
> block quote outside of list item (oops!)
>
> - another list item
Correct on all counts.
> * If I accidentally indent a bullet list, does that become a bullet
> list inside a block quote? ::
...
> I suspect the answer is: yes.
Your suspicions are well-founded. (Yes.)
> * Does the specification implicitly or explicitly support the use of
> an outdented comment to force the end of an indented block, as
> above?
>
> I suspect the behaviour isn't yet defined.
Right again. The spec doesn't explicitly or implicitly say anything. The
parser *does* support such (ab)use of an unindented comment. I'll modify the
spec.
Thanks for the 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