Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for man (redhat section 7)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

MAN(7)				    Linux Programmer's Manual				   MAN(7)

       man - macros to format man pages

       groff -Tascii -man file ...

       groff -Tps -man file ...

       man [section] title

       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.

       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 Distribution, MCC  Dis-

			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 Manual).

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

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

	      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 docu-
			mented, and the documentation that exists is outdated already. There  are
			better sources of information for kernel developers.

       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	include:  NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, EXIT STATUS,
       RITY, CONFORMING TO, NOTES, BUGS, AUTHOR, and SEE ALSO.	Where a traditional heading would
       apply, please use it; this kind of consistency can make the information easier  to  under-
       stand.	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  make-
       whatis(8) program to create a database of short command descriptions for the whatis(1) and
       apropos(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); bold-
		     face is used for as-is text and italics are  used	to  indicate  replaceable
		     arguments. Brackets ([]) surround optional arguments, vertical bars (|) sep-
		     arate choices, and ellipses (...) can be repeated.  For functions, it  shows
		     any required data declarations or #include directives, followed by the func-
		     tion 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 behav-

       USAGE	     describes the grammar of any sublanguage this implements.

       EXAMPLES      provides one or more examples describing how this function, file or  command
		     is used.

       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 impli-
		     cations, 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

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

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

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

	      For functions, the arguments are always specified using italics, even in the SYNOP-
	      SIS 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  SYNOP-
	      SIS 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 porta-
       bility'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
       .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
       .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.

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

   Indented Paragraph Macros
       .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

       .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 fol-
		lowing 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
       .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 hyper-
		text 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 appro-
		priate).  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

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

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

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

   Predefined Strings
       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: "

       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  com-
       mands  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 docu-
       ment know about the safe command or sequence that should be added to this list.

       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.kernelnotes.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 recom-
       mend  that you avoid using anything other than tbl(1), and Linux can detect that automati-
       cally.  However, you might want to include this information so your man page can  be  han-
       dled  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)


       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.

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

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

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

Linux					    1999-06-16					   MAN(7)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 04:47 PM.