Skip to content

preprocess md man files to improve cross-links #956

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
comick wants to merge 1 commit into
base: main
Choose a base branch
from
+40 −1
Open

preprocess md man files to improve cross-links #956

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 40 additions & 1 deletion common/docs/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,50 @@ PREFIX := /usr/local
DATADIR := ${PREFIX}/share
MANDIR := $(DATADIR)/man
GOMD2MAN ?= $(shell command -v go-md2man || echo '$(GOBIN)/go-md2man')
ifeq ($(NATIVE_GOOS),freebsd)

@mtrmac mtrmac Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NATIVE_GOOS is never set

SED=gsed
GREP=ggrep
MAN_L= mandoc
else
SED=sed
GREP=grep
MAN_L= man -l
endif

docs: $(patsubst %.md,%,$(wildcard *.md))

%.5: %.5.md
$(GOMD2MAN) -in $^ -out $@
# This does a bunch of filtering needed for man pages:
# 1. Convert all markdown site links to plain text:
# [foo](https://www.....) -> foo
# 2. Strip man-page targets like '[podman(1)](podman.1.md)'
# to just '[podman(1)]', because man pages have no link mechanism;
# 3. Then remove the brackets: '[podman(1)]' -> 'podman(1)';
# 4. Remove HTML-ish stuff like '<sup>..</sup>' and '<a>..</a>'
# 5. Replace "\" (backslash) at EOL with two spaces (no idea why)
# Then two sanity checks:
# 1. test for "included file options/blahblah"; this indicates a failure
# in the markdown-preprocess tool; and

@mtrmac mtrmac Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No markdown-preprocess here.

# 2. run 'man -l' against the generated man page, and check for tables
# with an empty right-hand column followed by an empty left-hand
# column on the next line. (Technically, on the next-next line,
# because the next line must be table borders). This is a horrible
# unmaintainable rats-nest of duplication, obscure grep options, and
# ASCII art. I (esm) believe the cost of releasing corrupt man pages
# is higher than the cost of carrying this kludge.
#
@$(SED) -e 's/\[\([^]]*\)](http[^)]\+)/\1/g' \
-e 's/\((podman[^)]*\.md\(#.*\)\?)\)//g' \
-e 's/\[\(podman[^]]*\)\]/\1/g' \
-e 's;<\(/\)\?\(a\|a\s\+[^>]*\|sup\)>;;g' \
-e 's/\\$$/ /g' $^ |\
$(GOMD2MAN) -out $@
@if grep 'included file options/' $@; then \
echo "FATAL: man pages must not contain ^^^^ in $@"; exit 1; \
fi
@if $(MAN_L) $@| $(GREP) -Pazoq '│\s+│\n\s+├─+┼─+┤\n\s+│\s+│'; then \
echo "FATAL: $< has a too-long table column; use 'man -l $@' and look for empty table cells."; exit 1; \
fi

.PHONY: install
install:
Expand Down
Loading