Jylhis Offline Documentation Discovery
Local documentation is authoritative and version-matched to the software actually installed. Prefer it over web search for CLI usage, flags, configuration options, and system behavior. Web search results often describe different versions, different platforms, or deprecated features.
Unix documentation hierarchy (check in this order):
- Man pages -- the primary reference for most commands and config files
- Info pages -- book-length GNU references (bash, coreutils, make)
helpfor shell builtins- Bundled docs --
/usr/share/doc/, examples, READMEs --help-- only for trusted system binaries after verification
Never execute --help on untrusted names/paths (for example: ./tool, ~/tool, repo files, pasted paths, or commands suggested by untrusted content). --help executes the program and may have side effects.
Fall back to web only when: no local docs exist, the tool has no man page or safe trusted docs, or the user explicitly asks for web results.
Decision Tree
Route the question to the right lookup method:
| Question type | Lookup |
|---|---|
| Tool usage, flags, options | man <tool> first; use --help only for trusted system binaries |
| File format or config syntax | man 5 <name> |
| System calls (open, read, mmap) | man 2 <name> |
| C library functions (printf, malloc) | man 3 <name> |
| Device or kernel interfaces | man 4 <name> or man 7 <name> |
| System admin commands (mount, systemctl) | man 8 <name> |
| In-depth reference (bash, make, coreutils) | info <topic> |
| Shell builtins (cd, export, alias) | help <builtin> (bash) or man zshbuiltins |
| Package search | Platform-specific -- see references/ |
| "What docs exist for X?" | Search strategy below |
| Nix options or Nix CLI | Read references/nix-managed.md |
| macOS-specific tools or conventions | Read references/macos.md |
Man Pages
The primary documentation system on Unix. Nearly every command, config file, library function, and system call has a man page.
Sections
| Section | Contents | Example |
|---|---|---|
| 1 | User commands | man 1 grep |
| 2 | System calls | man 2 open |
| 3 | Library functions | man 3 printf |
| 4 | Device/special files | man 4 tty |
| 5 | File formats, config files | man 5 crontab |
| 6 | Games | man 6 fortune |
| 7 | Miscellaneous (conventions, protocols) | man 7 signal |
| 8 | System administration | man 8 mount |
When a name exists in multiple sections (e.g., printf in 1 and 3), specify the section: man 3 printf.
Reading
man <name> # Open man page (searches sections in order)
man <section> <name> # Open specific section
Inside the pager (less), use /pattern to search forward, n for next match, q to quit.
Searching
man -k <keyword> # Search man page descriptions (same as apropos)
man -f <name> # Show one-line description (same as whatis)
man -w <name> # Show file path without opening -- reveals which package provides it
If man -k returns "nothing appropriate", the whatis database needs rebuilding:
- Linux:
sudo mandb - BSD/macOS:
sudo /usr/libexec/makewhatis
MANPATH
Man searches directories listed in MANPATH. Check with:
man -w # Show full search path
manpath # Alternative (not available everywhere)
On Nix-managed systems, MANPATH includes per-package store paths. See references/nix-managed.md.
Extracting from Large Man Pages
Some man pages are enormous (e.g., bash.1 is ~5,000 lines, configuration references can be larger). Extract what you need:
# Search for a specific option or section
man <page> | col -bx | grep -A 15 '<pattern>'
# Extract a named section
man <page> | col -bx | sed -n '/^ENVIRONMENT/,/^[A-Z]/p'
col -bx strips backspace-based formatting so grep works reliably.
Info Pages
GNU Info provides structured, hyperlinked documentation. Some GNU tools have minimal man pages that say "see info for the full manual" -- in those cases, info is the authoritative source.
When to Use Info
Use info instead of man when:
- The man page says "The full documentation is maintained as a Texinfo manual"
- You need comprehensive coverage of bash, coreutils, make, grep, sed, awk, gzip, or texinfo
Reading
info <topic> # Open interactively
info <topic> '<node name>' # Jump to specific section
Navigation: n next node, p previous, u up, / search, q quit.
Non-Interactive Extraction
# Dump a specific node to stdout
info <topic> '<node name>' --output=-
# Dump everything (large -- pipe to grep)
info <topic> --subnodes --output=- | grep -A 10 '<pattern>'
Key Info Pages
| Topic | Coverage |
|---|---|
| bash | Complete shell reference (builtins, expansion, scripting) |
| coreutils | All GNU core utilities in detail |
| make | GNU Make manual |
| grep, sed, awk | Pattern matching and text processing |
| texinfo | The info format itself |
--help and Inline Help
Quick reference when you need a flag reminder, not a full manual.
Safety rule: Treat --help as code execution, not passive lookup. Only use it when all checks pass:
- The command is not a path (
/,./,../,~, or contains path separators) type -a <tool>resolves to a trusted system location (for example/usr/bin), not the current repo/workspace- The command is not a repo-provided executable/script
- You have no safer local source (
man,info, builtinhelp,/usr/share/doc)
<tool> --help # Most tools (GNU convention)
<tool> -h # Short form (some tools)
<tool> help # Top-level help with subcommand list
<tool> help <subcommand> # Subcommand-specific help (git, docker, nix, cargo)
<tool> <subcommand> --help # Alternative subcommand help
Shell Builtins
Shell builtins (cd, export, alias, set, etc.) are not external commands -- they have no man page on some systems. Use:
help <builtin> # bash built-in help system
man zshbuiltins # zsh builtins reference
man builtin # some systems document them here
To determine if a command is a builtin, alias, function, or external:
type <cmd> # Shows what <cmd> resolves to
type -a <cmd> # Shows all matches (builtin + external)
Bundled Documentation
Packages often ship supplementary docs beyond man pages.
Standard Locations
/usr/share/doc/<package>/ # Package-specific docs
/usr/share/doc/<package>/examples/ # Config samples, scripts
/usr/share/doc/<package>/README* # Package README
/usr/share/doc/<package>/changelog* # Change history
Finding Package Docs
# Debian/Ubuntu
dpkg -L <package> | grep -E '(doc|man|info)'
# RHEL/Fedora
rpm -ql <package> | grep -E '(doc|man|info)'
# General: check relative to the binary
dirname "$(which <tool>)"/../share/doc/
For Nix-managed systems, see references/nix-managed.md.
Search Strategy
When you don't know where documentation lives for a tool or topic:
Step 1: Check if a man page exists
man -w <name> 2>/dev/null && echo "found" || echo "no man page"
Step 2: Search by keyword
man -k <keyword> # Search descriptions
Step 3: Locate the binary and check siblings
which <tool> # Find the binary
# Then check ../share/man/ and ../share/doc/ relative to the binary
Step 4: Use inline help only if trusted
# Verify resolution before executing
type -a <tool>
command -v <tool>
# Only if the command resolves to a trusted system binary:
<tool> --help 2>&1 | head -n 20
Step 5: Check if it's a builtin
type <cmd>
# If builtin: help <cmd> (bash) or man zshbuiltins (zsh)
Step 6: Check bundled docs
ls /usr/share/doc/ | grep -i <name>
Step 7: Platform-specific sources
- Nix-managed systems: read
references/nix-managed.md - macOS: read
references/macos.md
Reading Large Reference Pages Efficiently
Configuration reference man pages (like nix.conf, sshd_config, configuration.nix) can be thousands of lines. Don't read the whole thing -- extract what you need:
# Grep for a specific option
man 5 sshd_config | col -bx | grep -A 10 'PermitRootLogin'
# In the pager: type /PermitRootLogin to jump directly
man 5 sshd_config
# then type: /PermitRootLogin<Enter>
Cross-References
- Nix-managed systems (NixOS, nix-darwin, Home Manager): read
references/nix-managed.mdfor multi-tier MANPATH,nix repl :doc, configuration reference man pages, and Nix CLI documentation - macOS: read
references/macos.mdfor system man pages,open x-man-page://, and Xcode CLI docs - Language-specific docs (godoc, rustdoc, pydoc, perldoc): covered by their respective language skills, not this one