Janice Manwiller | 29 Jul 03:25 2015

Paragraphs within list item jutting into page footer

I had asked about this issue earlier, and thought I had found a solution, but unfortunately it's not working reliably.

On occasion, PDF pages do not break correctly within a list item. If the list item contains more than one paragraph, then the paragraphs can bleed into the page footer.

I had come across the dbfo-need option, which sometimes works, but not always.

The attached image shows an example of this happening.

Here is the source DocBook XML for the same excerpt.

                        <para>To use a column to add a new field to the source data, in the dropdown
                            list field, type the name of the new field, then press
                                    <imagedata scale="100"
                                    <phrase>Entering a new source field name for a CSV
                        <para>For information on restrictions on field names, see <xref
                        <para>For these new fields, Sqrrl infers the data type based on the values
                            in the file.</para>
                        <?dbfo-need height="2in" ?>
                        <para>These new fields are not added to the source definition.</para>
                        <para>To remove a column from the list, click its delete icon.</para>

So while I have the dbfo-need option set for the paragraph, it's still not causing the page to break.

Any ideas to get this to work reliably?



To unsubscribe, e-mail: docbook-apps-unsubscribe <at> lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help <at> lists.oasis-open.org
Dew, Simon | 17 Jul 18:30 2015

PACBook announce


I'm pleased (also slightly nervous) to announce the PACBook project.
This is a suite of linguistic pre-processing stylesheets for XML
documentation, primarily aimed at DocBook.

The project is hosted here:


The stylesheets deal with two inter-related areas:

1. Translating documents;

2. The linguistic consequences of transclusion and / or conditional

Users of Publican may be interested to know that, among many other
things, these stylesheets attempt to address the linguistic problems
mentioned here:


Although I'm using these stylesheets daily (along with the DocBook XSL
stylesheets) and have been for years, this is not a 1.0 release.
Documentation is, ironically, a work in progress — see the doc folder or
the wiki, and unit tests are basically non-existent.

I'm happy to offer these stylesheets to the DocBook community in the
hope that someone will find them useful. Contributions are welcome.
Simon Dew

Technical Author | Stanley Security Solutions
1 Park Gate Close, Bredbury, Stockport SK6 2SZ, U.K.

Simon.Dew <at> SBDInc.com | +44 (0) 161 406 3400

Registered Office: Stanley House, Bramble Road, Swindon
Registered in England and Wales No. 181585 VAT No. 232 2446 95
Stanley Security Solutions Limited is a limited company registered in England and Wales with registered
number 181585 and VAT registered number 232244695. Registered Office: Stanley House, Bramble Road,
Swindon, SN2 8ER. This message and any attachments are confidential. It may not be disclosed to, or used
by, anyone other than the addressee, without the consent of the sender. If you receive this message in
error, please send the message back to us and then permanently delete the message. For information about
how we process data and monitor communications please see our Privacy Policy
jnilo | 13 Jul 11:22 2015

displaying last leaf of doc in chm file using htmlhelp

Hello all
I am using the htmlhelp stylesheet to create the chm version of my documentation.
A test file looks like:

<?xml version="1.0" encoding="UTF-8"?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0" xml:lang="en">
<section xml:id="_chapter_1">
<title>Chapter 1</title>
<section xml:id="_section_11">
<title>Section 11</title>
<section xml:id="_sub_section_111">
<title>Sub section 111</title>
<simpara>Some text appears here</simpara>

I am chunking this file with the following parameters:
I order to have seperated files for the different contents.

Now when I open the chm file I would like NOT to display on the right panel the "empty" content of Chapter 1 and
Section 11 while keeping them appearing in TOC. That is display only the final leafs containing "real" content.

Is there a trick/parameter to do that (NB: my "final" leaf is not always at the same level)

Thank you for your help !

Gabriela Simonka | 8 Jul 22:36 2015

Linking to an HTML file


I am writing documentation (article) in XML for one of our products, and I would like to link to an HTML file exported from an IPython Notebook document that we are including alongside our documentation. How does one do this?

Thanks in advance,
Gabriela Simonka
Technical Writer
T +1 514-369-2023
F +1 514-369-2026
Subscribe to INRO announcements
DISCLAIMER: This message, including attachments, may contain confidential information for the sole use of the intended recipient(s). Any unauthorized use, disclosure, viewing, copying, alteration, or distribution of any information in this message is prohibited. If you have received this message in error please notify the sender immediately.
Gabriela Simonka | 8 Jul 21:18 2015

Page numbering and volumes


I am splitting one of our manuals into two volumes.  How does one continue the page numbering and autolabelling of tables, figures in the second volume?  For example, volume 1 goes from page 1 to 650 and I would like volume 2 to go from page 651 to 1140.

Gabriela Simonka
Technical Writer
T +1 514-369-2023
F +1 514-369-2026
Subscribe to INRO announcements
DISCLAIMER: This message, including attachments, may contain confidential information for the sole use of the intended recipient(s). Any unauthorized use, disclosure, viewing, copying, alteration, or distribution of any information in this message is prohibited. If you have received this message in error please notify the sender immediately.
DeanNelson | 8 Jul 07:10 2015

Long Table Markers

Is the next Docbook XSL version going to support long table markers? (i.e 'continued' on the top of next page of long tables).
That's a very nice feature for tables.
Dean Nelson
Bob Stayton | 7 Jul 23:16 2015

ANNOUNCE: new solar book produced using Docbook

You know me as the author of DocBook XSL: The Complete Guide.  Now I have written another book on a completely different topic: solar energy.  Since I produced my new book using DocBook, I'm taking this opportunity to tell the DocBook community about it, and I describe how I produced it at the end of this message.  Replies about the DocBook process can go to the whole list if you think it's appropriate.  If you want to reply about the book's content, please reply just to me so we don't burden the mailing list.

I'm pleased to announce that my book Power Shift: From Fossil Energy to Dynamic Solar Power has been unleashed from its long development and is now available to the world.  If you have any interest in solar energy, then you should read this book.

Climate change researchers sometimes paint a bleak picture of our current global-warming crisis, but rarely explain how we got into this predicament in the first place and how we get out of it. Now, for the first time, my new book does just that. Power Shift retells human history through the lens of energy, explains the science behind the crisis--in clear, succinct language that anyone can understand—and provides a detailed blueprint for the future, from governmental, commercial, and individual perspectives.

Wondering if the book is any good?  Here is what others are saying:

"Solar is surging all of a sudden, and if you read this comprehensive
book you’ll understand why!" -- Bill McKibben, author of The End of Nature

"An energy book that is a pleasure to read" -- Kirkus Reviews

"visionary and brilliant" -- NASA Researcher Joe Jordan

"Exceptionally well written" -- Midwest Book Review

"lucid, convincing" -- Denis Hayes, organizer of the first Earth Day

"points the way to a clean energy future" -- California Secretary of Natural Resources John Laird

or check out the reader reviews on Amazon

After teaching solar energy for many years, I spent over 15 years researching and writing this book, all while living the life in the off-grid solar home we built. This is my lifework.

It has been a long road to publication.  I handed out the first draft in January 2000, and many things have changed since then. Now I get to report on solar energy's success instead of just wishing for it.  I'm self publishing the book, because as an unknown author I could not interest a publishing company, and because they don't offer much in the way of marketing for new authors anyway.  So I started my own publishing company, Sandstone Publishing (www.sandstonepublishing.com), whose catalog contains exactly one book.

Now I get to market my book, an activity for which I am totally unsuited.  My low-budget marketing plan consists of getting good reviews, and word of mouth.  So if you read the book and like it, please write a review on Amazon or Goodreads, and tell your friends and family about it.  Even climate skeptics can get something out of this book.

The book is available in paperback and Kindle at Amazon, in paperback and Nook Book at Barnes & Noble,  in iBooks at the Apple iTunes Store and in Kobo from Kobo Books. And if you can't afford one, convince me and I'll give you an Ebook copy.  8^)

By the way, although you know me as Bob Stayton, I'm publishing the book under my full name Robert Arthur Stayton as a gesture to honor my father Chester Arthur Stayton, Jr. and my grandfather Chester Arthur Stayton, Sr., with whom I share my middle name.

Producing Power Shift with DocBook

I wrote the book in DocBook 5 using XMetal 7.  I started off writing it in modular fashion, but found that it got in the way of continuity. This isn't technical documentation, after all.  8^)   So I merged all the files into one big book file and finished the book that way.  That allowed me to easily find something for cross referencing and to keep the narrative flow moving. Searches for indexterms were much easier in a single file, and I used XMetal macros to assist with inserting indexterms.

I hired a book designer for the interior and implemented the specs from the InDesign file she gave me in DocBook XSL.  From that I could generate the PDF for the book's interior.  I had hoped to be able to show you the page design by referring to the Look Inside the Book feature on Amazon, but for some reason they put the Kindle version in there and I have not been able to reach the right person at Amazon to replace it with the PDF version I submitted to them two weeks ago.  One of the many trials of working with automated publishing vendors.

For the cover, I started with a cover template in InDesign that I generated from Lightning Source, which is the print-on-demand vendor that I'm using.  They provide a form to enter the book's dimensions, paper type (which determines thickness), and page count, and they generate an InDesign template for the cover spread (back cover on left, spine in center, front cover on the right).  I could then fill in the text in the appropriate boxes. I left the cover in InDesign rather than try to implement it in DocBook.  From InDesign I produced the PDF for the cover.

Then it was just a matter of setting up the book at Lightning Source and submitting the two PDFs.  Since I already had an account at Lightning Source for my DocBook book, I just had to add another book.  If you are new self publisher, they will likely try to push you over to Ingram Spark, their service that is intended for self-publishers with little publishing experience.  Lightning Source does much less hand holding than Spark.

Lightning Source has some specific requirements for the PDF files you submit.  All fonts must be embedded, including those of any SVGs you insert.  They also came back and said the cover colors were too rich and had to be scaled back.  I was able to fix all the PDF issues using PhotoShop and Acrobat Pro's Preflight tools.

In January of this year I ordered the first Advance Reading Copies (ARC) to send to reviewers that want the book months before publication so they can write a review.  The ARC version predated the final copy edit, the index, and other final details.   The great thing about print-on-demand is that I could order only as many copies as I needed.  In April I completed the final revisions in XMetal and submitted my revised PDFs.  It cost only $40 each to update the book block and the cover.  Once I approved the test book, Lightning Source arranges for the book to be posted on Amazon and listed in Books-in-Print.

I also used the DocBook tools to produce Ebook versions with the epub3 stylesheet.  I ended up producing four different epub3 flavors for Kindle, Nook, iBooks, and Kobo.  They differ mostly in the CSS used, because their readers are not at all consistent about how CSS is handled.  It reminded me of the bad old days of HTML browser incompatibilities.  I then had to set up accounts on each of the systems to become an Ebook seller.  The biggest pain was iBooks, because Apple *requires* you to use an Apple computer to run the software they use to manage iBooks.

Just when you think you are done, you realize that no one is buying your book because no one knows about it.  So I had to start a whole new career as book marketeer.  Not much help from DocBook there.
-- Bob Stayton Sagehill Enterprises bobs <at> sagehill.net
Thomas Schraitle | 30 Jun 08:53 2015

Time for new DocBook Stylesheet Release?


in the last years I've observed a trend, that the DocBook stylesheets
don't publish new releases very often.

The last release of the stylesheets is from 2013 which is two years old!
Am I'm the only one who need and wait desperately for a new release? ;))

I know, you are all busy with other things. However, I fear, this makes
the wrong impression that this project is dead. I hope this is not.

After two years I would love to see a new release. Maybe with a release
cycle which counts in months and not years?

Any plans? Thoughts? :)


    Thomas Schraitle
DeanNelson | 30 Jun 01:19 2015

Docbook XSL and FOP 2.0

I have tried to update our production documentation system to FOP 2.0 but in doing so I discovered a little problem that prevented the use of FOP 2.0. I get an exception and cannot get around it without recompiling with a fix. (See https://issues.apache.org/jira/browse/FOP-2461 )
I am interested in other people's experience in using FOP 2.0. In your experience, is it really ready for prime time? Are you using it successfully?
I'm using the 1.78.1 stylesheets with Docbook 4.5.
Dean Nelson
Olivier Ishacian | 29 Jun 22:07 2015

New resources for those interested in DocBook 5.1 new assembly and topic elements

Two new resources for those interested in DocBook 5.1 new assembly 
andtopic elements:

* Free, open source, assembly processor: XMLmind Assembly Processor.

* Tutorial: DocBook Assemblies and Topics for the Impatient.
Olivier Ishacian | 29 Jun 22:00 2015

[ANN] Release of XMLmind XML Editor v6.3.1

XMLmind is happy to announce the version 6.3.1 of XMLmind XML Editor.

XMLmind XML Editor Evaluation Edition v6.3.1 can be downloaded from

Professional Edition users, please upgrade using this form:

(The above form is usually accessed through

XMLmind XML Editor v6.3.1 (June 24, 2015)


* Preliminary support for DocBook 5.1, which introduces new topic
   and assembly elements.

   This support is packaged as a new add-on called "DocBook v5.1
   configuration (Release Candidate)". This add-on is NOT included
   by default in XXE distributions. If you want to experiment with
   DocBook 5.1 assemblies and topics, please use menu item
   "Options|Install Add-ons" and select the add-on in order
   to download and install it.

   New resources related to DocBook 5.1:

    - New tutorial: DocBook Assemblies and Topics for the Impatient.

    - New documentation: XMLmind XML Editor - Support of
      DocBook 5.1 Assemblies.

    - New open source software: XMLmind Assembly Processor.

* Upgraded Apache Batik (SVG support) to version 1.8.
   Upgraded Apache FOP (PDF generator) to version 2.0.

* Several other enhancements (e.g. menu item "DocBook|Convert
   to Module") and a few bug fixes.

More information in


* DocBook Assemblies and Topics for the Impatient

* XMLmind XML Editor - Support of DocBook 5.1 Assemblies

* XMLmind Assembly Processor