tags.rb: substitute AsciiDoc attributes in tagged inline text - #260
Merged
Bill Traynor (wmat) merged 2 commits intoSep 1, 2026
Conversation
Asciidoctor applies substitutions at the block level in the order
specialcharacters, quotes, attributes, replacements, macros,
post_replacements. Inline nodes are produced by the quotes pass, so their
text has only had specialcharacters applied and an attribute reference such
as `{ge}` reached the tags JSON unresolved.
PR #131 fixed that by replaying the parent block's whole sub list over the
inline text, which also ran the three passes after `attributes`: apostrophes
became `’`, `[.underline]` was dropped, and `<<xref>>` cross references
were deleted outright. That was a net loss and was reverted in PR #170.
Apply only the attributes substitution instead. Nested formatting is
unaffected because bold, italics, underline and friends are separate inline
nodes that reach the converter in their own right.
The expanded value keeps the post-specialcharacters escaping the rest of this
file already uses, so `:ge: ≥` yields `&#8805;` exactly as an
author-written `≥` does today (see norm:unicode_decimal_value), and
create_normative_rules.py renders both as the same character.
Adds three test cases covering attribute expansion inside nested formatting,
attribute expansion alongside an apostrophe and a cross reference, and an
undefined attribute being left alone.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Bill Traynor <wmat@greenmonkeylabs.com>
Collaborator
Author
|
Jordan Carlin (@jordancarlin) would you mind checking this one? I think both James and Tim have moved on from this. |
Jordan Carlin (jordancarlin)
left a comment
There was a problem hiding this comment.
I think long term we should think about simplifying a lot of this, but this seems fine for now.
Bill Traynor (wmat)
force-pushed
the
169-substitute-asciidoc-attributes-in-tagged-text-without-rewriting-other-inline-markup
branch
from
September 1, 2026 20:38
65f13a8 to
c4bb4b5
Compare
riscv-isa-manual removed the only consumer in riscv/riscv-isa-manual#3334: the check-normative-tags workflow, the committed ref/riscv-spec-norm-tags.json and the supporting scripts all went, because the reference copy existed only to raise automated issues and those are no longer wanted. Nothing else calls the script - it has no importers, appears in no workflow here, and the only remaining references were this Makefile and the tools README. Normative rules are still built in CI and shipped in every release; that path goes through create_normative_rules.py and is untouched. This also retires test-tag-changes-update, which has been failing since PR #248 removed the --update-reference flag the target still passed. `make test` now exits 0. Recoverable from history if the review aid is ever wanted back. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: Bill Traynor <wmat@greenmonkeylabs.com>
Jordan Carlin (jordancarlin)
approved these changes
Sep 1, 2026
Bill Traynor (wmat)
deleted the
169-substitute-asciidoc-attributes-in-tagged-text-without-rewriting-other-inline-markup
branch
September 1, 2026 21:34
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 #169.
Two commits: the attribute-substitution fix, and the removal of
detect_tag_changes.pyper Jordan Carlin (@jordancarlin)'s review.1. The problem
Asciidoctor applies substitutions at the block level, in this order:
specialcharacters,quotes,attributes,replacements,macros,post_replacements. Inline nodes are produced by thequotespass, so theirtext has only had
specialcharactersapplied — an attribute reference such as{ge}reached the tags JSON unresolved, and there is no built-in way to ask aninline node for its substituted text.
PR #131 fixed that by replaying the parent block's whole sub list over the
inline text. That also ran the three passes after
attributes, which is whatmade it a net loss and got it reverted in PR #170:
replacementsrewrote apostrophes to’[.underline]was dropped<<xref>>cross references were deleted outrightThe fix applies only the attributes substitution. Nested formatting is
unaffected, because bold, italics, underline and friends are separate inline
nodes that reach the converter in their own right — they never pass through
this code path as raw text.
Verified against riscv-isa-manual
Built
make build-tagsonriscv-isa-manualatmainwith the submodule oneach revision. No warnings under
--failure-level=WARN. Of 2923 tags, 38change, all of them attribute expansions; the tag set is identical and
nothing else moves. Cross references survive (
<<translation>>innorm:sfence_vma_asid_only), apostrophes stay literal (two's,entry i's),and superscripts and
insn:/csr:/ext:macros are untouched:A note on escaping
{ge}expands to≥becausesymbols.adocdefines it as literal Unicode.{endash},{emdash}and{asterisk}are defined as character referencesinstead, so they expand to the
&-escaped form —&#8205;&#8211;&#8205;.That looks like over-escaping but is the consistent result: every string this
backend emits sits at the post-
specialcharactersstage (<<,&),and an author-written
≥already produces&#8805;today — seenorm:unicode_decimal_value. Both spellings render identically throughcreate_normative_rules.py.Tests
Three cases added to
tests/norm-rule/test-ch1.adoc, pinning all threeregressions from #169 plus the attribute-missing default:
Attribute expands through nested formatting; apostrophe stays literal; cross
reference survives; an undefined attribute is left alone.
2. Deleting detect_tag_changes.py
riscv/riscv-isa-manual#3334 removed the only consumer — the
check-normative-tags workflow, the committed
ref/riscv-spec-norm-tags.jsonand the supporting scripts — because the reference copy existed only to raise
automated issues, and those are no longer wanted. Nothing else calls the
script: no importers, no workflow here, and the only remaining references were
this Makefile and the tools README.
Normative rules are still built in CI and shipped in every release. That path
goes through
create_normative_rules.pyand is untouched.This also retires
test-tag-changes-update, which has been failing sincePR #248 removed the
--update-referenceflag the target still passed.Result
make testexits 0 from a cleanbuild/— 16 assertions, 0 failures, no makeerrors, for the first time since #248.
🤖 Generated with Claude Code