slachiewicz opened a new pull request, #140:
URL: https://github.com/apache/maven-doxia-converter/pull/140
A `*.vm` file only becomes valid Doxia markup after Velocity has run over
it. The converter, however, hands the unprocessed source straight to the
parser, which mangles everything it does not understand. This is three related
changes that make such a source survive a conversion.
### Keep Velocity constructs intact when converting a `*.vm` source
`${project.name}` used as a section title came out of the conversion as `#
$<a id="project.name"></a>project.name`, and `#set( $prefix = '.' )` came out
as escaped body text. References, whole directive lines and `#* *#` block
comments are now replaced with an opaque placeholder before parsing and
substituted back afterwards. This is only applied when the input file name ends
in `.vm`.
A reference is put back exactly where it was. A directive occupying a whole
line survives, but the parser may reposition it relative to the surrounding
blocks, so those are logged as a warning rather than being silently moved.
### Warn when conversion turns literal text into a live Velocity reference
APT writes `$\{foo\}` in order to show `${foo}` as literal text, and the
parser unescapes it. The converted `*.vm` therefore ends up holding a live
reference that Velocity resolves at rendering time. In
maven-shared-reporting-exec this produced
`[org.apache.maven.model.ReportPlugin@c754401]` on a page that was documenting
`${project.reporting.plugins}` as text.
The masker knows which references it took out of the source, so any
reference present in the converted document that was not one of them is
reported.
### Make a masked reference still look like a URL
A reference frequently opens a link destination, as in
`{{{${project.scm.url}/src/main/resources/DISCLAIMER.vm}DISCLAIMER.vm}}`. A
parser decides from the shape of the destination whether it is looking at a
link or at an in-page anchor; with the reference replaced by a placeholder made
of bare letters, the destination looked like neither and was mangled into an
anchor. The placeholder now carries `://` so that such a destination is still
recognised as a URL.
---
New tests are in `VelocityMaskerTest`.
This is part of the wider APT to Markdown migration tracked in
https://github.com/apache/maven-doxia-converter/issues/139.
--
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]
