[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Formats and re-use of other tools/docs
> 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.
HTML allows a lot of scope for the author to make an enormous mess. Take a
look at the typical doc produced by Netscape composer if you don't believe
me (-:
If you want plain HTML , you'll need a parser, and the parser needs to get
rid of any "rubbish". I don't know how sdoc stands up. But this parser
would not be able to assume that the author would write "good" code.
It will be pretty hard to enforce a consistent look in your help system if
you allow everyone to go off and do their own thing in HTML without
attempting to enforce some kind of look/layout
> 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
yes, so this is the kind of thing that should be looked at. Something
"lower level" than html, as I mentioned in my previous post.
HTML gives the author too much freedom, even for the SEUL website, or any
large website for that matter.
(incidently, I also use my own parsers for my web documents)
The tags at most should include something like <STRONG> , <EM>, <H1> -
<H3> , <A HREF= >, <A NAME= > , <BLOCKQUOTE>, <P> anything too fancy
should be avoided. The first thing I'd have the parser do is swallow "bad"
tags.
Again, even keeping it this simple, I suspect that maintaining a
consistent look might not be that easy.
-- Donovan
_____________________________________________________
Donovan Rebbechi, Lord of the Elves,
Dept of Mathematics, Rutgers University Newark
Visit my webpage: http://pegasus.rutgers.edu/~elflord
*****************************************************
On Sat, 18 Apr 1998, Erik Walthinsen 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
> > 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.
_____________________________________________________
Donovan Rebbechi, Lord of the Elves,
Dept of Mathematics, Rutgers University Newark
Visit my webpage: http://pegasus.rutgers.edu/~elflord
*****************************************************
On Sat, 18 Apr 1998, Erik Walthinsen 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
> > 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
>
>