[Doc-SIG] RE: reStructuredText

[David Goodger]

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