Re: [E-devel] Documenting e

[Drew S. <dr...@mu...>]

On Sun, 2002-03-10 at 05:30, Christian Kreibich wrote:
> Drew Smith wrote:
> > 
> > Oh ya, I have to agree this is the way to handle it all, but I can see
> > "issues" with the different dtd's and how they are implemented on
> > different systems (which is where I was yesterday).
> 
> These should just be issues of people who normally don't deal with sgml
> and dtds :) 

And what a royal pain in the a$$ those issues can be. :)

> > I wonder if it would
> > be worth the thought to consider putting something together that "we"
> > know will work
> 
> HAHAHA -- never ever :) This stuff *does* work. Docbook is about as
> standardized as it gets. We may have to agree on the sgml or xml
> version, but that's it. The makefile probably needs a bit of work to
> better find things on more systems, but we're *not* going to hack
> together our own documentation system, okay :o)
 
If and *only* if it's configured just so, it works ok, sorta. Here's my
case: The other day I wasted away hours goofing around using any
documentation, hacking this, that and the other thing to get it working
without any manual intervention, and you know what? I finally got so
pi$$ed that I ended up dropping the Slack 8 sgml package in and it still
barks and grumbles when I do a make html-docs on some packages. Now
maybe it's me and I really am stupid, but I don't think so. Yesterday
when I built a fresh cvs, I only saw one package even attempt to enable
the html-docs when built and even that used the included default of
/usr/share/blah/blah which ended up failing miserably. Slacks default
location of the sgml tools is in /opt/sgml.... Hence my thinking that
perhaps, just perhaps, somebody could do up an "e" specific sgml package
and then when somebody says "but I can't build the documentation on my
system" all we have to say is "if your not using the e-sgml-tools
package, all questions to /dev/null please". We've got issues :)

> > and can be carried over to the desktop? (no flames
> > please, just thinking out loud :)
> 
> Not sure what you mean by "carrying over to the desktop"?

That's alright, I'm not either :) Just thinking that having some sort of
user docs (html?) available to the desktop, installed in the build by
default, and ending up wherever, with a fancy little help button
installed somewhere in the default menus or iconbar might be kinda nice
for the end users who actually do read docs (there are a few, albeit
few). Like I said, just kicking around the ball. 

Drew
--
you can lead 'em to the docs, but you can't make 'em read