From 56039cffd7923d682bd620e5a5a974aabc94dd1b Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 2 Aug 2022 06:02:04 -0600 Subject: Refactor common options in man pages podman-create and -run have many options in common. To date, these are copy-pasted and haphazardly maintained. Solution: add an include mechanism, '@@option foo', such that multiple md source files can fetch from one common file. This is a Phase One commit, a very small subset of what's possible. Purpose of this commit is ease of review. If this passes review, much more (trickier stuff) will be forthcoming. Signed-off-by: Ed Santiago --- Makefile | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) (limited to 'Makefile') diff --git a/Makefile b/Makefile index ad4b0f594..4f222d6d4 100644 --- a/Makefile +++ b/Makefile @@ -77,7 +77,12 @@ BUILDTAGS_CROSS ?= containers_image_openpgp exclude_graphdriver_btrfs exclude_gr CONTAINER_RUNTIME := $(shell command -v podman 2> /dev/null || echo docker) OCI_RUNTIME ?= "" -MANPAGES_MD ?= $(wildcard docs/source/markdown/*.md) +# The 'sort' below is crucial: without it, 'make docs' behaves differently +# on the first run than on subsequent ones, because the generated .md +MANPAGES_SOURCE_DIR = docs/source/markdown +MANPAGES_MD_IN ?= $(wildcard $(MANPAGES_SOURCE_DIR)/*.md.in) +MANPAGES_MD_GENERATED ?= $(MANPAGES_MD_IN:%.md.in=%.md) +MANPAGES_MD ?= $(sort $(wildcard $(MANPAGES_SOURCE_DIR)/*.md) $(MANPAGES_MD_GENERATED)) MANPAGES ?= $(MANPAGES_MD:%.md=%) MANPAGES_DEST ?= $(subst markdown,man, $(subst source,build,$(MANPAGES))) @@ -416,17 +421,24 @@ completions: podman podman-remote pkg/api/swagger.yaml: make -C pkg/api -$(MANPAGES): %: %.md .install.md2man docdir +$(MANPAGES_MD_GENERATED): %.md: %.md.in $(MANPAGES_SOURCE_DIR)/options/*.md + hack/markdown-preprocess $< -### sed is used to filter http/s links as well as relative links -### replaces "\" at the end of a line with two spaces -### this ensures that manpages are renderd correctly +$(MANPAGES): %: %.md .install.md2man docdir - @$(SED) -e 's/\((podman[^)]*\.md\(#.*\)\?)\)//g' \ - -e 's/\[\(podman[^]]*\)\]/\1/g' \ - -e 's/\[\([^]]*\)](http[^)]\+)/\1/g' \ - -e 's;<\(/\)\?\(a\|a\s\+[^>]*\|sup\)>;;g' \ - -e 's/\\$$/ /g' $< | \ +# This does a bunch of filtering needed for man pages: +# 1. Strip markdown link targets like '[podman(1)](podman.1.md)' +# to just '[podman(1)]', because man pages have no link mechanism; +# 2. Then remove the brackets: '[podman(1)]' -> 'podman(1)'; +# 3. Then do the same for all other markdown links, +# like '[cgroups(7)](https://.....)' -> just 'cgroups(7)'; +# 4. Remove HTML-ish stuff like '..' and '..' +# 5. Replace "\" (backslash) at EOL with two spaces (no idea why) + @$(SED) -e 's/\((podman[^)]*\.md\(#.*\)\?)\)//g' \ + -e 's/\[\(podman[^]]*\)\]/\1/g' \ + -e 's/\[\([^]]*\)](http[^)]\+)/\1/g' \ + -e 's;<\(/\)\?\(a\|a\s\+[^>]*\|sup\)>;;g' \ + -e 's/\\$$/ /g' $< |\ $(GOMD2MAN) -in /dev/stdin -out $(subst source/markdown,build/man,$@) .PHONY: docdir -- cgit v1.2.3-54-g00ecf