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

commit c0f311467d522553c679c39cb7b549450cf39371 (patch)
parent 979858d4f961c9adc1cf394e9d682747257ab604
Author: Alex Karle <>
Date:   Mon, 13 Sep 2021 23:56:20 -0400

mdoc: Convert phony Xr's from Lk to Xr via postprocessing

Ever since starting to dump the raw ascii of the manpages for, I've been aware of the ugliness coming from
out-of-base cross references (Xrs). For instance, I want to link in my uses(7) page, so I previously had a .Lk element
to enable the inline link in the HTML:

    .Lk vim(1)

This "phony Xr" looks great in HTML but is super ugly in the ascii:


I hypothesize that anyone actually reading the ascii probably knows
what Vim is and would much rather just see "vim(1)" -- there's no
hyperlinking on anyways, so why bother posting
the URL? It just hurts the flow of the paragraph.

To solve this "links in HTML but just plain Xr in text", I added
a new postprocessing step to that uses sed(1) to change
any of the .Xr links that are invalid urls (not in base) to a known
good link via the LINKS file. I'm pretty pleased with how the sed(1)
command is genated using awk(1) and eval'd on the fly :)

The ascii dump doesn't care what's in base and what's not, so
no need for change there!

ALINKS | 10++++++++++
Mbin/ | 4+++-
Mbin/ | 4+++-
Mself-hosted.7 | 6++----
Muse-feeds.7 | 2+-
Muses.7 | 14+++++++-------
6 files changed, 26 insertions(+), 14 deletions(-)

diff --git a/LINKS b/LINKS @@ -0,0 +1,10 @@ +dwm.1 +st.1 +vim.1 +git.1 +bash.1 +mutt.1 +pass.1 +newsboat.1 +stagit.1 +git-daemon.1 diff --git a/bin/ b/bin/ @@ -39,7 +39,9 @@ for p in $POSTS; do ENTRY # Print fragment (no need for escapes -- in CDATA mandoc -Thtml -O'fragment,man=%N.html;' "$REPO/$p.7" \ - | sed '/<td class="head-vol">Miscellaneous Information Manual<\/td>/d' + | sed '/<td class="head-vol">Miscellaneous Information Manual<\/td>/d' \ + | eval \ + "sed $(awk '{ printf " \\\n -e s#", $1, $2 } END { printf "\n" }' "$REPO/LINKS")" cat <<EOENTRY ]]> </content> diff --git a/bin/ b/bin/ @@ -13,6 +13,7 @@ cd $REPO # 2. Add lang="en" to head for accessibility # 3. Remove Misc Info column in header (too large on mobile) # 4. Add a footer with license info +# 5. Correct various off-site links (i.e. .Xr st -> instead of mandoc -Thtml -O 'man=%N.html;,style=style.css' \ | sed \ -e 's#</head>#<meta name="viewport" content="width=device-width,initial-scale=1">&# ' \ @@ -21,4 +22,5 @@ mandoc -Thtml -O 'man=%N.html;,style=style.css' \ -e 's#</body>#<p class="foot-license">\ © 2019-2021 Alex Karle | <a href="/">Home</a> | <a href="/license.html">License</a>\ </p>\ -&#' +&#' | eval \ + "sed $(awk '{ printf " \\\n -e s#", $1, $2 } END { printf "\n" }' LINKS)" diff --git a/self-hosted.7 b/self-hosted.7 @@ -74,13 +74,13 @@ templating Perl script that I home-rolled .Bl -dash -compact .It Public repos served with -.Sy git-daemon(1) +.Xr git-daemon 1 over the `git://` protocol .It Push access via the `ssh://` protocol .It static HTML of content generated via post-receive hook with -.Sy stagit(1) +.Xr stagit 1 .El .El .Pp @@ -95,6 +95,4 @@ That's all for now! .Lk .It .Lk Mojolicious -.It -.Lk stagit(1) .El diff --git a/use-feeds.7 b/use-feeds.7 @@ -34,7 +34,7 @@ it also allows for an increasingly diverse set of clients and sources. .Pp For example, there are clients ranging from FOSS text only terminal clients like -.Lk newsboat(1) +.Xr newsboat 1 to commercial apps like .Lk Feedly . And despite being drastically different UI's, their purpose is the same: diff --git a/uses.7 b/uses.7 @@ -17,7 +17,7 @@ as well as for anyone else out there who enjoys the "genre". .Sh SOFTWARE .Ss Editor I got hooked on -.Lk vim(1) +.Xr vim 1 mid-college (~2017) and never looked back. It's first on this list (with a dedicated section!) because it was the "gateway program" @@ -70,7 +70,7 @@ Roughly in order of first-use: .Pp .Bl -compact -bullet .It -.Lk git(1) +.Xr git 1 for notes, code, config backups (~2016, usage increased over time) .It .Xr tmux 1 @@ -79,22 +79,22 @@ persistent sessions over dropped .Xr ssh 1 connections... really a necessity! (~2018) .It -.Lk bash(1) +.Xr bash 1 as my Linux shell (zsh previously, moved for work reasons early-2018) .It -.Lk dwm(1) +.Xr dwm 1 as my window manager (since early Linux days, early-2019) .It -.Lk st(1) +.Xr st 1 as my terminal emulator (also early-2019) .It -.Lk mutt(1) +.Xr mutt 1 for personal email (great for mailing lists, mid-2019) .It .Xr ksh 1 on OpenBSD for shells (late-2019) .It -.Lk pass(1) +.Xr pass 1 for password/secret management (late-2020) .El .Pp