User:Varekova/man-pages

Manual how to create man-page

the list of man-pages section is on man.1 man page, most probable are:

1. User Commands
5. File Formats and Conventions

Automatic generation of man pages from --help to man-pages format

package help2man contains this tool

Link to another man-page

if the man-page describing the binary or config file already exists there could be used only link man page:

.so man1/relevant_man_page.1

the reason not to do "ordinary" simlink using ls is - man can go through this links and show the information from which file this man-page is.

Man-page scheme

NAME, SYNOPSIS, DESCRIPTION and SEE ALSO parts are the most common and usually are in man-pages

.\" Copyright ..
.TH man_page_name section date "Linux" man_pages_type
.SH NAME
name \- one line description
.SH SYNOPSIS               
.B syntax                  
.SH DESCRIPTION
detail description of the functionality ....
.SH "EXIT STATUS"          -- usually in sections 1, 8
possible exit status
.SH "RETURN VALUE"         -- usually in sections 2, 3
detail description
.SH ERRORS                 -- usually in sections 2, 3
detail description
.SH NOTES                  -- only where it is relevant
detail description
.SH "SEE ALSO"
list of relevant man pages
.SH AUTHOR                 -- copyright should be enough so not needed

Useful tags

• .\" -- comment
• .B -- text on the whole line is bold (useful for keywords, command name and options)
• .I -- text on the whole line is italics (useful for SYNOPSIS part)
• .BR -- the odd words are bold, even are normal (used in SEE ALSO part - bold are man-pages name, normal ale section numbers of them)
• .BI -- the odd words are bold, even are italics (used in SYNOPSIS part - italics are types, bold are variable names)
• .BR, .BI, ... -- analogy of ^
• .sp -- skip one line vertically
• .br -- line break (used in SEE ALSO to separate the man-pages name, .. )
• the list of all tags is groff.7 man page

Example

good pages should be all in man-pages package

.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) 
.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk 
.\"     <mtk.manpages@gmail.com> 
.\" ....
.TH ATAN 3  2008-12-02 "" "Linux Programmer's Manual"
.SH NAME
atan, atanf, atanl \- arc tangent function
.SH SYNOPSIS
.nf 
.B #include <math.h> 
.sp 
.BI "double atan(double " x ); 
.br 
.BI "float atanf(float " x ); 
.br 
.BI "long double atanl( long double " x ); 
.sp 
.fi
...
.SH DESCRIPTION
The
.BR atan ()
function calculates the principal value of the arc tangent of \fIx\fP;
that is the value whose tangent is \fIx\fP.
.SH "RETURN VALUE"
On success, these functions return the principal value of the arc tangent of
.IR x
in radians; the return value is in the range [\-pi/2,\ pi/2].

If
.I x
is a NaN, a NaN is returned.
..
.SH ERRORS
No errors occur.
.SH "SEE ALSO"
.BR acos (3),
.BR asin (3), 
..
.SH COLOPHON
This page is part of release 3.22 of the Linux
.I man-pages
project.
A description of the project,
and information about reporting bugs,
can be found at
http://www.kernel.org/doc/man-pages/.