slachiewicz opened a new pull request, #151:
URL: https://github.com/apache/maven-doxia-converter/pull/151
Follow-on to #149, which merged while this commit was being written — it is
the same work, just
missed the merge window, so it is rebased onto current `master` here.
Four more failures from the ongoing migration, all the same shape: green
build, unchanged text,
damage in markup the text comparison does not inspect.
### Two arrived as field reports that did not reproduce as described
Both are on the page in their corrected form, checked here before writing.
**The info string.** The report was that the converter emits ` ```unknown `
for *both* APT
verbatim forms, so substituting a language over-boxes. It does not.
Converting a fixture holding
both forms:
| source | output |
|---|---|
| APT `+---+` | ` ```unknown ` |
| APT `---` | bare fence |
| xdoc `<source>` | ` ```unknown ` |
| xdoc `<pre>` | bare fence |
The converter already distinguishes them. The real error is the inverse —
adding a language to a
fence it left bare, which boxes a block the source deliberately left
unboxed. Console
transcripts and log samples are both the usual unboxed form and the most
tempting thing to
label ` ```bash `. The page now says to key on the literal `unknown` and
nothing else.
**The anchors.** The report was that an `<a name="…">` on its own line gets
wrapped in a `<p>`
and costs the *following* heading its generated id, the fix being to glue
the anchor to the end
of the preceding block. Headings kept their ids in every arrangement I
tried, and the glued form
did not survive either. A controlled pair, same line, same position, only
the attribute differs:
```
<a name="x"></a> -> (nothing at all)
<a id="x"></a> -> <a id="x"></a>
<a name="x" id="x"></a> -> <a id="x"></a>
```
The obsolete `name` attribute is dropped; that leaves an element with no
attributes and no
content, and it is discarded. The anchor is **deleted outright** rather than
displaced — same
visible symptom, different cause, and a fix that works: write `id`.
Also documented there: a raw `<pre>` gains no classes, so hand-written
blocks need
`<pre class="prettyprint linenums"><code>` spelled out; and there is no
`{#id}` attribute syntax
for headings — the braces stay in the text and get percent-encoded into the
id.
### The other two
**What the comparison cannot see.** `tools/normalize-site-page.py` drops
every attribute but
`href` — that is what makes it quiet enough to read — so `<pre
class="prettyprint linenums">`
and a bare `<pre>` compare equal, an `<a>` with no `href` leaves no token,
and `<ol>` and `<ul>`
are both `[ITEM]`. A tree-wide unboxing passes on every page. Added a second
structural pass over
the tag sequence and the anchor id set, with a recipe run against this
project's own pages. This
is not a defect in the script; a normaliser that kept attributes would be
unreadable.
**The escaping rule, stated properly.** Escaping is needed only where the
page *displays* a
reference **and** the name *resolves* — now a small table.
Displayed-and-unresolvable
(`${basedir}`, `${surefire.forkNumber}`) passes through either way;
resolved-and-displayed
(`${project.build.outputDirectory}`) is the only bug, and it publishes an
absolute path from
whichever machine built the site.
### Verification
`mvn verify`: BUILD SUCCESS, RAT 0 unapproved, 23/23 tests. `mvn site`: all
ten `<h2>`, the new
`<h3>` and the table render. JDK 21, Maven 3.9.16, macOS only — CI on the
push is the real check.
Generated with assistance from Claude Opus 5.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
