FreeTDS Development Group

["Mark H. Wood" <mwood AT IUPUI.Edu>]

On Sat, 19 May 2001, James K. Lowden wrote:
[snip good advice about versioning documentation]
> Everyone,
>
> This idea leads me to another question: what should the make file do
> vis-a-vis userguide.sgml?  Nothing?  Use OpenJade (creates a dependency)
> and generate the html?  Or, should the html be included in CVS, such
> that "make install" plunks the html in, say, /usr/doc/freetds?  That's
> what a lot of packages do, perl for one.

If 'make' builds the documentation then it should be a *conditional*
dependency, of course:  if 'configure' finds OpenJade then it gets built,
otherwise you just get a message that doc rebuild is being skipped.  The
standard final form of the documentation should ship too, in this case, so
you get it freshly translated if you have the tool and you still get it if
you don't have the tool.

> If userguide.sgml were in the source tree, people could send patches.  I
> don't lie awake at night in fear of a flood of documentation patches,
> but at least it would be possible.  And talk about meta-data, I suppose
> I should write a README-sgml.txt about how to make the html.  Does
> anyone besides me care about such things?

Facilitating improved documentation is good.

> I also wonder vaguely if html is even the One True answer to the form of
> the docs.  I think there are tools out there to convert sgml to pretty
> much anything.  Would info files be better?  (I can't seem to get the
> hang of info).  What about good ol' man pages for some things?  I think
> it would be cool, for some value of "cool", to type "man 5 interfaces"
> or "man tdsver" and get the right answer.  I would create such things,
> if people think it would be helpful.

I think the answer varies, both with individual tastes and with the nature
of the document in question.  'man' is great for small stuff that actually
*fits* in a real page, or two, or perhaps even three; but it is really bad
if the pages are huge.  'man perlfunc' to see what I mean.

'info' is IMHO much better than 'man' for large, complex things with lots
of structure.  Sometimes it makes sense to provide two *separate*
documents:  a man page as a quick reminder about the command itself, and
e.g. a texinfo document which describes the input language at length.  Tcl
and, again, Perl are huge subjects, and I wish they had their online
documentation packed into info, even though I too have trouble getting
used to info's many features.  One problem I see with a lot of texinfo
documents is that they are oriented very strongly toward the book view,
so that the online view gets wordy and hard to follow in that little
window.

For myself, I'll use HTML documentation if nothing else is available, but
I'd prefer not having to crank up a browser and tell it where to find the
"document" in question.  HTML does handle large, structured piles of
information better than *roff, though.

> I like to see documentation on the web.  It helps me decide what to use
> or try, never mind actually using it.  I also like documentation to be
> local, because the installed version may differ from the web-documented
> version.  I like HTML for documentation, because I don't have to learn
> anything to read it.  But HTML docs are a pain because they're hardly
> ever (including the instant case) indexed, and they're hard to search.

I can agree with most of this.  OTOH it should be easy to generate indexed
HTML documents from SGML so long as people will take the trouble to put in
the tags.

> Man pages get high marks for being indexed.

'man bash' provides a counterexample.  It's the granularity thing again.

'man' also gets into trouble as the number of independent developers
increases, due to name collisions.  I have to pick my way through manpages
very carefully these days, to be sure I get the page for the Tcl function
rather than the Perl page or the libc page.  Now, if I could say 'man tcl
foobar' vs. 'man 3 foobar' I would feel more confident.  And I *can* say
'info $PACKAGE $FUNCTION...' so I accept my lack of facility with 'info'
willingly, if not joyfully.

}don flame-retardant suit{
I'm an old VMS lag, and I still admire the way documentation is done in
that environment.  There's generally (1) a hierarchial HELP module which
serves mainly as a memory-jogger for those who have read (2) the Reference
Manual (which rigorously explains every public aspect of the product) and
(3) the User's Guide (which places the product in the context of a
complete system, showing how it links to other facilities and suggesting
good ways to think about it).  I feel that trying to cram these three
functions into a single document is what makes so many Unixland documents
less than satisfactory (to me, anyway).

-- 
Mark H. Wood, Lead System Programmer   mwood AT IUPUI.Edu
Make a good day.