SPAM-LOW: RE: [OpenAFS] Documetation for asetkey and aklog

[Ken Hornstein]

>I've done some work on using DocBook to make both web documents and 
>high-quality PDFs. The approach I used was to put LaTeX hints into the 
>DocBook elements using the 'role' attribute. Role is ignored by most 
>downstream processing, but you can easily write a DocBook-to-LaTeX 
>converter that uses these hints to invoke the right high-level LaTeX 
>constructs.
>
>For example, the closest thing in DocBook to a LaTeX theorem is a 
><formalpara>. If you mark up your document with <formalpara 
>role='theorem'>, the HTML converter does all it can, but the LaTeX 
>converter makes it a theorem.

This illustrates _exactly_ my feelings about documentation formats.
Basically, I don't give a shit about 90% of the worthless crap that
these systems do (yeah, I'm going to be writing a WHOLE LOT of theorems
in the Kerberos FAQ); what I want is a simple layout that looks
reasonable in text and in HTML, and I want to learn the minimum
necessary to accomplish that.  I have my HTML reference, and I remember
enough of the HTML tags that doing the FAQ in HTML isn't too bad.  I
don't even have enough time to write the information that goes in the
FAQ (you know, the USEFUL stuff); there's NO WAY I'm going to learn
DocBook, POD, Latex, XML, TeXinfo, or whatever the latest exciting
new documentation format is when HTML is sufficient for my needs.
What you describe above is even worse; I'd have to learn both DocBook
_and_ LaTeX to make sense of that, and that's simply Not Going To
Happen.

Now, I told Ted that I didn't have a problem with him converting the
FAQ into LaTeX, and that's true ... but at that point I feel it no
longer becomes my FAQ, it becomes his.  If I ever get around to updating
it (which may or may not happen, I have no idea right now), I won't
be updating the LaTeX version, I'll be updating my version.  If Ted
wants to take it over, and his version becomes the one that people
update, then hey, that's fine with me; I'll retire my version and
point people to it.

--Ken