Peter Fleck | 25 Aug 15:47 2015

Index of People (5.1)

Hi all,

Can anyone give a starter on how to create and "Index of People" and "Index of Organizations" in 5.1?

I know that I can wrap an  <indexterm type="people"> around the <person> tag in the source file but wondered if the Index could be created without the extra XML tagging.


Carlos Araya | 24 Aug 22:17 2015

Re: PDF-like HTML output

Please see my comments inline

On Wed, Aug 19, 2015 at 2:07 PM, Jan Tosovsky <j.tosovsky <at>> wrote:
Dear Carlos,

thanks for your valuable feedback!

On 2015-08-19 Carlos Araya wrote:
> The main issue for me is that, to my knowledge, there is no open source
> solution that works with CSS Paged media and its associated generated
> content) and none of the available commercial solutions is cheap.

I personally take those HTML+CSS processors as temporary 'dead end' solution
which will be (in long term) replaced with regular web browsers.

Paged media content may or may not be the same solution than generating adaptive layouts like epub's multiple renditions.  The purpose of Paged Media is to generate print-ready layouts... there are books that have been created with CSS Paged Media (Lea Verou's CSS Secrets comes to mind) and we can expect more such content in the future

I would not call it a dead end solution just yet. 

So I was quite skeptic to CSS paged media (not mature yet, expensive
processors) ... until I met vivliostyle.js. It brings CSS paged media to
browsers NOW. To some extent it makes dedicated processors redundant.

Thank you for sharing this. I think it's worth taking a look at it but I'd ask right off the bat what's the browser support for this technology and what happens when Javascript is not available or we need it to work with assistive technology?

I don't believe all works in reality as smooth as announced on their page,
but I like the concept. As it is open source, you can extend it if you find
some funcionality missing. So instead of patching XSL-FO processors I'd
rather patched this Javascript library (if I could). It is also temporary
'dead end' which will be replaced with regular browsers, but you can prepare
the content in pure CSS standard NOW with minimal risk of further updates
when browsers will become mature enough.

In an ideal world you would be able to get high quality print outuput directly from your web content without having to use a library at all. But we're not there yet and, sadly it'll be a long time before we get there from a publisher and content distributor perspective.

Publishers and other vendors will want DRM to be built into the content they distribute.  Do we really want EME for content other than video?

That said there's nothing stopping you from hacking Norm's XSLT 2 stylesheets ( to generate the HTML you need to work with vivliostyle :)

Once your content is rendered in a browser, it is quite straight forward to
convert it into PDF. But to be honest, this conversion IMHO doesn't make
much sense any more ;-)

Why do you see it making no sense?  

I personally would still like the option of hard copy reading so I can make notes and underline the content I read. I would also like the capability to share the content and the annotations I make without violating the license to my content.  

IF you're interested on the convergence between web, ebook and other digital content you may want to check the epub+web white paper at:

All above shouldn't be taken too seriously. It is just my (naive) view.

We all have our opinions about how things should work. It's the sharing of these opinions that make us grow as a community.   

> The final question I'd have before jumping into CSS Paged Media
> development is for what version of the stylesheets?

While I'd prefer XSLT2, I am afraid this is not acceptable by majority of
end users.


To unsubscribe, e-mail: docbook-apps-unsubscribe <at>
For additional commands, e-mail: docbook-apps-help <at>

Lars Vogel | 19 Aug 14:21 2015

<part> should become <appendix> in another book


I use xinclude to include certain documents in different books. In a certain context I want to use it as part in another as appendix.

I tried to remove the top level node with the following to my customization layer:

<!-- Remove all sections marked with wrapper -->
<xsl:template match="part[ <at> role='wrapper']" mode="profile">
<xsl:apply-templates select="part" mode="profile" />

And include it into the books like this:

<title>Gerrit code reviews with Eclipse</title>
<xi:include xmlns:xi="" href="820_gerrit.xml" />


<title>Gerrit code reviews with Eclipse</title>
<xi:include xmlns:xi="" href="820_gerrit.xml" />

Unfortunately my customization removes not only the top level part element but the whole part.

Is anyone aware of a nice trick to replace part in some books with appendix? 

Best regards, Lars

P.S. What I would like to have is the equivalent of the <merge> node for defining Android layouts, this node is only their to have a valid XML file, but is removed during the include process.
Peter Eisentraut | 14 Aug 21:17 2015

Re: PDF-like HTML output

On 8/9/15 4:45 PM, Jan Tosovsky wrote:
> Dear All,
> (1) there was lot of work in W3 recently dedicated in CSS for paged media
> (2) there are conversion tools from HTML+CSS to PDF utilizing these features
> (3) some interesting JavaScript libraries have appeared (e.g.
> vivliostyle.js) emulating the intended rendering to 'yet inmature' browsers
> (polyfills)
> which make me wonder if there is an interest in making some kind of
> reference implementation of PDF-like output in HTML+CSS from DocBook source,
> especially for (3). Has anybody any experience with it?

There were some mumblings a while ago that this might be the direction
of print output, seeing that XSL-FO doesn't have much activity anymore.
 So more investigation is surely welcome.

I played with this a while ago, and while you can get pretty good
looking "print" output with fairly little effort, there are some obvious
functionality gaps, such as: How do you produce a table of contents with
page numbers?
Winslow Dalpe | 14 Aug 06:53 2015

Announce: Tabletop role-playing game materials produced with DocBook

Hi, everyone! I'm really excited to announce a project I'm working on: a community-use campaign world and accompanying series of adventures for tabletop role-playing games. And while I'm very excited about its content, I'm also pleased to announce that the project is being published using DocBook and related technologies.

We've only just now released a draft of the player's guide for our first adventure path: Two Graves. You can check out the results online at

or by grabbing a PDF or EPUB from

The project's main page is

So, now for the fun bits!

The materials are targeting DocBook 5.0 and utilize my fork of the DocBook XSLT 2.0 Stylesheets for HTML output and the DocBook XSL stylesheets for EPUB output. For PDF output, I have chosen not to use XSL-FO for the final output, although I do have build targets for it. Instead, I'm trying out some newer CSS features. The PDF is generated from the exact same HTML output using PrinceXML and print media CSS stylesheets of my own writing. Calabash handles the pipelining for the XSLT 2.0 transformations, although I may apply it to the 1.0 transformations as well in the future.

You may notice that the actual source for the materials is in Asciidoc. I wanted to make contribution to the materials more accessible for non-technical contributors. As powerful as raw DocBook is, I don't think I would have very many takers on writing the XML directly or purchasing specialized software. Although the plan is to continue writing the source in Asciidoc, the jury is still out. I don't particularly enjoy writing Ruby extensions to Asciidoctor to give me markup already present in raw DocBook, so if community contribution is not seeing any benefit from Asciidoc then I will have to come up with some other mechanism for accepting contributions.

Like the materials, this project is still early in development. Everything's a little rough, but I heartily welcome constructive criticism on both the textual content and infrastructure. This is my first project using DocBook and many of these other tools and concepts, so I'm certain there's plenty of room for improvement. The code itself is AGPLv3 and the textual content for the book is OGL, so I also welcome contributions if anyone is feeling froggy.

I hope you all enjoy this in some capacity, and thank you for all the hard work everyone has put in before me! I'm truly standing on the shoulders of giants.

Winslow Dalpe
Jan Tosovsky | 9 Aug 22:45 2015

PDF-like HTML output

Dear All,

(1) there was lot of work in W3 recently dedicated in CSS for paged media
(2) there are conversion tools from HTML+CSS to PDF utilizing these features
(3) some interesting JavaScript libraries have appeared (e.g.
vivliostyle.js) emulating the intended rendering to 'yet inmature' browsers

which make me wonder if there is an interest in making some kind of
reference implementation of PDF-like output in HTML+CSS from DocBook source,
especially for (3). Has anybody any experience with it?

I am not experienced in this field, but I am willing to help, at least with
testing :-)

Thanks, Jan
Attachment (winmail.dat): application/ms-tnef, 3069 bytes

To unsubscribe, e-mail: docbook-apps-unsubscribe <at>
For additional commands, e-mail: docbook-apps-help <at>
Dave Pawson | 5 Aug 10:51 2015

ay/  and associated code

New CSS3 grid layout. So easy to overlay on docbook and it looks so

Well worth watching. 

regards Dave P
Lars Vogel | 4 Aug 13:14 2015

Default for scale factor for images


for my screenshots I typically add a scale factor of 40 to make the images size well.

<imagedata fileref="./images/application_model_ui_elements.png" scale="40" />
<phrase>Application Model UI Elements</phrase>

Is there a general parameter for this? My desired behavior would be that I can define a default for all imageobject which do not specify this parameter but override it for individual imageobject via this parameter.

Best regards, Lars
Cathy Riely | 31 Jul 18:55 2015

support for olink PDF fragment IDs

I am using oXygen XML Editor 16.1 with the bundled DocBook 5 stylesheets and Apache FOP 1.1 and Saxon 6.5.5.

I am generating PDFs from within Oxygen. I followed the instructions here to set up everything. I can link from one PDF and open to a spot within a second PDF, if I am linking to sections in the other doc. But it is not working for me to link to a table within the other PDF; instead it opens to page 1 of the PDF.

Anyone have this same issue? Or able to successfully link to a table within a second PDF?


Cathy Riely
 Technical Writer, Lonestar Design Center
512-910-6275 office
512-413-6250 cell

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>
For additional commands, e-mail: docbook-apps-help <at>
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> | +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