alexkarle.com

commit 3420bba2a845151cde021167a85764632a466ac8 (patch)
parent 3aaf05960aed1a3957bbf76f7dc956474b3a1bb7
Author: Alex Karle <alex@alexkarle.com>
Date:   Thu, 31 Dec 2020 00:22:24 -0500

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!

Diffstat:
M
my-old-man.7
 | 
24
++++++++++++++++++++----

1 file changed, 20 insertions(+), 4 deletions(-)
diff --git 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#</head>#<meta name="viewport" content="width=device-width,initial-scale=1">&# ' \\
 	    > $@
 .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 <name>.7 page), and
+.Sy $@
+is the target (the <name>.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 <meta> viewport tag for mobile
 devices.