From c0f311467d522553c679c39cb7b549450cf39371 Mon Sep 17 00:00:00 2001 From: Alex Karle Date: Mon, 13 Sep 2021 23:56:20 -0400 Subject: [PATCH] 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! --- LINKS | 10 ++++++++++ bin/genatom.sh | 4 +++- bin/genpost.sh | 4 +++- self-hosted.7 | 6 ++---- use-feeds.7 | 2 +- uses.7 | 14 +++++++------- 6 files changed, 26 insertions(+), 14 deletions(-) create mode 100644 LINKS diff --git a/LINKS b/LINKS new file mode 100644 index 0000000..46a1984 --- /dev/null +++ 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 index 588a2f7..34a8347 100755 --- 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 '/Miscellaneous Information Manual<\/td>/d' + | sed '/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 < diff --git a/bin/genpost.sh b/bin/genpost.sh index 34e93aa..0fe7cfa 100755 --- 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##&# ' \ @@ -21,4 +22,5 @@ mandoc -Thtml -O 'man=%N.html;https://man.openbsd.org/%N.%S,style=style.css' \ -e 's##

\ © 2019-2021 Alex Karle | Home | License\

\ -&#' +&#' | 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 index cf946d4..3bad0c0 100644 --- 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 index ad45626..cccfb01 100644 --- 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 index ce4d4e5..fe12870 100644 --- 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 -- libgit2 1.1.1