Undone at 04:28, 25 March 2007

2007-03-25T04:28:05Z

← Older revision		Revision as of 04:28, 25 March 2007
Line 91:		Line 91:

	*SEE ALSO - Document here other related commands and manual sections, especially if not obvious.		*SEE ALSO - Document here other related commands and manual sections, especially if not obvious.

			[[Category:Helpdesk]]

Undone: /* Headings used in a man page */

2007-02-11T03:59:05Z

Headings used in a man page

← Older revision		Revision as of 03:59, 11 February 2007
Line 60:		Line 60:
	== Headings used in a man page ==		== Headings used in a man page ==

	A quick google and here are the main headings used in man pages - now ~~its~~ time for you to try your own. :)		A quick google and here are the main headings used in man pages - now it's time for you to try your own. :)

	*NAME - This should be the product name followed by a short description. The text on this line is also used as the keyword list for man -k and apropos.		*NAME - This should be the product name followed by a short description. The text on this line is also used as the keyword list for man -k and apropos.

Undone: /* A man-ly example */

2007-02-11T03:58:49Z

A man-ly example

← Older revision		Revision as of 03:58, 11 February 2007
Line 49:		Line 49:

	SYNOPSIS		SYNOPSIS
	sample [options]		sample [options]

	.SH SYNOPSIS		.SH SYNOPSIS

Undone at 03:57, 11 February 2007

2007-02-11T03:57:14Z

Show changes

Undone at 03:40, 11 February 2007

2007-02-11T03:40:01Z

New page

Creating your own man page

[ Author : John Doyle (art_wolf) : 2005 ]

This is simply a little tutorial for fun :) You will finally have your name up their with 'find', 'sed' and 'hey'!
The nroff -man Command

The nroff command is an emulator and by giving the -man option it outputs the file in a manual page style. This prints everything out so it is best to catch the output and pipe it into 'more' like so:

nroff -man ~art_wolf/art_wolf.8 | more

It is the nroff syntax we will be looking at and how to make the output resemble a man page.
Nroff's Syntax

nroff has several settings and we will be using most of them to achive our look. Here are the main ones:

Request Cause Explanation
Break?

.B t no Text t is bold. Quote to imbed blanks.
.I t no Text t is italic. Quote to imbed blanks.
.TP x yes Set prevailing indent to 5. Begin
indented paragraph with hanging tag
given by first argument. Tag x is
always placed on a separate line.
.LP yes Same as .PP.
.PP yes Begin paragraph. Set prevailing
indent to 5.
.RE yes End of relative indent. Set prevailing
indent to amount of starting .RS.
.RS yes Start relative indent, move left margin
in distance 5.
.SH t yes Subhead. Quote to imbed blanks.
.SS t yes Subsection. Quote to imbed blanks. No
indent for t.
.TH n s c v d yes Begin page named n of chapter s; c is
the chapter name; d is the date of the
most recent change; v is version number.
Sets prevailing indent and tabs to 5.

A man-ly example

Read a sample man page here. Save this to your home directory and rename it 'username.8' and modify it to your hearts content :)

.TH USERNAME 1 This is part of a normal man page layout which prints USERNAME(1) at the corners of the man page.

.SH SECTION This sets a head section..surprise surprise.. used like this:

SYNOPSIS
sample [options]

.SH SYNOPSIS
sample [options]

.TP 5 This gives a break and is used between options to seperate them.

.B sample This sets everything on the line to bold. If there are spaces in the word everything must be enclosed with quotes.
Headings used in a Man page

A quick google and here are the main headings used in man pages - now its time for you to try your own :)

NAME

This should be the product name followed by a short description. The text on this line is also used as the keyword list for man -k and apropos.

SYNOPSIS or SYNTAX

Document here the complete syntax of the command used to invoke the product.

AVAILABILITY

Document here the OS flavors for which the program is available.

DESCRIPTION

Document here a full but succinct description of the use of the product.

OPTIONS

Document here all the options available for the invoking command.

EXAMPLES

Document here situations in which the program can be used, if there are uses that are not obvious.

NOTES

Document here any information the user should be aware of when using the command.

MESSAGES AND EXIT CALLS

Document here all errors and other messages returned to the user. Include the cause and the recovery actions whenever appropriate and possible.

AUTHOR

Document here the product coordinator and/or the major developers and contributors, along with their particular areas of expertise, as appropriate.

HISTORY

Document here the significant changes in each release of the product.

RESOURCES

If your product is designed to work under X windows, document here any X resources that affect the product's behavior.

FILES

Document here all files, or at least their directories if there are too many files. Also mention here any files in the user's home area that are needed/accessed (e.g., $HOME/.mh_profile, $HOME/Mail/components for the mh and exmh products).

BUGS

Document here things that do not (yet!) work as designed. Provide work-arounds whenever possible.

CAVEATS

Document here things that work as designed but which may be unclear or surprising to the user. (This is the System V replacement for the BUGS category; you too can pretend your product has no bugs!)

SEE ALSO

Document here other related commands and manual sections, especially if not obvious.

Creating Man Pages - Revision history

Undone at 04:28, 25 March 2007

Undone: /* Headings used in a man page */

Undone: /* A man-ly example */

Undone at 03:57, 11 February 2007

Undone at 03:40, 11 February 2007