💾 Archived View for unixcat.coffee › gemlog › 2021-05-10-gtfm.gmi captured on 2021-12-03 at 14:04:38. Gemini links have been rewritten to link to archived content

View Raw

More Information

-=-=-=-=-=-=-

GTFM (Generate the Friendly Manual)

The 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

I 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.

The script does the following 8 tasks:

• Downloads and extracts the tar.gz archive of the Zsh Manual from their website
• Removes some unneeded files
• Removes some HTML noise using Sed
• Renames the file extensions from .html to .md
• Converts html to GitHub-flavored Markdown using Pandoc
• Moves the resulting markdown files to the temporary mdBook src directory
• Generates a table of contents for each file using DocToc.
• Calls a Python script to generate the SUMMARY.md by scraping the original Zsh Manual’s table of contents.

There 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.

UPDATE: I now use a Perl script to do all of these tasks.

Original Zsh Manual

Modernized Zsh Manual

https://github.com/hyperreal64/zsh-manual-mdBook

~~~

Last updated: 2021-11-18

Gemlog archive

Back to unixcat.coffee