EditPageHistoryDiffInfoLikePages

Annotated edit history of troff(1) version 4, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	TROFF
		2	!!!TROFF
		3	NAME
		4	SYNOPSIS
		5	DESCRIPTION
		6	OPTIONS
		7	USAGE
		8	ENVIRONMENT
		9	FILES
		10	SEE ALSO
		11	----
		12	!!NAME
		13
		14
		15	troff - format documents
		16	!!SYNOPSIS
		17
		18
		19	__troff__ [[ __-abivzCERU__ ] [[ __-w__''name'' ]
		20	[[ __-W__''name'' ] [[ __-d__''cs'' ] [[
		21	__-f__''fam'' ] [[ __-m__''name'' ] [[
		22	__-n__''num'' ] [[ __-o__''list'' ] [[
		23	__-r__''cn'' ] [[ __-T__''name'' ] [[
		24	__-F__''dir'' ] [[ __-M__''dir'' ] [[
		25	''files...'' ]
		26
		27
		28	It is possible to have whitespace between a command line
		29	option and its parameter.
		30	!!DESCRIPTION
		31
		32
		33	This manual page describes the GNU version of __troff__,
		34	which is part of the groff document formatting system. It is
		35	highly compatible with UNIX troff. Usually it should be
		36	invoked using the groff command, which will also run
		37	preprocessors and postprocessors in the appropriate order
		38	and with the appropriate options.
		39	!!OPTIONS
		40
		41
		42	__-a__ Generate an ASCII approximation of
		43	the typeset output.
		44
		45
		46	__-b__ Print a backtrace with each warning or error
		47	message. This backtrace should help track down the cause of
		48	the error. The line numbers given in the backtrace may not
		49	always be correct: __troff__'s idea of line numbers gets
		50	confused by __as__ or __am__ requests.
		51
		52
		53	__-i__ Read the standard input after all the named input
		54	files have been processed.
		55
		56
		57	__-v__ Print the version number.
		58
		59
		60	__-w__''name''
		61
		62
		63	Enable warning ''name''. Available warnings are described
		64	in the Warnings subsection below. Multiple __-w__ options
		65	are allowed.
		66
		67
		68	__-W__''name''
		69
		70
		71	Inhibit warning ''name''. Multiple __-W__ options are
		72	allowed.
		73
		74
		75	__-E__ Inhibit all error messages of __troff__. Note
		76	that this doesn't affect messages output to standard error
		77	by macro packages using the __.tm__ or __.tm1__
		78	requests.
		79
		80
		81	__-z__ Suppress formatted output.
		82
		83
		84	__-C__ Enable compatibility mode.
		85
		86
		87	__-d__''cs''
		88
		89
		90	__-d__''name''__=__''s''
		91
		92
		93	Define ''c'' or ''name'' to be a string ''s'';
		94	''c'' must be a one letter name.
		95
		96
		97	__-f__''fam''
		98
		99
		100	Use ''fam'' as the default font family.
		101
		102
		103	__-m__''name''
		104
		105
		106	Read in the file ''name''__.tmac__. If it isn't found,
		107	try __tmac.__''name'' instead. It will be first
		108	searched for in directories given with the __-M__ command
		109	line option, then in directories given in the
		110	__GROFF_TMAC_PATH__ environment variable, then in the
		111	current directory (only if in unsafe mode), the home
		112	directory, /usr/lib/groff/site-tmac,
		113	/usr/share/groff/site-tmac, and
		114	/usr/share/groff/1.17.2/tmac.
		115
		116
		117	__-U__ Unsafe mode. This will enable the following
		118	requests: __.open__, __.opena__, __.pso__,
		119	__.sy__, and __.pi__. For security reasons, these
		120	potentially dangerous requests are disabled otherwise. It
		121	will also add the current directory to the macro search
		122	path.
		123
		124
		125	__-R__ Don't load __troffrc__ and
		126	__troffrc-end__.
		127
		128
		129	__-n__''num''
		130
		131
		132	Number the first page ''num''.
		133
		134
		135	__-o__''list''
		136
		137
		138	Output only pages in ''list'', which is a comma-separated
		139	list of page ranges; ''n'' means print page ''n'',
		140	''m''__-__''n'' means print every page between
		141	''m'' and ''n'', __-__''n'' means print every
		142	page up to ''n'', ''n''__-__ means print every page
		143	from ''n''. __Troff__ will exit after printing the
		144	last page in the list.
		145
		146
		147	__-r__''cn''
		148
		149
		150	__-r__''name''__=__''n''
		151
		152
		153	Set number register ''c'' or ''name'' to ''n'';
		154	''c'' must be a one character name; ''n'' can be any
		155	troff numeric expression.
		156
		157
		158	__-T__''name''
		159
		160
		161	Prepare output for device ''name'', rather than the
		162	default __ps__.
		163
		164
		165	__-F__''dir''
		166
		167
		168	Search in directory (or directory path) ''dir'' for
		169	subdirectories __dev__''name'' (''name'' is the
		170	name of the device) and there for the __DESC__ file and
		171	font files. ''dir'' is scanned before all other font
		172	directories.
		173
		174
		175	__-M__''dir''
		176
		177
		178	Search directory (or directory path) ''dir'' for macro
		179	files. This is scanned before all other macro
		180	directories.
		181	!!USAGE
		182
		183
		184	Only the features not in UNIX troff are described
		185	here.
		186
		187
		188	__Long names__
		189
		190
		191	The names of number registers, fonts,
		192	strings/macros/diversions, special characters can be of any
		193	length. In escape sequences, where you can use
		194	__(__''xx'' for a two character name, you can use
		195	__[[__''xxx''__]__ for a name of arbitrary
		196	length:
		197
		198
		199	__[[__''xxx''__]__
		200
		201
		202	Print the special character called ''xxx''.
		203
		204
		205	__f[[__''xxx''__]__
		206
		207
		208	Set font ''xxx''.
		209
		210
		211	__*[[__''xxx''__]__
		212
		213
		214	Interpolate string ''xxx''.
		215
		216
		217	__n[[__''xxx''__]__
		218
		219
		220	Interpolate number register ''xxx''.
		221
		222
		223	__Fractional pointsizes__
		224
		225
		226	A ''scaled point'' is equal to 1/sizescale points, where
		227	sizescale is specified in the __DESC__ file (1 by
		228	default). There is a new scale indicator __z__ which has
		229	the effect of multiplying by sizescale. Requests and escape
		230	sequences in troff interpret arguments that represent a
		231	pointsize as being in units of scaled points, but they
		232	evaluate each such argument using a default scale indicator
		233	of __z__. Arguments treated in this way are the argument
		234	to the __ps__ request, the third argument to the
		235	__cs__ request, the second and fourth arguments to the
		236	__tkf__ request, the argument to the __H__ escape
		237	sequence, and those variants of the __s__ escape sequence
		238	that take a numeric expression as their
		239	argument.
		240
		241
		242	For example, suppose sizescale is 1000; then a scaled point
		243	will be equivalent to a millipoint; the request __.ps
		244	10.25__ is equivalent to __.ps 10.25z__ and so sets the
		245	pointsize to 10250 scaled points, which is equal to 10.25
		246	points.
		247
		248
		249	The number register __n[[.s]__ returns the pointsize in
		250	points as decimal fraction. There is also a new number
		251	register __n[[.ps]__ that returns the pointsize in scaled
		252	points.
		253
		254
		255	It would make no sense to use the __z__ scale indicator
		256	in a numeric expression whose default scale indicator was
		257	neither __u__ nor __z__, and so __troff__ disallows
		258	this. Similarly it would make no sense to use a scaling
		259	indicator other than __z__ or __u__ in a numeric
		260	expression whose default scale indicator was __z__, and
		261	so __troff__ disallows this as well.
		262
		263
		264	There is also new scale indicator __s__ which multiplies
		265	by the number of units in a scaled point. So, for example,
		266	__n[[.ps]s__ is equal to __1m__. Be sure not to confuse
		267	the __s__ and __z__ scale indicators.
		268
		269
		270	__Numeric expressions__
		271
		272
		273	Spaces are permitted in a number expression within
		274	parentheses.
		275
		276
		277	__M__ indicates a scale of 100ths of an em.
		278
		279
		280	''e1''____''e2''
		281
		282
		283	The maximum of ''e1'' and ''e2''.
		284
		285
		286	''e1''____''e2''
		287
		288
		289	The minimum of ''e1'' and ''e2''.
		290
		291
		292	__(__''c''__;__''e''__)__
		293
		294
		295	Evaluate ''e'' using ''c'' as the default scaling
		296	indicator. If ''c'' is missing, ignore scaling indicators
		297	in the evaluation of ''e''.
		298
		299
		300	__New escape sequences__
		301
		302
		303	__A'__''anything''__'__
		304
		305
		306	This expands to __1__ or __0__ according as
		307	''anything'' is or is not acceptable as the name of a
		308	string, macro, diversion, number register, environment or
		309	font. It will return __0__ if ''anything'' is empty.
		310	This is useful if you want to lookup user input in some sort
		311	of associative table.
		312
		313
		314	__B'__''anything''__'__
		315
		316
		317	This expands to __1__ or __0__ according as
		318	''anything'' is or is not a valid numeric expression. It
		319	will return __0__ if ''anything'' is
		320	empty.
		321
		322
		323	__C'__''xxx''__'__
		324
		325
		326	Typeset character named ''xxx''. Normally it is more
		327	convenient to use __[[__''xxx''__]__. But __C__
		328	has the advantage that it is compatible with recent versions
		329	of UNIX and is available in compatibility
		330	mode.
		331
		332
		333	__E__
		334
		335
		336	This is equivalent to an escape character, but it's not
		337	interpreted in copy-mode. For example, strings to start and
		338	end superscripting could be defined like this:
		339
		340
		341	.ds { v'-.3m's'En[[.s]*6u/10u'
		342	.ds } s0v'.3m'
		343
		344
		345	The use of __E__ ensures that these definitions will work
		346	even if __*{__ gets interpreted in copy-mode (for
		347	example, by being used in a macro argument).
		348
		349
		350	__N'__''n''__'__
		351
		352
		353	Typeset the character with code ''n'' in the current
		354	font. ''n'' can be any integer. Most devices only have
		355	characters with codes between 0 and 255. If the current font
		356	does not contain a character with that code, special fonts
		357	will ''not'' be searched. The __N__ escape sequence
		358	can be conveniently used on conjunction with the __char__
		359	request:
		360
		361
		362	__.char [[phone] f(ZDN'37'__
		363
		364
		365	The code of each character is given in the fourth column in
		366	the font description file after the __charset__ command.
		367	It is possible to include unnamed characters in the font
		368	description file by using a name of __---__; the __N__
		369	escape sequence is the only way to use these.
		370
		371
		372	__R'__''name n''__'__
		373
		374
		375	This has the same effect as
		376
		377
		378	__.nr__ ''name n''
		379
		380
		381	__s(__''nn''
		382
		383
		384	__s(__''nn''
		385
		386
		387	Set the point size to ''nn'' points; ''nn'' must be
		388	exactly two digits.
		389
		390
		391	__s[[__''n''__]__
		392
		393
		394	__s[[__''n''__]__
		395
		396
		397	__s'__''n''__'__
		398
		399
		400	__s'__''n''__'__
		401
		402
		403	Set the point size to ''n'' scaled points; ''n'' is a
		404	numeric expression with a default scale indicator of
		405	__z__.
		406
		407
		408	__V__''x''
		409
		410
		411	__V(__''xx''
		412
		413
		414	__V[[__''xxx''__]__
		415
		416
		417	Interpolate the contents of the environment variable
		418	''xxx'', as returned by getenv(3). __V__ is
		419	interpreted in copy-mode.
		420
		421
		422	__Y__''x''
		423
		424
		425	__Y(__''xx''
		426
		427
		428	__Y[[__''xxx''__]__
		429
		430
		431	This is approximately equivalent to
		432	__X'*[[__''xxx''__]'__. However the contents of the
		433	string or macro ''xxx'' are not interpreted; also it is
		434	permitted for ''xxx'' to have been defined as a macro and
		435	thus contain newlines (it is not permitted for the argument
		436	to __X__ to contain newlines). The inclusion of newlines
		437	requires an extension to the UNIX troff output format, and
		438	will confuse drivers that do not know about this
		439	extension.
		440
		441
		442	__Z'__''anything''__'__
		443
		444
		445	Print anything and then restore the horizontal and vertical
		446	position; ''anything'' may not contain tabs or
		447	leaders.
		448
		449
		450	__$0__
		451
		452
		453	The name by which the current macro was invoked. The
		454	__als__ request can make a macro have more than one
		455	name.
		456
		457
		458	__$*__
		459
		460
		461	In a macro, the concatenation of all the arguments separated
		462	by spaces.
		463
		464
		465	__$@__
		466
		467
		468	In a macro, the concatenation of all the arguments with each
		469	surrounded by double quotes, and separated by
		470	spaces.
		471
		472
		473	__$(__''nn''
		474
		475
		476	__$[[__''nnn''__]__
		477
		478
		479	In a macro, this gives the ''nn''-th or ''nnn''-th
		480	argument. Macros can have an unlimited number of
		481	arguments.
		482
		483
		484	__?__''anything''__?__
		485
		486
		487	When used in a diversion, this will transparently embed
		488	''anything'' in the diversion. ''anything'' is read in
		489	copy mode. When the diversion is reread, ''anything''
		490	will be interpreted. ''anything'' may not contain
		491	newlines; use __!__ if you want to embed newlines in a
		492	diversion. The escape sequence __?__ is also recognised
		493	in copy mode and turned into a single internal code; it is
		494	this code that terminates ''anything''. Thus
		495
		496
		497	__.nr x 1
		498	.nf
		499	.di d
		500	?\?\\?\\\\nx\\?\??
		501	.di
		502	.nr x 2
		503	.di e
		504	.d
		505	.di
		506	.nr x 3
		507	.di f
		508	.e
		509	.di
		510	.nr x 4
		511	.f
		512	__
		513
		514
		515	will print __4__.
		516
		517
		518	__/__
		519
		520
		521	This increases the width of the preceding character so that
		522	the spacing between that character and the following
		523	character will be correct if the following character is a
		524	roman character. For example, if an italic f is immediately
		525	followed by a roman right parenthesis, then in many fonts
		526	the top right portion of the f will overlap the top left of
		527	the right parenthesis producing ''f''), which is ugly.
		528	Inserting __/__ produces ''f'') and avoids this
		529	problem. It is a good idea to use this escape sequence
		530	whenever an italic character is immediately followed by a
		531	roman character without any intervening space.
		532
		533
		534	__,__
		535
		536
		537	This modifies the spacing of the following character so that
		538	the spacing between that character and the preceding
		539	character will correct if the preceding character is a roman
		540	character. For example, inserting __,__ between the
		541	parenthesis and the f changes (''f'' to (''f''. It is
		542	a good idea to use this escape sequence whenever a roman
		543	character is immediately followed by an italic character
		544	without any intervening space.
		545
		546
		547	__)__
		548
		549
		550	Like ____ except that it behaves like a character
		551	declared with the __cflags__ request to be transparent
		552	for the purposes of end of sentence
		553	recognition.
		554
		555
		556	__~__
		557
		558
		559	This produces an unbreakable space that stretches like a
		560	normal inter-word space when a line is
		561	adjusted.
		562
		563
		564	__:__
		565
		566
		567	This causes the insertion of a zero-width break point. It is
		568	equal to __%__ but without insertion of a soft hyphen
		569	character.
		570
		571
		572	__#__
		573
		574
		575	Everything up to and including the next newline is ignored.
		576	This is interpreted in copy mode. This is like ____
		577	except that ____ does not ignore the terminating
		578	newline.
		579
		580
		581	__New requests__
		582
		583
		584	__.aln__ ''xx yy''
		585
		586
		587	Create an alias ''xx'' for number register object named
		588	''yy''. The new name and the old name will be exactly
		589	equivalent. If ''yy'' is undefined, a warning of type
		590	__reg__ will be generated, and the request will be
		591	ignored.
		592
		593
		594	__.als__ ''xx yy''
		595
		596
		597	Create an alias ''xx'' for request, string, macro, or
		598	diversion object named ''yy''. The new name and the old
		599	name will be exactly equivalent (it is similar to a hard
		600	rather than a soft link). If ''yy'' is undefined, a
		601	warning of type __mac__ will be generated, and the
		602	request will be ignored. The __de__, __am__,
		603	__di__, __da__, __ds__, and __as__ requests only
		604	create a new object if the name of the macro, diversion or
		605	string diversion is currently undefined or if it is defined
		606	to be a request; normally they modify the value of an
		607	existing object.
		608
		609
		610	__.am1__ ''xx yy''
		611
		612
		613	Similar to __.am__, but compatibility mode is switched
		614	off during execution. On entry, the current compatibility
		615	mode is saved and restored at exit.
		616
		617
		618	__.asciify__ ''xx''
		619
		620
		621	This request `unformats' the diversion ''xx'' in such a
		622	way that ASCII and space characters (and some
		623	escape sequences) that were formatted and diverted into
		624	''xx'' will be treated like ordinary input characters
		625	when ''xx'' is reread. Useful for diversions in
		626	conjunction with the __.writem__ request. It can be also
		627	used for gross hacks; for example, this
		628
		629
		630	__.tr @.
		631	.di x
		632	@nr n 1
		633	.br
		634	.di
		635	.tr @@
		636	.asciify x
		637	.x
		638	__
		639
		640
		641	will set register __n__ to 1. Note that glyph information
		642	(font, font size, etc.) is not preserved; use
		643	__.unformat__ instead.
		644
		645
		646	__.backtrace__
		647
		648
		649	Print a backtrace of the input stack on stderr.
		650
		651
		652	__.blm__ ''xx''
		653
		654
		655	Set the blank line macro to ''xx''. If there is a blank
		656	line macro, it will be invoked when a blank line is
		657	encountered instead of the usual troff
		658	behaviour.
		659
		660
		661	__.box__ ''xx''
		662
		663
		664	__.boxa__ ''xx''
		665
		666
		667	These requests are similar to the __di__ and __da__
		668	requests with the exception that a partially filled line
		669	will not become part of the diversion (i.e., the diversion
		670	always starts with a new line) but restored after ending the
		671	diversion, discarding the partially filled line which
		672	possibly comes from the diversion.
		673
		674
		675	__.break__
		676
		677
		678	Break out of a while loop. See also the __while__ and
		679	__continue__ requests. Be sure not to confuse this with
		680	the __br__ request.
		681
		682
		683	__.brp__
		684
		685
		686	This is the same as __p__.
		687
		688
		689	__.cflags__ ''n c1 c2...''
		690
		691
		692	Characters ''c1'', ''c2'',... have properties
		693	determined by ''n'', which is ORed from the
		694	following:
		695
		696
		697	1
		698
		699
		700	the character ends sentences (initially characters
		701	__.?!__ have this property);
		702
		703
		704	2
		705
		706
		707	lines can be broken before the character (initially no
		708	characters have this property); a line will not be broken at
		709	a character with this property unless the characters on each
		710	side both have non-zero hyphenation codes.
		711
		712
		713	4
		714
		715
		716	lines can be broken after the character (initially
		717	characters __-__ have this property); a line will not be
		718	broken at a character with this property unless the
		719	characters on each side both have non-zero hyphenation
		720	codes.
		721
		722
		723	8
		724
		725
		726	the character overlaps horizontally (initially characters
		727	____ have this property);
		728
		729
		730	16
		731
		732
		733	the character overlaps vertically (initially character
		734	____ has this property);
		735
		736
		737	32
		738
		739
		740	an end of sentence character followed by any number of
		741	characters with this property will be treated as the end of
		742	a sentence if followed by a newline or two spaces; in other
		743	words the character is transparent for the purposes of end
		744	of sentence recognition; this is the same as having a zero
		745	space factor in TEX (initially characters ____
		746	have this property).
		747
		748
		749	__.char__ ''c string''
		750
		751
		752	Define character ''c'' to be ''string''. Every time
		753	character ''c'' needs to be printed, ''string'' will
		754	be processed in a temporary environment and the result will
		755	be wrapped up into a single object. Compatibility mode will
		756	be turned off and the escape character will be set to
		757	__\__ while ''string'' is being processed. Any
		758	emboldening, constant spacing or track kerning will be
		759	applied to this object rather than to individual characters
		760	in ''string''. A character defined by this request can be
		761	used just like a normal character provided by the output
		762	device. In particular other characters can be translated to
		763	it with the __tr__ request; it can be made the leader
		764	character by the __lc__ request; repeated patterns can be
		765	drawn with the character using the __l__ and __L__
		766	escape sequences; words containing the character can be
		767	hyphenated correctly, if the __hcode__ request is used to
		768	give the character a hyphenation code. There is a special
		769	anti-recursion feature: use of character within the
		770	character's definition will be handled like normal
		771	characters not defined with __char__. A character
		772	definition can be removed with the __rchar__
		773	request.
		774
		775
		776	__.chop__ ''xx''
		777
		778
		779	Chop the last character off macro, string, or diversion
		780	''xx''. This is useful for removing the newline from the
		781	end of diversions that are to be interpolated as
		782	strings.
		783
		784
		785	__.close__ ''stream''
		786
		787
		788	Close the stream named ''stream''; ''stream'' will no
		789	longer be an acceptable argument to the __write__
		790	request. See the __open__ request.
		791
		792
		793	__.continue__
		794
		795
		796	Finish the current iteration of a while loop. See also the
		797	__while__ and __break__ requests.
		798
		799
		800	__.cp__ ''n''
		801
		802
		803	If ''n'' is non-zero or missing, enable compatibility
		804	mode, otherwise disable it. In compatibility mode, long
		805	names are not recognised, and the incompatibilities caused
		806	by long names do not arise.
		807
		808
		809	__.dei__ ''xx yy''
		810
		811
		812	Define macro indirectly. The following example
		813
		814
		815	__.ds xx aa
		816	.ds yy bb
		817	.dei xx yy
		818	__
		819
		820
		821	is equivalent to
		822
		823
		824	__.de aa bb__
		825
		826
		827	__.de1__ ''xx yy''
		828
		829
		830	Similar to __.de__, but compatibility mode is switched
		831	off during execution. On entry, the current compatibility
		832	mode is saved and restored at exit.
		833
		834
		835	__.do__ ''xxx''
		836
		837
		838	Interpret ''.xxx'' with compatibility mode disabled. For
		839	example,
		840
		841
		842	__.do fam T__
		843
		844
		845	would have the same effect as
		846
		847
		848	__.fam T__
		849
		850
		851	except that it would work even if compatibility mode had
		852	been enabled. Note that the previous compatibility mode is
		853	restored before any files sourced by ''xxx'' are
		854	interpreted.
		855
		856
		857	__.ecs__
		858
		859
		860	Save current escape character.
		861
		862
		863	__.ecr__
		864
		865
		866	Restore escape character saved with __ecs__. Without a
		867	previous call to __ecs__, `__\__' will be the new
		868	escape character.
		869
		870
		871	__.evc__ ''xx''
		872
		873
		874	Copy the contents of environment ''xx'' to the current
		875	environment. No pushing or popping of environents will be
		876	done.
		877
		878
		879	__.fam__ ''xx''
		880
		881
		882	Set the current font family to ''xx''. The current font
		883	family is part of the current environment. If ''xx'' is
		884	missing, switch back to previous font family. See the
		885	description of the __sty__ request for more information
		886	on font families.
		887
		888
		889	__.fspecial__ ''f s1 s2...''
		890
		891
		892	When the current font is ''f'', fonts ''s1'',
		893	''s2'',... will be special, that is, they will searched
		894	for characters not in the current font. Any fonts specified
		895	in the __special__ request will be searched after fonts
		896	specified in the __fspecial__ request.
		897
		898
		899	__.ftr__ ''f g''
		900
		901
		902	Translate font ''f'' to ''g''. Whenever a font named
		903	''f'' is referred to in __f__ escape sequence, or in
		904	the __ft__, __ul__, __bd__, __cs__, __tkf__,
		905	__special__, __fspecial__, __fp__, or __sty__
		906	requests, font ''g'' will be used. If ''g'' is
		907	missing, or equal to ''f'' then font ''f'' will not be
		908	translated.
		909
		910
		911	__.hcode__ ''c1 code1 c2 code2...''
		912
		913
		914	Set the hyphenation code of character ''c1'' to
		915	''code1'' and that of ''c2'' to ''code2''. A
		916	hyphenation code must be a single input character (not a
		917	special character) other than a digit or a space. Initially
		918	each lower-case letter has a hyphenation code, which is
		919	itself, and each upper-case letter has a hyphenation code
		920	which is the lower case version of itself. See also the
		921	__hpf__ request.
		922
		923
		924	__.hla__ ''lang''
		925
		926
		927	Set the current hyphenation language to ''lang''.
		928	Hyphenation exceptions specified with the __hw__ request
		929	and hyphenation patterns specified with the __hpf__
		930	request are both associated with the current hyphenation
		931	language. The __hla__ request is usually invoked by the
		932	__troffrc__ file.
		933
		934
		935	__.hlm__ ''n''
		936
		937
		938	Set the maximum number of consecutive hyphenated lines to
		939	''n''. If ''n'' is negative, there is no maximum. The
		940	default value is -1. This value is associated with the
		941	current environment. Only lines output from an environment
		942	count towards the maximum associated with that environment.
		943	Hyphens resulting from __%__ are counted; explicit
		944	hyphens are not.
		945
		946
		947	__.hpf__ ''file''
		948
		949
		950	Read hyphenation patterns from ''file''; this will be
		951	searched for in the same way that ''name''__.tmac__ is
		952	searched for when the __-m__''name'' option is
		953	specified. It should have the same format as the argument to
		954	the patterns primitive in TEX; the letters appearing in this
		955	file are interpreted as hyphenation codes. A __%__
		956	character in the patterns file introduces a comment that
		957	continues to the end of the line. The set of hyphenation
		958	patterns is associated with the current language set by the
		959	__hla__ request. The __hpf__ request is usually
		960	invoked by the __troffrc__ file.
		961
		962
		963	__.hym__ ''n''
		964
		965
		966	Set the ''hyphenation margin'' to ''n'': when the
		967	current adjustment mode is not __b__, the line will not
		968	be hyphenated if the line is no more than ''n'' short.
		969	The default hyphenation margin is 0. The default scaling
		970	indicator for this request is ''m''. The hyphenation
		971	margin is associated with the current environment. The
		972	current hyphenation margin is available in the
		973	__n[[.hym]__ register.
		974
		975
		976	__.hys__ ''n''
		977
		978
		979	Set the ''hyphenation space'' to ''n'': when the
		980	current adjustment mode is __b__ don't hyphenate the line
		981	if the line can be justified by adding no more than ''n''
		982	extra space to each word space. The default hyphenation
		983	space is 0. The default scaling indicator for this request
		984	is __m__. The hyphenation space is associated with the
		985	current environment. The current hyphenation space is
		986	available in the __n[[.hys]__ register.
		987
		988
		989	__.kern__ ''n''
		990
		991
		992	If ''n'' is non-zero or missing, enable pairwise kerning,
		993	otherwise disable it.
		994
		995
		996	__.length__ ''xx string''
		997
		998
		999	Compute the length of ''string'' and return it in the
		1000	number register ''xx'' (which is not necessarily defined
		1001	before).
		1002
		1003
		1004	__.linetabs__ ''n''
		1005
		1006
		1007	If ''n'' is non-zero or missing, enable line-tabs mode,
		1008	otherwise disable it (which is the default). In line-tabs
		1009	mode, tab distances are computed relative to the (current)
		1010	output line. Otherwise they are taken relative to the input
		1011	line. For example, the following
		1012
		1013
		1014	__.ds x atc
		1015	.ds y btc
		1016	.ds z c
		1017	.ta 1i 3i
		1018	*x
		1019	*y
		1020	*z
		1021	__
		1022
		1023
		1024	yields
		1025
		1026
		1027	a b c
		1028
		1029
		1030	In line-tabs mode, the same code gives
		1031
		1032
		1033	a b c
		1034
		1035
		1036	Line-tabs mode is associated with the current environment;
		1037	the read-only number register __n[[.linetabs]__ is set to
		1038	1 if in line-tabs mode, and 0 otherwise.
		1039
		1040
		1041	__.mso__ ''file''
		1042
		1043
		1044	The same as the __so__ request except that ''file'' is
		1045	searched for in the same directories as macro files for the
		1046	the __-m__ command line option. If the file name to be
		1047	included has the form ''name''__.tmac__ and it isn't
		1048	found, __mso__ tries to include __tmac.__''name''
		1049	instead and vice versa.
		1050
		1051
		1052	__.nop__ ''anything''
		1053
		1054
		1055	Execute ''anything''. This is similar to `.if
		1056	1'.
		1057
		1058
		1059	__.nroff__
		1060
		1061
		1062	Make the __n__ built-in condition true and the __t__
		1063	built-in condition false. This can be reversed using the
		1064	__troff__ request.
		1065
		1066
		1067	__.open__ ''stream filename''
		1068
		1069
		1070	Open ''filename'' for writing and associate the stream
		1071	named ''stream'' with it. See also the __close__ and
		1072	__write__ requests.
		1073
		1074
		1075	__.opena__ ''stream filename''
		1076
		1077
		1078	Like __open__, but if ''filename'' exists, append to
		1079	it instead of truncating it.
		1080
		1081
		1082	__.pnr__
		1083
		1084
		1085	Print the names and contents of all currently defined number
		1086	registers on stderr.
		1087
		1088
		1089	__.psbb__ ''filename''
		1090
		1091
3	perry	1092	Get the bounding box of a !PostScript image ''filename''.
1	perry	1093	This file must conform to Adobe's Document Structuring
3	perry	1094	Conventions; the command looks for a __%%!BoundingBox__
1	perry	1095	comment to extract the bounding box values. After a
3	perry	1096	successful call, the coordinates (in !PostScript units) of
1	perry	1097	the lower left and upper right corner can be found in the
		1098	registers __n[[llx]__, __n[[lly]__, __n[[urx]__, and
		1099	__n[[ury]__, respectively. If some error has occurred, the
		1100	four registers are set to zero.
		1101
		1102
		1103	__.pso__ ''command''
		1104
		1105
		1106	This behaves like the __so__ request except that input
		1107	comes from the standard output of
		1108	''command''.
		1109
		1110
		1111	__.ptr__
		1112
		1113
		1114	Print the names and positions of all traps (not including
		1115	input line traps and diversion traps) on stderr. Empty slots
		1116	in the page trap list are printed as well, because they can
		1117	affect the priority of subsequently planted
		1118	traps.
		1119
		1120
		1121	__.rchar__ ''c1 c2...''
		1122
		1123
		1124	Remove the definitions of characters ''c1'',
		1125	''c2'',... This undoes the effect of a __char__
		1126	request.
		1127
		1128
		1129	__.return__
		1130
		1131
		1132	Within a macro, return immediately. No effect
		1133	otherwise.
		1134
		1135
		1136	__.rj__
		1137
		1138
		1139	__.rj__ ''n''
		1140
		1141
		1142	Right justify the next ''n'' input lines. Without an
		1143	argument right justify the next input line. The number of
		1144	lines to be right justified is available in the
		1145	__n[[.rj]__ register. This implicitly does __.ce 0__.
		1146	The __ce__ request implicitly does __.rj
		1147	0__.
		1148
		1149
		1150	__.rnn__ ''xx yy''
		1151
		1152
		1153	Rename number register ''xx'' to ''yy''.
		1154
		1155
		1156	__.shc__ ''c''
		1157
		1158
		1159	Set the soft hyphen character to ''c''. If ''c'' is
		1160	omitted, the soft hyphen character will be set to the
		1161	default __-__. The soft hyphen character is the character
		1162	which will be inserted when a word is hyphenated at a line
		1163	break. If the soft hyphen character does not exist in the
		1164	font of the character immediately preceding a potential
		1165	break point, then the line will not be broken at that point.
		1166	Neither definitions (specified with the __char__ request)
		1167	nor translations (specified with the __tr__ request) are
		1168	considered when finding the soft hyphen
		1169	character.
		1170
		1171
		1172	__.shift__ ''n''
		1173
		1174
		1175	In a macro, shift the arguments by ''n'' positions:
		1176	argument ''i'' becomes argument ''i''-''n'';
		1177	arguments 1 to ''n'' will no longer be available. If
		1178	''n'' is missing, arguments will be shifted by 1.
		1179	Shifting by negative amounts is currently
		1180	undefined.
		1181
		1182
		1183	__.special__ ''s1 s2...''
		1184
		1185
		1186	Fonts ''s1'', ''s2'', are special and will be searched
		1187	for characters not in the current font.
		1188
		1189
		1190	__.sty__ ''n f''
		1191
		1192
		1193	Associate style ''f'' with font position ''n''. A font
		1194	position can be associated either with a font or with a
		1195	style. The current font is the index of a font position and
		1196	so is also either a font or a style. When it is a style, the
		1197	font that is actually used is the font the name of which is
		1198	the concatenation of the name of the current family and the
		1199	name of the current style. For example, if the current font
		1200	is 1 and font position 1 is associated with style __R__
		1201	and the current font family is __T__, then font __TR__
		1202	will be used. If the current font is not a style, then the
		1203	current family is ignored. When the requests __cs__,
		1204	__bd__, __tkf__, __uf__, or __fspecial__ are
		1205	applied to a style, then they will instead be applied to the
		1206	member of the current family corresponding to that style.
		1207	The default family can be set with the __-f__ option. The
		1208	styles command in the DESC file controls
		1209	which font positions (if any) are initially associated with
		1210	styles rather than fonts.
		1211
		1212
		1213	__.substring__ ''xx n1''
		1214	__[[__''n2''__]__
		1215
		1216
		1217	Replace the string in register ''xx'' with the substring
		1218	defined by the indices ''n1'' and ''n2''. The first
		1219	character in the string has index one. If ''n2'' is
		1220	omitted, it is taken to be equal to the string's length. If
		1221	the index value ''n1'' or ''n2'' is negative or zero,
		1222	it will be counted from the end of the string, going
		1223	backwards: The last character has index 0, the character
		1224	before the last character has index -1, etc.
		1225
		1226
		1227	__.tkf__ ''f s1 n1 s2 n2''
		1228
		1229
		1230	Enable track kerning for font ''f''. When the current
		1231	font is ''f'' the width of every character will be
		1232	increased by an amount between ''n1'' and ''n2''; when
		1233	the current point size is less than or equal to ''s1''
		1234	the width will be increased by ''n1''; when it is greater
		1235	than or equal to ''s2'' the width will be increased by
		1236	''n2''; when the point size is greater than or equal to
		1237	''s1'' and less than or equal to ''s2'' the increase
		1238	in width is a linear function of the point
		1239	size.
		1240
		1241
		1242	__.tm1__ ''string''
		1243
		1244
		1245	Similar to the __tm__ request, ''string'' is read in
		1246	copy mode and written on the standard error, but an initial
		1247	double quote in ''string'' is stripped off to allow
		1248	initial blanks.
		1249
		1250
		1251	__.tmc__ ''string''
		1252
		1253
		1254	Similar to __tm1__ but without writing a final
		1255	newline.
		1256
		1257
		1258	__.trf__ ''filename''
		1259
		1260
		1261	Transparently output the contents of file ''filename''.
		1262	Each line is output as it would be were it preceded by
		1263	__!__; however, the lines are not subject to copy-mode
		1264	interpretation. If the file does not end with a newline,
		1265	then a newline will be added. For example, you can define a
		1266	macro ''x'' containing the contents of file ''f'',
		1267	using
		1268
		1269
		1270	__.di__ ''x''__
		1271	.trf__ ''f''__
		1272	.di__
		1273
		1274
		1275	Unlike with the __cf__ request, the file cannot contain
		1276	characters such as NUL that are not legal
		1277	troff input characters.
		1278
		1279
		1280	__.trnt abcd__
		1281
		1282
		1283	This is the same as the __tr__ request except that the
		1284	translations do not apply to text that is transparently
		1285	throughput into a diversion with __!__. For
		1286	example,
		1287
		1288
		1289	__.tr ab
		1290	.di x
		1291	!.tm a
		1292	.di
		1293	.x
		1294	__
		1295
		1296
		1297	will print __b__; if __trnt__ is used instead of
		1298	__tr__ it will print __a__.
		1299
		1300
		1301	__.troff__
		1302
		1303
		1304	Make the __n__ built-in condition false, and the __t__
		1305	built-in condition true. This undoes the effect of the
		1306	__nroff__ request.
		1307
		1308
		1309	__.unformat__ ''xx''
		1310
		1311
		1312	This request `unformats' the diversion ''xx''. Contrary
		1313	to the __.asciify__ request, which tries to convert
		1314	formatted elements of the diversion back to input tokens as
		1315	much as possible, __.unformat__ will only handle tabs and
		1316	spaces between words (usually caused by spaces or newlines
		1317	in the input) specially. The former are treated as if they
		1318	were input tokens, and the latter are stretchable again.
		1319	Note that the vertical size of lines is not preserved. Glyph
		1320	information (font, font size, space width, etc.) is
		1321	retained. Useful in conjunction with the __.box__ and
		1322	__.boxa__ requests.
		1323
		1324
		1325	__.vpt__ ''n''
		1326
		1327
		1328	Enable vertical position traps if ''n'' is non-zero,
		1329	disable them otherwise. Vertical position traps are traps
		1330	set by the __wh__ or __dt__ requests. Traps set by the
		1331	__it__ request are not vertical position traps. The
		1332	parameter that controls whether vertical position traps are
		1333	enabled is global. Initially vertical position traps are
		1334	enabled.
		1335
		1336
		1337	__.warn__ ''n''
		1338
		1339
		1340	Control warnings. ''n'' is the sum of the numbers
		1341	associated with each warning that is to be enabled; all
		1342	other warnings will be disabled. The number associated with
		1343	each warning is listed in the `Warnings' section. For
		1344	example, __.warn 0__ will disable all warnings, and
		1345	__.warn 1__ will disable all warnings except that about
		1346	missing characters. If ''n'' is not given, all warnings
		1347	will be enabled.
		1348
		1349
		1350	__.while__ ''c anything''
		1351
		1352
		1353	While condition ''c'' is true, accept ''anything'' as
		1354	input; ''c'' can be any condition acceptable to an
		1355	__if__ request; ''anything'' can comprise multiple
		1356	lines if the first line starts with __{__ and the last
		1357	line ends with __}__. See also the __break__ and
		1358	__continue__ requests.
		1359
		1360
		1361	__.write__ ''stream anything''
		1362
		1363
		1364	Write ''anything'' to the stream named ''stream''.
		1365	''stream'' must previously have been the subject of an
		1366	__open__ request. ''anything'' is read in copy mode; a
		1367	leading ____ will be stripped.
		1368
		1369
		1370	__.writem__ ''stream xx''
		1371
		1372
		1373	Write the contents of the macro or string ''xx'' to the
		1374	stream named ''stream''. ''stream'' must previously
		1375	have been the subject of an __open__ request. ''xx''
		1376	is read in copy mode.
		1377
		1378
		1379	__Extended requests__
		1380
		1381
		1382	__.cf__ ''filename''
		1383
		1384
		1385	When used in a diversion, this will embed in the diversion
		1386	an object which, when reread, will cause the contents of
		1387	''filename'' to be transparently copied through to the
		1388	output. In UNIX troff, the contents of ''filename'' is
		1389	immediately copied through to the output regardless of
		1390	whether there is a current diversion; this behaviour is so
		1391	anomalous that it must be considered a bug.
		1392
		1393
		1394	__.ev__ ''xx''
		1395
		1396
		1397	If ''xx'' is not a number, this will switch to a named
		1398	environment called ''xx''. The environment should be
		1399	popped with a matching __ev__ request without any
		1400	arguments, just as for numbered environments. There is no
		1401	limit on the number of named environments; they will be
		1402	created the first time that they are
		1403	referenced.
		1404
		1405
		1406	__.fp__ ''n f1 f2''
		1407
		1408
		1409	The __fp__ request has an optional third argument. This
		1410	argument gives the external name of the font, which is used
		1411	for finding the font description file. The second argument
		1412	gives the internal name of the font which is used to refer
		1413	to the font in troff after it has been mounted. If there is
		1414	no third argument then the internal name will be used as the
		1415	external name. This feature allows you to use fonts with
		1416	long names in compatibility mode.
		1417
		1418
		1419	__.ss__ ''m n''
		1420
		1421
		1422	When two arguments are given to the __ss__ request, the
		1423	second argument gives the ''sentence space size''. If the
		1424	second argument is not given, the sentence space size will
		1425	be the same as the word space size. Like the word space
		1426	size, the sentence space is in units of one twelfth of the
		1427	spacewidth parameter for the current font. Initially both
		1428	the word space size and the sentence space size are 12.
		1429	Contrary to UNIX troff, GNU troff handles this request in
		1430	nroff mode also; a given value is then rounded down to the
		1431	nearest multiple of 12. The sentence space size is used in
		1432	two circumstances: if the end of a sentence occurs at the
		1433	end of a line in fill mode, then both an inter-word space
		1434	and a sentence space will be added; if two spaces follow the
		1435	end of a sentence in the middle of a line, then the second
		1436	space will be a sentence space. Note that the behaviour of
		1437	UNIX troff will be exactly that exhibited by GNU troff if a
		1438	second argument is never given to the __ss__ request. In
		1439	GNU troff, as in UNIX troff, you should always follow a
		1440	sentence with either a newline or two spaces.
		1441
		1442
		1443	__.ta__ ''n1 n2...nn'' __T__ ''r1
		1444	r2...rn''
		1445
		1446
		1447	Set tabs at positions ''n1'', ''n2'',..., ''nn''
		1448	and then set tabs at ''nn''+''r1'',
		1449	''nn''+''r2'',...., ''nn''+''rn'' and then at
		1450	''nn''+''rn''+''r1'',
		1451	''nn''+''rn''+''r2'',...,
		1452	''nn''+''rn''+''rn'', and so on. For
		1453	example,
		1454
		1455
		1456	__.ta T .5i__
		1457
		1458
		1459	will set tabs every half an inch.
		1460
		1461
		1462	__New number registers__
		1463
		1464
		1465	The following read-only registers are
		1466	available:
		1467
		1468
		1469	__n[[.C]__
		1470
		1471
		1472	1 if compatibility mode is in effect, 0
		1473	otherwise.
		1474
		1475
		1476	__n[[.cdp]__
		1477
		1478
		1479	The depth of the last character added to the current
		1480	environment. It is positive if the character extends below
		1481	the baseline.
		1482
		1483
		1484	__n[[.ce]__
		1485
		1486
		1487	The number of lines remaining to be centered, as set by the
		1488	__ce__ request.
		1489
		1490
		1491	__n[[.cht]__
		1492
		1493
		1494	The height of the last character added to the current
		1495	environment. It is positive if the character extends above
		1496	the baseline.
		1497
		1498
		1499	__n[[.csk]__
		1500
		1501
		1502	The skew of the last character added to the current
		1503	environment. The ''skew'' of a character is how far to
		1504	the right of the center of a character the center of an
		1505	accent over that character should be placed.
		1506
		1507
		1508	__n[[.ev]__
		1509
		1510
		1511	The name or number of the current environment. This is a
		1512	string-valued register.
		1513
		1514
		1515	__n[[.fam]__
		1516
		1517
		1518	The current font family. This is a string-valued
		1519	register.
		1520
		1521
		1522	__n[[.fp]__
		1523
		1524
		1525	The number of the next free font position.
		1526
		1527
		1528	__n[[.g]__
		1529
		1530
		1531	Always 1. Macros should use this to determine whether they
		1532	are running under GNU troff.
		1533
		1534
		1535	__n[[.hla]__
		1536
		1537
		1538	The current hyphenation language as set by the __hla__
		1539	request.
		1540
		1541
		1542	__n[[.hlc]__
		1543
		1544
		1545	The number of immediately preceding consecutive hyphenated
		1546	lines.
		1547
		1548
		1549	__n[[.hlm]__
		1550
		1551
		1552	The maximum allowed number of consecutive hyphenated lines,
		1553	as set by the __hlm__ request.
		1554
		1555
		1556	__n[[.hy]__
		1557
		1558
		1559	The current hyphenation flags (as set by the __hy__
		1560	request).
		1561
		1562
		1563	__n[[.hym]__
		1564
		1565
		1566	The current hyphenation margin (as set by the __hym__
		1567	request).
		1568
		1569
		1570	__n[[.hys]__
		1571
		1572
		1573	The current hyphenation space (as set by the __hys__
		1574	request).
		1575
		1576
		1577	__n[[.in]__
		1578
		1579
		1580	The indent that applies to the current output
		1581	line.
		1582
		1583
		1584	__n[[.int]__
		1585
		1586
		1587	Set to a positive value if last output line is interrupted
		1588	(i.e., if it contains ''c'').
		1589
		1590
		1591	__n[[.kern]__
		1592
		1593
		1594	__1__ if pairwise kerning is enabled, __0__
		1595	otherwise.
		1596
		1597
		1598	__n[[.lg]__
		1599
		1600
		1601	The current ligature mode (as set by the __lg__
		1602	request).
		1603
		1604
		1605	__n[[.linetabs]__
		1606
		1607
		1608	The current line-tabs mode (as set by the __linetabs__
		1609	request).
		1610
		1611
		1612	__n[[.ll]__
		1613
		1614
		1615	The line length that applies to the current output
		1616	line.
		1617
		1618
		1619	__n[[.lt]__
		1620
		1621
		1622	The title length as set by the __lt__
		1623	request.
		1624
		1625
		1626	__n[[.ne]__
		1627
		1628
		1629	The amount of space that was needed in the last __ne__
		1630	request that caused a trap to be sprung. Useful in
		1631	conjunction with the __n[[.trunc]__ register.
		1632
		1633
		1634	__n[[.ns]__
		1635
		1636
		1637	__1__ if no-space mode is active, __0__
		1638	otherwise.
		1639
		1640
		1641	__n[[.pn]__
		1642
		1643
		1644	The number of the next page: either the value set by a
		1645	__pn__ request, or the number of the current page plus
		1646	1.
		1647
		1648
		1649	__n[[.ps]__
		1650
		1651
		1652	The current pointsize in scaled points.
		1653
		1654
		1655	__n[[.psr]__
		1656
		1657
		1658	The last-requested pointsize in scaled points.
		1659
		1660
		1661	__n[[.rj]__
		1662
		1663
		1664	The number of lines to be right-justified as set by the
		1665	__rj__ request.
		1666
		1667
		1668	__n[[.sr]__
		1669
		1670
		1671	The last requested pointsize in points as a decimal
		1672	fraction. This is a string-valued register.
		1673
		1674
		1675	__n[[.tabs]__
		1676
		1677
		1678	A string representation of the current tab settings suitable
		1679	for use as an argument to the __ta__
		1680	request.
		1681
		1682
		1683	__n[[.trunc]__
		1684
		1685
		1686	The amount of vertical space truncated by the most recently
		1687	sprung vertical position trap, or, if the trap was sprung by
		1688	a __ne__ request, minus the amount of vertical motion
		1689	produced by the __ne__ request. In other words, at the
		1690	point a trap is sprung, it represents the difference of what
		1691	the vertical position would have been but for the trap, and
		1692	what the vertical position actually is. Useful in
		1693	conjunction with the __n[[.ne]__ register.
		1694
		1695
		1696	__n[[.ss]__
		1697
		1698
		1699	__n[[.sss]__
		1700
		1701
		1702	These give the values of the parameters set by the first and
		1703	second arguments of the __ss__ request.
		1704
		1705
		1706	__n[[.vpt]__
		1707
		1708
		1709	1 if vertical position traps are enabled, 0
		1710	otherwise.
		1711
		1712
		1713	__n[[.warn]__
		1714
		1715
		1716	The sum of the numbers associated with each of the currently
		1717	enabled warnings. The number associated with each warning is
		1718	listed in the `Warnings' subsection.
		1719
		1720
		1721	__n[[.x]__
		1722
		1723
		1724	The major version number. For example, if the version number
		1725	is __1.03__ then __n[[.x]__ will contain
		1726	__1__.
		1727
		1728
		1729	__n[[.y]__
		1730
		1731
		1732	The minor version number. For example, if the version number
		1733	is __1.03__ then __n[[.y]__ will contain
		1734	__03__.
		1735
		1736
		1737	__n[[.Y]__
		1738
		1739
		1740	The revision number of groff.
		1741
		1742
		1743	__n[[llx]__
		1744
		1745
		1746	__n[[lly]__
		1747
		1748
		1749	__n[[urx]__
		1750
		1751
		1752	__n[[ury]__
		1753
		1754
		1755	These four registers are set by the __.psbb__ request and
3	perry	1756	contain the bounding box values (in !PostScript units) of a
		1757	given !PostScript image.
1	perry	1758
		1759
		1760	The following read/write registers are set by the __w__
		1761	escape sequence:
		1762
		1763
		1764	__n[[rst]__
		1765
		1766
		1767	__n[[rsb]__
		1768
		1769
		1770	Like the __st__ and __sb__ registers, but takes
		1771	account of the heights and depths of
		1772	characters.
		1773
		1774
		1775	__n[[ssc]__
		1776
		1777
		1778	The amount of horizontal space (possibly negative) that
		1779	should be added to the last character before a
		1780	subscript.
		1781
		1782
		1783	__n[[skw]__
		1784
		1785
		1786	How far to right of the center of the last character in the
		1787	__w__ argument, the center of an accent from a roman font
		1788	should be placed over that character.
		1789
		1790
		1791	Other available read/write number registers
		1792	are:
		1793
		1794
		1795	__n[[c.]__
		1796
		1797
		1798	The current input line number. __n[[.c]__ is a read-only
		1799	alias to this register.
		1800
		1801
		1802	__n[[hp]__
		1803
		1804
		1805	The current horizontal position at input line.
		1806
		1807
		1808	__n[[systat]__
		1809
		1810
		1811	The return value of the system() function executed by the
		1812	last __sy__ request.
		1813
		1814
		1815	__n[[slimit]__
		1816
		1817
		1818	If greater than 0, the maximum number of objects on the
		1819	input stack. If less than or equal to 0, there is no limit
		1820	on the number of objects on the input stack. With no limit,
		1821	recursion can continue until virtual memory is
		1822	exhausted.
		1823
		1824
		1825	__n[[year]__
		1826
		1827
		1828	The current year. Note that the traditional __troff__
		1829	number register __n[[yr]__ is the current year minus
		1830	1900.
		1831
		1832
		1833	__Miscellaneous__
		1834
		1835
		1836	__troff__ predefines a single (read/write) string-based
		1837	register, __*(.T__, which contains the argument given to
		1838	the __-T__ command line option, namely the current output
		1839	device (for example, ''latin1'' or ''ascii''). Note
		1840	that this is not the same as the (read-only) number register
		1841	__n[[.T]__ which is defined to be 1 if __troff__ is
		1842	called with the __-T__ command line option, and zero
		1843	otherwise. This behaviour is different to UNIX
		1844	troff.
		1845
		1846
		1847	Fonts not listed in the DESC file are
		1848	automatically mounted on the next available font position
		1849	when they are referenced. If a font is to be mounted
		1850	explicitly with the __fp__ request on an unused font
		1851	position, it should be mounted on the first unused font
		1852	position, which can be found in the __n[[.fp]__ register;
		1853	although __troff__ does not enforce this strictly, it
		1854	will not allow a font to be mounted at a position whose
		1855	number is much greater than that of any currently used
		1856	position.
		1857
		1858
		1859	Interpolating a string does not hide existing macro
		1860	arguments. Thus in a macro, a more efficient way of
		1861	doing
		1862
		1863
		1864	__.__''xx'' __\$@__
		1865
		1866
		1867	is
		1868
		1869
		1870	__\*[[__''xx''__]\__
		1871
		1872
		1873	If the font description file contains pairwise kerning
		1874	information, characters from that font will be kerned.
		1875	Kerning between two characters can be inhibited by placing a
		1876	____ between them.
		1877
		1878
		1879	In a string comparison in a condition, characters that
		1880	appear at different input levels to the first delimiter
		1881	character will not be recognised as the second or third
		1882	delimiters. This applies also to the __tl__ request. In a
		1883	__w__ escape sequence, a character that appears at a
		1884	different input level to the starting delimiter character
		1885	will not be recognised as the closing delimiter character.
		1886	When decoding a macro argument that is delimited by double
		1887	quotes, a character that appears at a different input level
		1888	to the starting delimiter character will not be recognised
		1889	as the closing delimiter character. The implementation of
		1890	__$@__ ensures that the double quotes surrounding an
		1891	argument will appear the same input level, which will be
		1892	different to the input level of the argument itself. In a
		1893	long escape name __]__ will not be recognized as a
		1894	closing delimiter except when it occurs at the same input
		1895	level as the opening __]__. In compatibility mode, no
		1896	attention is paid to the input-level.
		1897
		1898
		1899	There are some new types of condition:
		1900
		1901
		1902	__.if r__''xxx''
		1903
		1904
		1905	True if there is a number register named
		1906	''xxx''.
		1907
		1908
		1909	__.if d__''xxx''
		1910
		1911
		1912	True if there is a string, macro, diversion, or request
		1913	named ''xxx''.
		1914
		1915
		1916	__.if c__''ch''
		1917
		1918
		1919	True if there is a character ''ch'' available; ''ch''
		1920	is either an ASCII character or a special
		1921	character ____''xx'' or __[[__''xxx''__]__;
		1922	the condition will also be true if ''ch'' has been
		1923	defined by the __char__ request.
		1924
		1925
		1926	The __tr__ request can now map characters onto
		1927	__~__.
		1928
		1929
		1930	__Warnings__
		1931
		1932
		1933	The warnings that can be given by __troff__ are divided
		1934	into the following categories. The name associated with each
		1935	warning is used by the __-w__ and __-W__ options; the
		1936	number is used by the __warn__ request, and by the
		1937	__.warn__ register.
		1938
		1939
		1940	__char__ 1
		1941
		1942
		1943	Non-existent characters. This is enabled by
		1944	default.
		1945
		1946
		1947	__number__ 2
		1948
		1949
		1950	Invalid numeric expressions. This is enabled by
		1951	default.
		1952
		1953
		1954	__break__ 4
		1955
		1956
		1957	In fill mode, lines which could not be broken so that their
		1958	length was less than the line length. This is enabled by
		1959	default.
		1960
		1961
		1962	__delim__ 8
		1963
		1964
		1965	Missing or mismatched closing delimiters.
		1966
		1967
		1968	__el__ 16
		1969
		1970
		1971	Use of the __el__ request with no matching __ie__
		1972	request.
		1973
		1974
		1975	__scale__ 32
		1976
		1977
		1978	Meaningless scaling indicators.
		1979
		1980
		1981	__range__ 64
		1982
		1983
		1984	Out of range arguments.
		1985
		1986
		1987	__syntax__ 128
		1988
		1989
		1990	Dubious syntax in numeric expressions.
		1991
		1992
		1993	__di__ 256
		1994
		1995
		1996	Use of __di__ or __da__ without an argument when there
		1997	is no current diversion.
		1998
		1999
		2000	__mac__ 512
		2001
		2002
		2003	Use of undefined strings, macros and diversions. When an
		2004	undefined string, macro or diversion is used, that string is
		2005	automatically defined as empty. So, in most cases, at most
		2006	one warning will be given for each name.
		2007
		2008
		2009	__reg__ 1024
		2010
		2011
		2012	Use of undefined number registers. When an undefined number
		2013	register is used, that register is automatically defined to
		2014	have a value of 0. a definition is automatically made with a
		2015	value of 0. So, in most cases, at most one warning will be
		2016	given for use of a particular name.
		2017
		2018
		2019	__tab__ 2048
		2020
		2021
		2022	Inappropriate use of a tab character. Either use of a tab
		2023	character where a number was expected, or use of tab
		2024	character in an unquoted macro argument.
		2025
		2026
		2027	__right-brace__ 4096
		2028
		2029
		2030	Use of __}__ where a number was expected.
		2031
		2032
		2033	__missing__ 8192
		2034
		2035
		2036	Requests that are missing non-optional
		2037	arguments.
		2038
		2039
		2040	__input__ 16384
		2041
		2042
		2043	Illegal input characters.
		2044
		2045
		2046	__escape__ 32768
		2047
		2048
		2049	Unrecognized escape sequences. When an unrecognized escape
		2050	sequence is encountered, the escape character is
		2051	ignored.
		2052
		2053
		2054	__space__ 65536
		2055
		2056
		2057	Missing space between a request or macro and its argument.
		2058	This warning will be given when an undefined name longer
		2059	than two characters is encountered, and the first two
		2060	characters of the name make a defined name. The request or
		2061	macro will not be invoked. When this warning is given, no
		2062	macro is automatically defined. This is enabled by default.
		2063	This warning will never occur in compatibility
		2064	mode.
		2065
		2066
		2067	__font__ 131072
		2068
		2069
		2070	Non-existent fonts. This is enabled by default.
		2071
		2072
		2073	__ig__ 262144
		2074
		2075
		2076	Illegal escapes in text ignored with the __ig__ request.
		2077	These are conditions that are errors when they do not occur
		2078	in ignored text.
		2079
		2080
		2081	There are also names that can be used to refer to groups of
		2082	warnings:
		2083
		2084
		2085	__all__
		2086
		2087
		2088	All warnings except __di__, __mac__ and __reg__. It
		2089	is intended that this covers all warnings that are useful
		2090	with traditional macro packages.
		2091
		2092
		2093	__w__
		2094
		2095
		2096	All warnings.
		2097
		2098
		2099	__Incompatibilities__
		2100
		2101
		2102	Long names cause some incompatibilities. UNIX troff will
		2103	interpret
		2104
		2105
		2106	__.dsabcd__
		2107
		2108
		2109	as defining a string __ab__ with contents __cd__.
		2110	Normally, GNU troff will interpret this as a call of a macro
		2111	named __dsabcd__. Also UNIX troff will interpret
		2112	__*[[__ or __n[[__ as references to a string or number
		2113	register called __[[__. In GNU troff, however, this will
		2114	normally be interpreted as the start of a long name. In
		2115	''compatibility mode'' GNU troff will interpret these
		2116	things in the traditional way. In compatibility mode,
		2117	however, long names are not recognised. Compatibility mode
		2118	can be turned on with the __-C__ command line option, and
		2119	turned on or off with the __cp__ request. The number
		2120	register __n[[.C]__ is 1 if compatibility mode is on, 0
		2121	otherwise.
		2122
		2123
		2124	GNU troff does not allow the use of the escape sequences
		2125	__\|^__(space)__'`-_!%c__ in names of strings,
		2126	macros, diversions, number registers, fonts or environments;
		2127	UNIX troff does. The __A__ escape sequence may be helpful
		2128	in avoiding use of these escape sequences in
		2129	names.
		2130
		2131
		2132	Fractional pointsizes cause one noteworthy incompatibility.
		2133	In UNIX troff the __ps__ request ignores scale indicators
		2134	and so
		2135
		2136
		2137	__.ps 10u__
		2138
		2139
		2140	will set the pointsize to 10 points, whereas in GNU troff it
		2141	will set the pointsize to 10 scaled points.
		2142
		2143
		2144	In GNU troff there is a fundamental difference between
		2145	unformatted, input characters, and formatted, output
		2146	characters. Everything that affects how an output character
		2147	will be output is stored with the character; once an output
		2148	character has been constructed it is unaffected by any
		2149	subsequent requests that are executed, including __bd__,
		2150	__cs__, __tkf__, __tr__, or __fp__ requests.
		2151	Normally output characters are constructed from input
		2152	characters at the moment immediately before the character is
		2153	added to the current output line. Macros, diversions and
		2154	strings are all, in fact, the same type of object; they
		2155	contain lists of input characters and output characters in
		2156	any combination. An output character does not behave like an
		2157	input character for the purposes of macro processing; it
		2158	does not inherit any of the special properties that the
		2159	input character from which it was constructed might have
		2160	had. For example,
		2161
		2162
		2163	__.di x
		2164	\\
		2165	.br
		2166	.di
		2167	.x
		2168	__
		2169
		2170
		2171	will print __\__ in GNU troff; each pair of input
		2172	__\__s is turned into one output __\__ and the
		2173	resulting output __\__s are not interpreted as escape
		2174	characters when they are reread. UNIX troff would interpret
		2175	them as escape characters when they were reread and would
		2176	end up printing one __\__. The correct way to obtain a
		2177	printable __\__ is to use the __e__ escape sequence:
		2178	this will always print a single instance of the current
		2179	escape character, regardless of whether or not it is used in
		2180	a diversion; it will also work in both GNU troff and UNIX
		2181	troff. If you wish for some reason to store in a diversion
		2182	an escape sequence that will be interpreted when the
		2183	diversion is reread, you can either use the traditional
		2184	__!__ transparent output facility, or, if this is
		2185	unsuitable, the new __?__ escape sequence.
		2186	!!ENVIRONMENT
		2187
		2188
		2189	__GROFF_TMAC_PATH__
		2190
		2191
		2192	A colon separated list of directories in which to search for
		2193	macro files. __troff__ will scan directories given in the
		2194	__-M__ option before these, and in standard directories
		2195	(current directory if in unsafe mode, home directory,
		2196	__/usr/share/groff/site-tmac__,
		2197	__/usr/lib/groff/site-tmac__,
		2198	__/usr/share/groff/1.17.2/tmac__) after
		2199	these.
		2200
		2201
		2202	__GROFF_TYPESETTER__
		2203
		2204
		2205	Default device.
		2206
		2207
		2208	__GROFF_FONT_PATH__
		2209
		2210
		2211	A colon separated list of directories in which to search for
		2212	the __dev__''name'' directory. __troff__ will scan
		2213	directories given in the __-F__ option before these, and
		2214	in standard directories
		2215	(__/usr/share/groff/1.17.2/font:/usr/lib/font__) after
		2216	these.
		2217	!!FILES
		2218
		2219
		2220	__/usr/share/groff/1.17.2/tmac/troffrc__
		2221
		2222
		2223	Initialization file (called before any other macro
		2224	package).
		2225
		2226
		2227	__/usr/share/groff/1.17.2/tmac/troffrc-end__
		2228
		2229
		2230	Initialization file (called after any other macro
		2231	package).
		2232
		2233
		2234	__/usr/share/groff/1.17.2/tmac/__''name''__.tmac__
		2235
		2236
		2237	__/usr/share/groff/1.17.2/tmac/tmac.__''name''
		2238
		2239
		2240	Macro files
		2241
		2242
		2243	__/usr/share/groff/1.17.2/font/dev__''name''__/DESC__
		2244
		2245
		2246	Device description file for device ''name''.
		2247
		2248
		2249	__/usr/share/groff/1.17.2/font/dev__''name''__/__''F''
		2250
		2251
		2252	Font file for font ''F'' of device
		2253	''name''.
		2254
		2255
		2256	Note that __troffrc__ and __troffrc-end__ are neither
		2257	searched in the current nor in the home directory by default
		2258	for security reasons (even if the __-U__ option is
		2259	given). Use the __-M__ command line option or the
		2260	__GROFF_TMAC_PATH__ environment variable to add these
		2261	directories to the search path if necessary.
		2262	!!SEE ALSO
		2263
		2264
		2265	groff(7) -- This is a short but complete reference of
		2266	all requests, registers, and escapes.
		2267
		2268
		2269	groff(1), tbl(1), pic(1),
		2270	eqn(1), refer(1), soelim(1),
		2271	grn(1), grops(1), grodvi(1),
4	perry	2272	grotty(1), grohtml(1), grolj4(1),
		2273	groff_font(5), __groff_out__(5),
		2274	groff_char(7)
1	perry	2275	----