Category Archives: Tools

ForgeRock 3.2.2 doc tools released

ForgeRock Logo ForgeRock doc tools 3.2.2 were released today.

This is a maintenance release, compatible with earlier 3.2.x releases.

ForgeRock doc tools 3.2.2 includes the following components:

  • forgerock-doc-maven-plugin
  • forgerock-doc-common-content
  • forgerock-doc-default-branding

This release resolves bugs and includes several improvements. For details, see the release notes.

Big thanks once again for enhancements, for identifying problems, and for help debugging.

Thanks to Chris Lee, Cristina Herraz, Joanne Henry, Lana Frost, Lori Goldman, David Goldsmith, Gene Hirayama, and Mike Jang for fixes, improvements, testing and bug reports.

Thanks also to the ForgeRock BackStage team for their help and continued improvements to release documentation.

Leave a comment

Filed under Docs, Tools

ForgeRock repos and mirrors

ForgeRock LogoYou might already know that ForgeRock’s platform is built on open source software. We have been using Stash, now BitBucket, to host the git repos and to manage the review process.

If you want to read the code or the doc source code, you will find the canonical copies on that server. For example—there are more repos on the server, but here are some of the most popular links:

If you want to contribute a patch or a feature, sign up, login, and follow the development process. That process involves working on https://stash.forgerock.org/.

You will also find read-only mirrors (and other goodies) at GitHub, under https://github.com/ForgeRock:

Either server is fine if you just want to read the code or clone a repo.

Leave a comment

Filed under Tools

docbkx-tools 2.0.17 is out

Congratulations to Cedric on the release of docbkx-tools 2.0.17 earlier this week.

For those of you working with DocBook and Maven, docbkx-tools provides a plugin to generate output formats (HTML, PDF, etc.) as part of the Maven build, by applying the DocBook XSL stylesheets.

The 2.0.17 release adds some improvements, including support for DocBook XSL 1.79.1.

At ForgeRock, we have been relying on docbkx-tools since 2011. The next release of our doc build plugin is using 2.0.17. Upgrade was straightforward. The only issue that still needs fixing is olink support in chunked HTML.

Leave a comment

Filed under Docs, Tools

ForgeRock doc tools 3.2.0 released

ForgeRock Logo ForgeRock doc tools 3.2.0 were released today.

This is a minor release, compatible with earlier 3.x releases, with one small exception. See the release notes for details.

ForgeRock doc tools 3.2.0 includes the following components:

  • forgerock-doc-maven-plugin
  • forgerock-doc-common-content
  • forgerock-doc-default-branding

This release brings several improvements and squashes a few bugs.

Big thanks once again to Chris Lee for enhancements to the Bootstrap-styled HTML (the default for draft, in-progress docs to read when trying nightly builds), for identifying problems, and for help debugging.

Thanks also to Joanne Henry, Lana Frost, Lori Goldman, David Goldsmith, Gene Hirayama, and Mike Jang for testing and bug reports.

Leave a comment

Filed under Docs, Tools

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.

Leave a comment

Filed under Docs, 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…

Leave a comment

Filed under Docs, Tools

ForgeRock doc tools 2.1.4 released

ForgeRock doc tools 2.1.4 is now available. This is a maintenance release, primarily to integrate an options for OpenICF docs. See the release notes for details.

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

1 Comment

Filed under Docs, Tools