Return-Path: 
 <dev-return-15484-apmail-forrest-dev-archive=forrest.apache.org@forrest.apache.org>
Delivered-To: apmail-forrest-dev-archive@www.apache.org
Received: (qmail 91306 invoked from network); 31 Mar 2005 21:52:54 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur.apache.org with SMTP; 31 Mar 2005 21:52:54 -0000
Received: (qmail 89444 invoked by uid 500); 31 Mar 2005 21:52:53 -0000
Delivered-To: apmail-forrest-dev-archive@forrest.apache.org
Received: (qmail 89403 invoked by uid 500); 31 Mar 2005 21:52:53 -0000
Mailing-List: contact dev-help@forrest.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:dev-help@forrest.apache.org>
list-unsubscribe: <mailto:dev-unsubscribe@forrest.apache.org>
List-Post: <mailto:dev@forrest.apache.org>
Reply-To: dev@forrest.apache.org
Delivered-To: mailing list dev@forrest.apache.org
Received: (qmail 89380 invoked by uid 99); 31 Mar 2005 21:52:52 -0000
X-ASF-Spam-Status: No, hits=0.0 required=10.0
	tests=
X-Spam-Check-By: apache.org
Received-SPF: neutral (hermes.apache.org: local policy)
Received: from ns3.wkwyw.net (HELO ns3.wkwyw.net) (217.199.181.91)
  by apache.org (qpsmtpd/0.28) with SMTP; Thu, 31 Mar 2005 13:52:52 -0800
Received: (qmail 5713 invoked from network); 31 Mar 2005 21:52:56 -0000
Received: from 82-69-78-226.dsl.in-addr.zen.co.uk (HELO ?192.168.0.4?)
 (82.69.78.226)
  by ns3.wkwyw.net with SMTP; 31 Mar 2005 21:52:56 -0000
Message-ID: <424C7130.20206@apache.org>
Date: Thu, 31 Mar 2005 22:52:48 +0100
From: Ross Gardler <rgardler@apache.org>
User-Agent: Mozilla Thunderbird 1.0 (Windows/20041206)
X-Accept-Language: en-us, en
MIME-Version: 1.0
To: dev@forrest.apache.org
Subject: Re: DITA plugin (Derby history)
References: <20050331014217.65532.qmail@web81602.mail.yahoo.com>
 <424C539D.8080902@bristowhill.com> <424C5BB6.8070704@apache.org>
 <424C694C.3020600@bristowhill.com>
In-Reply-To: <424C694C.3020600@bristowhill.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-Virus-Checked: Checked
X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N

Jean T. Anderson wrote:
> Ross Gardler wrote:
> 
>> Jean T. Anderson wrote:
>> <snip />
>>
>>> We'd like to do a separate forrest project for 
>>> repos/asf/incubator/derby/docs and use forrest to build the manuals 
>>> from dita source, then copy those built docs into the derby web site 
>>> source -- but not under xdocs. We don't need to rebuild the docs each 
>>> time the derby web site is built.
>>
>>  
>> Do you want the site navigation on the DITA docs?
> 
> 
> Users want pdf and html as whole books and as books in pieces -- much of 
> this is captured at http://issues.apache.org/jira/browse/DERBY-79 , but 
> much still needs to be specified. I expect users to want some set of 
> files hooked into the site navigation, but many fewer than what we have 
> now.

OK, from that issue:

* Provide manuals in a PDF format (one manual per PDF file, not PDF 
files for every page, see mail thread in derby-dev below)
* Improve navigation in HTML format. For example, have left hand frame 
with table of contents and less pages to navigate (see mail thread in 
derby-user below)
* Provide hyperlinks across manuals
* Make it easier to search the manual (on the user's PC, not refering to 
the Google search on the Derby web site). PDFs will address this. Having 
less HTML pages would also help here.

PDF is not a problem once we have the files generated by Forrest.

Improved naviagation is also not a problem

Hyperlinks across manuals depends on how linking works in DITA. Of 
course I am sure that you could simply create a hyperlink if nothing 
else would work, although that could become a maintenance problem.

Offline searching is not a problem if your users have Forrest installed 
since, as you may know, Forrest has Lucene integrated for local searching.

> The current setup at 
> http://incubator.apache.org/derby/manuals/index.html isn't optimal. 748 
> *.ihtml files get rendered into 748 *.html files, and this has the 
> following problems:

OK I understand.

What we do here at Forrest is we have two sets of xdocs. The first is 
the website, the second is the docs. The docs can be built independently 
of the website and are linked in via the menu system in the website.

I suspect that this will be the easiest way of achieveing what you need.

> With DITA there are 1048 files -- I'm the main advocate for keeping them 
> out of the derby web site's xdoc directory. :-)

I can understand that.

Ross