Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MAN(7)			   Linux Programmer's Manual			MAN(7)

NAME
       man - macros to format man pages

SYNOPSIS
       groff -Tascii -man file ...

       groff -Tps -man file ...

       man [section] title

DESCRIPTION
       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
       The first command in a man page (after comment lines) should be

	      .TH title	section	date source manual,

       where:

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

       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, net-
			work  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 documented, and the
			documentation that exists is outdated  already.	 There
			are  better sources of information for kernel develop-
			ers.

SECTIONS
       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  in-
       clude:  NAME,  SYNOPSIS,	 DESCRIPTION, RETURN VALUE, EXIT STATUS, ERROR
       HANDLING, ERRORS, OPTIONS, USAGE, EXAMPLES, FILES,  ENVIRONMENT,	 DIAG-
       NOSTICS,	 SECURITY,  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 understand.  However,
       feel free to create your	own headings if	they make things easier	to un-
       derstand.  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) program to create a database
       of short	command	descriptions for the  whatis(1)	 and  apropos(1)  com-
       mands.

       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 de-
		     tails  unless  they're critical for understanding the in-
		     terface.  Describe	the usual case;	for information	on op-
		     tions  use	the OPTIONS section.  If there is some kind of
		     input grammar or complex set of subcommands, consider de-
		     scribing 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  re-
		     turn  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.

       EXAMPLES	     provides one or more examples describing how  this	 func-
		     tion, 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 di-
		     rectory  part  to	match user preferences.	 For many pro-
		     grams, the	default	installation location is  in  /usr/lo-
		     cal,  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  sec-
		     tions  (such  as the DESCRIPTION or USAGE section).  How-
		     ever, 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.  Conven-
		     tionally this is the last section.

FONTS
       Although	there are many arbitrary conventions for man pages in the UNIX
       world,  the  existence  of several hundred Linux-specific man pages de-
       fines 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 cur-
	      rent  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 spec-
	   ifications)

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

OTHER MACROS AND STRINGS
       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 "prevail-
       ing 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 in-
       dent  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	corre-
		sponding .RE.

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

   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 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
       .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 ig-
		nore 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
       .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 break.

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

SAFE SUBSET
       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 char-
       acters and N is any digit, include: \', \`, \-, \., \", \%, \*x,	\*(xx,
       \(xx,  \$N,  \nx,  \n(xx,  \fx,	and \f(xx.  Avoid using	the escape se-
       quences for drawing graphics.

       Do not use the optional parameter for bp	(break page).  Use only	 posi-
       tive  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  dif-
       ferent  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	condi-
       tion.  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 parame-
       ters).

       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
       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 informa-
       tion.  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  be-
       ginning	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"
       result).

       Many man	pages begin with '\" followed by a space and a list of charac-
       ters, indicating	how the	page is	to be preprocessed.  For portability's
       sake to non-troff translators we	recommend that you  avoid  using  any-
       thing other than	tbl(1),	and Linux can detect that automatically.  How-
       ever, 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
       /usr/share/groff/[*/]tmac/tmac.an
       /usr/man/whatis

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

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

Linux				  1999-06-16				MAN(7)

NAME | SYNOPSIS | DESCRIPTION | PREAMBLE | SECTIONS | FONTS | OTHER MACROS AND STRINGS | SAFE SUBSET | NOTES | FILES | BUGS | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=man&sektion=7&manpath=Red+Hat+9>

home | help