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

[Steven Jenkins]

This is a multi-part message in MIME format.
--------------010400010005040902090105
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Oops, sent privately to Ken by mistake.

Steve

--------------010400010005040902090105
Content-Type: message/rfc822;
 name="Re: SPAM-LOW: Re: SPAM-LOW: RE: [OpenAFS] Documetation for asetkey and aklog"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="Re: SPAM-LOW: Re: SPAM-LOW: RE: [OpenAFS] Documetation for asetkey and aklog"

Message-ID: <42CEE7C4.7080700@ieee.org>
Date: Fri, 08 Jul 2005 13:53:24 -0700
From: Steven Jenkins <steven.jenkins@ieee.org>
User-Agent: Mozilla Thunderbird 0.9 (Windows/20041103)
X-Accept-Language: en-us, en
MIME-Version: 1.0
To: Ken Hornstein <kenh@cmf.nrl.navy.mil>
Subject: Re: SPAM-LOW: Re: SPAM-LOW: RE: [OpenAFS] Documetation for asetkey
 and aklog
References: <200507081853.j68Ir2q9016341@ginger.cmf.nrl.navy.mil>
In-Reply-To: <200507081853.j68Ir2q9016341@ginger.cmf.nrl.navy.mil>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

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


--------------010400010005040902090105--