Re: Thoughts.

[Kevin Forge <forgeltd@usa.net>]

Roger Dingledine wrote:
> 
> Can we write them in some metaformat that can generate formats like
> html, man, info, etc? That way we just run a little help-file-creator
> and it generates myhelp.html, myhelp.man, myhelp.info, so users can
> use whatever form they like best. (Or rather, whatever reader they
> like best, since all formats will be supported.) This makes document
> generation more complicated since we have to support more features
> (the union of man/info/html is more complex than any one of them
> alone), but it may well be worth it.
>
This would complicate maters both for the user ( when the conversion is 
done improperly or the metafile format is screwed up somehow by the 
author ),  and for authors.  Best to stick with a proven workhorse,
that we can all use.  HTML.  Even people who don't understand most HTML 
tags ( like me ) it is still useable since HTML can be generated with
simple wisiwig programs ( even Netscape and a slew of Word processors ) 
>
> What's up with the linux doc project? Do they keep lists of which
> man pages ought to be worked on, or are they not working much on man
> pages these days?
>
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.
>
> I can't help here either. But here goes. The way I see it, there are
> two ways to do this. First, we can provide some sort of library that
> they link against, that provides the graphical parts of the help, and
> reads the seul help repositories. That gets complicated quickly. The
> second option is much more straightforward: come up with a list of
> guidelines that they should follow, ideally with plenty of graphical
> examples. I know gnome has these...are theirs any good?
> http://www.gnome.org/devel/sg/
>
Have a look and tell us. 
>
> These are hardly valid reasons, though. I bet /usr/info/help and
> /usr/doc/help are pretty empty, too. Do we want to consider a /usr/help?
> It's heavily nonstandard.
>
No, no, no.  I mean to facilitate the new user.  I remember one of my 
major problems when trying to read the files in /usr/doc was that 
there was so much stuff in that directory that I had a hard time 
figuring out which sub directory to go into.  /usr/doc/help dose not
exist.  but /usr/doc is a crowded directory in which "help" could 
easily get lost.
>
> What groups out there for this sort of thing? Linux doc project and
> gnome come to mind. Somebody needs to find a more comprehensive list.
> This is one of the biggest things I've been trying to get done lately
> (cf my post 
>
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. 
>
> This is more complicated than "see #2". (It should be "see #3 and #4"
> as well. ;)
>
No read my response to question number 2 and you will see that 
task-help is what I think needs to be written. 
>
> We seem to have quite a few KDE advocates around here. Does anybody
> know a Gnome advocate, so we can throw questions at him? Or is Gnome
> too young to have many real advocates?
> 
Real programers don't actually advocate stuff.  Right now only real
programers can get GNOME working so ... 

> --Roger

-- 
Through the the Firewall, out the ruter, down the T1, bounced from
satellite.  ... Nothing but net.