#!/usr/bin/env bash
# $Id: man2htmldoc 78 2026-11-03 07:28:32Z peter $
#
# 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 Index.org).
#
# Copyright (C) 2026 Péter Felecan
#
# This program is free software: you can redistribute it and/or
# modify it under the terms of the GNU General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# 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

if [ $# -ne 2 ]; then
    echo "usage: man2htmldoc SRC.1 DEST.html" >&2
    exit 2
fi
src="$1"
dest="$2"
if [ ! -r "$src" ]; then
    echo "man2htmldoc: cannot read $src" >&2
    exit 1
fi

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), from packpay (2026-08-18): without it, groff
# assumes a Latin-1-family input encoding and mis-renders UTF-8
# multi-byte characters byte by byte ("café" came out as "cafÃ©").
# Every man page of the project is UTF-8 source, so this is the
# default, not a per-page opt-in.
# groff is run on its own, its status looked at: in a pipe its failure
# (on Debian, groff-base has the program and no HTML device) was lost, the
# page written was empty, and the script said that it had written it
# (0.39.0). The page is written to a file of its own and put in place
# when complete.
tmp="$dest.tmp.$$"
trap 'rm -f "$tmp" "$tmp.html"' EXIT HUP INT TERM
if ! groff -mandoc -Kutf8 -Thtml "$src" > "$tmp.html"; then
    echo "man2htmldoc: groff could not write HTML for $src (on Debian the package groff has the HTML device, groff-base has not)" >&2
    exit 1
fi
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 US-ASCII even under -Kutf8 (it emits
    # entities, not raw UTF-8). Declared UTF-8 anyway: the page is
    # spliced with our own UTF-8 text (the index back-link) and lives
    # beside the other UTF-8 HTML of the project (no apostrophe here:
    # this comment is inside the single-quoted awk program).
    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 }
' "$tmp.html" > "$tmp"
mv -f "$tmp" "$dest"

echo "man2htmldoc: wrote $dest"
