Man page

Latest revision as of 04:07, 28 December 2023

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.

[edit] 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

[edit] 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.

[edit] Writing a man page

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

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

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.

[edit] Software

• man
• man-db
• GNU troff (groff)
• mandoc

[edit] Sample files

• dexvert samples — document/manPage

[edit] Links

• Wikipedia: Man page
• tldr: Simplified and community-driven man pages