pip install pnu-mtoc
mtoc - show Manual table of contents
mtoc [-f|--file|--whatis FILE] [-n|--no MACROS] [-t|--type] [--Dq] [--Pa|--PaSq] [--PaDq] [--Xr] [--debug] [--help|-?] [--version] [--] [SECTION ...]
The mtoc utility shows the Manual table of contents.
Without arguments, it will list the Manual sections listed in man man.
With arguments, it will list the contents of the requested Manual sections in whatis(1) format.
The display can be a little bit improved over standard whatis format by using the --Dq, --Pa, --PaSq, --PaDq and --Xr options, in order to interpret the corresponding mdoc(7) macros.
It can also be used as a database-less substitute of whatis, by using the -f, --file or --whatis options on a Manual page's pathname.
It is possible to discard man(7) or mdoc(7) pages by using the -n or --no options with a man or mdoc parameter.
The -t or --type options will add the type of man page after a pipe character: man, mdoc, other, so(X):{man, mdoc, other}, with X indicating the number of redirections (more than 3 will cause an error in order to prevent loops).
The -f and -n options can be used multiple times.
| Options | Use |
|---|---|
| -f|--file|--whatis FILE | Process a specific file, like whatis(1) |
| -n|--no MACROS | Discard man or mdoc macros |
| -t|--type | Print type of man page (ie. man, mdoc, other, so) |
| --Dq | Interpret .Dq (double quotes) macros |
| --Pa|--PaSq | Interpret .Pa (path) macros as single quoted strings |
| --PaDq | Interpret .Pa (path) macros as double quoted strings |
| --Xr | Interpret .Xr (cross reference) macros |
| --debug | Enable debug mode |
| --help|-? | Print usage and a short help message and exit |
| --version | Print version and exit |
| -- | Options processing terminator |
The MTOC_DEBUG environment variable can also be set to any value to enable debug mode.
The mtoc utility uses the MANPATH environment variable to find man pages. It provides default values both for Unix-like and Windows operating systems.
Locale man pages can be processed if the path where they are stored is added to MANPATH.
Under Windows, the command can use the APPDATA, HOMEPATH and USERPROFILE environment variables to find man pages.
The mtoc utility exits 0 on success, and >0 if an error occurs.
man(1), whatis(1), apropos(1), man(7), mandoc_char(7), mdoc(7), roff(7)
The mtoc utility is not a standard UNIX command.
It tries to follow the PEP 8 style guide for Python code.
Tested OK under Windows.
This utility was made for The PNU project in order to explore providing a Manual under non-Unix operating systems. This turned out to be way more complex than anticipated, forcing me to delve much more deeply in roff(7) macros than originally intended!
Check this excellent History of UNIX Manpages.
This utility is available under the 3-clause BSD license.
The order of names in a man page is sorted alphabetically, which sometimes differ from whatis(1) output. I couldn't find the logic behind whatis behaviour...
It isn't currently possible to process:
- architecture-dependent man pages (for example, in /usr/share/man/man[48]/{aarch64, amd64, arm, i386, powerpc})
- already uncompressed man pages (for example, in /usr/share/man/cat[1-9])