{ "content": [ { "type": "text", "text": "# groff_out (man)\n\n## DESCRIPTION\n\nThe fundamental operation of the \u001b]8;;man:troff(1)\u001b\\troff(1)\u001b]8;;\u001b\\ formatter is the translation of the \u001b]8;;man:groff(7)\u001b\\groff(7)\u001b]8;;\u001b\\ input\nlanguage into a series of instructions concerned primarily with placing glyphs or geometric\nobjects at specific positions on a rectangular page. In the following discussion, the term\ncommand refers to this intermediate output language, never to the \u001b]8;;man:groff(7)\u001b\\groff(7)\u001b]8;;\u001b\\ language intended\nfor use by document authors. Intermediate output commands comprise several categories: glyph\noutput; font, color, and text size selection; motion of the printing position; page advance‐\nment; drawing of geometric primitives; and device control commands, a catch-all for other op‐\nerations. The last includes directives to start and stop output, identify the intended out‐\nput device, and embed URL hyperlinks in supported output formats.\n\n## Sections\n\n- **Name**\n- **Description**\n- **Language concepts** (3 subsections)\n- **Command reference** (5 subsections)\n- **Postprocessing**\n- **Example**\n- **Compatibility**\n- **Files**\n- **Authors**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "groff_out", "section": "", "mode": "man", "summary": null, "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "Name", "lines": 2, "subsections": [] }, { "name": "Description", "lines": 23, "subsections": [] }, { "name": "Language concepts", "lines": 7, "subsections": [ { "name": "Separation", "lines": 30 }, { "name": "Argument units", "lines": 16 }, { "name": "Document parts", "lines": 25 } ] }, { "name": "Command reference", "lines": 3, "subsections": [ { "name": "Comment command", "lines": 5 }, { "name": "Simple commands", "lines": 92 }, { "name": "Graphics commands", "lines": 130 }, { "name": "Device control commands", "lines": 81 }, { "name": "Obsolete command", "lines": 18 } ] }, { "name": "Postprocessing", "lines": 10, "subsections": [] }, { "name": "Example", "lines": 95, "subsections": [] }, { "name": "Compatibility", "lines": 28, "subsections": [] }, { "name": "Files", "lines": 3, "subsections": [] }, { "name": "Authors", "lines": 47, "subsections": [] } ], "sections": { "Name": { "content": "groffout - GNU roff intermediate output format\n", "subsections": [] }, "Description": { "content": "The fundamental operation of the \u001b]8;;man:troff(1)\u001b\\troff(1)\u001b]8;;\u001b\\ formatter is the translation of the \u001b]8;;man:groff(7)\u001b\\groff(7)\u001b]8;;\u001b\\ input\nlanguage into a series of instructions concerned primarily with placing glyphs or geometric\nobjects at specific positions on a rectangular page. In the following discussion, the term\ncommand refers to this intermediate output language, never to the \u001b]8;;man:groff(7)\u001b\\groff(7)\u001b]8;;\u001b\\ language intended\nfor use by document authors. Intermediate output commands comprise several categories: glyph\noutput; font, color, and text size selection; motion of the printing position; page advance‐\nment; drawing of geometric primitives; and device control commands, a catch-all for other op‐\nerations. The last includes directives to start and stop output, identify the intended out‐\nput device, and embed URL hyperlinks in supported output formats.\n\nBecause the front-end command \u001b]8;;man:groff(1)\u001b\\groff(1)\u001b]8;;\u001b\\ is a wrapper that normally runs the troff formatter to\ngenerate intermediate output and an output driver (“postprocessor”) to consume it, users nor‐\nmally do not encounter this language. The groff program's -Z option inhibits postprocessing\nsuch that this intermediate output is sent to the standard output stream as when troff is run\nmanually.\n\ngroff's intermediate output facilitates the development of output drivers and other post‐\nprocessors by offering a common programming interface. It is an extension of the page de‐\nscription language developed by Brian Kernighan for AT&T device-independent troff circa 1980.\nWhere a distinction is necessary, we will say “troff output” to describe the output of GNU\ntroff, and “intermediate output” to denote the language accepted by the parser implemented in\ngroff's internal C++ library used by most of its output drivers.\n", "subsections": [] }, "Language concepts": { "content": "During the run of troff, the roff input is cracked down to the information on what has to be\nprinted at what position on the intended device. So the language of the intermediate output\nformat can be quite small. Its only elements are commands with or without arguments. In\nthis document, the term “command” always refers to the intermediate output language, never to\nthe roff language used for document formatting. There are commands for positioning and text\nwriting, for drawing, and for device controlling.\n", "subsections": [ { "name": "Separation", "content": "Classical troff output had strange requirements on whitespace. The groff output parser, how‐\never, is smart about whitespace by making it maximally optional. The whitespace characters,\ni.e., the tab, space, and newline characters, always have a syntactical meaning. They are\nnever printable because spacing within the output is always done by positioning commands.\n\nAny sequence of space or tab characters is treated as a single syntactical space. It sepa‐\nrates commands and arguments, but is only required when there would occur a clashing between\nthe command code and the arguments without the space. Most often, this happens when variable\nlength command names, arguments, argument lists, or command clusters meet. Commands and ar‐\nguments with a known, fixed length need not be separated by syntactical space.\n\nA line break is a syntactical element, too. Every command argument can be followed by white‐\nspace, a comment, or a newline character. Thus a syntactical line break is defined to con‐\nsist of optional syntactical space that is optionally followed by a comment, and a newline\ncharacter.\n\nThe normal commands, those for positioning and text, consist of a single letter taking a\nfixed number of arguments. For historical reasons, the parser allows stacking of such com‐\nmands on the same line, but fortunately, in groff intermediate output, every command with at\nleast one argument is followed by a line break, thus providing excellent readability.\n\nThe other commands — those for drawing and device controlling — have a more complicated\nstructure; some recognize long command names, and some take a variable number of arguments.\nSo all D and x commands were designed to request a syntactical line break after their last\nargument. Only one command, ‘x X’ has an argument that can stretch over several lines, all\nother commands must have all of their arguments on the same line as the command, i.e., the\narguments may not be split by a line break.\n\nLines containing only spaces and/or a comment are treated as empty and ignored.\n" }, { "name": "Argument units", "content": "Some commands accept integer arguments that represent measurements, but the scaling units of\nthe formatter's language are never used. Most commands assume a scaling unit of “u” (basic\nunits), and others use “z” (scaled points); These are defined by the parameters specified in\nthe device's DESC file; see \u001b]8;;man:grofffont(5)\u001b\\grofffont(5)\u001b]8;;\u001b\\ and, for more on scaling units, \u001b]8;;man:groff(7)\u001b\\groff(7)\u001b]8;;\u001b\\ and Groff:\nThe GNU Implementation of troff, the groff Texinfo manual. Color-related commands use dimen‐\nsionless integers.\n\nNote that single characters can have the eighth bit set, as can the names of fonts and spe‐\ncial characters (this is, glyphs). The names of glyphs and fonts can be of arbitrary length.\nA glyph that is to be printed will always be in the current font.\n\nA string argument is always terminated by the next whitespace character (space, tab, or new‐\nline); an embedded # character is regarded as part of the argument, not as the beginning of a\ncomment command. An integer argument is already terminated by the next non-digit character,\nwhich then is regarded as the first character of the next argument or command.\n" }, { "name": "Document parts", "content": "A correct intermediate output document consists of two parts, the prologue and the body.\n\nThe task of the prologue is to set the general device parameters using three exactly speci‐\nfied commands. The groff prologue is guaranteed to consist of the following three lines (in\nthat order):\n\nx T device\nx res n h v\nx init\n\nwith the arguments set as outlined in subsection “Device Control Commands” below. However,\nthe parser for the intermediate output format is able to swallow additional whitespace and\ncomments as well.\n\nThe body is the main section for processing the document data. Syntactically, it is a se‐\nquence of any commands different from the ones used in the prologue. Processing is termi‐\nnated as soon as the first x stop command is encountered; the last line of any groff interme‐\ndiate output always contains such a command.\n\nSemantically, the body is page oriented. A new page is started by a p command. Positioning,\nwriting, and drawing commands are always done within the current page, so they cannot occur\nbefore the first p command. Absolute positioning (by the H and V commands) is done relative\nto the current page, all other positioning is done relative to the current location within\nthis page.\n" } ] }, "Command reference": { "content": "This section describes all intermediate output commands, the classical commands as well as\nthe groff extensions.\n", "subsections": [ { "name": "Comment command", "content": "#anything⟨line-break⟩\nA comment. Ignore any characters from the # character up to the next newline. Each\ncomment can be preceded by arbitrary syntactical space; every command can be termi‐\nnated by a comment.\n" }, { "name": "Simple commands", "content": "The commands in this subsection have a command code consisting of a single character, taking\na fixed number of arguments. Most of them are commands for positioning and text writing.\nThese commands are smart about whitespace. Optionally, syntactical space can be inserted be‐\nfore, after, and between the command letter and its arguments. All of these commands are\nstackable, i.e., they can be preceded by other simple commands or followed by arbitrary other\ncommands on the same line. A separating syntactical space is necessary only when two integer\narguments would clash or if the preceding argument ends with a string argument.\n\nC id⟨white-space⟩\nTypeset the glyph of the special character id. Trailing syntactical space is neces‐\nsary to allow special character names of arbitrary length. The drawing position is\nnot advanced.\n\nc c Typeset the glyph of the ordinary character character c. The drawing position is not\nadvanced.\n\nf n Select the font mounted at position n. n cannot be negative.\n\nH n Horizontally move the drawing position to n basic units from the left edge of the\npage. n cannot be negative.\n\nh n Move the drawing position right n basic units. AT&T troff allowed negative n; GNU\ntroff does not produce such values, but groff's output driver library handles them.\n\nm scheme [component ...]\nSelect the stroke color using the components in the color space scheme. Each compo‐\nnent is an integer between 0 and 65536. The quantity of components and their meanings\nvary with each scheme. This command is a groff extension.\n\nmc cyan magenta yellow\nUse the CMY color scheme with components cyan, magenta, and yellow.\n\nmd Use the default color (no components; black in most cases).\n\nmg gray\nUse a grayscale color scheme with a component ranging between 0 (black) and\n65536 (white).\n\nmk cyan magenta yellow black\nUse the CMYK color scheme with components cyan, magenta, yellow, and black.\n\nmr red green blue\nUse the RGB color scheme with components red, green, and blue.\n\nN n Typeset the glyph with index n in the current font. n is normally a non-negative in‐\nteger. The drawing position is not advanced. The html and xhtml devices use this\ncommand with negative n to produce unbreakable space; the absolute value of n is taken\nand interpreted in basic units.\n\nn b a Indicate a break. No action is performed; the command is present to make the output\nmore easily parsed. The integers b and a describe the vertical space amounts before\nand after the break, respectively. GNU troff issues this command but groff's output\ndriver library ignores it. See v and V.\n\np n Begin a new page, setting its number to n. Each page is independent, even from those\nusing the same number. The vertical drawing position is set to 0. All positioning,\nwriting, and drawing commands are interpreted in the context of a page, so a p command\nmust precede them.\n\ns n Set type size to n scaled points (unit z in GNU troff). AT&T troff used unscaled\npoints (p) instead; see section “Compatibility” below.\n\nt xyz...⟨white-space⟩\nt xyz... dummy-arg⟨white-space⟩\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. The t command is\na groff extension and is output only for devices whose DESC file contains the tcommand\ndirective; see \u001b]8;;man:grofffont(5)\u001b\\grofffont(5)\u001b]8;;\u001b\\.\n\nu n xyz...\nu xyz... dummy-arg⟨white-space⟩\nTypeset word xyz with track kerning. As t, but after placing each glyph, the drawing\nposition is further advanced horizontally by n basic units. The u command is a groff\nextension and is output only for devices whose DESC file contains the tcommand direc‐\ntive; see \u001b]8;;man:grofffont(5)\u001b\\grofffont(5)\u001b]8;;\u001b\\.\n\nV n Vertically move the drawing position to n basic units from the top edge of the page.\nn cannot be negative.\n\nv n Move the drawing position down n basic units. AT&T troff allowed negative n; GNU\ntroff does not produce such values, but groff's output driver library handles them.\n\nw Indicate an inter-word space. No action is performed; the command is present to make\nthe output more easily parsed. Only adjustable, breakable inter-word spaces are thus\ndescribed; those resulting from \\~ or horizontal motion escape sequences are not. GNU\ntroff issues this command but groff's output driver library ignores it. See h and H.\n" }, { "name": "Graphics commands", "content": "Each graphics or drawing command in the intermediate output starts with the letter D followed\nby one or two characters that specify a subcommand; this is followed by a fixed or variable\nnumber of integer arguments that are separated by a single space character. A D command may\nnot be followed by another command on the same line (apart from a comment), so each D command\nis terminated by a syntactical line break.\n\ntroff output follows the classical spacing rules (no space between command and subcommand,\nall arguments are preceded by a single space character), but the parser allows optional space\nbetween the command letters and makes the space before the first argument optional. As\nusual, each space can be any sequence of tab and space characters.\n\nSome graphics commands can take a variable number of arguments. In this case, they are inte‐\ngers representing a size measured in basic units u. The h arguments stand for horizontal\ndistances where positive means right, negative left. The v arguments stand for vertical dis‐\ntances where positive means down, negative up. All these distances are offsets relative to\nthe current location.\n\nUnless indicated otherwise, each graphics command directly corresponds to a similar groff \\D\nescape sequence; see \u001b]8;;man:groff(7)\u001b\\groff(7)\u001b]8;;\u001b\\.\n\nUnknown D commands are assumed to be device-specific. Its arguments are parsed as strings;\nthe whole information is then sent to the postprocessor.\n\nIn the following command reference, the syntax element ⟨line-break⟩ means a syntactical line\nbreak as defined in subsection “Separation” above.\n\nD~ h1 v1 h2 v2 ... hn vn⟨line-break⟩\nDraw B-spline from current position to offset (h1, v1), then to offset (h2, v2) if\ngiven, etc., up to (hn, vn). This command takes a variable number of argument pairs;\nthe current position is moved to the terminal point of the drawn curve.\n\nDa h1 v1 h2 v2⟨line-break⟩\nDraw arc from current position to (h1, v1)+(h2, v2) with center at (h1, v1); then move\nthe current position to the final point of the arc.\n\nDC d⟨line-break⟩\nDC d dummy-arg⟨line-break⟩\nDraw a solid circle using the current fill color with diameter d (integer in basic\nunits u) with leftmost point at the current position; then move the current position\nto the rightmost point of the circle. An optional second integer argument is ignored\n(this allows the formatter to generate an even number of arguments). This command is\na groff extension.\n\nDc d⟨line-break⟩\nDraw circle line with diameter d (integer in basic units u) with leftmost point at the\ncurrent position; then move the current position to the rightmost point of the circle.\n\nDE h v⟨line-break⟩\nDraw a solid ellipse in the current fill color with a horizontal diameter of h and a\nvertical diameter of v (both integers in basic units u) with the leftmost point at the\ncurrent position; then move to the rightmost point of the ellipse. This command is a\ngroff extension.\n\nDe h v⟨line-break⟩\nDraw an outlined ellipse with a horizontal diameter of h and a vertical diameter of v\n(both integers in basic units u) with the leftmost point at current position; then\nmove to the rightmost point of the ellipse.\n\nDF color-scheme [component ...]⟨line-break⟩\nSet fill color for solid drawing objects using different color schemes; the analogous\ncommand for setting the color of text, line graphics, and the outline of graphic ob‐\njects is m. The color components are specified as integer arguments between 0 and\n65536. The number of color components and their meaning vary for the different color\nschemes. These commands are generated by the groff escape sequences \\D'F ...' and \\M\n(with no other corresponding graphics commands). This command is a groff extension.\n\nDFc cyan magenta yellow⟨line-break⟩\nSet fill color for solid drawing objects using the CMY color scheme, having the\n3 color components cyan, magenta, and yellow.\n\nDFd ⟨line-break⟩\nSet fill color for solid drawing objects to the default fill color value (black\nin most cases). No component arguments.\n\nDFg gray⟨line-break⟩\nSet fill color for solid drawing objects to the shade of gray given by the ar‐\ngument, an integer between 0 (black) and 65536 (white).\n\nDFk cyan magenta yellow black⟨line-break⟩\nSet fill color for solid drawing objects using the CMYK color scheme, having\nthe 4 color components cyan, magenta, yellow, and black.\n\nDFr red green blue⟨line-break⟩\nSet fill color for solid drawing objects using the RGB color scheme, having the\n3 color components red, green, and blue.\n\nDf n⟨line-break⟩\nThe argument n must be an integer in the range -32767 to 32767.\n\n0≤n≤1000\nSet the color for filling solid drawing objects to a shade of gray, where 0\ncorresponds to solid white, 1000 (the default) to solid black, and values in\nbetween to intermediate shades of gray; this is obsoleted by command DFg.\n\nn<0 or n>1000\nSet the filling color to the color that is currently being used for the text\nand the outline, see command m. For example, the command sequence\n\nmg 0 0 65536\nDf -1\n\nsets all colors to blue.\n\nThis command is a groff extension.\n\nDl h v⟨line-break⟩\nDraw line from current position to offset (h, v) (integers in basic units u); then set\ncurrent position to the end of the drawn line.\n\nDp h1 v1 h2 v2 ... hn vn⟨line-break⟩\nDraw a polygon line from current position to offset (h1, v1), from there to offset\n(h2, v2), etc., up to offset (hn, vn), and from there back to the starting position.\nFor historical reasons, the position is changed by adding the sum of all arguments\nwith odd index to the current horizontal position and the even ones to the vertical\nposition. Although this doesn't make sense it is kept for compatibility. This com‐\nmand is a groff extension.\n\nDP h1 v1 h2 v2 ... hn vn⟨line-break⟩\nThe same macro as the corresponding Dp command with the same arguments, but draws a\nsolid polygon in the current fill color rather than an outlined polygon. The position\nis changed in the same way as with Dp. This command is a groff extension.\n\nDt n⟨line-break⟩\nSet the current line thickness to n (an integer in basic units u) if n>0; if n=0 se‐\nlect the smallest available line thickness; otherwise, the line thickness is made pro‐\nportional to the type size, which is the default. For historical reasons, the hori‐\nzontal position is changed by adding the argument to the current horizontal position,\nwhile the vertical position is not changed. Although this doesn't make sense, it is\nkept for compatibility. This command is a groff extension.\n" }, { "name": "Device control commands", "content": "Each device control command starts with the letter x followed by a space character (optional\nor arbitrary space/tab in groff) and a subcommand letter or word; each argument (if any) must\nbe preceded by a syntactical space. All x commands are terminated by a syntactical line\nbreak; no device control command can be followed by another command on the same line (except\na comment).\n\nThe subcommand is basically a single letter, but to increase readability, it can be written\nas a word, i.e., an arbitrary sequence of characters terminated by the next tab, space, or\nnewline character. All characters of the subcommand word but the first are simply ignored.\nFor example, troff outputs the initialization command x i as x init and the resolution com‐\nmand x r as x res. But writings like x ilikegroff and x roffisgroff are accepted as well\nto mean the same commands.\n\nIn the following, the syntax element ⟨line-break⟩ means a syntactical line break as defined\nin subsection “Separation” above.\n\nxF name⟨line-break⟩\n(Filename control command)\nUse name as the intended name for the current file in error reports. This is useful\nfor remembering the original file name when groff uses an internal piping mechanism.\nThe input file is not changed by this command. This command is a groff extension.\n\nxf n s⟨line-break⟩\n(font control command)\nMount font position n (a non-negative integer) with font named s (a text word); see\n\u001b]8;;man:grofffont(5)\u001b\\grofffont(5)\u001b]8;;\u001b\\.\n\nxH n⟨line-break⟩\n(Height control command)\nSet character height to n (a positive integer in scaled points z). Classical troff\nused the unit points (p) instead; see section “Compatibility” below.\n\nxi ⟨line-break⟩\n(init control command)\nInitialize device. This is the third command of the prologue.\n\nxp ⟨line-break⟩\n(pause control command)\nParsed but ignored. The classical documentation reads pause device, can be restarted.\n\nxr n h v⟨line-break⟩\n(resolution control command)\nResolution is n, while h is the minimal horizontal motion, and v the minimal vertical\nmotion possible with this device; all arguments are positive integers in basic units u\nper inch. This is the second command of the prologue.\n\nxS n⟨line-break⟩\n(Slant control command)\nSet slant to n degrees (an integer in basic units u).\n\nxs ⟨line-break⟩\n(stop control command)\nTerminates the processing of the current file; issued as the last command of any in‐\ntermediate troff output.\n\nxt ⟨line-break⟩\n(trailer control command)\nGenerate trailer information, if any. In groff, this is currently ignored.\n\nxT xxx⟨line-break⟩\n(Typesetter control command)\nSet the name of the output driver to xxx, a sequence of non-whitespace characters ter‐\nminated by whitespace. The possible names correspond to those of groff's -T option.\nThis is the first command of the prologue.\n\nxu n⟨line-break⟩\n(underline control command)\nConfigure underlining of spaces. If n is 1, start underlining of spaces; if n is 0,\nstop underlining of spaces. This is needed for the cu request in nroff mode and is\nignored otherwise. This command is a groff extension.\n\nxX anything⟨line-break⟩\n(X-escape control command)\nSend string anything uninterpreted to the device. If the line following this command\nstarts with a + character this line is interpreted as a continuation line in the fol‐\nlowing sense. The + is ignored, but a newline character is sent instead to the de‐\nvice, the rest of the line is sent uninterpreted. The same applies to all following\nlines until the first character of a line is not a + character. This command is gen‐\nerated by the groff escape sequence \\X. The line-continuing feature is a groff exten‐\nsion.\n" }, { "name": "Obsolete command", "content": "In classical troff output, emitting a single glyph was mostly done by a very strange command\nthat combined a horizontal move and the printing of a glyph. It didn't have a command code,\nbut is represented by a 3-character argument consisting of exactly 2 digits and a character.\n\nddc Move right dd (exactly two decimal digits) basic units u, then print glyph with sin‐\ngle-letter name c.\n\nIn groff, arbitrary syntactical space around and within this command is allowed to be\nadded. Only when a preceding command on the same line ends with an argument of vari‐\nable length a separating space is obligatory. In classical troff, large clusters of\nthese and other commands were used, mostly without spaces; this made such output al‐\nmost unreadable.\n\nFor modern high-resolution devices, this command does not make sense because the width of the\nglyphs can become much larger than two decimal digits. In groff, it is used only for output\nto the X75, X75-12, X100, and X100-12 devices. For others, the commands t and u provide\ngreater functionality and superior troubleshooting capacity.\n" } ] }, "Postprocessing": { "content": "The roff postprocessors are programs that have the task to translate the intermediate output\ninto actions that are sent to a device. A device can be some piece of hardware such as a\nprinter, or a software file format suitable for graphical or text processing. The groff sys‐\ntem provides powerful means that make the programming of such postprocessors an easy task.\n\nThere is a library function that parses the intermediate output and sends the information ob‐\ntained to the device via methods of a class with a common interface for each device. So a\ngroff postprocessor must only redefine the methods of this class. For details, see the ref‐\nerence in section “Files” below.\n", "subsections": [] }, "Example": { "content": "This section presents the intermediate output generated from the same input for three differ‐\nent devices. The input is the sentence hell world fed into groff on the command line.\n\n• High-resolution device ps\n\nshell> echo \"hell world\" | groff -Z -T ps\n\nx T ps\nx res 72000 1 1\nx init\np1\nx font 5 TR\nf5\ns10000\nV12000\nH72000\nthell\nwh2500\ntw\nH96620\ntorld\nn12000 0\nx trailer\nV792000\nx stop\n\nThis output can be fed into the postprocessor \u001b]8;;man:grops(1)\u001b\\grops(1)\u001b]8;;\u001b\\ to get its representation as a Post‐\nScript file, or \u001b]8;;man:gropdf(1)\u001b\\gropdf(1)\u001b]8;;\u001b\\ to output directly to PDF.\n\n• Low-resolution device latin1\n\nThis is similar to the high-resolution device except that the positioning is done at a mi‐\nnor scale. Some comments (lines starting with #) were added for clarification; they were\nnot generated by the formatter.\n\nshell> \"hell world\" | groff -Z -T latin1\n\n# prologue\nx T latin1\nx res 240 24 40\nx init\n# begin a new page\np1\n# font setup\nx font 1 R\nf1\ns10\n# initial positioning on the page\nV40\nH0\n# write text 'hell'\nthell\n# inform about a space, and do it by a horizontal jump\nwh24\n# write text 'world'\ntworld\n# announce line break, but do nothing because ...\nn40 0\n# ... the end of the document has been reached\nx trailer\nV2640\nx stop\n\nThis output can be fed into the postprocessor \u001b]8;;man:grotty(1)\u001b\\grotty(1)\u001b]8;;\u001b\\ to get a formatted text document.\n\n• Classical style output\n\nAs a computer monitor has a very low resolution compared to modern printers the intermedi‐\nate output for the X devices can use the jump-and-write command with its 2-digit displace‐\nments.\n\nshell> \"hell world\" | groff -Z -T X100\n\nx T X100\nx res 100 1 1\nx init\np1\nx font 5 TR\nf5\ns10\nV16\nH100\n# write text with old-style jump-and-write command\nch07e07l03lw06w11o07r05l03dh7\nn16 0\nx trailer\nV1100\nx stop\n\nThis output can be fed into the postprocessor \u001b]8;;man:xditview(1x)\u001b\\xditview(1x)\u001b]8;;\u001b\\ or \u001b]8;;man:gxditview(1)\u001b\\gxditview(1)\u001b]8;;\u001b\\ for displaying\nin X.\n\nDue to the obsolete jump-and-write command, the text clusters in the classical output are al‐\nmost unreadable.\n", "subsections": [] }, "Compatibility": { "content": "The intermediate output language of the classical troff was first documented in [CSTR #97].\nThe groff intermediate output format is compatible with this specification except for the\nfollowing features.\n\n• The classical quasi device independence is not yet implemented.\n\n• The old hardware was very different from what we use today. So the groff devices are also\nfundamentally different from the ones in classical troff. For example, the classical Post‐\nScript device was called post and had a resolution of 720 units per inch, while groff's ps\ndevice has a resolution of 72000 units per inch. Maybe, by implementing some rescaling\nmechanism similar to the classical quasi device independence, these could be integrated\ninto modern groff.\n\n• The B-spline command D~ is correctly handled by the intermediate output parser, but the\ndrawing routines aren't implemented in some of the postprocessor programs.\n\n• The argument of the commands s and x H has the implicit unit scaled point z in groff, while\nclassical troff had point (p). This isn't an incompatibility, but a compatible extension,\nfor both units coincide for all devices without a sizescale parameter, including all clas‐\nsical and the groff text devices. The few groff devices with a sizescale parameter either\ndid not exist, had a different name, or seem to have had a different resolution. So con‐\nflicts with classical devices are very unlikely.\n\n• The position changing after the commands Dp, DP, and Dt is illogical, but as old versions\nof groff used this feature it is kept for compatibility reasons.\n\nThe differences between groff and classical troff are documented in \u001b]8;;man:groffdiff(7)\u001b\\groffdiff(7)\u001b]8;;\u001b\\.\n", "subsections": [] }, "Files": { "content": "/usr/share/groff/1.23.0/font/devname/DESC\ndescribes the output device name.\n", "subsections": [] }, "Authors": { "content": "James Clark wrote an early version of this document, which described only the differences be‐\ntween AT&T device-independent troff's output format and that of GNU roff. The present ver‐\nsion was completely rewritten in 2001 by \u001b]8;;mailto:groff-bernd.warken-72@web.de\u001b\\Bernd Warken\u001b]8;;\u001b\\.\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 device-independent out‐\nput format referred to 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 device-independent output format.\n\n\u001b]8;;man:groff(1)\u001b\\groff(1)\u001b]8;;\u001b\\\ndocuments the -Z option and contains pointers to further groff documentation.\n\n\u001b]8;;man:groff(7)\u001b\\groff(7)\u001b]8;;\u001b\\\ndescribes the groff language, including its escape sequences and system of units.\n\n\u001b]8;;man:grofffont(5)\u001b\\grofffont(5)\u001b]8;;\u001b\\\ndetails the device scaling parameters of device DESC files.\n\n\u001b]8;;man:troff(1)\u001b\\troff(1)\u001b]8;;\u001b\\\ngenerates the device-independent intermediate output documented here.\n\n\u001b]8;;man:roff(7)\u001b\\roff(7)\u001b]8;;\u001b\\\npresents historical aspects and the general structure of roff systems.\n\n\u001b]8;;man:groffdiff(7)\u001b\\groffdiff(7)\u001b]8;;\u001b\\\nenumerates differences between the intermediate output produced by AT&T troff and that\nof groff.\n\n\u001b]8;;man:gxditview(1)\u001b\\gxditview(1)\u001b]8;;\u001b\\\nis a viewer for intermediate output.\n\nRoff.js\n⟨https://github.com/Alhadis/Roff.js/⟩ is a viewer for intermediate output written in\nJavaScript.\n\n\u001b]8;;man:grodvi(1)\u001b\\grodvi(1)\u001b]8;;\u001b\\, \u001b]8;;man:grohtml(1)\u001b\\grohtml(1)\u001b]8;;\u001b\\, \u001b]8;;man:grolbp(1)\u001b\\grolbp(1)\u001b]8;;\u001b\\, \u001b]8;;man:grolj4(1)\u001b\\grolj4(1)\u001b]8;;\u001b\\, \u001b]8;;man:gropdf(1)\u001b\\gropdf(1)\u001b]8;;\u001b\\, \u001b]8;;man:grops(1)\u001b\\grops(1)\u001b]8;;\u001b\\, and \u001b]8;;man:grotty(1)\u001b\\grotty(1)\u001b]8;;\u001b\\ are groff\npostprocessors.\n\ngroff 1.23.0 31 March 2024 groffout(5)", "subsections": [] } } } }