aux/workflow/manpages.sh: Refactor how manpages and translations are made

I didn't like the previous version of aux/workflow/manpages.sh mainly for 2 reasons:
1. its CLI was terrible, ugly and fragile;
2. it mixed handling manpages and handling *translations*.

The first step was to split the translations part to a different file:
aux/workflow/l10n.sh.  Now it has the base logic for running po4a, and
can apply it to manpages.  It is useful for updating translated files
in other scenarios, such as catgets() message catalogs, markdown files,
etc.

After I used the venerable getopts to handle the command line
arguments, and give aux/workflow/manpages.sh a saner interface.

I disliked the fact that aux/workflow/manpages.sh still is being used
for the "install" and "uninstall" targets.  Before this file, the
canonical workflow of "make && make install/uninstall" was 100%
embedded within the Makefile itself.  But now the Makefile calls to an
external script for that.  This isn't a real cost, other than how
obvious the behaviour is for someone looking at the Makefile for the
first time.

I still chose to do it anyway, because there was already too many
things in the Makefile itself, and it was getting worse with time.  I
made sure to never cross the line of relying on an external tool for
the canonical "make && make install/uninstall", and even for
"make check".  Those all work without requiring any extra tool outside
what POSIX defines, such as "sed", "awk", etc.  Despite the cost of
adding this detour from the liner Makefile flow, I found it to be worth
it to call to the external script, as this script can now also be
shared across projects, and the customized Makefile be made simpler.

In other to remove the "-- $(do_subst)" horrendous hack, I chose to use
an inference rule for ".in" files, and remove the "$(do_subst)"
variable altogether.  Now all the files that need to go through sed
should end in ".in", and the Makefile will take care of producing it.
The upside is that this model is much better integrater into make
itself.

Addresses #task-9ee2bbc8-295f-52b7-4104-483869bad017.

10 files changed, 135 insertions, 71 deletions

diff --git a/.gitignore b/.gitignore
index 4a61da9..b75107f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
 /public/
-/git-permalink
+/src/git-permalink.sh
 /po/*.mo
 /po/*.po~
 /tests/remotes/
 /tests/prefix/
+/doc/*.1
diff --git a/Makefile b/Makefile
index c485659..c98364b 100644
--- a/Makefile
+++ b/Makefile
@@ -7,11 +7,23 @@ NAME         = git-permalink
 MAILING_LIST = public-inbox
 TRANSLATIONS = pt fr eo
 
-all: git-permalink
+.SUFFIXES:
+.SUFFIXES: .in
 
-git-permalink: src/git-permalink.sh.in
-	$(do_subst) < $? > $@
-	chmod +x $@
+.in:
+	sed -e 's/@VERSION@/$(VERSION)/g' -e 's/@DATE@/$(DATE)/g' < $< > $@
+
+manpages.en.in = \
+	doc/git-permalink.en.1.in \
+
+manpages.in = $(manpages.en.in)  \
+	doc/git-permalink.pt.1.in \
+	doc/git-permalink.fr.1.in \
+	doc/git-permalink.eo.1.in
+
+manpages = $(manpages.in:.in=)
+
+all: src/git-permalink.sh $(manpages)
 
 check: all
 	sh tests/cli-opts.sh
@@ -23,28 +35,25 @@ dev-check: check
 	sh aux/workflow/assert-todos.sh
 	sh aux/workflow/assert-changelog.sh $(NAME) $(NAME)
 	sh aux/workflow/assert-readme.sh $(NAME) $(MAILING_LIST)
-	sh aux/workflow/manpages.sh '$(TRANSLATIONS)' --update
+	sh aux/workflow/l10n.sh -l '$(TRANSLATIONS)' $(manpages.en.in)
 	sh aux/workflow/assert-manpages.sh $(NAME) $(MAILING_LIST)
 
-do_subst = sed \
-	-e 's:[@]VERSION[@]:$(VERSION):g' \
-	-e 's:[@]DATE[@]:$(DATE):g'
-
 install: all
 	mkdir -p $(DESTDIR)$(PREFIX)/bin
-	cp git-permalink $(DESTDIR)$(PREFIX)/bin/$(NAME)
-	sh aux/workflow/manpages.sh '$(TRANSLATIONS)' --install '$(DESTDIR)$(MANPREFIX)' -- $(do_subst)
+	cp src/git-permalink.sh $(DESTDIR)$(PREFIX)/bin/$(NAME)
+	chmod +x $(DESTDIR)$(PREFIX)/bin/$(NAME)
+	sh aux/workflow/manpages.sh -ip $(DESTDIR)$(PREFIX) $(manpages)
 
 uninstall:
 	rm -f $(DESTDIR)$(PREFIX)/bin/$(NAME)
-	sh aux/workflow/manpages.sh '$(TRANSLATIONS)' --uninstall '$(DESTDIR)$(MANPREFIX)'
+	sh aux/workflow/manpages.sh -up $(DESTDIR)$(PREFIX) $(manpages)
 
 clean:
-	rm -rf public/ git-permalink
+	rm -rf public/ src/git-permalink.sh $(manpages)
 
 dist:
 	sh aux/workflow/dist.sh $(DATE) $(VERSION) $(NAME) $(NAME) $(MAILING_LIST)
 
-public: README.md TODOs.md CHANGELOG.md
+public: README.md TODOs.md CHANGELOG.md $(manpages)
 	sh aux/workflow/public.sh $(NAME) $(NAME) $(MAILING_LIST) public
-	sh aux/workflow/manpages.sh '$(TRANSLATIONS)' --html '' -- $(do_subst)
+	sh aux/workflow/manpages.sh -Ho public $(manpages)
diff --git a/aux/workflow/assert-changelog.sh b/aux/workflow/assert-changelog.sh
index 61cd916..e2cd926 100755
--- a/aux/workflow/assert-changelog.sh
+++ b/aux/workflow/assert-changelog.sh
@@ -33,8 +33,7 @@ for VVERSION in $(git tag); do
 done
 
 # "$@" represents a list of tags to be also included in the verification.
-# shellcheck disable=2068
-for VVERSION in $@; do
+for VVERSION in "$@"; do
 	DATE="$(date '+%Y-%m-%d')"
 	assert "$DATE" "$VVERSION"
 done
diff --git a/aux/workflow/assert-readme.sh b/aux/workflow/assert-readme.sh
index e256fcf..8fcf188 100755
--- a/aux/workflow/assert-readme.sh
+++ b/aux/workflow/assert-readme.sh
@@ -50,8 +50,7 @@ for VVERSION in $(git tag); do
 done
 
 # "$@" represents a list of tags to be also included in the verification.
-# shellcheck disable=2068
-for VVERSION in $@; do
+for VVERSION in "$@"; do
 	if ! git tag | grep -qF "$VVERSION"; then
 		DATE="$(date '+%Y-%m-%d')"
 		add_release "$DATE" "$VVERSION"
diff --git a/aux/workflow/l10n.sh b/aux/workflow/l10n.sh
new file mode 100755
index 0000000..81a7d02
--- /dev/null
+++ b/aux/workflow/l10n.sh
@@ -0,0 +1,44 @@
+#!/bin/sh
+set -eu
+
+LANGS=
+while getopts 'l:' flag; do
+	case "$flag" in
+		l)
+			LANGS="$OPTARG"
+			;;
+		*)
+			exit 2
+			;;
+	esac
+done
+shift $((OPTIND - 1))
+if [ -z "$LANGS" ]; then
+	echo "Missing LANG" >&2
+	exit 2
+fi
+
+for f in $(find $@ -not -name '*.en.*'); do
+	case "$f" in
+		*.en.[1-9].in)
+			manpage "$f"
+			;;
+		*)
+			echo "Unsupported file format: $f" >&2
+			exit 2
+			;;
+	esac
+done
+
+manpage() {
+	from_f="$1"
+	for l in $LANGS; do
+		to_f="$(echo "$from_f" | sed "s/\.en\./.$l./")"
+		po4a-updatepo -f man -m "$from_f" -p "po/$l.po"
+		OUT="$(po4a-translate -f man -m "$from_f" -p "po/$l.po" -l "$to_f" -k 0 -v 2>&1)"
+		echo "$OUT" >&2
+		if ! echo "$OUT" | grep -qF ' is 100% translated ('; then
+			printf '\n\tWARNING!\n	Missing translations for %s\n\n' "$to_f" >&2
+		fi
+	done
+}
diff --git a/aux/workflow/manpages.sh b/aux/workflow/manpages.sh
index fd88d95..7332d8f 100755
--- a/aux/workflow/manpages.sh
+++ b/aux/workflow/manpages.sh
@@ -1,55 +1,67 @@
 #!/bin/sh
 set -eu
 
-LANGS="$1"
-OP="$2"
-PREFIX="${3:-}"
+while getopts 'iuHo:p:' flag; do
+	case "$flag" in
+		i)
+			ACTION=install
+			;;
+		u)
+			ACTION=uninstall
+			;;
+		H)
+			ACTION=html
+			;;
+		o)
+			OUTDIR="$OPTARG"
+			;;
+		p)
+			MANPREFIX="$OPTARG"
+			;;
+		*)
+			exit 2
+			;;
+	esac
+done
+shift $((OPTIND - 1))
 
-if [ "$OP" = '--update' ]; then
-	for f in doc/*.en.[1-9]; do
-		for lang in $LANGS; do
-			to="$(echo "$f" | sed "s|\.en\.|.$lang.|")"
-			po4a-updatepo  -f man -m "$f" -p "po/$lang.po"
-			printf 'Translating %s...\n' "$to" >&2
-			OUT="$(po4a-translate -f man -m "$f" -p "po/$lang.po" -l "$to" -k 0 -v 2>&1)"
-			echo "$OUT" >&2
-			if ! echo "$OUT" | grep -qF ' is 100% translated ('; then
-				printf "\n  WARNING!\n  Missing translations for %s\n\n" "$to" >&2
-			fi
-		done
-	done
-else
-	shift 4 ||: # remove up to '--'
-	for f in doc/*.en.[1-9]; do
-		n="${f##*.}"
-		fileto_name="$(basename "${f%.en.$n}").$n"
-		for lang in $LANGS en; do
-			filefrom_name="${f%.en.$n}.$lang.$n"
-			mandir_name="$PREFIX/$lang/man$n"
-			htmldir_name="public/$lang/"
-			case "$OP" in
-				--install)
-					mkdir -p "$mandir_name"
-					# shellcheck disable=2068
-					$@ < "$filefrom_name" > "$mandir_name/$fileto_name"
-					mkdir -p "$PREFIX/man$n"
-					ln -fs "../en/man$n/$fileto_name" "$PREFIX/man$n/$fileto_name"
-					;;
-				--uninstall)
-					rm -f \
-						"$PREFIX/$lang/man$n/$fileto_name" \
-						"$PREFIX/man$n/$fileto_name"
-					;;
-				--html)
-					mkdir -p "$htmldir_name"
-					# shellcheck disable=2068
-					$@ < "$filefrom_name" | pandoc -s -r man -w html > "public/$lang/$fileto_name.html"
-					;;
-				*)
-					echo "Unsupported operation: $OP"
-					exit 2
-					;;
-			esac
-		done
-	done
-fi
+assert() {
+	if [ -z "$1" ]; then
+		echo "Missing $2 argument" >&2
+		exit 2
+	fi
+}
+
+assert "${ACTION:-}" ACTION
+
+for f in "$@"; do
+	l="$(echo "$f" | awk -F. '{print $(NF-1)}')"
+	n="$(echo "$f" | awk -F. '{print $NF}')"
+	en="$(echo "$f" | sed "s/\.$l\./.en./")"
+	case "$ACTION" in
+		html)
+			assert "${OUTDIR:-}" OUTDIR
+			to_name="$(basename "${f%.$l.$n}.html")"
+			mkdir -p "$OUTDIR/$l"
+			pandoc -s -r man -w html --metadata "lang=$l" < "$f" > "$OUTDIR/$l/$to_name"
+			;;
+		install)
+			assert "${MANPREFIX:-}" MANPREFIX
+			to_name="$(basename "${f%.$l.$n}.$n")"
+			mkdir -p "$MANPREFIX/$l/man$n" "$MANPREFIX/man$n"
+			cp "$f" "$MANPREFIX/$l/man$n/$to_name"
+			ln -fs "../en/man$n/$to_name" "$MANPREFIX/man$n/$to_name"
+			;;
+		uninstall)
+			assert "${MANPREFIX:-}" MANPREFIX
+			to_name="$(basename "${f%.$l.$n}.$n")"
+			rm -f \
+				"$MANPREFIX/$l/man$n/$to_name" \
+				"$MANPREFIX/man$n/$to_name"
+			;;
+		*)
+			echo "Bad ACTION: $ACTION"
+			exit 1
+			;;
+	esac
+done
diff --git a/doc/git-permalink.en.1 b/doc/git-permalink.en.1.in
index 63d8f0e..63d8f0e 100644
--- a/doc/git-permalink.en.1
+++ b/doc/git-permalink.en.1.in
diff --git a/doc/git-permalink.eo.1 b/doc/git-permalink.eo.1.in
index 0d799c0..0d799c0 100644
--- a/doc/git-permalink.eo.1
+++ b/doc/git-permalink.eo.1.in
diff --git a/doc/git-permalink.fr.1 b/doc/git-permalink.fr.1.in
index 3dcc01a..3dcc01a 100644
--- a/doc/git-permalink.fr.1
+++ b/doc/git-permalink.fr.1.in
diff --git a/doc/git-permalink.pt.1 b/doc/git-permalink.pt.1.in
index 5b8ae4a..5b8ae4a 100644
--- a/doc/git-permalink.pt.1
+++ b/doc/git-permalink.pt.1.in