#!/usr/bin/env bash
# man2htmldoc --- convert a project groff man page to a styled standalone
# HTML page matching the look of the Org-exported documentation
# (same body font/width and link colour as Doc/Index.org).
#
# Usage:  man2htmldoc SRC.1 DEST.html
#
# This is NOT the man2html(1) from the man2html-base package: that tool is
# a CGI helper --- it emits an HTTP "Content-type:" header line and a
# hardcoded "Return to Main Contents" link to /cgi-bin/man/man2html, with
# no option to suppress either or to inject our styling and our index
# back-link. We need a clean static page wired into the documentation set,
# so we keep this small converter under a distinct name to avoid any PATH
# clash with the packaged tool.
#
# Depends only on groff (mandoc macros) and awk --- both universally
# available wherever the rest of the toolchain runs. No external CSS or
# network resource: the page is self-contained so it survives being moved
# into the distribution archive alongside the other *.html files.

set -eu

src="$1"
dest="$2"

if ! command -v groff >/dev/null 2>&1; then
    echo "man2htmldoc: groff not found; cannot convert $src" >&2
    exit 1
fi

# groff -Thtml emits a complete <html> document with its own <style>.
# We append our stylesheet and an index back-link just before </head>,
# so our rules win by cascade order. awk does the injection portably.
#
# -Kutf8 (input encoding) ADDED 2026-08-18, a real bug found while
# converting this project's own first real man page (netlist.1):
# without it, groff assumes a Latin-1-family input encoding and
# mis-renders any real UTF-8 multi-byte character byte-by-byte --
# confirmed directly, not guessed: "Péter" (the AUTHOR section's own
# real accented name, used verbatim throughout this project's other
# documentation) came out as the mojibake "PÃ©ter" without this flag,
# and correctly as "Péter" (via the real HTML entity &eacute;) with
# it. Every man page this project ships is real UTF-8 source (the
# same encoding every other document in this project already uses),
# so this is the correct default, not a per-page opt-in.
groff -mandoc -Kutf8 -Thtml "$src" | awk '
/<\/head>/ {
    print "<style>"
    print "  body { font-family: sans-serif; max-width: 760px; margin: 2em auto; }"
    print "  h1   { border-bottom: 2px solid #444; padding-bottom: 0.3em; }"
    print "  h2   { margin-top: 1.5em; color: #222; }"
    print "  a    { color: #0055aa; }"
    print "  pre, code { font-family: monospace; }"
    print "  hr   { display: none; }"
    print "</style>"
    print "</head>"
    next
}
/<meta http-equiv="Content-Type"/ {
    # groff -Thtml declares this charset from its OUTPUT encoding
    # decision, which (confirmed directly, 2026-08-18) stays
    # "US-ASCII" even under -Kutf8 above -- groff transcodes real
    # non-ASCII input into plain-ASCII HTML entities (&eacute; etc.)
    # rather than emitting raw UTF-8 output bytes, so the US-ASCII
    # claim is technically accurate for what groff itself emits.
    # Corrected to UTF-8 anyway: this page is spliced together with
    # OUR OWN literal UTF-8 text below (the index back-link) and
    # lives alongside this project own other real UTF-8 HTML
    # (Concept.html and its own Devanagari project-name quote), so a
    # per-page US-ASCII claim would be actively wrong in context even
    # where groff itself, immediately, does not need it.
    print "<meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\">"
    next
}
/<body>/ {
    print
    print "<p style=\"max-width:760px;margin:0.5em auto;font-size:90%;\"><a href=\"Index.html\">&larr; Documentation index</a></p>"
    next
}
{ print }
'  > "$dest"

echo "man2htmldoc: wrote $dest"
