My personal website and Gemini capsule
hyperreal.bsky.moonshadow.dev
1# GTFM (Generate the Friendly Manual)
2
3The Zsh Manual is already friendly; I just decided to make it more hospitable by publishing an mdBook version. I endeavored to automate this with a script and deploy the mdBook via Netlify. The result can be viewed here: https://zsh-manual.netlify.app
4
5I started out writing a Python script, but after some progress I realized that the task could be done more efficiently with my homies Bash, Sed, and Find, though I kept the bit of Python code that generates the SUMMARY.md file.
6
7The script does the following 8 tasks:
8
9* Downloads and extracts the tar.gz archive of the Zsh Manual from their website
10* Removes some unneeded files
11* Removes some HTML noise using Sed
12* Renames the file extensions from .html to .md
13* Converts html to GitHub-flavored Markdown using Pandoc
14* Moves the resulting markdown files to the temporary mdBook src directory
15* Generates a table of contents for each file using DocToc.
16* Calls a Python script to generate the SUMMARY.md by scraping the original Zsh Manual’s table of contents.
17
18There are probably some minor issues that could be found by perusing the mdBook but all in all the content seems to have transferred over nicely. The only parts that are missing are the indexes from the original Zsh Manual–their HTML structure doesn’t lend itself well to Markdown–but I reckon there is little need for them now with mdBook’s search feature.
19
20UPDATE: I now use a Perl script to do all of these tasks.
21
22=> http://zsh.sourceforge.net/Doc/ Original Zsh Manual
23=> https://zsh-manual.netlify.app/ Modernized Zsh Manual
24=> https://github.com/hyperreal64/zsh-manual-mdBook
25
26## END
27Last updated: 2021-11-18
28
29=> ../gemlog/ Gemlog archive
30=> ../ Back to hyperreal.coffee