Skip to content

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

Open
vharseko wants to merge 2 commits into
OpenIdentityPlatform:masterfrom
vharseko:issue-1128-docs-xinclude
Open

vharseko wants to merge 2 commits into
OpenIdentityPlatform:masterfrom
vharseko:issue-1128-docs-xinclude

Conversation

@vharseko

Copy link
Copy Markdown
Member

Fixes #1128

The generated reference still carried DocBook markup from before the AsciiDoc migration; Asciidoctor printed it as text, and the link checker of doc.openidentityplatform.org reported the href targets as broken.

Where Occurrences Was Now
dsconfig property, "Allowed Values" of a duration 244 <xinclude:include href="itemizedlist-duration.xml" /> inline text naming the units (ms, s, m, h, d, w)
dsconfig property, "Allowed Values" of an ACI (global-aci) — not listed in the issue, same kind of leftover 2 <olink targetdoc="admin-guide" targetptr="about-acis" /> xref:../admin-guide/chap-privileges-acis.adoc#about-acis[…], in the form admin-tools-ref.adoc already uses
upgrade description 1 <xinclude:include href="description-upgrade.xml" /> include::./_description-upgrade.adoc[] (new partial)
backendstat show-index-status 1 <xinclude:include href="variablelist-backendstat-index-status.xml" /> include::./_variablelist-backendstat-index-status.adoc[] (new partial)
  • The duration and ACI values sit inside the "Allowed Values" item of a description list in an open block, where an included list would break the markup 244 times and an xref to another page degrades to plain text in the man pages; the duration syntax is therefore written inline. The message keys drop their _REL_URL suffix (REF_DSCFG_ACI_SYNTAX, REF_DSCFG_DURATION_SYNTAX), ordinals unchanged; there are no localized copies.
  • The upgrade and backendstat supplements follow the pattern already used for _description-rate-tools.adoc and _description-psearch-info.adoc. The backendstat partial describes the current output rather than the 3.x DocBook one: the subcommand is show-index-status, and the columns are Raw DB Name, Valid, Confidential, Over Entry Limit.
  • visitDuration also glued its sentences together ("Lower limit is 0 seconds.Upper limit is …", 85+ times on the site); they are now separated by a space.

Verification

  • Generated man-dsconfig.adoc, man-upgrade.adoc and man-backendstat.adoc the way GenerateRefEntriesMojo does (gendoc --help on the packaged server classpath). Before: 244 duration + 2 olink leftovers in dsconfig, matching the published page, and one each in upgrade and backendstat. After: none.
  • Rendered the upgrade and backendstat pages and two dsconfig subcommands with AsciidoctorJ 2.5.3, html5 and manpage backends: both includes resolve, no warnings, the xref becomes ../admin-guide/chap-privileges-acis.html#about-acis.
  • The full Antora site build was not run locally.

…ftovers of the generated reference with AsciiDoc

The duration and ACI syntaxes of dsconfig properties now read as text and an
xref to "About Access Control Instructions"; the upgrade and backendstat
show-index-status supplements include new AsciiDoc partials, updated to the
current columns. Duration limits are separated by a space.
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: DocBook xinclude leftovers in the generated reference

1 participant