Deprecated: Joomla\Input\Input implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in /homepages/13/d380392445/htdocs/Jlive/libraries/vendor/joomla/input/src/Input.php on line 41

Deprecated: Return type of Joomla\Input\Input::count() should either be compatible with Countable::count(): int, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /homepages/13/d380392445/htdocs/Jlive/libraries/vendor/joomla/input/src/Input.php on line 170
Experiences using DocBook XML - Macrotone Blogs

Macrotone Blogs

Macrotone blogs upon Joomla, our products and other matters.
Font size: +

Experiences using DocBook XML

This summaries a few of the lessons learned using DocBook XML for documentation.

Upcast: The conversion from Microsoft Word to DocBook XML introduced a few opportunities for changes:

1. Media objects (figures) are all converted to ‘inlinemediaobject’, and even when the image is on its own it always is surrounded by ‘para’ and results up positioned on the left hand side of the page. The best approach we found was to convert them to simple ‘mediaobject’ and change then to become ‘figures’ and in this way also enable the creation of a ‘List of Figures’. We also tended to change the specified exact image size to use scaling so that the width of 14cm was most appropriate. [This did impact the fact that all html screen images come out at a standard width.]

2. Tables were an interesting investigation. The tables were created as ‘informaltable’ using ‘colgroup’ with a ‘width’ specification. This resulted in tables being of a restricted width and all swashed to the left hand side of the page.  We changed the table definition to use the ‘pgwide’ attribute and change any width specification to be specified in ‘%’ rather than specific pixels.  This means that we can use the whole width of the page and also removed a message from the FOP process where it cannot understand the width specification where more than one column is specified. It is not necessary to specify the width of all the columns only the few that we want to be of a certain size. otherwise all columns end up with the same width. Changing them to standard tables, as with the images described above, also enabled the creation of the ‘List of Table’.

3. The generated XML file had a lot of references to the ‘role’ attribute, which is a DocBook v4 specification and not a DocBook v5 specification.  There were also a number of uses of the ‘id’ attribute when it should, under v5 be using ‘xml:id’ instead.

[We used the evaluation edition of ‘upcast’ so some of these findings may not be present in the released version, and not being experts on ‘upcast’, may have missed options for changing the generated output.]

 

XML Editing: These were general editing improvements:

1. Make use of ‘info’, ‘tip’, ‘important’ and ‘note’ fields where possible.

 

Apache FOP:

1. There are a number of messages generated by FOP which are informative, but tend to block out real errors.

We see a number of warning messages ‘Line 1 of a paragraph overflows the available area by 105 millipoints. (No context info available) but this is no indication as to which line the error is encountered. It seems one can ignore the message since the output looks fine, but it would be nice to resolve it properly.

Also get the following warning messages:

Font "Symbol,normal,700" not found. Substituting with "Symbol,normal,400".

Font "ZapfDingbats,normal,700" not found. Substituting with "ZapfDingbats,normal,400".

and the Error:

Couldn't find hyphenation pattern for lang="en".  This is resolved by downloading the OFFO hyphenation files from sourceforge and placing the jar file in the fop/lib directory. Language of the book can be specified by using the attribute xml:lang.

It seems to be reasonable to ignore the warning messages, which appear to be known problems.

2. The –q (quiet) option doesn’t seem to affect the display of the messages at all, so appears to be ignored.

3. The –d (debug) option doesn’t seem to generate anything useful at all.

[This is using version 1.1 of FOP.]

 

Other:

1. Changing the FOP configuration to use an A4 pagesize doesn’t stop the generated PDF document saying it is in US letter size.  Need to specify the parameter paper.type A4 to the XSL processing. One can add this on the command line to FOP.

2. The PDF properties such as Author, Title etc. are not set.  These can be changed by a PDF editor but it is another manual step.

3. The tag cover does not seem to be handled in the PDF output.  It is possible to add an inlinemediaobject to the subtitle (and title) tag, which is then added under the title.

Farewell to Microsoft Messenger
DocBook XML to PDF
 
Go To Top

Joomla! Debug Console

Session

Profile Information

Memory Usage

Database Queries