(maven-doxia-converter) 01/01: Compare document metadata as well, not just the rendered body

[sl...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch agent/apt-to-markdown-migration-guide
in repository https://gitbox.apache.org/repos/asf/maven-doxia-converter.git

commit 63c57e04b5f268a21d5d7c91a241d879797b2f43
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Sun Aug 9 23:49:03 2026 +0200

    Compare document metadata as well, not just the rendered body
    
    The normaliser reduced a page to its visible text and link targets, so a
    page that had lost its title, authors and date compared equal. That is
    not hypothetical: it is how a large conversion shipped with the metadata
    of several hundred pages silently dropped.
    
    Emit the <title> and the author/date <meta> content alongside the body,
    and document both halves of the cause: the YAML front matter the
    converter writes carries that metadata and must be kept as the first
    bytes of the file, and a body-only comparison will never notice when it
    is gone.
    
    Generated-by: Claude Opus 5 (1M context)
---
 src/site/markdown/migrating-apt-to-markdown.md | 21 +++++++++++++++++----
 tools/normalize-site-page.py                   | 10 +++++++++-
 2 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/src/site/markdown/migrating-apt-to-markdown.md b/src/site/markdown/migrating-apt-to-markdown.md
index 84c1d4a..3a19045 100644
--- a/src/site/markdown/migrating-apt-to-markdown.md
+++ b/src/site/markdown/migrating-apt-to-markdown.md
@@ -45,6 +45,13 @@ Pass `-outEncoding UTF-8` explicitly. Without it the output follows the autodete
 encoding, and an ASCII source is detected as ISO-8859-1; an APT escaped space (`\ `, which
 becomes U+00A0) is then written as a lone `0xa0` byte.
 
+**Keep the YAML front matter the converter writes.** It carries the title, authors and date
+from the APT header, and the skin renders them into `<title>` and `<meta>`. Delete it and the
+parser falls back to the first heading for the title, so a page headed *Release Notes* under
+project *Modello* silently retitles itself `Modello – Modello`. The front matter must be the
+**first bytes of the file** — the parser only looks for it when the source starts with `---`,
+so the licence header goes below it. RAT accepts either order.
+
 ## Velocity and Markdown disagree about `#`
 
 A Markdown ATX heading below level one starts with `##`, which is also how a Velocity line
@@ -124,16 +131,22 @@ not "fix" these back:
 
 Comparing raw HTML is too noisy to be useful: `<b>` becomes `<strong>`, `<i>` becomes `<em>`,
 attribute order changes, and `<code>` and `<a>` nest the other way round. Reduce each page to
-its visible text plus its link targets and compare that instead. A script that does so ships
-with this project as `tools/normalize-site-page.py`:
+the parts that carry meaning — its title, author and date metadata, its visible text and its
+link targets — and compare that instead. A script that does so ships with this project as
+`tools/normalize-site-page.py`:
 
 ```
 diff <(tools/normalize-site-page.py before/index.html) \
      <(tools/normalize-site-page.py after/index.html)
 ```
 
-Two mistakes are easy to make when scripting the comparison and both produce a reassuring
-but meaningless result:
+**Compare the `<head>`, not just the body.** An APT header carries the document's title,
+authors and date, and the skin turns them into `<title>` and `<meta name="author">` /
+`<meta name="date">`. A normaliser that reduces a page to its rendered body will pass a page
+that has lost all of it. This is the single easiest way to ship a migration that looks
+perfect and is not: the body matches on every page while the metadata quietly disappears.
+
+Two further mistakes produce a reassuring but meaningless result:
 
 * **Check the exit status of `mvn site`.** A failed build leaves the previous output in
   `target/site`, so a comparison against it reports no difference at all.
diff --git a/tools/normalize-site-page.py b/tools/normalize-site-page.py
index ff7fb97..bfe496a 100755
--- a/tools/normalize-site-page.py
+++ b/tools/normalize-site-page.py
@@ -34,6 +34,14 @@ import sys
 
 html = io.open(sys.argv[1], encoding="utf-8", errors="replace").read()
 
+# The document's metadata is part of what the migration must not change: the APT header
+# carries the title, authors and date, and the skin turns them into <title> and <meta>.
+# Comparing only the rendered body hides a page that has lost them, which is exactly how
+# a migration once dropped the metadata of 387 pages without any comparison noticing.
+meta = ["[TITLE:%s]" % t for t in re.findall(r"<title>([^<]*)</title>", html)]
+meta += ["[META:%s=%s]" % (k, v) for k, v in
+         re.findall(r'<meta name="(author|date)" content="([^"]*)"', html)]
+
 # the skin wraps the document; only the rendered document itself is of interest
 match = re.search(r"<main.*?</main>", html, re.DOTALL)
 body = match.group(0) if match else html
@@ -56,4 +64,4 @@ body = body.replace("&#x2026;", "...").replace("…", "...")
 body = body.replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&")
 body = re.sub(r"\s+", " ", body).strip()
 
-sys.stdout.write("\n".join(body.split(" ")))
+sys.stdout.write("\n".join(meta + body.split(" ")))