alexkarle.com

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

my-old-man-orig.html (10515B) [raw]


      1 <!DOCTYPE html>
      2 <html lang="en">
      3 <head>
      4   <meta charset="utf-8"/>
      5   <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
      6 <style>
      7 /* general defaults */
      8 body {
      9   background-color: #F5F5F5;
     10   margin-left: 20px;
     11   margin-right: 20px;
     12   font-size: 1.3em;
     13   line-height: 1.3;
     14   font-family: monospace;
     15 }
     16 
     17 /* style tweaks */
     18 a:link { color: #0a7899; }
     19 a:visited { color: #033a4a; }
     20 code { font-size: 1em; }
     21 h1 { font-size: 1.1em; }
     22 h2 { font-size: 1em; }
     23 .foot-license {
     24     margin-top: 16px;
     25     font-size: .7em;
     26     position: static;
     27     bottom: 0;
     28 }
     29 
     30 /* override bold/italic colors within permalinks */
     31 a.permalink { text-decoration: none }
     32 b,i { color: #000000 }
     33 
     34 /* Responsive screen sizes */
     35 @media only screen and (min-width: 992px) {
     36   body {
     37     width: 60%;
     38     margin: 0 auto;
     39   }
     40 } 
     41 @media only screen and (min-width: 600px) and (max-width: 991px) {
     42   body {
     43     width: 80%;
     44     margin: 0 auto;
     45   }
     46 }
     47 
     48 /* Smaller font on small screens */
     49 @media only screen and (max-width: 599px) {
     50   body { font-size: 1.1em; }
     51 }
     52 
     53 /* margins around head/foot */
     54 table.foot { margin-top: 3em; }
     55 table.head { margin-bottom: 3em; }
     56 
     57 /* scrollbars on the block-display content */
     58 div.Bd-indent {
     59     border-left-color: gray;
     60     border-left-style: solid;
     61     border-left-width: 2px;
     62     border-radius: 5px;
     63     padding-left: 1em;
     64 }
     65 
     66 .Bd > pre {
     67     overflow-x: auto;
     68 }
     69 
     70 /* Bl-tag correctly with grid for blog.7 */
     71 dl.Bl-tag {
     72     display: grid;
     73     grid-template-columns: max-content auto
     74 }
     75 dl.Bl-tag dd {
     76      margin-left: 16px;
     77      margin-bottom: 1em;
     78 }
     79 
     80 /* defaults from mandoc(1)'s inlined CSS */
     81 table.head, table.foot { width: 100%; }
     82 td.head-rtitle, td.foot-os { text-align: right; }
     83 .Nd, .Bf, .Op { display: inline; }
     84 .Pa, .Ad { font-style: italic; }
     85 .Ms { font-weight: bold; }
     86 .Bl-diag > dt { font-weight: bold; }
     87 code.Nm, .Fl, .Cm, .Ic, code.In, .Fd, .Fn, .Cd {
     88     font-weight: bold;
     89 }
     90 </style>
     91   <title>MY-OLD-MAN(7)</title>
     92 <meta name="viewport" content="width=device-width,initial-scale=1"></head>
     93 <body>
     94 <table class="head">
     95   <tr>
     96     <td class="head-ltitle">MY-OLD-MAN(7)</td>
     97     <td class="head-rtitle">MY-OLD-MAN(7)</td>
     98   </tr>
     99 </table>
    100 <div class="manual-text">
    101 <section class="Sh">
    102 <h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
    103 <p class="Pp"><code class="Nm">my-old-man</code> &#x2014;
    104     <span class="Nd">adventures in using
    105     <a class="Xr" href="https://man.openbsd.org/mdoc.7">mdoc(7)</a> as the
    106     markup for this site</span></p>
    107 </section>
    108 <section class="Sh">
    109 <h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
    110 <div class="Bd Bd-indent Li">
    111 <pre>Uh oh,
    112 looks like,
    113 I'm seeing more of my old man(1) in me
    114        ~ Mac DeMarco (added (1) by me)</pre>
    115 </div>
    116 </section>
    117 <section class="Sh">
    118 <h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
    119 <p class="Pp">While Mac wasn't talking about good old roff-style man pages, I
    120     felt his words were a fun description of my effort to move from a markdown
    121     based templated site to a
    122     <a class="Xr" href="https://man.openbsd.org/mdoc.7">mdoc(7)</a> based
    123   site.</p>
    124 <p class="Pp" id="why">After pointing out that
    125     <a class="Lk" href="https://git.alexkarle.com/alexkarle.com/file/intro.7.html">I
    126     really did</a> rewrite my site in
    127     <a class="Xr" href="https://man.openbsd.org/mdoc.7">mdoc(7)</a>, you might
    128     be wondering <a class="permalink" href="#why"><i class="Em">why</i></a> I
    129     would do this. This blog post is intended to answer just that.</p>
    130 </section>
    131 <section class="Sh">
    132 <h1 class="Sh" id="WHY"><a class="permalink" href="#WHY">WHY</a></h1>
    133 <section class="Ss">
    134 <h2 class="Ss" id="For_the_learning_experience"><a class="permalink" href="#For_the_learning_experience">For
    135   the learning experience</a></h2>
    136 <p class="Pp">The single biggest motivator of the rewrite was that I like to use
    137     this site as a playground for learning new (old) technology, and
    138     <a class="Xr" href="https://man.openbsd.org/mdoc.7">mdoc(7)</a> was on my
    139     list of tech to learn.</p>
    140 <p class="Pp">What better way to learn a new markup language than to port an
    141     existing project to use it?</p>
    142 <p class="Pp">I had a blast transferring my old posts and coming up with a new
    143     build system.</p>
    144 </section>
    145 <section class="Ss">
    146 <h2 class="Ss" id="For_the_look"><a class="permalink" href="#For_the_look">For
    147   the look</a></h2>
    148 <p class="Pp">I really enjoy a good
    149     <a class="Xr" href="https://man.openbsd.org/man.1">man(1)</a> page.</p>
    150 <p class="Pp">You've probably heard it before, but I'll say it again: one of the
    151     best parts of using OpenBSD is its concise and comprehensive man pages in
    152     the base system.</p>
    153 <p class="Pp">There's a certain warm fuzzy feeling when you can learn something
    154     both without internet access and with the knowledge that it is the
    155     authoritative source.</p>
    156 <p class="Pp">I want my site to be a homage to good, well thought out,
    157     <a class="Xr" href="https://man.openbsd.org/man.1">man(1)</a> pages.</p>
    158 </section>
    159 <section class="Ss">
    160 <h2 class="Ss" id="Keeping_it_all_in_base"><a class="permalink" href="#Keeping_it_all_in_base">Keeping
    161   it all in base</a></h2>
    162 <p class="Pp">As an OpenBSD nerd, I find a bit of joy in having a site which is
    163     built, deployed, and served all via the base OpenBSD system.</p>
    164 <p class="Pp">By using
    165     <a class="Xr" href="https://man.openbsd.org/mandoc.1">mandoc(1)</a> instead
    166     of Markdown.pl, I can now build my site without any additional
    167   dependencies.</p>
    168 <p class="Pp" id="fast">Better yet,
    169     <a class="Xr" href="https://man.openbsd.org/mandoc.1">mandoc(1)</a> is
    170     ported to the various Linux distros I use day to day, and it is
    171     <a class="permalink" href="#fast"><i class="Em">fast</i></a>.</p>
    172 </section>
    173 </section>
    174 <section class="Sh">
    175 <h1 class="Sh" id="HOW"><a class="permalink" href="#HOW">HOW</a></h1>
    176 <p class="Pp">If you read this far, I thought you might be interested to hear
    177     how I'm deploying the content.</p>
    178 <p class="Pp">I'm a big fan of automation, so I've rigged up the site to deploy
    179     on a push to the master branch. Doing so involved two steps.</p>
    180 <section class="Ss">
    181 <h2 class="Ss" id="Building_the_mdoc"><a class="permalink" href="#Building_the_mdoc">Building
    182   the mdoc</a></h2>
    183 <p class="Pp">I created a small Makefile that builds each HTML file from each
    184     man page source.</p>
    185 <p class="Pp">The relevant bit is the implicit suffix rule to convert each .7
    186     file to .html:</p>
    187 <div class="Bd Pp Bd-indent Li">
    188 <pre>.SUFFIXES: .7 .html
    189 .7.html:
    190 	@echo &quot;mandoc $&lt;&quot;
    191 	@mandoc -Thtml -O 'man=%N.html;https://man.openbsd.org/%N.%S,style=style.css' $&lt; \
    192 	    | sed 's#&lt;/head&gt;#&lt;meta name=&quot;viewport&quot; content=&quot;width=device-width,initial-scale=1&quot;&gt;&amp;# ' \
    193 	    &gt; $@</pre>
    194 </div>
    195 <p class="Pp" id="$_">This looks crazy, but it's not too complex. First, know
    196     that <a class="permalink" href="#$_"><b class="Sy">$&lt;</b></a> is the
    197     source (the &lt;name&gt;.7 page), and
    198     <a class="permalink" href="#$@"><b class="Sy" id="$@">$@</b></a> is the
    199     target (the &lt;name&gt;.html page). The
    200     <a class="permalink" href="#@"><b class="Sy" id="@">@</b></a> prefix is a
    201     bit of magic to suppress printing the command run (so that all the output
    202     shown on git-push is just a single &quot;mandoc&quot; line for each file
    203     updated).</p>
    204 <p class="Pp" id=".Xr">Moving on to the mandoc command, I use the html output of
    205     mandoc via -T, with the -O switch specifying that linked man-page references
    206     should look locally first, then to point to man.openbsd.org. This allows me
    207     to quickly reference OpenBSD base tools and pages, while also using the
    208     terse <a class="permalink" href="#.Xr"><b class="Sy">.Xr</b></a> macro for
    209     linking individual site pages.</p>
    210 <p class="Pp">Finally, I use a
    211     <a class="Xr" href="https://man.openbsd.org/sed.1">sed(1)</a> oneliner to
    212     splice in a &lt;meta&gt; viewport tag for mobile devices.</p>
    213 <p class="Pp">And that's really it! The rest is just listing the man pages I
    214     want built, with a phony default target depending on the html pages so that
    215     a &#x2018;<code class="Li">make</code>&#x2019; builds them all. Check out
    216     the full source
    217     <a class="Lk" href="https://git.alexkarle.com/alexkarle.com/file/Makefile.html">here</a>.</p>
    218 </section>
    219 <section class="Ss">
    220 <h2 class="Ss" id="Deploying_via_git_hook"><a class="permalink" href="#Deploying_via_git_hook">Deploying
    221   via git hook</a></h2>
    222 <p class="Pp">Since I'm self-hosting git on the same server as the website, it's
    223     trivial to deploy when it receives a push by leveraging git hooks.</p>
    224 <p class="Pp">For the unfamiliar, git hooks are simply shell scripts that are
    225     triggered by specific git actions. In this case, I used the post-receive
    226     hook to publish after the refs were updated via a
    227     &#x2018;<code class="Li">git push</code>&#x2019;.</p>
    228 <p class="Pp">More specifically, I added the following to
    229     <span class="Pa">&lt;git-dir&gt;/hooks/post-receive</span>:</p>
    230 <div class="Bd Pp Bd-indent Li">
    231 <pre>echo &quot;Deploying to to /var/www/htdocs... &quot;
    232 WT=/var/www/htdocs
    233 git -C ${dir} --work-tree=${WT} checkout -f master
    234 make -C ${WT}
    235 echo &quot;done&quot;</pre>
    236 </div>
    237 <p class="Pp">So, on any push, it checks out the entire source tree into the
    238     webserver's content area and rebuilds only the necessary HTML files (thanks
    239     to <a class="Xr" href="https://man.openbsd.org/make.1">make(1)</a>).</p>
    240 <p class="Pp">If I had files I didn't want served, I would modify it to build
    241     elsewhere and copy the contents to /var/www; however, I'm publishing both
    242     the source for the site and the git history at
    243     <a class="Lk" href="https://git.alexkarle.com">https://git.alexkarle.com</a>,
    244     so I don't see any harm to having the README.md accessible from the
    245   root.</p>
    246 </section>
    247 </section>
    248 <section class="Sh">
    249 <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
    250   ALSO</a></h1>
    251 <ul class="Bl-bullet Bl-compact">
    252   <li><a class="Xr" href="blog.html">blog(7)</a></li>
    253   <li><a class="Lk" href="https://www.git-scm.com/docs/githooks">git
    254     hooks</a></li>
    255 </ul>
    256 </section>
    257 </div>
    258 <table class="foot">
    259   <tr>
    260     <td class="foot-date">December 30, 2020</td>
    261     <td class="foot-os">OpenBSD 7.0</td>
    262   </tr>
    263 </table>
    264 <p class="foot-license">
    265   © 2019-2021 Alex Karle | <a href="/">Home</a> | <a href="/license.html">License</a>
    266 </p>
    267 </body>
    268 </html>