Man page
From Just Solve the File Format Problem
(Difference between revisions)
(Writing a page) |
Dexvertbot (Talk | contribs) m (Change telparia.com samples link to template) |
||
| (10 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
| + | {{DISPLAYTITLE:man page}} | ||
{{FormatInfo | {{FormatInfo | ||
|name=man page | |name=man page | ||
| Line 23: | Line 24: | ||
== Specifications == | == Specifications == | ||
| − | * | + | 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. | ||
== Writing a man page == | == Writing a man page == | ||
| Line 35: | Line 37: | ||
! code | ! code | ||
! meaning | ! meaning | ||
| + | |- | ||
| .TH | | .TH | ||
| First command (see below) | | First command (see below) | ||
| Line 68: | Line 71: | ||
The first command (non-comment block) is often (but not necessarily) .TH, it's format consists of the following: | The first command (non-comment block) is often (but not necessarily) .TH, it's format consists of the following: | ||
| − | {| class=' | + | {| class='wikitable' |
! block name | ! block name | ||
! meaning | ! meaning | ||
| Line 95: | 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 101: | 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
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.
