Formats and re-use of other tools/docs

[Erik Walthinsen <omega@omegacs.net>]

> 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 ) 
I would have to agree.  HTML is enough of a standard format, and is capable 
of enough stuff, that we can safely stick with that.  IMO it prints reasonably 
(one reason why people are so into DocBook), is hypertext, everyone knows 
it or can learn quickly, etc.

Besides, arma of all people should know what HTML can do... he wrote the 
sdoc parser, which is used to mark up the SEUL website.  The source 
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.

> 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 know gnome has these...are theirs any good?
> > http://www.gnome.org/devel/sg/
> Have a look and tell us. 
You should know by now that we hardly have time to breath... :)  Any time 
we ask if someone else could look or do, it's a plea for relief more than 
anything.... ;-)

> /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/ ?

> 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. 
Are you talking about the help application, or the documentation?  
Inevitably, both will collide, and there's nothing we can do about it but 
try to make the best decision we can.

One thing that I think many people forget too often is that most of what's
out there isn't necessarily targeted towards the end user.  For instance,
neither LinuxConf nor COAS are set up to ask the user "do you want a local
newsfeed" and "which groups".  They're designed for those who know what's 
under the hood (for the most part) but either don't want to or don't have 
the time to deal with the details.

My guess would be that the KDE help system and docs follow that to some 
degree (though obviously they have some form of end-user goal)...  Without 
more information, I can't commit to anything.

Anyway... my point is that we may have to make some decisions as to what to 
include and not to include in SEUL based not on how complete or well-done 
something is, but how apropos it is to our target audience.

TTYL,
    Omega


     Erik Walthinsen <omega@seul.org> - SEUL Project system architect
        __
       /  \                SEUL: Simple End-User Linux -
      |    | M E G A            Creating a Linux distribution
      _\  /_                         for the home or office user