Re: DITA plugin (Derby history)

["Jean T. Anderson" <jt...@bristowhill.com>]

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.

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:

1) Users don't like having quite so many files (captured in the 
http://mail-archives.eu.apache.org/mod_mbox/db-derby-dev/200410.mbox/%3c200410071315.32497.Joel.Rosi-Schwartz@Etish.org%3e 
thread).

2) 'forrest site' takes anywhere from 15-60 minutes depending on the 
speed of your processor and available memory. I have a 64bit processor 
and 2gig of memory, and it takes me 10-15 minutes.

3) 748 files are too many to be listed in the menu. Right now just the 
table of contents and index page are listed for each book. But I 
included the rest of the files in the site.xml (without a label) so when 
you click on a page it keeps the association with the manuals tab. 
However, it loses the association with a specific book. Clunky.

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

  -jean

Re: DITA plugin (Derby history)

[Ross Gardler <rg...@apache.org>]

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