[Doc-SIG] epydoc 1.0 release

[Edward Loper]

> 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