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

[Kevin Forge <forgeltd@usa.net>]

Roger Dingledine wrote:
> 
> 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.)
>
If the conversion is not too painful, go right ahead ( from what I am 
reading it could be automated for at least the properly formatted docs
..
Yes ? )
>
> >> 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.
>
Ahh... That is useful and relatively painless.  Yes we are obligated to 
write man pages for our apps ( at the very least the text mode ones ).
We don't want to offend vi users after all :)
A listing of orphaned man pages would be of immense value since a
seasoned user
can write a man page for his favorite app in <1 hour.
>
> >> /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.
> 
And if something is wrong to force him in there he is desperate and 
must not be aggravated further.  trust me on this.  I 1st saw Linux in 
1996.  It was the 1st *nix system I ever used ( I once did an SCO 
install, but not so much as booted the system after ).  typing ls in a
directory with 1.8 zillion files and wondering if what you are looking
for 
was there.  With cases sensitive filenames it gets real easy to forget.
-- 
Through the the Firewall, out the ruter, down the T1, bounced from
satellite.  ... Nothing but net.