forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: DITA plugin (Derby history)
Date Thu, 31 Mar 2005 21:52:48 GMT
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

Mime
View raw message