diff options
Diffstat (limited to 'Documentation/howto-man-page.txt')
| -rw-r--r-- | Documentation/howto-man-page.txt | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/Documentation/howto-man-page.txt b/Documentation/howto-man-page.txt new file mode 100644 index 0000000..5ca4af0 --- /dev/null +++ b/Documentation/howto-man-page.txt @@ -0,0 +1,161 @@ +.\" This is an util-linux manual page example in troff format. +.\" +.\" .TH macro is expecting following arguments: +.\" title section date footer header +.\" The title is usually command name. +.\" The section must match with file name extension. +.\" The date tells month and year when last update happen. +.\" The footer is fixed to "util-linux". +.\" The header is textual string of section +.\" 1 "User Commands" +.\" 2 "System calls" +.\" 3 "Programmer's Manual" +.\" 4 "Special Files" +.\" 5 "File Formats" +.\" 6 "Games" +.\" 7 "Miscellanea" +.\" 8 "System Administration" +.\" +.\" Please read `man 7 groff_man' howto use various macros. +.\" +.TH EXAMPLE "1" "August 2011" "util-linux" "User Commands" +.SH NAME +example \- an util-linux man page howto +.SH SYNOPSIS +.B example +[options] +.I argument +.SH DESCRIPTION +All manual pages need some sort of description. Write such here. +.SH OPTIONS +.TP +\fB\-n\fR, \fB\-\-no\-argument\fR +This option does not use argument. +.TP +\fB\-o\fR, \fB\-\-optional\fR [\fIargument\fR] +Tell in description an +.I argument +is optional, and what happens when is or is not given. Notice that +.I argument +is not abbreviated, like in usage function. Assuming usage function would +define argument to be +.IR num , +the manual page should say +.IR number . +.TP +\fB\-r\fR, \fB\-\-required\fR \fIargument\fR +Tell in description option +.I argument +is required. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information and exit. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display help and exit. +.SH NOTES +Tell details what users might need to know. For example kernel feature or +version requirements. +.PP +The man page groff input lines should not exceed 80 characters length. +.PP +Do not leave empty lines to groff input. If you need break or paragraph use +appropriate groff macros. See +.BR groff_man (7) +how to use man page macros. +.PP +Use of +.I italic +which is underlined in terminal, and +.B bold +are not strictly defined. As some sort of convention +.I arguments +use italic, and the +.B other highlights +are bold. +.\" +.\" The manual page comments are undervalued way of adding clarifications +.\" quite not belong to the manual, questions, TODO items etc. Feel free +.\" to use them. +.\" +.PP +When in the source a new sentence begins somewhere midline, it should use a +double space before its initial letter. This is done because groff uses double +spaces last sentence ends to end of line, and next begins from new line. +Unless double spaces are used in middle of of line the spacing style is +inconsistent. +.SH ENVIRONMENT +Tell which environment variables affect, and how, to execution of the command. +.TP +.B EXAMPLE_PATH +Configuration file path. Notice that a well-known environment variables such as +.B HOME +does not need explanation. +.SH FILES +Tell which file(s) command uses. +.TP +.B $EXAMPLE_PATH +.TQ +.B $HOME/.example.conf +.TQ +.B /etc/example.conf +What are these files, which order and will the evaluation end or continue if a +file is found. In case the explanation is not simple write separated Special +Files manual page that tells about syntax, meaning of key-value settings etc. +The file manual page needs to be referred in +.B SEE ALSO +section. +.TP +.B /var/log/example.log +Another file. +.SH EXAMPLES +Write typical and/or clever use examples here. The bellow examples are stupid, +and you should never write them to real man page. +.TP +.B example -h +Output help screen. +.TP +.B example -V +Output version information. +.SH "EXIT STATUS" +This section can be removed if command has only two return values, +.B 0 +for success and +.B 1 +for failure. Use of +.B sysexits.h +return values must be mentioned, but does not need to be explained. +.PP +.RS +.PD 0 +.TP +.B 0 +success +.TP +.B 1 +failure +.TP +.B 2 +tell why this could happen +.TP +.B 3 +etc +.PD +.RE +.SH AUTHORS +.MT rjh@\:example.org +Random J. Hacker +.ME +.br +.MT fred@\:example.com +Fred Foobar +.ME +.SH "SEE ALSO" +.BR groff_man (7), +.BR foo (1), +.BR bar (8) +.SH AVAILABILITY +The example command is part of the util-linux package and is available from +.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ +Linux Kernel Archive +.UE . |