5
This file is part of groff, the GNU roff type-setting system.
7
Copyright (C) 2000, 2001 Free Software Foundation, Inc.
8
written by Bernd Warken <bwarken@mayn.de>
10
Permission is granted to copy, distribute and/or modify this document
11
under the terms of the GNU Free Documentation License, Version 1.1 or
12
any later version published by the Free Software Foundation; with the
13
Invariant Sections being this .ig-section and AUTHOR, with no
14
Front-Cover Texts, and with no Back-Cover Texts.
16
A copy of the Free Documentation License is included as a file called
17
FDL in the main directory of the groff source package.
20
.\" --------------------------------------------------------------------
22
.\" --------------------------------------------------------------------
35
.\" a comment macro which does nothing
44
.c text lines in macro definitions or bracketed sections \{...\}
50
. ds @tmp@ \f(CB\$1\fP
56
.als shellcommand option
58
.c --------- characters ---------
61
. ds @tmp@ \f(CB\$1\fP
68
. ds @tmp@ \(oq\f(CB\$1\fP\(cq
75
. ds @tmp@ \(lq\f(CB\$1\fP\(rq
81
.c --------- requests ---------
87
. IP "\f(CB\&\*[@tmp@] \fP\f(CI\&\$*\fP" 10n
92
. ds @tmp@ \f(CB\$1\fP
98
.c --------- macro or function arguments ---------
101
. ds @tmp@ \f(CI\$1\fP
103
. while (\n[.$] >= 2) \{\
104
. as @tmp@ \/\f(CR\$1\fP\f(CI\,\$2\fP
107
. if \n[.$] .as @tmp@ \/\f(CR\$1\fP
112
.c argument followed by a numerical expression
114
. ds @tmp@ \f(CI\$1\fP\|\f(CR\$2\fP
120
.c --------- numerical elements ---------
123
. ds @tmp@ \f(CR\$1\fP
130
. ds @tmp@ \&\$1\ \f(CR\$2\fP
136
.als scaleindicator request
139
. ds @tmp@ \f(CR\$1\fP\f(CB\$2\fP
146
. ds @tmp@ \(oq\f(CB\$1\fP\(cq
152
.c --------- escape sequences ---------
155
. ds @tmp@ \f(CB\(rs\$1[\fP\f(CI\$2\fP\f(CB]\fP
162
. ds @tmp@ \f(CB\(rs\$1(\fP\f(CI\$2\fP
169
. ds @tmp@ \f(CB\(rs\$1\fP\f(CI\$2\fP
176
. ds @tmp@ \f(CB\(rs[\fP\f(CI\$1\fP\f(CB]\fP
183
. ds @tmp@ \f(CB\(rs(\fP\f(CI\$1\fP
190
. ds @tmp@ \f(CB\(rs\$1\fP
197
. ds @tmp@ \f(CB\(rs(\$1\fP
204
. ds @tmp@ \f(CB\(rs[\$1]\fP
210
.c escape sequence synopsis
214
. IP "\f(CB\(rs\&\*[@tmp@]\fP\f(CI\&\$*\fP"
218
.c synopsis for escape sequences with a long name
223
. IP "\f(CB\(rs\&\*[@arg1@][\fP\f(CI\&\*[@arg2@]\fP\f(CB]\&\$*\fP"
228
.c synopsis escape sequence with quoted argument
232
. IP "\f(CB\(rs\&\*[@tmp@]\(cq\fP\f(CI\h'-0.2m'\$*\/\fP\f(CB\(cq\fP"
236
.c synopsis for 2-escapes (special characters)
240
. text \f(CB\(rs(\&\*[@tmp@]\ \ \ \fP\fR\(\*[@tmp@]\fP
246
.c --------- registers ---------
248
.c synopsis for registers
251
. text \&\f(CR\(rsn[\fP\f(CB\$1\fP\f(CR]\fP
256
.als register request
258
.c --------- warnings ---------
262
.c description of warnings
273
.\" --------------------------------------------------------------------
275
.\" --------------------------------------------------------------------
277
.TH GROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
279
groff \- a short reference for the GNU roff language
281
.\" --------------------------------------------------------------------
283
.\" --------------------------------------------------------------------
287
and is the free implementation of the roff type-setting system.
290
for a survey and the background of the groff system.
292
This document gives only short descriptions of the predefined roff
293
language elements as used in groff.
294
Both the classical features and the groff extensions are provided.
301
is compatible with the classical system and provides proper extensions.
307
could be used as synonyms.
310
slightly tends to refer more to the classical aspects, whereas
312
emphasizes the GNU extensions, and
314
is the general term for the language.
316
This file is only a short version of the complete documentation that is
320
file, which contains more detailed, actual, and concise information.
322
The general syntax for writing groff documents is relatively easy, but
323
writing extensions to the roff language can be a bit harder.
325
The roff language is line-oriented.
326
There are only two kinds of lines, control lines and text lines.
327
The control lines start with a control character, by default a period
331
all other lines are text lines.
334
represent commands, optionally with arguments.
335
They have the following syntax.
336
The leading control character can be followed by a command name;
337
arguments, if any, are separated by blanks from the command name and
338
among themselves, for example,
341
\&\.command_name arg1 arg2
344
For indentation, any number of space or tab characters can be inserted
345
between the leading control character and the command name, but the control
346
character must be on the first position of the line.
349
represent the parts that will be printed.
350
They can be modified by escape sequences, which are recognized by a
353
These are in-line or even in-word formatting elements or functions.
354
Some of these take arguments separated by single quotes
356
others are regulated by a length encoding introduced by an open
359
or enclosed in brackets
364
The roff language provides flexible instruments for writing language
365
extension, such as macros.
366
When interpreting macro definitions, the roff system enters a special
367
operating mode, called the
370
The copy mode behavior can be quite tricky, but there are some rules
371
that ensure a safe usage.
373
Printable backslashes must be denoted as
377
represents the current escape character.
378
To get a backslash glyph, use
381
Double all backslashes.
383
Begin all text lines with the special non-spacing character
386
This does not produce the most efficient code, but it should work as a
388
For better strategies, see the groff info file and
389
.BR groff_tmac (@MAN5EXT@).
391
Reading roff source files is easier, just reduce all double backslashes
392
to a single one in all macro definitions.
394
.\" --------------------------------------------------------------------
396
.\" --------------------------------------------------------------------
397
The roff language elements add formatting information to a text file.
398
The fundamental elements are predefined commands and variables that make
399
roff a full-blown programming language.
401
There are two kinds of roff commands, possibly with arguments.
403
are written on a line of their own starting with a dot
409
are in-line functions and in-word formatting elements starting with a
413
The user can define her own formatting commands using the
415
request. These commands are called
417
but they are used exactly like requests. Macro packages are pre-defined
418
sets of macros written in the groff language.
419
A user's possibilities to create escape sequences herself is very
420
limited, only special characters can be mapped.
422
The groff language provides several kinds of variables with
423
different interfaces.
424
There are pre-defined variables, but the user can define her own
428
variables store character sequences.
429
They are set with the
431
request and retrieved by the
436
variables can store numerical values, numbers with a scale unit, and
437
occasionally string-like objects.
438
They are set with the
440
request and retrieved by the
445
allow the user to temporarily store global formatting parameters like
446
line length, font size, etc. for later reuse.
452
are identified either by a name or by an internal number.
453
The current font is chosen by the
458
Each device has special fonts, but the following fonts are available for
461
is the standard font Roman.
470
is everywhere available, but on text devices, it is displayed as an
471
underlined Roman font.
472
For the graphical output devices, there exist constant-width pendants of
478
On text devices, all characters have a constant width anyway.
480
Moreover, there are some advanced roff elements.
483
stores information into a macro for later usage.
486
is a positional condition like a certain number of lines from page top
487
or in a diversion or in the input.
488
Some action can be prescribed to be run automatically when the condition
491
More detailed information can be found in the groff info file.
493
.\" --------------------------------------------------------------------
494
.SH "CONTROL CHARACTERS"
495
.\" --------------------------------------------------------------------
496
There is a small set of characters that have a special controlling task
497
in certain conditions.
500
A dot is only special at the beginning of a line or after the
501
condition in the requests
507
There it is the control character that introduces a request (or macro).
508
The special behavior can be delayed by using the
513
request, the control character can be set to a different character,
516
a non-special character.
518
In all other positions, it just means a dot character.
519
In text paragraphs, it is advantageous to start each sentence at a line
523
The single quote has two controlling tasks. At the beginning of a line
524
and in the conditional requests it is the non-breaking control
526
That means that it introduces a request like the dot, but with the
527
additional property that this request doesn't cause a linebreak.
530
request, the non-break control character can be set to a different
533
As a second task, it is the most commonly used argument separator in
534
some functional escape sequences (but any pair of characters not part
535
of the argument will work).
536
In all other positions, it denotes the single quote or apostrophe
538
Groff provides a printable representation with the
543
The double quote is used to enclose arguments in requests and macros. In
548
requests, a leading double quote in the argument will be stripped off,
549
making everything else afterwards the string to be defined (enabling leading
551
The escaped double quote
553
introduces a comment.
554
Otherwise, it is not special.
555
Groff provides a printable representation with the
560
The backslash usually introduces an escape sequence (this can be
564
A printed version of the escape character is the
566
escape; a backslash glyph can be obtained by
570
The open parenthesis is only special in escape sequences when
571
introducing an escape name or argument consisting of exactly two
573
In groff, this behavior can be replaced by the \f(CB[]\fP construct.
576
The opening bracket is only special in groff escape sequences; there it
577
is used to introduce a long escape name or long escape argument.
578
Otherwise, it is non-special, e.g. in macro calls.
581
The closing bracket is only special in groff escape sequences; there it
582
terminates a long escape name or long escape argument.
583
Otherwise, it is non-special.
586
Space characters are only functional characters. They separate the
587
arguments in requests or macros, and the words in text lines.
588
They are subject to groff's horizontal spacing calculations.
589
To get a defined space width, escape sequences like
591
(this is the escape character followed by a space),
598
In text paragraphs, newlines mostly behave like space characters.
599
Continuation lines can be specified by an escaped newline, i.e., by
600
specifying a backslash
602
as the last character of a line.
604
If a tab character occurs during text the interpreter makes a horizontal
605
jump to the next pre-defined tab position.
606
There is a sophisticated interface for handling tab positions.
608
.\" --------------------------------------------------------------------
609
.SH "NUMERICAL EXPRESSIONS"
610
.\" --------------------------------------------------------------------
613
is a signed or unsigned integer or float with or without an appended
617
is a one-character abbreviation for a unit of measurement.
618
A number followed by a scale indicator signifies a size value.
619
By default, numerical values do not have a scale indicator, i.e., they are
622
The roff language defines the following scale indicators.
631
P@Pica\ \(eq\ 1/6\ inch
632
p@Point\ \(eq\ 1/72\ inch
634
Em\ \(eq\ \fRthe font size in points (width of letter `\f(CRm\fR')
636
M@100th \fRof an \f(CREm
638
u@\fRBasic unit for actual output device
639
v@\fRVertical line space in basic units
641
scaled point\ \(eq\ 1/\f(CIsizescale\fR of a point (defined in
642
font \fIDESC\fP file)
648
.B Numerical expressions
649
are combinations of the numerical values defined above with
650
the arithmetical operators
657
the comparative operators
665
the logical operators
679
added the following operators for numerical expressions:
686
e1\f(CB>?\fPe2@The maximum of \f(CIe1\fP and \f(CIe2\fP.
687
e1\f(CB<?\fPe2@The minimum of \f(CIe1\fP and \f(CIe2\fP.
688
\f(CB(\fPc\f(CB;\fPe\f(CB)@T{
689
Evaluate \f(CIe\fP using \f(CIc\fP as the default scaling
696
For details see the groff info file.
698
.\" --------------------------------------------------------------------
700
.\" --------------------------------------------------------------------
702
occur in tests raised by the
708
The following table characterizes the different types of conditions.
716
A numerical expression \f(CIN\fP yields true if its value
720
True if the value of \f(CIN\fP is\ \f(CR\(<=0\fP.
722
\&'\f(CIs1\fP'\f(CIs2\fP'@T{
723
True if string\ \f(CIs1\fP is identical to string\ \f(CIs2\fP.
725
!'\f(CIs1\fP'\f(CIs2\fP'@T{
726
True if string\ \f(CIs1\fP is not identical to string\ \f(CIs2\fP.
729
True if there is a character\ \f(CIch\fP available.
732
True if there is a string, macro, diversion, or request
735
e@Current page number is even.
736
o@Current page number is odd.
737
n@Formatter is \fBnroff\fP.
739
True if there is a register named \f(CIreg\fP.
741
t@Formatter is \fBtroff\fR.
747
.\" --------------------------------------------------------------------
749
.\" --------------------------------------------------------------------
750
This section provides a short reference for the predefined requests.
751
In groff, request and macro names can be arbitrarily long.
752
No bracketing or marking of long names is needed.
754
Most requests take one or more arguments.
755
The arguments are separated by space characters (no tabs!); there is no
756
inherent limit for their length or number.
757
An argument can be enclosed by a pair of double quotes: This is very handy
758
if an argument contains space characters, e.g.,
759
.argument "\(dqarg\ with\ space\(dq"
760
denotes a single argument.
762
Some requests have optional arguments with a different behaviour.
763
Not all of these details are outlined here.
764
Refer to the groff info file for all details.
766
In the following request specifications, most argument names were chosen
768
Only the following denotations need clarification.
775
c@denotes a single character.
777
a font either specified as a font name or a font number.
780
all characters up to the end of the line or within \f(CB\(rs{\fP
784
is a numerical expression that evaluates to an integer value.
787
is an arbitrary numerical expression, signed or unsigned.
790
has three meanings depending on its sign, described below.
796
If an expression defined as
800
sign the resulting value of the expression will be added to an already
801
existing value inherent to the related request, e.g. adding to a number
803
If the expression starts with a
805
the value of the expression will be subtracted from the request value.
809
replaces the existing value directly.
810
To assign a negative number either prepend\ \c
812
or enclose the negative number in parentheses.
814
.\" --------------------------------------------------------------------
815
.SS "REQUEST SHORT REFERENCE"
816
.\" --------------------------------------------------------------------
820
Empty line, ignored. Useful for structuring documents.
822
.REQ .\(rs\(dq anything
823
Complete line is a comment.
828
on standard error, exit program.
831
Begin line adjustment for output lines in current adjust mode.
834
Start line adjustment in mode
836
(\f(CIc\fP\f(CR\|\^\(eq\|l,r,b,n\fP).
843
(\f(CIc\fP\f(CR\|\^\(eq\|l,i,I,a,A\fP).
845
.REQ .aln alias register
846
Create alias name for
849
.REQ .als alias object
850
Create alias name for request, string, macro, or diversion
870
but with compatibility mode switched off during macro expansion.
875
but with compatibility mode switched off during macro expansion.
877
.REQ .as stringvar anything
881
.argument stringvar .
883
.REQ .asciify diversion
884
Unformat ASCII characters, spaces, and some escape sequences in
885
.argument diversion .
888
Print a backtrace of the input on stderr.
898
Embolden Special Font
904
Unset the blank line macro.
907
Set the blank line macro to
911
End current diversion.
916
omitting a partially filled line.
919
End current diversion.
924
omitting a partially filled line.
927
Eject current page and begin new page.
930
Eject current page; next page number
937
Break and spread output line.
942
Break out of a while loop.
945
Reset no-break control character to
949
Set no-break control character to
953
Reset control character to
957
Set control character to
961
Center the next input line.
969
Copy contents of file
971
unprocessed to stdout or to the diversion.
973
.REQ .cflags mode c1 c2 ...
989
.REQ .char c anything
996
Chop the last character off macro, string, or diversion
1004
Finish the current iteration of a while loop.
1007
Enable compatibility mode.
1012
is zero disable compatibility mode, otherwise enable it.
1015
Set constant character width mode for
1023
Continuous underline in nroff, like
1028
End current diversion.
1031
Divert and append to
1051
but with compatibility mode switched off during macro expansion.
1056
but with compatibility mode switched off during macro expansion.
1059
Define or redefine a macro whose name is contained in the string register
1066
Define or redefine a macro indirectly.
1070
are string registers whose contents are interpolated for the macro name
1071
and the end macro, respectively.
1074
End current diversion.
1083
with compatibility mode disabled.
1085
.REQ .ds stringvar anything
1089
.argument anything .
1092
Set diversion trap to position
1094
(default scale indicator\ \c
1095
.scaleindicator v ).
1098
Reset escape character to
1102
Set escape character to
1106
Restore escape character saved with
1110
Save current escape character.
1113
Else part for if-else (\c
1120
will be run after the end of input.
1123
Turn off escape character mechanism.
1126
Switch to previous environment.
1129
Push down environment number or name
1134
Copy the contents of environment
1136
to the current environment.
1137
No pushing or popping.
1140
Exit from roff processing.
1143
Return to previous font family.
1146
Set the current font family to
1150
Disable field mechanism.
1153
Set field delimiter to
1155
and pad character to space.
1157
Set field delimiter to
1159
and pad character to
1166
Flush output buffer.
1174
.REQ .fp n internal external
1175
Mount font with long
1182
.REQ .fspecial font s1 s2...
1183
When the current font is
1192
Return to previous font.
1196
Change to font name or number
1202
.REQ .ftr font1 font2
1209
Remove additional hyphenation indicator character.
1212
Set up additional hyphenation indicator character\ \c
1215
.REQ .hcode c1 code1 c2 code2 ...
1216
Set the hyphenation code of character
1227
Set the current hyphenation language to
1231
Set the maximum number of consecutive hyphenated lines to
1235
Read hyphenation patterns from
1241
with exceptional hyphenation.
1244
Switch to hyphenation mode
1248
Set the hyphenation margin to
1250
(default scale indicator\ \c
1251
.scaleindicator m ).
1254
Set the hyphenation space to
1257
.REQ .ie cond anything
1265
.REQ .if cond anything
1269
.argument anything ;
1270
otherwise do nothing.
1282
Change to previous indent value.
1285
Change indent according to
1287
(default scale indicator\ \c
1288
.scaleindicator m ).
1291
Set an input-line count trap at position
1295
Enable pairwise kerning.
1300
is zero, disable pairwise kerning, otherwise enable it.
1303
Remove leader repetition character.
1306
Set leader repetition character to\ \c
1309
.REQ .length register anything
1310
Write the length of the string
1313
.argument register .
1316
Enable line-tabs mode (i.e., calculate tab positions relative to output
1322
is zero, disable line-tabs mode, otherwise enable it.
1325
Set input line number to
1335
Change to previous line length.
1338
Set line length according to
1341
.scalednumber 6.5 i ,
1342
default scale indicator\ \c
1343
.scaleindicator m ).
1346
Change to the previous value of additional intra-line skip.
1349
Set additional intra-line skip value to
1353
blank lines are inserted after each text output line.
1356
Length of title (default scale indicator\ \c
1357
.scaleindicator m ).
1360
Margin character off.
1365
after each text line at actual distance from right margin.
1368
Set margin character to
1372
from right margin (default scale indicator\ \c
1373
.scaleindicator m ).
1376
Mark current vertical position in
1377
.argument register .
1380
The same as the .so request except that
1382
is searched in the tmac directories.
1385
No output-line adjusting.
1388
Need a one-line vertical space.
1393
vertical space (default scale indicator\ \c
1394
.scaleindicator v ).
1397
No filling or adjusting of output-lines.
1405
.REQ .nm \(+-N M S I
1406
In line number mode, set number, multiple, spacing, and indent.
1409
Do not number next line.
1418
.argument anything .
1420
.REQ .nr register \(+-N M
1429
Make the built-in condition
1436
Turn no-space mode on.
1441
.REQ .open stream filename
1444
for writing and associate the stream named
1448
.REQ .opena stream filename
1454
Output vertical distance that was saved by the
1459
Reset page number character to\ \c
1463
Page number character.
1471
Set page length to default
1472
.scalednumber 11 i .
1473
The current page length is stored in
1477
Change page length to
1479
(default scale indicator\ \c
1480
.scaleindicator v ).
1483
Print macro names and sizes (number of blocks of 128 bytes).
1486
Print only total of sizes of macros (number of 128 bytes blocks).
1493
Print the names and contents of all currently defined number registers
1497
Change to previous page offset. The current page offset is available in
1505
Return to previous point-size.
1511
Get the bounding box of a PostScript image
1512
.argument filename .
1515
This behaves like the
1517
request except that input comes from the standard output of
1521
Print the names and positions of all traps (not including input line
1522
traps and diversion traps) on stderr.
1524
.REQ .rchar c1 c2...
1525
Remove the definitions of characters
1534
Return from a macro.
1537
Right justify the next
1542
Remove request, macro, or string
1546
Rename request, macro, or string
1559
.argument register .
1562
Restore spacing; turn no-space mode off.
1567
to marked vertical place (default scale indicator\ \c
1568
.scaleindicator v ).
1571
Reset soft hyphen character to
1575
Set the soft hyphen character to
1579
In a macro, shift the arguments by
1584
Include source file.
1587
Skip one line vertically.
1590
Space vertical distance
1592
up or down according to sign of
1594
(default scaling indicator\ \c
1595
.scaleindicator v ).
1597
.REQ .special s1 s2 ...
1601
etc. are special and will be searched for characters not in the current font.
1604
Space-character size set to
1606
of the spacewidth in the current font.
1609
Space-character size set to
1611
and sentence space size set to
1613
of the spacewidth in the current font (\f(CR\(eq1/3 em\fP).
1621
.REQ .substring register n1 n2
1622
Replace the string in
1624
with the substring defined by the indices
1635
Save the vertical distance
1637
for later output with
1641
.REQ .sy command-line
1643
.argument command-line .
1646
Set tabs after every position that is a multiple of
1648
(default scaling indicator\ \c
1649
.scaleindicator m ).
1650
.REQ .ta n1 n2 ... nn \f(CBT\fP r1 r2 ... rn
1651
Set tabs at positions
1662
.argument nn + rn + r1 ,
1663
.argument nn + rn + r2 ,
1665
.argument nn + rn + rn ,
1669
.\"Restore internally saved tab positions.
1672
.\"Save tab positions internally.
1675
Remove tab repition character.
1677
Set tab repetition character to\ \c
1681
Temporary indent next line (default scaling indicator\ \c
1682
.scaleindicator m ).
1684
.REQ .tkf font s1 n1 s2 n2
1685
Enable track kerning for
1688
.REQ .tl \f(CB\(cq\fPleft\f(CB\(cq\fPcenter\f(CB\(cq\fPright\f(CB\(cq\fP
1694
on terminal (UNIX standard message output).
1699
on terminal (UNIX standard message output), allowing leading whitespace if
1703
(which will be stripped off).
1708
without emitting a final newline.
1721
Transparently output the contents of file
1722
.argument filename .
1725
This is the same as the
1727
request except that the translations do not apply to text that is
1728
transparently throughput into a diversion with
1732
Make the built-in condition
1739
Underline font set to
1741
(to be switched to by
1745
Underline (italicize in troff)
1749
.REQ .unformat diversion
1750
Unformat space characters and tabs, preserving font information in
1751
.argument diversion .
1753
Enable vertical position traps if
1755
is non-zero, disable them otherwise.
1758
Change to previous vertical base line spacing.
1761
Set vertical base line spacing to
1764
.scalednumber 12 p .
1767
Set warnings code to
1771
Set location trap; negative means from page bottom.
1773
.REQ .while cond anything
1780
.REQ .write stream anything
1788
Besides these standard groff requests, there might be further macro
1790
They can originate from a macro package (see
1791
.BR roff (@MAN7EXT@)
1792
for an overview) or from a preprocessor.
1794
Preprocessor macros are easy to be recognized. They enclose their code
1795
into a pair of characteristic macros.
1798
box, center, tab (@);
1801
preprocessor@start macro@ end macro
1808
soelim@\fInone@\fInone
1813
.\" --------------------------------------------------------------------
1814
.SH "ESCAPE SEQUENCES"
1815
.\" --------------------------------------------------------------------
1817
Escape sequences are in-line language elements usually introduced by
1820
and followed by an escape name and sometimes by a required argument.
1821
Input processing is continued directly after the escaped character or
1822
the argument resp. without an intervening separation character.
1823
So there must be a way to determine the end of the escape name and the end
1826
This is done by enclosing names (escape name and arguments consisting of
1827
a variable name) by a pair of brackets
1829
and constant arguments (number expressions and characters) by apostrophes
1831
.IR \(cqconstant\(cq .
1833
There are abbreviations for short names.
1834
Two character escape names can be specified by an opening parenthesis like
1836
without a closing counterpart.
1837
And all one-character names different from the special characters
1841
can even be specified without a marker in the form
1844
Constant arguments of length
1846
can omit the marker apostrophes, too, but there is no two-character
1849
While 1-character escape sequences are mainly used for in-line functions
1850
and system related tasks, the 2-letter names following the
1852
construct are used for special characters predefined by the roff system.
1853
Names with more than two characters
1855
mostly denote user defined named characters (see the
1859
.\" --------------------------------------------------------------------
1860
.SS "SINGLE CHARACTER ESCAPES"
1861
.\" --------------------------------------------------------------------
1865
.\" --------- comments ---------
1868
Beginning of a comment.
1869
Everything up to the end of the line is ignored.
1872
Everything up to and including the next newline is ignored.
1873
This is interpreted in copy mode.
1876
except the ignoring of the terminating newline.
1878
.\" --------- strings ---------
1881
The string stored in the string variable with 1-character name
1885
The string stored in the string variable with 2-character name
1889
The string stored in the string variable with arbitrary length name
1890
.argument stringvar .
1892
.\" --------- macro arguments ---------
1895
The name by which the current macro was invoked. The
1897
request can make a macro have more than one name.
1900
Macro argument with 1-place number
1904
is a digit between 1 and 9.
1907
Macro argument with 2-digit number
1911
Macro argument with number
1915
is a numerical expression evaluating to an integer \(>=1.
1918
In a macro, the concatenation of all the arguments separated by spaces.
1921
In a macro, the concatenation of all the arguments with each surrounded
1922
by double quotes, and separated by spaces.
1924
.\" --------- escaped characters ---------
1927
reduces to a single backslash; useful to delay its interpretation as
1928
escape character in copy mode.
1929
For a printable backslash, use
1933
The acute accent \(aa; same as
1935
Unescaped: apostrophe, right quotation mark, single quote (ASCII 0x27).
1938
The grave accent \(ga; same as
1940
Unescaped: left quote, backquote (ASCII 0x60).
1943
The \- sign in the current font.
1946
An uninterpreted dot (period), even at start of line.
1949
Default optional hyphenation character.
1952
Transparent line indicator.
1954
.ESC ? anything\fB?\fP
1955
In a diversion, this will transparently embed
1959
is read in copy mode.
1960
See also the escape sequences
1966
.\" --------- spacing ---------
1969
Unpaddable space-size space character (no line break).
1975
1/6\ em narrow space character; zero width in nroff.
1978
1/12\ em half-narrow space character; zero width in nroff.
1981
Non-printable, zero width character.
1986
except that it behaves like a character declared with the cflags
1987
request to be transparent for the purposes of end of sentence
1991
Increases the width of the preceding character so that the spacing
1992
between that character and the following character will be correct if
1993
the following character is a roman character.
1996
Modifies the spacing of the following character so that the spacing
1997
between that character and the preceding character will correct if the
1998
preceding character is a roman character.
2001
Unbreakable space that stretches like a normal inter-word space when a
2005
Inserts a zero-width break point (similar to
2007
but without a soft hyphen character).
2010
Ignored newline, for continuation lines.
2012
.\" --------- structuring ---------
2015
Begin conditional input.
2018
End conditional input.
2020
.\" --------- longer escape names ---------
2023
The special character with 2-character name
2026
.BR "SPECIAL CHARACTERS" .
2029
The named character with arbitrary length name
2032
.\" --------- alphabetical escapes ---------
2035
Non-interpreted leader character.
2040
is acceptable as a name of a string, macro, diversion, register,
2041
environment or font it expands to
2048
Bracket building function.
2053
is acceptable as a valid numeric expression it expands to
2060
Interrupt text processing.
2063
The character called
2067
but compatible to other roff versions.
2070
Forward (down) 1/2 em vertical unit (1/2 line in nroff).
2073
Draw a graphical element defined by the characters in
2075
see groff info file for details.
2078
Printable version of the current escape character.
2081
Equivalent to an escape character, but is not interpreted in copy-mode.
2084
Change to font with 1-character name or 1-digit number
2088
Change to font with 2-characer name or 2-digit number
2092
Change to font with arbitrary length name or number expression
2096
Return format of register with name
2106
Local horizontal motion; move right
2111
Set height of current font to
2115
Mark horizontal input place in register with arbitrary length name
2123
Horizontal line drawing function (optionally using character
2127
Vertical line drawing function (optionally using character
2131
The numerical value stored in the register variable with the 1-character
2136
The numerical value stored in the register variable with the 2-character
2141
The numerical value stored in the register variable with arbitrary
2146
Typeset the character with code
2148
in the current font, no special fonts are searched. Useful for adding
2149
characters to a font using the
2154
Overstrike characters
2161
Break and spread output line.
2164
Reverse 1\ em vertical motion (reverse line in nroff).
2173
Set the point size to
2175
scaled points. Note the alternative forms
2176
.BI \(rss \(+- [ N ]\c
2178
.BI \(rss' \(+-N '\c
2180
.BI \(rss \(+- ' N '\c
2183
.BI \(rss \(+- ( xy\c
2196
Non-interpreted horizontal tab.
2199
Reverse (up) 1/2 em vertical motion (1/2 line in nroff).
2202
Local vertical motion; move down
2207
The contents of the environment variable
2215
The width of the character sequence
2219
Extra line-space function (negative before, positive after).
2224
as device control function.
2227
Output string variable or macro
2229
uninterpreted as device control function.
2238
with zero width (without spacing).
2243
and then restore the horizontal and vertical position;
2245
may not contain tabs or leaders.
2248
The escape sequences
2260
are interpreted in copy mode.
2262
Escape sequences starting with
2266
do not represent single character escape sequences, but introduce escape
2267
names with two or more characters.
2269
If a backslash is followed by a character that does not constitute a
2270
defined escape sequence the backslash is silently ignored and the
2271
character maps to itself.
2273
.\" --------------------------------------------------------------------
2274
.SS "SPECIAL CHARACTERS"
2275
.\" --------------------------------------------------------------------
2276
Common special characters are predefined by escape sequences of the form
2282
Some of these exist in the usual font while most of them are only
2283
available in the special font. Below you'll find a selection of the most
2284
important glyphs; a complete list can be found in
2285
.BR groff_char (@MAN7EXT@).
2293
.ESc dd Double dagger
2298
.ESc rg Registered sign
2299
.ESc sc Section sign
2300
.ESc ul Underline character
2302
.ESc >= Larger or equal
2303
.ESc <= Less or equal
2307
.ESc +- Plus-minus sign
2311
.\" --------------------------------------------------------------------
2313
.\" --------------------------------------------------------------------
2314
Registers are variables that store a value.
2315
In groff, most registers store numerical values (see section
2316
.B NUMERICAL EXPRESSIONS
2317
above), but some can also hold a string value.
2319
Each register is given a name.
2320
Arbitrary registers can be defined and set with the request
2322
.argument register .
2324
The value stored in a register can be retrieved by the escape sequences
2328
Most useful are predefined registers.
2329
In the following the notation
2331
is used to refer to a register called
2333
to make clear that we speak about registers.
2334
Please keep in mind that the
2336
decoration is not part of the register name.
2338
.\" --------------------------------------------------------------------
2339
.SS "READ-ONLY REGISTERS"
2340
.\" --------------------------------------------------------------------
2341
The following registers have predefined values that should not be
2342
modified by the user (usually, registers starting with a dot a read-only).
2343
Mostly, they provide information on the current settings or store results
2347
.REG .$ Number of arguments in the current macro.
2349
Post-line extra line-space most recently utilized using
2362
.REG .c Current input line number.
2363
.REG .C 1 if compatibility mode is in effect, 0 otherwise.
2365
The depth of the last character added to the current environment.
2366
It is positive if the character extends below the baseline.
2368
The number of lines remaining to be centered, as set by the
2372
The height of the last character added to the current environment.
2373
It is positive if the character extends above the baseline.
2375
The skew of the last character added to the current environment.
2376
The skew of a character is how far to the right of the center of a character
2377
the center of an accent over that character should be placed.
2379
Current vertical place in current diversion; equal to register
2381
.REG .ev The name or number of the current environment (string-valued).
2382
.REG .f Current font number.
2383
.REG .fam The current font family (string-valued).
2384
.REG .fp The number of the next free font position.
2386
Always 1 in GNU troff.
2387
Macros should use it to test if running under groff.
2388
.REG .h Text base-line high-water mark on current page or diversion.
2389
.REG .H Available horizontal resolution in basic units.
2391
The current hyphenation language as set by the
2395
The number of immediately preceding consecutive hyphenated lines.
2397
The maximum allowed number of consecutive hyphenated lines, as set by
2402
The current hyphenation flags (as set by the
2406
The current hyphenation margin (as set by the
2410
The current hyphenation space (as set by the
2413
.REG .i Current ident.
2414
.REG .in The indent that applies to the current output line.
2416
Positive if last output line contains
2420
if pairwise kerning is enabled,
2423
.REG .l Current line length.
2425
The current ligature mode (as set by the
2429
The current line-tabs mode (as set by the
2432
.REG .ll The line length that applies to the current output line.
2434
The title length (as set by the
2437
.REG .n Length of text portion on previous output line.
2439
The amount of space that was needed in the last
2441
request that caused a trap to be sprung.
2442
Useful in conjunction with
2446
if in no-space mode,
2449
.REG .o Current page offset.
2450
.REG .p Current page length.
2452
The number of the next page: either the value set by a
2454
request, or the number of the current page plus\ 1.
2455
.REG .ps The current pointsize in scaled points.
2456
.REG .psr The last-requested pointsize in scaled points.
2458
The number of lines to be right-justified as set by the rj request.
2459
.REG .s Current point size as a decimal fraction.
2461
The last requested pointsize in points as a decimal fraction
2463
.REG .t Distance to the next trap.
2471
A string representation of the current tab settings suitable for use as
2476
The amount of vertical space truncated by the most recently sprung
2477
vertical position trap, or, if the trap was sprung by a
2479
request, minus the amount of vertical motion produced by
2482
In other words, at the point a trap is sprung, it represents the difference
2483
of what the vertical position would have been but for the trap, and what the
2484
vertical position actually is.
2485
Useful in conjunction with the
2489
The value of the parameters set by the first argument of the
2493
The value of the parameters set by the second argument of the
2496
.REG .u Equal to 1 bin fill mode and 0 in nofill mode.
2497
.REG .v Current vertical line spacing.
2498
.REG .V Available vertical resolution in basic units.
2501
if vertical position traps are enabled,
2504
.REG .w Width of previous character.
2506
The sum of the number codes of the currently enabled warnings.
2507
.REG .x The major version number.
2508
.REG .y The minor version number.
2509
.REG .Y The revision number of groff.
2510
.REG .z Name of current diversion.
2513
.\" --------------------------------------------------------------------
2514
.SS "WRITABLE REGISTERS"
2515
.\" --------------------------------------------------------------------
2516
The following registers can be read and written by the user.
2517
They have predefined default values, but these can be modified for
2518
customizing a document.
2521
.REG % Current page number.
2522
.REG c. Current input line number.
2523
.REG ct Character type (set by width function
2525
.REG dl Maximal width of last completed diversion.
2526
.REG dn Height of last completed diversion.
2527
.REG dw Current day of week (1-7).
2528
.REG dy Current day of month (1-31).
2529
.REG hp Current horizontal position at input line.
2531
Lower left x-coordinate (in PostScript units) of a given PostScript
2535
Lower left y-coordinate (in PostScript units) of a given PostScript
2538
.REG ln Output line number.
2539
.REG mo Current month (1-12).
2540
.REG nl Vertical position of last printed text base-line.
2543
but takes account of the heights and depths of characters.
2547
but takes account of the heights and depths of characters.
2549
Depth of string below base line (generated by width function
2552
Right skip width from the center of the last character in the
2556
If greater than 0, the maximum number of objects on the input stack.
2557
If \(<=0 there is no limit, i.e., recursion can continue until virtual
2558
memory is exhausted.
2560
The amount of horizontal space (possibly negative) that should be added
2561
to the last character before a subscript (generated by width function
2564
Height of string above base line (generated by width function
2567
The return value of the
2569
function executed by the last
2573
Upper right x-coordinate (in PostScript units) of a given PostScript
2577
Upper right y-coordinate (in PostScript units) of a given PostScript
2580
.REG year The current year (year 2000 compliant).
2582
Current year minus 1900. For Y2K compliance use register
2587
.\" --------------------------------------------------------------------
2589
.\" --------------------------------------------------------------------
2590
Each warning generated by groff is identified by a name and a code
2591
number. The codes are powers of 2 to allow bit-encoding with a single
2592
integer. There are also names that can be used to refer to groups of
2595
The name associated with a warning is used by the
2600
the number code is used by the
2613
Intended to cover all warnings with traditional macro packages.
2615
In fill mode, lines which could not be broken so that their length was
2616
less than the line length. This is enabled by default.
2618
Non-existent characters. This is enabled by default.
2620
Missing or mismatched closing delimiters.
2626
without an argument when there is no current diversion.
2630
request with no matching
2633
.Warning escape 32768
2634
Unrecognized escape sequence. Then the escape character is ignored.
2635
.Warning font 131072
2636
Non-existent fonts. This is enabled by default.
2638
Illegal escapes in text ignored with the
2640
request. These are conditions that are errors when they occur outside
2643
Use of undefined strings, macros, and diversions. Automatically handled
2644
as empty. Usually, only one warning per name.
2645
.Warning missing 8192
2646
Request that is missing non-optional arguments.
2647
.Warning input 16384
2648
Illegal input character.
2650
Invalid numeric expressions. This is enabled by default.
2652
Out of range arguments.
2654
Use of undefined number register. Automatically defined as having
2655
value 0. Usually, only one warning per name.
2656
.Warning right-brace 4096
2659
where a number was expected.
2661
Meaningless scaling indicators.
2662
.Warning space 65536
2663
Missing space between a request or macro and its argument. Then no
2664
macro is automatically defined. This is enabled by default. This
2665
warning will never occur in compatibility mode.
2667
Dubious syntax in numeric expressions.
2669
Inappropriate use of a tab character (either in an unquoted macro
2670
argument or where a number was expected).
2676
tab(@), box, expand;
2677
c c c | c c c | c c c
2678
R RI CB | R RI CB | R RI CB.
2679
Bit@Code@Warning@Bit@Code@Warning@Bit@Code@Warning
2681
0@1@char@8@256@di@16@65536@space
2682
1@2@number@9@512@mac@17@131072@font
2683
2@4@break@10@1024@reg@18@262144@ig
2684
3@8@delim@11@2048@tab
2685
4@16@el@12@4096@right-brace
2686
5@32@scale@13@8192@missing
2687
6@64@range@14@16384@input
2688
7@128@syntax@15@32768@escape
2692
.\" --------------------------------------------------------------------
2694
.\" --------------------------------------------------------------------
2697
.B compatibility mode
2698
that allows to process roff code written for classical
2700
or for other implementations of roff in a consistent way.
2702
Compatibility mode can be turned on with the
2704
command line option, and turned on or off with the
2706
request. The number register
2710
if compatibility mode is on,
2714
This became necessary because the GNU concept for long names causes some
2722
as defining a string
2728
will interpret this as a call of a macro named
2737
as references to a string or number register called
2742
however, this will normally be interpreted as the start of a long name.
2747
groff will interpret these things in the traditional way, but long names
2750
On the other hand, groff in
2752
does not allow to use the escape sequences
2768
in names of strings, macros, diversions, number registers, fonts or
2769
environments, whereas
2773
escape sequence can be helpful in avoiding these escape sequences in
2776
Fractional pointsizes cause one noteworthy incompatibility.
2782
request ignores scale indicators and so
2788
will set the pointsize to 10 points, whereas in groff native mode the
2789
pointsize will be set to 10 scaled points.
2793
mode, there is a fundamental difference between unformatted input
2794
characters, and formatted output characters.
2795
Everything that affects how an output character will be output is stored
2796
with the character; once an output character has been constructed it is
2797
unaffected by any subsequent requests that are executed, including the
2806
Normally output characters are constructed from input characters at the
2807
moment immediately before the character is added to the current output
2809
Macros, diversions and strings are all, in fact, the same type of object;
2810
they contain lists of input characters and output characters in any
2813
An output character does not behave like an input character for the
2814
purposes of macro processing; it does not inherit any of the special
2815
properties that the input character from which it was constructed might
2817
The following example will make things clearer.
2833
this will be printed as
2835
So each pair of input backslashes
2837
is turned into a single output backslash
2839
and the resulting output backslashes are not interpreted as escape
2840
characters when they are reread.
2843
would interpret them as escape characters when they were reread and
2844
would end up printing a single backslash
2847
The correct way to get a printable
2851
escape sequence. This will always print a single instance of the
2852
current escape character, regardless of whether or not it is used in a
2853
diversion. It will also work in both GNU mode and compatibility mode.
2855
To store an escape sequence in a diversion that will be interpreted when
2856
the diversion is reread, either the traditional
2858
transparent output facility or the
2861
escape sequence can be used.
2863
.\" --------------------------------------------------------------------
2865
.\" --------------------------------------------------------------------
2866
At the moment, the documentation of the groff system is in a state of
2867
change and evolution. It is possible that there are small
2868
inconsistencies between different documents temporarily.
2873
.BR troff (@MAN1EXT@).
2875
.\" --------------------------------------------------------------------
2877
.\" --------------------------------------------------------------------
2878
This document is part of groff, the GNU roff distribution. It was
2879
written by Bernd Warken <bwarken@mayn.de>.
2881
It is distributed under the terms of the FDL (GNU Free Documentation
2882
License) version 1.1 or later. You should have received a copy of the
2883
FDL on your system, it is also available on-line under
2886
.IR http://www.gnu.org/copyleft/fdl.html .
2889
Formerly, the extensions of the groff language were kept in the manual
2891
.BR troff (@MAN1EXT@).
2892
This document contains the essential parts of that documentation, but
2893
the gory details are found in the groff info file.
2895
.\" --------------------------------------------------------------------
2897
.\" --------------------------------------------------------------------
2898
The main source of information for the groff language is the
2903
For a survey of roff and the groff system and further documentation
2905
.BR roff (@MAN7EXT@).
2907
The formatter programs are described in
2908
.BR groff (@MAN1EXT@)
2910
.BR troff (@MAN1EXT@);
2911
a complete of all predefined glyph names can be found in
2912
.BR groff_char (@MAN7EXT@).
2916
documentation is available on-line at
2919
.I http://cm.bell-labs.com/cm/cs/cstr.html
2923
.IR http://www.kohala.com/start/troff/ .
2925
.\" Local Variables:
added
removed
man/groff.man
