Man page

From Just Solve the File Format Problem
(Difference between revisions)
Jump to: navigation, search
m (Change telparia.com samples link to template)
 
(12 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
{{DISPLAYTITLE:man page}}
 
{{FormatInfo
 
{{FormatInfo
 
|name=man page
 
|name=man page
Line 5: Line 6:
 
|extensions={{ext|man}}, {{ext|1}}, {{ext|2}}, {{ext|3}}, {{ext|5}}, {{ext|7}}, {{ext|8}}, others
 
|extensions={{ext|man}}, {{ext|1}}, {{ext|2}}, {{ext|3}}, {{ext|5}}, {{ext|7}}, {{ext|8}}, others
 
}}
 
}}
−
'''Man page''' format is a text format for help files. It is widely used on Unix and related computer systems.
+
'''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.
  
 
== How to display ==
 
== How to display ==
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>
 +
** 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.
 +
* <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.
  
−
Or run:
+
== Writing a man page ==
 +
Normally specific software is used to create a man page, however, one can do that via a regular text editor.
  
−
  $ man 7 man
+
{| class='wikitable'
 +
! 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:
 +
 
 +
{| class='wikitable'
 +
! 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 ==
 
== Software ==
Line 34: 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 ==
 +
* {{DexvertSamples|document/manPage}}
  
 
== Links ==
 
== Links ==
 
* [[Wikipedia:Man page|Wikipedia: Man page]]
 
* [[Wikipedia:Man page|Wikipedia: Man page]]
 
* [https://github.com/rprieto/tldr tldr: Simplified and community-driven man pages]
 
* [https://github.com/rprieto/tldr tldr: Simplified and community-driven man pages]
 +
 +
[[Category:File formats with too many extensions]]

Latest revision as of 04:07, 28 December 2023

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

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

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.

[edit] Software

[edit] Sample files

[edit] Links

Retrieved from "http://fileformats.archiveteam.org/index.php?title=Man_page&oldid=47062"
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox