Man page

From Just Solve the File Format Problem
(Difference between revisions)
Jump to: navigation, search
(Added sample files)
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{DISPLAYTITLE:man page}}
 
{{FormatInfo
 
{{FormatInfo
 
|name=man page
 
|name=man page
Line 23: Line 24:
  
 
== Specifications ==
 
== Specifications ==
* http://manpages.ubuntu.com/manpages/lucid/man7/man.7.html
+
Typical man pages are written with the <tt>man</tt> or <tt>mdoc</tt> formats, occasionally with a bit of pure troff sprinkled in.
 
+
* <tt>man</tt>: https://www.mankier.com/7/man, or run <code>man 7 man</code>
Or run:
+
** 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 [https://man.openbsd.org/roff.7 roff(7)] for what BSDs consider necessary.
  $ man 7 man
+
* <tt>mdoc</tt>: https://mandoc.bsd.lv/man/mdoc.7.html, or run <code>man 7 mandoc_mdoc</code>
 +
** This is the semantic, "modern" way of writing manpages, and there are macros for the program name, the synopsis, ... everything.
  
 
== Writing a man page ==
 
== Writing a man page ==
Line 96: Line 98:
  
 
:Todo: There seems to be .IX block that often duplicates what other blocks do. What is it?
 
: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 ==
 
== Software ==
Line 102: Line 105:
 
* [http://www.gnu.org/software/groff/ GNU troff (groff)]
 
* [http://www.gnu.org/software/groff/ GNU troff (groff)]
 
* [http://mdocml.bsd.lv/ mandoc]
 
* [http://mdocml.bsd.lv/ mandoc]
 +
 +
== Sample files ==
 +
* https://telparia.com/fileFormatSamples/document/manPage/
  
 
== Links ==
 
== Links ==

Revision as of 20:31, 29 July 2021

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

Sample files

Links

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox