FreeTDS Development Group

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

All, 

The existence of the freebcp man page leads me to other musings.  

I think there should be other man pages.  In particular, freetds.conf
should have one.  The UG is doing the job for now, but when you want to
tweak your configuration, you shouldn't have to hunt down a user guide;
that's what a reference manual is for.  Basically, anything you could do
with FreeTDS from the keyboard should have one.  

I've thought about man pages for the APIs, and decided there's a better
way.  I know its ambitious, but down the pike we should document the whole
API with Doxygen.  

This line of thought leads to questions about where to keep things and
where to put them. I'd like to (re)visit these questions:

1.      Where should man pages go, and in what format, in CVS?  
2.      Where should man pages be installed?  
3.      What documentation, and in what form, should be included in the 
release
tarball?
4.      Where should the UG, FAQ, and doxygen output be installed?  

I of course have some suggestions.

1.      Man pages should go in doc/.  They should be in the form of mdoc
macros, until and unless we find a suitable docbook->man converter.  I
think there is one, but I haven't pursued it.  

2.      They should be installed in /usr/local/man/man[1..9] (by default).  

3.      The source form of the UG is SGML/Docbook, but that's not useful to
anyone not writing documentation.  The release tarballs should include all
the documentation in  human-readable form.  That form should be HTML.  The
HTML docs and/or manpages should include links to other forms of
documentation (ps, pdf) available on the website.  

4.      The docs should be installed in:
        /usr/local/doc/freetds/userguide/
        /usr/local/doc/freetds/faq.html
        /usr/local/doc/freetds/reference/<api>
(that last one being dependent on what Doxygen wants to do.)

Comments naturally welcome.  

--jkl