Re: Contacting other groups.

[Roger Dingledine <arma@mit.edu>]

In message <98042322062705.00482@duck1.foul>, twoducks@globalserve.net writes:
>It seems that it might be a good idea for seul-dev-help to
>contact other groups who may be interested in the attempt
>that we will be making to improve documentation for the
>end user.
>
>I would guess that we do not want to duplicate any efforts
>already occuring, so it would probably be best to contact
>these other groups before any really serious effort is expended.
>
>Some of the groups I thought should be contacted would be:
>
>KDE
>GNOME
>LDP (Linux Documentation Project)
>
>At the very least I thought it would be useful to inform them about
>the existence of this group and some of the actual concrete things
>we would be attempting to provide (task-help, a help system). I assume
>that if we were to work on documentation such as man pages (eew),
>HOWTOs and the like we would do that through LDP.
>
>Any comments? Are there any other groups that should be included
>and is there anything else that we might be doing that they would be
>interested with?
>
>Ken

<ramble>
http://www.on-line.de/~lutz.behnke/docfs/docfs.html describes a project
called DocFS -- Unified Documentation Storage and Retrieval. Apparently
it involves a kernel module in user-space to let you access files in
/usr/doc and /usr/man as if they were ordinary directories, but it
generates the requested file on the fly, from the original (sgml) copy.
There are some big problems with this (somebody want to argue either way?)
but the section on "Reverse Documentation Tools"
(http://www.on-line.de/~lutz.behnke/docfs/node9.html) indicates programs
called info2www, texi2html, and "RosettaMan".

http://star.pst.qub.ac.uk/rman.html shows a man page for this RosettaMan
program. Apparently it's a very versatile and powerful program designed
to convert man pages into more useful things, like sgml, html, latex,
roff, TkMan, Ensemble, ascii, etc. (Somebody should start cataloguing
all the different formats documentation is coming in these days, come
to think of it. But that's a different thread.)
RosettaMan provides an email address of the author: phelps@CS.Berkeley.EDU
Everything I found was dated at most 1994, though. I have no idea if this
program is actually widespread; one readme indicated that tkman uses it,
which would imply it's pretty widespread but lowlevel.
</ramble>

So I guess there are two ways to improve documentation here:
a) come up with ways of converting between the formatting schemes. Looks
like that's covered pretty well already.
b) actually write it. Given a, what format we use is not crucial. (Though
I agree that SGML is a good default.)

I grabbed the 1.18 man pages from the LDP (awfully slow .nl site actually
had them, so I put them at ftp://ftp.seul.org/pub/man-pages-1.18.tar.gz once
I was done) and checked them out. I get the feeling the LDP is moving away
from man pages (who isn't, these days). I also suspect that they don't have
a list of unwritten man pages -- every man page they think they want, they've
written. So we should decide if there are any that we want that they don't
realize they want, and write them or propose them.

Anyway, I get the distinct feeling I'm incoherent here, so I'm going to
end this before it becomes more confused.

--Roger