Fix the doc build process for the 1.x line

[GoogleCodeExporter]

The documentation in the 1.x line needs updating. However, the build process is 
not trivial, and took me a while to get running (I'm a new doc committer with 
no prior docbook experience).

I am now able to build the documentation on Windows, but the output is less 
than ideal in PDF. This needs fixing, probably through tweaking of the 
stylesheets.

I will also try to produce the PDF output from a linux setup, which seems to 
have better support for docbook.

One thing to consider is also to move the documentation source to docbook 5 
(currently version 4.1.2 of the docbook format is specified in the doc source). 
The impact of moving to docbook 5 needs to be evaluated, and might solve the 
PDF format problem described above.

I'm initially putting this High priority and Bug, but I am not familiar with 
the project's "standards" on issues. Please correct if I'm wrong.

Resolving this issue will obviously be useful for the 3.x line documentation 
build process.

Original issue reported on code.google.com by rcham...@gmail.com on 25 Oct 2010 at 1:39

[GoogleCodeExporter]

I just tried generating the tutorial's doc using a docbook 5 DTD. The only 
required change was to adjust the header of docs/tutorial/src/en/index.xml (the 
DTD version is part of the XML namespace) and also the DTD changed name 
(docbook.dtd instead of docbookx.dtd).

This did not fix the PDF formating problems.

However, if we only need to change the header of the three index.xml files, I 
would be tempted to suggest we consider moving to docbook 5, which by the way 
still seems to be in beta phase.

Original comment by rcham...@gmail.com on 25 Oct 2010 at 2:28

• Changed state: Started

[GoogleCodeExporter]

Docbook 5 DTD also works well for DataAccessGuide and DataMapperGuide.

I'm testing all this on a local copy, I do not intend to commit these changes 
until I get feedback from others, and until we fix all the urgent issues with 
the doc build process.

Original comment by rcham...@gmail.com on 25 Oct 2010 at 2:39

[GoogleCodeExporter]

In trying to fix the FOP related problems (PDF version of the doc), I looked at 
the Hibernate docbook source files (our fopdf.xsl files were oringinnally 
imported from the hibernate project, so the headers say).

They seem to still be using docbook 4.5. I suppose there might be good reasons 
for that. Food for thought in our decision making regarding upgrading our 
source to a more recent version of docbook than our current 4.1.2.

Original comment by rcham...@gmail.com on 26 Oct 2010 at 1:21

[GoogleCodeExporter]

Here is my current list of issues with the production of the PDF format of the 
doc:

- Cover page missing most of its information (authors, date, version number, 
...).
- Leaders in TOC not adequate,
- Some images are way too wide, I don't yet know how to control this from the 
stylesheets, or even if it's possible.
- When code samples are too long, the line doesn't wrap automatically and the 
rightmost portion is lost.

If someone else manages to build the PDF doc and notices other issues, please 
add them here.

As far as I know, the CHM output is as good as it can get, I haven't noticed 
any issues, but I did not read the CHM docs thoroughly, just skimmed them.

Original comment by rcham...@gmail.com on 26 Oct 2010 at 1:37

[GoogleCodeExporter]

Revision 28 fixes the overblown images in PDF output problem. This required 
changing both the docbook XML source files AND the stylesheets for HTML.

I also proposed a temporary path to the cover page and TOC problems, by 
removing the custom first page and custom TOC in the PDF stylesheet 
(tutorial/styles/fopdf.xsl). If this is acceptable, I will mimic this solution 
in DataAccessGuide and DataMapperGuide PDF stylesheets until I can figure out 
what the problem is with FOP and custom first pages.

The only remaining issue would be the long lines in code samples which are 
clipped.

Original comment by rcham...@gmail.com on 27 Oct 2010 at 3:31

[GoogleCodeExporter]

Revision 29 fixes the overrunning lines in code samples.

Original comment by rcham...@gmail.com on 27 Oct 2010 at 3:49

[GoogleCodeExporter]

Closing this issue, will create a new one with the remaining PDF problem 
(custom first page).

Original comment by rcham...@gmail.com on 27 Oct 2010 at 11:43

• Changed state: Fixed
• Added labels: Priority-High
• Removed labels: Priority-Critical