.profile/templates/manpage.5

114 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