In this lesson, you will learn how to transform the comments inside your Bash scripts into professional-grade man pages so that other users can understand your code without reading the source.
The Problem of Hidden Logic
As your scripts grow in complexity, relying on internal comments alone is often insufficient for users who just want to know how to run your tool. The standard Linux way to provide help is through man (manual) pages. Instead of writing a separate text file that quickly becomes outdated, you can use Documentation Extraction to pull documentation directly from your script’s metadata.
Using help2man
The most common tool for this is help2man. It works by executing your script with a special flag (usually --help) and formatting the output into a troff-formatted file—the language used by the man system.
To make this work, you must structure your script's --help output clearly. Here is how your script header should look:
#!/bin/bash
# myscript.sh - A tool to process system logs
if [[ "$1" == "--help" ]]; then
echo "myscript - Processes system logs"
echo "Usage: myscript [OPTION]"
echo ""
echo "Options:"
echo " -v Verbose mode"
exit 0
fi
Once your script provides a clean help menu, you can generate a real manual page by running:
help2man ./myscript.sh > myscript.1
This creates a file named myscript.1. You can then preview it immediately using man -l myscript.1. By embedding your documentation inside the script itself, you ensure that every time you update your code's functionality, your manual page remains synced and accurate.
Why This Matters
For a developer, this automation removes the tedious task of maintaining two separate sources of truth. If you update the --help block, a quick re-run of help2man updates the manual page, keeping your project professional and easy to navigate for any system administrator.
Key Takeaway: Documentation extraction allows you to treat your manual pages as code, ensuring that your script’s internal help text and official man-pages never drift out of sync.