[Doc-SIG] Hello and feedback

[David Priest]

I'm feeling that I've perhaps pissed in someone's cornflakes, but I'm going 
to respond anyways.  If I've offended, I apologize profusely:
no offense was intended.
 On Sat, 15 Mar 2003 01:01:25 -0500, David Goodger <goodger@python.org> 
wrote:

> XML character entities (&xNNNN;) are unknown to reStructuredText and
> are the wrong way to do it.  Docutils is correct in substituting
> "&amp;" in HTML output for every "&" in the input file (how could it
> tell the difference between *using* an XML character entity and just
> *talking* about one?).
 The charent pattern can be detected easily enough, and the "&" encoding
skipped for those entities.  If you want to talk about an entity directly, 
literalizing it would do the trick.  In all other cases the
ampersand can be safely encoded.
 But the substitution table using "proper" characters is good enough, 
although I'm not entirely sure that all backends output will be able to 
deal with two-byte Unicode.

> There's absolutely no need for any regex substitution here.  That's
> exactly what the Writers are for.  The ":gui:`File`" input may become
> "<gui>File</gui>" in the internal document tree.  The HTML Writer
> would write it with bold (or, better yet, with <span class="gui">,
> made bold by the stylesheet).  The DocBook Writer would write it with
> <guilabel>.
 The problem with implementing it as a Writer is that Writers don't
travel with the source text files.  If I send you a ReST file with :gui: 
roles in it, what's your DocUtils installation going to do with it?

> There has been some discussion about parameterizing the interpreted
> text system somehow, to avoid proliferation of element types (gui,
> keypress, etc.).  No decision or action yet.
  If "parameterizing the interpreted text system" means that simple role
substitutions -- the kind that can be handled by regex -- can be placed 
within the source text files, great!  It makes the source text more
portable.
  If the role can't be handled by a regex, then of course it's going to
require a Writer.  (Although... if one could embed a Python script...
but, no.  That's verging on silly.)
 And if this email has been scrunched into a blob, I apologize.  I assure
you that there are blank lines scattered throughout it.  I've tossed
extra space characters in them, too.  But my email client may still
toss them aside.  I have submitted a bug report.