Source for
git clone git://
Log | Files | Refs | README | LICENSE

commit ff4a9ead849225aa5d90ea4c2519cce98153138c (patch)
parent 924bb6548faa227d640f36a694ef687f7162a7f1
Author: Alex Karle <>
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,

MMakefile | 3++-
Amy-old-man.7 | 133+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mstyle.css | 4+++-
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 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, 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;,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 +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 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 , +so I don't see any harm to having the accessible from the root. +.Sh SEE ALSO +.Bl -compact -bullet -offset indent +.It +.Xr blog 7 +.It +.Lk 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 }