Docbook tools

But DocBook is definitely one of my two choices for reports, books, and longer bits of documentation. Interesting article, thank you. I maintain church service books, which need quite complex layout, so I have been writing them directly in epub.

I then process these to PDF for printing, but also output them for electronic books. Looking at the article, it seems I may gain some advantage from DocBook, using different toolchains for the various formats. My main problem with using epub is that I'm the only one with the skills to maintain them. DocBook, for all it's comprehensiveness, and verbosity, appears very understandable.

One little complexity that I have to manage is 4-part music, at the moment I use Lilypond mark-up for that, and embed the resulting images. Any thoughts would be helpful. Like TeX, it seems that DocBook does best with pure text output.

Working with graphics and trying to place them precisely is challenging as far as I can tell. Scribus, of course, is designed for layout at great precision, and is wysiwyg. It also has Render frames, which can make use of Lilypond markup, TeX, and others. I have tried Scribus, I found it, like most wysiwyg desktop applications, almost unusable, sorry. I also found the documentation, for instance the wiki, very out of date.

But thank you for the suggestion. As with anything, it's all about what you need to do. In those rare instances I need to create a shorter document with a more complex layout, I turn to Scribus. Depends on what you're trying to do. Placing graphics isn't difficult if you're just inserting graphics into the flow of text or block elements. However, if you're doing something like fancy layout design, like partly transparent background images or rounded graphics that you want to wrap text around, or even text on paths, then docbook is likely not the best option.

I use scribus for projects that require fancy layouts. I use docbook for the docs that I want to be able to work on without a GUI, and that many other people would do in a word processor. I don't consider it a layout or design schema Getting started with Docbook An introduction to DocBook, a flexible markup language worth learning.

DocBook is easy to learn, easy to write, and does things other text markup languages can't do. Image by :. Internet Archive Book Images. Modified by Opensource. Get the highlights in your inbox every week. Topics Documentation.

Multimedia Makers column. About the author. He has worked in the film and computing industry, often at the same time. He is one of the maintainers of the Slackware-based multimedia production project Slackermedia.

More about me. Recommended reading Build a static website with Eleventy. A DevOps guide to documentation. How to create a documentation site with Docsify and GitHub Pages. Scott Nesbitt on 14 Sep Permalink. Same here! Long time since I heard of Docbook. Thanks for the article. Seth Kenlon on 14 Sep Permalink. Richard Downing on 15 Sep Permalink. Greg Pittman on 15 Sep Permalink. Wear your duck on your sleeve!

Well, your chest anyway. DocBook V5. This release updates the Schematron rules to match the Schematron standard that changed after 5. The 5. DocBook Version 5. This release adds support for assemblies modular documentation and resolves a number of issues. See DocBook Version 5. This schema remains non-normative, and more permissive than the normative DocBook schema, but hopefully represents a significant improvement over the previous, machine-generated attempt. Version 5. The element may have different content models in different contexts, to manage titled and non-titled elements, for example.

DocBook 5 introduces a general purpose annotation mechanism that allows you to associate information with any element. The main difference is that the document's root element must have the DocBook namespace attribute and a schema version attribute.

For example:. A namespace attribute may optionally define a namespace prefix , and then the elements in that namespace must use the prefix on the element name. In the following example, the prefix is d :. Note that the root element is now d:book , and all other DocBook elements in the document must also have the d: prefix on their names in both opening tags and closing tags of elements.

When a namespace attribute has no prefix, the namespace becomes the default namespace. A namespace attribute on an element means that the namespace is in scope for that element and all of its descendants. That does not necessarily mean those elements are in the namespace, just that the namespace is recognized. An element within that scope is actually in the namespace only if the element's prefix matches the namespace attribute's prefix.

That includes the special case of the default namespace when the attribute does not define a prefix, in which case any element that is in scope and without a prefix is in that namespace. Setting the namespace as the default namespace is usually more convenient when creating an entire document in a single namespace, as is typically done with DocBook.

If you put a default namespace attribute on the root element, then the namespace is in scope for all elements, and all elements without a prefix are in the namespace. Compare these two equivalent documents, one using the default namespace and the other using a prefix:. Of course, just adding a namespace declaration may not make a DocBook 4 into a valid DocBook 5 document.

There are differences in elements and content models between the two versions, so some fixup may be required. Fortunately, a guide and conversion stylesheet exist to help transition DocBook 4 documents to DocBook5. First consult DocBook V5. It provides guidelines for conversion and describes the db4-upgrade. If you are assembling modular DocBook files into larger documents as described in Chapter 23, Modular DocBook files , then each of the included files must also have the DocBook namespace declaration on its root element.

If not, then the stylesheet will report that the module's root element has no matching template. Another major difference between DocBook 4 and DocBook 5 is the schema language. An XML schema defines the element and attribute names, and the rules for how they are combined into documents. Its major advantages for use as the official DocBook schema include:. It allows the content model of an element to be different when that element is in different contexts. It is quite easy to customize in order to extend or subset the DocBook schema.

These other versions contain the same element and attribute names. However, in each of these other versions, certain features of the schema are lost. For example, the DTD version does not permit an element to have different content when the element appears in different contexts. In DocBook 4, only specialized elements are used for creating links within and between documents.

In DocBook 4, you can use xref or link with linkend attributes to form links within a DocBook document, you can use olink to form links between DocBook documents, and you can use ulink to form an arbitrary URL link. In DocBook 5, almost all elements can be used as the basis for a link. That's because almost all elements have a set of attributes that are defined in the XLink namespace, such as xlink:href.

For example, you can turn a command element into a link that targets the reference page for the command. That standard says that any XML element can become the source or target of a link if it has the universal XLink attributes on it.

Because these attributes are in their own namespace, they do not interfere with any native attributes declared for an element. This is similar to the DocBook 4 link and xref elements. The link and xref elements were retained in DocBook 5. This is similar to the DocBook 4 ulink element, which was removed in DocBook 5. Instead of ulink , use a link element with a URL in its xlink:href attribute.

An olink-style link from any element can be formed using two attributes. The olink element itself is retained in DocBook 5. See Chapter 24, Olinking between documents to learn more about DocBook olinks. At the same time, the familiar DocBook linking attribute linkend has also been added anywhere an XLink can be used. The linkend attribute is limited to linking to an xml:id target within the same document.

The universal linking mechanism enables you to create logical links between any two DocBook elements. However, such logical links may or may not be expressible in formatted output. For example, if you put an xlink:href on an inline element, then the text of the inline element can become clickable link text in the output. However, if you put an xlink:href attribute on a block element such as section , then it is doubtful that making all the text in the section into a clickable link will be useful.

The DocBook stylesheets currently only handle xlink:href on inline elements for this reason. If you want to express linking from a block element, you will have to customize the stylesheet to do so, perhaps by putting a clickable icon in the margin.