Blog Archives

STC Summit day 1 – Why not DocBook?

I’m attending STC 2012, the annual conference of the Society for Technical Communication. It’s Monday morning, the first day of general sessions. The weekend has been packed with pre-conference events and socialising too.

The first session of the morning is by Richard Hamilton of XML Press. Richard is the publisher of my book, and I’ve just met him in person for the first time. Up to now, we’ve corresponded by email, wiki and Twitter. It was great to shake his hand.

Why not DocBook?

That’s the title of Richard’s session: “Why not Docbook?” He covered the following points:

  • The schema, and what’s new and what’s happening
  • The tools and documentation
  • The DocBook community

Discussing the schema, Richard emphasised its simplicity. As long as something is familiar and organised, it works. And DocBook is essentially that. The structure is organised around creating a book. You can also generate a number of other formats, such as slides, text, HTML, EPUB, and more.

Richard gave us an informed look into the DocBook schema and its structure. I took just a few notes:

  • Using namespaces, you can embed chunks of other XML into DocBook, such as SVG and MathML. This is really powerful and useful.
  • The latest version of DocBook uses the Relax NG schema language. To customise XML, you often have to do a lot of stuff. But using Relax NG in DocBook, it’s simple – just 2 lines of code.

Next Richard moved onto the tools and documentation available for DocBook, and why they are a plus point for DocBook usage. He discussed Schematron, a language for making assertions about patterns found in XML documents. For example, if you want to say that a footnote cannot contain another footnote, you would use Schematron. Most XML IDEs will apply the rules defined in a Schematron.

Another selling point of DocBook is its stylesheets. Richard recommends a book called “DocBook XSL: The Complete Guide”, by Bob Stayton.

Richard listed a number of tools, including Confluence wiki which has a plugin that allows you to generate DocBook from the wiki content. The plugin is developed by K15t Software.

In the third part of his presentation, Richard talked about the DocBook community. It consists of people using DocBook, and also all the people who can help out. O’Reilly Media do a lot of work in DocBook, and are doing more and more. XML Press is another publisher that uses DocBook as core to its processes. There are a number of open source projects that use DocBook.

On the support side, there are a couple of mailing lists that are very active and very well covered. For example,people will respond to questions about a particular customisation by giving a chunk of code that does the job.

In summing up, Richard says that in terms of generating different output formats, DocBook is number one. And in terms of support, you can’t do better either.

After the presentation, Richard answered a number of indepth questions from the audience. Thanks for an interesting session, Richard, and a great start toMonday at STC 2012.

DocBook export and import round trip with Confluence wiki

This is exciting news for technical communicators. We can export content from Confluence wiki to DocBook and then import it back into Confluence. I’ve just tried it using the Scroll Wiki DocBook Exporter and the RedHat DocBook Import for Confluence.

As you may already know, I’ve written a book. πŸ˜‰ The book is about Confluence, and the content is on a Confluence site. So I decided to try exporting the book to DocBook XML and then importing it back into a different Confluence space.

In summary:

  • I’m running Confluence wiki, version 3.5.3.Β  (The DocBook Import plugin does not yet support Confluence 4.)
  • I used version 2.0.2 of the Scroll Wiki DocBook Exporter, a Confluence plugin from K15t Software, to export the content of my book to DocBook XML.
  • Without making any changes to the XML, I used version 1.1.1 of RedHat’s DocBook Import for Confluence to import the content back into Confluence, in a new space that I had created for this purpose.
  • There were a few hiccups, but basically it worked well.

A friendly word of warning: The DocBook Import plugin is unsupported. It was originally created for the JBoss Community Project Documentation Editor, and the developers decided to make it publicly available, free of charge. You can read about the plugin and ask questions on the JBoss Community site.

Exporting the content to DocBook XML

I used the Scroll Wiki DocBook Exporter, a Confluence plugin from K15t Software, to export the content of my book to DocBook XML. My earlier post gives quite a bit of detail on how to use the plugin: Writing a book with DocBook and a Confluence wiki. This screenshot shows the settings I used to export the pages from Confluence:

Exporting from Confluence to DocBook XML

A note: I had to use the template called “Book using preface and chapters“. When I chose the template “Book using preface, parts and appendix“, the import pulled in only the home page and the appendices. The explanation lies somewhere in the DocBook formatting, but I don’t know the details.

Importing the XML back into Confluence

I installed RedHat’s DocBook Import for Confluence plugin onto my Confluence site. Then I added a new space in Confluence, and went to the home page of that new space. The plugin adds an option to the “Tools” menu called “JBoss DocBook Importer“:

DocBook import option in Confluence Tools menu

Clicking that option invokes the importer configuration page:

DocBook Import configuration page

As we who know and love Confluence are aware, you cannot have two pages with the same name in a Confluence space. The DocBook Importer accepts a prefix that it will use to resolve such conflicts. But on my first attempt, I did not give it any prefix. I knew that all the page titles in my book were unique, so I thought the import would be good. It turned out that there was a duplicate page title, because I had used a heading level 1 to highlight the book title, and had given the page the same name as the title.

The importer gave me an error message, and I supplied a rather unimaginative prefix “123”.

Message requesting prefix to resolve duplicate page names

This time everything went smoothly. In the following screenshot, you can see the success reported by the importer on the right, and the newly-created table of contents in the left-hand panel:

Import successful

Results

Success!

  • All the pages are there, with all content present.
  • The images are all present.
  • Tables are correctly formatted. My content includes only simple tables.
  • List formatting looks good.
  • Bold and italic formatting are good.
  • Links are good.

One of the book's illustrations by Ryan Maddox

The above screenshot shows one of the illustrations in the book, created by Ryan Maddox and reproduced here with his permission.

A few hiccups

Some things will need fixing, either manually after each import or perhaps in a future version of the importer plugin:

  • The images are larger than on the original pages.
  • URLs printed on the page have acquired URL encoding rather than retaining the human-readable form.
  • The Scroll Wiki DocBook Exporter plugin allows you to add information for a book index and footnotes, via special macros. The reimported pages print the content of the index or footnote entry on the page itself. For example, in the screenshot below I have highlighted an index entry at the top of the page.

Another page imported from DocBook

Thanks to the teams at K15t Software, Red Hat and the JBoss Community for these two plugins!

Using the plugins in earnest

Richard Hamilton, at XML Press, and I have used the Scroll Wiki DocBook Exporter to produce my new book. I haven’t used the DocBook Import, other than to try it out for this blog post. I’d love to know if you’re using either of these two plugins in your documentation or content management procedures. Do you have any stories or tips to share?

Writing a book with DocBook and a Confluence wiki

We’re in the final stages before sending my book off to the printers. Exciting! While we wait, let me tell you a bit about how the publishing team and I have produced the book. We’re using a Confluence wiki and DocBook XML.

Cover of "Confluence, Tech Comm, Chocolate"Here’s our process in brief:

  • Plan, write and review the book on a Confluence site.
  • Use theΒ Scroll Wiki DocBook Exporter to convert the content to DocBook XML.
  • Use DocBook XSL-FO style sheets to create a PDF file for sending to the printers.
  • Use XSL to generate ebook formats too.

This post is about writing and reviewing the book on the wiki, and converting the Confluence content to DocBook XML – the first two points in the list above. Richard Hamilton, at XML Press, is the expert on the further DocBook processing.

A bit about the book

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. Details are at XML Press. It is all about developing technical documentation on a wiki, with a focus on Confluence wiki. And just to be ultra meta, I’ve written the book on a Confluence site. Dogfooding FTW!

Writing, planning and technical review on the wiki

Richard Hamilton and I have spent the last nine months on a Confluence wiki site. We kicked off our planning there in May 2011. Since then, I’ve spent around 400 hours writing the content on the wiki. Ryan Maddox, our illustrator, has uploaded his images onto the wiki. For two weeks in early December, the technical reviewers joined us there too – six knowledgeable and enthusiastic people:

The wiki was abuzz with review comments, opinions and counter-opinions, laughter and chat.

Now it’s gone a bit quiet while Richard and I work on the last stages of book production. When we launch the book, we’ll open up the wiki site too. You’ll be able to join us there and make it buzz again. πŸ™‚

DocBook for the publication processes

DocBook is an XML standard for documents, developed by O’Reilly as a means of making their publishing process more efficient. It is now an open standard maintained by OASIS.Β  Richard Hamilton, at XML Press, uses DocBook XML to publish a range of books on the subject of technical communication. Using a customised set of the open source XSL style sheets for DocBook,Β  Richard can create HTML, PDF (through XSL-FO), EPUB and other epublishing formats from the DocBook source.

Converting content from Confluence wiki to DocBook XML

So, I’ve finished writing the book and the reviewers have worked their magic too. It’s all on a Confluence wiki. The content is stored in the Confluence database in wiki format. How do we get it to DocBook so that Richard can create the print and ebook formats?

Enter the Scroll Wiki DocBook Exporter.

Scroll Wiki DocBook Exporter is a plugin for Confluence, developed by K15t Software. (A plugin is a small piece of software that extends the functionality of the wiki. It is similar to an add-on for a web browser.) Once you have installed the Scroll Wiki DocBook Exporter on your Confluence site, you can export a page, a set of pages or an entire space, to DocBook XML.

How to use the Scroll Wiki DocBook Exporter

The first thing is to add the plugin to your Confluence site. You need to be a Confluence system administrator, then you can install the plugin in the usual way:

  1. Log in as a Confluence system administrator.
  2. Choose “Browse” > “Confluence Admin” > “Plugins” > “Install”.
  3. Type “scroll wiki docbook exporter” into the search box and click “Search”.
  4. Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
  5. Click “Install Now”.

See the Confluence documentation on installing plugins.

You will need a license key from K15t Software. They provide a free evaluation license that gives you full functionality for 30 days.

Once the plugin is installed, a new option appears in the Confluence “Tools” menu, allowing you to export the content to DocBook format.

  1. Go to the page that you want to export. If you want to export a set of pages, go to the parent page of the set.
  2. Click “Tools” > “Export to DocBook”.
  3. Adjust the options in the dialog that pops up:
DocBook Exporter dialog

Scroll Wiki DocBook Exporter

When you are ready, click “Start Export”. The plugin will create a zipped file containing the DocBook XML and attachments, and will offer the file to you for downloading.

A sample of the output

Here is one of the book’s pages on the wiki:

Book's front page on the wiki

Front page of the book on the wiki

And here is an extract of the DocBook XML:

<?xml version=”1.0″ encoding=”UTF-8″?>
<book xmlns=”http://docbook.org/ns/docbook&#8221; xmlns:xlink=”http://www.w3.org/1999/xlink&#8221; xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance&#8221; xsi:schemaLocation=”http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd&#8221; version=”5.0″ xml:id=”scroll-bookmark-1″>
<info>
<title>Confluence, Tech Comm, Chocolate</title>
</info>
<part xml:id=”scroll-bookmark-2″>
<title>Confluence, Tech Comm, Chocolate</title>
<chapter xml:id=”scroll-bookmark-3″>
<title>A wiki as platform extraordinaire for technical communication</title>
<para>By Sarah Maddox</para>
</chapter>
</part>

[SNIP]

<index />
</book>

Index, footnotes and figure captions

The Scroll Wiki DocBook Exporter supports these too. The plugin adds a number of macros to Confluence, which you can use to mark up the index entries, footnotes and figure captions.Β I’ll write another post with the details. I’m sure many people are agog to know how this works. πŸ˜‰

Working with K15t Software and XML Press

Richard and I have worked on this project with Tobias Anstett and the rest of the team K15t Software.Β  They are great people to work with: knowledgeable, enthusiastic and energetic. As far as I know, this is the first time anyone has written a book on Confluence for publication via DocBook XML. We have added new functionality to the plugin, especially for the index and footnotes, adapting and tuning as we go.

Thank you all. It’s exciting to help perfect a plugin that many other authors and technical writers will be able to use.

And I can’t wait to get my hands on a copy of the book!

Scroll converts wiki to DocBook and PDF

K15t Software have just announced release 1.0 of Scroll, a Confluence plugin that converts wiki documentation to DocBook and PDF. I’ve been interested in this project since the early beta days and I’m excited for the K15t guys about the functionality Scroll offers already and about their plans for even more awesome developments.

First things first: You’re probably wondering why they’re called “K15t Software” πŸ˜‰ It’s because one of the developers and company founders is Stefan Kleineikenscheidt. I guess that most people, like me, go cross-eyed upon encountering his surname. So he uses “K15t”, in the proud tradition of “i18n” and other such abbreviations. Another K15t Software developer is Tobias Anstett, fondly known as “t11t”. During Scroll’s beta period we’ve had some good conversations via Twitter, blogs, video conferencing and email.

History in the making

The guys founded K15t Software as a company just a few weeks ago. If you’re a technical writer, you’ll like their mission statement:

“K15t Software is a small development shop from Stuttgart, Germany. Its mission is to build useful software products with the focus on tools for wiki-based documentation.”

It all started five years ago, when Stefan lodged a request for a DocBook export from Confluence wiki. The request is on the Atlassian JIRA site — CONF-762. A DocBook exporter is not on the roadmap for core Confluence, so Stefan and the team decided to build one as a plugin. And the rest is history! Well, it’s the future too, because K15t plan to keep adding features to Scroll.

How does Scroll work?

It’s a plugin (add-on) to Confluence. If you have administrator permissions on your Confluence site, you can install the plugin as described in the Scroll Installation Guide.

Once it’s installed, the “Scroll Wiki Exporter” option will appear in your Confluence menu. Here’s a screenshot of the option in Confluence 2.10. I’m on a wiki page called the “Crowd User Guide” and have opened the “Tools” menu on the right:

Scroll converts wiki to DocBook and PDF

Scroll converts wiki to DocBook and PDF

When you choose the “Scroll Wiki Exporter” option, you get a screen with some tabs where you can choose either PDF or DocBook output and set some formatting options. On the “Document Information” tab you can set the document title, author and version. Scroll will provide default values based on the wiki page, but you can change them:

Scroll converts wiki to DocBook and PDF

Scroll converts wiki to DocBook and PDF

The “Page Tree” tab shows you a hierarchical view of the pages you are about to export. The top level of the tree is always the page you were on when you clicked the “Scroll Wiki Exporter” option. The export will include that page plus all its sub-pages and their sub-pages etc. At the moment, “Page Tree” tab is view only. Scroll may allow re-ordering in a future release.

Next is the “Formatting” tab. Here’s where you choose either PDF or DocBook. If you choose PDF, you can select a theme, language, etc. Scroll 1.0 has two themes available. In future releases, K15t Software plan to provide more themes and also more options for customisation.

Scroll converts wiki to DocBook and PDF

Scroll converts wiki to DocBook and PDF

The Scroll documentation tells you more about the formatting options.

On the “Advanced” tab, you can tell Scroll what to do if it encounters some wiki markup or macros that it doesn’t recognise.

Scroll exports wiki to DocBook and PDF

Scroll exports wiki to DocBook and PDF

When you’re ready, you kick off the export. Scroll will show its progress and then present you with a file for downloading.

Scroll exports wiki to DocBook and PDF

Scroll exports wiki to DocBook and PDF

If you chose to export as PDF, the output will be a PDF file. If you chose DocBook, it will be a zip file containing the DocBook 5 XML and all images and other attachments.

Some comments from me

I’ve really enjoyed my contact with Tobias and K15t. They’re passionate about their software, passionate about Confluence wiki, and keen to hear feedback. Here are some useful titbits from my experimenting with Scroll:

  • Note the {scroll-ignore} macro. You can put it onto your wiki page to tell Scroll not to export a particular chunk of text/content.
  • Scroll supports a number of wiki markup elements and macros. The Scroll Authoring Guide tells you how to write your text for best Scroll results.
  • Scroll exports DocBook version 5.0.
  • The “Scroll Quick Help” tips on the right of the export screens (see above) are useful and concise.
  • It’s really useful to be able to determine error handling, telling Scroll what to do when it encounters some wiki markup or a macro that it doesn’t know what to do with. See the “Advanced” tab described above.
  • In the PDF export, the “Simple Documentation” theme is neat and attractive.
  • For PDF, Scroll 1.0 has two themes available. In future releases, K15t Software plan to provide more themes and also more options for customisation. They’re also planning to allow pluggable themes, so that developers can create their own themes for Scroll.
  • I’ve suggested an addition to the Scroll documentation, to provide more information about the DocBook XML produced. The Scroll team have added this to their “to do” list.
  • The section on nesting of headings in the Scroll documentation explains why your heading levels may sometimes be different to what you expect.

Some comments from Giles

Giles Gaskell is a technical writer and colleague at Atlassian. He’s had extensive experience with DocBook, so he’s very interested in the Scroll plugin for Confluence too and I’ve been delighted to have his help with the plugin analysis. Here are Giles’s comments:

  • I really like the XML indenting that Scroll generates. It makes the XML output very readable via a standard text editor. I’ve worked with several XML editors in the past that force you to use their products to read/edit your XML content, since they either implement their own strange XML indenting or remove all white space > 1 character in length, in their XML output files.
  • It’s great that the version of DocBook XML exported by Scroll is 5.0. There are several processing advantages in DocBook XML 5.0 (via the RELAX NG schema) over what’s available in previous versions of DocBook XML (which are based on DTD schema only). Furthermore, it seems that RELAX NG is the way DocBook XML processing is headed.
  • I validated both DocBook XML exports using my own installation of jEdit and both were without any errors πŸ™‚
  • Scroll does not add a document type declaration at the top of the XML output. It seems that DocBook XML 5.0 files which make use of RELAX NG-based processors typically do not possess a document type declaration. Likewise, it seems that DocBook XML 5.0 output without a document type declaration can only be processed by tools which are RELAX NG-compliant. Hence, it might be useful to have an option in the Scroll Wiki Exporter to add a document type declaration to the XML output, so that XML processing tools which verify XML against DTDs only can process these exports. [Giles would be very interested to hear any comments on this point from other DocBook users.]
  • It might also be worth providing an option to choose the version of DocBook XML exported — 4.0, 4.5 or 5.0. However, k15t might consider conducting a brief feasibility study on this first as I suspect integrating this feature would require a fair bit of work and some understanding about the differences between each version of DocBook. The main area of demand for this feature would be customers who have an existing/legacy tool setup that manipulates DocBook XML 4.x content, but do not have resources to upgrade their entire system to DocBook XML 5.0. DocBook XML 5.0 was only officially released in January 2008, so I suspect many DocBook XML customers would still be using DocBook XML 4.x.
  • Regarding the use of the <article> root element as opposed to <book> in the DocBook XML output: I believe this is an advantage, as it gives the author more flexibility to structure their books. The <book> element encapsulates information about a book’s content at a higher level than what is contained within an <article>. For example, an author may want to export multiple DocBook <article>s from a Confluence installation. These might be sourced from a variety of Confluence spaces or subtrees. They might then wish to combine these exported DocBook XML <article>s into a single DocBook <book>, using their own DocBook XML editor. If Scroll exported to a DocBook <book>, this would not be possible without additional XML processing.

Giles is also discussing a couple of minor points about the DocBook XML, such as the fact that each <link> element defines its own xlink namespace, and the production of the <?linebreak?> processing instructions.

Try it out yourself

You can either download the plugin for evaluation from the K15t Software site and try it on your own Confluence wiki, or you can use their demo Confluence site to see the pages already there, create your own pages, and then export them to DocBook or PDF. Awesome!

That’s all folks

Both Giles and I enjoy working with the K15t Software guys. They’re very quick to respond to feedback and I’m sure they’d be delighted for more input from other technical writers. πŸ™‚

A Confluence-to-XML export engine in the making

Imagine if you could use a wiki’s editing and collaboration tools to create your documentation, and then export your complete documentation set to a recognised XML format such as DocBook or DITA. From the XML, you could use your existing tools to transform the documentation to the various formats required by your different audiences or put it through your normal publication and archival workflow.

K15t & Friends are working on the Scroll Wiki Exporter, which exports Confluence wiki spaces and pages to DocBook and PDF. I’ve tried the beta DR03 version of the product and I think it has a lot of potential.

A friendly note of warning: The Scroll Wiki Exporter is currently in beta release. It is a Confluence plugin, developed by a third party. It is not part of the core Atlassian Confluence product. If you want to try it out, you should install the plugin into a test installation of Confluence.

Scroll Wiki Exporter is a Confluence plugin that converts a set of wiki pages to DocBook or PDF. You can choose to export an entire space or any page tree (hierarchical set of documents) within a space.

Screenshot after installation of the beta plugin, showing the Scroll Wiki Exporter option in the Confluence Tools menu and Scroll’s Export Options page:

A Confluence-to-XML export engine in the making

What can it do right now?

The software is in an early beta phase, so there are still some limitations on what it can do. The Scroll development team are adding new capabilities with each new beta release.

Scroll Wiki Exporter converts Confluence wiki spaces and pages to DocBook and PDF. Confluence itself supports a number of formatting options and macros. When you run Scroll Wiki Exporter, it analyses the wiki pages and displays warnings of any formatting it will not be able to reproduce. You can choose to ignore the warnings and do the export anyway. The beta version is best used with Confluence 2.8.2. The Scroll team will be working on compatibility with other versions for a future release.

For those participating in the beta testing, the Scroll team have provided some excellent documentation. It is clear and well structured, simple and to the point.

The documentation is itself written on Confluence and then converted to PDF using Scroll Wiki Exporter. It is also provided as the sample content (i.e. a Confluence space) for beta testers to use when testing the software. Multi-purpose documentation at its best πŸ™‚ There are a few grammatical errors, but basically the team have provided a very solid guide to getting Scroll Wiki Exporter up and running.

I’ve used the Scroll Wiki Exporter to generate PDF and DocBook outputs, using the sample space provided with the beta documentation. The DocBook output passes XML validation, and the PDF output looks good. I have also tried the Scroll Wiki Exporter with the Crowd documentation space, but there were a few hiccups because of the formatting and macros used in that space.

Some interesting aspects

Scroll Wiki Exporter allows you to choose a theme for your generated PDF or XML. The beta version I tried has only the default and Scroll themes. But the idea is that you will be able to add your own themes, defined in FOP (Formatting Objects Processor).

You can also choose to export a whole space, or a page tree starting from a selected page. At the moment, Scroll Wiki Exporter hooks into Confluence’s own page tree functionality. So when you re-arrange pages in the tree, you are actually re-arranging them in the Confluence space too. In a future release, there will be an independent means of organising pages just for the export.

Because I don’t use DocBook in my day-to-day documentation procedures, it was not easy to put the generated XML through its paces. It would be great if other technical writers can try it out too.

Scroll’s plans for the future

The Scroll team intend to provide conversion to DITA in a future release. At the moment, they are refining the DocBook capabilities. Once the framework is well established, they say, it will not be difficult to produce other formats such as DITA.

Calling tech writers

As someone who is enthusiastic about technical documentation on a wiki, I think the Scroll Wiki Exporter is a great initiative. The ability to export Confluence documents to a recognised XML format is a much-requested feature. See the existing requests for DocBook (CONF-762) and DITA (CONF-5571) support. This requirement also comes up often in forums, interviews and technical documentation conferences.

Technical writers may want to keep an eye on this one. The Scroll team will be issuing a public beta release within the next couple of months. Especially if you are already using DocBook in your day-to-day documentation procedures, your feedback would be really useful to the Scroll team. Let’s jump in there and give them as much feedback as we can. And I’d be very interested in your comments too:)

%d bloggers like this: