EditPageHistoryDiffInfoLikePages

Annotated edit history of mdoc.samples(7) version 2, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	----
		2	__NAME__
		3
		4
		5	mdoc.samples - tutorial sampler for writing
		6	BSD manuals with -mdoc
		7	__SYNOPSIS__
		8
		9
		10	man mdoc.samples
		11	__DESCRIPTION__
		12
		13
		14	A tutorial sampler for writing BSD manual
		15	pages with the -mdoc macro package, a ''content''-based
		16	and ''domain''-based for- matting package for
2	StuartYeates	17	troff(1). Its predecessor, the man(7)
1	perry	18	package, addressed page layout leaving the manipulation of
		19	fonts and other typesetting details to the individual
		20	author. In -mdoc, page layout macros make up the ''page
		21	structure domain'' which consists of macros for titles,
		22	sec- tion headers, displays and lists. Essentially items
		23	which affect the physical position of text on a formatted
		24	page. In addition to the page structure domain, there are
		25	two more domains, the manual domain and the general text
		26	domain. The general text domain is defined as macros which
		27	perform tasks such as quoting or emphasizing pieces of text.
		28	The manual domain is defined as macros that are a subset of
		29	the day to day informal language used to describe commands,
		30	routines and related BSD files. Macros in the
		31	manual domain handle command names, command line arguments
		32	and options, function names, function parameters, pathnames,
		33	variables, cross ref- erences to other manual pages, and so
		34	on. These domain items have value for both the author and
		35	the future user of the manual page. It is hoped the
		36	consistency gained across the manual set will provide easier
		37	translation to future documentation tools.
		38
		39
		40	Throughout the UNIX manual pages, a manual entry is simply referred to as a man page, regardless of actual length and without sexist intention.
		41	__GETTING STARTED__
		42
		43
		44	Since a tutorial document is normally read when a person
		45	desires to use the material immediately, the assumption has
		46	been made that the user of this document may be impatient.
		47	The material presented in the remained of this document is
		48	outlined as follows:
		49	1.TROFF IDIOSYNCRASIES
		50
		51
2	StuartYeates	52	Macro Usage. Passing Space Characters in an Argument. Trailing Blank Space Characters (awarning). Escaping Special Characters.2.THE ANATOMY OF A MAN PAGE A manual page template.3.TITLE MACROS.4.INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS. What's in a name.... General Syntax.5.MANUAL DOMAIN Addresses. Author name. Arguments. Configuration Declarations (section fouronly). Command Modifier. Defined Variables. Errno's (Section two only). Environment Variables. Function Argument. Function Declaration. Flags. Functions (library routines). Function Types. Interactive Commands. Names. Options. Pathnames. Variables. Cross References.6.GENERAL TEXT DOMAIN ATPAGE STRUCTURE DOMAIN Section Headers. Paragraphs and Line Spacing. Keeps. Displays. Font Modes (Emphasis, Literal, andSymbolic). Lists and Columns.8.PREDEFINED STRINGS9.DIAGNOSTICS10.FORMATTING WITH GROFF, TROFF AND NROFF11.BUGS__TROFF IDIOSYNCRASIES__
1	perry	53
		54
		55	The -mdoc package attempts to simplify the process of writ-
		56	ing a man page. Theoretically, one should not have to learn
		57	the dirty details of troff(1) to use -mdoc;
		58	however, there are a few limitations which are unavoidable
		59	and best gotten out of the way. And, too, be forewarned,
		60	this package is ''not'' fast.
		61
		62
		63	__Macro Usage__
		64
		65
		66	As in troff(1), a macro is called by placing a
		67	. (dot char- acter) at the beginning of a line
		68	followed by the two char- acter name for the macro.
		69	Arguments may follow the macro separated by spaces. It is
		70	the dot character at the begin- ning of the line which
		71	causes troff(1) to interpret the next two
		72	characters as a macro name. To place a . (dot
		73	charac- ter) at the beginning of a line in some context
		74	other than a macro invocation, precede the . (dot)
		75	with the escape sequence. The
		76	translates literally to a zero width space, and is never
		77	displayed in the output.
		78
		79
		80	In general, troff(1) macros accept up to nine
		81	arguments, any extra arguments are ignored. Most macros in
		82	-mdoc accept nine arguments and, in limited cases, arguments
2	StuartYeates	83	may be continued or extended on the next line (See
1	perry	84	__Extensions__). A few macros handle quoted arguments
		85	(see __Passing Space Characters in an Argument__
		86	below).
		87
		88
		89	Most of the -mdoc general text domain and manual domain
		90	macros are special in that their argument lists are
		91	''parsed'' for callable macro names. This means an
		92	argument on the argument list which matches a general text
		93	or manual domain macro name and is determined to be callable
		94	will be executed or called when it is processed. In this
		95	case the argument, although the name of a macro, is not
		96	preceded by a . (dot). It is in this manner that
2	StuartYeates	97	many macros are nested; for example the option macro,
1	perry	98	.Op, may ''call'' the flag and argument macros,
		99	Fl and Ar, to specify an optional flag
2	StuartYeates	100	with an argument:
1	perry	101	[[-s bytes] is produced by .Op Fl s Ar bytes
		102
		103
		104	To prevent a two character string from being interpreted as a macro name, precede the string with the escape sequence :
		105
		106
		107	[[Fl s Ar bytes] is produced by .Op
		108
		109
		110	Here the strings Fl and Ar are not
		111	interpreted as macros. Macros whose argument lists are
		112	parsed for callable argu- ments are referred to as parsed
		113	and macros which may be called from an argument list are
		114	referred to as callable throughout this document and in the
		115	companion quick refer- ence manual mdoc(7). This is
		116	a technical ''faux pas'' as almost all of the macros in
		117	-mdoc are parsed, but as it was cumber- some to constantly
		118	refer to macros as being callable and being able to call
		119	other macros, the term parsed has been used.
		120
		121
		122	__Passing Space Characters in an Argument__
		123	Sometimes it is desirable to give as one argument a string
		124	containing one or more blank space characters. This may be
		125	necessary to defeat the nine argument limit or to specify
		126	arguments to macros which expect particular arrangement of
		127	items in the argument list. For example, the function macro
		128	.Fn expects the first argument to be the name of a
		129	function and any remaining arguments to be function
		130	parameters. As ANSI C stipulates the
		131	declaration of function parameters in the parenthesized
		132	parameter list, each parameter is guaran- teed to be at
		133	minimum a two word string. For example, int
		134	foo.
		135
		136
		137	There are two possible ways to pass an argument which con-
		138	tains an embedded space. ''Implementation note'':
		139	Unfortu- nately, the most convenient way of passing spaces
		140	in between quotes by reassigning individual arguments before
		141	parsing was fairly expensive speed wise and space wise to
		142	implement in all the macros for AT
		143	troff. It is not expensive for groff but
		144	for the sake of portability, has been limited to the
		145	following macros which need it the most:
		146
		147
		148	Cd
		149	Configuration declaration (section 4
		150	__SYNOPSIS__)
		151	Bl
		152	Begin list (for the width specifier).
		153	Em
		154	Emphasized text.
		155	Fn
		156	Functions (sections two and four).
		157	It
		158	List items.
		159	Li
		160	Literal text.
		161	Sy
		162	Symbolic text.
		163	%B
		164	Book titles.
		165	%J
		166	Journal names.
		167	%O
		168	Optional notes for a reference.
		169	%R
		170	Report title (in a reference).
		171	%T
		172	Title of article in a book or journal.
		173
		174
		175	One way of passing a string containing blank spaces is to
		176	use the hard or unpaddable space character \ , that
		177	is, a blank space preceded by the escape character
		178	\. This method may be used with any macro but has
		179	the side effect of inter- fering with the adjustment of text
		180	over the length of a line. Troff sees the hard
		181	space as if it were any other printable character and cannot
		182	split the string into blank or newline separated pieces as
		183	one would expect. The method is useful for strings which are
		184	not expected to overlap a line boundary. For
		185	example:
		186
		187
		188	fetch(char str)
		189	is created by .Fn fetch char\ str
		190
		191
		192	fetch(char str)
		193	can also be created by .Fn fetch char
		194	str
		195
		196
		197	If the \ or quotes were omitted, .Fn would
		198	see three argu- ments and the result would be:
		199
		200
		201	fetch(char, str)
		202
		203
		204	For an example of what happens when the parameter list over-
		205	laps a newline boundary, see the __BUGS__
		206	section.
		207
		208
		209	__Trailing Blank Space Characters__
		210	Troff can be confused by blank space characters at the
		211	end of a line. It is a wise preventive measure to globally
		212	remove all blank spaces from
		213	escape character. For example, string\
		214	.
		215
		216
		217	__Escaping Special Characters__
		218	Special characters like the newline character n,
		219	are han- dled by replacing the \ with e
		220	(e.g. en) to preserve the backslash.
		221
		222
		223	__THE ANATOMY OF A MAN PAGE__
		224
		225
		226	The body of a man page is easily constructed from a basic
		227	template found in the file
		228	/usr/share/misc/mdoc.template. Several example man
		229	pages can also be found in
		230	/usr/share/examples/mdoc.
		231
		232
		233	__A manual page template__
		234
		235
		236	.
		237	The first items in the template are the macros (.Dd, .Os, .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__.
		238
		239
		240	The remaining items in the template are section headers
		241	(.Sh); of which __NAME__, __SYNOPSIS__ and
		242	__DESCRIPTION__ are manda- tory. The headers are
		243	discussed in __PAGE STRUCTURE DOMAIN__, after
		244	presentation of __MANUAL DOMAIN__. Several content macros
		245	are used to demonstrate page layout macros; reading about
		246	content macros before page layout macros is
		247	recommended.
		248	__TITLE MACROS__
		249
		250
		251	The title macros are the first portion of the page structure
		252	domain, but are presented first and separate for someone who
		253	wishes to start writing a man page yesterday. Three header
		254	macros designate the document title or manual page title,
		255	the operating system, and the date of authorship. These
		256	macros are one called once at the very beginning of the doc-
		257	ument and are used to construct the headers and footers
		258	only.
		259	.Dt DOCUMENT_TITLE section# [[volume]
		260
		261
		262	The document title is the subject of the man page and must
		263	be in CAPITALS due to troff limitations. The
		264	section number may be 1, ..., 8, and if it is speci- fied,
		265	the volume title may be omitted. A volume title may be
		266	arbitrary or one of the following:
		267
		268
		269	AMD UNIX Ancestral Manual Documents
		270
		271
		272	SMM UNIX System Manager's Manual
		273
		274
		275	URM UNIX Reference Manual
		276
		277
		278	PRM UNIX Programmer's Manual
		279
		280
		281	The default volume labeling is URM for sections 1,
		282	6, and 7; SMM for section 8; PRM for
		283	sections 2, 3, 4, and 5.
		284	.Os operating_system release#
		285
		286
		287	The name of the operating system should be the common
		288	acronym, e.g. BSD or FreeBSD
		289	or ATT . The release should be the standard
		290	release nomenclature for the system specified, e.g. 4.3,
		291	4.3+Tahoe, V.3, V.4. Unrecognized arguments are displayed as
		292	given in the page footer. For instance, a typical footer
		293	might be:
		294
		295
		296	.Os BSD 4.3
		297
		298
		299	or .Os FreeBSD 2.2
		300
		301
		302	or for a locally produced set
		303
		304
		305	.Os CS Department
		306
		307
		308	The Berkeley default, .Os without an argument, has
		309	been defined as BSD in the site specific file
		310	/usr/share/tmac/mdoc/doc-common. It really should
		311	default to LOCAL . Note, if the .Os
		312	macro is not pre- sent, the bottom left corner of the page
		313	will be ugly.
		314
		315
		316	.Dd month day, year
		317	The date should be written formally:
		318
		319
		320	January 25, 1989
		321
		322
		323	__INTRODUCTION OF MANUAL AND GENERAL TEXT
		324	DOMAINS__
		325
		326
		327	__What's in a name...__
		328
		329
		330	The manual domain macro names are derived from the day to
		331	day informal language used to describe commands, subroutines
		332	and related files. Slightly different variations of this
		333	language are used to describe the three different aspects of
		334	writing a man page. First, there is the description of -mdoc
		335	macro request usage. Second is the description of a
		336	UNIX command ''with'' -mdoc macros and
		337	third, the description of a command to a user in the verbal
		338	sense; that is, discussion of a command in the text of a man
		339	page.
		340
		341
		342	In the first case, troff(1) macros are themselves a
		343	type of command; the general syntax for a troff command
		344	is:
		345
		346
		347	.Va argument1 argument2 ... argument9
		348
		349
		350	The .Va is a macro command or request, and anything
		351	follow- ing it is an argument to be processed. In the second
		352	case, the description of a UNIX command using
		353	the content macros is a bit more involved; a typical
		354	__SYNOPSIS__ command line might be displayed
		355	as:
		356
		357
		358	filter [[-flag] infile outfile
		359
		360
		361	Here, filter is the command name and the bracketed string
		362	-flag is a ''flag'' argument designated as optional by
		363	the option brackets. In -mdoc terms, infile and outfile are
		364	called ''arguments''. The macros which formatted the
		365	above example:
		366
		367
		368	.Nm filter
		369	.Op Fl flag
		370	.Ar infile outfile
		371	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 above might be referred to as ''operands'' or ''file arguments''. Some command line argument lists are quite long:
		372	make
		373
		374
		375	[[-eiknqrstv] [[-D variable] [[-d flags] [[-fmakefile] [[-I directory] [[-j max_jobs][[variable=value] [[target ...]Here one might talk about the command make and qualify theargument makefile, as an argument to the flag, -f, or dis-cuss the optional file operand target. In the verbal con-text, such detail can prevent confusion, however the -mdocpackage 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:
		376
		377
		378	.Nm make
		379	.Op Fl eiknqrstv
		380	.Op Fl D Ar variable
		381	.Op Fl d Ar flags
		382	.Op Fl f Ar makefile
		383	.Op Fl I Ar directory
		384	.Op Fl j Ar max_jobs
		385	.Op Ar variable=value
		386	.Bk -words
		387	.Op Ar target ...
		388	.Ek
		389	The .Bk and .Ek macros are explained in __Keeps__.
		390
		391
		392	__General Syntax__
		393
		394
		395	The manual domain and general text domain macros share a
		396	similar syntax with a few minor deviations: .Ar,
		397	.Fl, .Nm, and .Pa differ only
		398	when called without arguments; .Fn and .Xr
		399	impose an order on their argument lists and the .Op
		400	and .Fn macros have nesting limitations. All
		401	content macros are capable of recognizing and properly
		402	handling punctuation, provided each punctuation character is
		403	separated by a lead- ing space. If an request is
		404	given:
		405
		406
		407	.Li sptr, ptr),
		408
		409
		410	The result is:
		411
		412
		413	sptr, ptr),
		414
		415
		416	The punctuation is not recognized and all is output in the
		417	literal font. If the punctuation is separated by a leading
		418	white space:
		419
		420
		421	.Li sptr , ptr ) ,
		422
		423
		424	The result is:
		425
		426
		427	sptr, ptr),
		428
		429
		430	The punctuation is now recognized and is output in the
		431	default font distinguishing it from the strings in literal
		432	font.
		433
		434
		435	To remove the special meaning from a punctuation character
		436	escape it with . Troff is limited as
		437	a macro language, and has difficulty when presented with a
		438	string containing a member of the mathematical, logical or
		439	quotation set:
		440
		441
		442	{+,-,/,,%,
		443	The problem is that troff may assume it is supposed to actu- ally 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.
		444	__MANUAL DOMAIN__
		445
		446
		447	__Address Macro__
		448
		449
		450	The address macro identifies an address construct of the
		451	form addr1[[,addr2[[,addr3]].
		452
		453
		454	Usage: .Ad address ...
		455	.Ad addr1
		456
		457
		458	''addr1''
		459	.Ad addr1 .''
		460	addr1''.
		461	.Ad addr1 , file2''
		462	addr1'', ''file2''
		463	.Ad f1 , f2 , f3 :''
		464	f1'', ''f2'', ''f3'':
		465	.Ad addr ) ) ,''
		466	addr'')),
		467
		468
		469	It is an error to call .Ad without arguments.
		470	.Ad is callable by other macros and is
		471	parsed.
		472
		473
		474	__Author Name__
		475	The .An macro is used to specify the name of the
		476	author of the item being documented, or the name of the
		477	author of the actual manual page. Any remaining arguments
		478	after the name information are assumed to be
		479	punctuation.
		480
		481
		482	Usage: .An author_name
		483	.An Joe Author Joe Author
		484	.An Joe Author ,
		485	Joe Author,
		486	.An Joe Author Aq nobody@FreeBSD.ORG
		487	Joe Author nobody@FreeBSD.ORG
		488	.An Joe Author ) ) ,
		489	Joe Author)),
		490
		491
		492	The .An macro is parsed and is callable. It is an
		493	error to call .An without any
		494	arguments.
		495
		496
		497	__Argument Macro__
		498	The .Ar argument macro may be used whenever a
		499	command line argument is referenced.
		500
		501
		502	Usage: .Ar argument ...
		503	.Ar
		504	file ...
		505	.Ar file1
		506	file1
		507	.Ar file1 .
		508	file1.
		509	.Ar file1 file2
		510	file1 file2
		511	.Ar f1 f2 f3 :
		512	f1 f2 f3:
		513	.Ar file ) ) ,
		514	file)),
		515
		516
		517	If .Ar is called without arguments file ... is
		518	assumed. The .Ar macro is parsed and is
		519	callable.
		520
		521
		522	__Configuration Declaration (section four only)__
		523	The .Cd macro is used to demonstrate a
		524	config(8) declaration for a device interface in a
		525	section four manual. This macro accepts quoted arguments
		526	(double quotes only).
		527
		528
		529	device le0 at scode?
		530	produced by: .Cd device le0 at scode?.
		531
		532
		533	__Command Modifier__
		534	The command modifier is identical to the .Fl (flag)
		535	command with the exception the .Cm macro does not
		536	assert a dash in front of every argument. Traditionally
		537	flags are marked by the preceding dash, some commands or
		538	subsets of commands do not use them. Command modifiers may
		539	also be specified in conjunction with interactive commands
		540	such as editor com- mands. See __Flags__.
		541
		542
		543	__Defined Variables__
		544	A variable which is defined in an include file is specified
		545	by the macro .Dv.
		546
		547
		548	Usage: .Dv defined_variable ...
		549	.Dv MAXHOSTNAMELEN
		550	MAXHOSTNAMELEN
		551	.Dv TIOCGPGRP )
		552	TIOCGPGRP)
		553
		554
		555	It is an error to call .Dv without arguments.
		556	.Dv is parsed and is callable.
		557
		558
		559	__Errno's (Section two only)__
		560	The .Er errno macro specifies the error return
		561	value for section two library routines. The second example
		562	below shows .Er used with the .Bq general
		563	text domain macro, as it would be used in a section two
		564	manual page.
		565
		566
		567	Usage: .Er ERRNOTYPE ...
		568	.Er ENOENT
		569	ENOENT
		570	.Er ENOENT ) ;
		571	ENOENT);
		572	.Bq Er ENOTDIR
		573	[[ENOTDIR]
		574
		575
		576	It is an error to call .Er without arguments. The
		577	.Er macro is parsed and is callable.
		578
		579
		580	__Environment Variables__
		581	The .Ev macro specifies an environment
		582	variable.
		583
		584
		585	Usage: .Ev argument ...
		586	.Ev DISPLAY
		587	DISPLAY
		588	.Ev PATH .
		589	PATH.
		590	.Ev PRINTER ) ) ,
		591	PRINTER)),
		592
		593
		594	It is an error to call .Ev without arguments. The
		595	.Ev macro is parsed and is callable.
		596
		597
		598	__Function Argument__
		599	The .Fa macro is used to refer to function
		600	arguments (param- eters) outside of the __SYNOPSIS__
		601	section of the manual or inside the __SYNOPSIS__ section
		602	should a parameter list be too long for the .Fn
		603	macro and the enclosure macros .Fo and .Fc
		604	must be used. .Fa may also be used to refer to
		605	structure members.
		606
		607
		608	Usage: .Fa function_argument ...
		609	.Fa d_namlen ) ) ,
		610	d_namlen)),
		611	.Fa iov_len
		612	iov_len
		613
		614
		615	It is an error to call .Fa without arguments.
		616	.Fa is parsed and is callable.
		617
		618
		619	__Function Declaration__
		620	The .Fd macro is used in the __SYNOPSIS__
		621	section with section two or three functions. The
		622	.Fd macro does not call other macros and is not
		623	callable by other macros.
		624
		625
		626	Usage: .Fd include_file (or defined
		627	variable)
		628
		629
		630	In the __SYNOPSIS__ section a .Fd request causes
		631	a line break if a function has already been presented and a
		632	break has not occurred. This leaves a nice vertical space in
		633	between the previous function call and the declaration for
		634	the next function.
		635
		636
		637	__Flags__
		638	The .Fl macro handles command line flags. It
		639	prepends a dash, -, to the flag. For interactive
		640	command flags, which are not prepended with a dash, the
		641	.Cm (command modifier) macro is identical, but
		642	without the dash.
		643
		644
		645	Usage: .Fl argument ...
		646	.Fl
		647	-
		648	.Fl cfv
		649	-cfv
		650	.Fl cfv .
		651	-cfv.
		652	.Fl s v t
		653	-s -v -t
		654	.Fl - ,
		655	--,
		656	.Fl xyz ) ,
		657	-xyz),
		658
		659
		660	The .Fl macro without any arguments results in a
		661	dash repre- senting stdin/stdout. Note that giving
		662	.Fl a single dash, will result in two dashes. The
		663	.Fl macro is parsed and is callable.
		664
		665
		666	__Functions (library routines)__
		667	The .Fn macro is modeled on ANSI C conventions.
		668
		669
		670	Usage: .Fn [[type] function [[[[type] parameters ... ]
		671	.Fn getchar
		672	getchar()
		673
		674
		675	.Fn strlen ) ,
		676	strlen()),
		677	.Fn int align const char sptrs,
		678	int align(const char sptrs),
		679
		680
		681	It is an error to call .Fn without any arguments. The .Fn macro is parsed and is callable, note that any call to another macro signals the end of the .Fn call (it will close-parenthesis at that point).
		682
		683
		684	For functions that have more than eight parameters (and this
		685	is rare), the macros .Fo (function open) and
		686	.Fc (function close) may be used with .Fa
		687	(function argument) to get around the limitation. For
		688	example:
		689
		690
		691	.Fo
		692	Produces:
		693	int res_mkquery(int op
		694	, char dname, int class, int type,char data, int datalen, struct rrec newrr, char buf,int buflen)
		695	The .Fo and .Fc macros are parsed and
		696	are callable. In the __SYNOPSIS__ section, the function
		697	will always begin at the beginning of line. If there is more
		698	than one function pre- sented in the __SYNOPSIS__ section
		699	and a function type has not been given, a line break will
		700	occur, leaving a nice vertical space between the current
		701	function name and the one prior. At the moment, .Fn
		702	does not check its word boundaries against troff line
		703	lengths and may split across a newline ungracefully. This
		704	will be fixed in the near future.
		705
		706
		707	__Function Type__
		708	This macro is intended for the __SYNOPSIS__ section.
		709	It may be used anywhere else in the man page without
		710	problems, but its main purpose is to present the function
		711	type in kernel nor- mal form for the __SYNOPSIS__ of
		712	sections two and three (it causes a line break allowing the
		713	function name to appear on the next line).
		714
		715
		716	Usage: .Ft type ...
		717	.Ft struct stat
		718
		719
		720	struct stat
		721
		722
		723	The .Ft request is not callable by other
		724	macros.
		725
		726
		727	__Interactive Commands__
		728	The .Ic macro designates an interactive or internal
		729	command.
		730
		731
		732	Usage: .Ic argument ...
		733	.Ic :wq :wq
		734	.Ic do while {...}
		735	do while {...}
		736	.Ic setenv , unsetenv
		737	setenv, unsetenv
		738
		739
		740	It is an error to call .Ic without arguments. The
		741	.Ic macro is parsed and is callable.
		742
		743
		744	__Name Macro__
		745	The .Nm macro is used for the document title or
		746	subject name. It has the peculiarity of remembering the
		747	first argu- ment it was called with, which should always be
		748	the subject name of the page. When called without arguments,
		749	.Nm regur- gitates this initial name for the sole
		750	purpose of making less work for the author. Note: a section
		751	two or three doc- ument function name is addressed with the
		752	.Nm in the __NAME__ section, and with
		753	.Fn in the __SYNOPSIS__ and remaining sec-
		754	tions. For interactive commands, such as the while
		755	command keyword in csh(1), the .Ic macro
		756	should be used. While the .Ic is nearly identical
		757	to .Nm, it can not recall the first argument it was
		758	invoked with.
		759
		760
		761	Usage: .Nm argument ...
		762	.Nm mdoc.sample
		763	mdoc.sample
		764	.Nm -mdoc
		765	-mdoc.
		766	.Nm foo ) ) ,
		767	foo)),
		768	.Nm
		769	mdoc.samples
		770
		771
		772	The .Nm macro is parsed and is
		773	callable.
		774
		775
		776	__Options__
		777	The .Op macro places option brackets around the any
		778	remain- ing arguments on the command line, and places any
		779	trailing punctuation outside the brackets. The macros
		780	.Oc and .Oo may be used across one or more
		781	lines.
		782
		783
		784	Usage: .Op options ...
		785	.Op [[]
		786	.Op Fl k
		787	[[-k]
		788	.Op Fl k ) .
		789	[[-k]).
		790	.Op Fl k Ar kookfile
		791	[[-k kookfile]
		792	.Op Fl k Ar kookfile ,
		793	[[-k kookfile],
		794	.Op Ar objfil Op Ar corfil
		795	[[objfil [[corfil]]
		796	.Op Fl c Ar objfil Op Ar corfil ,
		797	[[-c objfil [[corfil]],
		798	.Op word1 word2
		799	[[word1 word2]
		800
		801
		802	The .Oc and .Oo macros:
		803
		804
		805	.Oo
		806	.Op Fl k Ar kilobytes
		807	.Op Fl i Ar interval
		808	.Op Fl c Ar count
		809	.Oc
		810	Produce: [[
		811	[[-k kilobytes]
		812	[[-i interval]
		813	[[-c count]
		814	]The macros .Op
		815	, .Oc and .Oo are parsed and are
		816	callable.
		817	__Pathnames__
		818	The .Pa macro formats path or file names.
		819	Usage: .Pa pathname
		820	.Pa /usr/share /usr/share
		821	.Pa /tmp/fooXXXXX ) .
		822	/tmp/fooXXXXX).
		823	The .Pa macro is parsed and is callable.
		824	__Variables__
		825	Generic variable reference:
		826	Usage: .Va variable ...
		827	.Va count''
		828	count''
		829	.Va settimer,''
		830	settimer'',
		831	.Va int prt ) :''
		832	int prt''):
		833	.Va char s ] ) ) ,''
		834	char s''])),
		835	It is an error to call .Va without any
		836	arguments. The .Va macro is parsed and is
		837	callable.
		838	__Manual Page Cross References__
		839	The .Xr macro expects the first argument to be a
		840	manual page name, and the second argument, if it exists, to
		841	be either a section page number or punctuation. Any
		842	remaining arguments are assumed to be punctuation.
		843	Usage: .Xr man_page [[1,...,8]
		844	.Xr mdoc
		845	mdoc
		846	.Xr mdoc ,
		847	mdoc,
		848	.Xr mdoc 7
		849	mdoc(7)
		850	.Xr mdoc 7 ) ) ,
		851	mdoc(7))),
		852	The .Xr macro is parsed and is callable. It is
		853	an error to call .Xr without any arguments.
		854	__GENERAL TEXT DOMAIN__
		855
		856
		857	__AT__
		858
		859
		860	Usage: .At [[v6 | v7 | 32v | V.1 | V.4] ...
		861	.At
		862
		863
		864	AT
		865	.At v6 .
		866	Version 6 AT .
		867
		868
		869	The .At macro is ''not'' parsed and ''not''
		870	callable. It accepts at most two arguments.
		871
		872
		873	__BSD Macro__
		874	Usage: .Bx [[Version/release] ...
		875	.Bx
		876	BSD
		877	.Bx 4.3 .
		878	4.3 BSD .
		879
		880
		881	The .Bx macro is parsed and is
		882	callable.
		883
		884
		885	__FreeBSD Macro__
		886
		887
		888	Usage: .Fx Version.release ...
		889	.Fx 2.2 .
		890
		891
		892	FreeBSD 2.2.
		893
		894
		895	The .Fx macro is ''not'' parsed and ''not''
		896	callable. It accepts at most two arguments.
		897
		898
		899	__UNIX Macro__
		900	Usage: .Ux ...
		901	.Ux
		902	UNIX
		903
		904
		905	The .Ux macro is parsed and is
		906	callable.
		907
		908
		909	__Enclosure and Quoting Macros__
		910	The concept of enclosure is similar to quoting. The object
		911	being to enclose one or more strings between a pair of char-
		912	acters like quotes or parentheses. The terms quoting and
		913	enclosure are used interchangeably throughout this document.
		914	Most of the one line enclosure macros end in small letter
		915	q to give a hint of quoting, but there are a few
		916	irregulari- ties. For each enclosure macro there is also a
		917	pair of open and close macros which end in small letters
		918	o and c respec- tively. These can be used
		919	across one or more lines of text and while they have nesting
		920	limitations, the one line quote macros can be used inside of
		921	them.
		922
		923
		924	'' Quote Close Open Function Result
		925	''.Aq .Ac .Ao Angle Bracket Enclosure
		926	''
		927
		928
		929	Except for the irregular macros noted below, all of the
		930	quoting macros are parsed and callable. All handle punctua-
		931	tion properly, as long as it is presented one character at a
		932	time and separated by spaces. The quoting macros examine
		933	opening and closing punctuation to determine whether it
		934	comes before or after the enclosing string. This makes some
		935	nesting possible.
		936	.Ec
		937	,
		938	.Eo
		939
		940
		941	These macros expect the first argument to be the opening and
		942	closing strings respectively.
		943
		944
		945	.Ql
		946	The quoted literal macro behaves differently for troff than nroff. If formatted with nroff, a quoted literal is always quoted. If formatted with troff, an item is only quoted if the width of the item is less than three constant width characters. This is to make short strings more visible where the font change to literal (constant width) is less noticeable.
		947
		948
		949	.Pf
		950	The prefix macro is not callable, but it is
		951	parsed:
		952
		953
		954	.Pf ( Fa name2
		955	becomes (name2.
		956
		957
		958	The .Ns (no space) macro performs the analogous
		959	suffix function.
		960
		961
		962	Examples of quoting:
		963	.Aq
		964	.Aq Ar ctype.h ) ,
		965	ctype.h),
		966	.Bq
		967	[[]
		968	.Bq Em Greek , French .
		969	[[''Greek'', ''French''].
		970	.Dq
		971	``''
		972	.Dq string abc .
		973	``string abc''.
		974	.Dq ^[[A-Z]
		975	``^[[A-Z]''
		976	.Ql man mdoc
		977	man mdoc
		978	.Qq
		979	.Qq string ) ,
		980	string),
		981	.Qq string Ns ),
		982	string),
		983	.Sq
		984	.Sq string
		985	string
		986
		987
		988	For a good example of nested enclosure macros, see the
		989	.Op option macro. It was created from the same
		990	underlying enclosure macros as those presented in the list
		991	above. The .Xo and .Xc extended argument
		992	list macros were also built from the same underlying
		993	routines and are a good example of -mdoc macro usage at its
		994	worst.
		995
		996
		997	__No-Op or Normal Text Macro__
		998	The macro .No is a hack for words in a macro
		999	command line which should ''not'' be formatted and
		1000	follows the conventional syntax for content
		1001	macros.
		1002
		1003
		1004	Space Macro
		1005	The .Ns macro eliminates unwanted spaces in between
		1006	macro requests. It is useful for old style argument lists
		1007	where there is no space between the flag and
		1008	argument:
		1009
		1010
		1011	.Op Fl I Ns Ar directory produces
		1012	[[-Idirectory]
		1013
		1014
		1015	Note: the .Ns macro always invokes the .No
		1016	macro after elim- inating the space unless another macro
		1017	name follows it. The macro .Ns is parsed and is
		1018	callable.
		1019
		1020
		1021	__Section Cross References__
		1022	The .Sx macro designates a reference to a section
		1023	header within the same document. It is parsed and is
		1024	callable.
		1025
		1026
		1027	.Sx FILES__
		1028	FILES__
		1029
		1030
		1031	__References and Citations__
		1032	The following macros make a modest attempt to handle refer-
		1033	ences. At best, the macros make it convenient to manually
		1034	drop in a subset of refer style references.
		1035
		1036
		1037	.Rs
		1038	Reference Start. Causes a line break and begins collection
		1039	of reference information until the reference end macro is
		1040	read.
		1041	.Re
		1042	Reference End. The reference is printed.
		1043	.%A
		1044	Reference author name, one name per invocation.
		1045	.%B
		1046	Book title.
		1047	.%C
		1048	City/place.
		1049	.%D
		1050	Date.
		1051	.%J
		1052	Journal name.
		1053	.%N
		1054	Issue number.
		1055	.%O
		1056	Optional information.
		1057	.%P
		1058	Page number.
		1059	.%R
		1060	Report name.
		1061	.%T
		1062	Title of article.
		1063	.%V
		1064	Volume(s).
		1065
		1066
		1067	The macros beginning with % are not callable, and
		1068	are parsed only for the trade name macro which returns to
		1069	its caller. (And not very predictably at the moment either.)
		1070	The pur- pose is to allow trade names to be pretty printed
		1071	in troff/ditroff output.
		1072
		1073
		1074	__Return Values__
		1075	The .Rv macro generates text for use in the
		1076	__RETURN VALUES__ section.
		1077
		1078
		1079	Usage: .Rv [[-std function]
		1080
		1081
		1082	.Rv -std atexit will generate the following
		1083	text:
		1084
		1085
		1086	The atexit() function returns the value 0 if successful;
		1087	otherwise the value -1 is returned and the global variable
		1088	''errno'' is set to indicate the error.
		1089
		1090
		1091	The -std option is valid only for manual page sections 2 and
		1092	3.
		1093
		1094
		1095	__Trade Names (or Acronyms and Type Names)__
		1096	The trade name macro is generally a small caps macro for all
		1097	upper case words longer than two characters.
		1098
		1099
		1100	Usage: .Tn symbol ...
		1101	.Tn DEC
		1102	DEC
		1103	.Tn ASCII
		1104	ASCII
		1105
		1106
		1107	The .Tn macro is parsed and is callable by other
		1108	macros.
		1109
		1110
		1111	__Extended Arguments__
		1112	The .Xo and .Xc macros allow one to extend
		1113	an argument list on a macro boundary. Argument lists cannot
		1114	be extended within a macro which expects all of its
		1115	arguments on one line such as .Op.
		1116
		1117
		1118	Here is an example of .Xo using the space mode
		1119	macro to turn spacing off:
		1120
		1121
		1122	.Sm off
		1123	.It Xo Sy I Ar operation
		1124	.No en Ar count No en
		1125	.Xc
		1126	.Sm on
		1127	Produces
		1128	__ I__operationncountn
		1129
		1130
		1131	Another one:
		1132
		1133
		1134	.Sm off
		1135	.It Cm S No / Ar old_pattern Xo
		1136	.No / Ar new_pattern
		1137	.No / Op Cm g
		1138	.Xc
		1139	.Sm on
		1140	Produces
		1141	S/old_pattern /new_pattern
		1142	/[[g]
		1143
		1144
		1145	Another example of .Xo and using enclosure macros:
		1146	Test the value of an variable.
		1147
		1148
		1149	.It Xo
		1150	.Ic .ifndef
		1151	.Oo
		1152	Produces
		1153	.ifndef
		1154	[[ !]variable
		1155	[[operator variable ...]
		1156
		1157
		1158	All of the above examples have used the .Xo macro
		1159	on the argument list of the .It (list-item) macro.
		1160	The extend macros are not used very often, and when they are
		1161	it is usu- ally to extend the list-item argument list.
		1162	Unfortunately, this is also where the extend macros are the
		1163	most finicky. In the first two examples, spacing was turned
		1164	off; in the third, spacing was desired in part of the output
		1165	but not all of it. To make these macros work in this
		1166	situation make sure the .Xo and .Xc macros
		1167	are placed as shown in the third example. If the
		1168	.Xo macro is not alone on the .It argument
		1169	list, spacing will be unpredictable. The .Ns (no
		1170	space macro) must not occur as the first or last macro on a
		1171	line in this situation. Out of 900 manual pages (about 1500
		1172	actual pages) currently released with BSD
		1173	only fifteen use the .Xo macro.
		1174	__PAGE STRUCTURE DOMAIN__
		1175
		1176
		1177	__Section Headers__
		1178
		1179
		1180	The first three .Sh section header macros list
		1181	below are required in every man page. The remaining section
		1182	headers are recommended at the discretion of the author
		1183	writing the manual page. The .Sh macro can take up
		1184	to nine arguments. It is parsed and but is not
		1185	callable.
		1186	.Sh NAME The .Sh NAME
		1187	macro is mandatory. If not speci- fied, the headers,
		1188	footers and page layout defaults will not be set and things
		1189	will be rather unpleasant. The __NAME__ section consists
		1190	of at least three items. The first is the .Nm name
		1191	macro naming the subject of the man page. The second is the
		1192	Name Description macro, .Nd, which separates the
		1193	subject name from the third item, which is the description.
		1194	The descrip- tion should be the most terse and lucid possi-
		1195	ble, as the space available is small.
		1196
		1197
		1198	.Sh SYNOPSIS
		1199	The __SYNOPSIS__ section describes the typical usage of the subject of a man page. The macros required are either .Nm, .Cd, .Fn, (and possibly .Fo, .Fc, .Fd, .Ft macros). The func- tion name macro .Fn is required for manual page sections 2 and 3, the command and general name macro .Nm is required for sections 1, 5, 6, 7, 8. Section 4 manuals require a .Nm, .Fd or a .Cd configuration device usage macro. Several other macros may be necessary to produce the synopsis line as shown below:
		1200
		1201
		1202	cat [[-benstuv] [[-] file ...
		1203
		1204
		1205	The following macros were used:
		1206
		1207
		1208	.Nm cat
		1209
		1210
		1211	.Op Fl benstuv
		1212
		1213
		1214	.Op Fl
		1215
		1216
		1217	.Ar
		1218
		1219
		1220	__Note__: The macros .Op, .Fl, and
		1221	.Ar recognize the pipe bar character |, so a
		1222	command line such as:
		1223
		1224
		1225	.Op Fl a | Fl b
		1226
		1227
		1228	will not go orbital. Troff normally interprets a |
		1229	as a special operator. See __PREDEFINED STRINGS__ for a
		1230	usable | character in other situ- ations.
		1231	.Sh DESCRIPTION
		1232
		1233
		1234	In most cases the first text in the __DESCRIPTION__section is a brief paragraph on the command,function or file, followed by a lexical list ofoptions and respective explanations. To createsuch a list, the .Bl begin-list, .It list-item and .El end-list macros are used (see __Lists and Columns__ below).
		1235
		1236
		1237	The following .Sh section headers are part of the
		1238	preferred manual page layout and must be used appropriately
		1239	to main- tain consistency. They are listed in the order in
		1240	which they would be used.
		1241
		1242
		1243	.Sh ENVIRONMENT
		1244	The __ENVIRONMENT__ section should reveal any related
		1245	environment variables and clues to their behavior and/or
		1246	usage.
		1247
		1248
		1249	.Sh EXAMPLES
		1250	There are several ways to create examples. See the
		1251	__EXAMPLES__ section below for details.
		1252
		1253
		1254	.Sh FILES
		1255	Files which are used or created by the man page subject
		1256	should be listed via the .Pa macro in the
		1257	__FILES__ section.
		1258
		1259
		1260	.Sh SEE ALSO
		1261	References to other material on the man page topic and cross
		1262	references to other relevant man pages should be placed in
		1263	the __SEE ALSO__ section. Cross references are specified
		1264	using the .Xr macro. Cross references in the __SEE
		1265	ALSO__ section should be sorted by section number, and
		1266	then placed in alpha- betical order and comma separated. For
		1267	example:
		1268
		1269
		1270	ls(1), ps(1), group(5),
		1271	passwd(5).
		1272
		1273
		1274	At this time refer(1) style references are not
		1275	accommodated.
		1276
		1277
		1278	.Sh CONFORMING TO
		1279	If the command, library function or file adheres to a
		1280	specific implementation such as IEEE Std
		1281	1003.2 (`` POSIX .2'') or ANSI
		1282	X3.159-1989 (`` ANSI C '') this should be
		1283	noted here. If the command does not adhere to any standard,
		1284	its history should be noted in the __HISTORY__
		1285	section.
		1286
		1287
		1288	.Sh HISTORY
		1289	Any command which does not adhere to any specific standards
		1290	should be outlined historically in this
		1291	section.
		1292
		1293
		1294	.Sh AUTHORS
		1295	Credits, if need be, should be placed here.
		1296
		1297
		1298	.Sh DIAGNOSTICS
		1299	Diagnostics from a command should be placed in this
		1300	section.
		1301
		1302
		1303	.Sh ERRORS
		1304	Specific error handling, especially from library functions
		1305	(man page sections 2 and 3) should go here. The .Er
		1306	macro is used to specify an errno.
		1307
		1308
		1309	.Sh BUGS
		1310	Blatant problems with the topic go here...
		1311
		1312
		1313	User specified .Sh sections may be added, for
		1314	example, this section was set with:
		1315
		1316
		1317	.Sh PAGE STRUCTURE DOMAIN
		1318
		1319
		1320	__Paragraphs and Line Spacing.__
		1321	.Pp The .Pp
		1322	paragraph command may be used to specify a line space
		1323	where necessary. The macro is not neces- sary after a
		1324	.Sh or .Ss macro or before a .Bl
		1325	macro. (The .Bl macro asserts a vertical distance
		1326	unless the -compact flag is given).
		1327
		1328
		1329	__Keeps__
		1330	The only keep that is implemented at this time is for words. The macros are .Bk (begin-keep) and .Ek (end-keep). The only option that .Bk accepts is -words and is useful for preventing line breaks in the middle of options. In the example for the make command line arguments (see __What's in a name__), the keep prevented nroff from placing up the flag and the argument on separate lines. (Actually, the option macro used to prevent this from occurring, but was dropped when the decision (religious) was made to force right justified margins in troff as options in general look atrocious when spread across a sparse line. More work needs to be done with the keep macros, a -line option needs to be added.)
		1331
		1332
		1333	__Examples and Displays__
		1334	There are five types of displays, a quickie one line
		1335	indented display .D1, a quickie one line literal
		1336	display .Dl, and a block literal, block filled and
		1337	block ragged which use the .Bd begin-display and
		1338	.Ed end-display macros.
		1339
		1340
		1341	.D1 (D-one) Display one line of indented text. This
		1342	macro is parsed, but it is not callable.
		1343
		1344
		1345	-ldghfstru
		1346
		1347
		1348	The above was produced by: .Dl
		1349	-ldghfstru.
		1350
		1351
		1352	.Dl
		1353	(D-ell) Display one line of indented ''literal'' text.
		1354	The .Dl example macro has been used throughout this
		1355	file. It allows the indent (display) of one line of text.
		1356	Its default font is set to constant width (lit- eral)
		1357	however it is parsed and will recognized other macros. It is
		1358	not callable however.
		1359
		1360
		1361	% ls -ldg /usr/local/bin
		1362
		1363
		1364	The above was produced by .Dl % ls -ldg
		1365	/usr/local/bin.
		1366
		1367
		1368	.Bd
		1369	Begin-display. The .Bd display must be ended with
		1370	the .Ed macro. Displays may be nested within
		1371	displays and lists. .Bd has the following
		1372	syntax:
		1373
		1374
		1375	.Bd display-type [[-offset offset_value]
		1376	[[-compact]
		1377
		1378
		1379	The display-type must be one of the following four types and
		1380	may have an offset specifier for indenta- tion:
		1381	.Bd.
		1382
		1383
		1384	-ragged Display a block of text as typed, right (and left)
		1385	margin edges are left ragged.
		1386	-filled
		1387	Display a filled (formatted) block. The block of text is
		1388	formatted (the edges are filled - not left unjusti-
		1389	fied).
		1390	-literal
		1391	Display a literal block, useful for source code or simple
		1392	tabbed or spaced text.
		1393	-file file_name
		1394	The file name following the -file flag is read and
		1395	displayed. Literal mode is asserted and tabs are set at 8
		1396	constant width character intervals, however any
		1397	troff/-mdoc commands in file will be processed.
		1398	-offset string
		1399	If -offset is specified with one of the following strings,
		1400	the string is interpreted to indicate the level of
		1401	indentation for the forthcoming block of text:
		1402
		1403
		1404	left
		1405	Align block on the current left margin, this is the default
		1406	mode of .Bd.
		1407	center
		1408	Supposedly center the block. At this time unfortunately, the
		1409	block merely gets left aligned about an imaginary center
		1410	margin.
		1411	indent
		1412	Indents by one default indent value or tab. The default
		1413	indent value is also used for the .D1 dis- play so
		1414	one is guaranteed the two types of displays will line up.
		1415	This indent is normally set to 6n or about two thirds of an
		1416	inch (six constant width characters).
		1417	indent-two
		1418	Indents two times the default indent value.
		1419	right
		1420	This ''left'' aligns the block about two inches from the
		1421	right side of the page. This macro needs work and perhaps
		1422	may never do the right thing by troff.
		1423
		1424
		1425	.Ed
		1426	End-display.
		1427
		1428
		1429	__Font Modes__
		1430	There are five macros for changing the appearance of the
		1431	manual page text:
		1432
		1433
		1434	.Em Text may be stressed or emphasized with the .Em
		1435	macro. The usual font for emphasis is italic.
		1436
		1437
		1438	Usage: .Em argument ...
		1439	.Em does not''
		1440	does not''
		1441	.Em exceed 1024 .''
		1442	exceed 1024''.
		1443	.Em vide infra ) ) ,''
		1444	vide infra'')),
		1445
		1446
		1447	The .Em macro is parsed and is callable. It is an
		1448	error to call .Em without arguments.
		1449
		1450
		1451	.Li
		1452	The .Li literal macro may be used for special
		1453	charac- ters, variable constants, anything which should be
		1454	displayed as it would be typed.
		1455
		1456
		1457	Usage: .Li argument ...
		1458	.Li en
		1459	n
		1460	.Li M1 M2 M3 ;
		1461	M1 M2 M3;
		1462	.Li cntrl-D ) ,
		1463	cntrl-D),
		1464	.Li 1024 ...
		1465	1024 ...
		1466
		1467
		1468	The .Li macro is parsed and is
		1469	callable.
		1470
		1471
		1472	.Sy
		1473	The symbolic emphasis macro is generally a boldface macro in
		1474	either the symbolic sense or the traditional English
		1475	usage.
		1476
		1477
		1478	Usage: .Sy symbol ...
		1479	.Sy Important Notice__
		1480	Important Notice__
		1481
		1482
		1483	The .Sy macro is parsed and is callable. Arguments
		1484	to .Sy may be quoted.
		1485
		1486
		1487	.Bf
		1488	Begin font mode. The .Bf font mode must be ended
		1489	with the .Ef macro. Font modes may be nested within
		1490	other font modes. .Bf has the following
		1491	syntax:
		1492
		1493
		1494	.Bf font-mode
		1495
		1496
		1497	The font-mode must be one of the following three types:
		1498	.Bf.
		1499
		1500
		1501	__Em__ | -emphasis Same as if the .Em macro was
		1502	used for the entire block of text.__
		1503	Li__ | -literal
		1504	Same as if the .Li macro was used for the entire
		1505	block of text.__
		1506	Sy__ | -symbolic
		1507	Same as if the .Sy macro was used for the entire
		1508	block of text.
		1509
		1510
		1511	.Ef
		1512	End font mode.
		1513
		1514
		1515	__Tagged Lists and Columns__
		1516	There are several types of lists which may be initiated with
		1517	the .Bl begin-list macro. Items within the list are
		1518	speci- fied with the .It item macro and each list
		1519	must end with the .El macro. Lists may be nested
		1520	within themselves and within displays. Columns may be used
		1521	inside of lists, but lists are unproven inside of
		1522	columns.
		1523
		1524
		1525	In addition, several list attributes may be specified such
		1526	as the width of a tag, the list offset, and compactness
		1527	(blank lines between items allowed or disallowed). Most of
		1528	this document has been formatted with a tag style list
		1529	(-tag). For a change of pace, the list-type used to present
		1530	the list-types is an over-hanging list (-ohang). This type
		1531	of list is quite popular with TeX users, but
		1532	might look a bit funny after having read many pages of
		1533	tagged lists. The following list types are accepted by
		1534	.Bl:
		1535
		1536
		1537	-bullet
		1538	-item
		1539	-enum
		1540	These three are the simplest types of lists. Once the
		1541	.Bl macro has been given, items in the list are
		1542	merely indicated by a line consisting solely of the
		1543	.It macro. For example, the source text for a
		1544	simple enumerated list would look like:
		1545
		1546
		1547	.Bl -enum -compact
		1548	.It
		1549	Item one goes here.
		1550	.It
		1551	And item two here.
		1552	.It
		1553	Lastly item three goes here.
		1554	.El
		1555	The results:
		1556	1.Item one goes here.
		1557
		1558
		1559	2.And item two here.3.Lastly item three goes here.A simple bullet list construction:.Bl -bullet -compact
		1560	.It
		1561	Bullet one goes here.
		1562	.It
		1563	Bullet two here.
		1564	.El
		1565	Produces:
		1566	Bullet one goes here.
		1567
		1568
		1569	Bullet two here.-tag-diag-hang-ohang-insetThese list-types collect arguments specified with the .It macro and create a label which may be ''inset'' into the forth- coming text, ''hanged'' from the forthcoming text, ''overhanged'' from above and not indented or ''tagged''. This list was con- structed with the -ohang list-type. The .It macro is parsed only for the inset, hang and tag list-types and is not callable. Here is an example of inset labels:
		1570
		1571
		1572	''Tag'' The tagged list (also called a tagged paragraph)
		1573	is the most common type of list used in the Berkeley
		1574	manuals.
		1575
		1576
		1577	''Diag'' Diag lists create section four diagnostic lists
		1578	and are similar to inset lists except callable macros are
		1579	ignored.
		1580
		1581
		1582	''Hang'' Hanged labels are a matter of
		1583	taste.
		1584
		1585
		1586	''Ohang'' Overhanging labels are nice when space is con-
		1587	strained.
		1588
		1589
		1590	''Inset'' Inset labels are useful for controlling blocks
		1591	of paragraphs and are valuable for converting -mdoc manuals
		1592	to other formats.
		1593
		1594
		1595	Here is the source text which produced the above
		1596	example:
		1597
		1598
		1599	.Bl -inset -offset indent
		1600	.It Em Tag
		1601	The tagged list (also called a tagged paragraph) is the
		1602	most common type of list used in the Berkeley manuals.
		1603	.It Em Diag
		1604	Diag lists create section four diagnostic lists
		1605	and are similar to inset lists except callable
		1606	macros are ignored.
		1607	.It Em Hang
		1608	Hanged labels are a matter of taste.
		1609	.It Em Ohang
		1610	Overhanging labels are nice when space is constrained.
		1611	.It Em Inset
		1612	Inset labels are useful for controlling blocks of
		1613	paragraphs and are valuable for converting
		1614	.Nm -mdoc
		1615	manuals to other formats.
		1616	.El
		1617	Here is a hanged list with two items:
		1618	'' Hanged''labels appear similar to tagged lists when thelabel is smaller than the label width.
		1619
		1620
		1621	''Longer hanged list labels'' blend in to the paragraphunlike tagged paragraph labels.And the unformatted text which created it:.Bl -hang -offset indent
		1622	.It Em Hanged
		1623	labels appear similar to tagged lists when the
		1624	label is smaller than the label width.
		1625	.It Em Longer hanged list labels
		1626	blend in to the paragraph unlike
		1627	tagged paragraph labels.
		1628	.El
		1629	The tagged list which follows uses an optional width speci- fier to control the width of the tag.
		1630	SL
		1631
		1632
		1633	sleep time of the process (seconds blocked)PAGEINnumber of disk I/O's resulting from referencesby the process to pages not loaded in core.UIDnumerical user-id of process ownerPPIDnumerical id of parent of process process pri-ority (non-positive when in non-interruptiblewait)The raw text:.Bl -tag -width
		1634	Acceptable width specifiers:
		1635	-width Fl sets the width to the default width for aflag. All callable macros have a defaultwidth value. The .Fl
		1636	, value is presently set to ten constant width
		1637	characters or about five sixth of an inch.
		1638
		1639
		1640	-width 24n
		1641	sets the width to 24 constant width char- acters or about two inches. The n is absolutely necessary for the scaling to work correctly.
		1642
		1643
		1644	-width ENAMETOOLONG
		1645	sets width to the constant width length of the string
		1646	given.
		1647
		1648
		1649	-width int mkfifo
		1650	again, the width is set to the constant width of the string
		1651	given.
		1652
		1653
		1654	If a width is not specified for the tag list type, the first
		1655	time .It is invoked, an attempt is made to
		1656	determine an appropriate width. If the first argument to
		1657	.It is a callable macro, the default width for that
		1658	macro will be used as if the macro name had been supplied as
		1659	the width. However, if another item in the list is given
		1660	with a differ- ent callable macro name, a new and nested
		1661	list is assumed.
		1662
		1663
		1664	__PREDEFINED STRINGS__
		1665
		1666
		1667	The following strings are predefined as may be used by pre-
		1668	ceding with the troff string interpreting sequence
		1669	where ''xx'' is the name of the defined string or as
		1670	x where ''x'' is the name of the string. The
		1671	interpreting sequence may be used any where in the
		1672	text.
		1673
		1674
		1675	__String Nroff Troff__
		1676
		1677
		1678	Rq '' ''
		1679	Lq `` ``
		1680	ua ^
		1681	aa '
		1682	ga
		1683	q
		1684	Pi pi
		1685	Ne !=
		1686	Le
		1687	Ge
		1688	Lt
		1689	Gt
		1690	Pm +-
		1691	If infinity
		1692	Na ''NaN NaN''
		1693
		1694
		1695	Ba | |
		1696
		1697
		1698	__Note__: The string named q should be written
		1699	as q since it is only one char.
		1700	__DIAGNOSTICS__
		1701
		1702
		1703	The debugging facilities for -mdoc are limited, but can help
		1704	detect subtle errors such as the collision of an argument
		1705	name with an internal register or macro name. (A what?) A
		1706	register is an arithmetic storage class for troff
		1707	with a one or two character name. All registers internal to
		1708	-mdoc for troff and ditroff are two
		1709	characters and of the form
		1710	Ar,
		1711	aR or
		1712	C1.
		1713	And adding to the muddle, troff has its own
		1714	internal registers all of which are either two lower case
		1715	characters or a dot plus a letter or meta-character
		1716	character. In one of the introduction examples, it was shown
		1717	how to prevent the interpretation of a macro name with the
		1718	escape sequence . This is sufficient for the
		1719	internal register names also.
		1720
		1721
		1722	If a non-escaped register name is given in the argument list of a request unpredictable behavior will occur. In general, any time huge portions of text do not appear where expected in the output, or small strings such as list tags disappear, chances are there is a misunderstanding about an argument type in the argument list. Your mother never intended for you to remember this evil stuff - so here is a way to find out whether or not your arguments are valid: The .Db (debug) macro displays the interpretation of the argument list for most macros. Macros such as the .Pp (paragraph) macro do not contain debugging information. All of the callable macros do, and it is strongly advised whenever in doubt, turn on the .Db macro.
		1723
		1724
		1725	Usage: .Db [[on | off]
		1726
		1727
		1728	An example of a portion of text with the debug macro placed
		1729	above and below an artificially created problem (a flag
		1730	argument aC which should be in
		1731	order to work):
		1732
		1733
		1734	.Db on
		1735	.Op Fl aC Ar file )
		1736	.Db off
		1737	The resulting output:
		1738
		1739
		1740	DEBUGGING ON
		1741	DEBUG(argv) MACRO: `.Op' Line #: 2
		1742	Argc: 1 Argv: `Fl' Length: 2
		1743	Space: `' Class: Executable
		1744	Argc: 2 Argv: `aC' Length: 2
		1745	Space: `' Class: Executable
		1746	Argc: 3 Argv: `Ar' Length: 2
		1747	Space: `' Class: Executable
		1748	Argc: 4 Argv: `file' Length: 4
		1749	Space: ` ' Class: String
		1750	Argc: 5 Argv: `)' Length: 1
		1751	Space: ` ' Class: Closing Punctuation or suffix
		1752	MACRO REQUEST: .Op Fl aC Ar file )
		1753	DEBUGGING OFF
		1754	The first line of information tells the name of the calling macro, here .Op, and the line number it appears on. If one or more files are involved (especially if text from another file is included) the line number may be bogus. If there is only one file, it should be accurate. The second line gives the argument count, the argument (Fl) and its length. If the length of an argument is two characters, the argument is tested to see if it is executable (unfortunately, any regis- ter which contains a non-zero value appears executable). The third line gives the space allotted for a class, and the class type. The problem here is the argument aC should not be executable. The four types of classes are string, exe- cutable, closing punctuation and opening punctuation. The last line shows the entire argument list as it was read. In this next example, the offending aC is escaped:
		1755
		1756
		1757	.Db on
		1758	.Em An escaped
		1759
		1760
		1761	DEBUGGING ON
		1762	DEBUG(fargv) MACRO: `.Em' Line #: 2
		1763	Argc: 1 Argv: `An' Length: 2
		1764	Space: ` ' Class: String
		1765	Argc: 2 Argv: `escaped' Length: 7
		1766	Space: ` ' Class: String
		1767	Argc: 3 Argv: `aC' Length: 2
		1768	Space: ` ' Class: String
		1769	MACRO REQUEST: .Em An escaped
		1770	The argument shows up with the same length of 2 as the sequence produces a zero width, but a register named was not found and the type classified as string.
		1771
		1772
		1773	Other diagnostics consist of usage statements and are self
		1774	explanatory.
		1775	__GROFF, TROFF AND NROFF__
		1776
		1777
		1778	The -mdoc package does not need compatibility mode with
		1779	groff.
		1780
		1781
		1782	The package inhibits page breaks, and the headers and foot- ers which normally occur at those breaks with nroff, to make the manual more efficient for viewing on-line. At the moment, groff with -Tascii does eject the imaginary remain- der of the page at end of file. The inhibiting of the page breaks makes nroff'd files unsuitable for hardcopy. There is a register named cR which can be set to zero in the site dependent style file /usr/src/share/tmac/doc-nroff to restore the old style behavior.
		1783	__FILES__
		1784	/usr/share/tmac/tmac.doc
		1785	manual macro
		1786	package
		1787
		1788
		1789	/usr/share/misc/mdoc.template
		1790	template for writing a man page
		1791	/usr/share/examples/mdoc/
		1792	several example man pages
		1793
		1794
		1795	__SEE ALSO__
		1796
		1797
		1798	man(1), troff(1),
		1799	mdoc(7)
		1800	__BUGS__
		1801
		1802
		1803	Undesirable hyphenation on the dash of a flag argument is
		1804	not yet resolved, and causes occasional mishaps in the
		1805	__DESCRIPTION__ section. (line break on the
		1806	hyphen).
		1807
		1808
		1809	Predefined strings are not declared in documentation.
		1810
		1811
		1812	Section 3f has not been added to the header
		1813	routines.
		1814
		1815
		1816	.Nm font should be changed in __NAME__
		1817	section.
		1818
		1819
		1820	.Fn needs to have a check to prevent splitting up
		1821	if the line length is too short. Occasionally it separates
		1822	the last parenthesis, and sometimes looks ridiculous if a
		1823	line is in fill mode.
		1824
		1825
		1826	The method used to prevent header and footer page breaks
		1827	(other than the initial header and footer) when using nroff
		1828	occasionally places an unsightly partially filled line
		1829	(blank) at the would be bottom of the page.
		1830
		1831
		1832	The list and display macros to not do any keeps and cer-
		1833	tainly should be able to.
		1834
		1835
		1836	BSD December 30, 1993 1
		1837	----