Documentation considerations

James Cameron cameron at stl.dec.com
Mon May 21 02:06:17 EDT 2001


"James K. Lowden" wrote:
> 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?

configure should sense OpenJade is not present and decline to prepare
the HTML format.  Those who grab the source from CVS should be expected
to prepare a good build environment.  Have a file in CVS that lists the
development tools required; e.g. gcc, autoconf, automake, OpenJade.

> 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 the HTML should be included in .tar.gz distribution but not in
CVS.  This creates a dependency for the person doing the .tar.gz but
avoids having non-source files in CVS.  Some projects refuse to have a
configure in CVS, since it is generated from configure.in.  This means
the "make dist" rule needs to be adjusted to run autoconf, perhaps.

> If userguide.sgml were in the source tree, people could send patches. 

If it weren't there they couldn't send patches.

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

;-)

-- 
James Cameron                                      (cameron at stl.dec.com)

"Did I ask for fries?"



More information about the FreeTDS mailing list