[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

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
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.