From owner-freebsd-chat@FreeBSD.ORG Fri Feb 22 14:50:27 2013 Return-Path: Delivered-To: chat@freebsd.org Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 3A1B12D0 for ; Fri, 22 Feb 2013 14:50:27 +0000 (UTC) (envelope-from reed@reedmedia.net) Received: from c-0500.emailmediator.com (c-0500.emailmediator.com [64.85.162.118]) by mx1.freebsd.org (Postfix) with ESMTP id 1A7973F5 for ; Fri, 22 Feb 2013 14:50:26 +0000 (UTC) Received: from pool-173-74-104-132.dllstx.fios.verizon.net ([173.74.104.132] helo=reedmedia.net) by c-0500.emailmediator.com with esmtpa (Exim 4.69) (envelope-from ) id 1U8tYs-00029s-Ta for chat@freebsd.org; Fri, 22 Feb 2013 09:25:19 -0500 Received: from reed@reedmedia.net by reedmedia.net with local (mailout 0.17) id 22627-1361543118; Fri, 22 Feb 2013 08:25:19 -0600 Date: Fri, 22 Feb 2013 08:25:18 -0600 (CST) From: "Jeremy C. Reed" X-X-Sender: reed@t1.m.reedmedia.net To: chat@freebsd.org Subject: Re: including generated documentation with source In-Reply-To: <867gmdhnu9.fsf@ds4.des.no> Message-ID: References: <867gmdhnu9.fsf@ds4.des.no> User-Agent: Alpine 2.02 (NEB 1266 2009-07-14) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-BeenThere: freebsd-chat@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Non technical items related to the community List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 22 Feb 2013 14:50:27 -0000 On Tue, 12 Feb 2013, Dag-Erling Sm?rgrav wrote: > "Jeremy C. Reed" 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.