From 3420bba2a845151cde021167a85764632a466ac8 Mon Sep 17 00:00:00 2001 From: Alex Karle Date: Thu, 31 Dec 2020 00:22:24 -0500 Subject: [PATCH] my-old-man: Improve makefile recipe explanation After sending the blog link to my dad/brother, I realized the Makefile bit comes off as too magical. Hopefully this helps clear it up a bit! --- my-old-man.7 | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/my-old-man.7 b/my-old-man.7 index 8597caa..36ed532 100644 --- a/my-old-man.7 +++ b/my-old-man.7 @@ -83,13 +83,29 @@ The relevant bit is the implicit suffix rule to convert each .7 file to .html: \).SUFFIXES: .7 .html \).7.html: @echo "mandoc $<" - $(HIDE)mandoc -Thtml -O 'man=%N.html;https://man.openbsd.org/%N.%S,style=style.css' $< \\ + @mandoc -Thtml -O 'man=%N.html;https://man.openbsd.org/%N.%S,style=style.css' $< \\ | sed 's##&# ' \\ > $@ .Ed -Broken down, this uses the html output of mandoc, with the -O switch specifying -that .Xr references should look locally first (else use man.openbsd.org). -Further, we use a +This looks crazy, but it's not too complex. First, know that +.Sy $< +is the source (the .7 page), and +.Sy $@ +is the target (the .html page). +The +.Sy @ +prefix is a bit of magic to suppress printing the command run (so that all the +output shown on git-push is just a single "mandoc" line for each file updated). +.Pp +Moving on to the mandoc command, I use the html output of mandoc via -T, +with the -O switch specifying that linked man-page references should look +locally first, then to point to man.openbsd.org. +This allows me to quickly reference OpenBSD base tools and pages, while also +using the quick +.Sy .Xr +macro for linking individual site pages. +.Pp +Finally, I use a .Xr sed 1 oneliner to splice in a viewport tag for mobile devices. -- libgit2 1.1.1