[Doc-SIG] using the same delimiter on the left and right..

[Goodger, David]

Ken Manheimer wrote:
> David Goodger wrote:
> 
> > Trying to enforce rules on people for a supposedly 
> 'transparent' markup
> > system like ST is ass-backwards. The markup must abide by 
> common usage, not
> > the other way around. That's the strongest argument against using
> > single-quotes for inline literals I know of. We can use 
> `backticks` or
> > `symmetric quotes' or <gasp!> *both*! (I see problems with 
> symmetric, like:
> > "string assignment: `s = 'this is a string''". 
> Single-quotes are just too
> > common in all contexts, IMHO.)
> 
> Obviously, many of us don't think it's ass backwards.  Structured text
> uses conventions that take their markup significance from their
> common usage.  Many of us find this to be a big benefit in practice.
> A common use for single quotes is to signify literals - they're used
> for contractions and other things, but by paying attention to context
> there's no conflict.
> 
> I would note that you use structured text conventions, like
> *asterisks* for emphasis, in the very text where you dismiss
> structured text's approach.

Bad choice of words; I didn't mean to dismiss ST at all. I'm a strong
proponent; I love the concepts of ST, and Setext before it. It just feels
*right* (especially in comparison to POD or JavaDoc); but I think it's got
some warts (who doesn't? :-) and could use improvement (who can't? :-). It's
sometimes hard to be objective, to see the warts, if they're too close,
especially if you're used to them and love them dearly.

Nobody's attacking Zope's ST; at least, *I'm* not. It works for Zope; long
live Zope & ST! I apologize for any perceived attack.

My goal is simple: I want to write easily extractable docstrings in my
Python programs, and quick & dirty web pages and docs in general,
convertable to something useful. Because of its warts, ST (Classic or Next
Generation) hasn't been accepted for this purpose by myself or the Python
community.

Specifically, I was referring to the conflicting use of ' -- ' in ST for
definition/descriptive lists versus its common use in texts as em-dashes.
Somebody mentioned forcing people to use it for DL's only. If it's in common
use for one thing, I can't see using it for another. I think that
single-quotes for literals is another conflict, a wart that, if removed, may
bring us one step closer to my stated goal. Adding an escape mechanism is a
must, but you may see it as adding a wart. One man's wart is another man's
beauty mark.

/DG