Date: Fri, 22 Feb 2013 08:25:18 -0600 (CST) From: "Jeremy C. Reed" <reed@reedmedia.net> To: chat@freebsd.org Subject: Re: including generated documentation with source Message-ID: <alpine.NEB.2.02.1302220807360.343@t1.m.reedmedia.net> In-Reply-To: <867gmdhnu9.fsf@ds4.des.no> References: <alpine.NEB.2.02.1302111751360.27181@t1.m.reedmedia.net> <867gmdhnu9.fsf@ds4.des.no>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, 12 Feb 2013, Dag-Erling Sm?rgrav wrote: > "Jeremy C. Reed" <reed@reedmedia.net> writes: > > I help maintain documentation (man pages, guides in html, pdf, and plain > > text, and api/developer docs in html). The original source of the docs > > is in docbook or doxygen. I'd prefer not to include the generated docs > > in the source tree (git repo) because slight differences in the > > documentation tool chains on each developer's system. But I also don't > > want the end-user to have to install all the many software dependencies > > for providing the documentation end results so I include them in my > > "make dist" tarballs. (I am using autoconf/automake framework.) > > Look at the OpenPAM source code, particularly > > http://www.openpam.org/browser/openpam/trunk/doc/man/Makefile.am > > Almost all of the man pages are generated at compile time. The use of > the "dist" prefix in Makefile.am ensures that they are included in the > distribution, even though they are not in the repo. Thank you for the examples. This is similar to what I already do, but has one advantage that I don't currently have: its source includes the generation tool (misc/gendoc.pl). What happens if a make clean is done and no perl is available to regenerate? I didn't try, but I think this is the same problem I currently have: we don't want to force our users to install xsltproc, docbook stylesheets or rest of our documentation toolchain. I received another suggestion about adding a doc/ directory that has the generated files. The generated docs would be in the tarball but not in the git repo. If the docs toolchain is installed and a configure switch is set, then the docs are generated and put into (or replaced in) the doc directory. A "distclean" wouldn't remove those files, an "install" would install from there. I think I have seen example of this before, but don't recall where. I may try this idea.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.NEB.2.02.1302220807360.343>