115 lines
2.3 KiB
Groff
115 lines
2.3 KiB
Groff
.\" A brief introduction to manpages in groff
|
|
.TH manpage 5 "" "" "How to write a manpage"
|
|
.\" Name
|
|
.\" Number
|
|
.\" Footer Center
|
|
.\" Left Footer
|
|
.\" Center Header
|
|
|
|
.SH Groff
|
|
.\" #####
|
|
|
|
Macros start either with \fB.\fR at the beginning of a line, or with \fB\\f\fR anywhere else.
|
|
|
|
.SH Common Structure
|
|
.\" ################
|
|
|
|
Manpages for programs \fI(1)\fR usually have the following sections:
|
|
|
|
\fBNAME\fR:
|
|
The name of the programfollowed by a short (oneliner) description
|
|
.br
|
|
\fBSYNOPSIS\fR:
|
|
The syntax used to run the program from the command line
|
|
.br
|
|
\fBDESCRIPTION\fR:
|
|
A detailed description of what the program does
|
|
.br
|
|
\fBOPTIONS\fR:
|
|
A listing of the options, as listed in the \fBSYNOPSIS\fR section
|
|
.br
|
|
\fBBUGS\fR:
|
|
Any known bugs the program has
|
|
.br
|
|
\fBAUTHOR\fR:
|
|
The name and email address of the author
|
|
.br
|
|
\fBSEE ALSO\fR:
|
|
A list of related programs (name and section number)
|
|
|
|
.SH Headers
|
|
.\" #######
|
|
|
|
Start documents with a \fB\.TH\fR macro, followed by at least five parameters:
|
|
|
|
- Name of the manpage
|
|
.br
|
|
- Section number
|
|
.br
|
|
- Center footer
|
|
.br
|
|
- Left footer
|
|
.br
|
|
- Center header
|
|
|
|
The
|
|
.B \.SH
|
|
macro adds a section header
|
|
|
|
.SH Sections
|
|
.\" ########
|
|
|
|
.B Section 1\fR: Executable programs or shell commands
|
|
.br
|
|
.B Section 2\fR: System calls
|
|
.br
|
|
.B Section 3\fR: sLibrary calls
|
|
.br
|
|
.B Section 4\fR: Special files (usually in \fI/dev\fR)
|
|
.br
|
|
.B Section 5\fR: File formats and conventions (eg. \fI/etc/passwd\fR)
|
|
.br
|
|
.B Section 6\fR: Games
|
|
.br
|
|
.B Section 7\fR: Miscellaneous (including macro packages and conventions)
|
|
.br
|
|
.B Section 8\fR: System administration commands (usually for root)
|
|
.br
|
|
.B Section n\fR: Kernel routines
|
|
|
|
.SH Paragraphing
|
|
.\" ############
|
|
|
|
.B \.PP
|
|
Starts a new paragraph.
|
|
.br
|
|
A normal line-break can be achieved with
|
|
.B \.BR
|
|
|
|
\fB\.RS\fR and \fB\.RE\fR indent a paragraph.
|
|
|
|
You can center the following line with the
|
|
.B \.CR
|
|
macro
|
|
|
|
.SH Font Attributes
|
|
.\" ###############
|
|
|
|
.B \.I
|
|
makes text italic
|
|
(Note that italic may be represented as underlined instead)
|
|
|
|
.B \.B makes it bold
|
|
|
|
.SH File Locations
|
|
.\" ##############
|
|
|
|
The location of your manpages should be within your manpath
|
|
(man man-pages.7 for more information)
|
|
within subdirectories called \fBman1\fR, \fBman2\fR, etc.
|
|
where the number is the section number of the manpage.
|
|
|
|
After that, run \fBmandb\fR to find the new file
|
|
and add it to the database
|
|
for faster future access on slow systems
|