#!/bin/sh
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: 2026 Martino Ferrari
#
# The manual's check, the way tools/check_ui.py is the .ui files' check: it runs the four
# yelp-check subcommands that need no network, checks the structural rules below, then renders
# the whole set to HTML with yelp-build so a page that only fails at the transform step is
# caught too.
#
# `yelp-check validate` is deliberately absent, and it is worth being exact about why: it
# builds the RelaxNG schema locally with `xsltproc` and `mal-rng.xsl`, but the schema it
# generates includes the base grammar over the network, so on a machine where fetching is
# blocked it fails for that reason rather than for a fault in the pages.
#
# What that leaves unverified is *structure*, and that is not a small gap: three pages
# carrying a `<figure>` whose `<title>` was a sentence and which had no `<desc>` opened in
# nothing, while links, media, orphans, ids and the HTML render all passed. So the rules this
# project has actually needed are checked here, with xmllint's XPath and no schema at all.
# Add a rule when a page *teaches* one -- and do not add one you have not seen broken: a rule
# that fails a legal page is worse than no rule.
#
# Every expression uses local-name() on purpose. A Mallard page declares
# `xmlns="http://projectmallard.org/1.0/"`, and XPath 1.0 has no default namespace, so
# `//figure` matches *nothing* and every rule below silently passes. Written naively, this
# check reported "ok" for the very defect it was written for.
#
# Exit status is nonzero on the first finding.
set -eu

dir=${1:?usage: check_help.sh HELP_DIR}
if [ ! -f "$dir/index.page" ]; then
  echo "check_help: no index.page under $dir" >&2
  exit 1
fi

tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT

for sub in links media orphans ids; do
  printf 'yelp-check %s %s\n' "$sub" "$dir"
  yelp-check "$sub" "$dir" >/dev/null
done

failed=0
for page in "$dir"/*.page; do
  while IFS='|' read -r what expr; do
    [ -n "$what" ] || continue
    n=$(xmllint --xpath "$expr" "$page" 2>/dev/null || echo "?")
    if [ "$n" != "0" ]; then
      printf '  %s: %s (%s)\n' "$(basename "$page")" "$what" "$n" >&2
      failed=1
    fi
  done <<'RULES'
a figure describes itself|count(//*[local-name()='figure'][not(*[local-name()='desc'])])
a section has a title|count(//*[local-name()='section'][not(*[local-name()='title'])])
info is the page's first child|count(/*[local-name()='page']/*[1][local-name()!='info'])
no text sits directly under page|count(/*[local-name()='page']/text()[normalize-space()])
a media names its src|count(//*[local-name()='media'][not(@src)])
RULES
done
if [ "$failed" != 0 ]; then
  echo "check_help: structural findings above" >&2
  exit 1
fi
printf 'structure %s: ok\n' "$dir"

mkdir -p "$tmp/html"
yelp-build html -o "$tmp/html" "$dir"
pages=$(find "$tmp/html" -maxdepth 1 -name '*.html' | wc -l)
printf 'yelp-build html: %s page(s) rendered\n' "$pages"