CR-6565 OPENDJ-1806 Workaround usage() formatting in docs

Mark Craig

02.16.2015 ca92b2264272709e1223ad117d37ec93153dd62e

CR-6565 OPENDJ-1806 Workaround usage() formatting in docs

Whitespace is not generally significant in doc sources
except where markup specifies that it is
such as within ProgramListing, Screen, and LiteralLayout elements.

Some usage messages in the generated reference docs
are formatted for use in terminal windows,
with significant whitespace and newlines
that get lost when pulled as is into the documentation source.

This patch works around usage() message content
that contains significant whitespace, specifically newlines.

 opendj-cli/src/main/java/com/forgerock/opendj/cli/ArgumentParser.java

@@ -763,7 +763,7 @@
        map.put("shortDesc", getShortToolDescription());
        map.put("descTitle", REF_TITLE_DESCRIPTION.get());
        map.put("args", synopsisArgs);
        map.put("description", getToolDescription());
        map.put("description", eolToNewPara(getToolDescription()));
        map.put("info", getDocToolDescriptionSupplement());
        if (!argList.isEmpty()) {
            map.put("optionSection", getOptionsRefSect1(scriptName));
@@ -773,6 +773,14 @@
        applyTemplate(builder, "refEntry.ftl", map);
    }

    /**
     * Returns a String with line separators replaced by {@code </para><para>}.
     * @param input String in which to replace line separators.
     * @return A String with line separators replaced by {@code </para><para>}.
     */
    String eolToNewPara(final LocalizableMessage input) {
        return input.toString().replaceAll(EOL, "</para><para>");
    }

    /**
     * Returns a generated DocBook XML RefSect1 element for all command options.
@@ -795,7 +803,7 @@
            if (argGroup.containsArguments() && printHeaders) {
                LocalizableMessage description = argGroup.getDescription();
                if (description != LocalizableMessage.EMPTY) {
                    group.put("description", argGroup.getDescription());
                    group.put("description", eolToNewPara(description));
                } else {
                    group.put("description", INFO_SUBCMDPARSER_WHERE_OPTIONS_INCLUDE.get());
                }
@@ -844,7 +852,7 @@
    private Map<String, Object> getArgumentMap(final Argument a) {
        Map<String, Object> option = new HashMap<String, Object>();
        option.put("synopsis", getOptionSynopsis(a));
        option.put("description", a.getDescription());
        option.put("description", eolToNewPara(a.getDescription()));
        String dv = a.getDefaultValue();
        option.put("default", dv != null ? REF_DEFAULT.get(dv) : null);
        option.put("info", a.getDocDescriptionSupplement());

 opendj-cli/src/main/java/com/forgerock/opendj/cli/SubCommandArgumentParser.java

@@ -1151,7 +1151,7 @@
        map.put("shortDesc", getShortToolDescription());
        map.put("descTitle", REF_TITLE_DESCRIPTION.get());
        map.put("args", getSynopsisArgs());
        map.put("description", getToolDescription());
        map.put("description", eolToNewPara(getToolDescription()));
        map.put("info", getDocToolDescriptionSupplement());
        if (!globalArgumentList.isEmpty()) {
            map.put("optionSection", getOptionsRefSect1(scriptName));
@@ -1209,7 +1209,7 @@
        Map<String, Object> map = new HashMap<String, Object>();
        map.put("id", scriptName + "-" + subCommand.getName());
        map.put("name", scriptName + " " + subCommand.getName());
        map.put("description", subCommand.getDescription());
        map.put("description", eolToNewPara(subCommand.getDescription()));
        StringBuilder sb = new StringBuilder();
        applyTemplate(sb, "dscfgListItem.ftl", map);
        return sb.toString();
@@ -1228,7 +1228,7 @@
        map.put("id", scriptName + "-" + subCommand.getName());
        final String name = scriptName + " " + subCommand.getName();
        map.put("name", name);
        map.put("description", subCommand.getDescription());
        map.put("description", eolToNewPara(subCommand.getDescription()));
        map.put("optionsTitle", REF_TITLE_OPTIONS.get());
        map.put("optionsIntro", REF_INTRO_OPTIONS.get(name));

@@ -1258,7 +1258,7 @@
                Map<String, Object> option = new HashMap<String, Object>();
                String optionSynopsis = getOptionSynopsis(a);
                option.put("synopsis", optionSynopsis);
                option.put("description", a.getDescription());
                option.put("description", eolToNewPara(a.getDescription()));
                Map<String, Object> info = new HashMap<String, Object>();
                if (subCommandUsageHandler != null) {
                    if (!doesHandleProperties(a)) {
@@ -1304,10 +1304,10 @@
            map.put("year", new SimpleDateFormat("yyyy").format(new Date()));
            map.put("id", scriptName + "-" + subCommand.getName());
            map.put("name", scriptName + " " + subCommand.getName());
            map.put("purpose", subCommand.getDescription());
            map.put("purpose", eolToNewPara(subCommand.getDescription()));
            map.put("args", INFO_SUBCMDPARSER_OPTIONS.get());
            map.put("descTitle", REF_TITLE_DESCRIPTION.get());
            map.put("description", subCommand.getDescription());
            map.put("description", eolToNewPara(subCommand.getDescription()));
            map.put("info", subCommand.getDocDescriptionSupplement());
            map.put("optionsTitle", REF_TITLE_OPTIONS.get());
            map.put("optionsIntro", REF_INTRO_OPTIONS.get(scriptName + " " + subCommand.getName()));