From owner-freebsd-chat@FreeBSD.ORG Tue Feb 12 00:05:50 2013 Return-Path: Delivered-To: chat@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 0022DBB4 for ; Tue, 12 Feb 2013 00:05:49 +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 D7C5A84B for ; Tue, 12 Feb 2013 00:05:49 +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 1U53Nd-0003Xg-5I for chat@freebsd.org; Mon, 11 Feb 2013 19:05:49 -0500 Received: from reed@reedmedia.net by reedmedia.net with local (mailout 0.17) id 4654-1360627549; Mon, 11 Feb 2013 18:05:50 -0600 Date: Mon, 11 Feb 2013 18:05:49 -0600 (CST) From: "Jeremy C. Reed" X-X-Sender: reed@t1.m.reedmedia.net To: chat@freebsd.org Subject: including generated documentation with source Message-ID: 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: Tue, 12 Feb 2013 00:05:50 -0000 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.) Currently I use a ./configure switch --enable-generate-docs. If set, configure will check for some dependencies and the generated Makefiles will have targets for generating the docs. But if not set, the make targets will generate dummy doc files. The dummy doc files idea I got from the pango project, but I think now it is a poor idea. Maybe I should just force the additional dependencies for anyone building my software, or maybe force this for a "make dist" only. Or maybe I should go back to just keeping the generated docs in the git repo -- I could require (or automate this) that checkins only come from a dedicated documentation build system so that it is consistent. Does anyone have any advice or pointers to source code examples of how I can best handle providing generated docs with my tarball releases? (I'd prefer to not change from docbook to simpler format.) From owner-freebsd-chat@FreeBSD.ORG Tue Feb 12 09:40:31 2013 Return-Path: Delivered-To: chat@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 8EEA0FC2 for ; Tue, 12 Feb 2013 09:40:31 +0000 (UTC) (envelope-from des@des.no) Received: from smtp.des.no (smtp.des.no [194.63.250.102]) by mx1.freebsd.org (Postfix) with ESMTP id 54F0D9B for ; Tue, 12 Feb 2013 09:40:30 +0000 (UTC) Received: from ds4.des.no (smtp.des.no [194.63.250.102]) by smtp-int.des.no (Postfix) with ESMTP id 5653E658D; Tue, 12 Feb 2013 09:40:30 +0000 (UTC) Received: by ds4.des.no (Postfix, from userid 1001) id 27D71A277; Tue, 12 Feb 2013 10:40:30 +0100 (CET) From: =?utf-8?Q?Dag-Erling_Sm=C3=B8rgrav?= To: "Jeremy C. Reed" Subject: Re: including generated documentation with source References: Date: Tue, 12 Feb 2013 10:40:30 +0100 In-Reply-To: (Jeremy C. Reed's message of "Mon, 11 Feb 2013 18:05:49 -0600 (CST)") Message-ID: <867gmdhnu9.fsf@ds4.des.no> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.2 (berkeley-unix) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Cc: chat@freebsd.org 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: Tue, 12 Feb 2013 09:40:31 -0000 "Jeremy C. Reed" writes: > I help maintain documentation (man pages, guides in html, pdf, and plain= =20 > text, and api/developer docs in html). The original source of the docs=20 > is in docbook or doxygen. I'd prefer not to include the generated docs=20 > in the source tree (git repo) because slight differences in the=20 > documentation tool chains on each developer's system. But I also don't=20 > want the end-user to have to install all the many software dependencies=20 > for providing the documentation end results so I include them in my=20 > "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. DES --=20 Dag-Erling Sm=C3=B8rgrav - des@des.no