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:
-wor--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 bymanfor man pages. If manpath is a link toman, then “manpath” is equivalent to “man --path“.
-WLike-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.mdmandoc: -T: ERROR: No such file or directory mandoc: markdown: ERROR: No such file or directory
–jeroen
