[#1131] Escape the option placeholders of the generated reference, so AsciiDoc no longer reads them as missing attributes - #1142
Merged
vharseko merged 1 commit intoOct 1, 2026
Conversation
…erated reference, so AsciiDoc no longer reads them as missing attributes
The generated reference wrote option value placeholders such as {name},
{unit} or {property} as they are in the messages, and AsciiDoc read each
of them as a reference to a missing attribute: 3,521 warnings over the
220 generated man pages, about 99% of the site build log.
Every template of the generated reference, those of opendj-cli and those
DSConfig applies, goes through DocGenerationHelper.applyTemplate, which
now escapes each attribute reference of the result with a backslash.
A reference already escaped is left as is, since the templates nest (a
subcommand section inside the subcommands section inside the page), and
word characters are Unicode ones, as in Asciidoctor ({données} in the
French bundle). Text such as {PROP:VALUE} or {name=value} is no attribute
reference and stays as it is.
The rendered pages do not change: with attribute-missing=warn, the html5
and manpage output of all 220 pages is byte for byte the same as before,
without the warnings.
maximthomas
approved these changes
Oct 1, 2026
maximthomas
left a comment
Contributor
There was a problem hiding this comment.
praise: The escape sits at the one place every generated reference page passes through.
- All 12 template calls (
ArgumentParser×2,SubCommandArgumentParser×6,DSConfig×4) go throughDocGenerationHelper.applyTemplate, so the single change atDocGenerationHelper.java:83covers the dsconfig pages too. - The
(?<!\\)lookbehind keeps nested templates from escaping twice, andsubcommandReferenceEscapesPlaceholdersOncepins it withdoesNotContain("\\\\{"). {PROP:VALUE}and{name=value}are asserted unchanged in both cases.
This was referenced Oct 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1131
The generated reference wrote option value placeholders (
{name},{unit},{property}, …) as they are in the messages, and AsciiDoc read each of them as a reference to a missing attribute — 3,521 occurrences over the 220 generated man pages, the ~3,500skipping reference to missing attributewarnings of the site build.ArgumentParser/SubCommandArgumentParserapply and thoseDSConfigapplies — goes throughDocGenerationHelper.applyTemplate, which now escapes each attribute reference of the result with a backslash (\{name}). The.ftltemplates,GenerateRefEntriesMojoandAsciidocConverterUtilsare unchanged.\\{name}.{données}.{PROP:VALUE},{name=value}and the like are no attribute references in AsciiDoc and stay as they are.:attribute-missing: skipin each partial was not used: set in an included partial, it would change the setting for the rest of the including page as well.Verification
DocGenerationHelperTestCase: a tool without and a tool with subcommands, throughgetUsage()in gendoc mode; red before the fix, and red again with the "already escaped" lookbehind removed.opendj-doc-generated-ref/pom.xml(220 pages, dsconfig split) the wayGenerateRefEntriesMojodoes, before and after: 3,521 unescaped references → 0, each escaped exactly once; unescaping the result gives back the original pages byte for byte.html5andmanpagebackends,-a attribute-missing=warnas Antora sets it: 6,451 missing-attribute warnings → 0; the HTML and man output is byte for byte the same as before,{name}still shown as is.opendj-cli(48) andopendj-core(8,182) tests pass; javadoc builds.Not in this PR: 920 of the
{unit}occurrences come from another defect — in thedsconfig list-*/get-*subcommands, every option that handles no property (--unit-size,--unit-time,--property) gets the whole subtype list "… depends on the {unit} you provide", not only the name option.