Re: Thoughts.

[Donovan Rebbechi <elflord@pegasus.rutgers.edu>]

> Roger Dingledine wrote:
> > 
> This would complicate maters both for the user ( when the conversion is 
> done improperly or the metafile format is screwed up somehow by the 

the conversion will not be done improperly if the conversion package is
well written. 

> 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 

Is there any reason why html can not be converted to the other formats
without data loss ? 

> tags ( like me ) it is still useable since HTML can be generated with
> simple wisiwig programs ( even Netscape and a slew of Word processors ) 

I'm sceptical about the WYSIWYG programs because they create fairly awful
html. The problem is that to write decent html, you have to know what
you're writing, not just how what you're writing renders on your
hardware/software configuration. 

In fact, to enforce consistency in the look of the help system, some kind
of text file "marked up" to the other formats would be better. For example
:
%TaskName 	Copy
%TaskGroup	/KDE/file-management
%Author		Donovan Rebbechi <elflord@pegasus.rutgers.edu>
%Description	A tutorial on copying files in KDE
%Steps
%1	blah blah blah ... 

OK, I ripped this idea off the RPM spec file thing. The point is that html
offers too much scope for the author to put in junk that's not needed or
wanted, and it will take a more restrictive file format to be effective.
This does not require much of the author, since some-one not familiar with
the format can write one of these things by editing another one, since the
format is very canned. 

> > What's up with the linux doc project? 

speaking of which, the "linux user's guide", by Larry Greenfield , is
worth looking at for task help. in my view, the best for beginners out of
the LDP docs.

> > man pages ought to be worked on, 

the tar page is a mess (-: 

> or are they not working much on man
> > pages these days?

I use linux and solaris and the man pages are (by and large) no different.
Most of the man pages seem to come straight from the authors.

> We shouldn't bother with maintaining man pages.  While some are a little

Good point. In instances where the man page is bad (again , tar is my
favourite example), task help is the best remedy, not more man pages.


> 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 found the content OK, but I couldn't use the browser. Info wasn't
available to me until I had KDEhelp! It's ironic to have a help system
with a steep learning curve !

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

Another point with "/usr/doc" is that it's not just for help files, all
the licensing information goes there. THe reason why there's no standard
place to put the "help" system other than info and man, is because there
was no such thing prior to recent linux distributions.

> No read my response to question number 2 and you will see that 
> task-help is what I think needs to be written. 

ABsolutely. task-help is the kind of to-the-point concise and simple
information that SEUL's users need.

-- Donovan