[Doc-SIG] Hello and feedback

[David Priest]

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 &amp;-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&ndash;\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