Generate man pages in the AsciiDoc format (#418)

OpenIdentityPlatform · Oct 1, 2024 · c19cb1e · c19cb1e
1 parent 1cb7760
commit c19cb1e
Show file tree

Hide file tree

Showing 90 changed files with 3,335 additions and 214,308 deletions.
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -133,8 +133,9 @@ jobs:
           GITHUB_TOKEN: ${{ github.token }}
         run:   |
           cd ${{ github.event.repository.name }}.wiki
-          rm -rf docbkx
-          cp -R ../opendj-doc-generated-ref/target/docbkx ../${{ github.event.repository.name }}.wiki
+          rm -rf asciidoc
+          mkdir asciidoc
+          cp -R ../opendj-doc-generated-ref/target/asciidoc/pdf ../${{ github.event.repository.name }}.wiki/asciidoc        
           git add -A
           git commit -a -m "upload docs after deploy ${{ github.sha }}"
           git push --quiet --force

diff --git a/opendj-cli/src/main/java/com/forgerock/opendj/cli/ArgumentParser.java b/opendj-cli/src/main/java/com/forgerock/opendj/cli/ArgumentParser.java
@@ -659,7 +659,7 @@ void toRefEntry(StringBuilder builder, String synopsisArgs, List<Argument> argLi
      * @return A String with line separators replaced by {@code &lt;/para>&lt;para>}.
      */
     String eolToNewPara(final LocalizableMessage input) {
-        return input.toString().replaceAll(EOL, "</para><para>");
+        return input.toString().replaceAll(EOL, "\n");
     }
 
     /**

diff --git a/opendj-cli/src/main/java/com/forgerock/opendj/cli/SubCommandArgumentParser.java b/opendj-cli/src/main/java/com/forgerock/opendj/cli/SubCommandArgumentParser.java
@@ -1132,7 +1132,7 @@ private void setSubCommandOptionsInfo(Map<String, Object> map, SubCommand subCom
                 Map<String, Object> info = new HashMap<>();
                 if (subCommandUsageHandler != null) {
                     if (!doesHandleProperties(a)) {
-                        nameOption = "<option>" + optionSynopsis + "</option>";
+                        nameOption = "`" + optionSynopsis + "`";
                     }
 
                     // Let this build its own arbitrarily formatted additional info.

diff --git a/opendj-cli/src/main/resources/com/forgerock/opendj/cli/cli.properties b/opendj-cli/src/main/resources/com/forgerock/opendj/cli/cli.properties
@@ -448,14 +448,14 @@ ERR_ERROR_CANNOT_READ_HOST_NAME=Cannot read the host name
 # Strings for generated reference documentation.
 REF_TITLE_DESCRIPTION=Description
 REF_TITLE_OPTIONS=Options
-REF_INTRO_OPTIONS=The <command>%s</command> command takes the following options:
+REF_INTRO_OPTIONS=The `%s` command takes the following options:
 REF_DEFAULT=Default: %s
 REF_TITLE_SUBCOMMANDS=Subcommands
-REF_INTRO_SUBCOMMANDS=The <command>%s</command> command supports the following subcommands:
+REF_INTRO_SUBCOMMANDS=The `%s` command supports the following subcommands:
 REF_PART_TITLE_SUBCOMMANDS=%s Subcommands Reference
-REF_PART_INTRO_SUBCOMMANDS=This section covers <command>%s</command> subcommands.
-REF_DEFAULT_BACKEND_TYPE=Default: <literal>je</literal> for standard edition, \
-  <literal>pdb</literal> for OEM edition.
+REF_PART_INTRO_SUBCOMMANDS=This section covers `%s` subcommands.
+REF_DEFAULT_BACKEND_TYPE=Default: `je` for standard edition, \
+  `pdb` for OEM edition.
 
 # Supplements to descriptions for generated reference documentation.
-SUPPLEMENT_DESCRIPTION_CONTROLS=<xinclude:include href="variablelist-ldap-controls.xml" />
+SUPPLEMENT_DESCRIPTION_CONTROLS=include::./_variablelist-ldap-controls.adoc[]
diff --git a/opendj-cli/src/main/resources/templates/dscfgAppendProps.ftl b/opendj-cli/src/main/resources/templates/dscfgAppendProps.ftl
@@ -12,13 +12,16 @@
  # information: "Portions Copyright [year] [name of copyright owner]".
  #
  # Copyright 2015 ForgeRock AS.
+ # Portions Copyright 2024 3A Systems LLC.
  #-->
-<refsect1 xml:id="${id}">
-  <title>${title}</title>
 
-  <para>
-   ${intro}
-  </para>
+[#${id}]
+== ${title}
 
-  ${list}
-</refsect1>
+${intro}
+
+--
+
+${list}
+
+--
diff --git a/opendj-cli/src/main/resources/templates/dscfgListItem.ftl b/opendj-cli/src/main/resources/templates/dscfgListItem.ftl
@@ -12,14 +12,6 @@
  # information: "Portions Copyright [year] [name of copyright owner]".
  #
  # Copyright 2015 ForgeRock AS.
+ # Portions Copyright 2024 3A Systems LLC.
  #-->
-<listitem>
- <para>
-  <link
-   <#-- Link to the Reference. Change this if the pages move to another document. -->
-   xlink:href="reference#${id}"
-   xlink:role="http://docbook.org/xlink/role/olink"
-   xlink:show="new"
-  ><command>${name}</command></link>: ${description}
- </para>
-</listitem>
+* xref:dsconfig-subcommands-ref.adoc#${id}[${name}, window=_blank]: ${description}
diff --git a/opendj-cli/src/main/resources/templates/dscfgListSubtypes.ftl b/opendj-cli/src/main/resources/templates/dscfgListSubtypes.ftl
@@ -12,34 +12,22 @@
  # information: "Portions Copyright [year] [name of copyright owner]".
  #
  # Copyright 2015 ForgeRock AS.
+ # Portions Copyright 2024 3A Systems LLC.
  #-->
-<variablelist>
 
- <para>
-   ${dependencies}
- </para>
+[open]
+====
+${dependencies}
 
- <para>
-   ${typesIntro}
- </para>
+${typesIntro}
 
- <#list children as child>
-   <varlistentry>
-     <term>${child.name}</term>
-     <listitem>
-       <para>
-         ${child.default}
-       </para>
-
-       <para>
-         ${child.enabled}
-       </para>
-
-       <para>
-         ${child.link}
-       </para>
-     </listitem>
-   </varlistentry>
+<#list children as child>
+`${child.name}`::
++
+${child.default}
++
+${child.enabled}
++
+${child.link}
  </#list>
-
-</variablelist>
+====
diff --git a/opendj-cli/src/main/resources/templates/dscfgReference.ftl b/opendj-cli/src/main/resources/templates/dscfgReference.ftl
@@ -12,24 +12,16 @@
  # information: "Portions Copyright [year] [name of copyright owner]".
  #
  # Copyright 2015 ForgeRock AS.
+ # Portions Copyright 2024 3A Systems LLC.
  #-->
 ${marker}
-<reference xml:id="${name}-subcommands-ref"
-           xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="${locale}"
-           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-           xsi:schemaLocation="http://docbook.org/ns/docbook
-                               http://docbook.org/xml/5.0/xsd/docbook.xsd"
-           xmlns:xinclude="http://www.w3.org/2001/XInclude">
 
- <title>${title}</title>
+[#${name}-subcommands-ref]
+== ${title}
+:leveloffset: 1
 
- <partintro>
-  <para>
-   ${partintro}
-  </para>
- </partintro>
+${partintro}
 
- <#list subcommands as subcommand>
- <xinclude:include href="man-${subcommand.id}.xml" />
- </#list>
-</reference>
+<#list subcommands as subcommand>
+include::./man-${subcommand.id}.adoc[]
+</#list>
diff --git a/opendj-cli/src/main/resources/templates/dscfgSubcommand.ftl b/opendj-cli/src/main/resources/templates/dscfgSubcommand.ftl
@@ -1,6 +1,5 @@
 ${marker}
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
+////
   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.
@@ -13,85 +12,58 @@ ${marker}
   Header, with the fields enclosed by brackets [] replaced by your own identifying
   information: "Portions Copyright [year] [name of copyright owner]".
 
-  Copyright 2011-${year} ForgeRock AS.
--->
-<refentry xml:id="${id}"
-          xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="${locale}"
-          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-          xsi:schemaLocation="http://docbook.org/ns/docbook
-                              http://docbook.org/xml/5.0/xsd/docbook.xsd"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xinclude="http://www.w3.org/2001/XInclude">
+  Copyright 2011-2017 ForgeRock AS.
+  Portions Copyright ${year} 3A Systems LLC.
+////
 
- <info>
-  <copyright>
-   <year>${year}</year>
-   <holder>2011-2017 ForgeRock AS. 2017-${year} Open Identity Platform Community</holder>
-  </copyright>
- </info>
+[#${id}]
+= ${name}(1)
+:doctype: manpage
+:manmanual: Directory Server Tools
+:mansource: OpenDJ
 
- <refmeta>
-  <refentrytitle>${name}</refentrytitle><manvolnum>1</manvolnum>
-  <refmiscinfo class="software">OpenDJ</refmiscinfo>
-  <refmiscinfo class="version">${r"${project.version}"}</refmiscinfo>
- </refmeta>
+== Name
+${name} - ${purpose}
 
- <refnamediv>
-  <refname>${name}</refname>
-  <refpurpose>${purpose}</refpurpose>
- </refnamediv>
+== Synopsis
 
- <refsynopsisdiv>
-  <cmdsynopsis>
-   <command>${name}</command>
-   <arg choice="plain">${args}</arg>
-  </cmdsynopsis>
- </refsynopsisdiv>
+`${name}` ${args}
 
- <refsect1 xml:id="${id}-description">
-  <title>${descTitle}</title>
+[#${id}-description]
+== ${descTitle}
 
-  <para>
-   ${description?ensure_ends_with(".")}
-  </para>
+${description?ensure_ends_with(".")}
 
-  <#if info??>${info}</#if>
- </refsect1>
+<#if info??>${info}</#if>
 
- <#if options??>
- <refsect1 xml:id="${id}-options">
-  <title>${optionsTitle}</title>
+<#if options??>
+[#${id}-options]
+== ${optionsTitle}
 
-  <variablelist>
-   <para>
-    ${optionsIntro}
-   </para>
+${optionsIntro}
 
+--
    <#list options as option>
-   <varlistentry>
-    <term><option>${option.synopsis?xml}</option></term>
-    <listitem>
-     <para>
-      ${option.description?ensure_ends_with(".")}
-     </para>
+`${option.synopsis?xml}`::
 
+${option.description?ensure_ends_with(".")}
      <#if option.info??>
-       <#if option.info.usage??>${option.info.usage}</#if>
-
+       <#if option.info.usage??>
++
+${option.info.usage}
+       </#if>
        <#if option.info.default??>
-       <para>
-        ${option.info.default}
-       </para>
++
+${option.info.default}
+       </#if>
+       <#if option.info.doc??>
++
+${option.info.doc}
        </#if>
-
-       <#if option.info.doc??>${option.info.doc}</#if>
      </#if>
-    </listitem>
-   </varlistentry>
    </#list>
-  </variablelist>
- </refsect1>
- </#if>
-
- <#if propertiesInfo??>${propertiesInfo}</#if>
-</refentry>
+--
+</#if>
+<#if propertiesInfo??>
+${propertiesInfo}
+</#if>
diff --git a/opendj-cli/src/main/resources/templates/dscfgVarListEntry.ftl b/opendj-cli/src/main/resources/templates/dscfgVarListEntry.ftl
@@ -12,10 +12,8 @@
  # information: "Portions Copyright [year] [name of copyright owner]".
  #
  # Copyright 2015 ForgeRock AS.
+ # Portions Copyright 2024 3A Systems LLC.
  #-->
-<varlistentry>
-  <term>${term}</term>
-  <listitem>
-    ${definition}
-  </listitem>
-</varlistentry>
+
+${term}::
+${definition}
diff --git a/opendj-cli/src/main/resources/templates/dscfgVariableList.ftl b/opendj-cli/src/main/resources/templates/dscfgVariableList.ftl
@@ -12,29 +12,18 @@
  # information: "Portions Copyright [year] [name of copyright owner]".
  #
  # Copyright 2015-2016 ForgeRock AS.
+ # Portions Copyright 2024 3A Systems LLC.
  #-->
-<variablelist>
 
 <#list properties as property>
+${property.term}::
+[open]
+====
+${property.descTitle}::
+${property.description?xml}
 
-  <varlistentry>
-    <term>${property.term}</term>
-    <listitem>
-      <variablelist>
+${property.list}
 
-        <varlistentry>
-          <term>${property.descTitle}</term>
-          <listitem>
-            <para>
-              ${property.description?xml}
-            </para>
-          </listitem>
-        </varlistentry>
+====
 
-        ${property.list}
-      </variablelist>
-    </listitem>
-  </varlistentry>
-</#list>
-
-</variablelist>
+</#list>