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.🙂

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 18 May 2009, in Confluence, open standards, technical writing, wiki, xml and tagged , , , , , , , , , , , , . Bookmark the permalink. 11 Comments.

  1. Hi there Sarah,

    The company where I work recently upgraded to Confluence v3.0 and I’d like to know if the Scroll plugin provides users with more functionality regarding PDF export than the new engine in Confluence v3.0.

    Rgds,
    KalpaK

  2. Hallo KalpaK
    I haven’t done a comparison of the PDF export in Confluence 3.0 with the Scroll Wiki Exporter PDF. I do know that Confluence 3.0 offers more customisation of the PDF output at this stage, via CSS style sheets. But both Confluence and the plugin are under active and rapid development at the moment. For both of them, the PDF export is at its initial stages and there are definite plans for improvement in future releases.

    I have forwarded your request to some people who may know more. If they send me any information, I’ll post it here. With luck they’ll do that themselves.

    When I get a chance, I’ll do a comparison myself and write about it too🙂

    Cheers
    Sarah

  3. Hi KalpaK, Hi Sarah,

    The PDF export provided by Confluence 3.0 is a great step forward compared to earlier versions. However, Scroll still has some important features, which the Confluence PDF export doesn’t have (and some which it will never have).

    Scroll converts Wiki pages into a semantic model and uses this semantic model to export to formats such as DocBook and PDF. The PDF export provides a lot of customization features, as it is based on the DocBook stylesheets – title pages, custom formatting for admonitions, headings, indents, fonts, etc. There is a whole book about these features. Similar to the Confluence PDF export, these features aren’t currently available through the UI (you need hand-coding), but Scroll 1.1 will provide a UI for defining/customizing themes and allow to upload theme plug-ins.

    Because of Scroll’s semantic model, other export formats such as DITA, Forrest, WordProcessingML, etc. could be added. At present, we haven’t implemented these export formats, but already provide extension points for plugging in this kind of functionality (let us know, if you need more information about this).

    The only disadvantage of Scroll’s PDF export is the table support (auto column resizing), which Apache FOP 0.95 doesn’t support yet. Using a commercial FOP processor solves this problem.

    Feel free to contact me/us anytime if you have further questions.

    Cheers,
    Tobias

    • Hello there Sarah and Tobias,

      Thank you so much for your prompt reply and all these precious details.
      I know of DockBook but I’m more interested in the DITA approach😉

      Now, as far as PDF export functionality in general is concerned, I don’t feel I need all the features available from a DocBook stylesheet to output my wiki pages towards a paper-ready format but…we’ll see.

      I’ll let you know if I stumble upon issues using Confluence 3.0 PDF export functionality.

      BTW, is there a page I can watch regarding a “roadmap” listing all what Atlassian will be implementing to enhance even more its PDF export ?

      Thank you so much again for you help.
      KalpaK.

  4. Hallo again KalpaK

    I’ve had a word with our development team. There isn’t a published roadmap for the Confluence PDF functionality, apart from our issue tracker (more below). At this point, we’ve had very little feedback about the new PDF export. No further improvements are currently planned for Confluence 3.1.

    So the message is: We would welcome your feedback with open arms🙂 If you have any suggestions (and I’m sure you do😉 ) please would you file an issue on our issue tracker at jira.atlassian.com. If you don’t yet have a user ID there, you can just sign up for one. Also, if you see any issues there that you’d like to keep an eye on, you can add yourself as a “watcher”. You will automatically receive feedback on any issues you raise, as well as those you watch or comment on.

    It’s great having your comments!
    Cheers
    Sarah

  5. Hello Sarah,

    My company software is in continuing improvement and so is our documentation.

    Most of the time, changes between two versions concern screenshots, links, sentences. It is very rare that whole pages are modified. A section may appear or disappear.

    The versioning has been managed in two ways:

    • Copying all the pages of a particular documentation then modifying some pages. The issue is that sometimes we do have to replicate the modifications on several versions. It is quite fastidious and can be source of errors.

    • Using the macro include. We have defined a set of pages as the master documentation. Then, the various versions are a hierarchy of pages that include the master pages or create new ones to replace the section, images that have changed. This method becomes very difficult to manage when too many versions co-exist.

    In both cases, all pages are labeled with the versions. A page has often several such labels.

    I think we will a single sourcing system in the future but right now we are using Confluence v3.0.

    I am trying to find a better way to manage the versioning.

    Do you have suggestions that facilitate the versioning management?

    Do you know if some plug-ins exist to either copy a whole set of pages (solution 1) or copy a particular page in several spaces?

    Do you know if some plug-ins exist to manage a complex hierarchy?

    It may have documentation writing rules which make easier the versioning management.

    For instance, we want to obtain quickly a copy of the older version hierarchy, where we can add modification and change terms version 5.3.X by 6.0.X.

    Any help is welcome

    Rgds,

    JACQUOT Aurélien

  6. Hallo Jacquot

    Yes, version management is tricky on a wiki😉

    We’ve decided to copy the entire documentation set for each version, so that our customers and developers can have a unique documentation set that relates specifically to their version of the software. We use a separate space for each version. As you point out, that does mean that we occasionally need to apply the same change across multiple versions of the documentation. But that doesn’t happen often. We have also restricted the editing rights on the older versions, so that only the tech writers can update them. This means we have fewer spaces to monitor. All Atlassians have editing rights on the current documentation spaces.

    We use the Copy Space plugin to create the archive spaces for each product release. Here’s the info on the plugin:
    https://plugins.atlassian.com/plugin/details/212
    It’s not supported by Atlassian, but we use it🙂

    A couple of blog posts have more information on how we do it:
    https://ffeathers.wordpress.com/2007/11/17/wiki-docs-release-management/
    https://ffeathers.wordpress.com/2009/05/23/aodc-day-3-delivering-documentation-on-a-wiki/

    Also, here’s a new page that you may find useful, containing links to external blogs that have good information. Some of the links are about doing tech docs on Confluence:
    http://confluence.atlassian.com/display/DOC/Tips+of+the+Trade

    I haven’t seen any tools that automate the updating of multiple versions at once.

    I hope this helps! We’ve found it to be the cleanest way of managing versions, both from our own point of view as tech writers and from the reader’s point of view.

    Cheers
    Sarah

  7. I am using Confluence 4.0. Once I have installed the plugin, I don’t get the option when I hover my mouse on the Tools Option. I don’t see the Scroll Wiki Exporter. Is there something wrong I did? I also tried just using it on one space and followed the directions too.. I’m not sure now, so should I uninstall the plugin and instal the plugin again?

    Jerry

    • Hallo Jerry
      Ah Confluence 4.0! I hope you’re enjoying the new Confluence!

      It looks as if the Scroll Wiki Exporter plugins are not yet compatible with Confluence 4. I’ve had a look at the plugin details pages for the Scroll Wiki Exporter plugins. The K15t Software team have split the plugin into separate plugins, one for each export format. There is currently a page for the PDF exporter:
      https://plugins.atlassian.com/plugin/details/7019
      That page indicates that the plugin is not yet compatible with Confluence 4.0.

      There isn’t yet a page for the Scroll Wiki DocBook exporter plugin, so I think it’s not yet compatible either. You could try asking the K15t Software team when they plan to release new versions of the plugins. Their contact details are on the above plugin page.

      Cheers, Sarah

  8. Irene SoftSolutions!

    Hello Sarah,
    my company has only recently begun to use Confluence, where we are importing all our documentation. Within it, there are also some user manual and single pages that we would export to PDF in order to deliver them to our customers. So we need specific templates for manuals and others for single pages.
    I tried to use PDF stylesheet and layout, but, maybe for my little knowledge, I found it very difficult.
    My question is: Is Scroll PDF plugin the only solution? Indeed, it costs a lot.
    Can you indicate me any examples of printed pages/manuals with instructions? According to me, Confluence documentation isn’t so exhaustive.

    Thank you for your attention.

    Regards

    Irene

    • Hallo Irene

      As far as I know, the Scroll PDF add-on is the only one that supplies what you need. I’ve had a look on the Atlassian Marketplace, and could not find any other add-ons that fit the bill.

      I’d recommend that you get in touch with the team at K15t Software, who produce the Scroll add-ons. They’re really great, and will help you get the best solution for your documentation:
      http://www.k15t.com/

      I hope you enjoy Confluence!

      Cheers
      Sarah

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: