Re: Formats and re-use of other tools/docs

[Roger Dingledine <arma@mit.edu>]

In message <199804190642.XAA07878@sigma.omegacs.net>, omega@omegacs.net writes:
>documents are painfully simple... one pass through sdoc and you get any 
>kind of cool looking doc you can code the perl for.  In fact, while I 
>haven't tried, it, you could theoretically produce almost anything from 
>sdoc, if you code the handlers right.  That means if all else fails, we can 
>convert HTML into something else.

This is what I meant -- let's go ahead and convert things into the other
formats now, on the assumption that some people will prefer one format,
some another, etc. Surely there's an html2man out there? It's not a high
priority though, I'll grant you. (See below about Gnome's DocBook structure.)

>> We shouldn't bother with maintaining man pages.  While some are a little
>> outdated, none are so bad as to not be useful for the app.
>> As to info ... No offense but I have never actually used these except
>> in desperate emergency.  The information was as cryptic as any man page 
>> so it didn't fit my needs.
>For our target user, yes.  For others, not necessarily the case.  
>Basically, we shouldn't put any extraordinary effort into man pages, but 
>when we write a program, it should have a man page.  We can always generate 
>it from the 'official' documentation, using sdoc or whatever else.

I didn't mean maintaining man pages, so much as noting which man pages
are missing *entirely*, and filling them in. Hopefully somebody has already
been keeping track of that somewhere. I wish all these "list of linux links"
sites actually worked.

>> > I know gnome has these...are theirs any good?
>> > http://www.gnome.org/devel/sg/
>> Have a look and tell us. 

User interfaces aren't my thing. I use vi, for god's sake. ;) In any
case, I took a look at it, and it looked like it codified some pretty
good common-sense's about gui's. From a small sample of screenshots of
gnome apps on their software map, a good number of them are not following
all the gnome guidelines. But most of those apps are in alpha or beta; perhaps
they intend to conform to the gnome ui standards as a "final tweak".

It also turns out that gnome uses a markup setup called 'DocBook' (tutorial
available at http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html).
Basically, it looks like an attempt at marking up html enough that it can
do something useful for more situations than just web pages, similar to sdoc.
I wonder if they're actually using it. (My poking at the gnome site did not
turn up anything about actually writing documentation. Which I would
believe...)

>> /usr/doc/help dose not exist.  but /usr/doc is a crowded directory in
>> which "help" could easily get lost.
>Would it make sense then to move all the package-specific help into a 
>subdirectory, say /usr/doc/packages/ ?

Crowded doesn't seem as relevant to me -- if we have a user going into
/usr/doc and doing an ls, we've already messed up somewhere, right?
Hopefully we'll have something somewhere organizing the presentation of
all these various documents, which makes where they are actually stored
in the directory hierarchy less important.

>> All those plus the gropes working on important apps.  I.E. SEUL help
>> should not be a replacement for the already massive KDE help.  Just
>> an addition. 
>Are you talking about the help application, or the documentation?  
>Inevitably, both will collide, and there's nothing we can do about it but 
>try to make the best decision we can.
[snip]
>Anyway... my point is that we may have to make some decisions as to what to 
>include and not to include in SEUL based not on how complete or well-done 
>something is, but how apropos it is to our target audience.

While that's true, a sub-goal can be to make as many other projects and
applications include our ideas and work as possible. This will further the
goal of making linux more end-user friendly. If we can adopt some standards
similar or identical to the standards that other major projects (like gnome
or kde or redhat or whatever) use, that will be much easier. (The other side
of that coin is that we can use *their* work much more easily.)

--Roger