[Doc-SIG] RE: reStructuredText

[David Goodger]

on 2001-07-18 9:12 PM, Garth T Kidd (garth@deadlybloodyserious.com) wrote:
> It just occurred to me:
> 
> The lowest friction implementation for a Wiki using reStructuredText is
> to implicitly assume that if a _ target doesn't exist in the current
> document, the link must be intended to refer to another document in the
> system.

The "create a new page if the link doesn't exist" mechanism is an
application issue. If a Wiki uses reStructuredText, it's free to do whatever
it likes. The markup doesn't need to know about it though.

> This would still require people to add the _ suffix for anything they
> want linked, but would eliminate the concerns about non-punctuation
> markup

Wiki ImplicitLinksUsingCamelCase are so ambiguous, they must cause lots of
problems. Like a discussion about "Old MacDonald"... Better to have some
unambiguous syntax saying "this is a link".

> and ways of forcing links to pages whose names aren't that
> WikiLike. I'm concerned, however, that people could end up with some
> truly wierd names::
...
> On the other hand, the system can always refuse to create pages of such names.

Again, an application issue.

> This brings me back to the potential need for a "short form" of the link
> syntax. Consider an attempt to have the above example link to a more
> reasonably named FnarzleDocs::
> 
> See `the rest of my documentation on the fnarzle system`_ for more
> details.
> 
> .. _`the rest of my documentation on the fnarzle system`: FnarzleDocs_

Multiply-indirect hyperlinks? Interesting idea. I don't know if it's worth
the trouble though.

Of course, Wiki users could just write::

    See the rest of my documentation on the fnarzle system
    (FnarzleDocs_) for more details.

> I think my users would prefer::
> 
> See `the rest of my documentation on the fnarzle system`:FnarzleDocs
> for more details.
> 
> BTW, I just found the section in the spec that permits::
>
> I think you should `download Python 2.1`:http://www.python.org/2.1/
> before you touch that ugly Perl code.

Which section of which spec? That looks like StructuredText hyperlink
markup, which I rejected for reStructuredText. I chose a modified Setext
indirect hyperlink style because of WYSIWYG. In the processed page, we don't
want the URL of the hyperlink to be visible. In the raw text, having the URL
immediately after the link text is distracting; it breaks the flow of the
text.

> Miscellaneous concerns:
> 
> - embedding directives like includes or macro calls mid-paragraph.

Could be done with interpreted text. But is it really necessary? Could you
provide some examples?

> - being able to recognise indented paragraphs solely by their first
> line, so that people can lazily just keep typing (like I'm doing now)
> without having to manually terminate lines and indent the next one. The
> behaviour is arguably implied by the specification ("This is a paragraph
> continuation, not a sublist"), but I'd love explicit confirmation
> because it might be argued that an outdent implicitly terminates the
> previous paragraph but an indent doesn't. Needless to say, I'd argue
> against that.

Unfortunately, that syntax is ambiguous if blank lines between list items
are optional, which reStructuredText allows. You can have one or the other,
not both. For example, if a list item's paragraph containing text "x = x -
1" were to word wrap badly, you'd end up with::

    - This is list item 1. Here's a formula: "x = x
    - 1".
    - Here's list item 2. Sure looks like item 3 though.

And that's too dangerous to allow. I agree that the lazy typing style is
convenient, but reStructuredText has avoid ambiguity as much as possible.

The Doc-SIG historical record shows that allowing intra-list-item blank
lines to be optional is more in demand. Opinions or counter-arguments
anyone?

> - underlined style headings; I *really* like MoinMoin's use of a number
> of equals signs on each side of a paragraph: if the number of equals
> signs is the same, the paragraph is a heading of ident level equal to
> the number of equals signs.

It's a workable alternate syntax.

> - I would hope that the reStructuredText parser is smart enough to
> figure out that the example text above is part of the <li> above?

Once you indent the list item's paragraph, and further indent the example
text, yes. :-)

> - What's wrong with an automatically wrapped comment block like the
> following? ::
> 
> .. This would be a comment block except
> this line hasn't been indented
>    because some client re-wrapped the
> lines. Damn!

Same as list items: ambiguity.

> - I'm trying to figure out how to refer to a target within another
> document:

There's HTML's fragment syntax, which could be used::

    .. _link to 'refname' within another file: fileURL#refname

> - I hope the parser is able to deal with paragraphs inconveniently
> wrapped in the middle of some emphasis::
> 
> This is *emphasised
> text* with an
> inconvenient wrap
> point.

Yes, already implemented.

> ... otherwise I'd need an option to require delimiting the text::

Ugh. Thank goodness, unnecessary.

> ... which matches nicely with the link syntax, at least if you don't
> need to embold the link, which sometimes I do::
> 
>   This is an `emphasized link`*_ with an...

reStructuredText doesn't support nested inline markup. That way lies
madness...

> That's not as ugly as I thought it would be.

Ugly enough ;-)

> - Leading and trailing whitespace should be trimmed from inline
> literals so that someone can do this::
> 
>   Find the `` `interpreted text` `` in this paragraph!

Inline markup start-strings must be followed by non-whitespace, end-strings
preceeded by non-whitespace, so that won't work. What will work, though,
is::

     Find the ```interpreted text``` in this paragraph!

or::

     Find the \`interpreted text` in this paragraph!

> If I should just make up my own mind on each and submit a diff per to be
> discussed|debated|mangled, someone let me know, okay? :)

Please discuss reStructuredText syntax issues here. If you'd like to start a
variant syntax, or a completely unrelated syntax, you're free to do so;
indeed I'd encourage it. You're welcome to use my codebase. Please make it
compatible with the DPS (whose API is in its infancy, a blank slate).

As I mentioned in private email, I'll be posting version 0.3 of both
reStructuredText and the DPS by the end of the weekend. Look for: several
thousand lines of code; most constructs implemented; warning & error
generation; many unittests (over 90 & counting, just for the parser); DOM
generation; oodles of fun for all ages.

-- 
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