[Doc-SIG] Hello and feedback
David Priest
priest@sfu.ca
Fri, 14 Mar 2003 15:36:15 -0800
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