From a9eb94474ab4b8478da8d55e2d15dfb5bef2ab0c Mon Sep 17 00:00:00 2001
From: Valery Kharseko <vharseko@3a-systems.ru>
Date: Thu, 01 Oct 2026 10:18:13 +0000
Subject: [PATCH] [#1131] Escape the option placeholders of the generated reference, so AsciiDoc no longer reads them as missing attributes (#1142)
---
opendj-cli/src/main/java/com/forgerock/opendj/cli/DocGenerationHelper.java | 28 +++++++++++++++++++++++++++-
1 files changed, 27 insertions(+), 1 deletions(-)
diff --git a/opendj-cli/src/main/java/com/forgerock/opendj/cli/DocGenerationHelper.java b/opendj-cli/src/main/java/com/forgerock/opendj/cli/DocGenerationHelper.java
index b8f410a..5a49e17 100644
--- a/opendj-cli/src/main/java/com/forgerock/opendj/cli/DocGenerationHelper.java
+++ b/opendj-cli/src/main/java/com/forgerock/opendj/cli/DocGenerationHelper.java
@@ -12,6 +12,7 @@
* information: "Portions Copyright [year] [name of copyright owner]".
*
* Copyright 2015 ForgeRock AS.
+ * Portions Copyright 2026 3A Systems, LLC.
*/
package com.forgerock.opendj.cli;
@@ -23,6 +24,7 @@
import java.io.OutputStreamWriter;
import java.io.Writer;
import java.util.Map;
+import java.util.regex.Pattern;
/**
* This class provides utility functions to help generate reference documentation.
@@ -38,6 +40,13 @@
private static Configuration configuration;
/**
+ * An AsciiDoc attribute reference, such as {@code {name}}, that no backslash escapes.
+ * Word characters are Unicode ones, as in Asciidoctor.
+ */
+ private static final Pattern ATTRIBUTE_REFERENCE =
+ Pattern.compile("(?<!\\\\)(\\{\\w[\\w-]*\\})", Pattern.UNICODE_CHARACTER_CLASS);
+
+ /**
* Gets a FreeMarker configuration for applying templates.
*
* @return A FreeMarker configuration.
@@ -71,13 +80,30 @@
Writer writer = new OutputStreamWriter(outputStream)) {
Template configurationTemplate = configuration.getTemplate(template);
configurationTemplate.process(map, writer);
- builder.append(outputStream.toString());
+ builder.append(escapeAttributeReferences(outputStream.toString()));
} catch (Exception e) {
throw new RuntimeException(e.getMessage(), e);
}
}
/**
+ * Escapes the AsciiDoc attribute references in generated reference text.
+ *
+ * <br>
+ *
+ * The generated reference refers to no AsciiDoc attribute: a {@code {name}} in it is the placeholder
+ * of an option value, written as is in the messages, which AsciiDoc would read as a reference
+ * to a missing attribute. A reference that is already escaped is left as is,
+ * so the result of a template can go through another template that includes it.
+ *
+ * @param text The generated AsciiDoc text.
+ * @return The text with each attribute reference escaped by a backslash.
+ */
+ static String escapeAttributeReferences(final String text) {
+ return ATTRIBUTE_REFERENCE.matcher(text).replaceAll("\\\\$1");
+ }
+
+ /**
* Returns an option synopsis.
*
* <br>
--
Gitblit v1.10.0