ForgeRock Documentation Tools 3.2.0 Release Notes

ForgeRock Documentation Tools is a catch all for the doc build artifacts, sites where we post release documentation, and the documentation about documentation.

The link to the online issue tracker is https://bugster.forgerock.org/jira/browse/DOCS.

Compatibility

With the fix for DOCS-375, the <resourcesDirectory> can no longer be changed. Arbitrary resources must be moved to src/main/docbkx/resources by default, <docbkxSourceDirectory>/resources if the sources are in a non-default location.

Limitations

Documentation builds depend on system support for UTF-8. The locale for the user running the documentation build must support UTF-8, too. For example:

LANG="en_US.UTF-8"

Some systems set the locale to use ASCII by default. On such systems, it is not sufficient to set the JVM to use UTF-8, as in -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8. Lack of support for UTF-8 results in some UTF-8 characters being rendered as ??? or ??.

Improvements & New Features

DOCS-389: Bootstrap HTML: Produce section numbers for a.b.c.d.e

DOCS-386: Add build date to Bootstrap output

DOCS-376: Change Background Color on Warning Admonitions

The patch makes the Warning admonition less subtle in the Bootstrap output format.

PDF and Backstage output formats are not affected.

DOCS-371: Trim verbatim elements during pre-processing

The patch updates the DocBook source pre-processing to trim leading blank lines and trailing blank lines and spaces from <programlisting> and <screen> elements.

The present implementation only works if there is no inline markup. In other words, if there are elements such as <userinput> or <replaceable> inside the <programlisting> or <screen> element, then leading and trailing blank lines are left as is.

DOCS-370: Allow ordering for documentation sets

The patch adds an optional <documents> parameter to specify the intended order of documents in the set. DocBook (and Asciidoc) documents are identified by XML ID. Artifacts are identified by output directory.

<documents>
 <document>release-notes</document>
 <document>admin-guide</document>
 <document>reference</document>
 <document>javadoc</document>
</documents>

The result if specified is an array field, documents, in docset.json when building the documentation set for publication on BackStage.

DOCS-222: Remove the need to specify executions in the configuration

The patch introduces docs project packaging that redefines default lifecycle goals to run forgerock-doc-maven-plugin without specifying executions in the configuration.

<project>
    ...
    <packaging>docs</packaging>
    ...
    <build>
        <plugins>
        <plugin>
          <groupId>org.forgerock.commons</groupId>
          <artifactId>forgerock-doc-maven-plugin</artifactId>
          <version>3.2.0</version>
          <extensions>true</extensions>
          <configuration>
            <projectName>Test</projectName>
            <projectVersion>1.0.0-SNAPSHOT</projectVersion>
            <releaseVersion>1.0.0</releaseVersion>
          </configuration>
        </plugin>
      </plugins>
    </build>
    ...
</project>

The docs packaging lifecycle redefines the default lifecycle as described in the following table:

Default Lifecycle Phase Docs Packaging Phase
process-sources org.forgerock.commons:forgerock-doc-maven-plugin:process
compile org.forgerock.commons:forgerock-doc-maven-plugin:build
prepare-package org.forgerock.commons:forgerock-doc-maven-plugin:backstage
install org.apache.maven.plugins:maven-install-plugin:install
deploy org.apache.maven.plugins:maven-deploy-plugin:deploy

Notice that this does not map the site or release goals. You must declare those goals explicitly.

DOCS-8: Reduce verbosity of output from forgerock-doc-build-plugin

The patch introduces a boolean verbose setting to regulate logging verbosity.

Use <verbose>true</verbose> in the configuration or -Dverbose=true on the command line for more information in the logs.

Default: false

Bugs Fixed

DOCS-390 Allow normal links to work in PDF

DOCS-380: Images not handled correctly when usePreprocessedSources=true

The fix also allows Maven filtering on pre-processed sources.

DOCS-379: Prevent broken links to arbitrary resources in PDF

DOCS-378: Formatted introductory text to chapters is not always the first paragraph in the chapter

DOCS-375: Remove <resourcesDirectory> optional setting

Having this optional made building from pre-processed sources very tricky. In particular, having this optional does not work for BackStage.

DOCS-374: Arbitrary resource links do not support xlink:type=“resource”

DOCS-367: Build plugin backstage goal duplicates docset.json

DOCS-361: olink text in PDF output does not include document title

DOCS-230 PDF: Avoid bad line breaks in the middle of literals

The fix has hyphenation in <literal> element content occur after ., /, ,, or - where necessary.

Known Issues

This section lists the main known issues at the time of release.

DOCS-393: PDF: many blank left-hand pages in reference

DOCS-392: PDF: code examples run off the top and bottom of the page

DOCS-391: PDF: DRAFT watermark too big for page

DOCS-360: PDF: wrong procedure heading font size and spacing

DOCS-356: <glossseealso> generates See Also (with also in upper case)

DOCS-268: PDF: strange output when using bridgeheads

DOCS-190: PDF: release date and publication date are not shown


The contents of this file are subject to the terms of the Common Development and Distribution License (the License). You may not use this file except in compliance with the License.

You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the specific language governing permission and limitations under the License.

When distributing Covered Software, include this CDDL Header Notice in each file and include the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL Header, with the fields enclosed by brackets [] replaced by your own identifying information: “Portions copyright [year] [name of copyright owner]”.

Copyright 2015-2016 ForgeRock AS.