From Fedora Project Wiki

Revision as of 07:23, 25 September 2009 by Varekova (talk | contribs) (Created page with '== 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 === Automat...')
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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 man2html contains this tool


Link to another man-page

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

.so man1/relevant_man_page.1


Man-page scheme

bold parts are mandatory

.\" Copyright
.TH man_page_name section date "Linux" man_pages_type
.SH NAME
name \- one line description
.SH SYNOPSIS               -- only where it is relevant
.B syntax                  -- only where it is relevant
.SH DESCRIPTION
detail description ....
.SH "RETURN VALUE"         -- only where it is relevant
detail description         -- only where it is relevant
.SH ERRORS                 -- only where it is relevant
detail description         -- only where it is relevant
.SH NOTES                  -- only where it is relevant
detail description         -- only where it is relevant
.SH "SEE ALSO"
list of relevant man pages
.SH AUTHOR


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