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
