slachiewicz commented on issue #139:
URL:
https://github.com/apache/maven-doxia-converter/issues/139#issuecomment-5198504236
## Progress update
308 of 729 site APT documents converted, 421 remaining (of which about 300
are in scope; the rest are the archived SVN sandbox,
`codehaus-plexus.github.io` and the Maven 3 branches).
Converted since the issue was opened: 31 repositories in the small-plugin
tranche and 12 in the mid-size tranche, roughly 300 pages. Each is a single
commit on a `site-apt-to-markdown` branch, verified by building the site before
and after and comparing the visible text and link targets of every generated
page.
### Further traps found
**A backslash does not reliably escape a reference.** `\${foo}` only renders
as `${foo}` when `foo` resolves in the document's Velocity context; when it
does not, Velocity emits the backslash too and the page shows `\${foo}`.
`${esc.d}{foo}` always yields a literal dollar and is what these pages now use.
138 occurrences were affected.
**An APT table caption has no Markdown equivalent.** `<caption>` is dropped
and the caption text ends up as a paragraph after the table.
**Intraword emphasis does not survive.** The sink writes `_x_`, which
CommonMark does not treat as emphasis when it follows a word character, so
`Set<i>String</i>` rendered as literal `Set_String_`. Only one page was
affected, and there the APT rendering was itself wrong: the source meant the
Java type `Set<String>` and APT had read the angle brackets as italic markup.
**Bold ending in an asterisk.** `**maven.source.***` parses as
`**maven.source.**` followed by a stray `*`.
**A non-UTF-8 output file.** The converter follows the autodetected input
encoding, and an ASCII source is detected as ISO-8859-1, so an APT escaped
space (which becomes U+00A0) is written as a lone `0xa0` byte. Passing
`-outEncoding UTF-8` avoids it.
### Worth noting
Several differences the comparison flagged turned out to be pre-existing
faults in the APT rendering that the conversion repairs:
- `{{{#Identity Mapper}Identity Mapper}}` rendered as `href="#Identity
Mapper"` pointing at `id="Identity_Mapper"`, so the link never resolved.
- `<<<${basedir}/...>>>` rendered as `$<a id="basedir">basedir</a>/...`, an
anchor APT invented from the braces.
- `<<<\<overlay\>>>>` rendered with an anchor spliced into the middle of the
code span.
The accepted remaining differences are `<b>`/`<i>` becoming
`<strong>`/`<em>`, and quotes and ellipses in prose picking up the Markdown
module's typographic substitution. Code spans and code blocks are left alone by
that substitution.
--
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]
