<<< Date Index >>>     <<< Thread Index >>>

Re: docs (was "Re: How to change From: and other headers according to language")



On Fri, Dec 05, 2003 at 12:01:49PM -0500, Allister MacLeod wrote:
> On Fri, Dec 05, 2003 at 10:01:56AM -0500, David Yitzchak Cohen wrote:
> > On Fri, Dec 05, 2003 at 09:34:02AM -0500, David T-G wrote:

> It is with great trepidation that I enter into this thread, so
> warm to the touch, but here goes...

LOL ;-)

> > > 1) When you failed to find reply-hook in the stable docs on the web site,
> > > why didn't you try looking locally at your unstable package?
> > My unstable package doesn't have human-readable docs, so I have an easy
> > answer to that one ;-)
> 
> I humbly beg to differ.  The documentation source code, as far as I
> can tell, contains a pair of SGML files (manual.head.sgml and
> manual.tail.sgml).  Now, while SGML does indeed contain some markup
> which may not be immediately intelligible to the layman, the bulk of
> it is still eminently human-readable.

Eh, I'm not much of a fan of sifting through a cat of two DocBook/SGML
fragments in w3m.  I'd much rather have real HTML that w3m can browse
usefully, rather than having to search all over for anything that might
be interesting :-(

Having said that, I've now retracted my request for CVS docs to be put
online, instead concentrating the fight purely on the released versions.

> For that matter, the source code is human-readable also.  Even though
> program code must be machine-readable and correct for the compiler to
> accept it, a large purpose of good programming languages is for humans
> to communicate about machine instructions.  Otherwise, we'd all
> program our computers with fancy macro assemblers.

Um, yeah, you can glean your how-the-heck-do-I-use-this-damn-thing
docs from the source (and wipe out your almost-done doctoral thesis
because you made a slightly wrong assumption while speedreading a
straightforward-looking piece of code that could win an IOCCC award for
the manner in which something is done (the product of a dev who wanted
the code to look like it does what it does, even if it ddoes it in a
different way than the "standard" one)), but I'd rather have the dev
write me a few pages about how to use the darn thing himself: he knows
his own code better than I know his code.

> Finally, why don't you have a functioning sgml2txt and/or sgml2html?

Simple: I _do_ have an old version of the sgmltools, but Mutt doesn't
like it at all.

> On my Debian testing system, it was easy enough to 'apt-get install \
> linuxdoc-tools'.  There also exists some source code at 
> http://www.sgmltools.org/ (maybe the 1.0 series is more likely to
> provide sgml2txt.)

Yeah, it's relatively easy to get a new version, etc. - another reason
why I'm dropping my request for CVS docs online.

 - Dave

-- 
Uncle Cosmo, why do they call this a word processor?
It's simple, Skyler.  You've seen what food processors do to food, right?

Please visit this link:
http://rotter.net/israel

Attachment: pgpgJYsU451wC.pgp
Description: PGP signature