Re: including generated documentation with source

On Tue, 12 Feb 2013, Dag-Erling Sm?rgrav wrote:

> "Jeremy C. Reed" <[email protected]> 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.
_______________________________________________
[email protected] mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-chat
To unsubscribe, send any mail to "[email protected]"