do man page translation outside of mdbook

Author: tomeichlersmith

.github/workflows/mdbook.yml

@@ -32,23 +32,12 @@ jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      MDBOOK_VERSION: 0.4.30
+      MDBOOK_VERSION: 0.4.45
+      MDBOOK_ADMONISH_VERSION: 1.19.0 # need to re-run mdbook-admonish install if updating version
     steps:
       - uses: actions/checkout@v4
-      - name: Install mdBook and mdbook-cmdrun
-        run: |
-          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
-          rustup update
-          cargo install --version ${MDBOOK_VERSION} mdbook --locked
-          cargo install --git https://github.com/tomeichlersmith/mdbook-cmdrun --branch 18-check-exit-status mdbook-cmdrun --locked
-      - name: Install aha
-        run: sudo apt install aha
-      - name: Check Necessities
-        run: |
-          aha --version
-          ul --version
-          man --version
-          mdbook --version
+      - name: Install mdBook
+        run: ./ci/install-mdbook
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
@@ -57,6 +46,12 @@ jobs:
         working-directory: docs
       - name: Copy install script to website
         run: cp install uninstall ./docs/book/
+      - name: Check Links
+        id: lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          fail: true
+          args: ./docs/book
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

ci/build-docs

@@ -0,0 +1,26 @@
+#!/bin/sh
+# build the docs website
+# DEPENDENCIES
+#   mdbook
+#   man
+#   ul
+#   aha
+
+set -o nounset
+set -o errexit
+
+# convert a man page into a corresponding html page
+#
+# We use the '.md' suffix rather than '.html' so that mdbook still
+# processes the html into its own style with the side bar and header.
+mkdir -p docs/src/manual
+for man_page in man/man1/*; do
+  page_name="$(basename "${man_page}")"
+  output_file="docs/src/manual/${page_name}.md"
+  echo "<pre>" > "${output_file}"
+  MAN_KEEP_FORMATTING=1 COLUMNS=80 man "${man_page}" | ul | aha --no-header >> "${output_file}"
+  echo "</pre>" >> "${output_file}"
+done
+
+cd docs
+mdbook build

ci/install-mdbook

@@ -0,0 +1,52 @@
+#!/bin/sh
+
+set -o errexit
+set -o nounset
+
+# Assume the environment variables MDBOOK_VERSION and MDBOOK_ADMONISH_VERSION are set
+
+# Download a tar ball and then unpack it into a destination
+# Arguments
+#   1 - URL for the .tar.gz to download
+#   2 - target directory to unpack into
+download() {
+  wget -q -O - "${1}" | tar -xz --directory "${2}"
+}
+
+help() {
+  cat <<\HELP
+
+ USAGE:
+  ./.github/install-mdbook [target]
+
+ ARGUMENTS:
+  target : directory to download mdbook and mdbook-admonish into
+
+ ENVIRONMENT:
+  We assume that MDBOOK_VERSION and MDBOOK_ADMONISH_VERSION are set
+  to the desired versions like how it is done in the CI workflow.
+
+HELP
+}
+
+target="${HOME}/.local/bin"
+while [ "${#}" -gt 0 ]; do
+  case "${1}" in
+    -h|--help)
+      help
+      exit 0
+      ;;
+    *)
+      target="${1}"
+      ;;
+  esac
+  shift
+done
+
+mkdir -p "${target}"
+download \
+  https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz \
+  "${target}"
+download \
+  https://github.com/tommilligan/mdbook-admonish/releases/download/v${MDBOOK_ADMONISH_VERSION}/mdbook-admonish-v${MDBOOK_ADMONISH_VERSION}-x86_64-unknown-linux-gnu.tar.gz \
+  "${target}"

docs/src/SUMMARY.md

@@ -8,10 +8,10 @@
   - [Sidebar on Operating Systems](./os-sidebar.md)
 - [Tuning the denv](./tune.md)
 - [Command Reference Manual](./manual.md)
-  - [denv](./manual/denv.md)
-  - [denv-init](./manual/denv-init.md)
-  - [denv-config](./manual/denv-config.md)
-  - [denv-check](./manual/denv-check.md)
+  - [denv](./manual/denv.1.md)
+  - [denv-init](./manual/denv-init.1.md)
+  - [denv-config](./manual/denv-config.1.md)
+  - [denv-check](./manual/denv-check.1.md)
 - [Developing the Environment](./env_dev.md)
 
 # Contributing