[work] Re: [Doc-SIG] Hello and feedback

[David Goodger]

[David Goodger]
>>      The '&' entity is used by HTML and XML to
>>      represent the '&' character.
>> 
>> I shouldn't have to use inline literals here.

[David Priest]
> Personal preference, I suppose.

It's practicality.  In many of my documents, I (and, I imagine, other
authors) write *about* <tags> and &entities; and other uses of these
characters.  Some people write "&c" instead of "etc".  Should the parser
generate an error for this?  I think not.

>> Why are you unable to insert the actual, encoded characters into
>> the text?  What *are* you able to insert?  What encoding are your
>> files using?  What platform (OS, editor, etc.)?  It could be that
>> you *can* insert real characters but don't know it.
> 
> *I* am able to insert the actual encoded characters into the text. There's
> no guarantee, however, that *others* are going to be able to see them.
> These docs are going to be edited on Windows, Mac, Linux, and BeOS boxes
> using whatever flavour of editor the end-user wants to use.

So ASCII is your lowest common denominator?  I sympathize, but maintain that
Docutils doesn't need a character entity subsystem.  Your idea of a
substitution table file will work fine, and since *you* have control of it,
encoding it as UTF-8 shouldn't be a problem (and you can treat everything
else as UTF-8 since it's a strict superset of 7-bit ASCII).  Just change the
table from this form::

    .. exclamation point:
    .. |excl| replace:: &#x0021;

to this form::

    .. exclamation point:
    .. |excl| replace:: !

I.e., use the concrete characters.

I just realized there's a problem: reStructuredText is case-insensitive, so
&Eacute; and &eacute; will clobber each other.  You'll either have to come
up with a different name scheme, or perhaps the parser can be changed to be
case-sensitive-but-forgiving for substitution names.  I think that change is
feasible, but I haven't thought through the consequences.

> I hope I'm coming at this from a different angle than the rest of you,
> because that way I'll be able to contribute another view on how ReST can be
> used to best effect.

Your contributions are most welcome.  Just don't expect every idea to be
adopted. :-)

> I think one of the best ways to encourage wide adoptation is to make it as
> easy as possible for functionality to be implemented within the source text
> files. 

I'm very leery of making reStructuredText into a programming language or
meta-markup language.  Simplicity is one of its strengths, and the existing
extension mechanisms (directives, interpreted text roles, substitutions) are
already more than complex enough.

> It's going to be next to impossible to keep up with everyone's
> various ideas for roles.

Perhaps.  But I'm not going to implement a solution until it's the *right*
solution.  Regexes ain't it, sorry :-).

> The more that a role's functionality can be put
> into a text sourcefile, the easier it is to share one's documents.

I'd rather put the functionality into Docutils itself.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv