Jump to content

Creating Man Pages: Difference between revisions

Creating Man Pages (view source)

Revision as of 03:57, 11 February 2007

307 bytes removed ,  11 February 2007
m
no edit summary
mNo edit summary
 
mNo edit summary
Line 1: Line 1:
Creating your own man 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'!


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 -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:
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
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.
It is the nroff syntax we will be looking at and how to make the output resemble a man page.
Nroff's Syntax
 
== Nroff's Syntax ==


nroff has several settings and we will be using most of them to achive our look. Here are the main ones:
nroff has several settings and we will be using most of them to achive our look. Here are the main ones:
{| border="1" cellpadding="2"
!width="100"|Request
!width="100"|Cause Break
!width="225"|Explanation
|-
|.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.
|}             


    Request        Cause    Explanation
== A man-ly example ==
                    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 :)
Read a sample man page here. Save this to your home directory and rename it 'username.8' and modify it to your hearts content :)
Line 56: Line 57:


.B sample This sets everything on the line to bold. If there are spaces in the word everything must be enclosed with quotes.
.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.
== Headings used in a man page ==


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


Document here all errors and other messages returned to the user. Include the cause and the recovery actions whenever appropriate and possible.
*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.


AUTHOR
*SYNOPSIS or SYNTAX - Document here the complete syntax of the command used to invoke the product.


Document here the product coordinator and/or the major developers and contributors, along with their particular areas of expertise, as appropriate.
*AVAILABILITY - Document here the OS flavours for which the program is available.


HISTORY
*DESCRIPTION - Document here a full but succinct description of the use of the product.


Document here the significant changes in each release of the product.
*OPTIONS - Document here all the options available for the invoking command.


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


If your product is designed to work under X windows, document here any X resources that affect the product's behavior.
*NOTES - Document here any information the user should be aware of when using the command.


FILES
*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.


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).
*AUTHOR - Document here the product coordinator and/or the major developers and contributors, along with their particular areas of expertise, as appropriate.


BUGS
*HISTORY - Document here the significant changes in each release of the product.


Document here things that do not (yet!) work as designed. Provide work-arounds whenever possible.
*RESOURCES - If your product is designed to work under X windows, document here any X resources that affect the product's behaviour.


CAVEATS
*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).


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!)
*BUGS - Document here things that do not (yet!) work as designed. Provide work-arounds whenever possible.


SEE ALSO
*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!).


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.
Undone
496

edits

Retrieved from "https://wiki.redbrick.dcu.ie/Special:MobileDiff/4947"