man page

From Just Solve the File Format Problem
Revision as of 22:17, 7 May 2019 by Artoria2e5 (Talk | contribs)

Jump to: navigation, search
File Format
Name man page
Ontology
Extension(s) .man, .1, .2, .3, .5, .7, .8, others

Man page format is a text format for help files. It is widely used on Unix and related computer systems. It is based on troff format.

Contents

How to display

Man pages can be displayed by a standard utility named man. They are usually first installed in a central location.

The man utility can display files directly, without needing them to be installed, but the way to do that depends on the implementation. To display a file named, say, xyzformat.5, at least one of the following commands is likely to work:

 $ man xyzformat.5
 $ man ./xyzformat.5
 $ man -l xyzformat.5
 $ nroff -man xyzformat.5
 $ groff -man -Tutf8 xyzformat.5

If all else fails, read the manual:

 $ man man

Specifications

Typical man pages are written with the man or mdoc formats, occasionally with a bit of pure troff sprinkled in.

  • man: https://www.mankier.com/7/man, or run man 7 man
    • This page also lists a few troff directives sometimes seen in man pages. You will want to be able to process these too.'
    • See also roff(7) for what BSDs consider necessary.
  • mdoc: https://mandoc.bsd.lv/man/mdoc.7.html, or run man 7 mandoc_mdoc
    • This is the semantic, "modern" way of writing manpages, and there are macros for the program name, the synopsis, ... everything.

Writing a man page

Normally specific software is used to create a man page, however, one can do that via a regular text editor.

code meaning
.TH First command (see below)
.SH Section header
.SS Subheading
.P Paragraph
.HP Paragraph with heading indent
.RS Start nested indentation
.RE End nested indentation
.I Italics
.B Bold
.\" Comment

The first command (non-comment block) is often (but not necessarily) .TH, it's format consists of the following:

block name meaning example
name Name of the command that is being documented command
section Manual section (depending on what the command is, if it is software, then 1) 1
centre-footer Usually a date of editing of the manual page "2015 April 23"
left-footer Text that goes in the bottom left
centre-header Text that goes in the top centre
Todo: There seems to be .IX block that often duplicates what other blocks do. What is it?
OpenBSD roff(7) says it's a pod2man thing for table of contents.

Software

Links

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox