Converting a man page to markdown is a three step process:
- installing a tool that can convert the source of a man page to markdown
- finding the location of the man page source
- doing the actual conversion
Tool to convert man to markdown
The source format of man pages is troff, which is usually converted by man
using groff, or a set of macros.
My initial thought for the first problem was to use pandoc, but as I found earlier in pandoc oneliner from reStructuredText to html, on MacOS, the pandoc can write groff
format, but not read it.
Luckily doing a pandoc from groff to markdown – Google Search, I bumped into [WayBack] Convert groff to markdown · Issue #8 · neomutt/neomutt-docs · GitHub which lead to mandoc – Wikipedia.
Since I already had homebrew installed, getting mandoc was simple: brew install mandoc
.
Finding the man page source
Earlier in the process when searching for pandoc based conversions, I found the solution for the second problem too: [WayBack] Man page with preserved text decorations, proportional text and fixed-width code – Unix & Linux Stack Exchange taught me about the -w
option, but there is actually a -W
option that works better if you have multiple pages for a keyword:
-w
or--path
Don’t actually display the man pages, but do print the location(s) of the files that would be formatted or displayed. If no argument is given: display (onstdout
) the list of directories that is searched byman
for man pages. If manpath is a link toman
, then “manpath
” is equivalent to “man --path
“.
-W
Like-w
, but print file names one per line, without additional information. This is useful in shell commands likeman -aW man | xargs ls -l
Actual conversion for fsck_hfs
It all came down to a one-liner:
mandoc -T markdown `man -w fsck_hfs` > /tmp/fsck_hfs.8.md
Note the order here is important this will fail with an error:
mandoc `man -w fsck_hfs` -T markdown > /tmp/fsck_hfs.8.md
mandoc: -T: ERROR: No such file or directory mandoc: markdown: ERROR: No such file or directory
–jeroen