*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Linux man pages -> man (7)              



NAME    [Toc]    [Back]

       man - macros to format man pages

SYNOPSIS    [Toc]    [Back]

       groff -Tascii -man file ...

       groff -Tps -man file ...

       man [section] title

DESCRIPTION    [Toc]    [Back]

       This manual page explains the groff tmac.an macro package (often called
       the man macro package) and  related  conventions  for  creating	manual
       (man)  pages.   This  macro  package  should be used by developers when
       writing or porting man pages for Linux.	It is fairly  compatible  with
       other  versions	of this macro package, so porting man pages should not
       be a major problem (exceptions include the  NET-2  BSD  release,  which
       uses a totally different macro package called mdoc; see mdoc(7)).

       Note  that  NET-2  BSD  mdoc man pages can be used with groff simply by
       specifying the -mdoc option instead of  the  -man  option.   Using  the
       -mandoc	option is, however, recommended, since this will automatically
       detect which macro package is in use.

PREAMBLE    [Toc]    [Back]

       The first command in a man page (after comment lines) should be

	      .TH title section date source manual,


	      title	The title of the man page (e.g., MAN).

	      section	The section number the man page should	be  placed  in
			(e.g., 7).

	      date	The date of the last revision--remember to change this
			every time a change is made to	the  man  page,  since
			this is the most general way of doing version control.

	      source	The source of the command.

			For binaries, use something like: GNU, NET-2, SLS Dis-
			tribution, MCC Distribution.

			For  system  calls, use the version of the kernel that
			you are currently looking at: Linux 0.99.11.

			For library calls, use the  source  of	the  function:
			GNU, BSD 4.3, Linux DLL 4.4.1.

	      manual	The title of the manual (e.g., Linux Programmer's Man-

       Note that BSD mdoc-formatted pages begin with the Dd command,  not  the
       TH command.

       The manual sections are traditionally defined as follows:

	      1 Commands
			Those  commands  that can be executed by the user from
			within a shell.

	      2 System calls
			Those functions which must be performed by the kernel.

	      3 Library calls
			Most of the libc functions, such as qsort(3))

	      4 Special files
			Files found in /dev)

	      5 File formats and conventions
			The  format  for  /etc/passwd and other human-readable

	      6 Games

	      7 Macro packages and conventions
			A description of the standard file system layout, network
  protocols, ASCII and other character codes, this
			man page, and other things.

	      8 System management commands
			Commands like mount(8), many of which  only  root  can

	      9 Kernel routines
			This  is  an  obsolete	manual	section.   Once it was
			thought a good idea to document the Linux kernel here,
			but  in  fact very little has been documented, and the
			documentation that exists is outdated  already.  There
			are  better sources of information for kernel developers.

SECTIONS    [Toc]    [Back]

       Sections are started with .SH followed by the  heading  name.   If  the
       name  contains  spaces  and appears on the same line as .SH, then place
       the heading  in	double	quotes.   Traditional  or  suggested  headings
       traditional heading would apply, please use it; this  kind  of  consistency
  can  make  the  information easier to understand.  However, feel
       free to create your own headings if they make things easier  to	understand.
	The  only  required heading is NAME, which should be the first
       section and be followed on the next line by a one line  description  of
       the program:

	      .SH NAME
	      chess \- the game of chess

       It  is extremely important that this format is followed, and that there
       is a backslash before the single dash which follows the	command  name.
       This syntax is used by the makewhatis(8) or mandb(8) programs to create
       a database of short command descriptions for the  whatis(1)  and  apro-
       pos(1) commands.

       Some other traditional sections have the following contents:

       SYNOPSIS      briefly  describes  the  command or function's interface.
		     For commands, this shows the syntax of  the  command  and
		     its  arguments  (including options); boldface is used for
		     as-is text and italics are used to  indicate  replaceable
		     arguments.  Brackets  ([])  surround  optional arguments,
		     vertical bars (|) separate choices,  and  ellipses  (...)
		     can  be  repeated.   For functions, it shows any required
		     data declarations or #include directives, followed by the
		     function declaration.

       DESCRIPTION   gives  an	explanation  of what the command, function, or
		     format does.  Discuss how it  interacts  with  files  and
		     standard  input,  and what it produces on standard output
		     or standard error.   Omit	internals  and	implementation
		     details  unless  they're  critical  for understanding the
		     interface.  Describe the usual case; for  information  on
		     options  use  the OPTIONS section.  If there is some kind
		     of input grammar or complex set of subcommands,  consider
		     describing  them  in  a  separate USAGE section (and just
		     place an overview in the DESCRIPTION section).

       RETURN VALUE  gives a list of  the  values  the	library  routine  will
		     return  to the caller and the conditions that cause these
		     values to be returned.

       EXIT STATUS   lists the possible exit status values or  a  program  and
		     the conditions that cause these values to be returned.

       OPTIONS	     describes	the  options  accepted	by the program and how
		     they change its behavior.

       USAGE	     describes the grammar of any sublanguage this implements.

       FILES	     lists  the  files	the  program or function uses, such as
		     configuration files, startup files, and files the program
		     directly  operates  on.   Give the full pathname of these
		     files, and use the installation  process  to  modify  the
		     directory	part to match user preferences.  For many programs,
  the   default   installation   location   is   in
		     /usr/local,   so	your   base  manual  page  should  use
		     /usr/local as the base.

       ENVIRONMENT   lists all environment variables that affect your  program
		     or function and how they affect it.

       DIAGNOSTICS   gives  an	overview of the most common error messages and
		     how to cope with them.  You don't need to explain	system
		     error  messages  or  fatal signals that can appear during
		     execution of any program unless they're special  in  some
		     way to your program.

       SECURITY      discusses	security  issues and implications.  Warn about
		     configurations or environments that  should  be  avoided,
		     commands  that may have security implications, and so on,
		     especially if they aren't obvious.   Discussing  security
		     in  a separate section isn't necessary; if it's easier to
		     understand, place security information in the other  sections
  (such  as the DESCRIPTION or USAGE section).  However,
 please include security information somewhere!

       CONFORMING TO describes any standards or conventions this implements.

       NOTES	     provides miscellaneous notes.

       BUGS	     lists limitations, known defects or  inconveniences,  and
		     other questionable activities.

       AUTHOR	     lists  authors of the documentation or program so you can
		     mail in bug reports.

       SEE ALSO      lists related man pages in alphabetical  order,  possibly
		     followed  by  other  related pages or documents.  Conventionally
 this is the last section.

FONTS    [Toc]    [Back]

       Although there are many arbitrary conventions for man pages in the UNIX
       world,  the  existence  of  several  hundred  Linux-specific  man pages
       defines our font standards:

	      For functions, the arguments are always specified using italics,
	      even  in the SYNOPSIS section, where the rest of the function is
	      specified in bold:
	      int myfunction(int argc, char **argv);

	      Filenames are always in  italics	(e.g.,	/usr/include/stdio.h),
	      except in the SYNOPSIS section, where included files are in bold
	      (e.g., #include <stdio.h>).

	      Special macros, which are usually in upper  case,  are  in  bold
	      (e.g., MAXINT).

	      When  enumerating  a  list of error codes, the codes are in bold
	      (this list usually uses the .TP macro).

	      Any reference to another man page (or to the subject of the current
  man  page)	is  in	bold.  If the manual section number is
	      given, it is given in Roman (normal) font,  without  any	spaces
	      (e.g., man(7)).

       The commands to select the type face are:

       .B  Bold

       .BI Bold alternating with italics (especially useful for function specifications)

       .BR Bold alternating with Roman (especially  useful  for  referring  to
	   other manual pages)

       .I  Italics

       .IB Italics alternating with bold

       .IR Italics alternating with Roman

       .RB Roman alternating with bold

       .RI Roman alternating with italics

       .SB Small alternating with bold

       .SM Small (useful for acronyms)

       Traditionally,  each  command can have up to six arguments, but the GNU
       implementation removes this limitation (you might still want  to  limit
       yourself  to 6 arguments for portability's sake).  Arguments are delimited
 by spaces.	Double quotes can be used to specify an argument which
       contains  spaces.   All	of  the arguments will be printed next to each
       other without intervening spaces, so that the .BR command can  be  used
       to  specify  a word in bold followed by a mark of punctuation in Roman.
       If no arguments are given, the command is applied to the following line
       of text.


       Below  are  other relevant macros and predefined strings.  Unless noted
       otherwise, all macros cause a break (end the  current  line  of	text).
       Many of these macros set or use the "prevailing indent."  The "prevailing
 indent" value is set by any	macro  with  the  parameter  i	below;
       macros  may  omit i in which case the current prevailing indent will be
       used.  As a result, successive indented paragraphs  can	use  the  same
       indent without re-specifying the indent value.  A normal (non-indented)
       paragraph resets the prevailing indent value to its default value  (0.5
       inches).   By  default a given indent is measured in ens; try to ens or
       ems as units for indents, since these will automatically adjust to font
       size changes.  The other key macro definitions are:

   Normal Paragraphs    [Toc]    [Back]
       .LP	Same as .PP (begin a new paragraph).

       .P	Same as .PP (begin a new paragraph).

       .PP	Begin a new paragraph and reset prevailing indent.

   Relative Margin Indent    [Toc]    [Back]
       .RS i	Start  relative margin indent - moves the left margin i to the
		right (if i is omitted, the prevailing indent value is	used).
		A  new	prevailing  indent is set to 0.5 inches.  As a result,
		all following paragraph(s) will be indented until  the	corresponding

       .RE	End  relative margin indent and restores the previous value of
		the prevailing indent.

   Indented Paragraph Macros    [Toc]    [Back]
       .HP i	Begin paragraph with a hanging indent (the first line  of  the
		paragraph  is at the left margin of normal paragraphs, and the
		rest of the paragraph's lines are indented).

       .IP x i	Indented paragraph with optional hanging tag.  If the tag x is
		omitted,  the entire following paragraph is indented by i.  If
		the tag x is provided, it is hung at the  left	margin	before
		the following indented paragraph (this is just like .TP except
		the tag is included with the command instead of being  on  the
		following  line).   If the tag is too long, the text after the
		tag will be moved down to the next line (text will not be lost
		or  garbled).	For  bulleted  lists, use this macro with \(bu
		(bullet) or \(em (em dash) as the tag, and for numbered lists,
		use the number or letter followed by a period as the tag; this
		simplifies translation to other formats.

       .TP i	Begin paragraph with hanging tag.  The tag  is	given  on  the
		next  line, but its results are like those of the .IP command.

   Hypertext Link Macros    [Toc]    [Back]
       .UR u	Begins a hypertext link to the URI (URL) u; it will  end  with
		the  corresponding  UE	command.   When  generating  HTML this
		should translate into the HTML command <A HREF="u">.  There is
		an exception: if u is the special value ":", then no hypertext
		link of any kind will be generated until after the closing  UE
		(this  permits	disabling  hypertext  links  in  phrases  like
		LALR(1) when linking is  not  appropriate).   These  hypertext
		link  "macros"	are new, and many tools won't do anything with
		them, but since  many  tools  (including  troff)  will	simply
		ignore	undefined macros (or at worst insert their text) these
		are safe to insert.

       .UE	Ends the corresponding UR command; when generating  HTML  this
		should translate into </A>.

       .UN u	Creates  a  named hypertext location named u; do not include a
		corresponding UE command.  When generating  HTML  this	should
		translate  into the HTML command <A NAME="u" id="u">&nbsp;</A>
		(the &nbsp; is optional if support for Mosaic is unneeded).

   Miscellaneous Macros    [Toc]    [Back]
       .DT	Reset tabs to default tab values (every 0.5 inches); does  not
		cause a break.

       .IX ...	Inserts  index	information  (for  a  search system or printed
		index list).  Index information is not normally  displayed  in
		the  page  itself.   If  followed  by  a single parameter, the
		parameter is added as a standalone index term pointing to this
		location in the man page.  If it's two parameters, it's probably
 in Perl manpage format; the first parameter identifies the
		type of name (one of Name, Title, Header, Subsection, or Item)
		and the second parameter the name itself to be indexed.   Otherwise,
 it's in the long index format: each parameter gives an
		index term, subordinate index term, subsubordinate index term,
		and  so  on  until  terminated	by  an empty parameter, then a
		parameter with	the  name  of  the  program,  \em,  and  short
		description;  this  may be followed by another empty parameter
		and possibly by page control messages (e.g. PAGE  START).   An
		example  of  this  would  be  "programming  tools"  "make"  ""
		"\fLmake\fP \(em build programs".

       .PD d	Set  inter-paragraph  vertical	distance  to  d  (if  omitted,
		d=0.4v); does not cause a break.

       .SS t	Subheading  t  (like  .SH,  but used for a subsection inside a

   Predefined Strings    [Toc]    [Back]
       The man package has the following predefined strings:

       \*R    Registration Symbol: (R)

       \*S    Change to default font size

       \*(Tm  Trademark Symbol: tm

       \*(lq  Left angled doublequote: "

       \*(rq  Right angled doublequote: "

SAFE SUBSET    [Toc]    [Back]

       Although technically man is a troff macro package, in reality  a  large
       number  of  other tools process man page files that don't implement all
       of troff's abilities.  Thus, it's best to avoid some  of  troff's  more
       exotic  abilities  where  possible  to permit these other tools to work
       correctly.  Avoid using the various troff preprocessors (if  you  must,
       go  ahead and use tbl(1), but try to use the IP and TP commands instead
       for two-column tables).	Avoid using  computations;  most  other  tools
       can't  process them.  Use simple commands that are easy to translate to
       other formats.  The following troff macros  are	believed  to  be  safe
       (though	in many cases they will be ignored by translators): \", ., ad,
       bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps,
       so, sp, ti, tr.

       You may also use many troff escape sequences (those sequences beginning
       with \).  When you need to include the backslash  character  as	normal
       text, use \e.  Other sequences you may use, where x or xx are any characters
 and N is any digit, include: \', \`, \-, \., \", \%, \*x, \*(xx,
       \(xx,  \$N,  \nx,  \n(xx,  \fx,	and  \f(xx.   Avoid  using  the escape
       sequences for drawing graphics.

       Do not use the optional parameter for bp (break page).  Use only  positive
  values  for  sp (vertical space).	Don't define a macro (de) with
       the same name as a macro in this or the mdoc macro package with a  different
  meaning;  it's  likely that such redefinitions will be ignored.
       Every positive indent (in) should be paired with  a  matching  negative
       indent  (although  you  should  be using the RS and RE macros instead).
       The condition test (if,ie) should only have 't' or 'n'  as  the	condition.
  Only translations (tr) that can be ignored should be used.  Font
       changes (ft and the \f escape sequence) should only have the values  1,
       2,  3,  4,  R,  I, B, P, or CW (the ft command may also have no parameters).

       If you use capabilities beyond these, check the	results  carefully  on
       several tools.  Once you've confirmed that the additional capability is
       safe, let the maintainer of this document know about the  safe  command
       or sequence that should be added to this list.

NOTES    [Toc]    [Back]

       By all means include full URLs (or URIs) in the text itself; some tools
       such as man2html(1) can automatically turn them into  hypertext	links.
       You can also use the new UR macro to identify links to related information.
  If you include URLs, use the full URL (e.g., <http://www.kernel-
       notes.org>) to ensure that tools can automatically find the URLs.

       Tools processing these files should open the file and examine the first
       non-whitespace character. A period (.)  or  single  quote  (')  at  the
       beginning of a line indicates a troff-based file (such as man or mdoc).
       A left angle bracket (<) indicates an SGML/XML-based file (such as HTML
       or Docbook). Anything else suggests simple ASCII text (e.g., a "catman"

       Many man pages begin with '\" followed by a space and a list of characters,
 indicating how the page is to be preprocessed.  For portability's
       sake to non-troff translators we recommend that you  avoid  using  anything
 other than tbl(1), and Linux can detect that automatically.  However,
 you might want to include this information so your man  page  can
       be  handled  by other (less capable) systems.  Here are the definitions
       of the preprocessors invoked by these characters:

       e  eqn(1)

       g  grap(1)

       p  pic(1)

       r  refer(1)

       t  tbl(1)

       v  vgrind(1)

FILES    [Toc]    [Back]


BUGS    [Toc]    [Back]

       Most of the macros describe formatting (e.g., font  type  and  spacing)
       instead	of marking semantic content (e.g., this text is a reference to
       another page), compared to formats like mdoc and DocBook (even HTML has
       more  semantic  markings).   This situation makes it harder to vary the
       man format for different media, to make the formatting consistent for a
       given media, and to automatically insert cross-references.  By sticking
       to the safe subset described above, it should  be  easier  to  automate
       transitioning to a different reference page format in the future.

       The Sun macro TX is not implemented.

AUTHORS    [Toc]    [Back]

       -- James  Clark	(jjc@jclark.com) wrote the implementation of the macro

       -- Rickard E. Faith (faith@cs.unc.edu) wrote  the  initial  version  of
	  this manual page.

       -- Jens	Schweikhardt  (schweikh@noc.fdn.de)  wrote  the Linux Man-Page
	  Mini-HOWTO (which influenced this manual page).

       -- David A. Wheeler (dwheeler@ida.org)  heavily	modified  this	manual
	  page, such as adding detailed information on sections and macros.

SEE ALSO    [Toc]    [Back]

       apropos(1),  groff(1),  man(1),	man2html(1), mdoc(7), mdoc.samples(7),

Linux				  1999-06-16				MAN(7)
[ Back ]
 Similar pages
Name OS Title
groff_markup NetBSD groff macros for authoring web pages
groff_www FreeBSD groff macros for authoring web pages
man OpenBSD groff `an' macros to support generation of man pages
groff_man OpenBSD groff `an' macros to support generation of man pages
groff_man FreeBSD groff `man' macros to support generation of man pages
man FreeBSD groff `man' macros to support generation of man pages
groff_man NetBSD groff `man' macros to support generation of man pages
man FreeBSD format and display the on-line manual pages
iconbooktocatalog IRIX converts old iconbook pages to IRIX 6.5 format
bdftopcf Tru64 convert X font from Bitmap Distribution Format to Portable Compiled Format
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service