EditPageHistoryDiffInfoLikePages

Annotated edit history of groff_mdoc(7) version 2 showing authors affecting page license. View with all changes included.

Rev	Author	#	Line
2	AristotlePagaltzis	1	!!!NAME
1	perry	2
2	AristotlePagaltzis	3	groff_mdoc - reference for groff's mdoc implementation
1	perry	4
2	AristotlePagaltzis	5	!!!SYNOPSIS
1	perry	6
		7	groff -mdoc file ...
		8
2	AristotlePagaltzis	9	!!!DESCRIPTION
1	perry	10
2	AristotlePagaltzis	11	A complete reference for writing UNIX manual pages with the -mdoc macro package; a ''content''-based and ''domain''-based formatting package for GNU troff(1). Its predecessor, the !-man(7) package, addressed page layout leaving the manipulation of fonts and other typesetting details to the individual author. In -mdoc, page layout macros make up the ''page structure domain'' which consists of macros for titles, section headers, displays and lists - essentially items which affect the physical position of text on a formatted page. In addition to the page structure domain, there are two more domains, the ''manual'' domain and the ''general'' text domain. The general text domain is defined as macros which perform tasks such as quoting or emphasizing pieces of text. The manual domain is defined as macros that are a subset of the day to day informal language used to describe commands, routines and related UNIX files. Macros in the manual domain handle command names, command line arguments and options, function names, function parameters, pathnames, variables, cross references to other manual pages, and so on. These domain items have value for both the author and the future user of the manual page. It is hoped the consistency gained across the manual set will provide easier translation to future documentation tools.
1	perry	12
		13	Throughout the UNIX manual pages, a manual entry is simply referred to as a man page, regardless of actual length and without sexist intention.
		14
2	AristotlePagaltzis	15	!!!GETTING STARTED
1	perry	16
2	AristotlePagaltzis	17	The material presented in the remainder of this document is outlined as follows:
1	perry	18
2	AristotlePagaltzis	19	# TROFF IDIOSYNCRASIES
		20	** Macro Usage
		21	** Passing Space Characters in an Argument
		22	** Trailing Blank Space Characters
		23	** Escaping Special Characters
		24	** Other Possible Pitfalls
		25	# A MANUAL PAGE TEMPLATE
		26	# CONVENTIONS
		27	# TITLE MACROS
		28	# INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS
		29	** What's in a Name...
		30	** General Syntax
		31	# MANUAL DOMAIN
		32	** Addresses
		33	** Author Name
		34	** Arguments
		35	** Configuration Declarations (Section Four Only)
		36	** Command Modifiers
		37	** Defined Variables
		38	** Errno's
		39	** Environment Variables
		40	** Flags
		41	** Function Declarations
		42	** Function Types
		43	** Functions (Library Routines)
		44	** Function Arguments
		45	** Return Values
		46	** Interactive Commands
		47	** Library Names
		48	** Literals
		49	** Names
		50	** Options
		51	** Pathnames
		52	** Standards
		53	** Variable Types
		54	** Variables
		55	** Manual Page Cross References
		56	# GENERAL TEXT DOMAIN
		57	** ATPAGE STRUCTURE DOMAIN
		58	** Section Headers
		59	** Subsection Headers
		60	** Paragraphs and Line Spacing
		61	** Keeps
		62	** Examples and Displays
		63	** Lists and Columns
		64	# MISCELLANEOUS MACROS
		65	# PREDEFINED STRINGS
		66	# DIAGNOSTICS
		67	# FORMATTING WITH GROFF, TROFF, AND NROFF
		68	# FILES
		69	# SEE ALSO
		70	# BUGS
1	perry	71
		72
2	AristotlePagaltzis	73	__TROFF IDIOSYNCRASIES__
1	perry	74
2	AristotlePagaltzis	75
		76	The -mdoc package attempts to simplify the process of writing a man page. Theoretically, one should not have to learn the dirty details of GNU troff(1) to use -mdoc; however, there are a few limitations which are unavoidable and best gotten out of the way. And, too, be forewarned, this package is ''not'' fast.
1	perry	77
		78
		79	__Macro Usage__
		80
		81
2	AristotlePagaltzis	82	As in GNU troff(1), a macro is called by placing a . (dot character) at the beginning of a line followed by the two-character (or three-character) name for the macro. There can be space characters between the dot and the macro name (but ''no'' tabs). Arguments may follow the macro separated by spaces (again, no tabs). It is the dot character at the beginning of the line which causes GNU troff(1) to interpret the next two (or more) characters as a macro name. A single starting dot followed by nothing is ignored. To place a . (dot character) at the beginning of an input line in some context other than a macro invocation, precede the . (dot) with the escape sequence. The translates literally to a zero-width space, and is never displayed in the output.
1	perry	83
2	AristotlePagaltzis	84	In general, GNU troff(1) macros accept an unlimited number of arguments (contrary to other versions of troff which can't handle more than nine arguments). In limited cases, arguments may be continued or extended on the next line (See __Extended Arguments__ below). Almost all macros handle quoted arguments (see __Passing Space Characters in an Argument__ below).
1	perry	85
2	AristotlePagaltzis	86	Most of the -mdoc general text domain and manual domain macros are special in that their argument lists are ''parsed'' for callable macro names. This means an argument on the argument list which matches a general text or manual domain macro name and is determined to be callable will be executed or called when it is processed. In this case the argument, although the name of a macro, is not preceded by a . (dot). It is in this manner that many macros are nested; for example the option macro, .Op, may ''call'' the flag and argument macros, Fl and Ar, to specify an optional flag with an argument:
		87	[[-s bytes]
		88	is produced by .Op Fl s Ar bytes
1	perry	89
2	AristotlePagaltzis	90	To prevent a string from being interpreted as a macro name, precede the string with the escape sequence:
		91	[[Fl s Ar bytes]
1	perry	92	is produced by .Op
		93
2	AristotlePagaltzis	94	Here the strings Fl and Ar are not interpreted as macros. Macros whose argument lists are parsed for callable arguments are referred to as ''parsed'' and macros which may be called from an argument list are referred to as ''callable'' throughout this document. This is a technical ''faux pas'' as almost all of the macros in -mdoc are parsed, but as it was cumbersome to constantly refer to macros as being callable and being able to call other macros, the term parsed has been used.
1	perry	95
		96	__Passing Space Characters in an Argument__
		97
2	AristotlePagaltzis	98	Sometimes it is desirable to give as an argument a string containing one or more blank space characters.This may be necessary to specify arguments to macros which expect particular arrangement of items in the argument list. Additionally, it makes -mdoc working faster. For example, the function macro .Fn expects the first argument to be the name of a function and any remaining arguments to be function parameters. As ANSI C stipulates the declaration of function parameters in the parenthesized parameter list, each parameter is guaranteed to be at minimum a two word string. For example, int foo.
1	perry	99
2	AristotlePagaltzis	100	There are two possible ways to pass an argument which contains an embedded space. One way of passing a string containing blank spaces is to use the hard or unpaddable space character \ , that is, a blank space preceded by the escape character \. This method may be used with any macro but has the side effect of interfering with the adjustment of text over the length of a line. Troff sees the hard space as if it were any other printable character and cannot split the string into blank or newline separated pieces as one would expect. This method is useful for strings which are not expected to overlap a line boundary. An alternative is to use ~, a paddable (i.e. stretchable), unbreakable space (this is a GNU troff(1) extension). The second method is to enclose the string with double quotes.
1	perry	101
		102	For example:
		103
2	AristotlePagaltzis	104	fetch(char str)
1	perry	105	is created by .Fn fetch char\ str
		106
2	AristotlePagaltzis	107	fetch(char str)
		108	can also be created by .Fn fetch char str
1	perry	109
2	AristotlePagaltzis	110	If the \ before the space resp. the double quotes were omitted, .Fn would see three arguments, and the result would be:
1	perry	111
2	AristotlePagaltzis	112	fetch(char, str)
1	perry	113
		114	__Trailing Blank Space Characters__
		115
2	AristotlePagaltzis	116	Troff can be confused by blank space characters at the end of a line. It is a wise preventive measure to globally remove all blank spaces from blank-space end-of-line character sequences. Should the need arise to force a blank character at the end of a line, it may be forced with an unpaddable space and the escape character. For example, string\%%%.
1	perry	117
		118	__Escaping Special Characters__
		119
2	AristotlePagaltzis	120	Special characters like the newline character n are handled by replacing the \ with e (e.g. en) to preserve the backslash.
1	perry	121
		122	__Other Possible Pitfalls__
		123
2	AristotlePagaltzis	124	A warning is emitted when an empty input line is found outside of displays (see below). Use .sp instead. (Well, it is even better to use -mdoc macros to avoid the usage of low-level commands.)
1	perry	125
2	AristotlePagaltzis	126	Leading spaces will cause a break and are output directly. Avoid this behaviour if possible. Similarly, do not use more than one space character between words in an ordinary text line; contrary to other text formatters, they are ''not'' replaced with a single space.
1	perry	127
2	AristotlePagaltzis	128	You can't pass directly as an argument. Use [[q] (or q) instead.
1	perry	129
2	AristotlePagaltzis	130	By default, troff(1) inserts two space characters after a punctuation mark closing a sentence; characters like) or ' are treated transparently, not influencing the sentence-ending behaviour. To change this, insert before or after the dot:
1	perry	131
2	AristotlePagaltzis	132	The
		133	.Ql .
		134	character.
		135	.Pp
		136	The
		137	.Ql
1	perry	138
		139	gives
		140
2	AristotlePagaltzis	141	The . character
		142	The . character.
		143	test. test
		144	test. test
1	perry	145
2	AristotlePagaltzis	146	As can be seen in the first and third line, -mdoc handles punctuation characters specially in macro arguments. This will be explained in section __General Syntax__ below. In the same way, you have to protect trailing full stops of abbreviations with a trailing zero-width space:
1	perry	147
2	AristotlePagaltzis	148	e.g..
1	perry	149
2	AristotlePagaltzis	150	A comment in the source file of a man page can be either started with . on a single line, after some input, or # anywhere (the latter is a GNU troff(1) extension); the rest of such a line is ignored.
1	perry	151
2	AristotlePagaltzis	152	!!!A MANUAL PAGE TEMPLATE
1	perry	153
2	AristotlePagaltzis	154	The body of a man page is easily constructed from a basic template:
1	perry	155
		156	.
		157	The first items in the template are the macros .Dd, .Os, and .Dt; the document date, the operating system the man page or subject source is developed or modified for, and the man page title (in ''upper case'') along with the section of the manual the page belongs in. These macros identify the page and are discussed below in __TITLE MACROS__.
		158
2	AristotlePagaltzis	159	The remaining items in the template are section headers (.Sh); of which __NAME__, __SYNOPSIS__, and __DESCRIPTION__ are mandatory. The headers are discussed in __PAGE STRUCTURE DOMAIN__, after presentation of __MANUAL DOMAIN__. Several content macros are used to demonstrate page layout macros; reading about content macros before page layout macros is recommended.
1	perry	160
2	AristotlePagaltzis	161	!!!CONVENTIONS
1	perry	162
2	AristotlePagaltzis	163	In the description of all macros below, optional arguments are put into brackets. An ellipsis (...) represents zero or more additional arguments. Alternative values for a parameter are separated with |. If there are alternative values for a mandatory parameter, braces are used (together with |) to enclose the value set. Meta-variables are specified within angles.
1	perry	164
		165	Example:
		166	.Xx
2	AristotlePagaltzis	167	foo
		168	{bar1 | bar2}
		169	[[-test1 [[-test2 | -test3]]
		170	...
1	perry	171
		172	Except stated explicitly, all macros are parsed and callable.
		173
2	AristotlePagaltzis	174	Most macros have a default width value which can be used to specify a label width (-width) or offset (-offset) for the .Bl and .Bd macros. It is recommended not to use this rather obscure feature to avoid dependencies on local modifications of the -mdoc package.
1	perry	175
2	AristotlePagaltzis	176	!!!TITLE MACROS
1	perry	177
2	AristotlePagaltzis	178	The title macros are part of the page structure domain but are presented first and separately for someone who wishes to start writing a man page yesterday. Three header macros designate the document title or manual page title, the operating system, and the date of authorship. These macros are called once at the very beginning of the document and are used to construct headers and footers only.
1	perry	179
		180	.Dt
2	AristotlePagaltzis	181	[[document title]
		182	[[section number]
		183	[[volume]
1	perry	184
2	AristotlePagaltzis	185	The document title is the subject of the man page and must be in CAPITALS due to troff limitations. If omitted, UNTITLED is used. The section number may be a number in the range 1, ..., 9 or unass, draft, or paper. If it is specified, and no volume name is given, a default volume name is used.
1	perry	186
		187	Under BSD , the following sections are defined:
		188
2	AristotlePagaltzis	189	# System General Commands Manual
		190	# System Calls Manual
		191	# System Library Functions Manual
		192	# System Kernel Interfaces Manual
		193	# System File Formats Manual
		194	# System Games Manual
		195	# System Miscellaneous Information Manual
		196	# System Manager's Manual
		197	# System Kernel Developer's Manual
1	perry	198
2	AristotlePagaltzis	199	A volume name may be arbitrary or one of the following:
1	perry	200
2	AristotlePagaltzis	201	; US : System User's Supplementary Documents
		202	; PS : System Programmer's Supplementary Documents
		203	; AM : System Ancestral Manual Documents
		204	; SM : System Manager's Manual
		205	; UR : System Reference Manual
		206	; PR : System Programmer's Manual
		207	; K : System Kernel Manual
		208	; IN : System Manual Master Index
		209	; LOCA : System Local Manual
		210	; CON : System Contributed Software Manual
1	perry	211
2	AristotlePagaltzis	212	For compatibility, MMI can be used for IND, and LOC for LOCAL. Values from the previous table will specify a new volume name. If the third parameter is a keyword designating a computer architecture, its value is appended to the volume name as specified by the second parameter. By default, the following architecture keywords are defined:
1	perry	213
2	AristotlePagaltzis	214	alpha, amiga, arc, arm26, arm32, atari, bebox, cobalt, evbsh3, hp300, hpcmips, i386, luna68k, m68k, mac68k, macppc, mips, mmeye, mvme68k, news68k, newsmips, next68k, ofppc, pc532, pmax, powerpc, prep, sgimips, sh3, sparc, sparc64, sun3, tahoe, vax, x68k
1	perry	215
2	AristotlePagaltzis	216	In the following examples, the left (which is identical to the right) and the middle part of the manual page header strings are shown.
1	perry	217
2	AristotlePagaltzis	218	FOO(7) System Reference Manual
		219	.Dt FOO 2 mac68k
1	perry	220
2	AristotlePagaltzis	221	FOO(2) System Programmer's Manual (mac68k Architecture)
		222	.Dt FOO barFOO bar
1	perry	223
2	AristotlePagaltzis	224	''Ed: the above examples appear to have been copied to the wiki brokenly.''
1	perry	225
2	AristotlePagaltzis	226	Local, OS-specific additions might be found in the file mdoc.local; look for strings named volume-ds-XXX (for the former type) and volume-as-XXX (for the latter type); XXX then denotes the keyword to be used with the .Dt macro.
1	perry	227
2	AristotlePagaltzis	228	This macro is neither callable nor parsed.
1	perry	229
		230	.Os
		231	[[operating system]
		232	[[release]
		233
2	AristotlePagaltzis	234	If the first parameter is empty, the default BSD is used. This may be overridden in the local configuration file, mdoc.local. In general, the name of the operating system should be the common acronym, e.g. BSD or ATT . The release should be the standard release nomenclature for the system specified. In the following table, the possible second arguments for some predefined operating systems are listed. Similar to .Dt, local additions might be defined in mdoc.local; look for strings named operating-system-XXX-YYY, where XXX is the acronym for the operating system and YYY the release ID.
1	perry	235
		236	ATT
		237
2	AristotlePagaltzis	238	7th, 7, III, 3, V, V.2, V.3, V.4BSD3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r,4.3R, 4.4NetBSD0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1,1.2, 1.2a, 1.2b, 1.2c, 1.2d, 1.2e, 1.3,1.3a, 1.4, 1.5FreeBSD1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5,2.1, 2.1.5, 2.1.6, 2.1.7, 2.2, 2.2.1,2.2.2, 2.2.5, 2.2.6, 2.2.7, 2.2.8, 3.0,3.1, 3.2, 3.3, 3.4, 3.5, 4.0, 4.1, 4.2,5.0
1	perry	239
2	AristotlePagaltzis	240	For ATT , an unknown second parameter will be replaced with the string UNIX ; for the other predefined acronyms it will be ignored and a warning message emitted. Unrecognized arguments are displayed as given in the page footer. For instance, a typical footer might be:
1	perry	241
2	AristotlePagaltzis	242	.Os BSD 4.3
1	perry	243
2	AristotlePagaltzis	244	giving 4.3 Berkeley Distribution, or for a locally produced set
1	perry	245
2	AristotlePagaltzis	246	.Os CS Department
1	perry	247
		248	which will produce CS Department.
		249
2	AristotlePagaltzis	250	If the .Os macro is not present, the bottom left corner of the manual page will be ugly.
1	perry	251
2	AristotlePagaltzis	252	This macro is neither callable nor parsed.
1	perry	253
		254	.Dd
2	AristotlePagaltzis	255	[[
		256	month
		257	day,
		258	year
		259	]
1	perry	260
2	AristotlePagaltzis	261	If Dd has no arguments, Epoch is used for the date string. If it has exactly three arguments, they are concatenated, separated with unbreakable space:
1	perry	262
		263	.Dd January 25, 2001
		264
2	AristotlePagaltzis	265	Otherwise, the current date is used, ignoring the parameters.
1	perry	266
		267	This macro is neither callable nor parsed.
		268
2	AristotlePagaltzis	269	__INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS__
1	perry	270
		271	__What's in a Name__...
		272
2	AristotlePagaltzis	273	The manual domain macro names are derived from the day to day informal language used to describe commands, subroutines and related files. Slightly different variations of this language are used to describe the three different aspects of writing a man page. First, there is the description of -mdoc macro request usage. Second is the description of a UNIX command ''with'' -mdoc macros, and third, the description of a command to a user in the verbal sense; that is, discussion of a command in the text of a man page.
1	perry	274
2	AristotlePagaltzis	275	In the first case, troff(1) macros are themselves a type of command; the general syntax for a troff command is:
1	perry	276
		277	.Xx argument1 argument2 ...
		278
2	AristotlePagaltzis	279	.Xx is a macro command or request, and anything following it are arguments to be processed. In the second case, the description of a UNIX command using the content macros is a bit more involved; a typical __SYNOPSIS__ command line might be displayed as:
1	perry	280
2	AristotlePagaltzis	281	filter [[-flag] infile outfile
1	perry	282
2	AristotlePagaltzis	283	Here, filter is the command name and the bracketed string -flag is a ''flag'' argument designated as optional by the option brackets. In -mdoc terms, infile and outfile are called ''meta arguments''; in this example, the user has toreplace the meta expressions given in angle brackets withreal file names. Note that in this document meta argumentsare used to describe -mdoc commands; in most man pages, metavariables are not specifically written with angle brackets.The macros which formatted the above example:
1	perry	284
2	AristotlePagaltzis	285	.Nm filter .Op Fl flag
1	perry	286	.Ao Ar infile Ac Ao Ar outfile Ac
		287
2	AristotlePagaltzis	288	In the third case, discussion of commands and command syntax includes both examples above, but may add more detail. The arguments infile and outfile from the example abovemight be referred to as ''operands'' or '' file arguments''. Some command line argument lists are quite long:
1	perry	289
2	AristotlePagaltzis	290	make [[-eiknqrstv] [[-D variable] [[-d flags] [[-fmakefile] [[-I directory] [[-j max_jobs] [[variable=value] [[target ...]
1	perry	291
2	AristotlePagaltzis	292	Here one might talk about the command make and qualify the argument, makefile, as an argument to the flag, -f, or discuss the optional file operand target. In the verbal context, such detail can prevent confusion, however the -mdoc package does not have a macro for an argument ''to'' a flag. Instead the Ar argument macro is used for an operand or file argument like target as well as an argument to a flag like variable. The make command line was produced from:
1	perry	293
		294	.Nm make
		295	.Op Fl eiknqrstv
		296	.Op Fl D Ar variable
		297	.Op Fl d Ar flags
		298	.Op Fl f Ar makefile
		299	.Op Fl I Ar directory
		300	.Op Fl j Ar max_jobs
		301	.Op Ar variable Ns = Ns Ar value
		302	.Bk
		303	.Op Ar target ...
		304	.Ek
2	AristotlePagaltzis	305
1	perry	306	The .Bk and .Ek macros are explained in __Keeps__.
		307
		308	__General Syntax__
		309
2	AristotlePagaltzis	310	The manual domain and general text domain macros share a similar syntax with a few minor deviations; most notably, .Ar, .Fl, .Nm, and .Pa differ only when called without arguments; and .Fn and .Xr impose an order on their argument lists. All content macros are capable of recognizing and properly handling punctuation, provided each punctuation character is separated by a leading space. If a request is given:
1	perry	311
		312	.Ar sptr, ptr),
		313
		314	The result is:
		315
		316	sptr, ptr),
		317
2	AristotlePagaltzis	318	The punctuation is not recognized and all is output in the font used by .Ar. If the punctuation is separated by a leading white space:
1	perry	319
		320	.Ar sptr , ptr ) ,
		321
		322	The result is:
		323
		324	sptr, ptr),
		325
2	AristotlePagaltzis	326	The punctuation is now recognized and output in the default font distinguishing it from the argument strings. To remove the special meaning from a punctuation character escape it with .
1	perry	327
2	AristotlePagaltzis	328	Troff is limited as a macro language, and has difficulty when presented with a string containing a member of the mathematical, logical or quotation set:
1	perry	329
		330	{+,-,/,,%,
2	AristotlePagaltzis	331	The problem is that troff may assume it is supposed to actually perform the operation or evaluation suggested by the characters. To prevent the accidental evaluation of these characters, escape them with . Typical syntax is shown in the first content macro displayed below, .Ad.
1	perry	332
2	AristotlePagaltzis	333	!!!MANUAL DOMAIN
1	perry	334
		335	__Addresses__
		336
		337	The address macro identifies an address
		338	construct.
		339
		340	Usage: .Ad
		341	address ... .Ad addr1
		342	''addr1''
		343	.Ad addr1 .''
		344	addr1''.
		345	.Ad addr1 , file2''
		346	addr1'', ''file2''
		347	.Ad f1 , f2 , f3 :''
		348	f1'', ''f2'', ''f3'':
		349	.Ad addr ) ) ,''
		350	addr'')),
		351	The default width is 12n.
		352	__Author Name__
		353	The .An macro is used to specify the name of the
		354	author of the item being documented, or the name of the
		355	author of the actual manual page.
		356	Usage: .An
		357	author name ...
		358	.An Joe Author Joe Author
		359	.An Joe Author ,
		360	Joe Author,
		361	.An Joe Author Aq nobody@FreeBSD.org
		362	Joe Author nobody@FreeBSD.org
		363	.An Joe Author ) ) ,
		364	Joe Author)),
		365	The default width is 12n.
		366	In the __AUTHORS__ section, the .An request
		367	causes a line break allowing each new name to appear on its
		368	own line. If this is not desirable,
		369	.An -nosplit
		370	call will turn this off. To turn splitting back on,
		371	write
		372
		373
		374	.An -split
		375
		376
		377	__Arguments__
		378
		379
		380	The .Ar argument macro may be used whenever an
		381	argument is referenced. If called without arguments, the
		382	file ... string is output.
		383
		384
		385	Usage: .Ar [[
		386	argument] ... .Ar
		387	file ...
		388	.Ar file1
		389	file1
		390	.Ar file1 .
		391	file1.
		392	.Ar file1 file2
		393	file1 file2
		394	.Ar f1 f2 f3 :
		395	f1 f2 f3:
		396	.Ar file ) ) ,
		397	file)),
		398	The default width is 12n.
		399	__Configuration Declaration (Section Four Only)__
		400	The .Cd macro is used to demonstrate a
		401	config(8) declaration for a device interface in a
		402	section four manual.
		403	Usage: .Cd
		404	argument ...
		405	.Cd device le0 at scode?
		406	device le0 at scode?
		407	In the __SYNOPSIS__ section a .Cd request
		408	causes a line break before and after its arguments are
		409	printed.
		410	The default width is 12n.
		411	__Command Modifiers__
		412	The command modifier is identical to the .Fl (flag)
		413	command with the exception that the .Cm macro does
		414	not assert a dash in front of every argument. Traditionally
		415	flags are marked by the preceding dash, however, some
		416	commands or subsets of commands do not use them. Command
		417	modifiers may also be specified in conjunction with
		418	interactive commands such as editor commands. See
		419	__Flags__.
		420	The default width is 10n.
		421	__Defined Variables__
		422	A variable (or constant) which is defined in an include file
		423	is specified by the macro .Dv.
		424	Usage: .Dv
		425	defined variable ...
		426	.Dv MAXHOSTNAMELEN
		427	MAXHOSTNAMELEN
		428	.Dv TIOCGPGRP )
		429	TIOCGPGRP)
		430	The default width is 12n.
		431	__Errno's__
		432	The .Er errno macro specifies the error return
		433	value for section 2, 3, and 9 library routines. The second
		434	example below shows .Er used with the .Bq
		435	general text domain macro, as it would be used in a section
		436	two manual page.
		437	Usage: .Er
		438	errno type ...
		439	.Er ENOENT
		440	ENOENT
		441	.Er ENOENT ) ;
		442	ENOENT);
		443	.Bq Er ENOTDIR
		444	[[ENOTDIR]
		445	The default width is 17n.
		446	__Environment Variables__
		447	The .Ev macro specifies an environment
		448	variable.
		449	Usage: .Ev
		450	argument ...
		451	.Ev DISPLAY
		452	DISPLAY
		453	.Ev PATH .
		454	PATH.
		455	.Ev PRINTER ) ) ,
		456	PRINTER)),
		457	The default width is 15n.
		458	__Flags__
		459	The .Fl macro handles command line flags. It
		460	prepends a dash, -, to the flag. For interactive
		461	command flags, which are not prepended with a dash, the
		462	.Cm (command modifier) macro is identical, but
		463	without the dash.
		464	Usage: .Fl
		465	argument ...
		466	.Fl
		467	-
		468	.Fl cfv
		469	-cfv
		470	.Fl cfv .
		471	-cfv.
		472	.Cm cfv .
		473	cfv.
		474	.Fl s v t
		475	-s -v -t
		476	.Fl - ,
		477	--,
		478	.Fl xyz ) ,
		479	-xyz),
		480	.Fl |
		481	- |
		482	The .Fl macro without any arguments results in
		483	a dash representing stdin/stdout. Note that giving
		484	.Fl a single dash will result in two dashes.
		485	The default width is 12n.
		486	__Function Declarations__
		487	The .Fd macro is used in the __SYNOPSIS__
		488	section with section two or three functions. It is neither
		489	callable nor parsed.
		490	Usage: .Fd
		491	argument ...
		492	.Fd #include
		493	#include
		494	In the __SYNOPSIS__ section a .Fd request
		495	causes a line break if a function has already been presented
		496	and a break has not occurred. This leaves a nice vertical
		497	space in between the previous function call and the
		498	declaration for the next function.
		499	The .In (#include statement) macro is
		500	the short form of the above example. It specifies the C
		501	header file as being included in a C program. It also causes
		502	a line break, and is neither callable nor parsed.
		503	Usage: .In
		504	header file
		505	.In stdio.h
		506	#include
		507	__Function Types__
		508	This macro is intended for the __SYNOPSIS__ section. It
		509	may be used anywhere else in the man page without problems,
		510	but its main purpose is to present the function type in
		511	kernel normal form for the __SYNOPSIS__ of sections two
		512	and three (it causes a line break, allowing the function
		513	name to appear on the next line).
		514	Usage: .Ft
		515	type ...
		516	.Ft struct stat
		517	struct stat
		518	__Functions (Library Routines)__
		519	The .Fn macro is modeled on ANSI C
		520	conventions.
		521	Usage: .Fn
		522	function [[
		523	parameter] ...
		524	.Fn getchar getchar()
		525	.Fn strlen ) ,
		526	strlen()),
		527	.Fn align char ptr ,
		528	align(char ptr),
		529	Note that any call to another macro signals the end of
		530	the .Fn call (it will insert a closing parenthesis
		531	at that point).
		532	For functions with many parameters (which is rare), the
		533	macros .Fo (function open) and .Fc
		534	(function close) may be used with .Fa (function
		535	argument).
		536	Example:
		537	.Ft int
		538	.Fo res_mkquery
		539	.Fa
		540	Produces:
		541
		542
		543	int
		544	res_mkquery(int op
		545	, char dname, int class,int type, char data, int datalen, struct rrec newrr,char buf, int buflen)
		546	In the __SYNOPSIS__ section, the function will always
		547	begin at the beginning of line. If there is more than one
		548	function presented in the __SYNOPSIS__ section and a
		549	function type has not been given, a line break will occur,
		550	leaving a nice vertical space between the current function
		551	name and the one prior.
		552	The default width values of .Fn and
		553	.Fo are 12n and 16n, respectively.
		554
		555
		556	__Function Arguments__
		557	The .Fa macro is used to refer to function
		558	arguments (parameters) outside of the __SYNOPSIS__
		559	section of the manual or inside the __SYNOPSIS__ section
		560	if the enclosure macros .Fo and .Fc
		561	instead of .Fn are used. .Fa may also be
		562	used to refer to structure members.
		563
		564
		565	Usage: .Fa
		566	function argument ... .Fa d_namlen ) ) ,
		567	d_namlen)),
		568	.Fa iov_len
		569	iov_len
		570	The default width is 12n.
		571	__Return Values__
		572	The .Rv macro generates text for use in the
		573	__RETURN VALUES__ section.
		574	Usage: .Rv [[
		575	-std]
		576	function
		577	For example, .Rv -std atexit produces:
2	AristotlePagaltzis	578	The atexit() function returns the value 0 if successful; otherwise the value -1 is returned and the global
1	perry	579	variable ''errno'' is set to indicate the error.
		580
		581
		582	The -std option is valid only for manual page sections 2 and 3. Currently, this macro does nothing if used without the -std flag.
		583
		584
		585	__Interactive Commands__
		586
		587
		588	The .Ic macro designates an interactive or internal
		589	command.
		590
		591
		592	Usage: .Ic
		593	argument ... .Ic :wq
		594	:wq
		595	.Ic do while {...}
		596	do while {...}
		597	.Ic setenv , unsetenv
		598	setenv, unsetenv
		599	The default width is 12n.
		600	__Library Names__
		601	The .Lb macro is used to specify the library where
		602	a particular function is compiled in.
		603	Usage: .Lb
		604	argument ...
		605	Available arguments to .Lb and their results
		606	are:
		607	libarm32 ARM32 Architecture Library (libarm32,
		608	-larm32)
		609	libc
		610	Standard C Library (libc, -lc)
		611	libcompat
		612	Compatibility Library (libcompat, -lcompat)
		613	libcrypt
		614	Crypt Library (libcrypt, -lcrypt)
		615	libcurses
		616	Curses Library (libcurses, -lcurses)
		617	libedit
		618	Command Line Editor Library (libedit, -ledit)
		619	libi386
		620	i386 Architecture Library (libi386, -li386)
		621	libipsec
		622	IPsec Policy Control Library (libipsec, -lipsec)
		623	libkvm
		624	Kernel Data Access Library (libkvm, -lkvm)
		625	libm
		626	Math Library (libm, -lm)
		627	libmenu
		628	Curses Menu Library (libmenu, -lmenu)
		629	libossaudio
		630	OSS Audio Emulation Library (libossaudio,
		631	-lossaudio)
		632	libposix
		633	POSIX Compatibility Library (libposix,
		634	-lposix)
		635	libresolv
		636	DNS Resolver Library (libresolv, -lresolv)
		637	libtermcap
		638	Termcap Access Library (libtermcap, -ltermcap)
		639	libutil
		640	System Utilities Library (libutil, -lutil)
		641	libz
		642	Compression Library (libz, -lz)
		643	Local, OS-specific additions might be found in the file
		644	mdoc.local; look for strings named
		645	str-Lb-XXX. XXX then denotes the keyword
		646	to be used with the .Lb macro.
		647	__Literals__
		648	The .Li literal macro may be used for special
		649	characters, variable constants, etc. -- anything which
		650	should be displayed as it would be typed.
		651	Usage: .Li
		652	argument ...
		653	.Li en
		654	n
		655	.Li M1 M2 M3 ;
		656	M1 M2 M3;
		657	.Li cntrl-D ) ,
		658	cntrl-D),
		659	.Li 1024 ...
		660	1024 ...
		661	The default width is 16n.
		662	__Names__
		663	The .Nm macro is used for the document title or
		664	subject name. It has the peculiarity of remembering the
		665	first argument it was called with, which should always be
		666	the subject name of the page. When called without arguments,
		667	.Nm regurgitates this initial name for the sole
		668	purpose of making less work for the author. Note: A section
		669	two or three document function name is addressed with the
		670	.Nm in the __NAME__ section, and with
2	AristotlePagaltzis	671	.Fn in the __SYNOPSIS__ and remaining sections. For interactive commands, such as the while
1	perry	672	command keyword in csh(1), the .Ic macro
		673	should be used. While .Ic is nearly identical to
		674	.Nm, it can not recall the first argument it was
		675	invoked with.
		676	Usage: .Nm [[
		677	argument] ...
		678	.Nm groff_mdoc
		679	groff_mdoc
		680	.Nm -mdoc
		681	-mdoc
		682	.Nm foo ) ) ,
		683	foo)),
		684	.Nm :
		685	groff_mdoc:
		686	The default width is 10n.
		687	__Options__
		688	The .Op macro places option brackets around any
		689	remaining arguments on the command line, and places any
		690	trailing punctuation outside the brackets. The macros
		691	.Oo and .Oc (which produce an opening and
		692	a closing option bracket respectively) may be used across
		693	one or more lines or to specify the exact position of the
		694	closing parenthesis.
		695	Usage: .Op [[
		696	option] ...
		697	.Op [[]
		698	.Op Fl k
		699	[[-k]
		700	.Op Fl k ) .
		701	[[-k]).
		702	.Op Fl k Ar kookfile
		703	[[-k kookfile]
		704	.Op Fl k Ar kookfile ,
		705	[[-k kookfile],
		706	.Op Ar objfil Op Ar corfil
		707	[[objfil [[corfil]]
		708	.Op Fl c Ar objfil Op Ar corfil ,
		709	[[-c objfil [[corfil]],
		710	.Op word1 word2
		711	[[word1 word2]
		712	.Li .Op Oo Ao option Ac Oc ...
		713	.Op [[
		714	options] ...
		715	Here a typical example of the .Oo and
		716	.Oc macros:
		717	.Oo
		718	.Op Fl k Ar kilobytes
		719	.Op Fl i Ar interval
		720	.Op Fl c Ar count
		721	.Oc
		722	Produces:
		723
		724
		725	[[
		726	[[-k kilobytes]
		727	[[-i interval]
		728	[[-c count]
		729	]
		730	The default width values of .Op and
		731	.Oo are 14n and 10n, respectively.
		732
		733
		734	__Pathnames__
		735	The .Pa macro formats path or file names. If
		736	called without arguments, the ~ string is output,
		737	which represents the current user's home directory.
		738
		739
		740	Usage: .Pa [[
		741	pathname] ... .Pa ~ .Pa /usr/share /usr/share .Pa /tmp/fooXXXXX ) . /tmp/fooXXXXX
		742	).
		743	The default width is 32n.
		744	__Standards__
		745	The .St macro replaces standard abbreviations with
		746	their formal names.
		747	Usage: .St
		748	abbreviation ...
		749	Available pairs for ``Abbreviation/Formal Name''
		750	are:
		751	ANSI/ISO C
		752	-ansiC ANSI X3.159-1989 (``
		753	ANSI C '')
		754	-ansiC-89
		755	ANSI X3.159-1989 (`` ANSI C
		756	'')
		757	-isoC
		758	ISO/IEC 9899:1990 (`` ISO C89
		759	'')
		760	-isoC-99
		761	ISO/IEC 9899:1999 (`` ISO C99 '')
		762	POSIX Part 1: System API
		763	-iso9945-1-90
		764	ISO/IEC 9945-1:1990 (`` POSIX
		765	.1'')
		766	-iso9945-1-96
		767	ISO/IEC 9945-1:1996 (`` POSIX
		768	.1'')
		769	-p1003.1
		770	IEEE Std 1003.1 (`` POSIX
		771	.1'')
		772	-p1003.1-88
		773	IEEE Std 1003.1-1988 (`` POSIX
		774	.1'')
		775	-p1003.1-90
		776	ISO/IEC 9945-1:1990 (`` POSIX
		777	.1'')
		778	-p1003.1-96
		779	ISO/IEC 9945-1:1996 (`` POSIX
		780	.1'')
		781	-p1003.1b-93
		782	IEEE Std 1003.1b-1993 (`` POSIX
		783	.1'')
		784	-p1003.1c-95
		785	IEEE Std 1003.1c-1995 (`` POSIX
		786	.1'')
		787	-p1003.1g-2000
		788	IEEE Std 1003.1g-2000 (`` POSIX
		789	.1'')
		790	-p1003.1i-95
		791	IEEE Std 1003.1i-1995 (`` POSIX
		792	.1'')
		793	POSIX Part 2: Shell and Utilities
		794	-iso9945-2-93
		795	ISO/IEC 9945-2:1993 (`` POSIX
		796	.2'')
		797	-p1003.2
		798	IEEE Std 1003.2 (`` POSIX
		799	.2'')
		800	-p1003.2-92
		801	IEEE Std 1003.2-1992 (`` POSIX
		802	.2'')
		803	-p1003.2a-92
		804	IEEE Std 1003.2a-1992 (`` POSIX
		805	.2'')
		806	X/Open
		807	-susv2 Version 2 of the Single
		808	UNIX Specification (`` SUSv2
		809	'')
		810	-svid4
		811	System V Interface Definition, Fourth Edition (``
		812	SVID 4'')
		813	-xbd5
		814	X/Open System Interface Definitions Issue 5 (``
		815	XBD 5'')
		816	-xcu5
		817	X/Open Commands and Utilities Issue 5 (``
		818	XCU 5'')
		819	-xcurses4.2
		820	X/Open Curses Issue 4.2 (`` XCURSES
		821	4.2'')
		822	-xns5
		823	X/Open Networking Services Issue 5 (``
		824	XNS 5'')
		825	-xns5.2
		826	X/Open Networking Services Issue 5.2 (``
		827	XNS 5.2'')
		828	-xpg3
		829	X/Open Portability Guide Issue 3 (``
		830	XPG 3'')
		831	-xpg4
		832	X/Open Portability Guide Issue 4 (``
		833	XPG 4'')
		834	-xpg4.2
		835	X/Open Portability Guide Issue 4.2 (``
		836	XPG 4.2'')
		837	-xsh5
		838	X/Open System Interfaces and Headers Issue 5 (``
		839	XSH 5'')
		840	Miscellaneous
		841	-ieee754 IEEE Std
		842	754-1985
		843	-iso8802-3
		844	ISO/IEC 8802-3:1989
		845	__Variable Types__
		846	The .Vt macro may be used whenever a type is
		847	referenced. In the __SYNOPSIS__ section, it causes a line
		848	break (useful for old style variable declarations).
		849	Usage: .Vt
		850	type ...
		851	.Vt extern char optarg ;
		852	extern char optarg;
		853	.Vt FILE
		854	FILE
		855	__Variables__
		856	Generic variable reference.
		857	Usage: .Va
		858	variable ...
		859	.Va count ''count''
		860	.Va settimer ,''
		861	settimer'',
		862	.Va int prt ) :''
		863	int prt''):
		864	.Va char s ] ) ) ,''
		865	char s''])),
		866	The default width is 12n.
		867	__Manual Page Cross References__
		868	The .Xr macro expects the first argument to be a
		869	manual page name. The optional second argument, if a string
		870	(defining the manual section), is put into parentheses.
		871	Usage: .Xr
		872	man page name [[
		873	section] ...
		874	.Xr mdoc
		875	mdoc
		876	.Xr mdoc ,
		877	mdoc,
		878	.Xr mdoc 7
		879	mdoc(7)
		880	.Xr xinit 1x ;
		881	xinit(1x);
		882	The default width is 10n.
		883
2	AristotlePagaltzis	884	!!!GENERAL TEXT DOMAIN
		885
		886
		887
		888
		889	!!!AT
1	perry	890
		891
		892
		893	Usage: .At [[
		894	version] ... .At
		895	AT
		896	.At v6 .
		897	Version 6 AT .
		898	The following values for
		899	version are possible:
		900	32v, v1, v2, v3, v4, v5, v6, v7, V, V.1, V.2, V.3,
		901	V.4
		902	__BSD Macro__
		903	Usage: .Bx {
		904	-alpha | -beta | -devel} ... .Bx [[
		905	version [[
		906	release]] ...
		907	.Bx
		908	BSD
		909	.Bx 4.3 .
		910	4.3 BSD .
		911	.Bx -devel
		912	BSD (currently under development)
		913	version will be prepended to the string BSD .
		914	The following values for
		915	release are possible:
		916	Reno, reno, Tahoe, tahoe, Lite, lite, Lite2,
		917	lite2
		918	__NetBSD Macro__
		919	Usage: .Nx [[
		920	version] ...
		921	.Nx
		922	N et BSD
		923	.Nx 1.4 .
		924	N et BSD 1.4.
		925	For possible values of
		926	version see the description of the .Os request
		927	above in section __TITLE MACROS__.
		928	__FreeBSD Macro__
		929	Usage: .Fx [[
		930	version] ...
		931	.Fx
		932	FreeBSD
		933	.Fx 2.2 .
		934	FreeBSD 2.2.
		935	For possible values of
		936	version see the description of the .Os request
		937	above in section __TITLE MACROS__.
		938	__OpenBSD Macro__
		939	Usage: .Ox [[
		940	version] ...
		941	.Ox 1.0
		942	OpenBSD 1.0
		943	__BSD/OS Macro__
		944	Usage: .Bsx [[
		945	version] ...
		946	.Bsx 1.0
		947	BSD/OS 1.0
		948	__UNIX Macro__
		949	Usage: .Ux ...
		950	.Ux
		951	UNIX
		952	__Emphasis Macro__
		953	Text may be stressed or emphasized with the .Em
		954	macro. The usual font for emphasis is italic.
		955	Usage: .Em
		956	argument ...
		957	.Em does not ''does not''
		958	.Em exceed 1024 .''
		959	exceed 1024''.
		960	.Em vide infra ) ) ,''
		961	vide infra'')),
		962	The default width is 10n.
		963	__Font Mode__
		964	The .Bf font mode must be ended with the
		965	.Ef macro (the latter takes no arguments). Font
		966	modes may be nested within other font modes.
		967	.Bf has the following syntax:
		968	.Bf
		969	font mode
		970	font mode must be one of the following three types:
		971	__Em__ | -emphasis
		972	Same as if the .Em macro was used for the entire
		973	block of text.__
		974	Li__ | -literal
		975	Same as if the .Li macro was used for the entire
		976	block of text.__
		977	Sy__ | -symbolic
		978	Same as if the .Sy macro was used for the entire
		979	block of text.
		980	Both macros are neither callable nor parsed.
		981	__Enclosure and Quoting Macros__
		982	The concept of enclosure is similar to quoting. The object
2	AristotlePagaltzis	983	being to enclose one or more strings between a pair of characters like quotes or parentheses. The terms quoting and
1	perry	984	enclosure are used interchangeably throughout this document.
		985	Most of the one-line enclosure macros end in small letter
		986	q to give a hint of quoting, but there are a few
		987	irregularities. For each enclosure macro there is also a
		988	pair of open and close macros which end in small letters
		989	o and c respectively.
		990
		991
		992	''Quote Open Close Function Result
		993	''.Aq .Ao .Ac Angle Bracket Enclosure string
		994	.Bq .Bo .Bc Bracket Enclosure [[string]
		995	.Brq .Bro .Brc Brace Enclosure {string}
		996	.Dq .Do .Dc Double Quote ``string''
		997	.Eq .Eo .Ec Enclose String (in XX) XXstringXX
		998	.Pq .Po .Pc Parenthesis Enclosure (string)
		999	.Ql Quoted Literalstring or string
		1000	.Qq .Qo .Qc Straight Double Quote
		1001	string
		1002	.Sq .So .Sc Single Quote
		1003	string
		1004
		1005
		1006	All macros ending with q and o have a default width value of
		1007	12n.
		1008	.Eo
		1009	,
		1010	.Ec
		1011
		1012
		1013	These macros expect the first argument to be the opening and
		1014	closing strings respectively.
		1015
		1016
		1017	.Es, .En
		1018	Due to the nine-argument limit in the original troff program two other macros have been implemented which are now rather obsolete: .Es takes the first and second parameter as the left and right enclosure string, which are then used to enclose the arguments of .En. The default width value is 12n for both macros.
		1019
		1020
		1021	.Eq
		1022	The first and second arguments of this macro are the opening
		1023	and closing strings respectively, followed by the
		1024	arguments to be enclosed.
		1025
		1026
		1027	.Ql
		1028	The quoted literal macro behaves differently in troff and
		1029	nroff mode. If formatted with nroff, a quoted
		1030	literal is always quoted. If formatted with troff, an item
		1031	is only quoted if the width of the item is less than three
		1032	constant width characters. This is to make short strings
		1033	more visible where the font change to literal (constant
		1034	width) is less noticeable.
		1035
		1036
		1037	The default width is 16n.
		1038
		1039
		1040	.Pf
		1041	The prefix macro suppresses the whitespace between its first
		1042	and second argument:
		1043
		1044
		1045	.Pf ( Fa name2
		1046	(name2
		1047
		1048
		1049	The default width is 12n.
		1050
		1051
		1052	The .Ns macro (see below) performs the analogous
		1053	suffix function.
		1054
		1055
		1056	.Ap
		1057	The .Ap macro inserts an apostrophe and exits any
		1058	special text modes, continuing in .No
		1059	mode.
		1060
		1061
		1062	Examples of quoting:
		1063
		1064
		1065	.Aq
		1066	.Aq Pa ctype.h ) ,
		1067	ctype.h),
		1068	.Bq
		1069	[[]
		1070	.Bq Em Greek , French .
		1071	[[''Greek'', ''French''].
		1072	.Dq
		1073	``''
		1074	.Dq string abc .
		1075	``string abc''.
		1076	.Dq ^[[A-Z]
		1077	``^[[A-Z]''
		1078	.Ql man mdoc
		1079	man mdoc
		1080	.Qq
		1081	.Qq string ) ,
		1082	string),
		1083	.Qq string Ns ),
		1084	string),
		1085	.Sq
		1086	.Sq string
		1087	string
		1088	.Em or Ap ing''
		1089	or'''ing
		1090
		1091
		1092	For a good example of nested enclosure macros, see the
		1093	.Op option macro. It was created from the same
		1094	underlying enclosure macros as those presented in the list
		1095	above. The .Xo and .Xc extended argument
		1096	list macros are discussed below.
		1097
		1098
		1099	__No-Op or Normal Text Macro__
		1100	The .No macro can be used in a macro command line
		1101	for parameters which should ''not'' be formatted. Be
		1102	careful to add to the word No if you
		1103	really want that English word (and not the macro) as a
		1104	parameter.
		1105
		1106
		1107	Usage: .No
		1108	argument ...
		1109
		1110
		1111	.No test Ta with Ta tabs
		1112	test with tabs
		1113
		1114
		1115	The default width is 12n.
		1116
		1117
		1118	__No-Space Macro__
		1119	The .Ns macro suppresses insertion of a space
		1120	between the current position and its first parameter. For
		1121	example, it is useful for old style argument lists where
		1122	there is no space between the flag and
		1123	argument:
		1124
		1125
		1126	Usage: ...
		1127	argument Ns [[
		1128	argument] ... .Ns
		1129	argument ...
		1130
		1131
		1132	.Op Fl I Ns Ar directory
		1133	[[-Idirectory]
		1134
		1135
		1136	Note: The .Ns macro always invokes the .No
		1137	macro after eliminating the space unless another macro
		1138	name follows it. If used as a request (i.e., the second form
		1139	above in the Usage line, .Ns is identical to
		1140	.No.
		1141
		1142
		1143	__Section Cross References__
		1144	The .Sx macro designates a reference to a section
		1145	header within the same document.
		1146
		1147
		1148	Usage: .Sx
		1149	section reference ...
		1150
		1151
		1152	.Sx FILES__
		1153	FILES__
		1154
		1155
		1156	The default width is 16n.
		1157
		1158
		1159	__Symbolics__
		1160	The symbolic emphasis macro is generally a boldface macro in
		1161	either the symbolic sense or the traditional English
		1162	usage.
		1163
		1164
		1165	Usage: .Sy
		1166	symbol ...
		1167
		1168
		1169	.Sy Important Notice__
		1170	Important Notice__
		1171
		1172
		1173	The default width is 6n.
		1174
		1175
		1176	__Mathematical Symbols__
		1177	Use this macro for mathematical symbols and similar
		1178	things.
		1179
		1180
		1181	Usage: .Ms
		1182	math symbol ...
		1183
		1184
		1185	.Ms sigma__
		1186	sigma__
		1187
		1188
		1189	The default width is 6n.
		1190
		1191
		1192	__References and Citations__
2	AristotlePagaltzis	1193	The following macros make a modest attempt to handle references. At best, the macros make it convenient to manually
1	perry	1194	drop in a subset of refer(1) style
		1195	references.
		1196
		1197
		1198	.Rs
		1199	Reference start (does not take arguments). Causes a line
		1200	break in the __SEE ALSO__ section and begins collection
		1201	of reference information until the reference end macro is
		1202	read.
		1203	.Re
		1204	Reference end (does not take arguments). The reference is
		1205	printed.
		1206	.%A
		1207	Reference author name; one name per invocation.
		1208	.%B
		1209	Book title.
		1210	.%C
		1211	City/place (not implemented yet).
		1212	.%D
		1213	Date.
		1214	.%I
		1215	Issuer/publisher name.
		1216	.%J
		1217	Journal name.
		1218	.%N
		1219	Issue number.
		1220	.%O
		1221	Optional information.
		1222	.%P
		1223	Page number.
		1224	.%Q
		1225	Corporate or foreign author.
		1226	.%R
		1227	Report name.
		1228	.%T
		1229	Title of article.
		1230	.%V
		1231	Volume.
		1232
		1233
		1234	Macros beginning with % are not callable but accept
		1235	multiple arguments in the usual way. Only the .Tn
		1236	macro is handled properly as a parameter; other macros will
		1237	cause strange output. .%B and .%T can be
		1238	used outside of the .Rs/.Re
		1239	environment.
		1240
		1241
		1242	Example:
		1243
		1244
		1245	.Rs
		1246	.%A
		1247	produces
		1248	Matthew Bar and John Foo,'' Implementation Noteson foobar(1)'', Technical Report ABC-DE-12-345, Drofnats College, Nowhere, April 1991.
		1249
		1250
		1251	__Trade Names (or Acronyms and Type Names)__
		1252	The trade name macro prints its arguments in a smaller
		1253	font. Its intended use is to imitate a small caps fonts for
		1254	uppercase acronyms.
		1255
		1256
		1257	Usage: .Tn
		1258	symbol ... .Tn DEC
		1259	DEC
		1260	.Tn ASCII
		1261	ASCII
		1262	The default width is 10n.
		1263	__Extended Arguments__
		1264	The .Xo and .Xc macros allow one to extend
		1265	an argument list on a macro boundary for the .It
		1266	macro (see below). Note that .Xo and .Xc
		1267	are implemented similarly to all other macros opening and
		1268	closing an enclosure (without inserting characters, of
		1269	course). This means that the following is true for those
		1270	macros also.
		1271	Here is an example of .Xo using the space mode
		1272	macro to turn spacing off:
		1273	.Sm off
		1274	.It Xo Sy I Ar operation
		1275	.No en Ar count No en
		1276	.Xc
		1277	.Sm on
		1278	produces
		1279	__ I__operationncountn
		1280
		1281
		1282	Another one:
		1283
		1284
		1285	.Sm off
		1286	.It Cm S No / Ar old_pattern Xo
		1287	.No / Ar new_pattern
		1288	.No / Op Cm g
		1289	.Xc
		1290	.Sm on
		1291	produces
		1292	S/old_pattern /new_pattern
		1293	/[[g]
		1294
		1295
		1296	Another example of .Xo and enclosure macros: Test
		1297	the value of a variable.
		1298
		1299
		1300	.It Xo
		1301	.Ic .ifndef
		1302	.Oo
		1303	produces
		1304	.ifndef
		1305	[[ !]variable [[ operator variable ...
		1306	]
2	AristotlePagaltzis	1307
		1308	!!!PAGE STRUCTURE DOMAIN
		1309
1	perry	1310
		1311
		1312	__Section Headers__
		1313
		1314
		1315	The following .Sh section header macros are
		1316	required in every man page. The remaining section headers
		1317	are recommended at the discretion of the author writing
		1318	the manual page. The .Sh macro is parsed but not
		1319	generally callable. It can be used as an argument in a call
		1320	to .Sh only; it then reactivates the default font
		1321	for .Sh.
		1322
		1323
		1324	The default width is 8n.
		1325	.Sh NAME
		1326	The .Sh NAME macro is mandatory. If not
		1327	specified, headers, footers and page layout defaults will
		1328	not be set and things will be rather unpleasant. The
		1329	__NAME__ section consists of at least three items. The
		1330	first is the .Nm name macro naming the subject of
		1331	the man page. The second is the name description macro,
		1332	.Nd, which separates the subject name from the
		1333	third item, which is the description. The description should
		1334	be the most terse and lucid possible, as the space available
		1335	is small.
2	AristotlePagaltzis	1336	.Nd first prints -, then all its arguments.
1	perry	1337
		1338
		1339	.Sh LIBRARY
		1340	This section is for section two and three function calls. It should consist of a single .Lb macro call; see __Library Names__.
		1341
		1342
		1343	.Sh SYNOPSIS
		1344	The __SYNOPSIS__ section describes the typical usage of
		1345	the subject of a man page. The macros required are either
		1346	.Nm, .Cd, or .Fn (and possibly
		1347	.Fo, .Fc, .Fd, and .Ft).
		1348	The function name macro .Fn is required for manual
		1349	page sections 2 and 3; the command and general name macro
		1350	.Nm is required for sections 1, 5, 6, 7, and 8.
		1351	Section 4 manuals require a .Nm, .Fd or a
		1352	.Cd configuration device usage macro. Several other
		1353	macros may be necessary to produce the synopsis line as
		1354	shown below:
		1355
		1356
		1357	cat [[-benstuv] [[-] file ...
		1358
		1359
		1360	The following macros were used:
		1361
		1362
		1363	.Nm cat
		1364
		1365
		1366	.Op Fl benstuv
		1367
		1368
		1369	.Op Fl
		1370
		1371
		1372	.Ar
		1373	.Sh DESCRIPTION
		1374
		1375
		1376	In most cases the first text in the __DESCRIPTION__
		1377	section is a brief paragraph on the command, function or
		1378	file, followed by a lexical list of options and respective
		1379	explanations. To create such a list, the .Bl (begin
		1380	list), .It (list item) and .El (end list)
		1381	macros are used (see __Lists and Columns__
		1382	below).
		1383
		1384
		1385	.Sh IMPLEMENTATION NOTES
		1386	Implementation specific information should be placed
		1387	here.
		1388
		1389
		1390	.Sh RETURN VALUES
		1391	Sections 2, 3 and 9 function return values should go here.
		1392	The .Rv macro may be used to generate text for use
		1393	in the __RETURN VALUES__ section for most section 2 and 3
		1394	library functions; see __Return Values__.
		1395
		1396
		1397	The following .Sh section headers are part of the
		1398	preferred manual page layout and must be used appropriately
		1399	to maintain consistency. They are listed in the order in
		1400	which they would be used.
		1401
		1402
		1403	.Sh ENVIRONMENT The __ENVIRONMENT__ section
		1404	should reveal any related environment variables and clues to
		1405	their behavior and/or usage.
		1406
		1407
		1408	.Sh FILES
		1409	Files which are used or created by the man page subject
		1410	should be listed via the .Pa macro in the
		1411	__FILES__ section.
		1412
		1413
		1414	.Sh EXAMPLES
		1415	There are several ways to create examples. See the
		1416	__EXAMPLES__ section below for details.
		1417
		1418
		1419	.Sh DIAGNOSTICS
		1420	Diagnostic messages from a command should be placed in this
		1421	section.
		1422
		1423
		1424	.Sh COMPATIBILITY
		1425	Known compatibility issues (e.g. deprecated options or
		1426	parameters) should be listed here.
		1427
		1428
		1429	.Sh ERRORS
		1430	Specific error handling, especially from library functions
		1431	(man page sections 2, 3, and 9) should go here. The
		1432	.Er macro is used to specify an error
		1433	(errno).
		1434
		1435
		1436	.Sh SEE ALSO
		1437	References to other material on the man page topic and cross
		1438	references to other relevant man pages should be placed in
		1439	the __SEE ALSO__ section. Cross references are specified
		1440	using the .Xr macro. Currently refer(1)
		1441	style references are not accommodated.
		1442
		1443
		1444	It is recommended that the cross references are sorted on
		1445	the section number, then alphabetically on the names within
		1446	a section, and placed in that order and comma separated.
		1447	Example:
		1448
		1449
		1450	ls(1), ps(1), group(5),
		1451	passwd(5)
		1452
		1453
		1454	.Sh STANDARDS
		1455	If the command, library function or file adheres to a
		1456	specific implementation such as IEEE Std
		1457	1003.2 (`` POSIX .2'') or ANSI
		1458	X3.159-1989 (`` ANSI C '') this should be
		1459	noted here. If the command does not adhere to any standard,
		1460	its history should be noted in the __HISTORY__
		1461	section.
		1462
		1463
		1464	.Sh HISTORY
		1465	Any command which does not adhere to any specific standards
		1466	should be outlined historically in this
		1467	section.
		1468
		1469
		1470	.Sh AUTHORS
		1471	Credits should be placed here. The .An macro should
		1472	be used to specify the name(s) of the
		1473	person(s).
		1474
		1475
		1476	.Sh BUGS
		1477	Blatant problems with the topic go here.
		1478
		1479
		1480	User-specified .Sh sections may be added; for
		1481	example, this section was set with:
		1482
		1483
		1484	.Sh
		1485
		1486
		1487	__Subsection Headers__
		1488
		1489
		1490	Subsection headers have exactly the same syntax as section
		1491	headers: .Ss is parsed but not generally callable.
		1492	It can be used as an argument in a call to .Ss
		1493	only; it then reactivates the default font for
		1494	.Ss.
		1495
		1496
		1497	The default width is 8n.
		1498
		1499
		1500	__Paragraphs and Line Spacing__
		1501	.Pp
		1502
		1503
		1504	The .Pp paragraph command may be used to specify a
		1505	line space where necessary. The macro is not necessary after
		1506	a .Sh or .Ss macro or before a
		1507	.Bl or .Bd macro (which both assert a
		1508	vertical distance unless the -compact flag is
		1509	given).
		1510
		1511
		1512	The macro is neither callable nor parsed and takes no
		1513	arguments; an alternative name is .Lp.
		1514
		1515
		1516	__Keeps__
		1517	The only keep that is implemented at this time is for words.
		1518	The macros are .Bk (begin keep) and .Ek
		1519	(end keep). The only option that .Bk accepts
		1520	currently is -words (this is also the default if no option
		1521	is given) which is useful for preventing line breaks in the
		1522	middle of options. In the example for the make command line
		1523	arguments (see __What's in a Name__), the keep prevented
		1524	nroff from placing up the flag and the argument on
		1525	separate lines.
		1526
		1527
		1528	Both macros are neither callable nor parsed.
		1529
		1530
2	AristotlePagaltzis	1531	More work needs to be done with the keep macros; specifically, a -line option should be added.
1	perry	1532
		1533
		1534	__Examples and Displays__
		1535	There are seven types of displays.
		1536
		1537
		1538	.D1
		1539	(This is D-one.) Display one line of indented text. This
		1540	macro is parsed but not callable.
		1541
		1542
		1543	-ldghfstru
		1544
		1545
		1546	The above was produced by: .D1 Fl
		1547	ldghfstru.
		1548
		1549
		1550	.Dl
		1551	(This is D-ell.) Display one line of indented ''literal''
		1552	text. The .Dl example macro has been used
		1553	throughout this file. It allows the indentation (display) of
		1554	one line of text. Its default font is set to constant width
		1555	(literal). .Dl is parsed but not
		1556	callable.
		1557
		1558
		1559	% ls -ldg /usr/local/bin
		1560
		1561
		1562	The above was produced by: .Dl % ls -ldg
		1563	/usr/local/bin.
		1564
		1565
		1566	.Bd
		1567	Begin display. The .Bd display must be ended with
		1568	the .Ed macro. It has the following
		1569	syntax:
		1570
		1571
		1572	.Bd
		1573	{
		1574	-literal | -filled | -unfilled | -ragged | -centered}
		1575	[[
		1576	-offset
		1577	string] [[
		1578	-file
		1579	file name] [[
		1580	-compact]
		1581
		1582
		1583	-ragged Fill, but do not adjust the right margin (only
		1584	left-justify).
		1585	-centered
		1586	Center lines between the current left and right margin. Note
		1587	that each single line is centered.
		1588	-unfilled
		1589	Do not fill; display a block of text as typed, using line
		1590	breaks as specified by the user. This can produce overlong
		1591	lines without warning messages.
		1592	-filled
		1593	Display a filled block. The block of text is formatted
		1594	(i.e., the text is justified on both the left and right
		1595	side).
		1596	-literal
2	AristotlePagaltzis	1597	Display block with literal font (usually fixed-width). Useful for source code or simple tabbed or spaced text.
		1598
1	perry	1599	-file
		1600	file name
2	AristotlePagaltzis	1601	The file whose name follows the -file flag is read and displayed before any data enclosed with .Bd and .Ed, using the selected display type. Any troff/-mdoc commands in the file will be processed.
		1602
1	perry	1603	-offset
		1604	string
2	AristotlePagaltzis	1605	If -offset is specified with one of the following strings, the string is interpreted to indicate the level of indentation for the forthcoming block of text:
1	perry	1606
2	AristotlePagaltzis	1607	left
		1608	Align block on the current left margin; this is the default mode of .Bd.
1	perry	1609
		1610	center
2	AristotlePagaltzis	1611	Supposedly center the block. At this time unfortunately, the block merely gets left aligned about an imaginary center margin.
		1612
1	perry	1613	indent
2	AristotlePagaltzis	1614	Indent by one default indent value or tab. The default indent value is also used for the .D1 and .Dl macros, so one is guaranteed the two types of displays will line up. The indentation value is normally set to 6n or about two thirds of an inch (six constant width characters).
		1615
1	perry	1616	indent-two
		1617	Indent two times the default indent value.
2	AristotlePagaltzis	1618
1	perry	1619	right
2	AristotlePagaltzis	1620	This ''left'' aligns the block about two inches from the right side of the page. This macro needs work and perhaps may never do the right thing within troff.
1	perry	1621
2	AristotlePagaltzis	1622	If string is a valid numeric expression instead (''with a scale indicator other than u''), use that value for indentation. The most useful scale indicators are m and n, specifying the so-called ''Em'' and ''En square''. This is approximately the width of the letter m resp. the letter n of the current font (for nroff output, both scale indicators give the same values). If string isn't a numeric expression, it is tested whether it is an -mdoc macro name, and the default offset value associated with this macro is used. Finally, if all tests fail, the width of string (typeset with a fixed-width font) is taken as the offset.
1	perry	1623
		1624	-compact
		1625	Suppress insertion of vertical space before begin of
		1626	display.
		1627
		1628	.Ed
		1629	End display (takes no arguments).
		1630
		1631	__Lists and Columns__
		1632
2	AristotlePagaltzis	1633	There are several types of lists which may be initiated with the .Bl begin-list macro. Items within the list are specified with the .It item macro, and each list must end with the .El macro. Lists may be nested within themselves and within displays. The use of columns inside of lists or lists inside of columns is unproven.
1	perry	1634
2	AristotlePagaltzis	1635	In addition, several list attributes may be specified such as the width of a tag, the list offset, and compactness (blank lines between items allowed or disallowed). Most of this document has been formatted with a tag style list (-tag).
1	perry	1636
		1637	It has the following syntax forms:
		1638
		1639	.Bl
		1640	{
		1641	-hang | -ohang | -tag | -diag | -inset}
		1642	[[
		1643	-width
		1644	string] [[
		1645	-xwidth
		1646	command]
		1647	[[
		1648	-offset
		1649	string] [[
		1650	-compact]
		1651	.Bl
		1652	-column [[
		1653	-offset
		1654	string]
		1655	string1
		1656	string2 ...
		1657	.Bl
		1658	{
		1659	-item | -enum [[
		1660	-nested] | -bullet | -hyphen | -dash}
		1661	[[
		1662	-offset
		1663	string] [[
		1664	-compact]
		1665
		1666
		1667	And now a detailed description of the list
		1668	types.
		1669
		1670
		1671	-bullet
		1672	A bullet list.
		1673
		1674
		1675	.Bl -bullet -offset indent -compact
		1676	.It
		1677	Bullet one goes here.
		1678	.It
		1679	Bullet two here.
		1680	.El
		1681	Produces:
		1682	Bullet one goes here.
		1683
		1684
		1685	Bullet two here.-dash (or -hyphen)A dash list..Bl -dash -offset indent -compact
		1686	.It
		1687	Dash one goes here.
		1688	.It
		1689	Dash two here.
		1690	.El
		1691	Produces:
		1692	__ -__Dash one goes here.
		1693
		1694
		1695	__-__Dash two here.-enumAn enumerated list..Bl -enum -offset indent -compact
		1696	.It
		1697	Item one goes here.
		1698	.It
		1699	And item two here.
		1700	.El
		1701	The result:
		1702	1.Item one goes here.
		1703
		1704
		1705	2.And item two here.If you want to nest enumerated lists, use the-nested flag (starting with the second-level list):.Bl -enum -offset indent -compact
		1706	.It
		1707	Item one goes here
		1708	.Bl -enum -nested -compact
		1709	.It
		1710	Item two goes here.
		1711	.It
		1712	And item three here.
		1713	.El
		1714	.It
		1715	And item four here.
		1716	.El
		1717	Result:
		1718	1.Item one goes here.
		1719
		1720
		1721	1.1.Item two goes here. 1.2.And item three here.2.And item four here.-itemA list of type -item without list markers..Bl -item -offset indent
		1722	.It
		1723	Item one goes here.
		1724	Item one goes here.
		1725	Item one goes here.
		1726	.It
		1727	Item two here.
		1728	Item two here.
		1729	Item two here.
		1730	.El
		1731	Produces:
		1732
		1733
		1734	Item one goes here. Item one goes here. Item one goes
		1735	here.
		1736
		1737
		1738	Item two here. Item two here. Item two here.
		1739	-tag
		1740
		1741
		1742	A list with tags. Use -width or -xwidth to specifythe tag width. SL sleep time of the process (secondsblocked) PAGEIN number of disk I/O's resulting from ref-erences by the process to pages notloaded in core. UID numerical user-id of process owner PPID numerical id of parent of process prior-ity (non-positive when in non-interrupt-ible wait)The raw text:.Bl -tag -width
		1743	-diag
		1744
		1745
2	AristotlePagaltzis	1746	Diag lists create section four diagnostic lists and are similar to inset lists except callable macros are ignored. The flags -width and -xwidth are not meaningful in this context.
1	perry	1747
		1748
		1749	Example:
		1750
		1751
		1752	.Bl -diag
		1753	.It You can't use Sy here.
		1754	The message says all.
		1755	.El
		1756	produces
		1757
		1758
		1759	__You can't use Sy here.__ The message says
		1760	all.
		1761	-hang
		1762
		1763
2	AristotlePagaltzis	1764	A list with hanging tags. ''Hanged'' labels appear similar to tagged lists when the label is smaller than the label width. ''Longer hanged list labels'' blend into the paragraph unlike tagged paragraph labels. And the unformatted text which created it:
1	perry	1765
2	AristotlePagaltzis	1766	.Bl -hang -offset indent
		1767	.It Em Hanged
		1768	labels appear similar to tagged lists when the
		1769	label is smaller than the label width.
		1770	.It Em Longer hanged list labels
		1771	blend into the paragraph unlike
		1772	tagged paragraph labels.
		1773	.El
		1774	-ohang
1	perry	1775
2	AristotlePagaltzis	1776	Lists with overhanging tags do not use indentation for the items; tags are written to a separate line.
1	perry	1777
2	AristotlePagaltzis	1778	!!!SL
1	perry	1779
		1780	sleep time of the process (seconds blocked)
		1781
2	AristotlePagaltzis	1782	!!!PAGEIN
1	perry	1783
2	AristotlePagaltzis	1784	number of disk I/O 's resulting from references by the process to pages not loaded in core.
1	perry	1785
2	AristotlePagaltzis	1786	!!!UID
1	perry	1787
		1788	numerical user-id of process owner
		1789
2	AristotlePagaltzis	1790	!!!PPID
1	perry	1791
		1792	numerical id of parent of process priority (non-positive
		1793	when in non-interruptible wait)
		1794
		1795	The raw text:
		1796
		1797
		1798	.Bl -ohang -offset indent
		1799	.It Sy SL
		1800	sleep time of the process (seconds blocked)
		1801	.It Sy PAGEIN
		1802	number of disk
		1803	.Tn I/O Ns 's
		1804	resulting from references by the process
		1805	to pages not loaded in core.
		1806	.It Sy UID
		1807	numerical user-id of process owner
		1808	.It Sy PPID
		1809	numerical id of parent of process priority
		1810	(non-positive when in non-interruptible wait)
		1811	.El
		1812	-inset
		1813
		1814	Here is an example of inset labels:
		1815
		1816	''Tag'' The tagged list (also called a tagged paragraph) is the most common type of list used in the Berkeley manuals. Use a -width attribute as described below.
		1817
2	AristotlePagaltzis	1818	''Diag'' Diag lists create section four diagnostic lists and are similar to inset lists except callable macros are ignored.
1	perry	1819
2	AristotlePagaltzis	1820	''Hang'' Hanged labels are a matter of taste.
1	perry	1821
2	AristotlePagaltzis	1822	''Ohang'' Overhanging labels are nice when space is constrained.
1	perry	1823
2	AristotlePagaltzis	1824	''Inset'' Inset labels are useful for controlling blocks of paragraphs and are valuable for converting -mdoc manuals to other formats.
1	perry	1825
2	AristotlePagaltzis	1826	Here is the source text which produced the above example:
1	perry	1827
2	AristotlePagaltzis	1828	.Bl -inset -offset indent
1	perry	1829
2	AristotlePagaltzis	1830	.It Em Tag
		1831	The tagged list (also called a tagged paragraph) is the most common type of list used in the Berkeley manuals.
1	perry	1832
2	AristotlePagaltzis	1833	.It Em Diag
		1834	Diag lists create section four diagnostic lists and are similar to inset lists except callable macros are ignored.
1	perry	1835
		1836	.It Em Hang
		1837	Hanged labels are a matter of taste.
2	AristotlePagaltzis	1838
1	perry	1839	.It Em Ohang
		1840	Overhanging labels are nice when space is constrained.
2	AristotlePagaltzis	1841
1	perry	1842	.It Em Inset
2	AristotlePagaltzis	1843	Inset labels are useful for controlling blocks of paragraphs and are valuable for converting
		1844
1	perry	1845	.Nm -mdoc
		1846	manuals to other formats.
2	AristotlePagaltzis	1847
1	perry	1848	.El
		1849	-column
		1850
2	AristotlePagaltzis	1851	This list type generates multiple columns. The number of columns and the width of each column is determined by the arguments to the -column list. Each .It argument is parsed to make a row, each column within the row is a separate argument separated by a tab or the .Ta macro.
1	perry	1852
		1853	The table:
		1854
		1855	__String Nroff Troff__
		1856
		1857	was produced by:
		1858
		1859	.Bl -column -offset indent String Nroff Troff
		1860	.It Sy String Ta Sy Nroff Ta Sy Troff
		1861	.It Li
2	AristotlePagaltzis	1862
1	perry	1863	Other keywords:
		1864	-width string
		1865
2	AristotlePagaltzis	1866	If string is a valid numeric expression (''witha scale indicator other than u''), use that valuefor indentation. The most useful scale indicatorsare m and n, specifying the so-called ''Em'' and ''Ensquare''. This is approximately the width of theletter m resp. the letter n of the current font(for nroff output, both scale indicators give thesame values). If string isn't a numericexpression, it is tested whether it is an -mdocmacro name, and the default offset value associ-ated with this macro is used. Finally, if alltests fail, the width of string (typeset witha fixed-width font) is taken as the offset.If a width is not specified for the tag list type,every time .It is invoked, an attempt is made to determine an appropriate width. If the first argument to .It is a callable macro, the default width for that macro will be used; otherwise, the default width of .No is used.
1	perry	1867
		1868	-xwidth
		1869	string
		1870
2	AristotlePagaltzis	1871	Interpret string and use the width of the result. Almost all lists in this document use this option.
1	perry	1872
		1873	Example:
		1874
		1875	.Bl -tag -xwidth
		1876	gives:
		1877	-test string
		1878
2	AristotlePagaltzis	1879	This is a longer sentence to show how the-xwidth flag works in combination with atag list.Note that the current state of -mdoc is saved before string is interpreted; afterwards, allvariables are restored again. However, boxes(used for enclosures) can't be saved in GNUtroff(1); as a consequence, arguments must always be ''balanced'' to avoid nasty errors. For example, do not write .Ao string but .Ao string Xc instead if you really need only an opening angle bracket.
1	perry	1880
		1881	-offset
		1882	string
		1883	If
		1884	string is indent, a default indent value (normally set to
		1885	6n, similar to the value used in .Dl or
		1886	.Bd) is used. If
		1887	string is a valid numeric expression instead (''with a
		1888	scale indicator other than u''), use that value for
		1889	indentation. The most useful scale indicators are m and n,
		1890	specifying the so-called ''Em'' and ''En square''.
		1891	This is approximately the width of the letter m resp. the
		1892	letter n of the current font (for nroff output, both scale
		1893	indicators give the same values). If
		1894	string isn't a numeric expression, it is tested whether it
		1895	is an -mdoc macro name, and the default offset value
		1896	associated with this macro is used. Finally, if all tests
		1897	fail, the width of
		1898	string (typeset with a fixed-width font) is taken as the
		1899	offset.
		1900
		1901	-compact
2	AristotlePagaltzis	1902	Suppress insertion of vertical space before the list and between list items.
1	perry	1903
2	AristotlePagaltzis	1904	!!!MISCELLANEOUS MACROS
1	perry	1905
2	AristotlePagaltzis	1906	Here a list of the remaining macros which do not fit well into one of the above sections. We couldn't find real examples for the following macros: .Me and .Ot. They are documented here for completeness - if you know how to use them properly please send a mail to [mailto:bug-groff@gnu.org] (including an example).
1	perry	1907
2	AristotlePagaltzis	1908	.Bt
1	perry	1909	prints
2	AristotlePagaltzis	1910	is currently in beta test.
1	perry	1911
2	AristotlePagaltzis	1912	It is neither callable nor parsed and takes no arguments.
1	perry	1913
		1914	.Fr
		1915
		1916	Usage: .Fr
		1917	function return value ...
		1918
2	AristotlePagaltzis	1919	Don't use this macro. It allows a break right before the return value (usually a single digit) which is bad typographical behaviour. Use ~ to tie the return value to the previous word.
1	perry	1920
		1921	.Hf
		1922	Use this macro to include a (header) file literally. It
		1923	first prints File: followed by the file name, then
		1924	the contents of
		1925	file.
		1926
		1927	Usage: .Hf
		1928	file
		1929
		1930	It is neither callable nor parsed.
		1931
		1932	.Lk
		1933	To be written.
		1934
		1935	.Me
2	AristotlePagaltzis	1936	Exact usage unknown. The documentation in the -mdoc source file describes it as a macro for ``menu entries''.
1	perry	1937
		1938	Its default width is 6n.
		1939
		1940	.Mt
		1941	To be written.
		1942
		1943	.Ot
2	AristotlePagaltzis	1944	Exact usage unknown. The documentation in the -mdoc source file describes it as ``old function type (fortran)''.
1	perry	1945
		1946	.Sm
		1947	Activate (toggle) space mode.
		1948
		1949	Usage: .Sm [[
		1950	on | off] ...
		1951
2	AristotlePagaltzis	1952	If space mode is off, no spaces between macro arguments are inserted. If called without a parameter (or if the next parameter is neither on nor off, .Sm toggles space mode.
1	perry	1953
2	AristotlePagaltzis	1954	.Ud
1	perry	1955	prints
2	AristotlePagaltzis	1956	currently under development.
1	perry	1957
2	AristotlePagaltzis	1958	It is neither callable nor parsed and takes no arguments.
1	perry	1959
2	AristotlePagaltzis	1960	!!!PREDEFINED STRINGS
1	perry	1961
		1962	The following strings are predefined:
		1963
		1964
		1965	__String Nroff Troff Meaning__
		1966
		1967
		1968	Rq '' '' right double quote
		1969	Lq `` `` left double quote
		1970	ua ^ upwards arrow
		1971	aa acute accent
		1972	ga grave accent
		1973	q
		1974	Pi pi greek pi
		1975	Ne != not equal
		1976	Le
		1977	Ge
		1978	Lt
		1979	Gt
		1980	Pm +- plus minus
		1981	If infinity infinity
		1982	Na ''NaN NaN'' not a number
		1983
		1984	Ba | | vertical bar
		1985
2	AristotlePagaltzis	1986	The names of the columns __Nroff__ and __Troff__ are a bit misleading; __Nroff__ shows the ASCII representation, while __Troff__ gives the best glyph form available. For example, a Unicode enabled TTY -device will have proper glyph representations for all strings, whereas the enhancement for a Latin1 TTY -device is only the plus-minus sign.
1	perry	1987
2	AristotlePagaltzis	1988	String names which consist of two characters can be written as ; string names which consist of one character can be written as x. A generic syntax for a string name of any length is [[xxx] (this is a GNU troff(1) extension).
1	perry	1989
2	AristotlePagaltzis	1990	!!!DIAGNOSTICS
1	perry	1991
2	AristotlePagaltzis	1992	The debugging macro .Db available in previous versions of -mdoc has been removed since GNU troff(1) provides better facilities to check parameters; additionally, many error and warning messages have been added to this macro package, making it both more robust and verbose.
1	perry	1993
2	AristotlePagaltzis	1994	The only remaining debugging macro is .Rd which yields a register dump of all global registers and strings. A normal user will never need it.
1	perry	1995
		1996	__FORMATTING WITH GROFF, TROFF, AND NROFF__
		1997
2	AristotlePagaltzis	1998	By default, the package inhibits page breaks, headers, and footers if displayed with a TTY device like latin1 or unicode to make the manual more efficient for viewing on-line. This behaviour can be changed (e.g. to create a hardcopy of the TTY output) by setting the register cR to zero while calling groff:
1	perry	1999
2	AristotlePagaltzis	2000	groff -Tlatin1 -rcR=0 -mdoc foo.man
1	perry	2001
2	AristotlePagaltzis	2002	For double-sided printing, set register D to 1:
1	perry	2003
2	AristotlePagaltzis	2004	groff -Tps -rD1 -mdoc foo.man
1	perry	2005
2	AristotlePagaltzis	2006	To change the document font size to 11pt or 12pt, set register S accordingly:
1	perry	2007
2	AristotlePagaltzis	2008	groff -Tdvi -rS11 -mdoc foo.man
1	perry	2009
2	AristotlePagaltzis	2010	Register S is ignored for TTY devices.
1	perry	2011
2	AristotlePagaltzis	2012	!!!FILES
1	perry	2013
2	AristotlePagaltzis	2014	; doc.tmac : The main manual macro package.
		2015	; mdoc.tmac : A wrapper file to call doc.tmac.
		2016	; mdoc/doc-common : Common strings, definitions, stuff related typographic output.
		2017	; mdoc/doc-nroff : Definitions used for a TTY output device.
		2018	; mdoc/doc-ditroff : Definitions used for all other devices.
		2019	; mdoc.local : Local additions and customizations.
		2020	; andoc.tmac : This file checks whether the -mdoc or the -man package should be used.
1	perry	2021
2	AristotlePagaltzis	2022	!!!SEE ALSO
1	perry	2023
2	AristotlePagaltzis	2024	groff(1) man(1) troff(1) groff_man(7)
1	perry	2025
2	AristotlePagaltzis	2026	!!!BUGS
1	perry	2027
2	AristotlePagaltzis	2028	Section 3f has not been added to the header routines.
1	perry	2029
		2030	.Nm font should be changed in __NAME__ section.
		2031
2	AristotlePagaltzis	2032	.Fn needs to have a check to prevent splitting up if the line length is too short. Occasionally it separates the last parenthesis, and sometimes looks ridiculous if a line is in fill mode.
1	perry	2033
2	AristotlePagaltzis	2034	The list and display macros do not do any keeps and certainly should be able to.
1	perry	2035
		2036	BSD April 10, 2001 1