[Doc-SIG] epydoc 1.0 release
Edward Loper
edloper@gradient.cis.upenn.edu
Thu, 26 Sep 2002 21:55:46 -0400
> Edward Loper wrote:
>>I think that reST uses too many different inline markup constructs,
>>that can interact with each other in weird and non-intuitive ways.
David Goodger wrote:
> You're entitled to your opinion, of course. But can you back up this
> claim of "weird and non-intuitive" interaction?
The rules that govern when "*" is markup vs. just an asterisk. For
example, at least according to my understanding of the rules..
- This will not be marked as emph: *un*believable
- This will be marked as emph: *.*
- This will be marked as emph: *.txt and foo.* (even if those two
words are separated by several lines?)
- This will be not be marked as emph: *edloper*@wherever
As for interaction, it's not obvious which markups should nest inside
which other markups.. E.g., is ***this* ok**?
One of the problems with trying to guess what the user is thinking is
that there will always be borderline cases. And as the algorithm that's
doing the guessing gets more complex, the user is less likey to remember
what they need to escape. Also, as the algorithm gets more accurate,
the user is less likely to notice the occasional places where it doesn't
get things right.
I think that *given* the goal of guessing what the user means, you've
done a very admirable job of coming up with high-coverage rules (on the
docutils page you imply 90% mind-reading coverage for non-markup use of
"*".. I'd actually say it's significantly higher). But I actually find
it easier in the long run for me to try to understand the markup, rather
than having the markup trying to understand me. And it's much easier
for me to understand inline markup if it can be explained in 2 or 3
sentences, rather than 10 or 15 paragraphs. :)
> Correction: #this# has no meaning in reStructuredText.
Sorry, I haven't been paying attention to which markup is current (I
remember #this# being proposed at some point). But there are others
like |this|
>>I prefer a single unified inline markup syntax, that almost never
>>requires any escaping.
>
> To each his own. :-) But please note that reStructuredText inline
> markup rarely requires any escaping.
I agree.. The problem I have is that I'm not smart enough to remember
when it *does* require escaping. :)
I think that reST is a pretty good markup language, and I know a lot of
thought has gone into it.. I just don't think it's the markup language
for me. :)
-Edward