On Sat, 15 Mar 2003 10:55:09 -0500, David Goodger <goodger@python.org> wrote:
The '&' entity is used by HTML and XML to represent the '&' character.
I shouldn't have to use inline literals here.
Personal preference, I suppose. I'm already used to "escaping" entities when I'm writing about them directly, so I've no problem with the idea that I can't just write & willy-nilly through my document and expect it to display as such.
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. That's why we have charents in the first place: it lets anyone, using any old editor on any old OS, and print the raw document on any printer -- even an old 1978 daisywheel wordwhacker.
[re: interpreted text roles]
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?
The set of roles built into Docutils itself will grow. If the growth proves to be unlimited or unmanageable, there will have to be an alternative. If those roles are not handled by the default Docutils set, then they can be local to your installation. They wouldn't be portable, true; there's only so far a "standard" can go and we can't please everybody 100%.
I think that ReST has the opportunity to become a dominant markup standard. I've suggested to Opera that they make it their standard for email markup, as HTML email is a sin against humanity. The WikiWorld would do well to standardize on a single markup: it's very confusing to have to remember subtly different markups between various wikis. The ASCIIDoc author used his ST markup to create his website, and I've pointed him toward ReST as a direction for his ST project. And I'm intent on using ReST for my technical documentation. In the technical writing world DocBook is often overkill, especially when attempting collaborative work with naive users. The XML is complex, virtually requiring a DTD-aware editor, and patient study of the spec. ReST is nearly a perfect solution: it's intuitive, simple, and can be written using even a PDA. 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. 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. It's going to be next to impossible to keep up with everyone's various ideas for roles. The more that a role's functionality can be put into a text sourcefile, the easier it is to share one's documents.