Return-Path: Delivered-To: apmail-db-derby-dev-archive@www.apache.org Received: (qmail 4479 invoked from network); 3 Mar 2005 00:45:32 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur-2.apache.org with SMTP; 3 Mar 2005 00:45:32 -0000 Received: (qmail 5242 invoked by uid 500); 3 Mar 2005 00:45:31 -0000 Delivered-To: apmail-db-derby-dev-archive@db.apache.org Received: (qmail 5210 invoked by uid 500); 3 Mar 2005 00:45:31 -0000 Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: List-Id: Reply-To: "Derby Development" Delivered-To: mailing list derby-dev@db.apache.org Received: (qmail 5196 invoked by uid 99); 3 Mar 2005 00:45:31 -0000 X-ASF-Spam-Status: No, hits=-0.0 required=10.0 tests=SPF_HELO_PASS,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (hermes.apache.org: domain of jta@bristowhill.com designates 66.75.162.134 as permitted sender) Received: from ms-smtp-02-qfe0.socal.rr.com (HELO ms-smtp-02-eri0.socal.rr.com) (66.75.162.134) by apache.org (qpsmtpd/0.28) with ESMTP; Wed, 02 Mar 2005 16:45:29 -0800 Received: from [192.168.15.53] (cpe-204-210-23-212.san.res.rr.com [204.210.23.212]) by ms-smtp-02-eri0.socal.rr.com (8.12.10/8.12.7) with ESMTP id j230jPX7029986 for ; Wed, 2 Mar 2005 16:45:25 -0800 (PST) Message-ID: <42265E25.4090707@bristowhill.com> Date: Wed, 02 Mar 2005 16:45:25 -0800 From: "Jean T. Anderson" User-Agent: Mozilla Thunderbird 0.9 (X11/20041127) X-Accept-Language: en-us, en MIME-Version: 1.0 To: Derby Development Subject: [doc] What should the DITA source produce and how should it be produced? Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Virus-Scanned: Symantec AntiVirus Scan Engine X-Virus-Checked: Checked X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N I'm starting a new topic for questions raised on the thread "[doc] Where should the DITA source files be checked in?" -- for the start of that thread, see http://mail-archives.eu.apache.org/mod_mbox/db-derby-dev/200503.mbox/%3c42261727.90909@bristowhill.com%3e Andrew McIntyre asked: > This brings up several other question: should we have a copy of the built documentation checked in with the source for developer reference or only keep a copy in derby/site? It seems sensible to keep a copy of the build doc with the source it goes with, but would you just keep the built doc for the Developer's Guide? > Is there a convenient way for the source to live in derby/code/{branch} and also be built by the forrest from derby/site? We can specify non-default file locations in the forrest configuration files; however, it has been excrutiating to build all the manuals with each web site update. I strongly urge not using forrest to build the manuals. Instead build the docs separately, then check the built doc into the forrest source. The navigation that forrest adds to the built manual pages isn't always useful nor desirable. See the original discussions at http://mail-archives.eu.apache.org/mod_mbox/db-derby-dev/200410.mbox/threads.html and also in DERBY-79 at http://issues.apache.org/jira/browse/DERBY-79 > Will we keep versions of the docs on the site for the trunk and the branches if they diverge significantly? good question. > If not, what version do we keep up, latest development docs or latest stable docs? good question. > Won't this setup still require regenerating HTML/PDFs each build or is there a way to have forrest only update them if the source is newer than the output? No; we could include the built docs as a "raw" product. Discussion about xsl by Jeff Levitt and Scott Hutinger are in http://mail-archives.eu.apache.org/mod_mbox/db-derby-dev/200503.mbox/%3c42262C07.5080108@wiu.edu%3e . -jean