{ "content": [ { "type": "text", "text": "# GROFF_OUT (man)\n\n## NAME\n\ngroffout - groff intermediate output format\n\n## DESCRIPTION\n\nThis manual page describes the intermediate output format of the GNU roff(7) text processing\nsystem groff(1). This output is produced by a run of the GNU troff(1) program. It contains\nalready all device-specific information, but it is not yet fed into a device postprocessor\nprogram.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **LANGUAGE CONCEPTS** (3 subsections)\n- **COMMAND REFERENCE** (5 subsections)\n- **POSTPROCESSING**\n- **EXAMPLES**\n- **COMPATIBILITY**\n- **FILES**\n- **AUTHORS**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "GROFF_OUT", "section": "", "mode": "man", "summary": "groffout - groff intermediate output format", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [ "This section presents the intermediate output generated from the same input for three differ‐", "ent devices. The input is the sentence hell world fed into groff on the command line.", "• High-resolution device ps", "shell> echo \"hell world\" | groff -Z -T ps", "x T ps", "x res 72000 1 1", "x init", "p1", "x font 5 TR", "f5", "s10000", "V12000", "H72000", "thell", "wh2500", "tw", "H96620", "torld", "n12000 0", "x trailer", "V792000", "x stop", "This output can be fed into the postprocessor grops(1) to get its representation as a Post‐", "Script file, or gropdf(1) to output directly to PDF.", "• Low-resolution device latin1", "This is similar to the high-resolution device except that the positioning is done at a mi‐", "nor scale. Some comments (lines starting with #) were added for clarification; they were", "not generated by the formatter.", "shell> \"hell world\" | groff -Z -T latin1", "# prologue", "x T latin1", "x res 240 24 40", "x init", "# begin a new page", "p1", "# font setup", "x font 1 R", "f1", "s10", "# initial positioning on the page", "V40", "H0", "# write text ‘hell’", "thell", "# inform about a space, and do it by a horizontal jump", "wh24", "# write text ‘world’", "tworld", "# announce line break, but do nothing because ...", "n40 0", "# ... the end of the document has been reached", "x trailer", "V2640", "x stop", "This output can be fed into the postprocessor grotty(1) to get a formatted text document.", "• Classical style output", "As a computer monitor has a very low resolution compared to modern printers the intermedi‐", "ate output for the X devices can use the jump-and-write command with its 2-digit displace‐", "ments.", "shell> \"hell world\" | groff -Z -T X100", "x T X100", "x res 100 1 1", "x init", "p1", "x font 5 TR", "f5", "s10", "V16", "H100", "# write text with old-style jump-and-write command", "ch07e07l03lw06w11o07r05l03dh7", "n16 0", "x trailer", "V1100", "x stop", "This output can be fed into the postprocessor xditview(1x) or gxditview(1) for displaying", "in X.", "Due to the obsolete jump-and-write command, the text clusters in the classical output are al‐", "most unreadable." ], "see_also": [ { "name": "groff", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/groff/7/json" }, { "name": "man", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/man/1/json" }, { "name": "groff", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/groff/1/json" }, { "name": "groff", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/groff/7/json" }, { "name": "grofffont", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/grofffont/5/json" }, { "name": "troff", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/troff/1/json" }, { "name": "roff", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/roff/7/json" }, { "name": "groffdiff", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/groffdiff/7/json" }, { "name": "gxditview", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/gxditview/1/json" }, { "name": "grodvi", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/grodvi/1/json" }, { "name": "grohtml", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/grohtml/1/json" }, { "name": "grolbp", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/grolbp/1/json" }, { "name": "grolj4", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/grolj4/1/json" }, { "name": "grops", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/grops/1/json" }, { "name": "grotty", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/grotty/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 28, "subsections": [] }, { "name": "LANGUAGE CONCEPTS", "lines": 7, "subsections": [ { "name": "Separation", "lines": 31 }, { "name": "Argument Units", "lines": 18 }, { "name": "Document Parts", "lines": 25 } ] }, { "name": "COMMAND REFERENCE", "lines": 3, "subsections": [ { "name": "Comment Command", "lines": 7 }, { "name": "Simple Commands", "lines": 102 }, { "name": "Graphics Commands", "lines": 132 }, { "name": "Device Control Commands", "lines": 81 }, { "name": "Obsolete Command", "lines": 18 } ] }, { "name": "POSTPROCESSING", "lines": 10, "subsections": [] }, { "name": "EXAMPLES", "lines": 95, "subsections": [] }, { "name": "COMPATIBILITY", "lines": 28, "subsections": [] }, { "name": "FILES", "lines": 8, "subsections": [] }, { "name": "AUTHORS", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 51, "subsections": [] } ], "sections": { "NAME": { "content": "groffout - groff intermediate output format\n", "subsections": [] }, "DESCRIPTION": { "content": "This manual page describes the intermediate output format of the GNU roff(7) text processing\nsystem groff(1). This output is produced by a run of the GNU troff(1) program. It contains\nalready all device-specific information, but it is not yet fed into a device postprocessor\nprogram.\n\nAs the GNU roff processor groff(1) is a wrapper program around troff that automatically calls\na postprocessor, this output does not show up normally. This is why it is called intermedi‐\nate within the groff system. The groff program provides the option -Z to inhibit postpro‐\ncessing, such that the produced intermediate output is sent to standard output just like\ncalling troff manually.\n\nIn this document, the term troff output describes what is output by the GNU troff program,\nwhile intermediate output refers to the language that is accepted by the parser that prepares\nthis output for the postprocessors. This parser is smarter on whitespace and implements ob‐\nsolete elements for compatibility, otherwise both formats are the same. Both formats can be\nviewed directly with gxditview(1).\n\nThe main purpose of the intermediate output concept is to facilitate the development of post‐\nprocessors by providing a common programming interface for all devices. It has a language of\nits own that is completely different from the groff(7) language. While the groff language is\na high-level programming language for text processing, the intermediate output language is a\nkind of low-level assembler language by specifying all positions on the page for writing and\ndrawing.\n\nThe pre-groff roff versions are denoted as classical troff. The intermediate output produced\nby groff is fairly readable, while classical troff output was hard to understand because of\nstrange habits that are still supported, but not used any longer by GNU troff.\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\nEmpty lines, i.e., lines containing only space and/or a comment, can occur everywhere. They\nare just ignored.\n" }, { "name": "Argument Units", "content": "Some commands take integer arguments that are assumed to represent values in a measurement\nunit, but the letter for the corresponding scale indicator is not written with the output\ncommand arguments; see groff(7) and Groff: The GNU Implementation of troff, the groff Texinfo\nmanual, for more on this topic. Most commands assume the scale indicator u, the basic unit\nof the device, some use z, the scaled point unit of the device, while others, such as the\ncolor commands expect plain integers. Note that these scale indicators are relative to the\nchosen device. They are defined by the parameters specified in the device's DESC file; see\ngrofffont(5).\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⟨⟨end-of-line⟩⟩\nA comment. Ignore any characters from the # character up to the next newline charac‐\nter.\n\nThis command is the only possibility for commenting in the intermediate output. Each comment\ncan be preceded by arbitrary syntactical space; every command can be terminated 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 only necessary when two integer\narguments would clash or if the preceding argument ends with a string argument.\n\nC xxx⟨white-space⟩\nPrint a glyph (special character) named xxx. The trailing syntactical space or line\nbreak is necessary to allow glyph names of arbitrary length. The glyph is printed at\nthe current print position; the glyph's size is read from the font file. The print\nposition is not changed.\n\nc c Print glyph with single-letter name c at the current print position; the glyph's size\nis read from the font file. The print position is not changed.\n\nf n Set font to font number n (a non-negative integer).\n\nH n Move right to the absolute vertical position n (a non-negative integer in basic\nunits u) relative to left edge of current page.\n\nh n Move n (a non-negative integer) basic units u horizontally to the right. [CSTR #54]\nallows negative values for n also, but groff doesn't use this.\n\nm color-scheme [component ...]\nSet the color for text (glyphs), line drawing, and the outline of graphic objects us‐\ning different color schemes; the analogous command for the filling color of graphic\nobjects is DF. 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 sequence \\m. No position\nchanging. These commands are a groff extension.\n\nmc cyan magenta yellow\nSet color using the CMY color scheme, having the 3 color components cyan, ma‐\ngenta, and yellow.\n\nmd Set color to the default color value (black in most cases). No component argu‐\nments.\n\nmg gray\nSet color to the shade of gray given by the argument, an integer between 0\n(black) and 65536 (white).\n\nmk cyan magenta yellow black\nSet color using the CMYK color scheme, having the 4 color components cyan, ma‐\ngenta, yellow, and black.\n\nmr red green blue\nSet color using the RGB color scheme, having the 3 color components red, green,\nand blue.\n\nN n Print glyph with index n (an integer, normally non-negative) of the current font. The\nprint position is not changed. If -T html or -T xhtml is used, negative values are\nemitted also to indicate an unbreakable space with given width. For example, N -193\nrepresents an unbreakable space which has a width of 193u. This command is a groff\nextension.\n\nn b a Inform the device about a line break, but no positioning is done by this command. In\nclassical troff, the integer arguments b and a informed about the space before and af‐\nter the current line to make the intermediate output more human readable without per‐\nforming any action. In groff, they are just ignored, but they must be provided for\ncompatibility reasons.\n\np n Begin a new page in the outprint. The page number is set to n. This page is com‐\npletely independent of pages formerly processed even if those have the same page num‐\nber. The vertical position on the outprint is automatically set to 0. All position‐\ning, writing, and drawing is always done relative to a page, so a p command must be\nissued before any of these commands.\n\ns n Set point size to n scaled points (this is unit z in GNU troff). Classical troff used\nthe unit points (p) instead; see section “Compatibility” below.\n\nt xyz...⟨white-space⟩\nt xyz... dummy-arg⟨white-space⟩\nPrint a word, i.e., a sequence of glyphs with single-letter names x, y, z, etc., ter‐\nminated by a space character or a line break; an optional second integer argument is\nignored (this allows the formatter to generate an even number of arguments). The\nfirst glyph should be printed at the current position, the current horizontal position\nshould then be increased by the width of the first glyph, and so on for each glyph.\nThe widths of the glyph are read from the font file, scaled for the current point\nsize, and rounded to a multiple of the horizontal resolution. Special characters\n(glyphs with names longer than a single letter) cannot be printed using this command;\nuse the C command for those glyphs. This command is a groff extension; it is only\nused for devices whose DESC file contains the tcommand keyword; see grofffont(5).\n\nu n xyz...⟨white-space⟩\nPrint word with track kerning. This is the same as the t command except that after\nprinting each glyph, the current horizontal position is increased by the sum of the\nwidth of that glyph and n (an integer in basic units u). This command is a groff ex‐\ntension; it is only used for devices whose DESC file contains the tcommand keyword;\nsee grofffont(5).\n\nV n Move down to the absolute vertical position n (a non-negative integer in basic\nunits u) relative to upper edge of current page.\n\nv n Move n basic units u down (n is a non-negative integer). [CSTR #54] allows negative\nvalues for n also, but groff doesn't use this.\n\nw Informs about a paddable whitespace to increase readability. The spacing itself must\nbe performed explicitly by a move command.\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 groff(7).\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). No position changing. This command\nis 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\nNo position changing. This 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 actual horizontal position and the even ones to the vertical po‐\nsition. Although this doesn't make sense it is kept for compatibility. This command\nis 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; if n<0 set the line thickness proportional\nto the point size (this is the default before the first Dt command was specified).\nFor historical reasons, the horizontal position is changed by adding the argument to\nthe actual horizontal position, while the vertical position is not changed. Although\nthis doesn't make sense it is kept for compatibility. This command is a groff exten‐\nsion.\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\ngrofffont(5).\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 actually just ignored.\n\nxT xxx⟨line-break⟩\n(Typesetter control command)\nSet name of device to word xxx, a sequence of characters ended by the next whitespace\ncharacter. The possible device names coincide with those from the groff -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, this is only used for the\ndevices X75, X75-12, X100, and X100-12. For other devices, the commands t and u provide a\nbetter functionality.\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": [] }, "EXAMPLES": { "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 grops(1) to get its representation as a Post‐\nScript file, or gropdf(1) 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 grotty(1) 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 xditview(1x) or gxditview(1) 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 groffdiff(7).\n", "subsections": [] }, "FILES": { "content": "/usr/share/groff/1.22.4/font/devname/DESC\nDevice description file for device name.\n\nsrc/libs/libdriver/input.cpp\nDefines the parser and postprocessor for the intermediate output. It is located rela‐\ntive to the top directory of the groff source tree. This parser is the definitive\nspecification of the groff intermediate output format.\n", "subsections": [] }, "AUTHORS": { "content": "James Clark wrote an early version of this document, which described only the differences be‐\ntween ditroff(7)'s output format and that of GNU roff. The present version was completely\nrewritten in 2001 by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.\n", "subsections": [] }, "SEE ALSO": { "content": "A reference like groff(7) refers to a manual page; here groff in section 7 of the man page\ndocumentation system. To read the example, look up section 7 in your desktop help system or\ncall from the shell prompt\n\nshell> man 7 groff\n\nFor more details, see man(1).\n\ngroff(1)\noption -Z and further readings on groff.\n\ngroff(7)\nfor details of the groff language such as numerical units and escape sequences.\n\ngrofffont(5)\nfor details on the device scaling parameters of the DESC file.\n\ntroff(1)\ngenerates the device-independent intermediate output.\n\nroff(7)\nfor historical aspects and the general structure of roff systems.\n\ngroffdiff(7)\nThe differences between the intermediate output in groff and classical troff.\n\ngxditview(1)\nViewer for the intermediate output.\n\ngrodvi(1), grohtml(1), grolbp(1), grolj4(1), grops(1), grotty(1)\nthe groff postprocessor programs.\n\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\nThe classical troff output language is described in two AT&T Bell Labs CSTR documents avail‐\nable on-line at Bell Labs CSTR site ⟨http://cm.bell-labs.com/cm/cs/cstr.html⟩.\n\n[CSTR #97]\nA Typesetter-independent TROFF by Brian Kernighan is the original and most comprehen‐\nsive documentation on the output language; see CSTR #97 ⟨http://cm.bell-labs.com/cm/\ncs/cstr/97.ps.gz⟩.\n\n[CSTR #54]\nThe 1992 revision of the Nroff/Troff User's Manual by J. F. Ossanna and Brian\nKernighan isn't as comprehensive as [CSTR #97] regarding the output language; see\nCSTR #54 ⟨http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz⟩.\n\n\n\ngroff 1.22.4 23 March 2022 GROFFOUT(5)", "subsections": [] } } } }