ForgeRock doc tools 2.1.5 released

ForgeRock doc tools 2.1.5 is now available. This is a maintenance release, adding an option to stop the build after pre-processing DocBook XML sources and fixing some bugs. Thanks to Gene and Chris for their fixes, and to Lana for testing.

See the release notes for details about what has changed.

You do not need to make any configuration changes to move to this maintenance release from 2.1.4, except to update the version number in your POM.

See the README for more about how to use the doc tools.

Towards automating tests for examples in docs

LogoTM_verticalbigForgeRock documentation includes many (but never enough) examples. When reading about editing configuration files, you expect to see excerpts of the configuration files. When reading a developer guide, you expect to see code samples. When following a tutorial that involves the command line, you expect to see command line examples for each step. Most of us figure things out a lot more quickly given both a good explanation and also a working example.

Trouble is, examples can go stale and break when the software changes. Unless you have a test harness, this sort of breakage happens silently. If the doc source contains only example input and output, it can also take time to set the software up in order to reproduce the conditions for the example. And yet readers hardly want to search for the relevant part of the example in a mass of scaffolding code and configuration.

Some of that work can be done behind the scenes by quality engineers. They can set up a context that allows them to test examples in the documentation, and indeed some of the quality engineers at ForgeRock like Jean-Charles and Laurent are already starting to solve the problem that way. It would be better for them and for everyone else, however, if it were a lot easier to prepare the context, and not something separate from the examples.

So it would help both to include only the salient excerpts in the doc but also to link to all the material needed to set up the software to try or to test the examples. (Of course everything must be versioned alongside the software. If OpenAM changes between versions 11 and 12, then the examples must change as well.)

With XInclude and JCite support, this is already technically possible for XML and Java samples. We use JCite in the OpenDJ LDAP SDK Developer’s Guide to quote from code samples tested as part of the build. But throughout the docs we have samples that involve neither XML nor Java code.

For all the other samples, we are adding two things to the next major release of the forgerock-doc-maven-plugin: copying arbitrary resources into the documentation, and quoting from any text-based file.

In the next major version, copying arbitrary resources will involve setting <copyResourceFiles> to true. If the resources are not under src/main/docbkx/resources, you will set this by using the <resourcesDirectory> setting. There are some notes on this in the draft README for the nightly build version of the plugin. This way docs can include long example scripts and other files, without including the entire text in docs.

Quoting from any text based file will depend on a new plugin called xcite-maven-plugin. The basic idea is as follows. In the file you want to cite, you either add nothing (if you want to quote the entire file) or you add markers (if you want to quote only part of the file). The markers are just strings. So they could be in comments, but they could also be part of the text. Then in the file where you want the quote to appear, you add a citation, à la JCite. For example: [file.txt:start marker:end marker]

Suppose file.txt looks like this:

# start marker
This is a great quote & stuff.
# end marker

Then in your book.xml file, you might have the citation:

<para>[file.txt:start marker:end marker]</para>

After you run the plugin, the quote ends up in your book.xml file:

<para>This is a great quote &amp; stuff.</para>

The examples above are overly simplified. But you can imagine how this might work to include excerpts of a long shell script that involves some setup and configuration, then a number of example commands.

More to come…

ForgeRock doc tools 2.1.3 released

ForgeRock doc tools 2.1.3 is now available.

This is a minor maintenance release, mainly of the default branding.

As mentioned in the release notes, this release brings one improvement and two bug fixes:

  • DOCS-72: Improve widow and orphan control in PDF
    You can now use the processing instruction <?hard-pagebreak?> between block elements to force an unconditional page break in PDF (and RTF) output. The processing instruction has no effect on HTML output.
  • DOCS-162: <replaceable> tags within <screen> tags have no effect in the HTML
    The <replaceable> text now shows up in bold+italic font.
  • DOCS-173: Link text too dark in top-right banner showing latest release

No configuration changes are required, except to update the version number in your POM. See the README for more about how to use the doc tools.

ForgeRock doc tools 2.1.2 released

Thanks to Gene Hirayama and Laszlo Hordos for their contributions, and to Lana Frost for testing. ForgeRock doc tools 2.1.2 is now available.

This is a maintenance release of the Maven doc build plugin, the default branding, and the common content. No configuration changes are required, except to update the version number in your POM. In order to benefit from improvements to the PDF cover pages, however, you will want to add logos and update the authors list to include a corporate author.

For details about fixes, enhancements, and known issues in the doc tools, see the release notes.

ForgeRock doc tools 2.1.0 released

ForgeRock community logo Today we released ForgeRock doc tools 2.1.0. This maintenance release includes a couple of new features, a few improvements, and some bug fixes. See the release notes for details.

As described on the ForgeRock developer community Wiki, the Maven doc build plugin relies on a lot of great open source technologies to generate output. A little bit below the tip of the iceberg, we stand on the shoulders of these giants:

Big thanks to all the maintainers of these tools, and to all the people answering questions on their mailing lists. Recursive thanks to all the giants holding up these projects, too. 🙂

When you upgrade to use the latest plugin, also take these compatibility changes into account:

  • Add a <projectVersion> setting to your configuration when executing forgerock-doc-maven-plugin (required)
  • Update <screen> examples to use continuation characters when folding user input lines, and make use of <userinput> and <computeroutput> markup (optional). Here’s an example:
      <screen>
    $ <userinput>ldapsearch \
     --baseDN "" \
     --searchScope base \
     --port 1389 \
     "(objectclass=*)" supportedExtension</userinput>
    <computeroutput>dn:
    supportedExtension: 1.3.6.1.1.8
    supportedExtension: 1.3.6.1.4.1.26027.1.6.1
    supportedExtension: 1.3.6.1.4.1.26027.1.6.2
    supportedExtension: 1.3.6.1.4.1.26027.1.6.3
    supportedExtension: 1.3.6.1.4.1.4203.1.11.1
    supportedExtension: 1.3.6.1.4.1.4203.1.11.3
    supportedExtension: 1.3.6.1.4.1.1466.20037</computeroutput>
      </screen>
    

ForgeRock doc tools 2.0.0 released

ForgeRock Community Logo Today marked the release of ForgeRock doc tools 2.0.0. This release includes changes for 32 issues. Some were bug fixes, others issues and improvements, still others investigations into a future reimplementation of docs.forgerock.org.

You can read the release announcement sent to the docs list. You might also want to read the HTML version of the release notes. Some new features and improvements:

  • Integrated support for text-based UML image sources, thanks to PlantUML
  • Support for olinks in PDF
  • DPI set automatically on PNGs
  • ↪ on mouseover in HTML for all titles with anchors, making it easier to send the link to a procedure, example, or table
  • Support for Maven properties in XML attribute values
  • Branding and common content moved to separate Maven projects, enabling use of custom branding and boilerplate
  • Support for a basic .zip of release docs

When you upgrade to this version of the plugin, you must not only change the version number in your POM, but also adjust the configuration. After you read the release notes, also see the README for more information.