FreeTDS Development Group

[Brian Bruns <camber AT ais.org>]

On Sat, 19 May 2001, James K. Lowden wrote:

> 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.
> 
Thanks, I'll use the one on the site to update to update CVS, and then
integrate my changes.  I'll keep a version on freetds.org so I can diff
any changes from you back in.  The userguide.sgml will have a 'R0_52' tag
(for the 0.52 release of course) like all the other files in CVS and can
be extracted based on that to get a point in time copy.

Speaking of the 0.52 release, I've been considering adding a 
"Case Studies" area on the homepage.  This way potential users could get a
feel for what FreeTDS is and some of the ways it could be
used.  Explaining what FreeTDS is to people often ends up sounding rather
esoteric.  This might provide more concrete examples.

Of course, company and individuals names can be changed to protect the
innocent if necessary.  (Management sometimes get touchy about these
things...so we might say "a major e-commerce site did so and so" instead
of naming names).  

So if anyone thinks this is a good idea send a paragraph or three about
what you do and why, and I'll put it together.

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

I think we should generate the html and roll that out with the tarball.  I
don't see any real value to putting in the makefile.

> 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 man pages would be neat for documentation on API calls (dblib,
ctlib, but especially libtds which has no other source of documentation).
And for the file formats of course.