Hi, all. I'm a technical writer who has been looking for a way to allow my subject-matter experts (programmers and engineers) to contribute to the maintenance of documentation, freeing me to get on with writing some much- needed new documentation. These people are not willing to learn a new software tool. They'd really like to use Word, but that's simply a big, big mistake: it will crap out on us as the documents get big and complex. I'd like to use DocBook XML, but it's unweildly for them and difficult to read without an XML-aware editor -- which would be a new software tool, which they don't want. So it looks like structured text is the solution: as long as I can transform it into DocBook XML, so that I can import it into my layout app and generate a PDF in under five minutes, things will be cool. And as I improve the XSL, I can even bypass the layout app, which means they can publish straight to PDF themselves, no worries. After chasing a few false leads, ReST appears to be the best candidate for accomplishing what I want. The ASCIIDoc project was *almost* there, but lacked a few key pieces. I have spent the past couple days transforming a moderately complicated document to ReST. The transformation is not complete: there are some missing pieces. You can download the zipfile from http://www.sfu.ca/~priest/VRAS.zip The two key missing puzzle-pieces are as follows: - I am unable to insert Unicode character entities into the text. Substitutions are the answer, so I've created a |subst| replace:&xAAA; table, as included in the zipfile. Alas, the DocUtils insist on <PRE>coding or &-substituting the replacement text. If this is fixed (perhaps by a "replaceliteral:" role), DocUtils will be much improved. - I am unable to use regex macros to manipulate the input text. There are two uses for this: 1) To do standardized typographic replacement on naive-user's text. For instance -- in print documentation -- the long dash, as I just used it, should be replaced using an em-dash surrounded by thin spaces. This is a detail that no naive user should have to worry about: that's my job as technical writer. Likewise, certain measurement units require marking-up: I'd like my naive users to write "36.8degrees" and get 36.8[degree sign], or 10m3 and get 10m[superscripted 3]. .. use the formal en-dash with number ranges .. regex:: ([0-9]+?)-([0-9]+?) = \1–\2 Note that the parenthesis in the prefix part of the equation indicate grouping: the regex says to look for one-or-more numbers (and remember them), a hyphen, and one-or-more numbers (and remember them, too). The postfix equation says to insert the first memorized group, an en-dash, and the second memorized group. If a file has a regex definition, it will be run before all other macros and substitutions, mais non? I think so. 2) To supplement the :role:` ` coding. In particular, the software documentation needs to indicate GUI elements. In HTML they would be rendered bold; in DocBook as <guilabel>. It would be appropriate for the source text to read " open the :gui:`File` menu and choose :gui:`Save` ". A :role: transformer program would be overkill for this. All that is needed is the ability to run an appropriate regex against the enclosed text, appropriate being defined by the destination file type. .. role:: html <B>:gui:</B> .. role:: docbook <guilabel>:gui:</guilabel> Note that DocUtils will need substitute the content of the interpreted text where the role label is shown. Thus :gui:`File` becomes <B>File</B> and <guilabel>File</guilabel>, respectively. DocUtils will have to match its destination file type to the appropriate role substitution, of course. I think the ideas I have presented here will allow ReST to be used far more broadly. It is currently at the very cusp of being used for general technical writing. I believe that as long as ReST can be converted to DocBook XML, it stands a very good chance of becoming a "front-end" replacement for DocBook XML. Not that I'm knocking DocBook, but it is often overkill for most purposes. I am now subscribed to the doc-sig list, daily digest format. Please take a look at my sample file, http://www.sfu.ca/~priest/VRAS.zip , for a demonstration of ReSTs application in moderately complex print documentation for a hardware and software product. (there are some other gaps, but I see that they've been addressed by others. Figure/Table autonumbering and referencing are a biggie. I see that someone has suggested a naming convention to allow referencing, and the autonumbering shouldn't be any problem at all, so I anticipate a solution is on the way.) Thanks for reading, david