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/.