Skip to content

[#1131] Escape the option placeholders of the generated reference, so AsciiDoc no longer reads them as missing attributes - #1142

Merged
vharseko merged 1 commit into
OpenIdentityPlatform:masterfrom
vharseko:issue-1131-escape-reference-placeholders
Oct 1, 2026
Merged

vharseko merged 1 commit into
OpenIdentityPlatform:masterfrom
vharseko:issue-1131-escape-reference-placeholders

Conversation

@vharseko

Copy link
Copy Markdown
Member

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,500 skipping reference to missing attribute warnings of the site build.

  • Every template of the generated reference — those ArgumentParser/SubCommandArgumentParser apply and those DSConfig applies — goes through DocGenerationHelper.applyTemplate, which now escapes each attribute reference of the result with a backslash (\{name}). The .ftl templates, GenerateRefEntriesMojo and AsciidocConverterUtils are unchanged.
  • A reference already escaped is left as is: the templates nest (a subcommand section inside the subcommands section inside the page), and escaping each level again would give \\{name}.
  • Word characters are Unicode ones, as in Asciidoctor: the French bundle has {données}.
  • {PROP:VALUE}, {name=value} and the like are no attribute references in AsciiDoc and stay as they are.
  • :attribute-missing: skip in 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, through getUsage() in gendoc mode; red before the fix, and red again with the "already escaped" lookbehind removed.
  • Generated all 34 tools listed in opendj-doc-generated-ref/pom.xml (220 pages, dsconfig split) the way GenerateRefEntriesMojo does, before and after: 3,521 unescaped references → 0, each escaped exactly once; unescaping the result gives back the original pages byte for byte.
  • Rendered all 220 pages with AsciidoctorJ 2.5.3, html5 and manpage backends, -a attribute-missing=warn as 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) and opendj-core (8,182) tests pass; javadoc builds.
  • The full Antora site build was not run locally.

Not in this PR: 920 of the {unit} occurrences come from another defect — in the dsconfig 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.

…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 maximthomas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 through DocGenerationHelper.applyTemplate, so the single change at DocGenerationHelper.java:83 covers the dsconfig pages too.
  • The (?<!\\) lookbehind keeps nested templates from escaping twice, and subcommandReferenceEscapesPlaceholdersOnce pins it with doesNotContain("\\\\{").
  • {PROP:VALUE} and {name=value} are asserted unchanged in both cases.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug docs java Changes to Java sources

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: generated reference writes option placeholders as {name}, producing 3,500 missing-attribute warnings

2 participants