SysTutorials

Man Page Heading Cleanup Tracker

This page tracks man pages cleaned up by removing a redundant leading subtitle heading. The page title and header block already identify the page, so a page should start with content text rather than a redundant subtitle.

Cleanup Rule

Remove the first h2 heading of the body only when both hold:

  1. Its text is one of (case-insensitive): NAME, INTRO, INTRODUCTION, DESCRIPTION, SYNOPSIS
  2. The body does not already start with meaningful text before that heading — i.e. the heading is the very first content

Pages whose body already begins with a text paragraph keep all their headings. In those pages the leading paragraph is the subtitle (previously under a NAME heading, removed in pass 1), and the following SYNOPSIS/DESCRIPTION/… headings are informative section headers that must stay.

Non-exact variants (e.g. DETAILED DESCRIPTION, SYNTAX, C SYNOPSIS) are intentionally kept.

Passes

PassDateScopeFiles changedScript state
1 (#79)2026-11-21All files, one heading per file22,981 (mostly </p> cleanup + uppercase NAME removal)Buggy: no re.IGNORECASE → missed mixed-case headings
2 (this PR)2026-11-21Stragglers only240Fixed: case-insensitive match + “no text before heading” guard

Pass 2 details

Audit after pass 1 found 56,865 files in man-src/:

Post-pass-2 verification: 0 stragglers remain. The script is idempotent (a re-run changes 0 files).

Cleaned Pages (samples)

Man PagePassRemoved HeadingNotes
repo(1)1NAMESample 1
user_namespaces(7)1NAMESample 2
ocf_heartbeat_icp(7)1NAMESample 3
rmic-java-1(1)2Name (mixed case)Straggler from pass 1 regex bug
unopkg(1)2Name (mixed case)Straggler from pass 1 regex bug

Future Use

When re-building man pages, run the script before committing — it only touches files that violate the rule, and is safe to re-run at any time:

python3 scripts/fix-man-headings.py          # verbose
python3 scripts/fix-man-headings.py -q       # quiet (batch)
python3 scripts/fix-man-headings.py man-src/1/s/sort.md   # specific files