commit ff4a9ead849225aa5d90ea4c2519cce98153138c (patch)
parent 924bb6548faa227d640f36a694ef687f7162a7f1
Author: Alex Karle <alex@alexkarle.com>
Date: Wed, 30 Dec 2020 18:58:36 -0500
my-old-man: Add blog post on transition to mdoc
This also signifies the point at which I'm going to cut over the deployed
site to be the mdoc files! Woohoo!
I accidentally commited the my-old-man to the blog(7) in the previous commit,
whoops...
Diffstat:
3 files changed, 138 insertions(+), 2 deletions(-)
diff --git a/Makefile b/Makefile
@@ -8,7 +8,8 @@ HTML := \
domain-names.7.html \
BLM.7.html \
self-hosted.7.html \
- on-writing.7.html
+ on-writing.7.html \
+ my-old-man.7.html
.PHONY: build
build: $(HTML)
diff --git a/my-old-man.7 b/my-old-man.7
@@ -0,0 +1,133 @@
+.Dd December 30, 2020
+.Dt MY-OLD-MAN 7
+.Os
+.Sh NAME
+.Nm my-old-man
+.Nd adventures in using
+.Xr mdoc 7
+as a markup for this site
+.Sh SYNOPSIS
+.Bd -literal -offset indent
+Uh oh,
+looks like,
+I'm seeing more of my old man(1) in me
+ ~ Mac DeMarco (added (1) by me)
+.Ed
+.Sh DESCRIPTION
+While Mac wasn't talking about good old roff-style man pages,
+I felt his words were a fun description of my effort to move
+from a markdown based templated site to a
+.Xr mdoc 7
+based site.
+.Pp
+After pointing out that
+.Lk https://alexkarle.com/git/alexkarle.com/file/intro.7.html I really did
+rewrite my site in
+.Xr mdoc 7 ,
+you might be wondering
+.Em why
+I would do this. This blog post is intended to answer just that.
+.Sh WHY
+.Ss For the learning experience
+The single biggest motivator of the rewrite was that
+I like to use this site as a playground for learning new (old) technology,
+and
+.Xr mdoc 7
+was on my list of tech to learn.
+.Pp
+What better way to learn a new markup language than to port an existing
+project to use it?
+.Pp
+I had a blast transferring my old posts and coming up with a new build
+system.
+.Ss For the look
+I really enjoy a good
+.Xr man 1
+page.
+.Pp
+You've probably heard it before, but I'll say it again: one of the best
+parts of using OpenBSD is its concise and comprehensive man pages in
+the base system.
+.Pp
+There's a certain warm fuzzy feeling when you can learn something
+both without internet access and with the knowledge that it is the
+authoritative source.
+.Pp
+I want my site to be a homage to good, well thought out,
+.Xr man 1
+pages.
+.Ss Keeping it all in base
+As an OpenBSD nerd, I find a bit of joy in having a site which is built,
+deployed, and served all via the base OpenBSD system.
+.Pp
+By using
+.Xr mandoc 1
+instead of Markdown.pl, I can now build my site without any additional
+dependencies.
+.Pp
+Better yet,
+.Xr mandoc 1
+is ported to the various Linux distros I use day to day, and it is
+.Em fast .
+.Sh HOW
+If you read this far, I thought you might be interested to hear how I'm
+deploying the content.
+.Pp
+I'm a big fan of automation, so I've rigged up the site to deploy on a push
+to the master branch. Doing so involved two steps.
+.Ss Building the mdoc
+I created a small Makefile that builds each HTML file from each man page source.
+.Pp
+The relevant bit is the implicit suffix rule to convert each .7 file to .7.html:
+.Bd -literal -offset indent
+\).SUFFIXES: .7 .7.html
+\).7.7.html:
+ @echo "mandoc $<"
+ $(HIDE)mandoc -Thtml -O 'man=%N.%S.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
+.Xr sed 1
+oneliner to splice in a <meta> viewport tag for mobile
+devices.
+.Pp
+And that's really it! The rest is just listing the man pages I want built,
+with a phony default target depending on the html pages so that a `make` builds
+them all. Check out the full source
+.Lk https://alexkarle.com/git/alexkarle.com/file/Makefile.html here .
+.Ss Deploying via git hook
+Since I'm self-hosting git on the same server as the website, it's trivial to
+deploy when it receives a push by leveraging git hooks.
+.Pp
+For the unfamiliar, git hooks are simply shell scripts that are triggered by
+specific git actions.
+In this case, I used the post-receive hook to publish
+after the refs were updated via a `git push`.
+.Pp
+More specifically, I added the following to `<git-dir>/hooks/post-receive`:
+.Bd -literal -offset indent
+echo "Deploying to to /var/www/htdocs... "
+WT=/var/www/htdocs
+git -C ${dir} --work-tree=${WT} checkout -f master
+make -C ${WT}
+echo "done"
+.Ed
+So, on any push, it checks out the entire source tree into the webserver's content
+area and rebuilds only the necessary HTML files (thanks to
+.Xr make 1 ).
+.Pp
+If I had files I didn't want served, I would modify it to build elsewhere and
+copy the contents to /var/www; however, I'm publishing both the source for the site
+and the git history at
+.Lk https://alexkarle.com/git ,
+so I don't see any harm to having the README.md accessible from the root.
+.Sh SEE ALSO
+.Bl -compact -bullet -offset indent
+.It
+.Xr blog 7
+.It
+.Lk https://www.git-scm.com/docs/githooks git hooks
+.El
diff --git a/style.css b/style.css
@@ -12,7 +12,9 @@ body {
a:link { color: #0a7899; }
a:visited { color: #033a4a; }
code { font-size: 1em; }
-h1 { font-size: 1em; }
+h1 { font-size: 1.1em; }
+h2 { font-size: 1em; }
+.Bd-indent { margin-left: 1em; }
/* override bold/italic colors within permalinks */
a.permalink { text-decoration: none }
