alexkarle.com

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

my-old-man.7 (4838B) [raw]


      1 .Dd December 30, 2020
      2 .Dt MY-OLD-MAN 7
      3 .Os
      4 .Sh NAME
      5 .Nm my-old-man
      6 .Nd adventures in using
      7 .Xr mdoc 7
      8 as the markup for this site
      9 .Sh SYNOPSIS
     10 .Bd -literal -offset indent
     11 Uh oh,
     12 looks like,
     13 I'm seeing more of my old man(1) in me
     14        ~ Mac DeMarco (added (1) by me)
     15 .Ed
     16 .Sh DESCRIPTION
     17 While Mac wasn't talking about good old roff-style man pages,
     18 I felt his words were a fun description of my effort to move
     19 from a markdown based templated site to a
     20 .Xr mdoc 7
     21 based site.
     22 .Pp
     23 After pointing out that
     24 .Lk https://git.alexkarle.com/alexkarle.com/file/intro.7.html I really did
     25 rewrite my site in
     26 .Xr mdoc 7 ,
     27 you might be wondering
     28 .Em why
     29 I would do this.
     30 This blog post is intended to answer just that.
     31 .Sh WHY
     32 .Ss For the learning experience
     33 The single biggest motivator of the rewrite was that
     34 I like to use this site as a playground for learning new (old) technology,
     35 and
     36 .Xr mdoc 7
     37 was on my list of tech to learn.
     38 .Pp
     39 What better way to learn a new markup language than to port an existing
     40 project to use it?
     41 .Pp
     42 I had a blast transferring my old posts and coming up with a new build
     43 system.
     44 .Ss For the look
     45 I really enjoy a good
     46 .Xr man 1
     47 page.
     48 .Pp
     49 You've probably heard it before, but I'll say it again: one of the best
     50 parts of using OpenBSD is its concise and comprehensive man pages in
     51 the base system.
     52 .Pp
     53 There's a certain warm fuzzy feeling when you can learn something
     54 both without internet access and with the knowledge that it is the
     55 authoritative source.
     56 .Pp
     57 I want my site to be a homage to good, well thought out,
     58 .Xr man 1
     59 pages.
     60 .Ss Keeping it all in base
     61 As an OpenBSD nerd, I find a bit of joy in having a site which is built,
     62 deployed, and served all via the base OpenBSD system.
     63 .Pp
     64 By using
     65 .Xr mandoc 1
     66 instead of Markdown.pl, I can now build my site without any additional
     67 dependencies.
     68 .Pp
     69 Better yet,
     70 .Xr mandoc 1
     71 is ported to the various Linux distros I use day to day, and it is
     72 .Em fast .
     73 .Sh HOW
     74 If you read this far, I thought you might be interested to hear how I'm
     75 deploying the content.
     76 .Pp
     77 I'm a big fan of automation, so I've rigged up the site to deploy on a push
     78 to the master branch.
     79 Doing so involved two steps.
     80 .Ss Building the mdoc
     81 I created a small Makefile that builds each HTML file from each man page source.
     82 .Pp
     83 The relevant bit is the implicit suffix rule to convert each .7 file to .html:
     84 .Bd -literal -offset indent
     85 \).SUFFIXES: .7 .html
     86 \).7.html:
     87 	@echo "mandoc $<"
     88 	@mandoc -Thtml -O 'man=%N.html;https://man.openbsd.org/%N.%S,style=style.css' $< \\
     89 	    | sed 's#</head>#<meta name="viewport" content="width=device-width,initial-scale=1">&# ' \\
     90 	    > $@
     91 .Ed
     92 .Pp
     93 This looks crazy, but it's not too complex.
     94 First, know that
     95 .Sy $<
     96 is the source (the <name>.7 page), and
     97 .Sy $@
     98 is the target (the <name>.html page).
     99 The
    100 .Sy @
    101 prefix is a bit of magic to suppress printing the command run (so that all the
    102 output shown on git-push is just a single "mandoc" line for each file updated).
    103 .Pp
    104 Moving on to the mandoc command, I use the html output of mandoc via -T,
    105 with the -O switch specifying that linked man-page references should look
    106 locally first, then to point to man.openbsd.org.
    107 This allows me to quickly reference OpenBSD base tools and pages, while also
    108 using the terse
    109 .Sy .Xr
    110 macro for linking individual site pages.
    111 .Pp
    112 Finally, I use a
    113 .Xr sed 1
    114 oneliner to splice in a <meta> viewport tag for mobile
    115 devices.
    116 .Pp
    117 And that's really it!
    118 The rest is just listing the man pages I want built,
    119 with a phony default target depending on the html pages so that a
    120 .Ql make
    121 builds them all.
    122 Check out the full source
    123 .Lk https://git.alexkarle.com/alexkarle.com/file/Makefile.html here .
    124 .Ss Deploying via git hook
    125 Since I'm self-hosting git on the same server as the website, it's trivial to
    126 deploy when it receives a push by leveraging git hooks.
    127 .Pp
    128 For the unfamiliar, git hooks are simply shell scripts that are triggered by
    129 specific git actions.
    130 In this case, I used the post-receive hook to publish
    131 after the refs were updated via a
    132 .Ql git push .
    133 .Pp
    134 More specifically, I added the following to
    135 .Pa <git-dir>/hooks/post-receive :
    136 .Bd -literal -offset indent
    137 echo "Deploying to to /var/www/htdocs... "
    138 WT=/var/www/htdocs
    139 git -C ${dir} --work-tree=${WT} checkout -f master
    140 make -C ${WT}
    141 echo "done"
    142 .Ed
    143 .Pp
    144 So, on any push, it checks out the entire source tree into the webserver's content
    145 area and rebuilds only the necessary HTML files (thanks to
    146 .Xr make 1 ) .
    147 .Pp
    148 If I had files I didn't want served, I would modify it to build elsewhere and
    149 copy the contents to /var/www; however, I'm publishing both the source for the site
    150 and the git history at
    151 .Lk https://git.alexkarle.com ,
    152 so I don't see any harm to having the README.md accessible from the root.
    153 .Sh SEE ALSO
    154 .Bl -bullet -compact
    155 .It
    156 .Xr blog 7
    157 .It
    158 .Lk https://www.git-scm.com/docs/githooks git hooks
    159 .El