{
    "mode": "man",
    "parameter": "groff_diff",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/groff_diff/7/json",
    "generated": "2026-10-07T19:12:02Z",
    "sections": {
        "Name": {
            "content": "groffdiff - differences between GNU roff and AT&T troff\n",
            "subsections": []
        },
        "Description": {
            "content": "The  GNU  roff  text processing system, groff, is an extension of AT&T troff, the typesetting\nsystem originating in Unix systems of the 1970s.  groff removes  many  arbitrary  limitations\nand  adds features, both to the input language and to the page description language output by\nthe troff formatter.  Differences arising from groff's implementation of AT&T troff  features\nare also noted.  See roff(7) for background.\n",
            "subsections": []
        },
        "Language": {
            "content": "GNU  troff features identifiers of arbitrary length; supports color output, non-integral type\nsizes, and user-defined characters; adds more conditional  expression  operators;  recognizes\nadditional  scaling  units  and numeric operators; enables general file I/O (in “unsafe mode”\nonly); and exposes more formatter state.\n",
            "subsections": [
                {
                    "name": "Long names",
                    "content": "GNU troff introduces many new requests; with three exceptions (cp, do, rj), they  have  names\nlonger  than two characters.  The names of registers, fonts, strings/macros/diversions, envi‐\nronments, special characters, streams, and colors can be of any length.  Anywhere AT&T  troff\nsupports  a parameterized escape sequence that uses an opening parenthesis “(” to introduce a\ntwo-character argument, groff supports a square-bracketed form “[]” where the argument within\ncan be of arbitrary length.\n"
                },
                {
                    "name": "Font families, abstract styles, and translation",
                    "content": "GNU troff can group text typefaces into families containing each of the styles “R”, “I”, “B”,\nand “BI”.  So that a document need not be coupled to a specific font family, an output device\ncan associate a style in the abstract sense with a mounting position.  Thus the default  fam‐\nily can be combined with a style dynamically, producing a resolved font name.  A document can\ntranslate, or remap, fonts with the ftr request.\n\nApplying the requests cs, bd, tkf, uf, or fspecial to an abstract style affects the member of\nthe  default  family corresponding to that style.  The default family can be set with the fam\nrequest or -f command-line option.  The styles directive in the  output  device's  DESC  file\ncontrols  which  mounting  positions  (if  any) are initially associated with abstract styles\nrather than fonts, and the sty request can update this association.\n"
                },
                {
                    "name": "Colors",
                    "content": "groff supports color output with a variety of color spaces and up to  16  bits  per  channel.\nSome  devices,  particularly  terminals, may be more limited.  When color support is enabled,\ntwo colors are current at any given time: the stroke color, with which glyphs, rules (lines),\nand geometric figures are drawn, and the fill color, which paints the interior of filled geo‐\nmetric figures.  The color, defcolor, gcolor, and fcolor  requests;  \\m  and  \\M  escape  se‐\nquences; and .color, .m, and .M registers exercise color support.\n"
                },
                {
                    "name": "Fractional type sizes and new scaling units",
                    "content": "AT&T  troff  interpreted  all type size measurements in points.  Combined with integer arith‐\nmetic, this design choice made it impossible to support, for instance, ten and  a  half-point\ntype.   In  GNU  troff,  an output device can select a scaling factor that subdivides a point\ninto “scaled points”.  A type size expressed in scaled points can thus represent a  non-inte‐\ngral type size.\n\nA scaled point is equal to 1/sizescale points, where sizescale is specified in the device de‐\nscription file, DESC, and defaults to 1; see grofffont(5).  Requests and escape sequences in\nGNU  troff interpret arguments that represent a type size in points, which the formatter mul‐\ntiplies by sizescale and converts to an integer.  Arguments  treated  in  this  way  comprise\nthose  to the escape sequences \\H and \\s, to the request ps, the third argument to the cs re‐\nquest, and the second and fourth arguments to the tkf request.  Scaled points may  be  speci‐\nfied explicitly with the z scaling unit.  In GNU troff, the register \\n[.s] can interpolate a\nnon-integral type size.  The register \\n[.ps] interpolates the type size in scaled points.\n\nFor  example, if sizescale is 1000, then a scaled point is one thousandth of a point.  Conse‐\nquently, “.ps 10.5” is synonymous with “.ps 10.5z”; both set the type size to  10,500  scaled\npoints, or 10.5 points.\n\nIt  makes  no sense to use the “z” scaling unit in a numeric expression whose default scaling\nunit is neither “u” nor “z”, so GNU troff disallows this.  Similarly, it  is  nonsensical  to\nuse  a  scaling unit other than “z” or “u” in a numeric expression whose default scaling unit\nis “z”, so GNU troff disallows this as well.\n\nAnother new scaling unit, “s”, multiplies by the number of basic units  in  a  scaled  point.\nThus,  “\\n[.ps]s”  is  equal  to  “1m” by definition.  Do not confuse the “s” and “z” scaling\nunits.\n\nOutput devices may be limited in the type sizes they can employ.  The .s  and  .ps  registers\nrepresent  the  type size as selected by the output driver as it understands a device's capa‐\nbility.  The last requested type size is interpolated in scaled points by the read-only  reg‐\nister  .psr  and in points as a decimal fraction by the read-only string-valued register .sr.\nBoth are associated with the environment.  For example, if a type size of 10.95 points is re‐\nquested, and the nearest size permitted by a sizes request (or by the sizes or sizescale  di‐\nrectives in the device's DESC file) is 11 points, the output driver uses the latter value.\n\nA further two new measurement units available in groff are “M”, which indicates hundredths of\nan  em,  and  “f”,  which multiplies by 65,536.  The latter provides convenient fractions for\ncolor definitions with the defcolor request.  For example, 0.5f equals 32768u.\n"
                },
                {
                    "name": "Numeric expressions",
                    "content": "GNU troff permits spaces in a numeric expression within parentheses, and offers three new op‐\nerators.\n\ne1>?e2 Interpolate the greater of e1 and e2.\n\ne1<?e2 Interpolate the lesser of e1 and e2.\n\n(c;e)  Evaluate e using c as the default scaling unit, ignoring scaling units in e  if  c  is\nempty.\n"
                },
                {
                    "name": "Conditional expressions",
                    "content": "More  conditions  can be tested with the “if” and ie requests, as well as the new “while” re‐\nquest.\n\nc chr  True if a character chr is available, where chr is an ordinary character (Unicode  ba‐\nsic  Latin excluding control characters and the space), a special character, or \\N'in‐\ndex'.\n\nd nam  True if a string, macro, diversion, or request nam is defined.\n\nF fnt  True if a font fnt is available; fnt can be an abstract style or a font name.  fnt  is\nhandled  as if it were accessed with the ft request (that is, abstract styles and font\ntranslation are applied), but fnt cannot be  a  mounting  position,  and  no  font  is\nmounted.\n\nm col  True if a color col is defined.\n\nr reg  True if a register reg is defined.\n\nS sty  True if a style sty is registered.  Font translation applies.\n\nv      Always  false.  This condition is for compatibility with certain other troff implemen‐\ntations only.  (This refers to vtroff, a translator that would convert the C/A/T  out‐\nput  from  early-vintage  AT&T troff to a form suitable for Versatec and Benson-Varian\nplotters.)\n"
                },
                {
                    "name": "Drawing commands",
                    "content": "GNU troff offers drawing commands to  create  filled  circles  and  ellipses,  and  polygons.\nStroked  (outlined)  objects  are  drawn with the stroke color and filled (solid) ones shaded\nwith the fill color.  These are independent properties; if you want a filled, stroked figure,\nyou must draw the same figure twice using each drawing command.  A filled  figure  is  always\nsmaller  than a stroked one because the former is drawn only within its defined area, whereas\nstrokes have a line thickness (set with another new drawing command, \\D't').\n"
                },
                {
                    "name": "Escape sequences",
                    "content": "groff introduces several new escape sequences and extends the syntax of a few AT&T troff  es‐\ncape  sequences  (namely, \\D, \\f, \\k, \\n, \\s, \\$, and \\*).  In the following list, escape se‐\nquences are collated alphabetically at first, and then by  symbol  roughly  in  Unicode  code\npoint order.\n\n\\A'anything'\nInterpolate 1 if anything is a valid identifier, and 0 otherwise.  Because invalid in‐\nput  characters are removed, invalid identifiers are empty or contain spaces, tabs, or\nnewlines.  You can employ \\A to validate a macro argument before using it to construct\nanother escape sequence or identifier.\n\n\\B'anything'\nInterpolate 1 if anything is a valid numeric expression, and 0 otherwise.   You  might\nuse \\B along with the “if” request to filter out invalid macro arguments.\n\n\\D'C d'\nDraw filled circle of diameter d with its leftmost point at the drawing position.\n\n\\D'E h v'\nDraw filled ellipse with h and v as the axes and the leftmost point at the drawing po‐\nsition.\n\n\\D'p h1 v1 ... hn vn'\nDraw  polygon with vertices at drawing position and each point in sequence.  GNU troff\ncloses the polygon by drawing a line from (hn, vn) back to the initial  drawing  posi‐\ntion;  DWB  and  Heirloom  troffs  do not.  Afterward, the drawing position is left at\n(hn, vn).\n\n\\D'P h1 v1 ... hn vn'\nAs \\D'p', but the polygon is filled.\n\n\\D't n'\nSet line thickness of geometric objects to to n basic units.  A  zero  n  selects  the\nminimal  supported  thickness.   A  negative n selects a thickness proportional to the\ntype size; this is the default.\n\n\\E     Embed an escape character that is not interpreted in copy mode (compare  with  \\a  and\n\\t).  You can use it to ease the writing of nested macro definitions.  It is also con‐\nvenient  to  define strings containing escape sequences that need to work when used in\ncopy mode (for example, as macro arguments), or which will be interpolated at  varying\nmacro nesting depths.\n\n\\f[font]\nSelect font, which may be a mounting position, abstract style, or font name, to choose\nthe typeface.  \\f[] and \\fP are synonyms; we recommend the former.\n\n\\Ff\n\\F(fm\n\\F[family]\nSelect  default font family.  \\F[] makes the previous font family the default.  \\FP is\nunlike \\fP; it selects font family “P” as the default.  See the fam request below.\n\n\\k(rg\n\\k[reg]\nMark horizontal drawing position in two-character register name rg or arbitrary regis‐\nter name reg.\n\n\\mc\n\\m(cl\n\\m[col]\nSet the stroke color.  \\m[] restores the previous stroke  color,  or  the  default  if\nthere is none.\n\n\\Mc\n\\M(cl\n\\M[col]\nSet the fill color.  \\M[] restores the previous fill color, or the default if there is\nnone.\n\n\\n[reg]\nInterpolate register reg.\n\n\\On\n\\O[n]  Suppress  troff  output of glyphs and geometric objects.  The sequences \\O2, \\O3, \\O4,\nand \\O5 are intended for internal use by grohtml(1).\n\n\\O0\n\\O1    Disable and enable, respectively, the emission of glyphs and geometric  objects\nto  the output driver, provided that this sequence occurs at the outermost sup‐\npression level (see \\O3 and \\O4).  Horizontal  motions  corresponding  to  non-\noverstruck  glyph widths still occur.  These sequences also reset the registers\nopminx, opminy, opmaxx, and opmaxy to -1.  These four registers  mark  the  top\nleft  and  bottom right hand corners of a box encompassing all written or drawn\noutput.\n\n\\O2    At the outermost suppression level, enable emission of glyphs and geometric ob‐\njects, and write to the standard error stream the page number and values of the\nfour aforementioned registers encompassing glyphs written since the last inter‐\npolation of a \\O sequence, as well as the page offset, line length, image  file\nname  (if  any),  horizontal  and vertical device motion quanta, and input file\nname.  Numeric values are in basic units.\n\n\\O3\n\\O4    Begin and end a nested suppression  level,  respectively.   grohtml  uses  this\nmechanism  to  create images of output preprocessed with pic, eqn, and tbl.  At\nstartup, troff is at the outermost suppression  level.   pre-grohtml  generates\nthese  sequences  when  processing the document, using troff with the ps output\ndevice, Ghostscript, and the PNM tools to produce images in PNG format.   These\nsequences  start  a  new page if the device is not html or xhtml, to reduce the\nnumber of images crossing a page boundary.\n\n\\O5[Pfile]\nAt the outermost suppression level, write the name file to the  standard  error\nstream  at  position  P,  which  must be one of l, r, c, or i, corresponding to\nleft, right, centered, and inline alignments within the document, respectively.\nfile is is a name associated with the production of the next image.\n\n\\R'name ±n'\nSynonymous with “.nr name ±n”.\n\n\\s[±n]\n\\s±[n]\n\\s'±n'\n\\s±'n' Set the type size to, or increment or decrement it by, n scaled points.\n\n\\Ve\n\\V(ev\n\\V[env]\nInterpolate contents of the environment variable env, as returned by getenv(3).  \\V is\ninterpreted even in copy mode.\n\n\\X'anything'\nWithin \\X arguments, the escape sequences \\&, \\), \\%, and \\: are ignored;  \\space  and\n\\~  are converted to single space characters; and \\\\ is reduced to \\.  So that the ba‐\nsic Latin subset of the Unicode character set (that is,  ISO  646:1991-IRV  or,  popu‐\nlarly,  “US-ASCII”)  can be reliably encoded in anything, the special character escape\nsequences \\-, \\[aq], \\[dq], \\[ga], \\[ha], \\[rs], and \\[ti] are mapped to  basic  Latin\ncharacters;  see  groffchar(7).   For this transformation, character translations and\ndefinitions are ignored.  Other escape sequences are not supported.\n\nIf the usecharnamesinspecial directive appears in the output  device's  DESC  file,\nthe  use of special character escape sequences is not an error; they are simply output\nverbatim (with the exception of the seven mapped to Unicode  basic  Latin  characters,\ndiscussed above).  usecharnamesinspecial is currently employed only by grohtml(1).\n\n\\Ym\n\\Y(ma\n\\Y[mac]\nInterpolate  a macro as a device control command.  This is similar to \\X'\\*[mac]', ex‐\ncept the contents of mac are not interpreted, and mac can be a macro and thus  contain\nnewlines,  whereas  the argument to \\X cannot.  This inclusion of newlines requires an\nextension to the AT&T troff output format, and will confuse postprocessors that do not\nknow about it.\n\n\\Z'anything'\nSave the drawing position, format anything, then restore it.  Tabs and leaders in  the\nargument are ignored with an error diagnostic.\n\n\\#     Everything  up  to and including the next newline is ignored.  This escape sequence is\ninterpreted even in copy mode.  \\# is like \\\", except that \\\" does not ignore  a  new‐\nline; the latter therefore cannot be used by itself for a whole-line comment—it leaves\na blank line on the input stream.\n\n\\$0    Interpolate  the  name  by which the macro being interpreted was called.  In GNU troff\nthis name can vary; see the als request.\n\n\\$(nn\n\\$[nnn]\nIn a macro or string definition, interpolate the nnth or nnnth argument.   Macros  and\nstrings can have an unlimited number of arguments.\n\n\\$*    In  a  macro  or string definition, interpolate the catenation of all arguments, sepa‐\nrated by spaces.\n\n\\$@    In a macro or string definition, interpolate the catenation  of  all  arguments,  with\neach surrounded by double quotes and separated by spaces.\n\n\\$^    In  a  macro  or  string  definition, interpolate the catenation of all arguments con‐\nstructed in a form suitable for passage to the ds request.\n\n\\)     Interpolate a transparent dummy character—one that is ignored by  end-of-sentence  de‐\ntection.  It behaves as \\&, except that \\& is treated as letters and numerals normally\nare after “.”, “?”, and “!”; \\& cancels end-of-sentence detection, and \\) does not.\n\n\\*[string [arg ...]]\nInterpolate string, passing it arg ... as arguments.\n\n\\/     Apply an italic correction: modify the spacing of the preceding glyph so that the dis‐\ntance between it and the following glyph is correct if the latter is of upright shape.\nFor  example,  if  an italic “f” is followed immediately by a roman right parenthesis,\nthen in many fonts the top right portion of the “f” overlaps the top left of the right\nparenthesis, which is ugly.  Inserting \\/ between them avoids this problem.  Use  this\nescape  sequence whenever an oblique glyph is immediately followed by an upright glyph\nwithout any intervening space.\n\n\\,     Apply a left italic correction: modify the spacing of the following glyph so that  the\ndistance  between  it  and  the preceding glyph is correct if the latter is of upright\nshape.  For example, if a  roman  left  parenthesis  is  immediately  followed  by  an\nitalic  “f”, then in many fonts the bottom left portion of the “f” overlaps the bottom\nof the left parenthesis, which is ugly.  Inserting \\, between them avoids  this  prob‐\nlem.  Use this escape sequence whenever an upright glyph is followed immediately by an\noblique glyph without any intervening space.\n\n\\:     Insert  a non-printing break point.  That is, a word can break there, but the soft hy‐\nphen character does not mark the break point if it does (in contrast to  “\\%”).   This\nescape  sequence is an input word boundary, so the remainder of the word is subject to\nhyphenation as normal.\n\n\\?anything\\?\nWhen used in a diversion, this transparently embeds anything in the  diversion.   any‐\nthing  is  read  in copy mode.  When the diversion is reread, anything is interpreted.\nanything may not contain newlines; use \\! if you want to embed newlines  in  a  diver‐\nsion.   The escape sequence \\? is also recognized in copy mode and becomes an internal\ncode; it is this code that terminates anything.  Thus\n\n.nr x 1\n.nf\n.di d\n\\?\\\\?\\\\\\\\?\\\\\\\\\\\\\\\\nx\\\\\\\\?\\\\?\\?\n.di\n.nr x 2\n.di e\n.d\n.di\n.nr x 3\n.di f\n.e\n.di\n.nr x 4\n.f\n\nprints 4.\n\n\\[char]\nTypeset the special character char.\n\n\\[base-char combining-component ...]\nTypeset a composite glyph consisting of base-char overlaid with one or more combining-\ncomponents.  For example, “\\[A ho]” is a capital  letter  “A”  with  a  “hook  accent”\n(ogonek).   See  the  composite request below; Groff: The GNU Implementation of troff,\nthe groff Texinfo manual, for  details  of  composite  glyph  name  construction;  and\ngroffchar(7) for a list of components used in composite glyph names.\n\n\\~     Insert  an  unbreakable  space  that is adjustable like an ordinary space.  It is dis‐\ncarded from the end of an output line if a break is forced.\n"
                },
                {
                    "name": "Restricted requests",
                    "content": "To mitigate risks from untrusted input documents, the pi and sy requests are disabled by  de‐\nfault.   troff(1)'s -U option enables the formatter's “unsafe mode”, restoring their function\n(and enabling additional groff extension requests, open, opena, and pso).\n"
                },
                {
                    "name": "New requests",
                    "content": ".aln new old\nCreate alias new for existing register named old, causing the names to  refer  to  the\nsame  stored value.  If old is undefined, a warning in category “reg” is generated and\nthe request is ignored.  To remove a register alias, invoke rr on its name.  A  regis‐\nter's contents do not become inaccessible until it has no more names.\n\n.als new old\nCreate  alias new for existing request, string, macro, or diversion named old, causing\nthe names to refer to the same stored object.  If old is undefined, a warning in cate‐\ngory “mac” is produced, and the request is ignored.  The “am”, “as”, da, de,  di,  and\nds requests (together with their variants) create a new object only if the name of the\nmacro,  diversion,  or string is currently undefined or if it is defined as a request;\nnormally, they modify the value of an existing object.  To remove an alias, invoke  rm\non its name.  The object itself is not destroyed until it has no more names.\n\nWhen  a request, macro, string, or diversion is aliased, redefinitions and appendments\n“write through” alias names.  To replace an alias with a  separately  defined  object,\nyou must use the rm request on its name first.\n\n.am1 name [end-name]\nAs  “am”,  but  compatibility  mode is disabled while the appendment to name is inter‐\npreted: a “compatibility save” token is inserted at its beginning, and a  “compatibil‐\nity  restore” token at its end.  As a consequence, the requests “am”, am1, de, and de1\ncan be intermixed freely since the compatibility save/restore tokens affect  only  the\nparts of the macro populated by am1 and de1.\n\n.ami name [end-name]\nAppend to macro indirectly.  See dei below.\n\n.ami1 name [end-name]\nAs ami, but compatibility mode is disabled during interpretation of the appendment.\n\n.as1 name [contents]\nAs  “as”,  but  compatibility  mode is disabled while the appendment to name is inter‐\npreted: a “compatibility save” token is inserted at the beginning of contents,  and  a\n“compatibility restore” token after it.  As a consequence, the requests “as”, as1, ds,\nand  ds1  can  be intermixed freely since the compatibility save/restore tokens affect\nonly the portions of the strings populated by as1 and ds1.\n\n.asciify div\nUnformat the diversion div in a way such that Unicode basic Latin (ASCII)  characters,\ncharacters  translated  with  the  trin request, space characters, and some escape se‐\nquences, that were formatted in the diversion div  are  treated  like  ordinary  input\ncharacters  when div is reread.  Doing so can be useful in conjunction with the writem\nrequest.  asciify can be also used for gross hacks; for example,  the  following  sets\nregister n to 1.\n\n.tr @.\n.di x\n@nr n 1\n.br\n.di\n.tr @@\n.asciify x\n.x\n\nasciify  cannot return all items in a diversion to their source equivalent: nodes such\nas those produced by \\N[...] will remain nodes, so the result cannot be guaranteed  to\nbe  a pure string.  See section “Copy mode” in groff(7).  Glyph parameters such as the\ntype face and size are not preserved; use unformat to achieve that.\n"
                },
                {
                    "name": ".backtrace",
                    "content": "Write backtrace of input stack to the standard error stream.  See  the  -b  option  of\ntroff(1).\n\n.blm [name]\nSet  a blank line macro (trap).  If a blank line macro is thus defined, groff executes\nmacro when a blank line is encountered in the input file, instead of the usual  behav‐\nior.   A  line  consisting only of spaces is also treated as blank and subject to this\ntrap.  If no argument is supplied, the default  blank  line  behavior  is  (re-)estab‐\nlished.\n\n.box [name]\n.boxa [name]\nDivert  (or append) output to name, similarly to the di and da requests, respectively.\nAny pending output line is not included in the diversion.  Without an  argument,  stop\ndiverting output; any pending output line inside the diversion is discarded.\n\n.break Exit a “while” loop.  Do not confuse this request with a typographical break or the br\nrequest.  See “continue”.\n\n.brp   Break and adjust line; this is the AT&T troff escape sequence \\p in request form.\n\n.cflags n c1 c2 ...\nAssign  properties  encoded by the number n to characters c1, c2, and so on.  Ordinary\nand special characters have certain associated  properties.   (Glyphs  don't:  to  GNU\ntroff, like AT&T device-independent troff, a glyph is an identifier corresponding to a\nrectangle with some metrics; see grofffont(5).)  The first argument is the sum of the\ndesired  flags  and  the  remaining  arguments are the characters to be assigned those\nproperties.  Spaces between the cn arguments are optional.  Any argument cn can  be  a\ncharacter class defined with the class request rather than an individual character.\n\nThe  non-negative integer n is the sum of any of the following.  Some combinations are\nnonsensical, such as “33” (1 + 32).\n\n1      Recognize the character as ending a sentence if followed by a  newline  or  two\nspaces.  Initially, characters “.?!”  have this property.\n\n2      Enable  breaks  before the character.  A line is not broken at a character with\nthis property unless the characters on each side both have non-zero hyphenation\ncodes.  This exception can be overridden by adding 64.  Initially,  no  charac‐\nters have this property.\n\n4      Enable  breaks  after  the character.  A line is not broken at a character with\nthis property unless the characters on each side both have non-zero hyphenation\ncodes.  This exception can be overridden by adding 64.   Initially,  characters\n“-\\[hy]\\[em]” have this property.\n\n8      Mark the glyph associated with this character as overlapping other instances of\nitself  horizontally.  Initially, characters “\\[ul]\\[rn]\\[ru]\\[radicalex]\\[sqr‐\ntex]” have this property.\n\n16     Mark the glyph associated with this character as overlapping other instances of\nitself vertically.  Initially, the character “\\[br]” has this property.\n\n32     Mark the character as transparent for the purpose of  end-of-sentence  recogni‐\ntion.   In  other words, an end-of-sentence character followed by any number of\ncharacters with this property is treated as the end of a sentence  if  followed\nby  a newline or two spaces.  This is the same as having a zero space factor in\nTeX.  Initially, characters “'\")]*\\[dg]\\[dd]\\[rq]\\[cq]” have this property.\n\n64     Ignore hyphenation codes of the surrounding characters.  Use this value in com‐\nbination with values 2 and 4.  Initially, no characters have this property.\n\nFor example, if you need an automatic break point after the en-dash in  numeric\nranges like “3000–5000”, insert\n.cflags 68 \\[en]\ninto  your  document.   However,  this  can  lead to bad layout if done without\nthinking; in most situations, a better solution than changing the cflags  value\nis inserting “\\:” right after the hyphen at the places that really need a break\npoint.\n\nThe  remaining  values were implemented for East Asian language support; those who use\nalphabetic scripts exclusively can disregard them.\n\n128    Prohibit a break before the character, but allow a break after  the  character.\nThis works only in combination with values 256 and 512 and has no effect other‐\nwise.  Initially, no characters have this property.\n\n256    Prohibit  a  break after the character, but allow a break before the character.\nThis works only in combination with values 128 and 512 and has no effect other‐\nwise.  Initially, no characters have this property.\n\n512    Allow a break before or after the character.  This works  only  in  combination\nwith  values 128 and 256 and has no effect otherwise.  Initially, no characters\nhave this property.\n\nIn contrast to values 2 and 4, the values 128, 256, and 512 work  pairwise.   If,  for\nexample,  the left character has value 512, and the right character 128, no break will\nbe automatically inserted between them.  If we use value 6 instead for the left  char‐\nacter, a break after the character can't be suppressed since the neighboring character\non the right doesn't get examined.\n\n.char c contents\nDefine the ordinary or special character c as contents, which can be empty.  More pre‐\ncisely,  char  defines  a groff object (or redefines an existing one) that is accessed\nwith the name c on input, and produces contents on output.  Every time c is to be for‐\nmatted, contents is processed in a temporary environment and the result is wrapped  up\ninto  a  single  object.  Compatibility mode is turned off and the escape character is\nset to \\ while contents is processed.  Any emboldening,  constant  spacing,  or  track\nkerning is applied to this object as a whole, not to each character in contents.\n\nAn object defined by this request can be used just like a glyph provided by the output\ndevice.   In particular, other characters can be translated to it with the tr request;\nit can be made the tab or leader fill character with the tc and lc requests; sequences\nof it can be drawn with the \\l and \\L escape sequences; and, if the hcode  request  is\nused on c, it is subject to automatic hyphenation.\n\nTo  prevent infinite recursion, occurrences of c within its own definition are treated\nnormally (as if it were not being defined with char).  The tr and trin  requests  take\nprecedence  if  char  both apply to c.  A character definition can be removed with the\nrchar request.\n\n.chop object\nRemove the last character from the macro, string, or diversion object.  This is useful\nfor removing the newline from the end of a diversion that is to be interpolated  as  a\nstring.   This  request can be used repeatedly on the same object; see section “gtroff\nInternals” in Groff: The GNU Implementation of troff, the groff  Texinfo  manual,  for\ndiscussion of nodes inserted by groff.\n\n.class name c1 c2 ...\nDefine  a  character class (or simply “class”) name comprising the characters or range\nexpressions c1, c2, and so on.\n\nA class thus defined can then be referred to in lieu of  listing  all  the  characters\nwithin  it.   Currently,  only  the  cflags request can handle references to character\nclasses.\n\nIn the request's simplest form, each cn is a character (or special character).\n.class [quotes] ' \\[aq] \\[dq] \\[oq] \\[cq] \\[lq] \\[rq]\n\nSince class and special character names share the same name space, we recommend start‐\ning and ending the class name with “[” and “]”, respectively, to avoid collisions with\nexisting character names defined by groff or the  user  (with  char  and  related  re‐\nquests).   This  practice applies the presence of “]” in the class name to prevent the\nusage of the special character escape form “\\[...]”, thus you must use the  \\C  escape\nto access a class with such a name.\n\nYou can also use a character range expression consisting of a start character followed\nby  “-” and then an end character.  Internally, GNU troff converts these two character\nnames to Unicode code points (according to the groff glyph list [GGL]),  which  deter‐\nmine  the  start  and end values of the range.  If that fails, the class definition is\nskipped.  Furthermore, classes can be nested.\n.class [prepunct] , : ; > }\n.class [prepunctx] \\C'[prepunct]' \\[u2013]-\\[u2016]\nThe class “[prepunctx]” thus contains the contents of the class “[prepunct]” and char‐\nacters in the range U+2013–U+2016.\n\nIf you want to include “-” in a class, it must be the first character value in the ar‐\ngument list, otherwise it gets misinterpreted as part of the range syntax.\n\nIt is not possible to use class names as end points of range definitions.\n\nA typical use of the class request is to control line-breaking and  hyphenation  rules\nas  defined  by  the  cflags  request.  For example, to inhibit line breaks before the\ncharacters belonging to the “[prepunctx]” class defined in the previous  example,  you\ncan write the following.\n.cflags 2 \\C'[prepunctx]'\n\n.close stream\nClose  the  stream  named stream, invalidating it as an argument to the write request.\nSee open.\n\n.composite c1 c2\nMap character name c1 to character name c2 when c1 is a combining component in a  com‐\nposite glyph.  Typically, this remaps a spacing glyph to a combining one.\n"
                },
                {
                    "name": ".continue",
                    "content": "Skip  the remainder of a “while” loop's body, immediately starting the next iteration.\nSee break.\n\n.color n\nIf n is non-zero or missing, enable colors (the default), otherwise disable them.\n\n.cp n  If n is non-zero or missing, enable compatibility mode, otherwise disable it.  In com‐\npatibility mode, long names are not recognized, and the incompatibilities  they  cause\ndo not arise.\n\n.defcolor ident scheme color-component ...\nDefine a color named ident.  scheme identifies a color space and determines the number\nof required color-components; it must be one of “rgb” (three components), “cmy” (three\ncomponents),  “cmyk” (four components), or “gray” (one component).  “grey” is accepted\nas a synonym of “gray”.  The color components can be encoded as  a  hexadecimal  value\nstarting with # or ##.  The former indicates that each component is in the range 0–255\n(0–FF),  the  latter  the range 0–65535 (0–FFFF).  Alternatively, each color component\ncan be specified as a decimal fraction in the range 0–1, interpreted using  a  default\nscaling unit of “f”, which multiplies its value by 65,536 (but clamps it at 65,535).\n\nEach output device has a color named “default”, which cannot be redefined.  A device's\ndefault stroke and fill colors are not necessarily the same.\n\n.de1 name [end-name]\nDefine  a  macro  to  be  interpreted  with compatibility mode disabled.  When name is\ncalled, compatibility mode enablement status is saved; it is restored  when  the  call\ncompletes.\n\n.dei name [end-name]\nDefine  macro  indirectly, with the name of the macro to be defined in string name and\nthe name of the end macro terminating its definition in string end-name.\n\n.dei1 name [end-name]\nAs dei, but compatibility mode is disabled while the definition of the macro named  in\nstring name is interpreted.\n\n.device anything\nWrite  anything,  read  in copy mode, to troff output as a device control command.  An\ninitial neutral double quote is stripped to allow the embedding of leading spaces.\n\n.devicem name\nWrite contents of macro or string name to troff output as a device control command.\n\n.do name [arg ...]\nInterpret the string, request, diversion, or macro name  (along  with  any  arguments)\nwith  compatibility mode disabled.  Compatibility mode is restored (only if it was ac‐\ntive) when the expansion of name is interpreted; that is, the  restored  compatibility\nstate  applies to the contents of the macro, string, or diversion name as well as data\nread from files or pipes if name is any of the so, soquiet, mso, msoquiet, or pso  re‐\nquests.\n\nFor example,\n.de mac1\nFOO\n..\n.de1 mac2\ngroff\n.mac1\n..\n.de mac3\ncompatibility\n.mac1\n..\n.de ma\n\\\\$1\n..\n.cp 1\n.do mac1\n.do mac2 \\\" mac2, defined with .de1, calls \"mac1\"\n.do mac3 \\\" mac3 calls \"ma\" with argument \"c1\"\n.do mac3 \\[ti] \\\" groff syntax accepted in .do arguments\nresults in\nFOO groff FOO compatibility c1 ~\nas output.\n\n.ds1 name contents\nAs  ds, but compatibility mode is disabled while name is interpreted: a “compatibility\nsave” token is inserted at the beginning of contents, and  a  “compatibility  restore”\ntoken after it.\n\n.ecr   Restore  the  escape  character saved with ecs, or set escape character to “\\” if none\nhas been saved.\n\n.ecs   Save the current escape character.\n\n.evc env\nCopy the properties of environment env to the current environment, except for the fol‐\nlowing data.\n\n• a partially collected line, if present;\n\n• the interruption status of the previous input line (due to use of the \\c escape  se‐\nquence);\n\n• the  count  of remaining lines to center, to right-justify, or to underline (with or\nwithout underlined spaces)—these are set to zero;\n\n• the activation status of temporary indentation;\n\n• input traps and their associated data;\n\n• the activation status of line numbering (which can be reactivated  with  “.nm  +0”);\nand\n\n• the count of consecutive hyphenated lines (set to zero).\n\n.fam [family]\nSet  default font family to family.  If no argument is given, the previous font family\nis selected, or the formatter's default family if there is none.  The formatter's  de‐\nfault  font  family  is “T” (Times), but it can be overridden by the output device—see\ngrofffont(5).  The default font family is associated with the environment.  See \\F.\n\n.fchar c contents\nDefine fallback character c as contents.  The syntax of this request is  the  same  as\nthe  char  request; the difference is that a character defined with char hides a glyph\nwith the same name in the selected font, whereas characters  defined  with  fchar  are\nchecked  only if c isn't found in the selected font.  This test happens before special\nfonts are searched.\n\n.fcolor color\nSet the fill color to color.  Without an argument, the  previous  fill  color  is  se‐\nlected.\n\n.fschar f c contents\nDefine  fallback  special  character c for font f as contents.  A character defined by\nfschar is located after the list of fonts declared with fspecial is searched  but  be‐\nfore those declared with the “special” request.\n\n.fspecial f s1 s2 ...\nWhen  font  f is selected, fonts s1, s2, ... are treated as special; that is, they are\nsearched for glyphs not found in f.  Any fonts specified in the “special” request  are\nsearched  after  s1,  s2, and so on.  Without s arguments, fspecial clears the list of\nfonts treated as special when f is selected.\n\n.ftr f g\nTranslate font f to g.  Whenever a font named f is referred to in  an  \\f  escape  se‐\nquence,  in  the  F  and S conditional expression operators, or in the ft, ul, bd, cs,\ntkf, special, fspecial, fp, or sty requests, font g is used.  If g is missing or iden‐\ntical to f, then font f is not translated.\n\n.fzoom f zoom\nSet zoom factor zoom for font  f.   zoom  must  a  non-negative  integer  multiple  of\n1/1000th.   If it is missing or is equal to zero, it means the same as 1000, namely no\nmagnification.  f must be a resolved font name, not an abstract style.\n\n.gcolor color\nSet the stroke color to color.  Without an argument, the previous stroke color is  se‐\nlected.\n\n.hcode c1 code1 [c2 code2] ...\nSet  the hyphenation code of character c1 to code1, that of c2 to code2, and so on.  A\nhyphenation code must be an ordinary character (not a  special  character  escape  se‐\nquence) other than a digit.  The request is ignored if given no arguments.\n\nFor  hyphenation to work, hyphenation codes must be set up.  At startup, groff assigns\nhyphenation codes to the letters “a–z” (mapped to themselves), to  the  letters  “A–Z”\n(mapped  to  “a–z”), and zero to all other characters.  Normally, hyphenation patterns\ncontain only lowercase letters which should be applied regardless of case.   In  other\nwords,  they assume that the words “ABBOT” and “Abbot” should be hyphenated exactly as\n“abbot” is.  hcode extends this principle to letters outside the Unicode  basic  Latin\nalphabet;  without it, words containing such letters won't be hyphenated properly even\nif the corresponding hyphenation patterns contain them.\n\n.hla lang\nSet the hyphenation language to lang.  Hyphenation exceptions specified  with  the  hw\nrequest  and  hyphenation  patterns and exceptions specified with the hpf and hpfa re‐\nquests are associated with the hyphenation language.  The hla request is  usually  in‐\nvoked  by  a  localization file, which is in turn loaded by the troffrc or troffrc-end\nfile; see the hpf request below.  The hyphenation language is associated with the  en‐\nvironment.\n\n.hlm [n]\nSet  the maximum number of consecutive hyphenated lines to n.  If n is negative, there\nis no maximum.  If omitted, n is -1.  This value is associated with  the  environment.\nOnly  lines  output from a given environment count towards the maximum associated with\nthat environment.  Hyphens resulting from \\% are counted; explicit hyphens are not.\n\n.hpf pattern-file\nRead hyphenation patterns from pattern-file.  This file is sought in the same way that\nmacro files are with the mso request or the -mname command-line option to groff(1) and\ntroff(1).\n\nThe pattern-file should have the same format as (simple) TeX pattern files.  The  fol‐\nlowing scanning rules are implemented.\n\n• A  percent  sign  starts a comment (up to the end of the line) even if preceded by a\nbackslash.\n\n• “Digraphs” like \\$ are not supported.\n\n• “^^xx” (where each x is 0–9 or a–f) and ^^c (character c in  the  code  point  range\n0–127 decimal) are recognized; other uses of ^ cause an error.\n\n• No macro expansion is performed.\n\n• hpf checks for the expression \\patterns{...} (possibly with whitespace before or af‐\nter  the  braces).   Everything between the braces is taken as hyphenation patterns.\nConsequently, “{” and “}” are not allowed in patterns.\n\n• Similarly, \\hyphenation{...} gives a list of hyphenation exceptions.\n\n• \\endinput is recognized also.\n\n• For backwards compatibility, if \\patterns is missing, the whole file is treated as a\nlist of hyphenation patterns (but the “%” character is still recognized as the start\nof a comment).\n\nUse the hpfcode request (see below) to map the encoding used  in  hyphenation  pattern\nfiles to groff's input encoding.\n\nThe set of hyphenation patterns is associated with the hyphenation language set by the\nhla  request.  The hpf request is usually invoked by a localization file loaded by the\ntroffrc file.  By default, troffrc loads the localization file for  English.   (As  of\ngroff  1.23.0,  localization  files  for Czech (cs), German (de), English (en), French\n(fr), Japanese (ja), Swedish (sv), and Chinese (zh) exist.)   For  Western  languages,\nthe localization file sets the hyphenation mode and loads hyphenation patterns and ex‐\nceptions.\n\nA  second  call  to hpf (for the same language) replaces the old patterns with the new\nones.\n\nInvoking hpf causes an error if there is no hyphenation language.\n\nIf no hpf request is specified (either in the document, in a file loaded  at  startup,\nor in a macro package), GNU troff won't automatically hyphenate at all.\n\n.hpfa pattern-file\nAs  hpf, except that the hyphenation patterns and exceptions from pattern-file are ap‐\npended to the patterns already applied to the hyphenation language of the environment.\n\n.hpfcode a b [c d] ...\nDefine mapping values for character codes in pattern files.  This is an  older  mecha‐\nnism  no  longer  used by groff's own macro files; for its successor, see hcode above.\nhpf or hpfa apply the mapping after reading or appending to the active  list  of  pat‐\nterns.   Its  arguments  are pairs of character codes—integers from 0 to 255.  The re‐\nquest maps character code a to code b, code c to code d, and so on.   Character  codes\nthat  would otherwise be invalid in groff can be used.  By default, every code maps to\nitself except those for letters “A” to “Z”, which map to those for “a” to “z”.\n\n.hym [length]\nSet the (right) hyphenation margin to length.  If the adjustment mode is  not  “b”  or\n“n”,  the  line  is not hyphenated if it is shorter than length.  Without an argument,\nthe default hyphenation margin is reset to its default value, 0.  The default  scaling\nunit  is  “m”.  The hyphenation margin is associated with the environment.  A negative\nargument resets the hyphenation  margin  to  zero,  emitting  a  warning  in  category\n“range”.\n\n.hys [hyphenation-space]\nSuppress  hyphenation  of the line in adjustment modes “b” or “n”, if it can be justi‐\nfied by adding no more than hyphenation-space extra space to  each  inter-word  space.\nWithout  an argument, the hyphenation space adjustment threshold is set to its default\nvalue, 0.  The default scaling unit is “m”.  The hyphenation space adjustment  thresh‐\nold  is  associated  with the current environment.  A negative argument resets the hy‐\nphenation space adjustment threshold to zero, emitting a warning in category “range”.\n\n.itc n name\nAs “it”, but lines interrupted with the \\c escape sequence are not applied to the line\ncount.\n\n.kern n\nIf n is non-zero or missing, enable pairwise kerning (the default), otherwise  disable\nit.\n\n.length reg anything\nCompute the number of characters in anything and return the count in the register reg.\nIf reg doesn't exist, it is created.  anything is read in copy mode.\n\n.ds xxx abcd\\h'3i'efgh\n.length yyy \\*[xxx]\n\\n[yyy]\n14\n\n.linetabs n\nIf  n  is  non-zero  or  missing, enable line-tabs mode, otherwise disable it (the de‐\nfault).  In this mode, tab stops are computed relative to the  start  of  the  pending\noutput  line,  instead of the drawing position corresponding to the start of the input\nline.  Line-tabs mode is a property of the environment.\n\nFor example, the following\n\n.ds x a\\t\\c\n.ds y b\\t\\c\n.ds z c\n.ta 1i 3i\n\\*x\n\\*y\n\\*z\nyields\na         b         c\nwhereas in line-tabs mode, the same input gives\na         b                   c\ninstead.\n\n.lsm [name]\nSet the leading space macro (trap) to name.  If there are leading space characters  on\nan  input line, name is invoked in lieu of the usual roff behavior; the leading spaces\nare removed.  The count of leading spaces on an input line is stored in  \\n[lsn],  and\nthe  amount  of  corresponding horizontal motion in \\n[lss], irrespective of whether a\nleading space trap is set.  When it is, the leading spaces are removed from the  input\nline,  and no motion is produced before calling name.  If no argument is supplied, the\ndefault leading space behavior is (re-)established.\n\n.mso file\nAs “so”, except that file is sought in  the  same  directories  as  arguments  to  the\ngroff(1)  and troff(1) -m command-line option are (the “tmac path”).  If the file name\nto be interpolated has the form name.tmac and it isn't found,  mso  tries  to  include\ntmac.name  instead  and  vice  versa.   If  file does not exist, a warning in category\n“file” is emitted and the request has no other effect.\n\n.msoquiet file\nAs mso, but no warning is emitted if file does not exist.\n\n.nop anything\nInterpret anything as if it were an input line.  nop resembles  “.if  1”;  it  puts  a\nbreak  on  the output if anything is empty.  Unlike “if”, it cannot govern conditional\nblocks.  Its application is to maintain consistent indentation  within  macro  defini‐\ntions even when producing text lines.\n\n.nroff Make the n conditional expression evaluate true and t false.  See troff.\n\n.open stream file\nOpen file for writing and associate stream with it.  See write and close.\n\n.opena stream file\nAs open, but if file exists, append to it instead of truncating it.\n\n.output contents\nEmit  contents,  which are read in copy mode, to the formatter output; this is similar\nto \\! used in the top-level diversion.  An initial neutral double quote in contents is\nstripped to allow the embedding of leading spaces.\n\n.pev   Report the state of the current environment followed by that of all other environments\nto the standard error stream.\n\n.pnr   Write the names and values of all currently defined registers to  the  standard  error\nstream.\n\n.psbb file\nGet  the  bounding  box of a PostScript image file.  This file must conform to Adobe's\nDocument Structuring Conventions; the request attempts to  extract  the  bounding  box\nvalues  from  a  %%BoundingBox comment.  After invocation, the x and y coordinates (in\nPostScript units) of the lower left and upper right corners can be found in the regis‐\nters \\n[llx], \\n[lly], \\n[urx], and \\n[ury], respectively.  If an error occurs,  these\nfour registers are set to zero.\n\n.pso command\nAs “so”, except that input comes from the standard output stream of command.\n\n.ptr   Report the names and vertical positions of all page location traps to the standard er‐\nror  stream.   Empty  slots in the list are shown as well, because they can affect the\nvisibility of subsequently planted traps.\n\n.pvs ±n\nSet the post-vertical line spacing to n; default scaling unit is “p”.  With  no  argu‐\nment, the post-vertical line space is set to its previous value.\n\nIn  GNU  troff, the distance between text baselines consists of the extra pre-vertical\nline spacing set by the most negative \\x argument on the pending output line, the ver‐\ntical spacing (vs), the extra post-vertical line spacing set by the most  positive  \\x\nargument  on  the  pending output line, and the post-vertical line spacing set by this\nrequest.\n\n.rchar c ...\nRemove definition of each ordinary or special character c, undoing  the  effect  of  a\nchar,  fchar,  or schar request.  Glyphs, which are defined by font description files,\ncannot be removed.  Spaces and tabs may separate c arguments.\n"
                },
                {
                    "name": ".return",
                    "content": "Within a macro, return immediately.  If called with an argument, return twice,  namely\nfrom the current macro and from the macro one level higher.  No effect otherwise.\n\n.rfschar f c ...\nRemove  each  fallback special character c for font f.  Spaces and tabs may separate c\narguments.  See fschar.\n\n.rj [n]\nRight-align the next n input lines.  Without an argument, right-align the  next  input\nline.  rj implies “.ce 0”, and ce implies “.rj 0”.\n\n.rnn r1 r2\nRename register r1 to r2.  If r1 doesn't exist, the request is ignored.\n\n.schar c contents\nDefine  global  fallback character c as contents.  See char; the distinction is that a\ncharacter defined with schar is located after the list  of  fonts  declared  with  the\nspecial request but before any mounted special fonts.\n\n.shc [c]\nSet  the soft hyphen character, inserted when a word is hyphenated automatically or at\na hyphenation character, to c.  If c is omitted, the soft hyphen character is  set  to\nthe  default, \\[hy].  If the selected glyph does not exist in the font in use at a po‐\ntential hyphenation point, then the line is not broken at that point.  Neither charac‐\nter definitions (char and similar) nor translations (tr and  similar)  are  considered\nwhen assigning the soft hyphen character.\n\n.shift n\nIn a macro, shift the arguments by n positions: argument i becomes argument i-n; argu‐\nments  1  to  n are no longer available.  If n is missing, arguments are shifted by 1.\nNo effect otherwise.\n\n.sizes s1 s2 ... sn [0]\nSet the available type sizes to s1, s2, ... sn scaled points.  The list of  sizes  can\nbe  terminated  by  an optional “0”.  Each si can also be a range m–n.  In contrast to\nthe device description file directive of the same name (see grofffont(5)), the  argu‐\nment list can't extend over more than one line.\n\n.soquiet file\nAs “so”, but no warning is emitted if file does not exist.\n\n.special f ...\nDeclare  each  font  f  as  special, searching it for glyphs not found in the selected\nfont.  Without arguments, this list of special fonts is made empty.\n\n.spreadwarn [limit]\nEmit a break warning if the additional space inserted for each space between words  in\nan output line adjusted to both margins with “.ad b” is larger than or equal to limit.\nA negative value is treated as zero; an absent argument toggles the warning on and off\nwithout changing limit.  The default scaling unit is m.  At startup, spreadwarn is in‐\nactive and limit is 3 m.\n\nFor  example, “.spreadwarn 0.2m” causes a warning if break warnings are not suppressed\nand troff must add 0.2 m or more for each inter-word space in a line.\n\n.stringdown str\n.stringup str\nAlter the string named str by replacing each of its bytes with its lowercase (down) or\nuppercase (up) version (if one exists).  Special characters (see  groffchar(7))  will\noften  transform in the expected way due to the regular naming convention for accented\ncharacters.  When they do not, use substrings and/or catenation.\n\n.ds resume R\\['e]sum\\['e]\\\"\n\\*[resume]\n.stringdown resume\n\\*[resume]\n.stringup resume\n\\*[resume]\nRésumé résumé RÉSUMÉ\n\n.sty n s\nAssociate abstract style s with font mounting position n.\n\n.substring string start [end]\nReplace the string named string with its substring bounded by the  indices  start  and\nend,  inclusively.  The first character in the string has index 0.  If end is omitted,\nit is implicitly set to the largest valid value (the string length minus one).   Nega‐\ntive  indices  count  backwards from the end of the string: the last character has in‐\ndex -1, the character before the last has index -2, and so on.\n\n.ds xxx abcdefgh\n.substring xxx 1 -4\n\\*[xxx]\nbcde\n.substring xxx 2\n\\*[xxx]\nde\n\n.tkf f s1 n1 s2 n2\nEnable track kerning for font f.  When the current font is f the width of every  glyph\nis  increased  by an amount between n1 and n2; when the current type size is less than\nor equal to s1 the width is increased by n1; when it is greater than or  equal  to  s2\nthe  width  is  increased by n2; when the type size is greater than or equal to s1 and\nless than or equal to s2 the increase in width is a linear function of the type size.\n\n.tm1 message\nAs tm request, but strips a leading neutral double quote from message to allow the em‐\nbedding of leading spaces.\n\n.tmc message\nAs tm1 request, but does not append a newline.\n\n.trf file\nTransparently output the contents of file file.  Each line is output as if preceded by\n\\!; however, the lines are not subject to copy-mode interpretation.  If the file  does\nnot end with a newline, then a newline is added.  Unlike cf, file cannot contain char‐\nacters that are invalid as input to GNU troff.\n\nFor example, you can define a macro x containing the contents of file f, using\n\n.di x\n.trf f\n.di\n\n.trin abcd\nThis  is the same as the tr request except that the asciify request uses the character\ncode (if any) before the character translation.  Example:\n\n.trin ax\n.di xxx\na\n.br\n.di\n.xxx\n.trin aa\n.asciify xxx\n.xxx\n\nThe result is “x a”.  Using tr, the result would be “x x”.\n\n.trnt abcd\nThis is the same as the tr request except that the translations do not apply  to  text\nthat is transparently throughput into a diversion with \\!.  For example,\n\n.tr ab\n.di x\n\\!.tm a\n.di\n.x\n\nprints b; if trnt is used instead of tr it prints a.\n\n.troff Make the t conditional expression evaluate true and n false.  See nroff.\n\n.unformat div\nUnformat the diversion div.  Unlike asciify, unformat handles only tabs and spaces be‐\ntween  words,  the  latter usually arising from spaces or newlines in the input.  Tabs\nare treated as input tokens, and spaces become adjustable again.  The  vertical  sizes\nof  lines  are not preserved, but glyph information (font, type size, space width, and\nso on) is retained.\n\n.vpt n If n is non-zero or missing, enable vertical position traps (the  default),  otherwise\ndisable them.  Vertical position traps are those set by the ch, wh, and dt requests.\n\n.warn [n]\nSelect  the categories, or “types”, of reported warnings.  n is the sum of the numeric\ncodes associated with each warning category that is to be  enabled;  all  other  cate‐\ngories  are disabled.  The categories and their associated codes are listed in section\n“Warnings” of troff(1).  For example, “.warn 0” disables all warnings, and  “.warn  1”\ndisables all warnings except those about missing glyphs.  If no argument is given, all\nwarning categories are enabled.\n\n.warnscale si\nSet  the  scaling  unit used in warnings to si.  Valid values for si are u, i (the de‐\nfault), c, p, and P.\n\n.while cond-expr anything\nEvaluate the conditional expression cond-expr, and repeatedly execute anything  unless\nand until cond-expr evaluates false.  anything, which is often a conditional block, is\nreferred to as the while request's body.\n\ntroff treats the body of a while request similarly to that of a de request (albeit one\nnot  read  in copy mode), but stores it under an internal name and deletes it when the\nloop finishes.  The operation of a macro containing a while request can slow  signifi‐\ncantly if the while body is large.  Each time the macro is executed, the while body is\nparsed  and  stored  again.   An  often better solution—and one that is more portable,\nsince AT&T troff lacked the while request—is to instead write a recursive  macro.   It\nwill be parsed only once (unless you redefine it).  To prevent infinite loops, the de‐\nfault  number  of available recursion levels is 1,000 or somewhat less (because things\nother than macro calls can be on the input stack).  You can  disable  this  protective\nmeasure,  or raise the limit, by setting the slimit register.  See section “Debugging”\nbelow.\n\nIf a while body begins with a conditional block, its closing brace must end  an  input\nline.\n\nThe break and continue requests alter a while loop's flow of control.\n\n.write stream anything\nWrite  anything  to stream, which must previously have been the subject of an open re‐\nquest, followed by a newline.  anything is read in copy mode.  An initial neutral dou‐\nble quote in anything is stripped to allow the embedding of leading spaces.\n\n.writec stream anything\nAs write, but without a trailing newline.\n\n.writem stream name\nWrite the contents of the macro or string name to stream, which must  previously  have\nbeen the subject of an open request.  name is read in copy mode.\n"
                },
                {
                    "name": "Extended requests",
                    "content": ".cf file\nIn a diversion, embed an object which, when reread, will cause the contents of file to\nbe copied verbatim to the output.  In AT&T troff, the contents of file are immediately\ncopied  to  the output regardless of whether a diversion is being written to; this be‐\nhavior is so anomalous that it must be considered a bug.\n\n.de name [end-name]\n.am name [end-name]\n.ds name [contents]\n.as name [contents]\nIn compatibility mode, these requests behave similarly to de1, am1, ds1, and as1,  re‐\nspectively: a “compatibility save” token is inserted at the beginning, and a “compati‐\nbility  restore”  token  at the end, with compatibility mode switched on during execu‐\ntion.\n\n.hy n  New values 16 and 32 are available; the former enables  hyphenation  before  the  last\ncharacter in a word, and the latter enables hyphenation after the first character in a\nword.\n\n.ss word-space-size [additional-sentence-space-size]\nA second argument sets the amount of additional space separating sentences on the same\noutput  line.   If omitted, this amount is set to word-space-size.  Both arguments are\nin twelfths of current font's space width (typically one-fourth to  one-third  em  for\nWestern scripts; see grofffont(5)).  The default for both parameters is 12.  Negative\nvalues are erroneous.\n\n.ta [[n1 n2 ... nn ]T r1 r2 ... rn]\ngroff  supports  an extended syntax to specify repeating tab stops after the “T” mark.\nThese values are always taken as relative distances from the previous tab stop.   This\nis the idiomatic way to specify tab stops at equal intervals in groff.\n\nThe  syntax  summary  above  instructs groff to set tabs at positions n1, n2, ..., nn,\nthen at nn+r1, nn+r2, ..., nn+rn, then at nn+rn+r1, nn+rn+r2, ...,  nn+rn+rn,  and  so\non.\n"
                },
                {
                    "name": "New registers",
                    "content": "GNU  troff  exposes more formatter state via many new read-only registers.  Their names often\ncorrespond to the requests that affect them.\n\n\\n[.br]     Within a macro call, interpolate 1 if the macro is called with the “normal”  con‐\ntrol character (“.” by default), and 0 otherwise.  This facility allows the reli‐\nable modification of requests.  Using this register outside of a macro definition\nmakes no sense.\n\n.als bp*orig bp\n.de bp\n.tm before bp\n.ie \\\\n[.br] .bp*orig\n.el 'bp*orig\n.tm after bp\n..\n\n\\n[.C]      Interpolate 1 if compatibility mode is in effect, 0 otherwise.  See cp.\n\n\\n[.cdp]    Interpolate  depth of last glyph added to the environment.  It is positive if the\nglyph extends below the baseline.\n\n\\n[.ce]     Interpolate number of input lines remaining to be centered.\n\n\\n[.cht]    Interpolate height of last glyph added to the environment.  It is positive if the\nglyph extends above the baseline.\n\n\\n[.color]  Interpolate 1 if colors are enabled, 0 otherwise.\n\n\\n[.cp]     Within a “do” request, interpolate the saved value  of  compatibility  mode  (see\n\\n[.C] above).\n\n\\n[.csk]    Interpolate  skew of last glyph added to the environment.  The skew of a glyph is\nhow far to the right of the center of a glyph the center of an accent  over  that\nglyph should be placed.\n\n\\n[.ev]     Interpolate name of current environment.  This is a string-valued register.\n\n\\n[.fam]    Interpolate name of default font family.  This is a string-valued register.\n\n\\n[.fn]     Interpolate  resolved  name of the selected font.  This is a string-valued regis‐\nter.\n\n\\n[.fp]     Interpolate next free font mounting position.\n\n\\n[.g]      Interpolate 1.  Test with “if” or ie to check whether GNU troff is the formatter.\n\n\\n[.height] Interpolate font height.  See \\H.\n\n\\n[.hla]    Interpolate hyphenation language of the environment.   This  is  a  string-valued\nregister.\n\n\\n[.hlc]    Interpolate  count  of  immediately preceding consecutive hyphenated lines in the\nenvironment.\n\n\\n[.hlm]    Interpolate maximum number of consecutive hyphenated lines allowed in  the  envi‐\nronment.\n\n\\n[.hy]     Interpolate hyphenation mode of the environment.\n\n\\n[.hym]    Inteprolate hyphenation margin of the environment.\n\n\\n[.hys]    Interpolate hyphenation space adjustment threshold of the environment.\n\n\\n[.in]     Interpolate indentation amount applicable to the pending output line.\n\n\\n[.int]    Interpolate 1 if the previous output line was interrupted (ended with \\c), 0 oth‐\nerwise.\n\n\\n[.kern]   Interpolate 1 if pairwise kerning is enabled, 0 otherwise.\n\n\\n[.lg]     Interpolate ligature mode.\n"
                },
                {
                    "name": "\\n[.linetabs]",
                    "content": "Interpolate 1 if line-tabs mode is enabled, 0 otherwise.\n\n\\n[.ll]     Interpolate line length applicable to the pending output line.\n\n\\n[.lt]     Interpolate title line length.\n\n\\n[.m]      Interpolate name of the selected stroke color.  This is a string-valued register.\n\n\\n[.M]      Interpolate name of the selected fill color.  This is a string-valued register.\n\n\\n[.ne]     Interpolate  amount of space demanded by the most recent ne request that caused a\npage location trap to be sprung.  See \\n[.trunc].\n\n\\n[.nm]     Interpolate 1 if output line numbering  is  enabled  (even  if  temporarily  sup‐\npressed), 0 otherwise.\n\n\\n[.ns]     Interpolate 1 if no-space mode is enabled, 0 otherwise.\n\n\\n[.O]      Interpolate output suppression level.  See \\O.\n\n\\n[.P]      Interpolate  1  if  the current page is selected for output.  See -o command-line\noption to troff(1).\n\n\\n[.pe]     Interpolate 1 during page ejection, 0 otherwise.\n\n\\n[.pn]     Interpolate next page number (either that set by pn, or that of the current  page\nplus 1).\n\n\\n[.ps]     Interpolate type size in scaled points.\n\n\\n[.psr]    Interpolate most recently requested type size in scaled points.\n\n\\n[.pvs]    Interpolate post-vertical line spacing amount.\n\n\\n[.rj]     Interpolate number of input lines remaining to be right-aligned.\n\n\\n[.slant]  Interpolate font slant.  See \\S.\n\n\\n[.sr]     Interpolate  most  recently  requested type size in points as a decimal fraction.\nThis is a string-valued register.\n"
                },
                {
                    "name": "\\n[.ss]",
                    "content": "\\n[.sss]    Interpolate values of minimal  inter-word  space  and  additional  inter-sentence\nspace, respectively, in twelfths of the space width of the selected font.\n\n\\n[.sty]    Interpolate selected abstract font style, if any.  This is a string-valued regis‐\nter.\n\n\\n[.tabs]   Interpolate  representation  of the tab stop settings in a form suitable for pas‐\nsage to the ta request.\n\n\\n[.trunc]  Interpolate amount of vertical space truncated by the most recently  sprung  page\nlocation  trap,  or, if the trap was sprung by an ne request, minus the amount of\nvertical motion produced by the ne request.  In other words, at the point a  trap\nis  sprung,  \\n[.trunc]  represents  the difference of what the vertical position\nwould have been but for the trap, and what the  vertical  position  actually  is.\nSee \\n[.ne].\n\n\\n[.U]      Interpolate  1  if  in  unsafe  mode, 0 otherwise.  See -U command-line option to\ntroff(1).\n\n\\n[.vpt]    Interpolate 1 if vertical position traps are enabled, 0 otherwise.\n\n\\n[.warn]   Interpolate warning mode.  See section “Warnings” of troff(1).\n\n\\n[.x]      Interpolate major version number of the running troff formatter.  For example, if\nthe version number is 1.23.0, then \\n[.x] contains 1.\n\n\\n[.y]      Interpolate minor version number of the running troff formatter.  For example, if\nthe version number is 1.23.0, then \\n[.y] contains 23.\n\n\\n[.Y]      Interpolate revision number of the running troff formatter.  For example, if  the\nversion number is 1.23.0, then \\n[.Y] contains 0.\n\n\\n[.zoom]   Interpolate  magnification of font, in thousandths, or 0 if magnification unused.\nSee fzoom.\n\nThe following (writable) registers are set by the psbb request.\n"
                },
                {
                    "name": "\\n[llx]",
                    "content": ""
                },
                {
                    "name": "\\n[lly]",
                    "content": ""
                },
                {
                    "name": "\\n[urx]",
                    "content": ""
                },
                {
                    "name": "\\n[ury]",
                    "content": "Interpolate the (upper, lower, left, right) bounding box values (in PostScript  units)\nof the most recently processed PostScript image.\n\nThe following (writable) registers are set by the \\w escape sequence.\n"
                },
                {
                    "name": "\\n[rst]",
                    "content": "\\n[rsb] Like  \\n[st]  and \\n[sb], but taking account of the heights and depths of glyphs.  In\nother words, these registers store the highest and lowest vertical positions attained\nby the argument formatted by the \\w escape sequence, doing what AT&T troff documented\n\\n[st] and \\n[sb] as doing.\n\n\\n[ssc] The amount of horizontal space (possibly negative) that should be added to  the  last\nglyph before a subscript.\n\n\\n[skw] How far to right of the center of the last glyph in the \\w argument, the center of an\naccent from a roman font should be placed over that glyph.\n\nOther writable registers are as follows.  Those relating to date and time are initialized us‐\ning localtime(3) at formatter startup.\n\n\\n[c.]      Interpolate input line number.  \\n[.c] is a read-only alias of this register.\n\n\\n[hours]   Interpolate number of hours elapsed since midnight.\n\n\\n[hp]      Interpolate horizontal position relative to that at the start of the input line.\n"
                },
                {
                    "name": "\\n[lsn]",
                    "content": "\\n[lss]     Interpolate  count  of  leading  spaces on input line and amount of corresponding\nhorizontal motion, respectively.\n\n\\n[minutes] Interpolate number of minutes elapsed in the hour.\n\n\\n[seconds] Interpolate number of seconds elapsed in the minute.\n\n\\n[systat]  Interpolate return value of system(3) function executed by  most  recent  sy  re‐\nquest.\n\n\\n[slimit]  Interpolates  maximum  quantity  of  objects on troff's internal input stack (de‐\nfault: 1000).  If non-positive, there is no limit: recursion can  continue  until\nprogram memory is exhausted.\n\n\\n[year]    Interpolate  Gregorian  year.  AT&T troff's \\[yr] interpolates the Gregorian year\nminus 1900.\n"
                },
                {
                    "name": "Miscellaneous",
                    "content": "GNU troff predefines one string, .T, containing the argument given to the -T command-line op‐\ntion, namely the output device (for example, pdf or utf8).  The (read-only) register  .T  in‐\nterpolates 1 if GNU troff is run with the -T command-line option, and 0 otherwise.\n\nA font not listed in the output device's DESC file's fonts directive is automatically mounted\nat the next available font position when it is selected.  If you mount a font explicitly with\nthe  fp request, you should do so on the first unused position, which can be found in the .fp\nregister.\n\nUnparameterized string interpolation does not conceal the arguments to a macro  being  inter‐\npreted.   Thus,  in  a macro definition, the call of another macro with the existing argument\nlist,\n.xx \\\\$@\nis more efficiently done with\n\\\\*[xx]\\\\\n(that is, with string interpolation).  The trailing backslashes prevent the final newline  in\nthe  macro  definition from being interpolated, potentially putting an unwanted blank line on\nthe output.  See section “Punning Names” in groff(7).\n\nIf a font description file contains pairwise kerning information, glyphs from that  font  are\nkerned.   Kerning between two glyphs can be inhibited by placing a dummy character \\& between\nthem.\n\nGNU troff keeps track of the nesting depth of escape sequence interpolations and  other  uses\nof  delimiters,  as in the tl request and the output comparison operator (that is, input like\n'foo'bar' as a conditional expression), so the only characters you need to avoid using as de‐\nlimiters are those that appear in the arguments you input, not any that result from  interpo‐\nlation.   Typically,  '  works  fine.  Use visible characters as delimiters in GNU troff, not\n“ASCII” controls like BEL (Control+G).  The implementation of \\$@  ensures  that  the  double\nquotes  surrounding  an  argument appear at an interpolation depth different from that of the\narguments themselves.  Similarly, in bracket-form escape sequences  like  \\f[ZCMI],  a  right\nbracket  ]  does not end the sequence unless it occurs at the same interpolation depth as the\nopening [, so input like\n\\f[\\*[my-family]\\*[my-style]]\nworks as desired.  In compatibility mode, no attention is paid to the interpolation depth.\n\nIn GNU troff, the tr request can map characters to the unbreakable space escape  sequence  \\~\nas  a special case (tr normally operates only on characters).  This feature replaces the odd-\nparity tr mapping trick used in AT&T troff documents, where a character, often ~, was “sacri‐\nficed” by mapping it to “nothing”, drafting it  into  use  as  an  unadjustable,  unbreakable\nspace.  (This feature was gratuitous even in early AT&T troff, which supported the \\space es‐\ncape sequence by 1976.)  Often, it makes more sense to use GNU troff's \\~ escape sequence in‐\nstead, which has been adopted by every other active troff implementation except that of Illu‐\nmos, as well as by the non-troff mandoc.  Translation of a character to \\~ is unnecessary.\n\nGNU troff permits tabs and spaces after the first dot on a control line that ends a macro de‐\nfinition.\n.if t \\{\\\n.  de bar\n.    nop Hello, I'm 'bar'.\n.  .\n.\\}\n"
                }
            ]
        },
        "Formatter output": {
            "content": "The  page  description  language output by GNU troff is modeled after that used by AT&T troff\nonce the latter adopted a device-independent approach in the early 1980s.  Only  the  differ‐\nences are documented here.  For a fuller discussion, see groffout(5).\n\nGlyph  and  font names can be of arbitrary length; postprocessors should not assume that they\nare at most two characters.  A glyph to be formatted is always drawn from the  current  font;\nin contrast to AT&T device-independent troff, drivers need not search special fonts to find a\nglyph.\n",
            "subsections": [
                {
                    "name": "Units",
                    "content": "The argument to the s command is in scaled points (units of points/n, where n is the argument\nto  the  sizescale  command  in the DESC file).  The argument to the “x H” command is also in\nscaled points.\n"
                },
                {
                    "name": "Simple commands",
                    "content": "If the tcommand directive is present in the output device's DESC file, GNU troff employs  the\nfollowing two commands.\n\nt xyz...\nTypeset  word xyz; that is, set a sequence of ordinary glyphs named x, y, z, ..., ter‐\nminated by a space or newline; an optional second integer argument  is  ignored  (this\nallows  the  formatter to generate an even number of arguments).  Each glyph is set at\nthe current drawing position, and the position is then advanced  horizontally  by  the\nglyph's width.  A glyph's width is read from its metrics in the font description file,\nscaled  to  the  current type size, and rounded to a multiple of the horizontal motion\nquantum.  Use the C command to emplace glyphs of special characters.\n\nu n xyz...\nTypeset word xyz with track kerning.  As t, but after placing each glyph, the  drawing\nposition is further advanced horizontally by n basic units.\n\nNew commands implement color support.\n\nmc cyan magenta yellow\nmd\nmg gray\nmk cyan magenta yellow black\nmr red green blue\nSet  the  components of the stroke color with respect to various color spaces.  md re‐\nsets the stroke color to the default value.  The arguments are integers in the range 0\nto 65535.\n\nA new device control subcommand is available.\n\nx u n  If n is 1, start underlining of spaces.  If n is 0, stop underlining of spaces.   This\nfacility is needed for the cu request in nroff mode and is ignored otherwise.\n"
                },
                {
                    "name": "Extended drawing commands",
                    "content": "GNU  pic  does not produce troff escape sequences employing these extensions if its -n option\nis given.\n\nDf n   Set the shade of gray used to fill geometric objects to n, which must be  an  integer.\n0  corresponds  to  white and 1000 to black.  A grayscale ramp spans the two.  A value\noutside this range uses the stroke color as the fill color.  The fill color is opaque.\nNormally the default is black, but some drivers may provide a way  of  changing  this.\nDf is obsolete since 2002, superseded by DFg below.\n\nThe corresponding \\D'f' escape sequence should not be used: its argument is rounded to\nan  integer  multiple  of the horizontal motion quantum, which can limit the precision\nof n.\n\nDC d   Draw a filled circle of diameter d with its leftmost point at the drawing position.\n\nDE h v Draw a filled ellipse, of horizontal axis h and vertical axis  v,  with  its  leftmost\npoint at the drawing position.\n\nDp dx1dy1...dxndyn\nDraw  a  polygon  with,  for  i=1,...,n+1,  its  ith  vertex  at  the drawing position\n+j−=Σ1(dxj,dyj).  groff output drivers automatically close polygons, drawing a line from\n(dxn,dyn) back to (dx1,dy1).  The drawing position is left at the last specified  ver‐\ntex,  but  this may change in a future version of GNU troff.  Heirloom Doctools troff,\nlike DWB troff, by default does not close the polygon.   In  its  groff  compatibility\nmode,  Heirloom  closes the polygon but leaves the drawing position unchanged—that is,\nat the polygon's initial drawing position.\n\nAt the moment, GNU pic uses this command only to generate triangles and rectangles.\n\nDP dx1dy1...dxndyn\nAs Dp, but draw a filled rather than a stroked polygon.\n\nDt n   Set the line thickness to n basic units.  AT&T troff output drivers  use  a  thickness\nproportional  to  the type size; this is the GNU troff default.  A negative n requests\nthis explicitly.  An n of zero selects the smallest available line thickness.\n\nA difficulty arises in how the drawing position should be  changed  after  the  execution  of\nthese  commands.   This  has little importance to most users, since the output of GNU grn and\npic does not depend on it.  Given a drawing command of the form Dz x1y1...xnyn,  where  z  is\nnot  c or e, AT&T troff treats each xi as a horizontal motion, each yi as a vertical one, and\ntherefore assumes that the width of the drawn object is  in=Σ1xi,  and  its  height  is  in=Σ1yi.\n(Verify  its  assumption about height by examining the st and sb registers after using such a\ndrawing command in a \\w escape sequence).  For the sake of compatibility, GNU troff also fol‐\nlows this rule, even though it frustrates extensions to the D command that set drawing  para‐\nmeters  rather  than  rendering  objects, producing ugly results in the case of Dt and Df, or\notherwise don't parameterize objects as a series of vertices, as with GNU troff's filled  el‐\nlipse, DE.  Thus after executing a D command of the form Dz x1y1...xnyn, the drawing position\nshould  be increased by (in=Σ1xi,in=Σ1yi).  In a future release, GNU troff and its output drivers\nmay abandon the application of this assumption to drawing commands not  explicitly  specified\nin the AT&T “Troff User's Manual”.\n\nFill color selection is implemented with another set of extensions.\n\nDFc cyan magenta yellow"
                },
                {
                    "name": "DFd",
                    "content": "DFg gray\nDFk cyan magenta yellow black\nDFr red green blue\nSet  the components of the fill color as described under the \\M escape sequence above.\nDFd restores the device's default fill color.  The drawing position is not updated, in\ncontrast to Df.\n"
                },
                {
                    "name": "Device control syntax extension",
                    "content": "GNU troff introduces a line continuation convention, permitting the argument to the x X  com‐\nmand  to contain newlines.  A newline in the input is transformed to the sequence “newline+”.\nWhen interpreting an x X command, a postprocessor should therefore be  prepared  for  a  plus\nsign after a newline; if it occurs, preserve the newline, discard the plus sign, and continue\nto  collect the input into the argument of the x X command.  A newline not followed by a plus\nsign terminates the x X command.  An application of this feature is the  embedding  of  Post‐\nScript or PDF language command streams into troff output.\n\nGNU troff guarantees that the first three output commands it emits are as follows.\n\nx T device\nx res n h v\nx init\n"
                }
            ]
        },
        "Debugging": {
            "content": "In  addition  to AT&T troff's debugging features, GNU troff emits more error diagnostics when\nsyntactical or semantic nonsense is encountered and supports several warning categories;  the\noutput  of these can be selected with warn.  Also see the -E, -w, and -W options of troff(1).\nBacktraces can be automatically produced when errors or warnings  occur  (the  -b  option  of\ntroff(1)) or generated on demand (backtrace).\n\ngroff also adds more flexible diagnostic output requests (tmc and tm1).  More aspects of for‐\nmatter state can be examined with requests that write lists of defined registers (pnr), envi‐\nronments (pev), and page location traps (ptr) to the standard error stream.\n",
            "subsections": []
        },
        "Implementation differences": {
            "content": "GNU  troff's  features  sometimes cause incompatibilities with documents written assuming old\nimplementations of troff.  Some GNU extensions to troff are supported  by  other  implementa‐\ntions.\n\nWhen  adjusting  to both margins, AT&T troff at first adjusts spaces starting from the right;\nGNU troff begins from the left.  Both implementations adjust spaces from opposite ends on al‐\nternating output lines to prevent “rivers” in the text.\n\nGNU troff does not always hyphenate words as AT&T troff does.  The AT&T implementation uses a\nset of hard-coded rules specific to U.S. English, while GNU troff uses language-specific  hy‐\nphenation  pattern files derived from TeX.  In some versions of troff there was limited space\nto store hyphenation exceptions (arguments to the hw request); GNU troff has no such restric‐\ntion.\n\nLong names may be GNU troff's most obvious innovation.  AT&T troff  interprets  “.dsabcd”  as\ndefining  a string “ab” with contents “cd”.  Normally, GNU troff interprets this as a call of\na macro named “dsabcd”.  AT&T troff also interprets \\*[ and \\n[  as  an  interpolation  of  a\nstring or register, respectively, called “[”.  In GNU troff, however, the “[” is normally in‐\nterpreted  as beginning the enclosure of a long identifier.  In compatibility mode, GNU troff\ninterprets names in the traditional way, which means that they are  limited  to  one  or  two\ncharacters.   See  the -C option in troff(1) and, above, the .C and .cp registers, and cp and\n“do” requests, for more on compatibility mode.\n\nThe register \\n[.cp] is specialized and may require a statement of rationale.   When  writing\nmacro  packages  or  documents  that use GNU troff features and which may be mixed with other\npackages or documents that do not—common scenarios include serial processing of man pages  or\nuse  of the “so” or mso requests—you may desire correct operation regardless of compatibility\nmode enablement in the surrounding context.  It may occur to you to save the  existing  value\nof \\n(.C into a register, say, C, at the beginning of your file, turn compatibility mode off\nwith  “.cp  0”,  then restore it from that register at the end with “.cp \\n(C”.  At the same\ntime, a modular design of a document or macro package may lead you to multiple layers of  in‐\nclusion.   You cannot use the same register name everywhere lest you “clobber” the value from\na preceding or enclosing context.  The two-character register name space  of  AT&T  troff  is\nconfining  and  mnemonically challenging; you may wish to use GNU troff's more capacious name\nspace.  However, attempting “.nr mysavedC \\n(.C” will not work in compatibility mode;  the\nregister name is too long.  “This is exactly what .do is for,” you think, “.do nr mysavedC\n\\n(.C”.  The foregoing will always save zero to your register, because “do” turns compatibil‐\nity mode off while it interprets its argument list.  What you need is:\n.do nr mysavedC \\n[.cp]\n.cp 0\nat the beginning of your file, followed by\n.cp \\n[mysavedC]\n.do rr mysavedC\nat  the end.  As in the C language, we all have to share one big name space, so choose a reg‐\nister name that is unlikely to collide with other uses.\n\nThe existence of the .T string is a common feature of post-CSTR #54 troffs—DWB 3.3,  Solaris,\nHeirloom  Doctools, and Plan 9 troff all support it—but valid values are specific to each im‐\nplementation.  The behavior of the .T register in GNU troff differs from  AT&T  troff,  which\ninterpolated 1 only if nroff was the formatter and was called with -T.\n\nThe  lf  request sets the number of the current input line in AT&T troff, and the next in GNU\ntroff.\n\nAT&T troff had only environments named “0”, “1”, and “2”.  In GNU troff, any number of  envi‐\nronments may exist, using any valid identifiers for their names.\n\nGNU troff normally tracks the interpolation depth of escape sequence parameters and other de‐\nlimited structures, but not in compatibility mode.  See section “Miscellaneous” above.\n\nIn compatibility mode, the escape sequences \\f, \\H, \\m, \\M, \\R, \\s, and \\S are transparent at\nthe  beginning  of  an input line for the purpose of recognizing a control character, because\nthey modify formatter state (\\R) or properties of the environment (the rest) and therefore do\nnot create output nodes.  For example, this code produces bold output in both cases, but  the\ntext differs,\n.de xx '\nHello!\n..\n\\fB.xx\\fP\nformatting “.xx” normally and “Hello!” in compatibility mode.\n\nGNU  troff  request names unrecognized by other troff implementations will likely be ignored;\nescape sequences that are GNU troff extensions are liable to format their  function  selector\ncharacter.   For  example, the adjustable, non-breaking space escape sequence \\~ is also sup‐\nported by Heirloom  Doctools  troff  050915  (September  2005),  mandoc  1.9.5  (2009-09-21),\nneatroff (commit 1c6ab0f6e, 2016-09-13), and Plan 9 from User Space troff (commit 93f8143600,\n2022-08-12), but not by Solaris/Illumos troffs, which will render it as ~.\n\nGNU  troff does not allow the use of the escape sequences \\|, \\^, \\&, \\{, \\}, \\space, \\', \\`,\n\\-, \\, \\!, \\%, or \\c in identifiers; AT&T troff does.  The \\A escape sequence  (see  subsec‐\ntion “Escape sequences” above) may be helpful in avoiding their use.\n\nNormally,  the  syntax form \\sn accepts only a single character (a digit) for n, consistently\nwith other forms that originated in AT&T troff, like \\*, \\$, \\f, \\g, \\k, \\n, and \\z.  In com‐\npatibility mode only, a non-zero n must be in the range 4–39.  Legacy documents relying  upon\nthis  quirk  of parsing should be migrated to another \\s form.  [Background: The Graphic Sys‐\ntems C/A/T phototypesetter (the original device target for AT&T troff) supported only  a  few\ndiscrete  type  sizes  in  the  range 6–36 points, so Ossanna contrived a special case in the\nparser to do what the user must have meant.  Kernighan warned of this in the 1992 revision of\nCSTR #54 (§2.3), and more recently, McIlroy referred to it as a “living fossil”.]\n\nFractional type sizes cause one noteworthy incompatibility.  In AT&T troff the ps request ig‐\nnores scaling units and thus “.ps 10u” sets the type size to 10 points, whereas in GNU  troff\nit sets the type size to 10 scaled points, which may be a much smaller measurement.  See sub‐\nsection “Fractional type sizes and new scaling units” above.\n\nThe  ab  request  differs  from AT&T troff: GNU troff writes no message to the standard error\nstream if no arguments are given, and it exits with a failure status instead of a  successful\none.\n\nThe bp request differs from AT&T troff: GNU troff does not accept a scaling unit on the argu‐\nment, a page number; the former (somewhat uselessly) does.\n\nIn  AT&T troff the pm request reports macro, string, and diversion sizes in units of 128-byte\nblocks, and an argument reduces the report to a sum of the above  in  the  same  units.   GNU\ntroff ignores any arguments and reports the sizes in bytes.\n\nUnlike  AT&T  troff, GNU troff does not ignore the ss request if the output is a terminal de‐\nvice; instead, the values of minimum inter-word and additional inter-sentence space are  each\nrounded down to the nearest multiple of 12.\n\nIn  GNU troff there is a fundamental difference between (unformatted) characters and (format‐\nted) glyphs.  Everything that affects how a glyph is output is stored with  the  glyph  node;\nonce  a glyph node has been constructed, it is unaffected by any subsequent requests that are\nexecuted, including bd, cs, tkf, tr, or fp requests.  Normally, glyphs are  constructed  from\ncharacters  immediately before the glyph is added to an output line.  Macros, diversions, and\nstrings are all, in fact, the same type of object; they  contain  a  sequence  of  intermixed\ncharacter  and glyph nodes.  Special characters transform from one to the other: before being\nadded to the output, they behave as characters; afterward, they are  glyphs.   A  glyph  node\ndoes  not  behave  like a character node when it is processed by a macro: it does not inherit\nany of the special properties that the character from which it  was  constructed  might  have\nhad.  For example, the input\n.di x\n\\\\\\\\\n.br\n.di\n.x\nproduces  “\\\\”  in  GNU troff.  Each pair of backslashes becomes one backslash glyph; the re‐\nsulting backslashes are thus not interpreted as escape characters when they are reread as the\ndiversion is output.  AT&T troff would interpret them as  escape  characters  when  rereading\nthem and end up printing one “\\”.\n\nOne  way to format a backslash in most documents is with the \\e escape sequence; this formats\nthe glyph of the current escape character, regardless of whether it is used in  a  diversion;\nit  also  works  in  both GNU troff and AT&T troff.  (Naturally, if you've changed the escape\ncharacter, you need to prefix the “e” with whatever it is—and  you'll  likely  get  something\nother than a backslash in the output.)\n\nThe other correct way, appropriate in contexts independent of the backslash's common use as a\nroff escape character—perhaps in discussion of character sets or other programming languages—\nis  the  character  escape  \\(rs or \\[rs], for “reverse solidus”, from its name in the ECMA-6\n(ISO/IEC 646) standard.  [This escape sequence is not portable to AT&T troff, but is  to  its\nlineal descendant, Heirloom Doctools troff, as of its 060716 release (July 2006).]\n\nTo  store an escape sequence in a diversion that is interpreted when the diversion is reread,\neither use the traditional \\! transparent output facility, or, if this is unsuitable, the new\n\\? escape sequence.  See subsection “Escape sequences” above and  sections  “Diversions”  and\n“gtroff Internals” in Groff: The GNU Implementation of troff, the groff Texinfo manual.\n\nIn  the  somewhat pathological case where a diversion exists containing a partially collected\nline and a partially collected line at the top-level diversion has never existed, AT&T  troff\nwill output the partially collected line at the end of input; GNU troff will not.\n",
            "subsections": [
                {
                    "name": "Formatter output incompatibilities",
                    "content": "Its  extensions notwithstanding, the groff intermediate output format has some incompatibili‐\nties with that of AT&T troff, but better compatibility is sought; problem reports and patches\nare welcome.  The following incompatibilities are known.\n\n• The drawing position after rendering polygons is inconsistent  with  AT&T  troff  practice.\nOther implementations have diverged on this point as well.\n\n• The output cannot be easily rescaled to other devices as AT&T troff's could.\n"
                }
            ]
        },
        "Authors": {
            "content": "This document was written by James Clark, Werner Lemberg, Bernd Warken, and G. Branden Robin‐\nson.\n\nSee also\nGroff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary\ngroff manual.  You can browse it interactively with “info groff”.\n\n“Troff  User's Manual” by Joseph F. Ossanna, 1976 (revised by Brian W. Kernighan, 1992), AT&T\nBell Laboratories Computing Science Technical Report No. 54, widely called simply “CSTR #54”,\ndocuments the language, device and font description file formats, and output format  referred\nto collectively in groff documentation as AT&T troff.\n\n“A  Typesetter-independent TROFF” by Brian W. Kernighan, 1982, AT&T Bell Laboratories Comput‐\ning Science Technical Report No. 97, provides additional insights into the  device  and  font\ndescription file formats and output format.\n\ngroff(1), groff(7), roff(7)\n\ngroff 1.23.0                                31 March 2024                              groffdiff(7)",
            "subsections": []
        }
    },
    "flags": [],
    "examples": [],
    "see_also": []
}