Skip to Content.
Sympa Menu

freetds - docs form and location

freetds AT lists.ibiblio.org

Subject: FreeTDS Development Group

List archive

Chronological Thread  
  • From: "James K. Lowden" <jklowden AT schemamania.org>
  • To: TDS Development Group <freetds AT franklin.metalab.unc.edu>
  • Subject: docs form and location
  • Date: Sun, 16 Jun 2002 16:03:38 -0400


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



  • docs form and location, James K. Lowden, 06/16/2002

Archive powered by MHonArc 2.6.24.

Top of Page