slachiewicz opened a new pull request, #149:
URL: https://github.com/apache/maven-doxia-converter/pull/149
Two gaps in `migrating-apt-to-markdown.md`, both found while converting this
project's own site
in #148. Each is a way to follow the page *correctly* and still damage the
result, and both are
invisible in the converted Markdown.
### 1. `` ```unknown `` is load-bearing
The converter writes an info string of `unknown` for a boxed APT block
(`+-----+`). It reads
like a placeholder it failed to fill in, so deleting it is the obvious
tidy-up. It is also what
silently unboxes the block, because the Markdown parser treats **any
non-empty** info string as
the boxed flag.
Measured on `usage.md.vm`, same block, only the info string changed:
```
```java -> <pre class="prettyprint linenums"><code class="language-java">
```xml -> <pre class="prettyprint linenums"><code class="language-xml">
(none) -> <pre><code class="nohighlight nocode">
```
The visible text is identical either way, so a body-only comparison passes
and the build stays
green — only the box and the line numbers are gone. The page now says to
replace `unknown` with
the language the block actually is, never to delete it; that keeps the box
and adds the
highlighting the placeholder never had.
### 2. The advice to trust the converter's warnings inverts on an
already-`.vm` source
The page says *"watch its output rather than hunting for these by hand."* On
a source that was
already `*.apt.vm` the converter cannot tell a reference the page wants to
**show** from one it
wants to **resolve**, and warns about both. Converting `usage.apt.vm` emits:
```
WARN "${project.version}" was written literally in the source but is a live
Velocity
reference in "usage.md.vm", so escape it there
```
That reference is deliberately live — it renders the current version into
the sample command
lines, and it did so in the APT source too. A reader following the page's
advice would escape it
with `${esc.d}` and publish the literal text `${project.version}` instead of
the version.
Also documented: shell prompts inside code blocks (`# java -jar ...`) get
reported as Velocity
directives. A `#` followed by a space is literal to Velocity, so they are
safe.
### Verification
`mvn site`: the new `<h2>` renders, and the four-backtick fences containing
three-backtick
examples render as literal text rather than nesting. `${project.version}`
appears literally 7
times and is not interpolated (this page is `.md`, not `.md.vm`). `mvn
verify`: BUILD SUCCESS,
RAT 0 unapproved, 23/23 tests — JDK 21, Maven 3.9.16, macOS only. CI on the
push is the real
check.
### Unrelated observation for whoever owns the download page
While comparing, `download.html` rendered as *"Apache Maven Example Plugin
3.2.1"* in one build
and *"Doxia Tools :: Converter 1.4-SNAPSHOT"* in another, from identical
sources — it depends on
local repository state, not on the tree. I confirmed it is not caused by
this change by building
pristine `origin/master`, which is byte-identical to this branch for that
page. Flagging it
because `src/site/xdoc/download.xml.vm` is untouched here and someone is
looking at that page
separately.
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]
