The Wiert Corner – irregular stream of stuff

Jeroen W. Pluimers on .NET, C#, Delphi, databases, and personal interests

  • My badges

  • Twitter Updates

  • My Flickr Stream

  • Pages

  • All categories

  • Enter your email address to subscribe to this blog and receive notifications of new posts by email.

    Join 1,980 other followers

MacOS: converting a man page to markdown

Posted by jpluimers on 2020/03/09

Converting a man page to markdown is a three step process:

  1. installing a tool that can convert the source of a man page to markdown
  2. finding the location of the man page source
  3. 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 (on stdout) the list of directories that is searched by man for man pages. If manpath is a link to man, 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 like man -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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

 
%d bloggers like this: