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> — 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 "mandoc $<" 191 @mandoc -Thtml -O 'man=%N.html;https://man.openbsd.org/%N.%S,style=style.css' $< \ 192 | sed 's#</head>#<meta name="viewport" content="width=device-width,initial-scale=1">&# ' \ 193 > $@</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">$<</b></a> is the 197 source (the <name>.7 page), and 198 <a class="permalink" href="#$@"><b class="Sy" id="$@">$@</b></a> is the 199 target (the <name>.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 "mandoc" 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 <meta> 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 ‘<code class="Li">make</code>’ 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 ‘<code class="Li">git push</code>’.</p> 228 <p class="Pp">More specifically, I added the following to 229 <span class="Pa"><git-dir>/hooks/post-receive</span>:</p> 230 <div class="Bd Pp Bd-indent Li"> 231 <pre>echo "Deploying to to /var/www/htdocs... " 232 WT=/var/www/htdocs 233 git -C ${dir} --work-tree=${WT} checkout -f master 234 make -C ${WT} 235 echo "done"</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>