[Doc-SIG] backslashing
Edward D. Loper
edloper@gradient.cis.upenn.edu
Wed, 11 Apr 2001 19:04:26 EDT
> Any inline regexps will be complicated, no matter what escaping
> mechanism you choose. It's the nature of the beast!
If you used E<lt> and E<gt> or E{lb} and E{rb} or something like that,
then regexps would generally look how they're supposed to (at least
when you print them).
> Inline literals would be better::
>
> The regexp `r"\."` matches a literal period.
But then we have to say that inline literals can't ever contain "'"..
which in my mind is no better than saying that you can't backslash
'{' and '}'.
> I haven't spoken up about this, but: ugh! Somewhat dismayed to see
> the X<> type of construct being taken seriously. It works fine for
> POD: long live POD! Want to use it in docstrings? Implement a POD
> parser for HappyDoc or pydoc. In my estimation, readability is the
> most important criterion; X<> fails miserably.
I asked about this before, and didn't get any negative feedback.
Basically, I'd be happy to not use X<...> markup (or X{..} markup) if
we restrict ourselves to only using:
- either 'literal' or `literal`
- maybe *single* *word* *emph*
- no nesting
Guido has objected to `literal` (which doesn't mean we can't do it, of
course). I think that if the reason we're rejecting X{} or X<> is
because it's "not readable," then there's no reason to accept #code#,
which to me is signifigantly less intuitive than C{code}.
> Recently, I've come to the conclusion that requiring a blank line
> before the start of a list is reasonable and correct, even if we
> don't require blank lines between items. Minimizing ambiguity trumps
> minimizing vertical space.
That would make things easier. But we would also have to require that
sublists are surrounded by blank lines. So instead of::
text
- item1
- subitem 1.1
- subitem 1.2
- item2
- item3
text
We would have::
text
- item1
- subitem 1.1
- subitem 1.2
- item2
- item3
text
Any objections to that? The way my markup language currently works,
we don't have to worry about how to detect when a new list item
starts, because list item contents are required to be indented::
- this is a valid list
item.
- This is not a valid
list item.
-Edward