commit c0f311467d522553c679c39cb7b549450cf39371 (patch)
parent 979858d4f961c9adc1cf394e9d682747257ab604
Author: Alex Karle <alex@alexkarle.com>
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
text.alexkarle.com, I've been aware of the ugliness coming from
out-of-base cross references (Xrs). For instance, I want to link
vim.org in my uses(7) page, so I previously had a .Lk element
to enable the inline link in the HTML:
.Lk https://www.vim.org vim(1)
This "phony Xr" looks great in HTML but is super ugly in the ascii:
vim(1): https://www.vim.org
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 text.alexkarle.com 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 genpost.sh 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!
Diffstat:
6 files changed, 26 insertions(+), 14 deletions(-)
diff --git a/LINKS b/LINKS
@@ -0,0 +1,10 @@
+dwm.1 https://dwm.suckless.org
+st.1 https://st.suckless.org
+vim.1 https://www.vim.org
+git.1 https://git-scm.com/
+bash.1 https://www.gnu.org/software/bash/
+mutt.1 http://mutt.org
+pass.1 https://www.passwordstore.org
+newsboat.1 https://newsboat.org
+stagit.1 https://git.codemadness.org/stagit/
+git-daemon.1 https://git-scm.com/docs/git-daemon
diff --git a/bin/genatom.sh b/bin/genatom.sh
@@ -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;https://man.openbsd.org/%N.%S' "$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#https://man.openbsd.org/%s#%s#g", $1, $2 } END { printf "\n" }' "$REPO/LINKS")"
cat <<EOENTRY
]]>
</content>
diff --git a/bin/genpost.sh b/bin/genpost.sh
@@ -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 -> st.suckless.org instead of openbsd.org)
mandoc -Thtml -O 'man=%N.html;https://man.openbsd.org/%N.%S,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;https://man.openbsd.org/%N.%S,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#https://man.openbsd.org/%s#%s#g", $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 https://euchre.live
.It
.Lk https://mojolicious.org Mojolicious
-.It
-.Lk https://git.codemadness.org/stagit/ 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 https://newsboat.org newsboat(1)
+.Xr newsboat 1
to commercial apps like
.Lk https://feedly.com 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 https://www.vim.org 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 https://git-scm.com/ 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 https://www.gnu.org/software/bash/ bash(1)
+.Xr bash 1
as my Linux shell (zsh previously, moved for work reasons early-2018)
.It
-.Lk https://dwm.suckless.org/ dwm(1)
+.Xr dwm 1
as my window manager (since early Linux days, early-2019)
.It
-.Lk https://st.suckless.org/ st(1)
+.Xr st 1
as my terminal emulator (also early-2019)
.It
-.Lk http://mutt.org 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 https://www.passwordstore.org pass(1)
+.Xr pass 1
for password/secret management (late-2020)
.El
.Pp
