Oops, sent privately to Ken by mistake.
Steve
--- Begin Message ---
Ken Hornstein wrote:
1. My message was information and an offer of help. It wasn't even a
recommendation. If you don't want it, don't take it. You don't need to
unload a bunch of attitude on me.
Sigh. I apologize for that; the whole documentation mess has been something
I wished I could ignore, and the rant really wasn't directed at you; it
was just a general rant.
Thanks for saying so.
2. The theorem example was just that, an example. Would you be less
annoyed if the roles were FAQ-specific stuff like 'question' and
'answer'? With a little work, the subset of DocBook you'd have to know
would be *tiny*, and the subset of LaTeX you'd have to know would be *zero*.
The problem I have is "tiny" is greater than "zero". Even a tiny
amount of time is time I don't have. This is completely aside from the
problem that I don't have DocBook on any of the systems I have here and
I'd have to install it (actually, okay, I was curious and I checked it
out; it's not clear to me from a few minutes of Google exactly _what_
DocBook consists of; is just XML schema? If so, where do I get the
tools to process it? _What_ tools do I need?)
In principle, you don't need anything. The file *you* maintain, could be
as simple as:
Q: Why is AFS better than NFS?
A: Because we say so.
Q: Why should I believe you?
A: Because we run AFS.
I'm neglecting sectioning, etc. That's simple to deail with.
Something like that could be trivially converted to a DocBook instance
in a few lines of scripting. (Maybe someone other than you could write
that.)
It turns out that DocBook already has support for FAQ-like things. The
output would look something like this:
[a few lines of boilerplate header stuff]
...
<qandaset>
<qandaentry>
<question>
Why is AFS better than NFS?
</question>
<answer>
Because we say so.
</answer>
</qandaentry>
<qandaentry>
<question>
Why should I believe you?
</question>
<answer>
Because we run AFS.
</answer>
</qandaentry>
...
</qandaset>
...
(I'm just typing this in off the top of my head.) There's also no reason
you couldn't maintain the file in this format directly. It's not *that*
much uglier than HTML.
To turn that into HTML, you need OpenJade and the DocBook stylesheets.
It's a minor nuisance to get that installed, and that may tilt it for
you. But it's not too bad. In return you get a nice indexed FAQ like
this: http://www.dpawson.co.uk/docbook/reference.html/
Maybe you don't need hardcopy; for a FAQ, you probably don't. But
someone who does could fairly easily translate that using XSLT or a
simple script into LaTeX or whatever.
And while you say that the amount of DocBook that I need to know is
tiny, the real problem is that I have almost no experience with SGML or
XML, and I'd have to learn a bunch of stuff just to be able to GET
anywhere with it; we don't have any of the tools or experience in-house
here, and without that infrastructure I'd have to spend a ton of time
working on it to be able to make any progress with it. Years ago
I had the time to spend a week messing around with a TeX installation
to get it working, but I don't anymore (okay, it may only take a day or
two, but again, don't have the time).
Understood. I'm just pointing out options. On the other hand, if you
take an approach that others see as promising, they may be willing to help.
Steve
--- End Message ---
