man-to-md(1) - Converts nroff man pages to Markdown

Version 0.17.0, December 2020

$ man-to-md.pl [OPTIONS] <manpage.roff >output.md

Description

This program is a filter that reads man(7)-formatted nroff man pages and outputs Markdown. It can be used to automatically convert man page files to Markdown README files.

Options

• -p, --paste-section-after SECTION:FILENAME
  Instructs the program to attach a Markdown file after the section named SECTION has been completely written to the output. SECTION must be an exact match of the input section name. If the input contains no such section, the file will be attached to the end of the output. The attached file contents will have the exact FILENAME (without the .md extension) as their top-level section title.
  This option can be supplied more than once. Multiple files for the same section will be attached in the options' order.
• -P, --paste-section-before SECTION:FILENAME
  Like --paste-section-after, but attaches the file contents to the output just before the named section is written.
• --paste-after SECTION:FILENAME
  Like --paste-section-after, but does not add a section title.
• --paste-before SECTION:FILENAME
  Like --paste-section-before, but does not add a section title.
• -c, --comment [COMMENT]
  Adds an invisible comment as first line. Without the argument, it uses this default comment:
  “This file was autogenerated from the man page with 'make README.md'”.
• --escaped-dashes
  Don't remove the backslash from escaped dashes (\-).
• -w, --word WORD
  Adds a WORD to the list of known words not to be titlecased in section titles. (All other words will be titlecased except some known English stopwords which will be lowercased.)
  This option can be supplied more than once to add multiple known words.
• -f, --formatted-code
  Allows simple formatting in .nf-.fi code blocks and in the Synopsis line. (Without this option, all formatting in code block and in the Synopsis line will be removed.)
• -h, --help
  Shows program help.
• -V, --version
  Shows version and license information.

Standards

This program understands many man(7) nroff commands and macros commonly used in man page files. For a complete list, see doc/Commands.md.

The program emits Markdown syntax that should be readable with most Markdown editors/viewers. See doc/Markdown_Output_Format.md for more information.

The program makes several assumptions about the input format that are not standardized but seem to be fairly commonplace in man pages; see doc/Input_Format.md. It does not yet understand the newer mdoc(7) format.

License

GNU GPL v3

See Also

Project homepage: https://github.com/mle86/man-to-md

Author

Maximilian Eul <maximilian@eul.cc> (https://github.com/mle86)