[#1128] Replace the DocBook xinclude and olink leftovers of the generated reference with AsciiDoc

opendj-config/src/main/java/org/forgerock/opendj/config/dsconfig/DSConfig.java

@@ -414,7 +414,7 @@ private void appendSyntax(final StringBuilder b, PropertyDefinition<?> prop) {
 
                 @Override
                 public String visitACI(ACIPropertyDefinition prop, Void p) {
-                    b.append(op).append(REF_DSCFG_ACI_SYNTAX_REL_URL.get()).append(cp).append(EOL);
+                    b.append(op).append(REF_DSCFG_ACI_SYNTAX.get()).append(cp).append(EOL);
                     return null;
                 }
 
@@ -470,22 +470,22 @@ public String visitDN(DNPropertyDefinition prop, Void p) {
 
                 @Override
                 public String visitDuration(DurationPropertyDefinition prop, Void p) {
-                    b.append(REF_DSCFG_DURATION_SYNTAX_REL_URL.get()).append(EOL);
+                    b.append(REF_DSCFG_DURATION_SYNTAX.get()).append(EOL);
                     b.append(op);
                     if (prop.isAllowUnlimited()) {
                         b.append(REF_DSCFG_ALLOW_UNLIMITED.get()).append(" ");
                     }
                     if (prop.getMaximumUnit() != null) {
                         final String maxUnitName = prop.getMaximumUnit().getLongName();
-                        b.append(REF_DSCFG_DURATION_MAX_UNIT.get(maxUnitName)).append(".");
+                        b.append(REF_DSCFG_DURATION_MAX_UNIT.get(maxUnitName)).append(". ");
                     }
                     final DurationUnit baseUnit = prop.getBaseUnit();
                     final long lowerLimit = valueOf(baseUnit, prop.getLowerLimit());
                     final String unitName = baseUnit.getLongName();
                     b.append(REF_DSCFG_DURATION_LOWER_LIMIT.get(lowerLimit, unitName)).append(".");
                     if (prop.getUpperLimit() != null) {
                         final long upperLimit = valueOf(baseUnit, prop.getUpperLimit());
-                        b.append(REF_DSCFG_DURATION_UPPER_LIMIT.get(upperLimit, unitName)).append(".");
+                        b.append(" ").append(REF_DSCFG_DURATION_UPPER_LIMIT.get(upperLimit, unitName)).append(".");
                     }
                     b.append(cp).append(EOL);
                     return null;

opendj-config/src/main/resources/com/forgerock/opendj/dsconfig/dsconfig.properties

@@ -12,6 +12,7 @@
 #
 # Copyright 2006-2010 Sun Microsystems, Inc.
 # Portions Copyright 2011-2016 ForgeRock AS.
+# Portions Copyright 2026 3A Systems, LLC.
 
 #
 # Format string definitions
@@ -398,8 +399,12 @@ INFO_DSCFG_TOOL_DESCRIPTION_255=This utility can be used to define a base \
 
 # Strings for generated reference documentation.
 REF_DSCFG_ALLOW_UNLIMITED_1000=A value of "-1" or "unlimited" for no limit.
-REF_DSCFG_ACI_SYNTAX_REL_URL_1001=<olink targetdoc="admin-guide" targetptr="about-acis" />
-REF_DSCFG_DURATION_SYNTAX_REL_URL_1002=<xinclude:include href="itemizedlist-duration.xml" />
+REF_DSCFG_ACI_SYNTAX_1001=An access control instruction, as described in \
+ xref:../admin-guide/chap-privileges-acis.adoc#about-acis["About Access Control Instructions"] \
+ in the __Administration Guide__.
+REF_DSCFG_DURATION_SYNTAX_1002=A duration: a number followed by a unit, one of \
+ `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours), `d` (days) \
+ or `w` (weeks), for example `1 s` or `2 w`.
 REF_DSCFG_ARG_ADDITIONAL_INFO_1003=%s properties depend on the %s type, \
  which depends on the %s option.
 REF_DSCFG_SUBTYPE_DEPENDENCIES_1004=%s properties depend on the %s type, \

opendj-doc-generated-ref/src/main/asciidoc/man-pages/_description-upgrade.adoc

@@ -0,0 +1,39 @@
+////
+
+  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 ForgeRock AS.
+  Portions Copyright 2026 3A Systems, LLC.
+
+////
+
+This utility thus performs only part of the upgrade process, which includes the following phases for a single server.
+
+. Get and unpack a newer version of OpenDJ directory server software.
+
+. Stop the current OpenDJ directory server.
+
+. Overwrite existing binary and script files with those of the newer version, and then run this utility before restarting OpenDJ.
+
+. Start the upgraded OpenDJ directory server.
+
+[IMPORTANT]
+====
+This utility __does not back up OpenDJ before you upgrade, nor does it restore OpenDJ if the utility fails__. In order to revert a failed upgrade, make sure you back up OpenDJ directory server before you overwrite existing binary and script files.
+====
+
+By default this utility requests confirmation before making important configuration changes. You can use the `--no-prompt` option to run the command non-interactively.
+
+When using the `--no-prompt` option, if this utility cannot complete because it requires confirmation for a potentially very long or critical task, then it exits with an error and a message about how to finish making the changes. You can add the `--force` option to force a non-interactive upgrade to continue in this case, also performing long running and critical tasks.
+
+After upgrading, see the resulting `logs/upgrade.log` file for a full list of operations performed.

opendj-doc-generated-ref/src/main/asciidoc/man-pages/_variablelist-backendstat-index-status.adoc

@@ -0,0 +1,49 @@
+////
+
+  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 ForgeRock AS.
+  Portions Copyright 2026 3A Systems, LLC.
+
+////
+
+When you run the `show-index-status` subcommand, the result is a table, followed by a "Total", which is the total number of indexes, followed by a list of indexes with "Over index-entry-limit keys" to show the values for which the number of entries exceeded the index entry limit. The table has the following columns.
+
+Index Name::
+Name of the index, which takes the form __attr.type__ for attribute indexes, and vlv.__name__ for VLV indexes. Some indexes are for OpenDJ directory server's internal use.
++
+Example: `givenName.caseIgnoreSubstringsMatch:6`
+
+Raw DB Name::
+Name of the backend tree, which reflects how OpenDJ directory server organizes the data in the database.
++
+Example: `/dc=com,dc=example/givenName.caseIgnoreSubstringsMatch:6`
+
+Valid::
+This is `true` for valid indexes. If this is `false`, the index might be degraded. Verify the index, and rebuild the index if necessary. For an attribute index that is not valid, the record count and the key counts that follow it show `-`.
+
+Confidential::
+This is `true` for indexes with `confidentiality-enabled`, whose keys are stored encrypted. This is recorded as `-` for VLV indexes, which have no confidentiality setting.
+
+Record Count::
+Number of indexed keys. Use the `backendstat dump-index` command to see how many entry IDs correspond to each key.
+
+Over Entry Limit::
+Number of keys for which there are too many values to maintain an index, based on the index entry limit. This is recorded as `-` for VLV indexes.
++
+In other words, with the default index entry limit of 4000, if every user in your large directory has an email address ending in `@example.com`, and a substring index with default substring length of 6 is maintained for `mail`, then OpenDJ directory server does not maintain indexes for keys corresponding to substrings in `@example.com`.
++
+As a result, an LDAP search with the filter `"(mail=*@example.com)"` becomes an unindexed search even though a substring index exists for the mail attribute. By default OpenDJ directory server does not allow unindexed searches except by privileged users. This is usually exactly the behavior you want in order to prevent client applications from sending searches that return every user in the directory for example. Clients should refine their search filters instead.
+
+95%, 90%, 85%::
+Number of keys for which the number of values is approaching the index entry limit. This is a measure of how full the entry ID lists are. The `95%` column counts keys holding at least 95% of the limit, the `90%` column keys holding at least 90% but less than 95%, and the `85%` column keys holding at least 80% but less than 90%. These columns are recorded as `-` for VLV indexes, and stay at 0 for an index whose entry limit is 0, which means no limit.

opendj-server-legacy/src/messages/org/opends/messages/tool.properties

@@ -2615,7 +2615,7 @@ REF_SHORT_DESC_WINDOWS_SERVICE_15030=register OpenDJ as a Windows Service
 REF_SHORT_DESC_BACKEND_TOOL_15031=gather OpenDJ backend debugging information
 
 # Supplements to descriptions for generated reference documentation.
-SUPPLEMENT_DESCRIPTION_UPGRADE_CLI_20004=<xinclude:include href="description-upgrade.xml" />
+SUPPLEMENT_DESCRIPTION_UPGRADE_CLI_20004=include::./_description-upgrade.adoc[]
 INFO_ARGUMENT_DESCRIPTION_TESTONLY_20005=Just verify that the JVM can be \
  started properly
 INFO_INSTALLDS_BACKEND_TYPE_PLACEHOLDER_20006={backendType}
@@ -2632,7 +2632,7 @@ ERR_INSTANCE_NOT_CONFIGURED_20013=The local instance is not configured or you do
 ERR_SEARCH_INVALID_DEREFERENCE_POLICY_20014=Invalid deref alias specified: %s
 ERR_FILE_NOT_FULLY_READABLE_20015=Could not completely read file '%s'
 SUPPLEMENT_DESCRIPTION_BACKEND_TOOL_SUBCMD_LIST_INDEX_STATUS_20016=\
-  <xinclude:include href="variablelist-backendstat-index-status.xml" />
+  include::./_variablelist-backendstat-index-status.adoc[]
 INFO_DESCRIPTION_DEFAULT_ADD_20017=Legacy argument for ForgeRock OpenDJ compatibility.
 WARN_CONFIGDS_KEY_WRAPPING_TRANSFORMATION_UNSUPPORTED_20018=This Java runtime \
  supports neither the default key wrapping transformation %s nor an alternative \

opendj-server-legacy/src/test/java/org/opends/server/tools/dsconfig/DsconfigOptionsTestCase.java

@@ -12,13 +12,16 @@
  * information: "Portions Copyright [year] [name of copyright owner]".
  *
  * Copyright 2011-2016 ForgeRock AS.
+ * Portions Copyright 2026 3A Systems, LLC.
  */
 package org.opends.server.tools.dsconfig;
 
 import static com.forgerock.opendj.cli.ReturnCode.*;
 
 import static org.testng.Assert.*;
 
+import java.io.ByteArrayOutputStream;
+
 import org.forgerock.opendj.config.dsconfig.DSConfig;
 import org.opends.server.DirectoryServerTestCase;
 import org.opends.server.TestCaseUtils;
@@ -182,6 +185,33 @@ public void testGenerateDoc() throws Exception
     }
   }
 
+  /**
+   * Tests that the generated reference describes the duration and ACI values in AsciiDoc,
+   * and keeps the duration limits apart.
+   */
+  @Test
+  public void testGenerateDocHasNoDocBookLeftovers() throws Exception
+  {
+    System.setProperty("org.forgerock.opendj.gendoc", "true");
+    System.setProperty("com.forgerock.opendj.ldap.tools.scriptName", "dsconfig");
+    final ByteArrayOutputStream out = new ByteArrayOutputStream();
+    try
+    {
+      assertEquals(DSConfig.main(new String[] { "--no-prompt", "-?" }, out, System.err), SUCCESS.get());
+    }
+    finally
+    {
+      System.clearProperty("org.forgerock.opendj.gendoc");
+    }
+    final String doc = out.toString("UTF-8");
+    assertTrue(doc.contains("Upper limit is"), "no duration property with an upper limit was generated");
+    assertTrue(doc.contains("A duration: a number followed by a unit"), "duration syntax");
+    assertTrue(doc.contains("xref:../admin-guide/chap-privileges-acis.adoc#about-acis"), "ACI syntax");
+    assertFalse(doc.contains("<xinclude:include"), "DocBook xinclude leftover");
+    assertFalse(doc.contains("<olink"), "DocBook olink leftover");
+    assertFalse(doc.contains(".Lower limit") || doc.contains(".Upper limit"), "duration sentences glued together");
+  }
+
   private int dsconfigMain(String[] args)
   {
     return DSConfig.main(args, System.out, System.err);