Re: Thoughts.

[Roger Dingledine <arma@mit.edu>]

In message <35396AE3.A2088B3C@usa.net>, forgeltd@usa.net writes:
>Two Ducks wrote:
>> 
>> Several people have expressed the idea that the focus of SEUL
>> help be all systems (or possibly all) instead of targetting only
>> that which SEUL eventually settles on. i.e. not only gnome
>> (if that is what is chosen) but also other desktop managers.
>> 
>> If this is what we are going to do, there are several things that
>> should therefore be discussed (maybe?):
>> 
>> 1. Help file format
>
>HTML is the only viable choice for default format.  ALL SEUL help
>documents should be written in HTML.

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.

>> 2. Help types (HOWTOs, MAN, task-help...)
>
>All of the above.  However SEUL is more about filing in the gaps
>and integrating what has already been done so task-help is where
>we should concentrate.  

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?

>BTW : The trick to task help is to make general assumptions at the 
>beginning then work within those assumptions.  I have found it simpler 
>for users to adjust say instructions designed for Slackware on iNTEL
>to RedHat on alpha.  than to fit generalized instructions into what
>they have.
>
>> 3. Help file layout (for similar look and feel though written by many).
>
>Can't help there.

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/

>> 4. Help system structure (where do we put the help files?)
>
>/usr/man/help
>Why there ?  Well I don't think it's such a good idea to stick 
>something else in the /usr directory ( That's kinda like all the 
>little DOS programs that need to be in root ).

Makes sense. I think this question is directly related to the
core/layers proposal that Omega was writing for dev-distrib. Omega?

>so why not under /usr/info or /usr/doc ?  Well both of those produce 
>listings that go off the screen when you type ls

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.

>> 5. Communication with other groups.
>
>Absolutely essential.  And we must do it without getting into any 
>more holy wars.

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 http://www.seul.org/archives/seul/leaders/Mar-1998/msg00074.html)

>> 6. What needs writing
>
>see #2

This is more complicated than "see #2". (It should be "see #3 and #4"
as well. ;)

>> Anything else? Any comments? 
>
>Well KDE BETA 4 is coming soon.  On RedHat 5 / x86 It's fairly
>stable.

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?

--Roger