.TH MD2MAN 5                        2016\-03\-04                            5.1.1
.SH NAME
.PP
md2man \- UNIX manual page flavoring for Markdown \[la]http://daringfireball.net/projects/markdown/syntax\[ra]
.SH DESCRIPTION
.PP
md2man makes the Markdown \[la]http://daringfireball.net/projects/markdown/syntax\[ra] format more friendly for writing UNIX manual
pages by extending its syntax, semantics, and assumed processing extensions.
.SS Syntax
.PP
md2man extends Markdown \[la]http://daringfireball.net/projects/markdown/syntax\[ra] syntax by recognizing three kinds of paragraphs,
analogous to the underlying \fB\fC\&.PP\fR, \fB\fC\&.TP\fR, and \fB\fC\&.IP\fR directives in 
.BR roff (7).
.SS Normal paragraphs
.PP
Paragraphs whose lines are all indented by exactly zero or one additional
space are considered "normal paragraphs", analogous to \fB\fC\&.PP\fR in 
.BR roff (7):
.PP
.RS
.nf
This is a normal paragraph.

This is also
a normal
paragraph.

And
this
 is
 a
  normal
   paragraph
    too.
.fi
.RE
.SS Tagged paragraphs
.PP
Paragraphs whose first line is indented by less than two additional spaces and
whose subsequent lines are all uniformly indented by exactly two additional
spaces are considered "tagged paragraphs", analogous to \fB\fC\&.TP\fR in 
.BR roff (7):
.PP
.RS
.nf
This is a
  tagged
  paragraph.
.fi
.RE
.SS Indented paragraphs
.PP
Paragraphs whose lines are all uniformly indented by exactly two additional
spaces are considered "indented paragraphs", analogous to \fB\fC\&.IP\fR in 
.BR roff (7):
.PP
.RS
.nf
  This is an
  indented
  paragraph.
.fi
.RE
.SS Semantics
.PP
md2man extends Markdown \[la]http://daringfireball.net/projects/markdown/syntax\[ra] semantics by treating top\-level headings specially.
.SS Top\-level headings
.PP
The first top\-level \fB\fC<h1>\fR heading found in the input is considered to be the
\fB\fC\&.TH\fR directive in 
.BR roff (7), 
described under "Title line" in 
.BR man-pages (7) 
thus:
.PP
.RS
.RS
.nf
\&.TH title section date source manual
.fi
.RE
.TP
title
The title of the man page, written in all caps (e.g., \fB\fCMAN\-PAGES\fR).
.TP
section
The section number in which the man page should be placed (e.g., \fB\fC7\fR).
.TP
date
The date of the last revision, written in the form YYYY\-MM\-DD.
.TP
source
The source of the command, function, or system call (e.g., \fB\fCLinux\fR).
.TP
manual
The title of the manual (e.g., \fB\fCLinux Programmer's Manual\fR).
.RE
.PP
Any subsequent top\-level headings are treated as second\-level \fB\fC<h2>\fR headings.
.SS Extensions
.PP
md2man enables the following [Redcarpet] extensions while reading Markdown \[la]http://daringfireball.net/projects/markdown/syntax\[ra]:
.RS
.IP \(bu 2
tables
.IP \(bu 2
autolink
.IP \(bu 2
superscript
.IP \(bu 2
strikethrough
.IP \(bu 2
fenced_code_blocks
.RE
.SS Examples
.PP
Below is a complete example of an 
.BR md2man (5) 
formatted manual page adapted from
the Linux Man Page Howto \[la]http://www.schweikhardt.net/man_page_howto.html\[ra]
guide by Jens Schweikhardt.  The result of processing \[la]../man0/EXAMPLE.html\[ra]
this example with 
.BR md2man-html (1) 
has been bundled along with this manual page.
.PP
.RS
.nf
FOO 1 "MARCH 1995" Linux "User Manuals"
=======================================

NAME
\-\-\-\-

foo \- frobnicate the bar library

SYNOPSIS
\-\-\-\-\-\-\-\-

`foo` [`\-bar`] [`\-c` *config\-file*] *file* ...

DESCRIPTION
\-\-\-\-\-\-\-\-\-\-\-

`foo` frobnicates the bar library by tweaking internal symbol tables. By
default it parses all baz segments and rearranges them in reverse order by
time for the xyzzy(1) linker to find them. The symdef entry is then compressed
using the WBG (Whiz\-Bang\-Gizmo) algorithm. All files are processed in the
order specified.

OPTIONS
\-\-\-\-\-\-\-

`\-b`
  Do not write "busy" to stdout while processing.

`\-c` *config\-file*
  Use the alternate system wide *config\-file* instead of */etc/foo.conf*. This
  overrides any `FOOCONF` environment variable.

`\-a`
  In addition to the baz segments, also parse the blurfl headers.

`\-r`
  Recursive mode. Operates as fast as lightning at the expense of a megabyte
  of virtual memory.

FILES
\-\-\-\-\-

*/etc/foo.conf*
  The system wide configuration file. See foo(5) for further details.

*~/.foorc*
  Per user configuration file. See foo(5) for further details.

ENVIRONMENT
\-\-\-\-\-\-\-\-\-\-\-

`FOOCONF`
  If non\-null the full pathname for an alternate system wide */etc/foo.conf*.
  Overridden by the `\-c` option.

DIAGNOSTICS
\-\-\-\-\-\-\-\-\-\-\-

The following diagnostics may be issued on stderr:

**Bad magic number.**
  The input file does not look like an archive file.

**Old style baz segments.**
  `foo` can only handle new style baz segments. COBOL object libraries are not
  supported in this version.

BUGS
\-\-\-\-

The command name should have been chosen more carefully to reflect its
purpose.

AUTHOR
\-\-\-\-\-\-

Jens Schweikhardt <howto@schweikhardt.net>

SEE ALSO
\-\-\-\-\-\-\-\-

bar(1), foo(5), xyzzy(1), [Linux Man Page Howto](
http://www.schweikhardt.net/man_page_howto.html)
.fi
.RE
.SH SEE ALSO
.PP
Markdown \[la]http://daringfireball.net/projects/markdown/syntax\[ra], 
.BR man-pages (7), 
.BR roff (7), 
.BR md2man-roff (1), 
.BR md2man-html (1)