Skip to content

Latest commit

 

History

History
89 lines (53 loc) · 2.53 KB

Markdown_Output_Format.md

File metadata and controls

89 lines (53 loc) · 2.53 KB
Raw

Markdown Output Format

This file describes the Markdown output format generated by the man-to-md filter program.

First Chapter

The first section of the output will be generated from the input's .TH line, NAME section, and SYNOPSIS section.

This is the output format:

# programName(manSection) - programDescription

Version programVersion, programDate

```
programSyntax
```

Comments

  • If the --comment option is used, the first output line will be a hidden comment.
  • Comments in the nroff input will be removed.

Markdown does not really support comments, we're using this trick instead:

[//]: # (This file was autogenerated from the man page with 'make README.md')

Section Titles

  • The document title is a top-level headline (#).
  • All section titles (.SH) get converted to top-level headlines (#) as well.
  • All subsection titles (.SS) get converted to third-level headlines (###).

Line Breaks

  • Line breaks are done by appending two spaces to the preceding line.
  • Paragraph breaks are done through a simple blank like.

Code Blocks

  • If the filter program is run without the -f option (no formatting in code), code blocks will be output with four spaces indentation.
  • With the -f option (limited formatting in code allowed), code blocks will be output as <pre><code> blocks with <b>/<i> HTML formatting.

Special Characters

  • Input sequences such as \(lq will be converted directly to their UTF-8 representation.
    • Exception: \  will be converted to &nbsp; (HTML entity).
  • See Commands.md for a list of recognized sequences.

Text Formatting

  • Bold text (from .B or \fR) will be formatted with **.
  • Italic text (from .I or \fI) will be formatted with _.

Lists

  • Lists (.TP/.IP, end with .P) will be converted to simple * list items.
  • Multi-line list items will be indented with two spaces.
  • Sub lists (.RS–.RE) will be indented with four extra spaces.
  • .TP item titles will have two trailing spaces before the linebreak to force a visible linebreak between the item title and the description.

Links

  • Plain URLs won't be changed, as most Markdown viewers will automatically turn them into a link.
  • Other links will be converted to [title](url).
  • E-mail links will be converted to [addr](mailto:addr).