[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:: ! 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 É and é 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