FreeTDS Development Group

["James K. Lowden" <jklowden AT speakeasy.org>]

Brian,

Starting with version .52, I think it would be a good idea to version
label the UG in CVS, so that anyone who gets the source code gets the
(best effort) updated docs, and so it's possible to document features as
they accumulate (as we "make the pie higher" as my president recently
put it).  The html version on the website should reflect the latest
release, or if you like, both the release and cvs versions in separate
directories.

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

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 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.
Man pages get high marks for being indexed.

I have a sense this little essay is going to get me involved in automake
& Co.  Thanks a bunch, James Cameron.

I don't want to make work (make; make install; make work) for anyone, of
course.  I'm curious what people think, what they would use.  As long as
I'm going about making (as it were) the world a better place, I might as
well know what "better" means to its inhabitants.

--jkl