HHHHeeeeiiiirrrrlllloooooooommmm DDDDooooccccuuuummmmeeeennnnttttaaaattttiiiioooonnnn TTTToooooooollllssss NNNNrrrrooooffffffff////TTTTrrrrooooffffffff UUUUsssseeeerrrr’ssss MMMMaaaannnnuuuuaaaallll _J_o_s_e_p_h _F. _O_s_s_a_n_n_a _B_r_i_a_n _W. _K_e_r_n_i_g_h_a_n _G_u_n_n_a_r _R_i_t_t_e_r _a_n_d _o_t_h_e_r_s IIIInnnnttttrrrroooodddduuuuccccttttiiiioooonnnn _n_r_o_f_f and _t_r_o_f_f are text processors under the UNIX Time‐Sharing System1 that format text for typewriter‐like terminals and for a typesetter/raster devices, respectively. They accept lines of text interspersed with lines of format control information and format the text into a printable, paginated document hav‐ ing a user‐designed style. _n_r_o_f_f and _t_r_o_f_f offer unusual free‐ dom in document styling, including: arbitrary style headers and footers; arbitrary style footnotes; multiple automatic sequence numbering for paragraphs, sections, etc; multiple column output; dynamic font and point‐size control; arbitrary horizontal and vertical local motions at any point; and a family of automatic overstriking, bracket construction, and line drawing functions. _t_r_o_f_f produces its output in a device‐independent form, although parameterized for a specific device; _t_r_o_f_f output must be pro‐ cessed by a driver for that device to produce printed output. _n_r_o_f_f and _t_r_o_f_f are highly compatible with each other and it is almost always possible to prepare input acceptable to both. Con‐ ditional input is provided that enables the user to embed input expressly destined for either program. _n_r_o_f_f can prepare output directly for a variety of terminal types and is capable of util‐ izing the full resolution of each terminal. OOOOnnnn tttthhhheeee HHHHeeeeiiiirrrrlllloooooooommmm DDDDooooccccuuuummmmeeeennnnttttaaaattttiiiioooonnnn TTTToooooooollllssss EEEEddddiiiittttiiiioooonnnn In Summer 2005, Sun Microsystems, Inc. released the source code to the Solaris system,6 including the System V Release 4 ver‐ sion of _t_r_o_f_f, a derivative of ATT _D_o_c_u_m_e_n_t_e_r’_s _W_o_r_k_b_e_n_c_h _t_r_o_f_f, version 2. It had undergone few changes since the end of the 1980’s, so it could serve as a clean starting point for a new version of _t_r_o_f_f which is intended to be highly compatible with UNIX _t_r_o_f_f, but which also provides additional features desirable for a high‐quality typesetting application at the beginning of the 21st century. As with the other components of the _H_e_i_r_l_o_o_m _P_r_o_j_e_c_t, the origi‐ nal code, once it had been released under an Open Source license, has been made portable such that it compiles and runs on the contemporary UNIX‐style systems, including Linux. It contin‐ ues to be freely available under the same license as originally released, including its complete source code. PostScript and its close relative PDF are now the only dev‐ ice languages which are relevant to high‐quality printing; actu‐ ally, PostScript itself is more and more becoming an intermedi‐ ate language for the generation of PDF documents. The _H_e_i_r_l_o_o_m ‐ 1 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 version of _t_r_o_f_f is thus primarily directed towards generating PostScript output for further processing by a PDF creator, such as Ghostscript or Adobe Distiller; it can generate PDF‐specific instructions for prepress usage as well as for online navigation in PDF documents. The principal output device independence of _t_r_o_f_f has neverthe‐ less been retained, and changes to the intermediate language have been minor. Many _t_r_o_f_f post‐processors will thus continue to be usable with no or little adaptions. PostScript Type 1, OpenType, and TrueType have become device‐ independent font formats; virtually all commercial and free fonts are available in one of them. There is thus no need for a _t_r_o_f_f‐ specific device‐independent font format anymore; instead, _H_e_i_r_‐ _l_o_o_m _t_r_o_f_f can read font metrics directly from Type 1, OpenType, and TrueType font files. This has greatly relieved the task of installing fonts—it suffices to copy the original files to a user‐selectable font directory—, and makes it possible to access advanced typographic data, such as kerning tables or substitution instructions for old‐style numerals. _t_r_o_f_f provides convenient access to any character in a font file either by its PostScript name, by its Unicode position as speci‐ fied in a font‐specific or a generic table, or by conversion from POSIX‐style locale‐specific characters to Unicode positions. The last form allows direct input of international language texts in almost any character encoding, including UTF‐8. Improvements to the line adjusting mechanism can be activated to achieve more aesthetically pleasant output: _t_r_o_f_f can com‐ pute line breaks for a whole paragraph at once, using a variant of an algorithm originally developed by Donald Knuth and Michael Plass for the TEX system7. Interword spaces can be shrunk as an alternative to being expanded. Inter‐letter spaces and letter shapes can be dynamically varied both for computing break points and for adjusting output lines; this is sometimes called ‘‘micro‐ typography’’, cf. e.g. the thesis by Hàn The´^ Thành8. All para‐ graph formatting options can be arbitrarily combined. A variety of international paper formats and hyphenation languages are supported by _t_r_o_f_f. The algorithm for the latter is derived from the respective one developed for TEX by Franklin Liang9; _t_r_o_f_f uses the implementation of _L_i_b_H_n_j by Raph Levien. TEX hyphenation patterns can be converted to the format accepted by _t_r_o_f_f. Many internal limitations of _t_r_o_f_f have been removed; most not‐ ably, _t_r_o_f_f can now set characters in fractional point sizes. The _t_r_o_f_f language has been extended similarly as in the GNU ver‐ sion of _t_r_o_f_f, _g_r_o_f_f10; for example, names of requests, macros, strings, number registers, and fonts can consist of more than two characters. Although _H_e_i_r_l_o_o_m _t_r_o_f_f is not completely compatible with _g_r_o_f_f, a special compatibility mode is provided, and docu‐ ments prepared for _g_r_o_f_f can usually be processed without altera‐ tion. As even the most basic printing devices are now capable of ras‐ tering PostScript documents (at least using conversion tools), and as PostScript and PDF viewer programs allow an accurate on‐ screen display of _t_r_o_f_f documents, there is only one area where ‐ 2 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _n_r_o_f_f is still useful: the formatting of UNIX manual pages. The _H_e_i_r_l_o_o_m version of _n_r_o_f_f is thus specifically aimed at this task; it remains a separate program, is much smaller than _t_r_o_f_f, and is optionally able to run without external device description files. This makes it possible to use it to view manual pages even on small system distributions where the size of programs is an issue. The Solaris version of _n_r_o_f_f had already been updated to support input characters in arbitrary locales. The _H_e_i_r_l_o_o_m version adds the ability to generate UTF‐8 output. This extends the _n_r_o_f_f character set by many mathematical and typographical characters on terminals capable of displaying them. Although _H_e_i_r_l_o_o_m _n_r_o_f_f does of course not provide the typograph‐ ical extensions made for _t_r_o_f_f, it includes the same language extensions. It is thus well able to cope with the tangle of manual page code which has been produced by application writ‐ ers who have unfortunately become increasingly unaware of how to write well‐styled _n_r_o_f_f documents. This manual as well as some of the pre‐ and post‐processor com‐ mands have been derived from UNIX code released by Caldera11, and from materials released by Lucent as parts of the _P_l_a_n _9 sys‐ tem12. BBBBaaaacccckkkkggggrrrroooouuuunnnndddd ttttoooo tttthhhheeee SSSSeeeeccccoooonnnndddd EEEEddddiiiittttiiiioooonnnn _t_r_o_f_f was originally written by the late Joe Ossanna in about 1973, in assembly language for the PDP‐11, to drive the Graphic Systems CAT typesetter. It was rewritten in C around 1975, and underwent slow but steady evolution until Ossanna’s death late in 1977. In 1979, Brian Kernighan modified _t_r_o_f_f so that it would produce output for a variety of typesetters, while retaining its input specifications. Over the decade from 1979 to 1989, the internals have been modestly revised, though much of the code remains as it was when Ossanna wrote it. _t_r_o_f_f reads parameter files each time it is invoked, to set values for machine resolution, legal type sizes and fonts, and character names, character widths and the like. _t_r_o_f_f output is ASCII characters in a simple language that describes where each character is to be placed and in what size and font. A post‐processor must be written for each device to convert this typesetter‐independent language into specific instructions for that device. The output language contains information that was not readily identifiable in the older output. In the newer language, the beginning of each page, line, and word is marked, so post‐ processors can do device‐specific optimizations such as sorting the data vertically or printing it boustrophedonically, indepen‐ dent of _t_r_o_f_f. Capabilities for graphics have been added: _t_r_o_f_f recognizes com‐ mands for drawing diagonal lines, circles, ellipses, circular arcs, and quadratic B‐splines. There are also ways to pass arbi‐ trary information to the output, unprocessed by _t_r_o_f_f. A number of limitations have been eased or eliminated. A docu‐ ment may have an arbitrary number of fonts on any page (if the output device permits it, of course). Fonts may be accessed ‐ 3 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 merely by naming them; ‘‘mounting’’ is no longer necessary. There are no limits on the number of characters. Character height and slant may be set independently of width. The remainder of this document contains a description of usage and command‐line options; a summary of requests, escape sequences, and pre‐defined number registers; a reference manual; tutorial examples; and a list of commonly‐available characters. AAAAcccckkkknnnnoooowwwwlllleeeeddddggggeeeemmmmeeeennnnttttssss ((((ffffoooorrrr tttthhhheeee SSSSeeeeccccoooonnnndddd EEEEddddiiiittttiiiioooonnnn,,,, bbbbyyyy BBBBrrrriiiiaaaannnn KKKKeeeerrrrnnnniiiigggghhhhaaaannnn)))) Joe Ossanna’s _t_r_o_f_f remains a remarkable accomplishment. For more than twenty years, it has proven a robust tool, taking unbelievable abuse from a variety of preprocessors and being forced into uses that were never conceived of in the original design, all with considerable grace under fire. Recent versions of _t_r_o_f_f have profited from significant code improvements by Jaap Akkerhuis, Dennis Ritchie, Ken Thompson, and Molly Wagner. Andrew Hume, Doug McIlroy, Peter Nelson, and Ravi Sethi made valuable suggestions on the manual. I fear that the remaining bugs are my fault. AAAAcccckkkknnnnoooowwwwlllleeeeddddggggeeeemmmmeeeennnnttttssss ((((ffffoooorrrr tttthhhheeee HHHHeeeeiiiirrrrlllloooooooommmm EEEEddddiiiittttiiiioooonnnn,,,, bbbbyyyy GGGGuuuunnnnnnnnaaaarrrr RRRRiiiitttttttteeeerrrr)))) The _t_r_o_f_f program as written by Joseph Ossanna and Brian Ker‐ nighan turned out to be an excellent base for a typesetting sys‐ tem containing approximately twice as many lines of code. As with the second edition, the design and the principal parts of _t_r_o_f_f have remained the same, despite of additions and modifica‐ tions. This is particularly remarkable since much of it is now more than 40 years old, but serves its purpose as well as on day one. I am grateful to Sun, Caldera, and Lucent for releasing the source code without which this project would not have been possi‐ ble. I wish to thank Brian Kernighan for the permission to adapt this manual. AAAAvvvvaaaaiiiillllaaaabbbbiiiilllliiiittttyyyy aaaannnndddd CCCCoooonnnnttttaaaacccctttt IIIInnnnffffoooorrrrmmmmaaaattttiiiioooonnnn The source code of the _H_e_i_r_l_o_o_m _D_o_c_u_m_e_n_t_a_t_i_o_n _T_o_o_l_s and accompanying materials are freely available from . Comments and bug reports should be added at or send to . RRRReeeeffffeeeerrrreeeennnncccceeeessss [1] M. D. McIlroy, B. W. Kernighan (Eds.), _U_n_i_x _P_r_o_g_r_a_m_m_e_r’_s _M_a_n_u_a_l, Vol.2, ATT Bell Laboratories, Murray Hill, NJ 07974, 1979; . [2] B. W. Kernighan, L. L. Cherry, ‘‘Typesetting Mathematics — User’s Guide (Second Edition)’’, in [1]. [3] M. E. Lesk, ‘‘Tbl — A Program to Format Tables’’, in [1]. [4] B. W. Kernighan, ‘‘A TROFF Tutorial’’, in [1]. [5] J. F. Ossanna, ‘‘Nroff/Troff User’s Manual’’, in [1]. [6] [7] D. E. Knuth, M. F. Plass, ‘‘Breaking paragraphs into lines’’, _S_o_f_t_w_a_r_e—_P_r_a_c_t_i_c_e _a_n_d _E_x_p_e_r_i_e_n_c_e, Vol. 11, Issue 12 (1981), pp. 1119–1184; also in D. E. Knuth, _D_i_g_i_t_a_l _T_y_p_o_g_r_a_p_h_y, Stan‐ ford, 1999 (CSLI lecture notes no. 78), pp. 67–155. [8] Hàn The´^ Thành, _M_i_c_r_o‐_t_y_p_o_g_r_a_p_h_i_c _e_x_t_e_n_s_i_o_n_s _t_o _t_h_e _T_E_X _t_y_p_e_s_e_t_t_i_n_g _s_y_s_t_e_m, Masaryk University Brno, 2000. ‐ 4 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 [9] F. M. Liang, _W_o_r_d _H_y‐_p_h_e_n‐_a‐_t_i_o_n _b_y _C_o_m‐_p_u_t‐_e_r, Stanford University, CA 94305, Report No. STAN‐CS‐83‐977, 1983. [10] [11] [12] ‐ 5 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 UUUUssssaaaaggggeeee The general form of invoking _n_r_o_f_f (or _t_r_o_f_f) at UNIX command level is nnnnrrrrooooffffffff _o_p_t_i_o_n_s _f_i_l_e_(sor ttttrrrrooooffffffff _o_p_t_i_o_n_s _f_i_l_e_s) where _o_p_t_i_o_n_s represents any of a number of option arguments and _f_i_l_e_s represents the list of files containing the document to be formatted. An argument consisting of a single minus (----) is taken to be a file name corresponding to the standard input. If no file names are given input is taken from the standard input. The options, which may appear in any order so long as they appear before the files, are: _OOOO_pppp_tttt_iiii_oooo_nnnn _EEEE_ffff_ffff_eeee_cccc_tttt ----oooo_l_i_s_t Print only pages whose page numbers appear in _l_i_s_t, which consists of comma‐separated numbers and number ranges. A number range has the form _N-_M and means pages _N through _M; a initial -_N means from the beginning to page _N; and a final _N- means from _N to the end. ----nnnn_N Number first generated page _N. ----ssss_N Stop every _N pages. _n_r_o_f_f will halt prior to every _N pages (default _N=1) to allow paper loading or changing, and will resume upon receipt of a newline. _t_r_o_f_f will include a ‘‘pause’’ code every _N pages; its meaning, if any, depends on the output device. ----mmmm_n_a_m_e Prepend the macro file ////uuuussssrrrr////uuuuccccbbbblllliiiibbbb////ddddooooccccttttoooooooollllssss////ttttmmmmaaaacccc////_n_a_m_e to the input _f_i_l_e_s, or, if that file would not be accessi‐ ble, ////uuuussssrrrr////uuuuccccbbbblllliiiibbbb////ddddooooccccttttoooooooollllssss////ttttmmmmaaaacccc////ttttmmmmaaaacccc...._n_a_m_e. If the environment variable TTTTRRRROOOOFFFFFFFFMMMMAAAACCCCSSSS is set, its value is used instead of the default macro directory string, and no attempt is made to open _n_a_m_e with the ‘‘tmac.’’ prefix. The value is prepended to _n_a_m_e without inserting an additional slash as a directory separator, so it must either end with a slash itself or can be used to specify a file name prefix (as e.g. ‘‘tmac.’’). ----rrrr_a_N Register _a (one‐character) is set to _N. ----rrrr_a====N Register _a (may be more than one character) is set to _N. ----dddd_a_S String _a (one‐character) is set to _S. ----dddd_a====_S String _a (may be more than one character) is set to _S. ----iiii Read standard input after the input files are exhausted. ----qqqq Invoke the simultaneous input‐output mode of the rrrrdddd request. ----xxxx_N Set the extension level to _N (cf. §1.1). ----zzzz Check syntax only; do not generate any output except for error messages. _n_r_o_f_f Only ----eeee Produce equally‐spaced words in adjusted lines, using full terminal resolution. ‐ 6 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ----hhhh Use output tabs during horizontal spacing to speed output and reduce output character count. Tab set‐ tings are assumed to be every 8 nominal character widths. ----TTTT_n_a_m_e Specify the name of the output terminal type. Currently defined names are 33337777 for the (default) Model 37 Teletype®, llllpppp for any line printer or ter‐ minal without half‐line capability, ttttnnnn333300000000 for the GE TermiNet 300, 333300000000SSSS for the DASI‐300S, 333300000000 for the DASI‐300, and 444455550000 for the DASI‐450 (Diablo Hyterm). A special name, llllooooccccaaaalllleeee, is also supported. It gen‐ erates UTF‐8 output if permitted by the current LC_CTYPE locale, and has the same effect as llllpppp oth‐ erwise. _t_r_o_f_f Only ----ffff Refrain from feeding out paper and stopping the out‐ put device at the end of the run. ----aaaa Send a printable (ASCII) approximation of the results to the standard output. ----FFFF_p_a_t_h Look in directory _p_a_t_h for font information; the default is ////uuuussssrrrr////uuuuccccbbbblllliiiibbbb////ddddooooccccttttoooooooollllssss////ffffoooonnnntttt////ddddeeeevvvvppppssss. ----TTTT_n_a_m_e Specifies the output device. Currently defined names are ppppssss for (default) PostScript output at 72000 dpi, ppppssssmmmmeeeedddd for PostScript output at 3600 dpi, ppppsssslllloooowwww for PostScript output at 432 dpi, ppppoooosssstttt for PostScript output at 720 dpi with legacy fonts, and hhhhttttmmmmllll for producing HTML output with the ddddhhhhttttmmmmllll post‐ processor. ----uuuu_N Set the emboldening amount, i.e. the number of times a character is printed to simulate bold output, to _N. Each option is invoked as a separate argument; for example, nnnnrrrrooooffffffff ----oooo_4,_8-_1_0 ----TTTT_3_0_0_S ----mmmm_a_b_c _f_i_l_e_1 _f_i_l_e_2 requests formatting of pages 4, 8, 9, and 10 of a document con‐ tained in the files named _f_i_l_e_1 and _f_i_l_e_2, specifies the output terminal as a DASI‐300S, and invokes the macro package _a_b_c. Various pre‐ and post‐processors are available for use with _n_r_o_f_f and _t_r_o_f_f. These include the equation preprocessors _n_e_q_n and _e_q_n2 (for _n_r_o_f_f and _t_r_o_f_f respectively), the table‐construction preprocessor _t_b_l3, and _p_i_c and _g_r_a_p for various forms of graph‐ ics. A reverse‐line postprocessor _c_o_l is available for multiple‐ column _n_r_o_f_f output on terminals without reverse‐line ability; _c_o_l expects the Model 37 Teletype escape sequences that _n_r_o_f_f produces by default. _c_o_l can optionally also filter the back‐ space sequences which _n_r_o_f_f emits for underlining and emboldening in order to produce a plain text file. Another option is the _u_l postprocessor which converts backspace sequences to underline and reverse video escape sequences for CRT terminals. The ddddppppoooosssstttt postprocessor has a special role as it translates _t_r_o_f_f intermediate output to PostScript, which is currently the only relevant target device format. For example, in ttttbbbbllll _f_i_l_e_s |||| eeeeqqqqnnnn |||| ttttrrrrooooffffffff _o_p_t_i_o_n_s |||| ddddppppoooosssstttt >_o_u_t_p_u_t._p_s ‐ 7 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 the first |||| indicates the piping of _t_b_l’_s output to _e_q_n’_s input; the second the piping of _e_q_n’_s output to _t_r_o_f_f’s input; and the third indicates the piping of _t_r_o_f_f’s output to _d_p_o_s_t, which then writes PostScript code to _o_u_t_p_u_t._p_s. The following options are currently supported with _d_p_o_s_t: _OOOO_pppp_tttt_iiii_oooo_nnnn _EEEE_ffff_ffff_eeee_cccc_tttt ----eeee _e_n_c_o_d_i_n_gSet the PostScript encoding scheme. Possible values of _e_n_c_o_d_i_n_g are: 0000 using the PostScript aaaasssshhhhoooowwww operator, with the same representation as previous versions of _d_p_o_s_t 1111 using aaaasssshhhhoooowwww, integrating motion commands with text commands 2222 using the PostScript aaaawwwwiiiiddddtttthhhhsssshhhhoooowwww operator, com‐ puting space widths in PostScript 3333 using aaaawwwwiiiiddddtttthhhhsssshhhhoooowwww, computing space widths in _d_p_o_s_t 4444 using aaaasssshhhhoooowwww, storing text positions as differ‐ ences 5555 like 4444 but using a binary PostScript Level 2 representation The default is device‐specific. 3333 is the default with the high‐resolution ppppssss device; it usually produces the most efficient PostScript output and leads to the most compact PDF documents. With lower‐resolution devices, 2222 is preferred over 3333 since the latter may produce incorrect alignment because of accumulated rounding errors. 0000, 1111, or 4444 may be preferable if the text font contains many kerning pairs since 2222 or 3333 can result in less efficient or less compact output under these cir‐ cumstances. ----MMMM _m_a_r_k_s Print marks (in combination with the ttttrrrriiiimmmmaaaatttt _t_r_o_f_f request). Valid types of _m_a_r_k_s are: ccccuuuutttt‐‐‐‐ mmmmaaaarrrrkkkkssss, rrrreeeeggggiiiissssttttrrrraaaattttiiiioooonnnnmmmmaaaarrrrkkkkssss, ssssttttaaaarrrrttttaaaarrrrggggeeeettttssss, ccccoooolllloooorrrrbbbbaaaarrrrssss, and aaaallllllll. Mark names can be abbreviated and com‐ bined by colons, e.g. ----MMMMccccuuuutttt::::rrrreeeegggg will print cut marks and registration marks. ‐ 8 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 RRRReeeeqqqquuuueeeesssstttt SSSSuuuummmmmmmmaaaarrrryyyy In the following table, the notation ±_N in the _R_e_q_u_e_s_t _F_o_r_m column means that the forms _N, +_N, or -_N are permitted, to set the parameter to _N, increment it by _N, or decrement it by _N, respectively. Plain _N means that the value is used to set the parameter. _I_n_i_t_i_a_l _V_a_l_u_e_s separated by ;;;; are for _n_r_o_f_f and _t_r_o_f_f respectively. In the _N_o_t_e_s column, B Request normally causes a break. The use of ´´´´ as control character (instead of ....) suppresses the break function. D Mode or relevant parameters associated with current diversion level. E Relevant parameters are a part of the current environment. O Must stay in effect until logical output. P Mode must be still or again in effect at the time of physical output. T _t_r_o_f_f only; no effect in _n_r_o_f_f. vvvv,pppp,mmmm,uuuu Default scale indicator; if not specified, scale indicators are _i_g_n_o_r_e_d. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn 1111.... GGGGeeeennnneeeerrrraaaallll EEEExxxxppppllllaaaannnnaaaattttiiiioooonnnn ....ddddoooo _n_a_m_e ignored–Execute _n_a_m_e in extension level 3. ....xxxxffffllllaaaagggg _N 1 ignored–Set the extension level per‐ manently to _N. 2222.... FFFFoooonnnntttt aaaannnndddd CCCChhhhaaaarrrraaaacccctttteeeerrrr SSSSiiiizzzzeeee CCCCoooonnnnttttrrrroooollll ....llllcccc____ccccttttyyyyppppeeee _n_a_m_e ignored – Set the LC_CTYPE locale. ....ppppssss±_N 10point previous E,T,ppppPoint size; also ’e_s’\\\\ssss±_N. ....ffffzzzzoooooooommmm _F _Z 1 ignoredP,TZoom font _F by factor _Z. ....ssssssss _N [_M] 12/36m ignoredE,TSpace‐character size set to _N/36em; sentence space _M/36em. ....ccccssss_F_N_M off – P,T Constant character space (width) mode (font _F). ....bbbbdddd _F _N off – P,T Embolden font _F by _N−1 units. ....bbbbdddd SSSS _F _N off – P,TEmbolden Special Font when current font is _F. ....fffftttt _F Roman previous E Change to font _F = _x, _x_x, or 1‐4. Also \\\\ffff_x,\\\\ffff((((_x_x,\\\\ffff_N. ....ffffpppp _N _F [_f_i_l_e [_s_u_p_p_l_y]] ignoredPFont position; mounts the font _f_i_l_e. ....ffffppppssss _m_a_p ... ignoredP,TMount a font with a special character map. ....ffffeeeeaaaattttuuuurrrreeee _F ±_n_a_m_e ... ignoredP,TControl OpenType features. ....ffffaaaallllllllbbbbaaaacccckkkk _F _A _B ... ignoredP,TSelect the fallback sequence for font _F. ....hhhhiiiiddddeeeecccchhhhaaaarrrr _F _c _d ... ignoredP,THide the characters _c, _d, etc. from font F. ....ssssppppaaaacccceeeewwwwiiiiddddtttthhhh _N on O,T If _N≠0, use the space width from the font metrics file. ....ffffssssppppaaaacccceeeewwwwiiiiddddtttthhhh _F [_N] ignoredO,TSet the width of the space character in font _F to _N. 3333.... PPPPaaaaggggeeee CCCCoooonnnnttttrrrroooollll ....ppppllll±_N 11i 11i vvvv Page length. ....ppppaaaappppeeeerrrrssssiiiizzzzeeee _m_e_d_i_a ignoredT,uuuuSet the paper size. ....mmmmeeeeddddiiiiaaaassssiiiizzzzeeee _m_e_d_i_a ignoredT,uuuuSet the device media size. ‐ 9 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....ccccrrrrooooppppaaaatttt _L _T _W _H ignored T,pppp Set the ‘‘CropBox’’ page parameter for PDF generation. ....ttttrrrriiiimmmmaaaatttt _L _T _W _H ignored T,pppp Set the ‘‘TrimBox’’ page parameter for PDF generation. ....bbbblllleeeeeeeeddddaaaatttt _L _T _W _H ignoredT,ppppSet the ‘‘BleedBox’’ page parameter for PDF generation. ....bbbbpppp ±_N _N=1 – B Eject current page; next page number _N. ....ppppnnnn ±_N _N=1 ignored – Next page number _N. ....ppppoooo ±_N 0;1i previous mmmm Page offset. ....nnnneeee _N – _N=1v D,vvvv Need _N vertical space (_V = vertical spacing). ....mmmmkkkk _R none internal D Mark current vertical place in register _R. ....rrrrtttt ±_N none internal D,vvvvReturn (_u_p_w_a_r_d _o_n_l_y) to marked vertical place. 4444.... TTTTeeeexxxxtttt FFFFiiiilllllllliiiinnnngggg,,,, AAAAddddjjjjuuuussssttttiiiinnnngggg,,,, aaaannnndddd CCCCeeeennnntttteeeerrrriiiinnnngggg ....bbbbrrrr – – B Break. ....llllssssmmmm _x_x none none – Leading space macro is _x_x. ....bbbbrrrrpppp – – B Break and spread. ....ffffiiii fill – B,E Fill output lines. ....nnnnffff fill – B,E No filling or adjusting of output lines. ....aaaadddd _c adj,both adjust EAdjust output lines with mode _c; _c=l,r,c,b,p,_n_o_n_e ....nnnnaaaa adjust – E No output line adjusting. ....ppppaaaaddddjjjj _N off on – Control paragraph‐at‐once adjustment globally. ....cccceeee _N off _N=1 B,E Center following _N input text lines. ....rrrrjjjj _N off _N=1 B,E Right‐align following _N input text lines. ....bbbbrrrrnnnnllll _N off _N=∞ B,E Break at end of next _N input text lines. ....bbbbrrrrppppnnnnllll _N off _N=∞ B,EBreak and spread at end of next _N input text lines. ....mmmmiiiinnnnssssssss _N off off E,TMinimum word space when adjusting lines. ....lllleeeettttaaaaddddjjjj _X _U _S _Y _V off E,TDynamic letter spacing and reshaping when adjusting lines. ....sssseeeennnnttttcccchhhhaaaarrrr _c... ....????!!!!:::: off E Sentence‐ending characters. ....ttttrrrraaaannnnsssscccchhhhaaaarrrr _c.. """"’))))]]]]****†††† off E Transparent characters for sentence‐ending. ....ttttrrrraaaacccckkkk _F _S _N _T _M ignoredP,T,ppppStatic letter space tracking. ....kkkkeeeerrrrnnnn _N 1 1 P,T Control pairwise kerning. ....ffffkkkkeeeerrrrnnnn _F _N 1 1 P,TControl the use of kerning tables from font _F. ....kkkkeeeerrrrnnnnppppaaaaiiiirrrr _F _c... _G _d... _N ignoredP,TDefine a kerning pair. ....kkkkeeeerrrrnnnnaaaafffftttteeeerrrr _F _c... _N _d... _M ... P,TAdd a constant amount of space after a character. ....kkkkeeeerrrrnnnnbbbbeeeeffffoooorrrreeee _F _c... _N _d... _M ...P,TAdd a constant amount of space before a character. ‐ 10 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....llllhhhhaaaannnngggg _F _c... _N _d... _M ... ignoredTHanging characters at left margin. ....rrrrhhhhaaaannnngggg _F _c... _N _d... _M ... ignoredTHanging characters at right margin. 5555.... VVVVeeeerrrrttttiiiiccccaaaallll SSSSppppaaaacccciiiinnnngggg ....vvvvssss _N 1/6in;12pts previousE,ppppVertical base line spacing (_V). ....llllssss _N _N=1 previous E Output _N−1 _Vs after each text out‐ put line. ....sssspppp _N – _N=1_V B,vvvv Space vertical distance _N _i_n _e_i_t_h_e_r _d_i_r_e_c_t_i_o_n. ....ssssvvvv _N – _N=1_V vvvv Save vertical distance _N. ....oooossss – – – Output saved vertical distance. ....nnnnssss space – D Turn no‐space mode on. ....rrrrssss – – D Restore spacing; turn no‐space mode off. 6666.... LLLLiiiinnnneeee LLLLeeeennnnggggtttthhhh aaaannnndddd IIIInnnnddddeeeennnnttttiiiinnnngggg ....llllllll ±_N 6.5i previous E,mmmmLine length. ....iiiinnnn ±_N _N=0 previous B,E,mmmmIndent. ....ttttiiii ±_N – ignored B,E,mmmm Temporary indent. ....ppppsssshhhhaaaappppeeee ±_I_1 ±_L_1 ±_I_2 ±_L_2 ... offE,mmmmDefine the shape of the current paragraph in aaaadddd pppp mode. 7777.... MMMMaaaaccccrrrroooossss,,,, SSSSttttrrrriiiinnnnggggssss,,,, DDDDiiiivvvveeeerrrrssssiiiioooonnnn,,,, aaaannnndddd PPPPoooossssiiiittttiiiioooonnnn TTTTrrrraaaappppssss ....ddddeeee _x_x _y_y – ._y_y=........ –Define or redefine macro _x_x; end at call of _y_y. ....aaaammmm _x_x _y_y – ._y_y=........ –Append to a macro. ....ddddssss _x_x _s_t_r_i_n_g – ignored–Define a string _x_x containing _s_t_r_i_n_g. ....aaaassss _x_x _s_t_r_i_n_g – ignored–Append _s_t_r_i_n_g to string _x_x. ....llllddddssss _x_x _s_t_r_i_n_g – ignored–Define local string _x_x containing _s_t_r_i_n_g. ....ssssuuuubbbbssssttttrrrriiiinnnngggg _x_x _N [_M] _M=−1 – Replace string _x_x by its substring between _N and _M. ....lllleeeennnnggggtttthhhh _R _s_t_r_i_n_g _R set to 0–Store the length of _s_t_r_i_n_g in register _R. ....iiiinnnnddddeeeexxxx _R _x_x _s_t_r_i_n_g ignored–Store position where _s_t_r_i_n_g occurs in _x_x in register _R. ....cccchhhhoooopppp _x_x – ignored–Remove the last character of _x_x. ....rrrrmmmm _x_x – ignored – Remove request, macro, or string. ....rrrrnnnn _x_x _y_y – ignored–Rename request, macro, or string _x_x to _y_y. ....ddddiiii _x_x – end D Divert output to macro _x_x. ....ddddaaaa _x_x – end D Divert and append to _x_x. ....bbbbooooxxxx _x_x – end D Divert output to macro _x_x, excluding a partially filled line. ....bbbbooooxxxxaaaa _x_x – end D Divert and append to _x_x, excluding a partially filled line. ....uuuunnnnffffoooorrrrmmmmaaaatttt _x_x – ignored–Strip line break information from diversion _x_x. ....aaaasssscccciiiiiiiiffffyyyy _x_x – ignored–All characters in diversion _x_x changed to plain text. ‐ 11 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....wwwwhhhh _N _x_x – – vvvv Set location trap; negative is w.r.t. page bottom. ....cccchhhh _x_x _N – – vvvv Change trap location. ....ddddwwwwhhhh _N _x_x – – D,vvvvSet location trap in current diversion. ....ddddcccchhhh _x_x _N – – D,vvvvChange trap location in current diversion. ....ddddtttt _N _x_x – off D,vvvvSet a diversion trap. ....vvvvpppptttt _N 1 ignored – Enable or disable vertical position traps. ....iiiitttt _N _x_x – off E Set an input‐line count trap. ....iiiittttcccc _N _x_x – off E Input‐line count trap ignoring \\\\cccc. ....rrrreeeettttuuuurrrrnnnn – – – Return from the current macro. ....sssshhhhiiiifffftttt _N – 1 – Shift the arguments to the current macro. ....aaaallllssss _y_y _x_x – – – _y_y is created as an alias for _x_x. ....bbbbllllmmmm _x_x none none – Blank line macro is _x_x. ....eeeemmmm _x_x none none – End macro is _x_x. ....rrrreeeeccccuuuurrrrssssiiiioooonnnnlllliiiimmmmiiiitttt _N _M – – Set the maximum stack depth. 8888.... NNNNuuuummmmbbbbeeeerrrr RRRReeeeggggiiiisssstttteeeerrrrssss ....nnnnrrrr _R ±_N _M – uuuu Define and set number register _R; auto‐increment by _M. ....nnnnrrrrffff _R ±_F _G – uuuu Define and set floating‐point register _R; auto‐increment by _G. ....llllnnnnrrrr _R ±_N _M – uuuu Define and set local number regis‐ ter _R. ....llllnnnnrrrrffff _R ±_F _G – uuuu Define and set local floating‐ point register _R. ....aaaaffff _R _c arabic – – Assign format to register _R (_c=1111, iiii, IIII, aaaa, AAAA). ....rrrrrrrr _R – – – Remove register _R. ....rrrrnnnnnnnn _R _S – – – Rename register _R to _S. ....aaaallllnnnn _S _R – – – Register _S is created as an alias for _R. 9999.... TTTTaaaabbbbssss,,,, LLLLeeeeaaaaddddeeeerrrrssss,,,, aaaannnndddd FFFFiiiieeeellllddddssss ....ttttaaaa _N_t ... 8n; 0.5i noneE,mmmmTab settings; _l_e_f_t type, unless _t=RRRR(right), CCCC(centered). ....ttttcccc _c none none E Tab repetition character. ....llllcccc _c .... none E Leader repetition character. ....ffffcccc _a _b off off – Set field delimiter _a and pad char‐ acter _b. 11110000.... IIIInnnnppppuuuutttt aaaannnndddd OOOOuuuuttttppppuuuutttt CCCCoooonnnnvvvveeeennnnttttiiiioooonnnnssss aaaannnndddd CCCChhhhaaaarrrraaaacccctttteeeerrrr TTTTrrrraaaannnnssssllllaaaattttiiiioooonnnnssss ....eeeecccc _c \ \ – Set escape character. ....eeeeoooo on – – Turn off escape character mechanism. ....eeeeccccssss \ – – Save escape character. ....eeeeccccrrrr \ – – Restore saved escape character. ....eeeessssccccooooffffffff _e_s_c ... on ignored–Disable escapes _e_s_c .... ....eeeessssccccoooonnnn _e_s_c ... on ignored–Enable escapes _e_s_c .... ....llllgggg _N –;on on T Ligature mode on if _N>0. ....fffflllliiiigggg _F _s_t_r_i_n_g _c ... ignoredTDefine the ligatures in font _F. ....ffffddddeeeeffffeeeerrrrlllliiiigggg _F _s_t_r_i_n_g ... ignoredTDefer ligature building for the ‐ 12 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn first character of _s_t_r_i_n_g. ....uuuullll _N off _N=1 E Underline (italicize in _t_r_o_f_f) _N input lines. ....ccccuuuu _N off _N=1 E Continuous underline in _n_r_o_f_f; like uuuullll in _t_r_o_f_f. ....uuuuffff _F Italic Italic – Underline font set to _F (to be switched to by uuuullll). ....cccccccc _c .... .... E Set control character to _c. ....cccc2222 _c ´´´´ ´´´´ E Set nobreak control character to _c. ....ttttrrrr _a_b_c_d.... none – O Translate _a to _b, etc. on output. ....ttttrrrriiiinnnn _a_b_c_d.... none – O Translate but retranslate with aaaasssscccciiiiiiiiffffyyyy. ....ttttrrrrnnnntttt _a_b_c_d.... none – O Translate but not on transparent lines. ....ffffttttrrrr _F _a_b_c_d.... none – P,TFont‐specific ttttrrrr. ....cccchhhhaaaarrrr _c _s_t_r_i_n_g ignored–Define character _c to _s_t_r_i_n_g. ....ffffcccchhhhaaaarrrr _c _s_t_r_i_n_g ignored T Define fallback for character _c to _s_t_r_i_n_g. ....rrrrcccchhhhaaaarrrr _c... ignored–Remove character definitions for _c.... ....uuuuttttffff8888ccccoooonnnnvvvv _c_1 _c_2 ignored – _n_r_o_f_f UTF‐8 locale character trans‐ lation. ....oooouuuuttttppppuuuutttt _s_t_r_i_n_g ignored–Write _s_t_r_i_n_g directly to inter‐ mediate output. 11111111.... LLLLooooccccaaaallll HHHHoooorrrriiiizzzzoooonnnnttttaaaallll aaaannnndddd VVVVeeeerrrrttttiiiiccccaaaallll MMMMoooottttiiiioooonnnnssss,,,, aaaannnndddd tttthhhheeee WWWWiiiiddddtttthhhh FFFFuuuunnnncccc‐‐‐‐ t1111ttti2222iiio....ooonnnn OOOOvvvveeeerrrrssssttttrrrriiiikkkkeeee,,,, BBBBrrrraaaacccckkkkeeeetttt,,,, LLLLiiiinnnneeee‐ddddrrrraaaawwwwiiiinnnngggg,,,, GGGGrrrraaaapppphhhhiiiiccccssss,,,, aaaannnndddd ZZZZeeeerrrroooo‐wwwwiiiiddddtttthhhh t....FFFFttticcccuuuuiiiooooonnnnooonnnnnccccnnntnnnntttieeeeiiioccccooonttttnnnsccccssshhhhaaaarrrr _c.. """"\\\\((((rrrruuuu\\\\((((uuuullll\\\\((((rrrrnnnnoffEConnected characters for FlFFFuiuuunnnnncecccttttidiiiorooonannnswsssing. 11113333.... HHHHyyyypppphhhheeeennnnaaaattttiiiioooonnnn.... ....nnnnhhhh hyphenate – E No hyphenation. ....hhhhyyyy _N hyphenate hyphenateEHyphenate; _N = mode. ....hhhhyyyyllllaaaannnngggg _n_a_m_e off off E Set the hyphenation language. ....sssshhhhcccc _c ‐ ‐ E Set the soft hyphenation character. ....hhhhccccooooddddeeee _a_b_c_d... – E Hyphenation code of _a is _b, etc. ....hhhhyyyylllleeeennnn _N 5 5 E Hyphenate only words of at least _N characters in length. ....hhhhllllmmmm _N off off E Maximum number of consecutive hyphenated lines. ....hhhhyyyypppppppp _N _M _L 0 0 0 0 0 0 EDefine hyphenation penalties for aaaadddd pppp mode. ....bbbbrrrreeeeaaaakkkkcccchhhhaaaarrrr _c. ‐‐‐‐———— off E Optional line break characters. ....nnnnhhhhyyyycccchhhhaaaarrrr _c... ‐‐‐‐———— off E Hyphenation‐inhibiting characters. ....hhhhcccc _c \\\\%%%% \\\\%%%% E Hyphenation indicator character _c. ....hhhhwwww _w_o_r_d ... – ignored–Add words to hyphenation diction‐ ary. 11114444.... TTTThhhhrrrreeeeeeee‐PPPPaaaarrrrtttt TTTTiiiittttlllleeeessss.... ....ttttllll ´_l_e_f_t´_c_e_n_t_e_r´_r_i_g_h_t´ – – Three part title; delimiter may be any character. ....ppppcccc _c %%%% off – Page number character. ....lllltttt ±_N 6.5in previous E,mmmmLength of title. ‐ 13 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn 11115555.... OOOOuuuuttttppppuuuutttt LLLLiiiinnnneeee NNNNuuuummmmbbbbeeeerrrriiiinnnngggg.... ....nnnnmmmm ±_N _M _S _I off E Number mode on or off, set parame‐ ters. ....nnnnnnnn _N – _N=1 E Do not number next _N lines. 11116666.... CCCCoooonnnnddddiiiittttiiiioooonnnnaaaallll AAAAcccccccceeeeppppttttaaaannnncccceeee ooooffff IIIInnnnppppuuuutttt ....iiiiffff _c _a_n_y_t_h_i_n_g – – If condition _c true, accept _a_n_y_‐ _t_h_i_n_g as input, for multi‐line use \{_a_n_y_t_h_i_n_g\}. ....iiiiffff !!!!_c _a_n_y_t_h_i_n_g – – If condition _c false, accept _a_n_y_‐ _t_h_i_n_g. ....iiiiffff _N _a_n_y_t_h_i_n_g – uuuu If expression _N > 0, accept _a_n_y_‐ _t_h_i_n_g. ....iiiiffff !!!!_N _a_n_y_t_h_i_n_g – uuuu If expression _N ≤ 0 [sic], accept _a_n_y_t_h_i_n_g. ....iiiiffff ffff_F _a_n_y_t_h_i_n_g – uuuu If floating‐point expression _F > 0, accept _a_n_y_t_h_i_n_g. ....iiiiffff !!!!ffff_F _a_n_y_t_h_i_n_g – uuuu If floating‐point expression _F ≤ 0 [sic], accept _a_n_y_t_h_i_n_g. ....iiiiffff ´_s_t_r_i_n_g_1´_s_t_r_i_n_g_2´ _a_n_y_t_h_i_n_g –If _s_t_r_i_n_g_1 identical to _s_t_r_i_n_g_2, accept _a_n_y_t_h_i_n_g. ....iiiiffff !!!!´_s_t_r_i_n_g_1´_s_t_r_i_n_g_2´ _a_n_y_t_h_i_n_g–If _s_t_r_i_n_g_1 not identical to _s_t_r_i_n_g_2, accept _a_n_y_t_h_i_n_g. ....iiiieeee _c _a_n_y_t_h_i_n_g – uuuu If portion of if‐else; all above forms (like iiiiffff). ....eeeellll _a_n_y_t_h_i_n_g – – Else portion of if‐else. ....wwwwhhhhiiiilllleeee _c _a_n_y_t_h_i_n_g – – Execute _a_n_y_t_h_i_n_g while _c (like iiiiffff) is true. ....bbbbrrrreeeeaaaakkkk _n – 1 – Break out of _n nested wwwwhhhhiiiilllleeee loops. ....ccccoooonnnnttttiiiinnnnuuuueeee _n – 1 – Continue at the _n‐th nested wwwwhhhhiiiilllleeee loop. 11117777.... EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt SSSSwwwwiiiittttcccchhhhiiiinnnngggg.... ....eeeevvvv _n_a_m_e _n_a_m_e=0 previous–Environment switched (_p_u_s_h _d_o_w_n). ....eeeevvvvcccc _n_a_m_e – – Copy environment _n_a_m_e to the current environment. 11118888.... IIIInnnnsssseeeerrrrttttiiiioooonnnnssss ffffrrrroooommmm tttthhhheeee SSSSttttaaaannnnddddaaaarrrrdddd IIIInnnnppppuuuutttt ....rrrrdddd _p_r_o_m_p_t – _p_r_o_m_p_t=BEL–Read insertion. ....eeeexxxx – – – Exit from _n_r_o_f_f/_t_r_o_f_f. 11119999.... IIIInnnnppppuuuutttt////OOOOuuuuttttppppuuuutttt FFFFiiiilllleeee SSSSwwwwiiiittttcccchhhhiiiinnnngggg ....ssssoooo _f_i_l_e_n_a_m_e – – Switch source file (_p_u_s_h _d_o_w_n). ....ppppssssoooo _s_t_r_i_n_g – – Execute _s_t_r_i_n_g and read its out‐ put. ....nnnnxxxx _f_i_l_e_n_a_m_e end‐of‐file–Next file. ....ssssyyyy _s_t_r_i_n_g – – Execute program _s_t_r_i_n_g. Output not interpolated. ....ppppiiii _s_t_r_i_n_g – – Pipe output to program _s_t_r_i_n_g. ....ccccffff _f_i_l_e_n_a_m_e – – Copy file contents to _t_r_o_f_f out‐ put. ....ooooppppeeeennnn _s_t_r_e_a_m _f_i_l_e_n_a_m_e ignored–Open _f_i_l_e_n_a_m_e as _s_t_r_e_a_m, truncat‐ ing. ....ooooppppeeeennnnaaaa _s_t_r_e_a_m _f_i_l_e_n_a_m_e ignored–Open _f_i_l_e_n_a_m_e as _s_t_r_e_a_m, append‐ ‐ 14 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ing. ....wwwwrrrriiiitttteeee _s_t_r_e_a_m _t_e_x_t ignored–Write _t_e_x_t to file _s_t_r_e_a_m. ....wwwwrrrriiiitttteeeecccc _s_t_r_e_a_m _t_e_x_t ignored–Write _t_e_x_t without terminating newline. ....wwwwrrrriiiitttteeeemmmm _s_t_r_e_a_m _x_x ignored–Write contents of string, macro, or diversion _x_x. ....cccclllloooosssseeee _s_t_r_e_a_m – – Close the file _s_t_r_e_a_m. 22220000.... MMMMiiiisssscccceeeellllllllaaaannnneeeeoooouuuussss ....mmmmcccc _c _N – off E,mmmm Set margin character _c and separa‐ tion _N. ....llllppppffffxxxx _s_t_r_i_n_g off off E Set line prefix to _s_t_r_i_n_g. ....ttttmmmm _s_t_r_i_n_g – newline–Print _s_t_r_i_n_g on terminal (stan‐ dard error). ....ttttmmmmcccc _s_t_r_i_n_g – newline–Print _s_t_r_i_n_g without newline on terminal. ....nnnnoooopppp _r_e_m_a_i_n_d_e_r _o_f _l_i_n_e – – Use _r_e_m_a_i_n_d_e_r _o_f _l_i_n_e as input. ....cccchhhhoooommmmpppp _r_e_m_a_i_n_d_e_r _o_f _l_i_n_e – –Use _r_e_m_a_i_n_d_e_r _o_f _l_i_n_e _w_i_t_h_o_u_t _n_e_w_l_i_n_e as input. ....aaaabbbb _s_t_r_i_n_g – newline–Print _s_t_r_i_n_g on standard error, exit program. ....iiiigggg _y_y – ._y_y=........ – Ignore till call of _y_y. ....llllffff _N _f – – Set input line number to _N and filename to _f. ....ppppmmmm _t – all – Print macro names and sizes; if _t present, print only total of sizes. ....ffffllll – – B Flush output buffer. 22221111.... OOOOuuuuttttppppuuuutttt aaaannnndddd EEEErrrrrrrroooorrrr MMMMeeeessssssssaaaaggggeeeessss,,,, DDDDeeeebbbbuuuuggggggggiiiinnnngggg ....wwwwaaaarrrrnnnn ±_b_i_t_s|_n_a_m_e _w – Control warning messages. ....sssspppprrrreeeeaaaaddddwwwwaaaarrrrnnnn _N toggle mmmm Spread limit warning. ....eeeerrrrrrrrpppprrrriiiinnnntttt _s_t_r_i_n_g newline–Print _s_t_r_i_n_g like an error mes‐ sage. ....wwwwaaaattttcccchhhh _x_x off ignore –Notify on change of string or macro _x_x. ....uuuunnnnwwwwaaaattttcccchhhh _x_x off ignore –Disable notification for string or macro _x_x. ....wwwwaaaattttcccchhhhlllleeeennnnggggtttthhhh _N ignore – On change, report contents up to length _N. ....wwwwaaaattttcccchhhhnnnn _R off ignore –Notify on change of register _R. ....uuuunnnnwwwwaaaattttcccchhhhnnnn _R off ignore –Disable notification for register _R. 22222222.... CCCCoooolllloooorrrr SSSSuuuuppppppppoooorrrrtttt ....CCCCLLLL _c_o_l_o_r _t_e_x_t RGB black – Print _t_e_x_t in _c_o_l_o_r.* 22223333.... PPPPiiiiccccttttuuuurrrreeee IIIInnnncccclllluuuussssiiiioooonnnn ....ppppssssbbbbbbbb _f_i_l_e_n_a_m_e – – Read the PostScript bounding box from _f_i_l_e_n_a_m_e. ....BBBBPPPP _s_o_u_r_c_e _h_e_i_g_h_t _w_i_d_t_h _p_o_s_i_t_i_o_n _o_f_f_s_e_t _f_l_a_g_s _l_a_b_e_lDefine a frame and place a picture in it.* ....EEEEPPPP – – – End a picture started by ....BBBBPPPP.* ....PPPPIIII _s_o_u_r_c_e _h_e_i_g_h_t,,,,_w_i_d_t_h,,,,_y_o_f_f_s_e_t,,,,_x_o_f_f_s_e_t _f_l_a_g_sLow‐level picture inclusion.* ‐ 15 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn 22224444.... SSSSppppeeeecccciiiiaaaallll FFFFeeeeaaaattttuuuurrrreeeessss ffffoooorrrr PPPPDDDDFFFF DDDDooooccccuuuummmmeeeennnnttttssss 22225555.... _gggg_rrrr_oooo_ffff_ffff CCCCoooommmmppppaaaattttiiiibbbbiiiilllliiiittttyyyy ....ccccpppp _N off – – Enable _g_r_o_f_f compatibility mode. ....mmmmssssoooo _n_a_m_e – ignored–Include the macro package _n_a_m_e.* 22226666.... OOOOuuuuttttppppuuuutttt LLLLaaaannnngggguuuuaaaaggggeeee 22227777.... DDDDeeeevvvviiiicccceeee aaaannnndddd FFFFoooonnnntttt DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn FFFFiiiilllleeeessss ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽ ∗Defined as a macro in an external package; refer to the detailed description on how to include it. ‐ 16 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 AAAAllllpppphhhhaaaabbbbeeeettttiiiiccccaaaallll RRRReeeeqqqquuuueeeesssstttt aaaannnndddd SSSSeeeeccccttttiiiioooonnnn NNNNuuuummmmbbbbeeeerrrr CCCCrrrroooossssssss RRRReeeeffffeeeerrrreeeennnncccceeee ab........20de.........7hylang....13nhychar...13shift......7 ad.........4di.........7hylen.....13nm........15so........19 af.........8do.........1hypp......13nn........15sp.........5 aln........8ds.........7ie........16nop.......20spacewidth.2 als........7dwh........7if........16nr.........8spreadwarn21 am.........7dt.........7ig........20nrf........8ss.........2 as.........7ec........10in.........6ns.........5substring..7 asciify....7ecs.......10index......7nx........19sv.........5 bd.........2ecr.......10it.........7open......19sy........19 bleedat....3el........16itc........7opena.....19ta.........9 blm........7em.........7kern.......4os.........5tc.........9 box........7eo........10kernafter..4output....10ti.........6 boxa.......7EP........23kernbefore.4padj.......4tl........14 bp.........3errprint..21kernpair...4papersize..3tm........20 BP........23escoff....10lc.........9pc........14tr........10 br.........4escon.....10lc_ctype...2pi........19track......4 break.....16ev........17lds........7PI........23transchar..4 breakchar.13evc.......17length.....7pl.........3trimat.....3 brnl.......4ex........18letadj.....4pm........20trin......10 brp........4fallback...2lf........20pn.........3trnt......10 brpnl......4fc.........9lg........10po.........3uf........10 c2........10fchar.....10lhang......4ps.........2ul........10 cc........10fdeferlig.10li........10psbb......23unformat...7 ce.........4feature....2ll.........6pshape.....6unwatch...21 cf........19fi.........4lnr........8pso.......19unwatchn..21 ch.........7fkern......4lnrf.......8rchar.....10utf8conv..10 char......10fl........20lpfx......20rd........18vpt........7 chomp.....20flig......10ls.........5recursionlimivts7.........5 chop.......7fp.........2lsm........4return.....7warn......21 close.....19fps........2lt........14rhang......4watch.....21 CL........22fspacewidth2mc........20rj.........4watchlength21 connectchar12ft.........2mediasize..3rm.........7watchn....21 continue..16fzoom......2minss......4rn.........7wh.........7 cp........25hc........13mk.........3rnn........8while.....16 cropat.....3hcode.....13mso.......25rr.........8write.....19 cs.........2hidechar...2na.........4rs.........5writec....19 cu........10hlm.......13ne.........3rt.........3writem....19 da.........7hw........13nf.........4sentchar...4xflag......1 dch........7hy........13nh........13shc.......13 ‐ 17 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 EEEEssssccccaaaappppeeee SSSSeeeeqqqquuuueeeennnncccceeeessss ffffoooorrrr CCCChhhhaaaarrrraaaacccctttteeeerrrrssss,,,, IIIInnnnddddiiiiccccaaaattttoooorrrrssss,,,, aaaannnndddd FFFFuuuunnnnccccttttiiiioooonnnnssss _SSSS_eeee_cccc_tttt_iiii_oooo_nnnn _EEEE_ssss_cccc_aaaa_pppp_eeee _RRRR_eeee_ffff_eeee_rrrr_eeee_nnnn_cccc_eeee _SSSS_eeee_qqqq_uuuu_eeee_nnnn_cccc_eeee _MMMM_eeee_aaaa_nnnn_iiii_nnnn_gggg 10.1 \\\\\\\\ \ (to prevent or delay the interpretation of \) 2.1 \\\\´´´´ ´ (acute accent); equivalent to \\\\((((aaaaaaaa 2.1 \\\\```` ` (grave accent); equivalent to \\\\((((ggggaaaa 2.1 \\\\---- - Minus sign in the _c_u_r_r_e_n_t font 12.4 \\\\____ _ (underrule character); equivalent to \\\\((((uuuullll 7 \\\\.... Period (dot) (see ddddeeee) 4.1 \\\\(space) Unpaddable space‐size space character 4.1 \\\\∼∼∼∼ Paddable no‐break space character 11.1 \\\\0000 Digit width space 11.1 \\\\|||| 1/6em narrow space character (zero width in _n_r_o_f_f) 11.1 \\\\^^^^ 1/12em half‐narrow space character (zero width in _n_r_o_f_f) 4.1 \\\\&&&& Non‐printing, zero width character 4.1 \\\\)))) Transparent non‐printing zero width character 10.6 \\\\!!!! Transparent line indicator 10.8 \\\\"""" Beginning of comment 10.8 \\\\#### Comment including newline 7.3 \\\\$$$$_n,\\\\$$$$((((_n_n,\\\\$$$$[[[[_n_n_n]]]] Interpolate argument _n, _n_n, or _n_n_n 7.3 \\\\$$$$∗∗∗∗ Interpolate all arguments separated by spaces 7.3 \\\\$$$$@@@@ Interpolate all arguments in double quotes 7.3 \\\\$$$$0000 Interpolate name of current macro or string 13 \\\\%%%% Default optional hyphenation character 2.1 \\\\((((_x_x Character named _x_x 2.1 \\\\[[[[_x_x_x] Character named _x_x_x 7.1 \\\\∗∗∗∗_x,\\\\∗∗∗∗((((_x_x,\\\\∗∗∗∗[[[[_x_x_x]]]] Interpolate string _x, _x_x, or _x_x_x 7.1 \\\\∗∗∗∗[[[[_x_x_x _a_r_g ...]]]] Interpolate string _x_x_x with arguments _a_r_g ... 13 \\\\:::: Optional line‐break character 10.2 \\\\;;;; Ligature suppressor 17 \\\\@@@@{{{{,\\\\@@@@}}}} Inline environment push/pop 9.1 \\\\aaaa Non‐interpreted leader character 24.6 \\\\AAAA´_s_t_r_i_n_g´ Anchor definition 12.3 \\\\bbbb´_a_b_c...´ Bracket building function 1.4 \\\\BBBB'_s_t_r_i_n_g' Test if _s_t_r_i_n_g is a numerical expression 4.2 \\\\cccc Interrupt text processing 2.1 \\\\CCCC´_x_x_x´ Character named _x_x_x 11.1 \\\\dddd Forward (down) 1/2em vertical motion (1/2 line in _n_r_o_f_f) 12.5 \\\\DDDD´_c...´ Draw graphics function _c with parameters ...; _c=llll,cccc,eeee,aaaa,∼∼∼∼ 10.1 \\\\eeee Printable version of the _c_u_r_r_e_n_t escape character 10.1 \\\\EEEE Escape character, not interpreted in _c_o_p_y _m_o_d_e 2.2 \\\\ffff_x,\\\\ffff((((_x_x,\\\\ffff[[[[_x_x_x]]]],\\\\ffff_N Change to font named _x, _x_x, or _x_x_x, or position _N 8 \\\\gggg_x,\\\\gggg((((_x_x,\\\\gggg[[[[_x_x_x]]]] Format of number register _x, _x_x, or _x_x_x 11.1 \\\\hhhh´_N´ Local horizontal motion; move right _N (_n_e_g_a_t_i_v_e _l_e_f_t) 2.3 \\\\HHHH´_N´ Height of current font is _N 1.1 \\\\IIII'_s_t_r_i_n_g' Test if _s_t_r_i_n_g is a valid identifier name 4.1 \\\\jjjj´±_N´ Penalty for breaking a line after the current word is _N 4.1 \\\\JJJJ´±_N´ Default line breaking penalty is _N 11.3 \\\\kkkk_x,\\\\kkkk((((_x_x,\\\\kkkk[[[[_x_x_x]]]] Mark horizontal _i_n_p_u_t place in register _x, _x_x, or _x_x_x 12.4 \\\\llll´_N_c´ Horizontal line drawing function (optionally with _c) 12.4 \\\\LLLL´_N_c´ Vertical line drawing function (optionally with _c) 8 \\\\nnnn_x,\\\\nnnn((((_x_x,\\\\nnnn[[[[_x_x_x]]]] Interpolate number register _x, _x_x, or _x_x_x 2. \\\\NNNN´_N´ Character number _N on current font 12.1 \\\\oooo´_a_b_c...´ Overstrike characters _a, _b, _c, ... ‐ 18 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 4.1 \\\\pppp Break and spread output line 7.5 \\\\PPPP_x,\\\\PPPP((((_x_x,\\\\PPPP[[[[_x_x_x]]]] Output‐line trap _x, _x_x, or _x_x_x 11.1 \\\\rrrr Reverse 1em vertical motion (reverse line in _n_r_o_f_f) 8 \\\\RRRR´_R ±_N´ Set number register _R to ±_N 2.3 \\\\ssss_N,\\\\ssss±_N, Point‐size change function \\\\ssss´´´´±_N´´´´,\\\\ssss±´´´´_N´´´´, \\\\ssss[[[[±_N]]]],\\\\ssss±[[[[_N]]]] 2.2 \\\\SSSS´_N´ Slant output _N degrees 9.1 \\\\tttt Non‐interpreted horizontal tab 24.6 \\\\TTTT´_s_t_r_i_n_g´ Intra‐document link definition 11.1 \\\\uuuu Reverse (up) 1/2em vertical motion (1/2 line in _n_r_o_f_f) 2.1 \\\\UUUU´_X´ Character at Unicode position U+_X 11.1 \\\\vvvv´_N´ Local vertical motion; move down _N (_n_e_g_a_t_i_v_e _u_p) 20 \\\\VVVV_x,\\\\VVVV((((_x_x,\\\\VVVV[[[[_x_x_x]]]] Environment variable _x, _x_x, or _x_x_x 11.2 \\\\wwww´_s_t_r_i_n_g´ Interpolate width of _s_t_r_i_n_g 24.6 \\\\WWWW´_s_t_r_i_n_g´ URI link definition 5.2 \\\\xxxx´_N´ Extra line‐space function (_n_e_g_a_t_i_v_e _b_e_f_o_r_e, _p_o_s_i_t_i_v_e _a_f_t_e_r) 10.7 \\\\XXXX´_s_t_r_i_n_g´ Output _s_t_r_i_n_g as device control function 10.7 \\\\YYYY_x,\\\\YYYY((((_x_x,\\\\YYYY[[[[_x_x_x]]]] Output contents of macro _x, _x_x, or _x_x_x as device control function 12.2 \\\\zzzz_c Print _c with zero width (without spacing) 12.2 \\\\ZZZZ´_s_t_r_i_n_g´ Print _s_t_r_i_n_g with zero width and height 16 \\\\{{{{ Begin conditional input 16 \\\\}}}} End conditional input 10.7 \\\\(newline) Concealed (ignored) newline – \\\\_c _c, any character _n_o_t listed above The escape sequences \\\\\\\\, \\\\...., \\\\"""", \\\\####, \\\\$$$$, \\\\∗∗∗∗, \\\\aaaa, \\\\eeee, \\\\gggg, \\\\nnnn, \\\\tttt, \\\\VVVV, and \\\\(newline) are interpreted in _c_o_p_y _m_o_d_e (§7.2). PPPPrrrreeeeddddeeeeffffiiiinnnneeeedddd GGGGeeeennnneeeerrrraaaallll NNNNuuuummmmbbbbeeeerrrr RRRReeeeggggiiiisssstttteeeerrrrssss _SSSS_eeee_cccc_tttt_iiii_oooo_nnnn _RRRR_eeee_gggg_iiii_ssss_tttt_eeee_rrrr _RRRR_eeee_ffff_eeee_rrrr_eeee_nnnn_cccc_eeee _NNNN_aaaa_mmmm_eeee _DDDD_eeee_ssss_cccc_rrrr_iiii_pppp_tttt_iiii_oooo_nnnn 3 %%%% Current page number. – cccc.... Number of _l_i_n_e_s read from current input file. 11.2 cccctttt Character type (set by _w_i_d_t_h function). 7.4 ddddllll Width (maximum) of last completed diversion. 7.4 ddddnnnn Height (vertical size) of last completed diversion. – ddddwwww Current day of the week (1–7). – ddddyyyy Current day of the month (1–31). – hhhhoooouuuurrrrssss Hours portion of current local time (0–23). 11.3 hhhhpppp Current horizontal place on _i_n_p_u_t line. 15 llllnnnn Output line number. – mmmmiiiinnnnuuuutttteeeessss Minutes portion of current local time (0–59). – mmmmoooo Current month (1–12). 4.1 nnnnllll Vertical position of last printed text base‐line. 11.2 rrrrssssbbbb Visual depth of string below base line (generated by _w_i_d_t_h function). 11.2 rrrrsssstttt Visual height of string above base line (generated by _w_i_d_t_h function). 11.2 ssssbbbb Depth of string below base line (generated by _w_i_d_t_h function). – sssseeeeccccoooonnnnddddssss Seconds portion of current local time (0–60). 11.2 sssstttt Height of string above base line (generated by _w_i_d_t_h function). – yyyyeeeeaaaarrrr Current year. – yyyyrrrr Current year minus 1900. ‐ 19 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 25.1 ....gggg Current _g_r_o_f_f compatibility mode (0=off). PPPPrrrreeeeddddeeeeffffiiiinnnneeeedddd RRRReeeeaaaadddd‐OOOOnnnnllllyyyy NNNNuuuummmmbbbbeeeerrrr RRRReeeeggggiiiisssstttteeeerrrrssss _SSSS_eeee_cccc_tttt_iiii_oooo_nnnn _RRRR_eeee_gggg_iiii_ssss_tttt_eeee_rrrr _RRRR_eeee_ffff_eeee_rrrr_eeee_nnnn_cccc_eeee _NNNN_aaaa_mmmm_eeee _DDDD_eeee_ssss_cccc_rrrr_iiii_pppp_tttt_iiii_oooo_nnnn 19 $$$$$$$$ Process id of _n_r_o_f_f or _t_r_o_f_f. 7.3 ....$$$$ Number of arguments available at the current macro level. – ....AAAA Set to 1 in _t_r_o_f_f, if ----aaaa option used; always 1 in _n_r_o_f_f. 5.2 ....aaaa Post‐line extra line‐space most recently utilized using \\\\xxxx´_N´. 5.4 ....aaaasssscccceeeennnnddddeeeerrrr Ascender of current font and point size. 2.3 ....bbbb Emboldening level. 13 ....bbbbrrrreeeeaaaakkkkcccchhhhaaaarrrr Current optional line break characters. 4.1 ....bbbbrrrrnnnnllll Remaining number of lines with break at newline. 4.1 ....bbbbrrrrppppnnnnllll Remaining number of lines with break and spread at newline. – ....cccc Number of _l_i_n_e_s read from current input file. 11.2 ....ccccddddpppp Visual depth below base line of previous character. 4.1 ....cccceeee Remaining number of lines to be centered. 11.2 ....cccchhhhtttt Visual height above base line of previous character. 12.4 ....ccccoooonnnnnnnneeeeccccttttcccchhhhaaaarrrr Current characters connected for line drawing [sic]. 7.4 ....dddd Current vertical place in current diversion; equal to nnnnllll, if no diversion. 4.1 ....ddddeeeeffffppppeeeennnnaaaallllttttyyyy Default line breaking penalty. 5.4 ....ddddeeeesssscccceeeennnnddddeeeerrrr Descender of current font and point size. 7.4 ....ddddiiiilllleeeevvvv Current diversion level. 17 ....eeeevvvv Name of current environment [sic]. 2.2 ....ffff Current font as physical quadrant (1‐255). 2.2 ....ffffpppp Next unused physical font quadrant. 2.3 ....ffffzzzzoooooooommmm Current font zoom factor (may be a decimal fraction). 20 ....FFFF Current input file name [sic]. 4 ....hhhh Text base‐line high‐water mark on current page or diversion. 13 ....hhhhllllcccc Current number of consecutive hyphenated lines. 13 ....hhhhllllmmmm Maximum number of consecutive hyphenated lines. 13 ....hhhhyyyy Current hyphenation flags. 13 ....hhhhyyyyllllaaaannnngggg Current hyphenation language [sic]. 13 ....hhhhyyyylllleeeennnn Current minimum hyphenation word length. 13 ....hhhhyyyypppppppp Penalty for hyphen in aaaadddd pppp mode. 13 ....hhhhyyyypppppppp2222 Penalty for consecutive hyphens in aaaadddd pppp mode. 13 ....hhhhyyyypppppppp3333 Penalty for hyphenating the last word of a paragraph in aaaadddd pppp mode. 11.1 ....HHHH Available horizontal resolution in basic units. 6 ....iiii Current indent as set by iiiinnnn. 6 ....iiiinnnn Current indent including temporary indent, if any. 4.2 ....iiiinnnntttt Non‐zero if the previous line was interrupted with \\\\cccc. 4 ....jjjj Current aaaadddd mode. 4.1 ....kkkk Current output horizontal position. 4.2 ....kkkkcccc Output horizontal length of interrupted word, if any. 6 ....llll Current line length. 14 ....lllltttt Current title length. 2.1 ....llllcccc____ccccttttyyyyppppeeee Current LC_CTYPE locale [sic]. 4.1 ....lllleeeettttssssssss Current dynamic letter space threshold. 20 ....llllppppffffxxxx Current line prefix [sic]. 4.1 ....llllsssshhhhmmmmiiiinnnn Current minimum dynamic letter shape (may be a decimal fraction). 4.1 ....llllsssshhhhmmmmaaaaxxxx Current maximum dynamic letter shape (may be a decimal fraction). 4.1 ....llllssssppppmmmmiiiinnnn Current minimum dynamic letter space (may be a decimal fraction). ‐ 20 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 4.1 ....llllssssppppmmmmaaaaxxxx Current maximum dynamic letter space (may be a decimal fraction). 5.1 ....LLLL Current llllssss value. 4.1 ....mmmmiiiinnnnssssssss Current minimum space size. 4 ....nnnn Length of text portion on previous output line. 5 ....nnnnssss Non‐zero if no‐space mode is active. 13 ....nnnnhhhhyyyycccchhhhaaaarrrr Current hyphenation‐inhibiting characters. 3 ....oooo Current page offset. 3 ....pppp Current page length. 4 ....ppppaaaaddddjjjj Current paragraph‐at‐once global setting. 3 ....ppppnnnn Number of next page. 2.3 ....ppppssss Current point size in units. 2.3 ....ppppssssrrrr Last requested point size in units. 4.1 ....rrrrjjjj Remaining number of lines to be right‐aligned. 2.3 ....ssss Current point size (may be a decimal fraction). 13 ....sssshhhhcccc Current soft hyphenation character [sic]. 4.1 ....sssseeeennnnttttcccchhhhaaaarrrr Current sentence‐ending characters [sic]. 2.3 ....ssssrrrr Last requested point size (may be a decimal fraction). 2 ....ssssssss Current space size. 2 ....ssssssssssss Current sentence space size. 9.1 ....SSSS Current tab stops such that they can be passed back to ttttaaaa. 7.5 ....tttt Distance to the next trap. 9.1 ....ttttaaaabbbbssss Current tab stops such that they can be passed back to ttttaaaa. 4.1 ....ttttrrrraaaannnnsssscccchhhhaaaarrrr Current characters transparent for sentence‐ending [sic]. – ....TTTT Set to 1 in _n_r_o_f_f, if ----TTTT option used; always 0 in _t_r_o_f_f. 4.1 ....uuuu Equal to 1 in fill mode and 0 in nofill mode. 5.1 ....vvvv Current vertical line spacing. 7.5 ....vvvvpppptttt Vertical position traps enabled (1) or disabled (0). 11.1 ....VVVV Available vertical resolution in basic units. 11.2 ....wwww Width of previous character. 21 ....wwwwaaaarrrrnnnn Currently activated warning categories. 4.1 ....xxxx Remaining horizontal space on current output line.* 1.1 ....XXXX Current extension level. 6 ....yyyy Current indent including temporary indent, if any.* 7.4 ....zzzz Name [sic] of current diversion. 4.1 llllssssnnnn Number of leading spaces of a input line in fill mode. 4.1 llllssssssss Horizontal space corresponding to a line with leading spaces in fill mode. ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽ ∗The ....xxxx and ....yyyy registers had been described as ‘‘reserved version‐dependent registers’’ in previous editions. Their seman‐ tics have actually been as described from 7th Edition _t_r_o_f_f on. ‐ 21 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEE MMMMAAAANNNNUUUUAAAALLLL 1111.... GGGGeeeennnneeeerrrraaaallll EEEExxxxppppllllaaaannnnaaaattttiiiioooonnnn _1._1._F_o_r_m _o_f _i_n_p_u_t. Input consists of _t_e_x_t _l_i_n_e_s, which are des‐ tined to be printed, interspersed with _c_o_n_t_r_o_l _l_i_n_e_s, which set parameters or otherwise control subsequent processing. Con‐ trol lines begin with a _c_o_n_t_r_o_l _c_h_a_r_a_c_t_e_r—normally .... (period) or ´´´´ (acute accent)—followed by a name that specifies a basic _r_e_q_u_e_s_t or the substitution of a user‐defined _m_a_c_r_o in place of the control line. The control character ´´´´ suppresses the _b_r_e_a_k function—the forced output of a partially filled line—caused by certain requests. The control character may be separated from the request/macro name by white space (spaces and/or tabs) for esthetic reasons. Names must be followed by either space or new‐ line. Control lines with unrecognized names are ignored. Various special functions may be introduced anywhere in the input by means of an _e_s_c_a_p_e character, normally \\\\. For example, the function \\\\nnnn_R causes the interpolation of the contents of the _n_u_m_b_e_r _r_e_g_i_s_t_e_r _R in place of the function; here _R is either a single character name as in \\\\nnnn_x, a left‐parenthesis‐introduced, two‐character name as in \\\\nnnn((((_x_x, or a left‐bracket‐introduced, multiple character name as in \\\\nnnn[[[[_x_x_x]. In traditional _t_r_o_f_f, only one and two character names were per‐ mitted for request, macro, string, number register, and font names. Heirloom _t_r_o_f_f can accept names containing a (nearly) arbitrary number of ASCII characters. Escape \\\\IIII'_s_t_r_i_n_g' can by used to test if _s_t_r_i_n_g is a valid identifier name. By default, request and macro names are still required to contain at most two characters for compatibility reasons. The ----xxxx command line option, the ddddoooo request, or the xxxxffffllllaaaagggg request make the longer names available. The current extension level is available in the ....XXXX register. Four levels of extension availability are currently defined: 0 disables all extensions except for locale‐dependent input and Type 1/OpenType/TrueType font selection using ffffpppp. Since the ddddoooo request is not available at this level, it is not possible to change to another extension level again. It is most useful to print unmaintained documents for which any adaption would be too tedious. 1 enables extensions except for direct access to long names, i.e., ....aaaabbbbccccddddeeee will be interpreted as request aaaabbbb with argument ccccddddeeee, and \\\\****[[[[xxxxyyyyzzzz]]]] refers to the string named [[[[ followed by the text xxxxyyyyzzzz]]]]. Long names can be accessed using the ddddoooo request, e.g. ....ddddoooo ddddeeee aaaabbbbccccddddeeee, ....ddddoooo iiiiffff 1111 \\\\****[[[[xxxxyyyyzzzz]]]]. This level is the default. 2 enables direct access to long names on request lines and escape sequences, i.e., ....aaaabbbbccccddddeeee will be interpreted as macro aaaabbbbccccddddeeee, and \\\\****[[[[xxxxyyyyzzzz]]]] refers to the string named xxxxyyyyzzzz. If an undefined long ‐ 22 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 name is read, its first two characters are interpreted as a short request using the remaining characters as argument. So if a macro aaaabbbbccccddddeeee is defined, ....aaaabbbbccccddddeeee will execute it, but other‐ wise, ....aaaabbbbccccddddeeee continues to execute aaaabbbb. String and number regis‐ ter references are only interpreted if they start in the first two characters of a name, i.e. no string interpretation is per‐ formed on input ....aaaabbbb\\\\****((((xxxxyyyy. 3 ignores undefined long requests even if they form a prefix of a short request, and interprets string and number register refer‐ ences in any position of a name. It is recommended to execute ....ddddoooo xxxxffffllllaaaagggg 3333 at the beginning of new _t_r_o_f_f programs that need not rely on any existing code. _1._2._F_o_r_m_a_t_t_e_r _a_n_d _d_e_v_i_c_e _r_e_s_o_l_u_t_i_o_n. _t_r_o_f_f internally stores and processes dimensions in units that correspond to the particu‐ lar device for which output is being prepared; values from 300 to 72000/inch are typical. See §27. _n_r_o_f_f internally uses 240 units/inch, corresponding to the least common multiple of the horizontal and vertical resolutions of various typewriter‐ like output devices. _t_r_o_f_f rounds horizontal/vertical numerical parameter input to the actual horizontal/vertical resolution of the output device indicated by the ----TTTT option (default ppppssss). _n_r_o_f_f similarly rounds numerical input to the actual resolution of the output device indicated by the −−−−TTTT option (default Model 37 Tele‐ type). _1._3._N_u_m_e_r_i_c_a_l _p_a_r_a_m_e_t_e_r _i_n_p_u_t. Both _n_r_o_f_f and _t_r_o_f_f accept numer‐ ical input with the appended scale indicators shown in the fol‐ lowing table, where _S is the current type size in points, _V is the current vertical line spacing in basic units, and _C is a _n_o_m_‐ _i_n_a_l _c_h_a_r_a_c_t_e_r _w_i_d_t_h in basic units. ‐ 23 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ─┌───────────┬──────────────────────┬────────────────────────────────┐ │ Scale │ │ Number of basic units │ │Indicator │ Meaning │ _t_r_o_f_f -_T_p_s _n_r_o_f_f │ ─├───────────┼──────────────────────┼─────────────────┬───────────────┤ │ iiii │ Inch │ 72000 │ 240 │ │ cccc │ Centimeter │ 72000×50/127 │ 240×50/127 │ │ PPPP │ Pica = 1/6 inch │ 12000 │ 240/6 │ │ mmmm │ Em = _S points │ _S │ _C │ │ nnnn │ En = Em/2 │ _S/2 │ _C, _s_a_m_e _a_s _E_m │ │ MMMM │ 1/100 Em │ _S/100 │ _C/100 │ │ pppp,zzzz │ Point = 1/72 inch │ 1000 │ 240/72 │ │ uuuu,ssss │ Basic unit │ 1 │ 1 │ │ tttt │ Printer’s point │ 72000×100/7227 │ 240×100/7227 │ │ TTTT │ Printer’s pica │ 72000×400/2409 │ 240×400/2409 │ │ DDDD │ Didot point │ 72000×24/1621 │ 240×24/1621 │ │ CCCC │ Cicero │ 72000×288/1621 │ 240×288/1621 │ │ vvvv │ Vertical line space │ _V │ _V │ │ none │ Default, see below │ │ │ ─└───────────┴──────────────────────┴─────────────────┴───────────────┘ In _n_r_o_f_f, _b_o_t_h the em and the en are taken to be equal to the _C, which is output‐device dependent; common values are 1/10 and 1/12 inch. Actual character widths in _n_r_o_f_f need not be all the same and constructed characters such as −> (→) are often extra wide. The default scaling is mmmm for the horizontally‐oriented requests and functions llllllll, iiiinnnn, ttttiiii, ttttaaaa, lllltttt, ppppoooo, mmmmcccc, sssspppprrrreeeeaaaaddddwwwwaaaarrrrnnnn, \\\\hhhh, \\\\llll, and horizontal coordinates of \\\\DDDD; vvvv for the vertically‐ oriented requests and functions ppppllll, wwwwhhhh, cccchhhh, ddddtttt, sssspppp, ssssvvvv, nnnneeee, rrrrtttt, \\\\vvvv, \\\\xxxx, \\\\LLLL, and vertical coordinates of \\\\DDDD; pppp for the vvvvssss, ppppaaaappppeeeerrrrssssiiiizzzzeeee, mmmmeeeeddddiiiiaaaassssiiiizzzzeeee, ttttrrrriiiimmmmaaaatttt, bbbblllleeeeeeeeddddaaaatttt, and ccccrrrrooooppppaaaatttt requests; and uuuu for the requests nnnnrrrr, nnnnrrrrffff, iiiiffff, and iiiieeee. _A_l_l other requests ignore any scale indicators. When a number register containing an already appropriately scaled number is interpolated to pro‐ vide numerical input, the unit scale indicator uuuu may need to be appended to prevent an additional inappropriate default scaling. The number, _N, may be specified in decimal‐fraction form but the parameter finally stored is rounded to an integer number of basic units, except for floating‐point computations with nnnnrrrrffff and iiiiffff ffff. Exponential notation as in ‘1eeee++++9’ or ‘1eeee----10’ is supported. The _a_b_s_o_l_u_t_e _p_o_s_i_t_i_o_n indicator |||| may be prepended to a number _N to generate the distance to the vertical or horizontal place _N. For vertically‐oriented requests and functions, ||||_N becomes the distance in basic units from the current vertical place on the page or in a _d_i_v_e_r_s_i_o_n (§7.4) to the the vertical place _N. For _a_l_l other requests and functions, ||||_N becomes the distance from the current horizontal place on the _i_n_p_u_t line to the horizontal place _N. For example, ....sssspppp ||||3333....2222cccc will space _i_n _t_h_e _r_e_q_u_i_r_e_d _d_i_r_e_c_t_i_o_n to 3.2centimeters from the top of the page. _1._4._N_u_m_e_r_i_c_a_l _e_x_p_r_e_s_s_i_o_n_s. Wherever numerical input is expected an expression involving parentheses, the arithmetic operators ++++, −−−−, ////, ∗∗∗∗, %%%% (mod), the logical operators <<<<, >>>>, <<<<====, >>>>====, ==== (or ========), <<<<>>>> (not equal), &&&& (and), :::: (or), and the functions _a<<<>>>????_b (maximum of _a and _b), and ((((_c;;;;_e)))) (evaluate the expression _e using _c as default scale indicator, or ignoring scaling indicators if _c is omitted) may be used. Except where controlled by parentheses, evaluation of expressions is left‐ to‐right; there is no operator precedence. Spaces are ignored if they occur within parentheses; any other non‐numeric charac‐ ter terminates the expression. In the case of certain requests, an initial ++++ or −−−− is stripped and interpreted as an increment or decrement indicator respectively. In the presence of default scaling, the desired scale indicator must be attached to _e_v_e_r_y number in an expression for which the desired and default scaling differ. For example, if the number register xxxx contains 2 and the current point size is 10, then ....llllllll ((((4444....22225555iiii++++\\\\nnnnxxxxPPPP++++3333))))////2222uuuu will set the line length to 1/2 the sum of 4.25 inches + 2 picas + 30 points. The \\\\BBBB’_s_t_r_i_n_g’ escape sequence checks whether _s_t_r_i_n_g is a valid numerical expression and evaluates to ‘‘1’’ if it does and to ‘‘0’’ otherwise. _1._5._N_o_t_a_t_i_o_n. Numerical parameters are indicated in this manual in two ways. ±_N means that the argument may take the forms _N, +_N, or −_N and that the corresponding effect is to set the affected parameter to _N, to increment it by _N, or to decrement it by _N respectively. Plain _N means that an initial algebraic sign is _n_o_t an increment indicator, but merely the sign of _N. Gen‐ erally, unreasonable numerical input is either ignored or trun‐ cated to a reasonable value. For example, most requests expect to set parameters to non‐negative values; exceptions are sssspppp, wwwwhhhh, cccchhhh, nnnnrrrr, and iiiiffff. The requests ppppssss, fffftttt, ppppoooo, vvvvssss, llllssss, llllllll, iiiinnnn, and lllltttt restore the _p_r_e_v_i_o_u_s parameter value in the _a_b_s_e_n_c_e of an argu‐ ment. Single character arguments are indicated by single lower case letters and one/two character arguments are indicated by a pair of lower case letters. Character string arguments are indicated by multi‐character mnemonics. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....ddddoooo _n_a_m_e ignored–Execute the request or macro _n_a_m_e in extension level 3 and restore the previous level afterwards. ....xxxxffffllllaaaagggg _N 1 ignored–Set the extension level per‐ manently to _N. 2222.... FFFFoooonnnntttt aaaannnndddd CCCChhhhaaaarrrraaaacccctttteeeerrrr SSSSiiiizzzzeeee CCCCoooonnnnttttrrrroooollll _2._1._C_h_a_r_a_c_t_e_r _s_e_t. The basic _t_r_o_f_f character set is defined by a description file specific to each output device (§27). There are normally several regular fonts and one or more special fonts. The basic character set is shown in the attached Table I. All ASCII characters are included, with some on the Special Font. With three exceptions, the ASCII characters are input as them‐ selves, and non‐ASCII characters are input in the form \\\\((((_x_x where _x_x is a two‐character name given in the attached Table II. The three ASCII exceptions are mapped as follows: ‐ 25 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ─┌──────────────────────────┬─────────────────────────┐ │ ASCII Input │ Printed by _t_r_o_f_f │ │Character Name │ Character Name │ ─├──────────────────────────┼─────────────────────────┤ │ ´ acute accent │ ’ close quote │ │ ` grave accent │ ‘ open quote │ │ − minus │ – hyphen │ ─└──────────────────────────┴─────────────────────────┘ The characters ´´´´, ````, and ---- may be input by \\\\´´´´, \\\\````, and \\\\---- respec‐ tively or by their names (Table II). The characters \\\\ and """" can also be referred to as \\\\((((rrrrssss and \\\\((((ddddqqqq, respectively; this form allows to completely avoid their interpretation as argument del‐ imiter or escape character. In traditional _t_r_o_f_f,, the ASCII characters @@@@, ####, """", ´´´´, ````, <<<<, >>>>, \\\\, {{{{, }}}}, ~~~~, ^^^^, and ____ existed only on the Special Font and were printed as a 1‐em space if that Font was not mounted. With the ppppsssslllloooowwww device, these characters print in the _T_i_m_e_s font by default regardless of the current font (but see the ffffppppssss request below). With other devices, these characters are taken from the current font. With Type 1, OpenType, and TrueType fonts, _t_r_o_f_f allows to access all named PostScript characters of the current font and of those in the ffffaaaallllllllbbbbaaaacccckkkk sequence in the forms \\\\[[[[_n_a_m_e]]]] or \\\\CCCC''''_n_a_m_e''''. _t_r_o_f_f internally converts non‐ASCII characters of the current LC_CTYPE locale to named PostScript characters once they are read in regular (not _c_o_p_y) mode. If the current font is an OpenType or a TrueType font and contains a custom Unicode mapping table, the input character is looked up in that table first. Otherwise, a default table is used. A character that is not present in the current font is searched using the ffffaaaallllllllbbbbaaaacccckkkk sequence first, then in the special fonts. If the character cannot be found, it is discarded. Characters for which no name is known are replaced by spaces. The \\\\NNNN''''_n'''' escape sequence has historically been available to refer to character _n of the current font. It is still accepted, but its use is discouraged with Type 1, OpenType, and TrueType fonts since the arrangement of character in font tables is per‐ formed at run‐time and may change with future versions of _t_r_o_f_f. When register ....gggg is set to 1111 8‐bit character codes can also be accessed with \\\\[[[[cccchhhhaaaarrrr_n]]]] where 32≤_n≤255. _n_r_o_f_f has an analogous, but different, mechanism for defining legal characters and how to print them. By default all charac‐ ters are valid. There are such additional characters as may be available on the output device, such characters as may be able to be constructed by overstriking or other combination, and those that can reasonably be mapped into other printable characters. The exact behavior is determined by a driving table prepared for each device. In a UTF‐8 locale, combining characters are pro‐ cessed. The characters ´´´´, ````, and ____ print as themselves. Both _n_r_o_f_f and _t_r_o_f_f allow references to specific Unicode char‐ acters with the \\\\UUUU''''_X'''' escape sequence; it causes the character at position U+_X to be printed (_X is a hexadecimal number). For _t_r_o_f_f, it is required that this character is available in one of the fonts mounted at this point. As an example, \U'20AC' prints ‐ 26 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 the Euro character €. When register ....gggg is set to 1111 Unicode charactes can also be accessed with \\\\[[[[uuuu_X_X_X_X]]]] where _X_X_X_X is a four digit hexadecimal number. _2._2._F_o_n_t_s. _t_r_o_f_f begins execution by reading information for a set of defaults fonts, said to be _m_o_u_n_t_e_d; conventionally, the first four are Times Roman (RRRR), Times Italic (IIII), Times Bold (BBBB), and Times Bold Italic (BBBBIIII), and the last is a Special font (SSSS) containing miscellaneous characters. The set of fonts and posi‐ tions is determined by the device description file, described in §27. The _c_u_r_r_e_n_t font, initially Roman, may be changed (among the mounted fonts) by use of the fffftttt request, or by imbedding at any desired point either \\\\ffff_x, \\\\ffff((((_x_x, \\\\ffff[[[[_x_x_x]]]], or \\\\ffff_N where _x, _x_x, and _x_x_x are the name of a mounted font and _N is a numerical font position. It is _n_o_t necessary to change to the Special font; characters on that font are automatically handled as if they were physi‐ cally part of the current font. The Special font may actually be several fonts; the name SSSS is reserved and is generally used for one of these. The ffffaaaallllllllbbbbaaaacccckkkk request sets a font‐specific sequence of additional fonts that are searched for missing characters. _t_r_o_f_f can be informed that any particular font is mounted by use of the ffffpppp request. The list of known fonts is installa‐ tion dependent. In the subsequent discussion of font‐related requests, _F represents either a one/two‐character font name or the numerical font position. The current font is available (as numerical position) in the read‐only number register ....ffff; the ....ffffpppp register holds the next unused position. A request for a named but not‐mounted font is honored if the font description information exists. In this way, there is no limit on the number of fonts that may be printed in any part of a document. Mounted fonts may be handled more efficiently, and they may be referred to by their mount positions, but there is no other difference. Mention of an unmounted font loads it tem‐ porarily at font position zero, which serves as a one‐font cache. The function \\\\SSSS’±_N’ causes the current font to be slanted by ±_N degrees. Not all devices support slanting. _n_r_o_f_f understands font control and normally underlines Italic characters (see §10.5). _2._3._C_h_a_r_a_c_t_e_r _s_i_z_e. Character point sizes available depend on the specific output device; a typical (historical) set of values is 6, 7, 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, and 36. This is a range of 1/12 inch to 1/2 inch. Modern output dev‐ ices such as the default ddddeeeevvvvppppssss usually allow the point size to be set to arbitrary values, including fractional points. The ppppssss request is used to change or restore the point size. Alterna‐ tively the point size may be changed between any two characters by imbedding a \\\\ssss_N at the desired point to set the size to _N, or a \\\\ssss±_N (1≤_N≤8) to increment/decrement the size by _N; \\\\ssss0000 restores the _p_r_e_v_i_o_u_s size. On historical output devices, requested point size values that are between two valid sizes yielded the larger of the two. Note that through an accident of history, a construction like \\\\ssss33339999 is parsed as size 39, and thus converted to size 36 (given ‐ 27 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 the sizes above), while \\\\ssss44440000 is parsed as size 4 followed by 0000. The forms \\\\ssss((((_n_n, \\\\ssss±±±±((((_n_n, \\\\ssss´´´´±_n_n´´´´, \\\\ssss±´´´´_n_n´´´´, \\\\ssss[[[[±_n_n]]]], and \\\\ssss±[[[[_n_n]]]] permit specification of sizes that would otherwise be ambiguous. The current size (in points) is available in the ....ssss register. Note that this may be a decimal fraction if the current point size is not an integer. The ....ppppssss register stores the current size in units. The ....ssssrrrr and ....ppppssssrrrr registers store the requested point size in points and units, respectively; it is identical to the current size on modern output devices. _n_r_o_f_f ignores type size control. The function \\\\HHHH´±_N’ sets the height of the current font to _N, or increments it by +_N, or decrements it by -_N; if _N=0, the height is restored to the current point size. In each case, the width is unchanged. Not all devices support independent height and width for characters. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....llllcccc____ccccttttyyyyppppeeee _n_a_m_e ignored – Set the LC_CTYPE locale to _n_a_m_e. The default is the value of the LC_CTYPE environment variable. This request is useful to specify an input character set regardless of environment influences. The current value is available in the ....llllcccc____ccccttttyyyyppppeeee number register. ....ppppssss ±_N 10point previous E,ppppPoint size set to ±_N. Alterna‐ tively imbed \\\\ssss_N, \\\\ssss±_N, or \\\\ssss´´´´_N´´´´. Any positive size value may be requested on modern devices. If invalid, the next larger valid size will result on traditional devices, with a maximum of 36. A paired sequence +_N,−_N will work because the previous requested value is also remembered. Ignored in _n_r_o_f_f. ....ffffzzzzoooooooommmm _F _Z 1 ignoredP,TZoom font _F by factor _Z, which is a positive floating point number. This request is useful for adjusting fonts with different visual sizes but identical nominal points; the zoom is thus not applied to char‐ acters from another font that have been found by the ffffaaaallllllllbbbbaaaacccckkkk sequence or by the special font mechanism. The current value of the current font is available in the ....ffffzzzzoooooooommmm number register. ....ssssssss _N [_M] 12/36m ignoredE,TSpace‐character size is set to _N/36ems. This size is the minimum word spacing in adjusted text. The optional second argument sets the space that is added between sen‐ tences to _M/36ems. Ignored in _n_r_o_f_f. The number registers ....ssssssss and ‐ 28 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ....ssssssssssss contain the current values of _N and _M, respectively. ....ccccssss_F_N_M off – P Constant character space (width) mode is set on for font _F (if mounted); the width of every char‐ acter will be taken to be _N/36 ems. If _M is absent, the em is that of the character’s point size; if _M is given, the em is _M‐points. All affected characters are centered in this space, including those with an actual width larger than this space. Special Font characters occurring while the current font is _F are also so treated. If _N is absent, the mode is turned off. The mode must be still or again in effect when the characters are physically printed. Ignored in _n_r_o_f_f. ....bbbbdddd _F _N off – P The characters in font _F will be artificially emboldened by printing each one twice, separated by _N−1 basic units. A reasonable value for _N is 3 when the character size is in the vicinity of 10 points. If _N is missing the embolden mode is turned off. The emboldening value _N is in the ....bbbb register. TTTThhhhiiiissss ppppaaaarrrraaaaggggrrrraaaapppphhhh iiiissss pppprrrriiiinnnntttteeeedddd wwwwiiiitttthhhh ...._b_d _R _3.... TTTThhhheeee mmmmooooddddeeee mmmmuuuusssstttt bbbbeeee ssssttttiiiillllllll oooorrrr aaaaggggaaaaiiiinnnn iiiinnnn eeeeffffffffeeeecccctttt wwwwhhhheeeennnn tttthhhheeee cccchhhhaaaarrrraaaacccctttteeeerrrrssss aaaarrrreeee pppphhhhyyyyssssiiiiccccaaaallllllllyyyy pppprrrriiiinnnntttteeeedddd.... IIIIggggnnnnoooorrrreeeedddd iiiinnnn _n_r_o_f_f.... ....bbbbdddd SSSS _F _N off – P The characters in the Special Font will be emboldened whenever the current font is _F. The mode must be still or again in effect when the characters are physically printed. ....fffftttt _F Roman previous E Font changed to _F. Alternatively, imbed \\\\ffff_F. The font name PPPP is reserved to mean the previous font, and the name SSSS for the special font. ....ffffpppp _N _F [_f_i_l_e [_s_u_p_p_l_y]] ignoredPFont position. This is a state‐ ment that a font named _F is mounted on position _N. With two arguments, it is a fatal error if _F is not known as a legacy _t_r_o_f_f font file (§27.2). With three or more arguments, font metrics are read from the given _f_i_l_e, which must be in Type 1, Open‐ Type, or TrueType format. If the TTTTRRRROOOOFFFFFFFFOOOONNNNTTTTSSSS environment variable is set, each of the colon‐separated ‐ 29 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 directories in it is tested for the files _f_i_l_e._a_f_m, _f_i_l_e._o_t_f, _f_i_l_e._t_t_f, or, if the _f_i_l_e argument has an ....aaaaffffmmmm, ....oooottttffff, or ....ttttttttffff exten‐ sion itself, for _f_i_l_e. Otherwise, the font is loaded from the file ////uuuussssrrrr////uuuuccccbbbblllliiiibbbb////ddddooooccccttttoooooooollllssss////ffffoooonnnntttt////ddddeeeevvvvppppssss////_f_i_l_e....aaaaffffmmmm. The _N argument specifies a register on which the font is to be mounted (1≤_N≤255). If it is zero, the font is mounted on the next free position (not on position zero). At most 255 fonts may be mounted simultaneously; it is possible to use more than 255 fonts in a document by reusing font registers. The font is then available with ....fffftttt FFFF, \\\\ffffFFFF, etc. FFFF may be freely chosen, and may consist of more than two characters. _F may be the name of a previ‐ ously mounted font, such as RRRR. In this case, the same _N register must be reused. For best compatibility with conventional _t_r_o_f_f usage, it is recommended that the base fonts of a document are mounted as ‘‘1 R’’, ‘‘2 I’’, ‘‘3 B’’, ‘‘4 BI’’. The initial fonts on positions 9 (SSSS1111) and 10 (SSSS) should not be changed, as they contain special metrics for drawing commands. If the optional _s_u_p_p_l_y argument is present, glyph data is included in the generated PostScript file. If _s_u_p_p_l_y is one of oooottttffff, ppppffffbbbb, ppppffffaaaa, ttttttttffff, or tttt44442222, the file _s_u_p_p_l_y._p_f_b (or likewise) is searched in the directories in TTTTRRRROOOOFFFFFFFFOOOONNNNTTTTSSSS first as described for the AFM file above, and if it is not found there, in ////uuuussssrrrr////uuuuccccbbbblllliiiibbbb////ddddooooccccttttoooooooollllssss////ffffoooonnnntttt////ddddeeeevvvvppppssss////_s_u_p_p_l_y....ppppffffbbbb (or likewise). _s_u_p_p_l_y may also be the basename of a file like _f_i_l_e above. The _f_i_l_e_n_a_m_e may be surrounded by double‐quotes to permit imbedded space characters. ....ffffppppssss _m_a_p ... ignoredP,TMount a font with a special character map. By default, spe‐ cial characters like \\\\((((∗∗∗∗aaaa are not assigned when a font is mounted even if a matching named PostScript char‐ acter (like \\\\[[[[aaaallllpppphhhhaaaa]]]]) would have ‐ 30 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 been available. The following spe‐ cial character maps exist: mmmmaaaatttthhhh mathematical characters like ≤ ∪ → ∞ ggggrrrreeeeeeeekkkk greek characters like α β γ Α Β Γ ppppuuuunnnncccctttt the characters \(or - \` \´ " # < > @ \ ^ | llllaaaarrrrggggeeee parts of large characters like ⌉ ⎬ ⎩ ⎨ The ppppuuuunnnncccctttt map is used by default for the ppppssss and ppppssssmmmmeeeedddd devices. The remaining arguments are handled as described for ffffpppp. ....ffffeeeeaaaattttuuuurrrreeee _F ±_n_a_m_e ... ignoredP,TEnable (+) or disable (-) the OpenType feature _n_a_m_e in font _F. Only OpenType features that result in context‐insensitive single‐character substitutions are supported. Typical features are oooonnnnuuuummmm to enable old‐style numerals, or ssssmmmmccccpppp to enable small capitals. ....ffffaaaallllllllbbbbaaaacccckkkk _F _A _B ... ignoredP,TSelect the fallback sequence for font _F. If the current font is _F and a character is not found, font _A is searched first, then font _B, etc. If the character still has not been found, it is searched for in the Special Font, then in the fonts mounted at positions 0, 1, and so forth. ....hhhhiiiiddddeeeecccchhhhaaaarrrr _F _c _d ... ignoredP,THide the characters _c, _d, etc. from font F. If the characters appear in input afterwards, they are searched in other fonts using the fallback sequence. This is useful e.g. for combining characters from a regular and a Type 1 expert font. ....ssssppppaaaacccceeeewwwwiiiiddddtttthhhh _N on O,T If _N≠0, use the space width from the font metrics file. The space width otherwise defaults to 1/3em for variable‐width fonts, or to the width of the ssssppppaaaacccceeee character for monospaced fonts. With this request, the space width is set to the width of the ssssppppaaaacccceeee character as obtained from the font metrics file for variable‐width fonts too. ....ffffssssppppaaaacccceeeewwwwiiiiddddtttthhhh _F [_N] ignoredO,TSet the width of the space character in font _F to _N, which is given in units of 1/72000 of an inch multiplied by the current point size or 1/1000 of an em (as in AFM kern‐ ing pair definitions). If only one ‐ 31 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 argument is present, the space width is set to the width of the ssssppppaaaacccceeee character as obtained from the font metrics file. When the width of spaces in out‐ put is actually computed, the space size as set by ssssssss is also taken into account. The space width as defined above is used directly with ....ssssssss 11112222, which is the default. Otherwise, it is multiplied by the ssssssss setting divided by 12. 3333.... PPPPaaaaggggeeee ccccoooonnnnttttrrrroooollll Top and bottom margins are _n_o_t automatically provided; it is con‐ ventional to define two _m_a_c_r_o_s and to set _t_r_a_p_s for them at vert‐ ical positions 0 (top) and −_N (_N from the bottom). See §7 and Tutorial Examples §T2. A pseudo‐page transition onto the _f_i_r_s_t page occurs either when the first _b_r_e_a_k occurs or when the first _n_o_n‐_d_i_v_e_r_t_e_d text processing occurs. Arrangements for a trap to occur at the top of the first page must be completed before this transition. In the following, references to the _c_u_r_r_e_n_t _d_i_v_e_r_‐ _s_i_o_n (§7.4) mean that the mechanism being described works during both ordinary and diverted output (the former considered as the top diversion level). The physical limitations on _t_r_o_f_f and _n_r_o_f_f output are device dependent. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....ppppllll ±_N 11in 11in vvvv Page length set to ±_N. The current page length is available in the ....pppp register. ....ppppaaaappppeeeerrrrssssiiiizzzzeeee _m_e_d_i_a ignoredT,uuuuSet the paper size. _m_e_d_i_a can be one of eeeexxxxeeeeccccuuuuttttiiiivvvveeee, lllleeeetttttttteeeerrrr, lllleeeeggggaaaallll, lllleeeeddddggggeeeerrrr, ttttaaaabbbbllllooooiiiidddd, aaaa_N, bbbb_N, cccc_N, or two numbers giving the width and height directly. The page length is set from these parameters, the page offset and line length are adjusted as needed, and the post‐ processor is informed about the page metrics for its internal calcula‐ tions. The last action is the real reason why this request exists; without it, PostScript printers may displace the pages of the document. The default are lllleeeetttttttteeeerrrr measurements. This request should be used early in a document; if it is given multiple times, the last one will setup the device. ....mmmmeeeeddddiiiiaaaassssiiiizzzzeeee _m_e_d_i_a ignoredT,uuuuSet the device media size. _m_e_d_i_a can be one of eeeexxxxeeeeccccuuuuttttiiiivvvveeee, lllleeeetttttttteeeerrrr, lllleeeeggggaaaallll, lllleeeeddddggggeeeerrrr, ttttaaaabbbbllllooooiiiidddd, aaaa_N, bbbb_N, cccc_N, or two numbers giving the ‐ 32 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 width and height directly. This request performs the same actions as ppppaaaappppeeeerrrrssssiiiizzzzeeee and generates a dev‐ ice setup command in addition (the PostScript Level 2 operator sssseeeetttt‐‐‐‐ ppppaaaaggggeeeeddddeeeevvvviiiicccceeee as well as the DSC com‐ ment %%%%%%%%DDDDooooccccuuuummmmeeeennnnttttMMMMeeeeddddiiiiaaaa:::: with _d_p_o_s_t). The effect of this command can be the selection of a matching paper tray on a printer; on the other hand, the document may not print at all if no such tray is available. In general, it is recommended to use printer‐specific options from a PPD file when the file is submitted to the print spooling system instead of this request. However, when gen‐ erating PostScript as intermediate format with the intent of PDF crea‐ tion, use of this request is recom‐ mended. ....ccccrrrrooooppppaaaatttt _L _T _W _H ignored T,pppp Set the ‘‘CropBox’’ page parameter for PDF generation. The four argu‐ ments give the offset from the left (_L) and top (_T) margins of the docu‐ ment (as set by mmmmeeeeddddiiiiaaaassssiiiizzzzeeee), and width (_W) and height (_H) of the box. The default units are points. The CropBox restricts the area of the page that is shown by a PDF viewer program. It is useful to hide cut marks and other printing instruc‐ tions when the same PDF document is intended to be displayed on screen. ....ttttrrrriiiimmmmaaaatttt _L _T _W _H ignored T,pppp Set the ‘‘TrimBox’’ page parame‐ ter for PDF generation and enables printing of marks when combined with _d_p_o_s_t -_M. The four arguments give the offset from the left (_L) and top (_T) margins of the document (as set by mmmmeeeeddddiiiiaaaassssiiiizzzzeeee), and width (_W) and height (_H) of the box. The default units are points. The Trim‐ Box specifies how the page is to be cut after it has been printed; it is sort of an electronic equivalent for cut marks (which should continue to be printed in addition). ....bbbblllleeeeeeeeddddaaaatttt _L _T _W _H ignoredT,ppppSet the ‘‘BleedBox’’ page parameter for PDF generation. The four arguments give the offset from the left (_L) and top (_T) margins of the document (as set by mmmmeeeeddddiiiiaaaassssiiiizzzzeeee), and width (_W) and height (_H) of the ‐ 33 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 box. The default units are points. The BleedBox should be defined as a a frame around the objects of the actual document including any bleed areas (i.e. content that should extend to the end of the trimmed final page but is extended a bit such to work around possible cutting inaccuracies). Cut marks, color bars, and other information for the printing office should be positioned outside the BleedBox. ....bbbbpppp ±_N _N=1 – B Begin page. The current page is ejected and a new page is begun. If ±_N is given, the new page number will be ±_N. Also see request nnnnssss. ....ppppnnnn ±_N _N=1 ignored – Page number. The next page (when it occurs) will have the page number ±_N. A ppppnnnn must occur before the initial pseudo‐page transition to effect the page number of the first page. The current page number is in the %%%% register. The number of the next page is in the ....ppppnnnn register; this is either the value set by ppppnnnn or the current page number plus 1. ....ppppoooo ±_N 0;1i previous mmmm Page offset. The current _l_e_f_t _m_a_r_g_i_n is set to ±_N. The _t_r_o_f_f ini‐ tial value provides about 1 inch of paper margin on a typical device. The current page offset is available in the ....oooo register. ....nnnneeee _N – _N=1_V D,vvvv Need _N vertical space. If the dis‐ tance, _D, to the next trap posi‐ tion (see §7.5) is less than _N, a forward vertical space of size _D occurs, which will spring the trap. If there are no remaining traps on the page, _D is the distance to the bottom of the page. If _D<_V, another line could still be output and spring the trap. In a diversion, _D is the distance to the _d_i_v_e_r_s_i_o_n _t_r_a_p, if any, or is very large. ....mmmmkkkk _R none internal D Mark the _c_u_r_r_e_n_t vertical place in an internal register (both asso‐ ciated with the current diversion level), or in register _R, if given. See rrrrtttt request. ....rrrrtttt ±_N none internal D,vvvvReturn _u_p_w_a_r_d _o_n_l_y to a marked vertical place in the current diver‐ sion. If ±_N (w.r.t. current place) is given, the place is ±_N from the top of the page or diversion or, ‐ 34 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 if _N is absent, to a place marked by a previous mmmmkkkk. Note that the sssspppp request (§5.3) may be used in all cases instead of rrrrtttt by spac‐ ing to the absolute place stored in a explicit register; e.g. using the sequence ....mmmmkkkk _R ... ....sssspppp ||||\\\\nnnn_Ruuuu; this also works when the motion is down‐ wards. 4444.... TTTTeeeexxxxtttt FFFFiiiilllllllliiiinnnngggg,,,, AAAAddddjjjjuuuussssttttiiiinnnngggg,,,, aaaannnndddd CCCCeeeennnntttteeeerrrriiiinnnngggg _4._1._F_i_l_l_i_n_g _a_n_d _a_d_j_u_s_t_i_n_g. Normally, words are collected from input text lines and assembled into a output text line until some word does not fit. An attempt is then made the hyphen‐ ate the word in effort to assemble a part of it into the output line. The spaces between the words on the output line are then increased to spread out the line to the current _l_i_n_e _l_e_n_g_t_h minus any current _i_n_d_e_n_t. A _w_o_r_d is any string of characters delimited by the _s_p_a_c_e character or the beginning/end of the input line. Any adjacent pair of words that must be kept together (neither split across output lines nor spread apart in the adjustment pro‐ cess) can be tied together by separating them with the _u_n_p_a_d_d_a_b_l_e _s_p_a_c_e character "\\\\ " (backslash‐space). The paddable no‐break space character \\\\∼∼∼∼ keeps words on the same output line but may be spread during adjustment. The adjusted word spacings are uni‐ form in _t_r_o_f_f and the minimum interword spacing can be controlled with the ssssssss request (§2). In _n_r_o_f_f, word spacings are normally nonuniform because of quantization to character‐size spaces; how‐ ever, the command line option ----eeee causes uniform spacing with full output device resolution. Filling, adjustment, and hyphenation (§13) can all be prevented or controlled. The _t_e_x_t _l_e_n_g_t_h on the last line output is available in the ....nnnn register, and text base‐ line position on the page for this line is in the nnnnllll register. The text base‐line high‐water mark (lowest place) on the current page is in the ....hhhh register.* The current horizontal output position is in the ....kkkk register. The ....xxxx register indicates the remaining horizontal space on the current output line. Text lines beginning with space characters and empty text lines (blank lines) cause a break. The filling of the line currently being collected is stopped and the line is output without adjust‐ ment. The ....bbbbllllmmmm request can be used to redefine the processing of blank input lines. With the ....llllssssmmmm request the effect of lines beginning with spaces is changed. The read‐only number register llllssssnnnn contains the number of leading spaces. The read‐only number register llllssssssss contains the horizontal space which corresponds to the leading spaces. Both registers are set also if ....llllssssmmmm is not used. _t_r_o_f_f can optionally decrease word spacings, change the letter spacing, and reshape letters when adjusting lines to fit on both margins. The interword spacing controlled with the ssssssss request is then understood as the optimum setting. Words are collected from input until the first word that would require to condense ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽ ∗Local motions have no effect on register ....hhhh. ‐ 35 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 spacing or letter shapings is encountered. Between the end of the previous word and the end of this word, hyphenation points are additionally examined until the two possibilities to end the line surrounding the optimum are found. The point closest to the optimum is then chosen. If the word spacing so determined would fall below the minimum allowed, letter spacings and shapings are condensed. If it would exceed the threshold for expanded letter spacing and letter shaping, it is attempted to compensate until the threshold is reached, up to the maximum allowed letter spac‐ ing and letter shaping. Remaining space is distributed among the word spacings. Distribution among letter spacings and shaping is equal until one of the respective limits is reached. Lines that terminate with a _b_r_e_a_k are normally set using the optimum word and line spacings unless the last word collected is the first word that falls below the optimum spacing, which may result in condensed spacing and shaping. The horizontal positions in the ....kkkk and ....xxxx registers are always computed using default character and spacing widths. As an alternative to adjusting one line at a time as described, _t_r_o_f_f also supports adjusting one paragraph at once. In this mode, words are collected from input lines and requests are pro‐ cessed until a _b_r_e_a_k occurs. The words are then split into lines such that the interword spaces are closest to the optimum setting across the entire paragraph. Ultimately, the lines so determined are printed. Traps, page breaks, and any positioning become effective only at this time. It is thus well possible that the current page number as read on the input line in the %%%% regis‐ ter is lower than the number of the page on which the correspond‐ ing text is actually output. Any reference to the page number or page position (e.g. writing an index entry) should thus be han‐ dled using the output‐line trap mechanism instead of in‐line mac‐ ros. Likewise the ....kkkk and ....xxxx registers are not meaningful in this mode, except that ....kkkk is never zero when text is present in a par‐ tial paragraph. An input text line ending with ...., ????, !!!!, or ::::, optionally followed by any number of """", ´´´´, )))), ]]]], ****, or ††††, is taken to be the end of a _s_e_n_t_e_n_c_e, and an additional space character is automatically pro‐ vided during filling. To prevent this at individual locations, add \\\\&&&& to the end of the input line; the second argument to the ssssssss request (§2) changes the size of this space character and can also disable it globally. Both the sentence‐ending and the tran‐ sparent characters are configurable. The \\\\)))) character is always transparent but behaves like \\\\&&&& in all other respects. Multi‐ ple inter‐word space characters found in the input are retained, although the second character in a sequence of spaces following a sentence‐ending character has the width of a sentence space; if the sentence space has been set to zero, any sequence of spaces following a sentence‐ending character has the width of a single space. Trailing spaces are always discarded. Initial spaces are always retained and also cause a _b_r_e_a_k. With the bbbbrrrrnnnnllll request, a _b_r_e_a_k occurs at the end of each text input line in fill mode, except for lines interrupted with \\\\cccc. Contrasting to nofill mode, text is still adjusted to the line length. ‐ 36 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 When filling is in effect, a \\\\pppp may be imbedded or attached to a word to cause a _b_r_e_a_k at the _e_n_d of the word and have the result‐ ing output line _s_p_r_e_a_d _o_u_t to fill the current line length. When adjusting paragraphs at once, is possible to specify addi‐ tional _p_e_n_a_l_t_i_e_s for putting a line break after the current word (or part of a hyphenated word) by imbedding or attaching a \\\\jjjj´±_N´ to it. A positive value of _N discourages a line break, a nega‐ tive value encourages it. Values of 1000000 and above are taken as infinitive penalties and always prevent a line break; values of -1000000 always cause a line break. A default penalty can be set with the \\\\JJJJ´±_N´ escape sequence; this is useful to discourage line breaks within a certain group of words, e.g. a person’s name or a formula. Relative values in the argument to \\\\jjjj refer to the default penalty. The current default penalty is available in the ....ddddeeeeffffppppeeeennnnaaaallllttttyyyy number register. Separate penalties can be specified for breaking a line after a hyphenated word part using the hhhhyyyypppppppp request (§13). With the bbbbrrrrppppnnnnllll request, each end of a text input line in fill mode causes a _b_r_e_a_k and a spread, except for lines interrupted with \\\\cccc. The meaning of \\\\pppp is then changed such that a line that it is attached to is _n_o_t spread; this is the only method to achieve a regular _b_r_e_a_k without a spread then. Manually adjusted text can thus be typed more comfortably since only the (fewer) lines that are not spread need to be marked. A text input line that happens to begin with a control character can be made to not look like a control line by prefacing it with the non‐printing, zero‐width filler character \\\\&&&&. Still another way is to specify output translation of some convenient character into the control character using ttttrrrr (§10.5). _4._2._I_n_t_e_r_r_u_p_t_e_d _t_e_x_t. The copying of a input line in _n_o_f_i_l_l (non‐ fill) mode can be _i_n_t_e_r_r_u_p_t_e_d by terminating the partial line with a \\\\cccc. The _n_e_x_t encountered input text line will be con‐ sidered to be a continuation of the same line of input text. Similarly, a word within _f_i_l_l_e_d text may be interrupted by ter‐ minating the word (and line) with \\\\cccc; the next encountered text will be taken as a continuation of the interrupted word. If the intervening control lines cause a break, any partial line will be forced out along with any partial word. The ....iiiinnnntttt number regis‐ ter is set to a non‐zero value if the previous line was inter‐ rupted and to zero otherwise. The length of a partial word is ignored for the value of the ....kkkk number register in _f_i_l_l mode; it is separately available with the ....kkkkcccc register. _4._3._K_e_r_n_i_n_g. _t_r_o_f_f reads kerning tables from Type 1, OpenType, and TrueType font files. These tables contain small horizontal spacing adjustments for pairs of individual characters, e.g., the pair ‘‘Vo’’ would print as ‘‘Vo’’ without kerning applied. Plac‐ ing \\\\&&&& between two characters disables kerning at that location; the kkkkeeeerrrrnnnn request can disable it globally. The kkkkeeeerrrrnnnnppppaaaaiiiirrrr request adds a kerning pair; in contrast to predefined pairs, it allows the characters to originate from different fonts. It is sometimes useful to add or substact a constant amount of spacing whenever a specific character appears; for example, french quotation marks usually require some additional distance to the words contained in them. The kkkkeeeerrrrnnnnaaaafffftttteeeerrrr and kkkkeeeerrrrnnnnbbbbeeeeffffoooorrrreeee ‐ 37 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 requests allow to define such adjustments. Again, a \\\\.... disables them at individual points; they are generally not applied if the other character is a space. _4._4._H_a_n_g_i_n_g _c_h_a_r_a_c_t_e_r_s. Characters can hang beyond the left or right margins of adjusted text; the llllhhhhaaaannnngggg and rrrrhhhhaaaannnngggg requests specify this. Left margin adjustments are evaluated before the letters that fit on the current line are computed, and can thus principally be of any length. In contrast, right margin adjust‐ ments are evaluated after this computation is finished, and the adjustment is simply added to the word space of the output line. Thus a positive right adjustment that is large in relation to the line length will cause visible holes, and a negative adjustment will ultimately cause the words on the line to be printed over each other. This is not a problem for the typical application of hanging punctuation for visual alignment, though; if e.g. a line with eight word spaces is shifted by .08 em, each word space is enlarged by only .01 em. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....bbbbrrrr – – B Break. The filling of the line currently being collected is stopped and the line is output without adjustment. Text lines beginning with space characters and empty text lines (blank lines) also cause a break (This can be changed with the ....bbbbllllmmmm and ....llllssssmmmm requests.). ....llllssssmmmm _x_x none none – Whenever a line beginning with spaces is encountered, the macro _x_x is invoked instead of the default behavior to cause a break. If the spaces are followed by an escape, that may be processed before the macro is called (e.g. font changes). To avoid this prepend that escape with \\\\&&&&. ....bbbbrrrrpppp – – B Break and spread; same effect as the \\\\pppp escape sequence except that it causes the remaining part of a para‐ graph shape as set with ppppsssshhhhaaaappppeeee to be discarded. ....ffffiiii fill on – B,E Fill subsequent output lines. The register ....uuuu is 1 in fill mode and 0 in nofill mode. ....nnnnffff fill on – B,E Nofill. Subsequent output lines are _n_e_i_t_h_e_r filled _n_o_r adjusted. Input text lines are copied directly to output lines _w_i_t_h_o_u_t _r_e_g_a_r_d for the current line length. ....aaaadddd _c adj,both adjust ELine adjustment is begun. If fill mode is not on, adjustment will be deferred until fill mode is back on. If the type indicator _c is present, the adjustment type is ‐ 38 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 changed as shown in the following table. ─┌───────────┬────────────────────────────────────┐ │Indicator │ Adjust Type │ ─├───────────┼────────────────────────────────────┤ │ llll │ adjust left margin only │ │ rrrr │ adjust right margin only │ │ cccc │ center │ │ bbbb or nnnn │ adjust both margins │ │ pppp or ppppbbbb │ adjust both margins paragraph‐wise │ │ ppppllll │ adjust left margin paragraph‐wise │ │ pppprrrr │ adjust right margin paragraph‐wise │ │ ppppcccc │ center paragraph‐wise │ │ absent │ unchanged │ ─└───────────┴────────────────────────────────────┘ The number register ....jjjj contains the current value of the aaaadddd setting; its value can be recorded and used sub‐ sequently to set adjustment. ....nnnnaaaa adjust – E Noadjust. Adjustment is turned off; the right margin will be ragged. The adjustment type for aaaadddd is not changed. Output line filling still occurs if fill mode is on. ....ppppaaaaddddjjjj _N off on – Control paragraph‐at‐once adjust‐ ment globally. If _N≠0 or miss‐ ing, paragraph‐at‐once adjustment is enabled in all environments, and aaaadddd _x effectively acts like aaaadddd pppp_x. The current value is available in the ....ppppaaaaddddjjjj register. ....cccceeee _N off _N=1 B,E Center the next _N input text lines within the current (line‐length minus indent). If _N=0, any residual count is cleared. A break occurs after each of the _N input lines. If the input line is too long, it will be left adjusted. The number of lines to be right‐aligned, if any, is set to zero. The remain‐ ing number of lines to be centered is available in the ....cccceeee register. ....rrrrjjjj _N off _N=1 B,E Right‐align the next _N input text lines within the current (line‐ length minus indent); otherwise like cccceeee. The number of lines to be centered, if any, is set to zero. The remaining number of lines to be right‐justified is available in the ....rrrrjjjj register. ....bbbbrrrrnnnnllll _N off _N=∞ B,E Break at end of next _N input text lines when filling is in effect. ‐ 39 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 The remaining number of lines so treated is available in the ....bbbbrrrrnnnnllll register. ....bbbbrrrrppppnnnnllll _N off _N=∞ B,EBreak and spread at end of next _N input text lines when filling is in effect. The remaining number of lines so treated is available in the ....bbbbrrrrppppnnnnllll register. bbbbrrrrppppnnnnllll disables bbbbrrrrnnnnllll and vice‐versa. ....mmmmiiiinnnnssssssss _N off off E,TMinimum word space. When adjust‐ ing both margins, _t_r_o_f_f may decrease the size of the word space down to _N/36ems (rather than to the value set by ssssssss). The current value is available in the ....mmmmiiiinnnnssssssss register. ....lllleeeettttaaaaddddjjjj _X _U _S _Y _V off E,TDynamic letter spacing and reshaping when adjusting lines. The space between letters can be automatically expanded or condensed (in addition to the space between words), and the width of letters can be automatically changed in aaaadddd bbbb mode. The _X argument gives the minimum percentage of an en of the current point size by which adjacent characters may be tightened; the _U argument gives the minimum percen‐ tage of the letter width by which letters may be condensed. When the computed size of the word space would have to be larger than _S, additional space will be inserted between letters up to a limit of _Y percent of an en of the current point size, and letters will be expanded by up to _V percent of their width until the word space does not extend beyond _S anymore. _S is given in units of 1/36ems as with ssssssss. The number registers ....llllssssppppmmmmiiiinnnn, ....llllsssshhhhmmmmiiiinnnn, ....lllleeeettttssssssss, ....llllssssppppmmmmaaaaxxxx, and ....llllsssshhhhmmmmaaaaxxxx contain the current values of _X, _U, _S, _Y, and _V, respectively. ....sssseeeennnnttttcccchhhhaaaarrrr _c... ....????!!!!:::: off E Sentence‐ending characters. When one of the characters _c... appears at the end of an input text line, an additional space character of the size defined with the ssssssss request is inserted. The current set of sentence‐ending characters is avail‐ able in the ....sssseeeennnnttttcccchhhhaaaarrrr number regis‐ ter. ....ttttrrrraaaannnnsssscccchhhhaaaarrrr _c.. """"’))))]]]]****†††† off E Transparent characters for sentence‐ending. A sentence‐ending ‐ 40 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 character is recognized as such even if followed by one or more of the characters _c... before the end of an input text line. The current set of transparent characters for sen‐ tence ending is available in the ....ttttrrrraaaannnnsssscccchhhhaaaarrrr number register. ....ttttrrrraaaacccckkkk _F _S _N _T _M ignoredP,T,ppppStatic letter space track‐ ing. If the current font is _F and the point size is below or equal to _S, white space of width _N is added to each character. If the point size is above or equal to _T, white space of width _M is added. If the point size is between _S and _T, the amount of white space added is computed as a value between _N and _M using the current point size _s: (_s_M-_s_N+_T_N-_S_M)/(_T-_S). The default unit for all numeric argu‐ ments is points. Negative numbers are accepted and cause a decrease of letter space. No adjustment is per‐ formed on the last character of an output line. Tracking also applies to characters from another font that have been selected by the ffffaaaallllllllbbbbaaaacccckkkk sequence. ....kkkkeeeerrrrnnnn _N 1 1 P,T Control pairwise kerning; disabled if _N=0, otherwise enabled. ....ffffkkkkeeeerrrrnnnn _F _N 1 1 P,TControl the use of kerning tables from font _F; disabled if _N=0, enabled if _N=1 or missing. For _N≥2, only kerning pairs with abso‐ lute values greater or equal to _N are used. _t_r_o_f_f kerning adjustments as defined by the following requests are not affected. ....kkkkeeeerrrrnnnnppppaaaaiiiirrrr _F _c... _G _d... _N ignoredP,TAdd a kerning pair to the kerning table for character _c from font _F and character _d from font _G. _c and _d may consist of multi‐ ple characters; in this case, table entries are added for any pair com‐ bination of characters from _c and _d. The _N argument is 1/72000 of an inch multiplied by the current point size or 1/1000 of an em (as in AFM kerning pair definitions); it may be negative. To add a kerning pair that includes the space character, use ‘‘\ ’’. ....kkkkeeeerrrrnnnnaaaafffftttteeeerrrr _F _c... _N _d... _M ... P,TAdd a constant amount of space after a character if the current ‐ 41 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 font is _F and _c is the first charac‐ ter of a pair of characters subject to kerning. _c may consist of mul‐ tiple characters; in this case, the same amount is added whenever one of the given characters appears. The _N argument is 1/72000 of an inch mul‐ tiplied by the current point size or 1/1000 of an em (as in AFM kerning pair definitions); it may be nega‐ tive. Same for _d/_M etc. ....kkkkeeeerrrrnnnnbbbbeeeeffffoooorrrreeee _F _c... _N _d... _M ...P,TAdd a constant amount of space before a character if the current font is _F and _c is the second char‐ acter of a pair of characters sub‐ ject to kerning. _c may consist of multiple characters; in this case, the same amount is added whenever one of the given characters appears. The _N argument is 1/72000 of an inch multiplied by the current point size or 1/1000 of an em (as in AFM kern‐ ing pair definitions); it may be negative. Same for _d/_M etc. ....llllhhhhaaaannnngggg _F _c... _N _d... _M ... ignoredTHanging characters at left margin. When the current font is _F and _c appears at the left margin of an output line in left‐adjusted, both‐adjusted, or nofill mode, the margin is relocated to the right by _N, which is 1/72000 of an inch mul‐ tiplied by the current point size or 1/1000 of an em (as in AFM char‐ acter width definitions); it may be negative. _c may consist of multiple characters; in this case, the mar‐ gin is relocated whenever one of the given characters appears. Same for _d/_M etc. ....rrrrhhhhaaaannnngggg _F _c... _N _d... _M ... ignoredTHanging characters at right margin. When the current font is _F and _c appears at the right margin of an output line in right‐adjusted, both‐adjusted, or nofill mode, the margin is relocated to the right by _N, which is 1/72000 of an inch mul‐ tiplied by the current point size or 1/1000 of an em (as in AFM char‐ acter width definitions); it may be negative. _c may consist of multiple characters; in this case, the mar‐ gin is relocated whenever one of the given characters appears. Same for _d/_M etc. ‐ 42 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 5555.... VVVVeeeerrrrttttiiiiccccaaaallll SSSSppppaaaacccciiiinnnngggg _5._1._B_a_s_e‐_l_i_n_e _s_p_a_c_i_n_g. The vertical spacing (_V) between the base‐ lines of successive output lines can be set using the vvvvssss request. _V should be large enough to accommodate the character sizes on the affected output lines. For the common type sizes (9‐ 12 points), usual typesetting practice is to set _V to 2 points greater than the point size; _t_r_o_f_f default is 10‐point type on a 12‐point spacing (as in this document). The current _V is avail‐ able in the ....vvvv register. Multiple‐_V line separation (e.g. dou‐ ble spacing) may be requested with llllssss, but it is better to use a large vvvvssss instead; certain preprocessors assume single spacing. The current line spacing is available in the ....LLLL register. _5._2._E_x_t_r_a _l_i_n_e‐_s_p_a_c_e. If a word contains a vertically tall con‐ struct requiring the output line containing it to have extra vertical space before and/or after it, the _e_x_t_r_a‐_l_i_n_e‐_s_p_a_c_e func‐ tion \\\\xxxx´_N´ can be imbedded in or attached to that word. If _N is negative, the output line containing the word will be preceded by _N extra vertical space; if _N is positive, the output line con‐ taining the word will be followed by _N extra vertical space. If successive requests for extra space apply to the same line, the maximum values are used. The most recently utilized post‐line extra line‐space is available in the ....aaaa register. In \\\\xxxx´...´ and other functions having a pair of delimiters around their parameter (here ´´´´), the delimiter choice is arbitrary, except that it can not look like the continuation of a number expression for _N. _5._3._B_l_o_c_k_s _o_f _v_e_r_t_i_c_a_l _s_p_a_c_e. A block of vertical space is ordi‐ narily requested using sssspppp, which honors the _n_o‐_s_p_a_c_e mode and which does not space _p_a_s_t a trap. A contiguous block of vertical space may be reserved using ssssvvvv. _5._4._A_s_c_e_n_d_e_r_s _a_n_d _d_e_s_c_e_n_d_e_r_s. Type 1, OpenType, and TrueType metrics supply information about the typical extents of charac‐ ters above the base‐line (ascender) and below it (descender). Usually, these correspond to the top of the lowercase ‘‘d’’ and the bottom of the lowercase ‘‘p’’, respectively. The ....aaaasssscccceeeennnnddddeeeerrrr and ....ddddeeeesssscccceeeennnnddddeeeerrrr number registers contain these values in units with correct scaling for the current point size applied. If no values are available, these registers are set to zero. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....vvvvssss_N 1/6in;12pts previousE,ppppSet vertical base‐line spac‐ ing size _V. Transient _e_x_t_r_a verti‐ cal space available with \\\\xxxx´_N´ (see above). ....llllssss_N _N=1 previous E _L_i_n_e spacing set to ±_N. _N−1 _Vs (_b_l_a_n_k _l_i_n_e_s) are appended to each output text line. Appended blank lines are omitted, if the text or previous appended blank line reached a trap position. ....sssspppp _N – _N=1_V B,vvvv Space vertically in _e_i_t_h_e_r direc‐ tion. If _N is negative, the motion is _b_a_c_k_w_a_r_d (upward) and is lim‐ ited to the distance to the top of ‐ 43 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 the page. Forward (downward) motion is truncated to the distance to the nearest trap. (Recall the use of ....sssspppp ||||_N from §1.3.) If the no‐space mode is on, no spacing occurs (see nnnnssss, and rrrrssss below). ....ssssvvvv _N – _N=1_V vvvv Save a contiguous vertical block of size _N. If the distance to the next trap is greater than _N, _N vertical space is output. No‐space mode has _n_o effect. If this distance is less than _N, no vertical space is immedi‐ ately output, but _N is remembered for later output (see oooossss). Subse‐ quent ssssvvvv requests will overwrite any still remembered _N. ....oooossss – – – Output saved vertical space. No‐ space mode has _n_o effect. Used to finally output a block of verti‐ cal space requested by an earlier ssssvvvv request. ....nnnnssss space – D No‐space mode turned on. When on, the no‐space mode inhibits sssspppp requests and bbbbpppp requests _w_i_t_h_o_u_t a next page number. The no‐space mode is turned off when a line of out‐ put occurs, or with rrrrssss. The number register ....nnnnssss is set to a non‐zero value in no‐space mode and to zero otherwise. ....rrrrssss space – D Restore spacing. The no‐space mode is turned off. Blank text line. – B Causes a break and output of a blank line exactly like sssspppp 1111 unless a different action has been speci‐ fied with the bbbbllllmmmm request. 6666.... LLLLiiiinnnneeee LLLLeeeennnnggggtttthhhh aaaannnndddd IIIInnnnddddeeeennnnttttiiiinnnngggg The maximum line length for fill mode may be set with llllllll. The indent may be set with iiiinnnn; an indent applicable to _o_n_l_y the _n_e_x_t output line may be set with ttttiiii. The line length includes indent space but _n_o_t page offset space. The line‐length minus the indent is the basis for centering with cccceeee. The effect of llllllll, iiiinnnn, or ttttiiii is delayed, if a partially collected line exists, until after that line is output. In fill mode the length of text on an output line is less than or equal to the line length minus the indent. The current line length and indent are available in registers ....llll and ....iiii respectively; the ....yyyy and ....iiiinnnn registers both hold the indent that actually applies to the current line, taking a temporary indent into account. The length of _t_h_r_e_e‐_p_a_r_t _t_i_t_l_e_s produced by ttttllll (see §14) is _i_n_d_e_p_e_n_d_e_n_t_l_y set by lllltttt. In aaaadddd pppp mode, indent, temporary indent, and line length should be predefined for the entire paragraph at the time a _b_r_e_a_k occurs. To achieve this with indent and line length varying inside a paragraph, a shape can be defined with ppppsssshhhhaaaappppeeee. The llllllll and iiiinnnn ‐ 44 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 requests are also effective while formatting a paragraph but may result in less optimal line breaking decisions then. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....llllllll ±_N 6.5in previous E,mmmmLine length is set to ±_N. ....iiiinnnn ±_N _N=0 previous B,E,mmmmIndent is set to ±_N. The indent is prepended to each output line. ....ttttiiii ±_N – ignored B,E,mmmm Temporary indent. The _n_e_x_t output text line will be indented a dis‐ tance ±_N with respect to the current indent. The resulting total indent may not be negative. The current indent is not cghraanpghedi.n when the a special aaaadddd pppp paragraph shape for mode. At gets for‐ the cur‐ the matted, rent para‐ next _b_r_e_a_k its first line is indented by _I_1 and has length _L_1, its second line is indented by _I_2 and has length _L_2, and so forth. Relative numbers refer to the the first pair. previous indent The last of the or line length indent and line pair, or to the length pairs values set by stays effective iiiinnnn and llllllll for if the paragraph has more lines than pairs are giv‐ en. With an odd number of argu‐ ments, the standard line length as set by llllllll is used at the end. Once the current paragraph has been printed, the shape specification is forgotten, and the standard indent and line length values are in effect again unless another ppppsssshhhhaaaappppeeee request occurs. As an exception, \\\\pppp pre‐ serves the remaining part of the shape. To produce shapes with holes as in this example, diversion traps can be used to move formatted lines in vertical direction. 7777.... MMMMaaaaccccrrrroooossss,,,, SSSSttttrrrriiiinnnnggggssss,,,, DDDDiiiivvvveeeerrrrssssiiiioooonnnn,,,, aaaannnndddd PPPPoooossssiiiittttiiiioooonnnn TTTTrrrraaaappppssss _7._1._M_a_c_r_o_s _a_n_d _s_t_r_i_n_g_s. A _m_a_c_r_o is a named set of arbitrary _l_i_n_e_s that may be invoked by name or with a _t_r_a_p. A _s_t_r_i_n_g is a named string of _c_h_a_r_a_c_t_e_r_s, _n_o_t including a newline character, that may be interpolated by name at any point. Request, macro, and string names share the _s_a_m_e name list. Macro and string names may con‐ sist of an arbitrary number of ASCII characters (§1.1) and may usurp previously defined request, macro, or string names; this implies that build‐in operators may be (irrevocably) redefined. Any of these entities may be renamed with rrrrnnnn or removed with rrrrmmmm. Macros are created by ddddeeee and ddddiiii, and appended to by aaaammmm and ddddaaaa; ‐ 45 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ddddiiii and ddddaaaa cause normal output to be stored in a macro. Strings are created by ddddssss and appended to by aaaassss. A macro is invoked in the same way as a request; a control line beginning ...._x_x will interpolate the contents of macro _x_x. The remainder of the line may contain arbitrarily many _a_r_g_u_m_e_n_t_s. The strings _x, _x_x, and _x_x_x are interpolated at any desired point with \\\\∗∗∗∗_x, \\\\∗∗∗∗((((_x_x, and \\\\∗∗∗∗[[[[_x_x_x]]]] respectively; the form \\\\∗∗∗∗[[[[_x_x_x _a_r_g ...]]]] allows to specify arguments to a string. String references and macro invocations may be nested. _7._2._C_o_p_y _m_o_d_e _i_n_p_u_t _i_n_t_e_r_p_r_e_t_a_t_i_o_n. During the definition and extension of strings and macros (not by diversion) the input is read in _c_o_p_y _m_o_d_e. The input is copied without interpretation _e_x_c_e_p_t that: • The contents of number registers indicated by \\\\nnnn are interpolated. • Strings indicated by \\\\∗∗∗∗ are interpolated. • Arguments indicated by \\\\$$$$ are interpolated. • Environment variables indicated by \\\\VVVV are interpolated. • Concealed newlines indicated by \\\\(newline) are eliminated. • Comments indicated by \\\\"""" or \\\\#### are eliminated. • \\\\tttt and \\\\aaaa are interpreted as ASCII horizontal tab and SOH respectively (§9). • \\\\\\\\ is interpreted as \\\\. • \\\\.... is interpreted as "....". These interpretations can be suppressed by prepending a \\\\. For example, since \\\\\\\\ maps into a \\\\, \\\\\\\\nnnn will copy as \\\\nnnn which will be interpreted as a number register indicator when the macro or string is reread. _7._3._A_r_g_u_m_e_n_t_s. When a macro is invoked by name, the remainder of the line is taken to contain arguments. The argument separa‐ tor is the space character, and arguments may be surrounded by double‐quotes to permit imbedded space characters. Pairs of double‐quotes may be imbedded in double‐quoted arguments to represent a single double‐quote character. The argument """""""" is explicitly null. If the desired arguments won’t fit on a line, a concealed newline may be used to continue on the next line. A trailing double quote may be omitted. Similarly, arguments may be passed to strings with the \\\\∗∗∗∗[[[[ syn‐ tax, separated by spaces, until the argument list ends with the ]]]] character. String arguments are otherwise handled exactly like macro arguments. When a macro is invoked the _i_n_p_u_t _l_e_v_e_l is _p_u_s_h_e_d _d_o_w_n and any arguments available at the previous level become unavail‐ able until the macro is completely read and the previous level is restored. A macro’s own arguments can be interpolated at _a_n_y point within the macro with \\\\$$$$_n, \\\\$$$$((((_n_n, or \\\\$$$$[[[[_n_n_n]]]], which inter‐ polates the _nth, _n_nth, or _n_n_nth argument, respectively. If an invoked argument doesn’t exist, a null string results. For exam‐ ple, the macro _x_x may be defined by ....ddddeeee xxxxxxxx \\\\""""bbbbeeeeggggiiiinnnn ddddeeeeffffiiiinnnniiiittttiiiioooonnnn TTTTooooddddaaaayyyy iiiissss \\\\\\\\$$$$1111 tttthhhheeee \\\\\\\\$$$$2222.... ........ \\\\""""eeeennnndddd ddddeeeeffffiiiinnnniiiittttiiiioooonnnn and called by ....xxxxxxxx MMMMoooonnnnddddaaaayyyy 11114444tttthhhh to produce the text TTTTooooddddaaaayyyy iiiissss MMMMoooonnnnddddaaaayyyy tttthhhheeee 11114444tttthhhh.... ‐ 46 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 Note that the \\\\$$$$ was concealed in the definition with a prepended \\\\. The escape sequence \\\\$$$$∗∗∗∗ interpolates all arguments to a macro, separated by spaces; \\\\$$$$@@@@ interpolates all arguments, each one surrounded by double quotes, separated by spaces. The name of the current macro or string is available with the \\\\$$$$0000 escape sequence. The number of currently available arguments is in the ....$$$$ register. No arguments are available at the top (non‐macro) level or within a trap‐invoked macro. Arguments are copied in _c_o_p_y _m_o_d_e onto a stack where they are available for reference. It is advisable to conceal string references (with an extra \\\\) to delay interpolation until argu‐ ment reference time. _7._4._D_i_v_e_r_s_i_o_n_s. Processed output may be diverted into a macro for purposes such as footnote processing (see Tutorial §T5) or deter‐ mining the horizontal and vertical size of some text for condi‐ tional changing of pages or columns. A single diversion trap may be set at a specified vertical position. The number regis‐ ters ddddnnnn and ddddllll respectively contain the vertical and horizontal size of the most recently ended diversion. Processed text that is diverted into a macro retains the vertical size of each of its lines when reread in _n_o_f_i_l_l mode regardless of the current _V. Constant‐spaced (ccccssss) or emboldened (bbbbdddd) text that is diverted can be reread correctly only if these modes are again or still in effect at reread time. One way to do this is to imbed in the diversion the appropriate ccccssss or bbbbdddd requests with the _t_r_a_n_s_p_a_r_e_n_t mechanism described in §10.6. Diversions may be nested and certain parameters and registers are associated with the current diversion level (the top non‐ diversion level may be thought of as the 0th diversion level). These are the diversion trap and associated macro, no‐space mode, the internally‐saved marked place (see mmmmkkkk and rrrrtttt), the current vertical place (....dddd register), the current high‐water text base‐ line (....hhhh register), and the current diversion name (....zzzz register). The current diversion level is available in the ....ddddiiiilllleeeevvvv register. A previous partially filled line is included when a diversion begins. A partially filled line at the end of a diversion is not included but becomes part of the surrounding diversion level. With the bbbbooooxxxx request, a previous partially filled line is not included. At the end of the diversion, this partially filled line is restored at the surrounding level, discarding any par‐ tially filled line from within the diversion. The behavior is otherwise the same as with a standard diversion. _7._5._T_r_a_p_s. Five types of trap mechanisms are available—page traps, output‐line traps, a single diversion trap, multiple diversion traps, and an input‐line‐count trap. Macro‐invocation traps may be planted using wwwwhhhh at any page position including the top. This trap position may be changed using cccchhhh. Trap positions at or below the bottom of the page have no effect unless or until moved to within the page or rendered effective by an increase in page length. Two traps may be planted at the _s_a_m_e position only by first planting them at different positions and then moving one of the traps; the first planted trap will conceal the second ‐ 47 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 unless and until the first one is moved (see Tutorial Examples §T5). If the first one is moved back, it again conceals the second trap. The macro associated with a page trap is automati‐ cally invoked when a line of text is output whose vertical size _r_e_a_c_h_e_s or _s_w_e_e_p_s _p_a_s_t the trap position. Reaching the bottom of a page springs the top‐of‐page trap, if any, provided there is a next page. The distance to the next trap position is available in the ....tttt register; if there are no traps between the current position and the bottom of the page, the distance returned is the distance to the page bottom. An output‐line trap is planted using the escape sequence \\\\PPPP_x, \\\\PPPP((((_x_x, or \\\\PPPP[[[[_x_x_x]]]]. It is converted to an internal character code that becomes part of the current text. When the line containing it has been physically output, the macro _x, _x_x, or _x_x_x, respec‐ tively, is invoked. A line may contain more than one output‐line trap; they are invoked in the order they appear. If a page trap becomes effective at the same point, it is invoked immediately after all output‐line traps. Output‐line traps are not invoked at the time they become part of a diversion. They can thus be used to determine e.g. the effective page number of the surround‐ ing text, even when it had originally been diverted on another page. A single macro‐invocation trap effective in the current diver‐ sion may be planted using ddddtttt. If another ddddtttt follows in the same diversion, the trap position is changed. Multiple traps may be planted in the current diversion using ddddwwwwhhhh and ddddcccchhhh. The ....tttt register works in a diversion; if there is no subsequent trap a _l_a_r_g_e distance is returned. For a description of input‐line‐ count traps, see iiiitttt below. _7._6._R_e_c_u_r_s_i_o_n. _t_r_o_f_f macros can be invoked recursively. In gen‐ eral, return information and arguments for macro calls are stored as _f_r_a_m_e_s on a _s_t_a_c_k. Since the size of the stack is limited by available memory, recursive calls cannot descend to arbitrary depths. To avoid consumption of large amounts of memory in case of endless loops, the depth is deliberately restricted further; the rrrreeeeccccuuuurrrrssssiiiioooonnnnlllliiiimmmmiiiitttt request allows to adjust that restriction. A macro call can be _t_a_i_l‐_r_e_c_u_r_s_i_v_e, that is, the re‐invocation of the current macro can occur in its last statement. _t_r_o_f_f can then replace the stack frame of the current macro instance with that of the following one, and the stack size remains con‐ stant. The depth of tail‐recursive macro calls is thus princi‐ pally unlimited, and is not artificially restricted by default. Since _t_r_o_f_f cannot determine the control character at the time the macro is executed in advance, the recursive macro call must not only be the last statement of a macro, but must actually occur in the last line for tail‐recursion elimination to become effective, although it may be prefixed by ....iiiiffff or ....eeeellll or followed by \\\\}}}}. _7._7._L_o_c_a_l _s_t_r_i_n_g_s. Strings, macros, and diversions are, once defined, normally accessible from any part of a _t_r_o_f_f program. Local strings, defined with llllddddssss, are accessible only within the currently executing macro instance, and are not inherited to macros invoked from them. When the currently executing macro terminates, they are automatically deleted, and all associated ‐ 48 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 storage is reclaimed. As long as a local string named _x_x exists, any reference with \\\\((((_x_x or \\\\[[[[_x_x]]]] retrieves the value of the local string; the global string _x_x, if any, becomes inaccessible by this method. Calls to aaaassss, ssssuuuubbbbssssttttrrrriiiinnnngggg, iiiinnnnddddeeeexxxx, and cccchhhhoooopppp modify the local string. wwwwaaaattttcccchhhh with the name of a local string as argument notifies on modifi‐ cations of the local string. rrrrmmmm removes a local string and pos‐ sibly makes a global string visible again, rrrrnnnn renames a local string to another local string, and aaaallllssss creates a local alias to a local string. It is not allowed to define local macros or diversions. Calls to ._x_x or ´´´´_x_x reference a global macro or diversion even if a local string _x_x exists. Traps and the \\\\YYYY escape sequence always operate on global macros or diversions. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....ddddeeee _x_x _y_y – ._y_y=........ –Define or redefine the macro _x_x. The contents of the macro begin on the next input line. Input lines are copied in _c_o_p_y _m_o_d_e until the definition is terminated by a line beginning with ...._y_y, whereupon the macro _y_y is called. In the absence of _y_y, the definition is terminated by a line beginning with "........". A macro may contain ddddeeee requests pro‐ vided the terminating macros differ or the contained definition termina‐ tor is concealed. "........" can be con‐ cealed as \\\\\\\\........ which will copy as \\\\........ and be reread as "........". ....aaaammmm _x_x _y_y – ._y_y=........ –Append to macro (append version of ddddeeee). ....ddddssss _x_x _s_t_r_i_n_g – ignored–Define a string _x_x containing _s_t_r_i_n_g. Any initial double‐quote in _s_t_r_i_n_g is stripped off to permit initial blanks. ....aaaassss _x_x _s_t_r_i_n_g – ignored–Append _s_t_r_i_n_g to string _x_x (append version of ddddssss). ....llllddddssss _x_x _s_t_r_i_n_g – ignored–Define local string _x_x containing _s_t_r_i_n_g. Equivalent to ddddssss at the top non‐macro level. ....ssssuuuubbbbssssttttrrrriiiinnnngggg _x_x _N [_M] _M=−1 – Replace string _x_x by its sub‐ string between indices _N and _M. _N and _M start at 0. Negative values are interpreted relative to the end of the string; −1 implies the last character of the string. ....lllleeeennnnggggtttthhhh _R _s_t_r_i_n_g _R set to 0–Store the length of _s_t_r_i_n_g in register _R. _s_t_r_i_n_g is read in _c_o_p_y _m_o_d_e. ....iiiinnnnddddeeeexxxx _R _x_x _s_t_r_i_n_g ignored–Store the position of the first occurence of _s_t_r_i_n_g in _x_x in regis‐ ter _R. Positions are counted from ‐ 49 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 0. If no occurence is found, _R is set to -1. _s_t_r_i_n_g is read in _c_o_p_y _m_o_d_e. ....cccchhhhoooopppp _x_x – ignored–Remove the last character of the macro, string, or diversion _x_x. ....rrrrmmmm _x_x – ignored – Remove request, macro, or string. The name _x_x is removed from the name list and any related storage space is freed. Subsequent refer‐ ences will have no effect. If many macros and strings are being created dynamically, it may become necessary to remove unused ones to recapture internal storage space for newer registers. If a macro is removed while it is in use, associ‐ ated storage is not released, and a warning of the mmmmaaaacccc category is emit‐ ted. rrrrmmmm may have an unlimited number of arguments. However for creating portable documents only one argument to rrrrmmmm should be used. ....rrrrnnnn _x_x _y_y – ignored–Rename request, macro, or string _x_x to _y_y. If _y_y exists, it is first removed. ....ddddiiii _x_x – end D Divert output to macro _x_x. Normal text processing occurs during diver‐ sion except that page offsetting is not done. The diversion ends when the request ddddiiii or ddddaaaa is encoun‐ tered without an argument; extrane‐ ous requests of this type should not appear when nested diversions are being used. ....ddddaaaa _x_x – end D Divert, appending to _x_x (append ver‐ sion of ddddiiii). ....bbbbooooxxxx _x_x – end D Divert output to macro _x_x, excluding a partially filled line. ....bbbbooooxxxxaaaa _x_x – end D Divert and append to _x_x, excluding a partially filled line. ....uuuunnnnffffoooorrrrmmmmaaaatttt _x_x – ignored–Strip line break information from diversion _x_x. All breaks that do not result in explicit verti‐ cal movement are discarded, inter‐ word spaces that had been con‐ verted to horizontal movements dur‐ ing adjustment become space char‐ acters again, the effects of tabu‐ lators and field characters are reverted, and hyphenated word parts are combined again. ....aaaasssscccciiiiiiiiffffyyyy _x_x – ignored–All characters in diversion _x_x changed to plain text. Has all ‐ 50 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 effects described for uuuunnnnffffoooorrrrmmmmaaaatttt and additionally discards font and point size information and splits substi‐ tuted ligatures to their individual characters. ....wwwwhhhh _N _x_x – – vvvv Install a trap to invoke _x_x at page position _N; a _n_e_g_a_t_i_v_e _N will be interpreted with respect to the page _b_o_t_t_o_m. Any macro previously planted at _N is replaced by _x_x. A zero _N refers to the _t_o_p of a page. In the absence of _x_x, the first found trap at _N, if any, is removed. ....cccchhhh _x_x _N – – vvvv Change the trap position for macro _x_x to be _N. In the absence of _N, the trap, if any, is removed. ....ddddwwwwhhhh _N _x_x – – D,vvvvSet location trap in current diversion. Diversion traps planted with ddddtttt are not affected; if both a ddddwwwwhhhh and a ddddtttt trap are set at the same position, both are effec‐ tive. A ddddwwwwhhhh trap previously set at the same position is replaced. At the top non‐diversion level, it is equivalent to wwwwhhhh. Otherwise with a negative or zero _N, the trap will never be invoked since a diversion has no bottom and can never reach its top again. ....ddddcccchhhh _x_x _N – – D,vvvvChange trap location in current diversion; equivalent to cccchhhh at the top non‐diversion level. ....ddddtttt _N _x_x – off D,vvvvInstall a diversion trap at posi‐ tion _N in the _c_u_r_r_e_n_t diversion to invoke macro _x_x. Another ddddtttt will redefine the diversion trap. If no arguments are given, the diversion trap is removed. ....vvvvpppptttt _N 1 ignored – Enable (_N≠0) or disable (_N=0) page ejections and vertical position traps, i.e. those set with wwwwhhhh or ddddtttt. At end of input, the page is force‐ fully ejected. The number register ....vvvvpppptttt holds the current setting. ....iiiitttt _N _x_x – off E Set an input‐line‐count trap to invoke the macro _x_x after _N lines of _t_e_x_t input have been read (con‐ trol or request lines don’t count). The text may be in‐line text or text interpolated by inline or trap‐ invoked macros. ....iiiittttcccc _N _x_x – off E Set an input‐line‐count trap like iiiitttt, but ignore line interruptions with \\\\cccc when counting lines. ‐ 51 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ....rrrreeeettttuuuurrrrnnnn – – – Immediately return from the current macro to the level above. ....sssshhhhiiiifffftttt _N – 1 – Shift the arguments to the current macro by _N. ....aaaallllssss _y_y _x_x – – – _y_y is created as an alias for the request, macro, or string _x_x. The alias name is in every respect identical to the original name. If _x_x is removed or renamed, _y_y contin‐ ues to refer to the object at the time the alias had been created (and vice‐versa). If either _x_x or _y_y are redefined, both refer to the new definition. ....bbbbllllmmmm _x_x none none – Whenever a blank line is encoun‐ tered, the macro _x_x is invoked instead of the default behavior to output a blank line. ....eeeemmmm _x_x none none – The macro _x_x will be invoked when all input has ended. The effect is the same as if the contents of _x_x had been at the end of the last file processed, but all processing ceases at the next page eject. ....rrrreeeeccccuuuurrrrssssiiiioooonnnnlllliiiimmmmiiiitttt _N _M – – Set the maximum stack depth for generally recursive invocations of macros to _N, and for invocations of tail‐recursive macros to _M. If _N or _M are zero, the respective depth is unlimited. The default is 512 for the general case, and no limit for tail‐recursion. 8888.... NNNNuuuummmmbbbbeeeerrrr RRRReeeeggggiiiisssstttteeeerrrrssss A variety of parameters are available to the user as predefined, named _n_u_m_b_e_r _r_e_g_i_s_t_e_r_s (see Summary and Index, page 7). In addition, the user may define his own named registers. Regis‐ ter names are one or two characters long and _d_o _n_o_t conflict with request, macro, or string names. Except for certain prede‐ fined read‐only registers, a number register can be read, writ‐ ten, automatically incremented or decremented, and interpolated into the input in a variety of formats. One common use of user‐defined registers is to automatically number sections, para‐ graphs, lines, etc. A number register may be used any time numerical input is expected or desired and may be used in numeri‐ cal _e_x_p_r_e_s_s_i_o_n_s (§1.4). Number registers are created and modified using nnnnrrrr, which specifies the name, numerical value, and the auto‐increment size. Registers are also modified, if accessed with an auto‐ incrementing sequence. If the registers _x and _x_x both con‐ tain _N and have the auto‐increment size _M, the following access sequences have the effect shown: ‐ 52 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ─┌──────────┬──────────────────────┬──────────────┐ │ │ Effect on │ Value │ │Sequence │ Register │Interpolated │ ─├──────────┼──────────────────────┼──────────────┤ │\\\\nnnn_x │ none │ _N │ │\\\\nnnn((((_x_x │ none │ _N │ │\\\\nnnn[[[[_x_x_x]]]] │none │ _N │ │\\\\nnnn++++_x │_x incremented by _M │ _N+_M │ │\\\\nnnn----_x │_x decremented by _M │ _N-_M │ │\\\\nnnn++++((((_x_x │_x_x incremented by _M │ _N+_M │ │\\\\nnnn----((((_x_x │_x_x decremented by _M │ _N-_M │ │\\\\nnnn++++[[[[_x_x_x]]]] │_x_x_x incremented by _M │ _N+_M │ │\\\\nnnn----[[[[_x_x_x]]]] │_x_x_x decremented by _M │ _N-_M │ ─└──────────┴──────────────────────┴──────────────┘ Floating‐point registers can be created and modified using nnnnrrrrffff. They share a common name space with integer registers; a nnnnrrrr request turns a floating‐point register into an integer register. Access and auto‐increment are as with integer registers. When interpolated, a number register is converted to decimal (default), decimal with leading zeros, lower‐case Roman, upper‐ case Roman, lower‐case sequential alphabetic, or upper‐case sequential alphabetic according to the format specified by aaaaffff. Local number registers can be created and modified using llllnnnnrrrr and llllnnnnrrrrffff. Like local strings, local registers are accessible only within the currently executing macro instance, are not inherited to macros invoked from them, and are deleted when the current macro returns. The existence of a local number register _x_x makes the glo‐ bal number register _x_x, if any, completely inaccessible. The sequences \\\\nnnn((((_x_x and \\\\nnnn[[[[_x_x]]]] retrieve the value of the local regis‐ ter, \\\\RRRR’_x_x...’, \\\\nnnn++++((((_x_x and \\\\nnnn++++[[[[_x_x]]]] (and likewise) modify it, and \\\\gggg((((_x_x and \\\\gggg[[[[_x_x]]]] retrieve its format. Subsequent calls to nnnnrrrr, nnnnrrrrffff, aaaaffff, lllleeeennnnggggtttthhhh, and iiiinnnnddddeeeexxxx with _x_x as argument modify the local register. wwwwaaaattttcccchhhhnnnn notifies on modifications of the local regis‐ ter. rrrrrrrr removes a local register and possibly makes a global register visible again, rrrrnnnnnnnn renames a local register to another local register, and aaaallllnnnn creates a local alias to a local regis‐ ter. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....nnnnrrrr _R ±_N _M – uuuu The number register _R is assigned the value ±_N with respect to the previous value, if any. The incre‐ ment for auto‐incrementing is set to _M. An alternate syntax is available with the \\\\RRRR´_R ±_N´ escape sequence. ....nnnnrrrrffff _R ±_F _G – uuuu The floating‐point register _R is assigned the value ±_F with respect to the previous value, if any. Com‐ parison computations in the expres‐ sion _F are performed using floating‐ point values. The increment for auto‐incrementing, which also is a ‐ 53 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 floating‐point value, is set to _G. ....llllnnnnrrrr _R ±_N _M – uuuu Define and set local number regis‐ ter _R. ....llllnnnnrrrrffff _R ±_F _G – uuuu Define and set local floating‐ point register _R. ....aaaaffff _R _c arabic – – Assign format _c to register _R. The available formats are: ─┌────────┬───────────────────────────────────┐ │ │ Numbering │ │Format │ Sequence │ ─├────────┼───────────────────────────────────┤ │ 1111 │0,1,2,3,4,5,... │ │ 000000001111 │000,001,002,003,004,005,... │ │ iiii │0,i,ii,iii,iv,v,... │ │ IIII │0,I,II,III,IV,V,... │ │ aaaa │0,a,b,c,...,z,aa,ab,...,zz,aaa,... │ │ AAAA │0,A,B,C,...,Z,AA,AB,...,ZZ,AAA,... │ ─└────────┴───────────────────────────────────┘ An arabic format having _N digits specifies a field width of _N digits (example 2 above). The read‐ only registers, the _w_i_d_t_h function (§11.2), and floating‐point regis‐ ters are always arabic. Warning: the value of a number register in a non‐Arabic format is not numeric, and will not produce the expected results in expressions. The function \\\\gggg_x, \\\\gggg((((_x_x, or \\\\gggg[[[[_x_x_x]]]] returns the format of a number register in a form suitable for aaaaffff; it returns nothing if the register has not been used. ....rrrrrrrr _R – ignored – Remove register _R. If many regis‐ ters are being created dynamically, it may become necessary to remove no longer used registers to recapture internal storage space for newer registers. The register ....RRRR contains the number of number registers still available. rrrrrrrr may have an unlimited number of arguments. However for creating portable documents only one argument to rrrrrrrr should be used. ....rrrrnnnnnnnn _R _S – – – Rename register _R to _S. If _S exists, it is first removed. ....aaaallllnnnn _S _R – – – Register _S is created as an alias for _R. The alias name is in every respect identical to the original name. If _R is removed or renamed, _S continues to refer to the regis‐ ‐ 54 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ter at the time the alias had been created (and vice‐versa). A change in value or format in _R affects _S and vice‐versa. 9999.... TTTTaaaabbbbssss,,,, LLLLeeeeaaaaddddeeeerrrrssss,,,, aaaannnndddd FFFFiiiieeeellllddddssss _9._1._T_a_b_s _a_n_d _l_e_a_d_e_r_s. The ASCII horizontal tab character and the ASCII SOH (hereafter known as the _l_e_a_d_e_r character) can both be used to generate either horizontal motion or a string of repeated characters. The length of the generated entity is governed by internal _t_a_b _s_t_o_p_s specifiable with ttttaaaa. The default differ‐ ence is that tabs generate motion and leaders generate a string of periods; ttttcccc and llllcccc offer the choice of repeated character or motion. There are three types of internal tab stops—_l_e_f_t adjust‐ ing, _r_i_g_h_t adjusting, and _c_e_n_t_e_r_i_n_g. In the following table, _D is the distance from the current position on the _i_n_p_u_t line (where a tab or leader was found) to the next tab stop, _n_e_x_t‐ _s_t_r_i_n_g consists of the input characters following the tab (or leader) up to the next tab (or leader) or end of line, and _W is the width of _n_e_x_t‐_s_t_r_i_n_g. ─┌──────────┬─────────────────────┬───────────────────────────┐ │ Tab │Length of motion or │ Location of │ │ type │repeated characters │ _n_e_x_t‐_s_t_r_i_n_g │ ─├──────────┼─────────────────────┼───────────────────────────┤ │ Left │ _D │Following _D │ │ Right │ _D-_W │Right adjusted within _D │ │Centered │ _D-_W/2 │Centered on right end of _D │ ─└──────────┴─────────────────────┴───────────────────────────┘ The length of generated motion is allowed to be negative, but that of a repeated character string cannot be. Repeated char‐ acter strings contain an integer number of characters, and any residual distance is prepended as motion. Tabs or leaders found after the last tab stop are ignored, but may be used as _n_e_x_t‐ _s_t_r_i_n_g terminators. Tabs and leaders are not interpreted in _c_o_p_y _m_o_d_e. \\\\tttt and \\\\aaaa always generate a non‐interpreted tab and leader respectively, and are equivalent to actual tabs and leaders in _c_o_p_y _m_o_d_e. _9._2._F_i_e_l_d_s. A _f_i_e_l_d is contained between a _p_a_i_r of _f_i_e_l_d _d_e_l_i_m_‐ _i_t_e_r characters, and consists of sub‐strings separated by _p_a_d_‐ _d_i_n_g indicator characters. The field length is the distance on the _i_n_p_u_t line from the position where the field begins to the next tab stop. The difference between the total length of all the sub‐strings and the field length is incorporated as horizon‐ tal padding space that is divided among the indicated padding places. The incorporated padding is allowed to be negative. For example, if the field delimiter is #### and the padding indicator is ^^^^, ####^^^^_x_x_x^^^^_r_i_g_h_t#### specifies a right‐adjusted string with the string _x_x_x centered in the remaining space. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....ttttaaaa _N_t ... 8n; 0.5i noneE,mmmmSet tab stops and types. ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽ ∗Register ....SSSS is available for compatibility with DWB. ‐ 55 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _t=RRRR, right adjusting; _t=CCCC, center‐ ing; _t absent, left adjusting. _t_r_o_f_f tab stops are preset every 0.5in.; _n_r_o_f_f every 0.8in. The stop values are separated by spaces, and a value preceded by ++++ is treated as an increment to the previous stop value. The ....SSSS register* and the ....ttttaaaabbbbssss register hold a string with the current tab stops in a form that is acceptable for the ttttaaaa request; it can thus be used to save and restore tab stops. ....ttttaaaa _M_v ... _N_w TTTT _A_t ... _Z_ua _N=0E,mmmmSet repeated tab stops and types at _M_v, ..., _N_w, _N + _A_t, ..., _N + _Z_u, _N + _Z + _A_t, ..., _N + _Z + _Z_u, _N + 2·_Z + _A_t, ..., _N + 2·_Z + _Z_u, _N + 3·_Z + _A_t, ..., _N + 3·_Z + _Z_u, ... . Thus ....ttttaaaa TTTT 0000....5555iiii sets tab stops every 0.5in, and ....ttttaaaa 1111iiii 4444iiii TTTT ....22225555iiii 1111iiii sets tab stops at 1in, 4in, 4.25in, 5in, 5.25in, 6in, 6.25in, etc. ....ttttcccc _c none none E The tab repetition character becomes _c, or is removed specifying motion. ....llllcccc _c .... none E The leader repetition character becomes _c, or is removed specifying motion. ....ffffcccc _a _b off off – The field delimiter is set to _a; the padding indicator is set to the _s_p_a_c_e character or to _b, if given. In the absence of arguments the field mechanism is turned off. 11110000.... IIIInnnnppppuuuutttt aaaannnndddd OOOOuuuuttttppppuuuutttt CCCCoooonnnnvvvveeeennnnttttiiiioooonnnnssss aaaannnndddd CCCChhhhaaaarrrraaaacccctttteeeerrrr TTTTrrrraaaannnnssssllllaaaattttiiiioooonnnnssss _1_0._1._I_n_p_u_t _c_h_a_r_a_c_t_e_r _t_r_a_n_s_l_a_t_i_o_n_s. Ways of inputting the graphic character set were discussed in §2.1. The ASCII control charac‐ ters horizontal tab (§9.1), SOH (§9.1), and e_backspace (§10.3) are discussed elsewhere. The newline delimits input lines. In addition, STX, ETX, ENQ, ACK, and BEL are accepted, and may be used as delimiters or translated into a graphic with ttttrrrr (§10.5). _A_l_l others are ignored. The _e_s_c_a_p_e character \\\\ introduces _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s—causes the following character to mean another character, or to indicate some function. A complete list of such sequences is given in the Summary. \\\\ should not be confused with the ASCII control character ESC of the same name. The escape character \\\\ can be output by using the special character \\\\((((rrrrssss. The escape char‐ acter can be changed with eeeecccc, and all that has been said about the default \\\\ becomes true for the new escape character. \\\\eeee can be used to print whatever the current escape character is; this escape sequence is interpreted in _c_o_p_y _m_o_d_e. \\\\EEEE evaluates to the current escape character but is not interpreted in _c_o_p_y _m_o_d_e; if it is put into a string or macro, it will introduce an escape sequence once the string is printed or the macro is executed, ‐ 56 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 respectively. eeeeccccssss and eeeeccccrrrr save and restore the escape character. If necessary or convenient, the escape mechanism may be turned off with eeeeoooo, and restored with eeeecccc. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....eeeecccc _c \\\\ \\\\ – Set escape character to \\\\, or to _c, if given. ....eeeeoooo on – – Turn escape mechanism off. ....eeeeccccssss \ – – Save escape character. ....eeeeccccrrrr \ – – Restore saved escape character. ....eeeessssccccooooffffffff _e_s_c ... on ignored–Disable escapes _e_s_c .... For example the request ....eeeessssccccooooffffffff ;;;; @@@@ would disable escapes \\\\;;;;, \\\\@@@@{{{{, and \\\\@@@@}}}}. The request had been added as a workaround for manual pages which by mistake escape normal charaters. At the moment only one‐character arguments are valid. This may change in future versions. ....eeeessssccccoooonnnn _e_s_c ... on ignored–Enable escapes _e_s_c .... _1_0._2._L_i_g_a_t_u_r_e_s. The set of available ligatures is device and font dependent, but is often a subset of ffffiiii, ffffllll, ffffffff, ffffffffiiii, and ffffffffllll. They may be input (even in _n_r_o_f_f) by \\\\((((ffffiiii, \\\\((((ffffllll, \\\\((((ffffffff, \\\\((((FFFFiiii, and \\\\((((FFFFllll respectively. In _t_r_o_f_f, the fffflllliiiigggg request specifies the set of ligatures available with an individual font. The ligature mode is normally on in _t_r_o_f_f, and _a_u_t_o_m_a_t_i_c_a_l_l_y invokes ligatures during input. At most the five named ligatures are enabled by default. The ligature suppressor \\\\;;;; disables automatic ligature building if it is placed between two characters, but has no other effects. Many other escape sequences, e.g. \\\\&&&&, \\\\%%%%, also disable automatic ligature building. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....llllgggg _N off; on on – Ligature mode is turned on if _N is absent or non‐zero, and turned off if _N=0. If _N=2, only the two‐character ligatures are automat‐ ically invoked. Ligature mode is inhibited for request, macro, string, register, or file names, and in _c_o_p_y _m_o_d_e. No effect in _n_r_o_f_f. ....fffflllliiiigggg _F _s_t_r_i_n_g _c ... ignoredTDefine the set of ligatures to be used with font _F. _s_t_r_i_n_g may con‐ sist of up to four characters; its exact occurences are substituted by the character _c whenever the current font is _F. If _s_t_r_i_n_g starts with a minus sign, ligature subtitution for it is disabled; the _c argument must not be present in this case. It is required that any substring of _s_t_r_i_n_g that consists of two or more characters is also defined as ‐ 57 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 a ligature. Multiple _s_t_r_i_n_g/_c pairs may be given. As a special case, ....fffflllliiiigggg _F 0000 disables all ligatures for font _F. The default set of liga‐ tures is specific to a font and is determined from its metrics file. As examples, ....fffflllliiiigggg RRRR TTTThhhh \\\\[[[[TTTT____hhhh]]]] enables a ligature for ‘‘Th’’ in font RRRR, and ....fffflllliiiigggg RRRR ----TTTThhhh disables it. ....ffffddddeeeeffffeeeerrrrlllliiiigggg _F _s_t_r_i_n_g ... ignoredTDefer ligature building for the first character of _s_t_r_i_n_g. Nor‐ mally when a sequence of three char‐ acters appears for which both the first and the last two characters are defined as a ligature, the liga‐ ture is built using the first two characters. For example, if ‘‘ffi’’ appears in input and both ‘‘ff’’ and ‘‘fi’’ are defined as ligatures, the ‘‘ff’’ ligature is built, followed by a single ‘‘i’’ character. Use of this request causes the ligature to be built using the second two char‐ acters, so in the example, ....ffffddddeeeeffffeeeerrrr‐‐‐‐ lllliiiigggg RRRR ffffffffiiii would result in a single ‘‘f’’ character followed by a ‘‘fi’’ ligature. _1_0._3._B_a_c_k_s_p_a_c_i_n_g, _u_n_d_e_r_l_i_n_i_n_g, _o_v_e_r_s_t_r_i_k_i_n_g, _e_t_c. Unless in _c_o_p_y _m_o_d_e, the ASCII backspace character is replaced by a back‐ ward horizontal motion having the width of the space character. Underlining as a form of line‐drawing is discussed in §12.4. A generalized overstriking function is described in §12.1. _n_r_o_f_f automatically underlines characters in the _u_n_d_e_r_l_i_n_e font, specifiable with uuuuffff, normally that on font position 2 (normally Times Italic, see §2.2). In addition to fffftttt and \\\\ffff_F, the under‐ line font may be selected by uuuullll and ccccuuuu. Underlining is res‐ tricted to an output‐device‐dependent subset of _r_e_a_s_o_n_a_b_l_e char‐ acters. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....uuuullll _N off _N=1 E Underline in _n_r_o_f_f (italicize in _t_r_o_f_f) the next _N input text lines. Actually, switch to _u_n_d_e_r_‐ _l_i_n_e font, saving the current font for later restoration; _o_t_h_e_r font changes within the span of a uuuullll will take effect, but the restoration will undo the last change. Output generated by ttttllll (§14) _i_s affected by the font change, but does _n_o_t decre‐ ment _N. If _N>1, there is the risk that a trap interpolated macro may provide text lines within the span; environment switching can prevent ‐ 58 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 this. ....ccccuuuu _N off _N=1 E Continuous underline. A variant of uuuullll that causes _e_v_e_r_y character to be underlined in _n_r_o_f_f. Identical to uuuullll in _t_r_o_f_f. ....uuuuffff _F Italic Italic – Underline font set to _F. In _n_r_o_f_f, _F may _n_o_t be on position 1. _1_0._4._C_o_n_t_r_o_l _c_h_a_r_a_c_t_e_r_s. Both the control character .... and the _n_o‐ _b_r_e_a_k control character ´´´´ may be changed, if desired. Such a change must be compatible with the design of any macros used in the span of the change, and particularly of any trap‐invoked mac‐ ros. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....cccccccc _c .... .... E The basic control character is set to _c, or reset to "....". ....cccc2222 _c ´´´´ ´´´´ E The _n_o_b_r_e_a_k control character is set to _c, or reset to "´´´´". _1_0._5._O_u_t_p_u_t _t_r_a_n_s_l_a_t_i_o_n. One character can be made a stand‐in for another character using ttttrrrr. All text processing (e.g. charac‐ ter comparisons) takes place with the input (stand‐in) charac‐ ter which appears to have the width of the final character. The graphic translation occurs at the moment of output (including diversion). Text in a diversion is not translated again when it is output or rediverted unless the aaaasssscccciiiiiiiiffffyyyy request had been applied on it. A character can be substituted by an arbitrary sequence of char‐ acters, motions, drawing commands, etc. by means of the cccchhhhaaaarrrr request. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....ttttrrrr _a_b_c_d.... none – O Translate _a into _b, _c into _d, etc. If an odd number of characters is given, the last one will be mapped into the space character. To be consistent, a particular translation must stay in effect from _i_n_p_u_t to _o_u_t_p_u_t time. ....ttttrrrriiiinnnn _a_b_c_d.... none – O Translate _a into _b, _c into _d, etc. as with ttttrrrr, but when the aaaasssscccciiiiiiiiffffyyyy request is called, retranslate _b to _a, _d to _c, etc. in the diversion it is applied to. ....ttttrrrrnnnntttt _a_b_c_d.... none – O Translate _a into _b, _c into _d, etc. as with ttttrrrr, unless the output is written to a diversion in tran‐ sparent mode. ....ffffttttrrrr _F _a_b_c_d.... none – P,TFont‐specific ttttrrrr. If the current character originates from font _F, translate character _a into _b, _c into _d, etc. ....cccchhhhaaaarrrr _c _s_t_r_i_n_g ignored–Define character _c to _s_t_r_i_n_g. _s_t_r_i_n_g is read in _c_o_p_y _m_o_d_e when the request is processed. ‐ 59 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 Whenever _c occurs in regular (not copy mode) later, a temporary copy of the current environment is created, the escape character is temporarily set to \, and _s_t_r_i_n_g is output in nofill mode to an unnamed diversion. If _c itself occurs in _s_t_r_i_n_g, no recursive substitution takes place, but the plain character _c is selected instead. The result‐ ing object continues to behave like the single character _c in the data stream, notionally retaining its font and character size properties. It can thus be part of a kerning definition, can be hyphenated (pos‐ sibly requiring an explicit hyphena‐ tion code to be assigned using the hhhhccccooooddddeeee request), can become the tab or leader character, and can be used for line drawing. Static letter space adjustments defined with the ttttrrrraaaacccckkkk request are applied to each but the last charac‐ ter inside the diversion, and to the object as a whole. Dynamic letter space adjustments defined with the lllleeeettttaaaaddddjjjj request are only applied to the object as a whole. No letter reshaping is performed on either the object or the contents of the diver‐ sion. If both ttttrrrr and cccchhhhaaaarrrr are defined for a character _c, ttttrrrr becomes effective first and changes _c to the trans‐ lation defined, but if _c is the result of ttttrrrr and cccchhhhaaaarrrr is defined for it, cccchhhhaaaarrrr is applied. ffffttttrrrr has no effect on characters for which cccchhhhaaaarrrr is defined. Both ttttrrrr and ffffttttrrrr are applied to characters inside the cccchhhhaaaarrrr diversion as usual. At the time _c would have been out‐ put, the contents of the diversion are printed instead of it. ....ffffcccchhhhaaaarrrr _c _s_t_r_i_n_g ignored T Define character _c to _s_t_r_i_n_g as a fallback only: If _c is present in the current font, output _c, other‐ wise, output _s_t_r_i_n_g as with cccchhhhaaaarrrr. ....rrrrcccchhhhaaaarrrr _c... ignored–Remove character definitions for _c...; applies to both cccchhhhaaaarrrr and ffffcccchhhhaaaarrrr. ....uuuuttttffff8888ccccoooonnnnvvvv _c_1 _c_2 ignored – _n_r_o_f_f only: With ----TTTTllllooooccccaaaalllleeee and a UTF‐8 locale, "‐" is replaced by a ‐ 60 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 UTF‐8 hyphen, and "\\\\‐" remains the ASCII hyphen‐minus character. This is because in manual pages, "\\\\----" represents the ASCII option intro‐ duction character, and converting it to a UTF‐8 minus character would make it impossible to copy‐and‐paste option descriptions. Similar con‐ siderations apply to ` ' vs. \` \'. The former are typographic sin‐ gle quotes, while the latter are commonly used for the ASCII syntax quotes in manual pages. By use of uuuuttttffff8888ccccoooonnnnvvvv the three default translations can be redefined and additional translations can be done. If _c_2 is missing a translation is removed. This is applied for manual pages where the no translation is used. _1_0._6._T_r_a_n_s_p_a_r_e_n_t _t_h_r_o_u_g_h_p_u_t. An input line beginning with a \\\\!!!! is read in _c_o_p_y _m_o_d_e and _t_r_a_n_s_p_a_r_e_n_t_l_y output (without the ini‐ tial \\\\!!!!); the text processor is otherwise unaware of the line’s presence. This mechanism may be used to pass control information to a post‐processor or to imbed control lines in a macro created by a diversion. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....oooouuuuttttppppuuuutttt _s_t_r_i_n_g ignored–Write _s_t_r_i_n_g directly to inter‐ mediate output, regardless of whether there is a current diver‐ sion or not. _s_t_r_i_n_g is read in copy mode, and an initial double‐quote is discarded. _1_0._7._T_r_a_n_s_p_a_r_e_n_t _o_u_t_p_u_t. The sequence \\\\XXXX´_a_n_y_t_h_i_n_g´ copies _a_n_y_‐ _t_h_i_n_g to the _t_r_o_f_f output, as a device control function in the form xxxx XXXX _a_n_y_t_h_i_n_g (§26). Escape sequences in _a_n_y_t_h_i_n_g are pro‐ cessed. The sequence \\\\YYYY_x, \\\\YYYY((((_x_x, or \\\\YYYY[[[[_x_x_x]]]] copies the con‐ tents of the string or macro _x, _x_x, or _x_x_x,, respectively, to the output as a device control function without processing escape sequences. Newlines in the macro are embedded in the output. _n_r_o_f_f discards transparent output sequences and their contents. _1_0._8._C_o_m_m_e_n_t_s _a_n_d _c_o_n_c_e_a_l_e_d _n_e_w_l_i_n_e_s. An uncomfortably long input line that must stay one line (e.g. a string definition, or nofilled text) can be split into many physical lines by ending all but the last one with the escape \\\\. The sequence \\\\(newline) is _a_l_w_a_y_s ignored—except in a comment. Comments may be imbedded at the _e_n_d of any line by prefacing them with \\\\"""". This form does not conceal the newline at the end of the comment. A line begin‐ ning with \\\\"""" will appear as a blank line and behave like ....sssspppp 1111; a comment can be on a line by itself by beginning the line with ....\\\\"""". The form \\\\#### includes the newline as part of the comment. It thus effectively acts like a concealed newline in concatenat‐ ing the following line immediately to the current line. ‐ 61 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 11111111.... LLLLooooccccaaaallll HHHHoooorrrriiiizzzzoooonnnnttttaaaallll aaaannnndddd VVVVeeeerrrrttttiiiiccccaaaallll MMMMoooottttiiiioooonnnnssss,,,, aaaannnndddd tttthhhheeee WWWWiiiiddddtttthhhh FFFFuuuunnnncccc‐‐‐‐ t1_ttti1_iiio.ooon1_nnn._L_o_c_a_l _M_o_t_i_o_n_s. The functions \\\\vvvv´´´´_N´´´´ and \\\\hhhh´´´´_N´´´´ can be used tftttioiiiorooonnnn _l_o_c_a_l vertical and horizontal motion respectively. The dis‐ tance _N may be negative; the _p_o_s_i_t_i_v_e directions are _r_i_g_h_t_w_a_r_d and _d_o_w_n_w_a_r_d. A _l_o_c_a_l motion is one contained _w_i_t_h_i_n a line. To avoid unexpected vertical dislocations, it is necessary that the _n_e_t vertical local motion within a word in filled text and otherwise within a line balance to zero. The above and certain other escape sequences providing local motion are summarized in the following table.* ─┌──────────────┬────────────────────────╥──────────────┬─────────────────────────────┐ │ Vertical │ Effect in ║ Horizontal │ Effect in │ │Local Motion │ _t_r_o_f_f _n_r_o_f_f ║Local Motion │ _t_r_o_f_f _n_r_o_f_f │ ─├──────────────┼────────────────────────╫──────────────┼─────────────────────────────┤ ││ \\\\vvvv´´´´_N´´´´ ││Move distance _N ║║ \\\\hhhh´´´´_N´´´´ ││Move distance _N ││ │├───────────────│┼───────────────────────║ \\\\(space) │Unpaddable space‐size space │ │ │ │ ║ \\\\∼∼∼∼ │Paddable no‐break space │ │ \\\\uuuu │½ em up │½ line up ║ \\\\0000 │Digit‐size space │ │ \\\\dddd │½ em down │½ line down ║╟───────────────│┼─────────────────────────────│ │ \\\\rrrr │1 em up │1 line up ║ \\\\|||| │1/6 em space │ignored │ │ │ │ ║ \\\\^^^^ │1/12 em space │ignored │ ─└──────────────┴───────────┴─────────────╨──────────────┴────────────────────┴─────────┘ As an example, EEEE2222 could be generated by the sequence EEEE\\\\ssss----2222\\\\vvvv´´´´----0000....4444mmmm´´´´2222\\\\vvvv´´´´0000....4444mmmm´´´´\\\\ssss++++2222; note that the 0.4 em vertical motions are at the smaller size. _1_1._2._W_i_d_t_h _F_u_n_c_t_i_o_n. The _w_i_d_t_h function \\\\wwww´´´´_s_t_r_i_n_g´´´´ generates the numerical width of _s_t_r_i_n_g (in basic units). Size and font changes may be safely imbedded in _s_t_r_i_n_g, and will not affect the current environment. For example, ....ttttiiii ----\\\\wwww´´´´\\\\ffffBBBB1111.... ´´´´uuuu could be used to temporarily indent leftward a distance equal to the size of the string "1111.... " in font BBBB. The width function also sets five number registers. The regis‐ ters sssstttt and ssssbbbb are set respectively to the highest and lowest extent of _s_t_r_i_n_g relative to the baseline; then, for example, the total _h_e_i_g_h_t of the string is \\\\nnnn((((ssssttttuuuu----\\\\nnnn((((ssssbbbbuuuu. The registers rrrrsssstttt and rrrrssssbbbb are set respectively to the highest and lowest visual extent of _s_t_r_i_n_g relative to the baseline, i.e. to the maximum and minimum extent of the _y value of any bounding box of the characters in _s_t_r_i_n_g. In _t_r_o_f_f the number register cccctttt is set to a value between 0 and 3: 0 means that all of the characters in _s_t_r_i_n_g were short lower case characters without descenders (like eeee); 1 means that at least one character has a descender (like yyyy); 2 means that at least one character is tall (like HHHH); and 3 means that both tall characters and characters with descenders are present. The ....wwww number register contains the width of the previous char‐ acter independently of the width function. Similarly, the ....cccchhhhtttt and ....ccccddddpppp registers are set respectively to the highest and lowest visual extent of the previous character relative to the baseline. _1_1._3._M_a_r_k _h_o_r_i_z_o_n_t_a_l _p_l_a_c_e. The escape sequence \\\\kkkk_x will cause ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽ ∗The line drawing escapes \l and \L also cause local motions. ‐ 62 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 the _c_u_r_r_e_n_t horizontal position in the _i_n_p_u_t _l_i_n_e to be stored in register _x. As an example, the construction \\\\kkkkxxxx_w_o_r_d\\\\hhhh´´´´||||\\\\nnnnxxxxuuuu++++3333uuuu´´´´_w_o_r_d will embolden _w_o_r_d by backing up to almost its beginning and overprinting it, resulting in _w_w_o_o_r_r_d_d. Likewise, \\\\kkkk((((_x_x and \\\\kkkk[[[[_x_x_x]]]] will store the horizontal position in register _x_x or _x_x_x, respectively. The hhhhpppp number register also holds the current horizontal position in the input line. 11112222.... OOOOvvvveeeerrrrssssttttrrrriiiikkkkeeee,,,, BBBBrrrraaaacccckkkkeeeetttt,,,, LLLLiiiinnnneeee‐ddddrrrraaaawwwwiiiinnnngggg,,,, GGGGrrrraaaapppphhhhiiiiccccssss,,,, aaaannnndddd ZZZZeeeerrrroooo‐wwwwiiiiddddtttthhhh F1_FFFu2_uuun.nnnc1_ccct.tttiO_iiiov_ooone_nnnsr_sss_s_t_r_i_k_i_n_g. Automatically centered overstriking of up FtFFFuouuunnnncccctntttiiiiionooonennnssss characters is provided by the _o_v_e_r_s_t_r_i_k_e function \\\\oooo´´´´_s_t_r_i_n_g´´´´. The characters in _s_t_r_i_n_g overprinted with centers aligned; the total width is that of the widest character. _s_t_r_i_n_g may _n_o_t contain local vertical motion. As examples, \\\\oooo´´´´eeee\\\\´´´´´´´´ pro‐ duces e´´´´eee, and \\\\oooo´´´´\\\\((((mmmmoooo\\\\((((ssssllll´´´´ produces ∈////∈∈∈. _1_2._2._Z_e_r_o‐_w_i_d_t_h _c_h_a_r_a_c_t_e_r_s _a_n_d _s_t_r_i_n_g_s. The function \\\\zzzz_c will output _c without spacing over it, and can be used to produce left‐aligned overstruck combinations. As examples, \\\\zzzz\\\\((((cccciiii\\\\((((ppppllll will produce ○++++○○○, and \\\\((((bbbbrrrr\\\\zzzz\\\\((((rrrrnnnn\\\\((((uuuullll\\\\((((bbbbrrrr will produce the smallest possible constructed box ││││‾____‾‾‾││││. The function \\\\ZZZZ’_s_t_r_i_n_g’ prints _s_t_r_i_n_g in nofill mode and restores the horizontal and vertical position afterwards. _1_2._3._L_a_r_g_e _B_r_a_c_k_e_t_s. The Special Font contains a number of bracket construction pieces (⎧⎩⎫⎭⎨⎬⎪⌊⌋⌈⌉) that can be combined into various bracket styles. The function \\\\bbbb´´´´_s_t_r_i_n_g´´´´ may be used to pile up vertically the characters in _s_t_r_i_n_g (the first charac‐ ter on top and the last at the bottom); the characters are vert‐ ically separated by 1 em and the total pile is centered 1/2em above the current baseline (½ line in _n_r_o_f_f). For example, \\\\bbbb´´´´\\\\((((llllcccc\\\\((((llllffff´´´´EEEE\\\\||||\\\\bbbb´´´´\\\\((((rrrrcccc\\\\((((rrrrffff´´´´\\\\xxxx´´´´----0000....5555mmmm´´´´\\\\xxxx´´´´0000....5555mmmm´´´´ produces ⌈⌈⌈⌈ ⌊⌊⌊⌊EEEE⌉⌉⌉⌉ ⌋⌋⌋⌋. _1_2._4._L_i_n_e _d_r_a_w_i_n_g. The function \\\\llll´´´´_N_c´´´´ (backslash‐ell) will draw a string of repeated _c’s towards the right for a distance _N. If _c looks like a continuation of an expression for _N, it may insu‐ lated from _N with a \\\\&&&&. If _c is not specified, the ⎽⎽⎽⎽ (base‐ line rule) is used (underline character in _n_r_o_f_f). If _N is nega‐ tive, a backward horizontal motion of size _N is made _b_e_f_o_r_e draw‐ ing the string. Any space resulting from _N/(size of _c) having a remainder is put at the beginning (left end) of the string. If _N is less than the width of _c, a single _c is centered on a distance _N. In the case of characters that are designed to be connected such as baseline‐rule ⎽⎽⎽⎽, underrule ____, and root‐ en ‾‾‾‾, the remainder space is covered by over‐lapping; the set of these characters can be customized with the ccccoooonnnnnnnneeeeccccttttcccchhhhaaaarrrr request described below. If _N is _l_e_s_s than the width of _c, a single _c is centered on a distance _N. As an example, a macro to underscore a string can be written ....ddddeeee uuuussss \\\\\\\\$$$$1111\\\\llll´´´´||||0000\\\\((((uuuullll´´´´ ........ or one to draw a box around a string ....ddddeeee bbbbxxxx \\\\((((bbbbrrrr\\\\||||\\\\\\\\$$$$1111\\\\||||\\\\((((bbbbrrrr\\\\llll´´´´||||0000\\\\((((rrrrnnnn´´´´\\\\llll´´´´||||0000\\\\((((uuuullll´´´´ ........ such that ....uuuussss """"uuuunnnnddddeeeerrrrlllliiiinnnneeeedddd wwwwoooorrrrddddssss"""" ‐ 63 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 and ....bbbbxxxx """"wwwwoooorrrrddddssss iiiinnnn aaaa bbbbooooxxxx"""" yield u_n_d_e_r_l_i_n_e_d__w_o_r_d_s_ and │_‾w_‾o_‾r_‾d_‾s_‾‾_i_‾n_‾‾_a_‾‾_b_‾o_‾x_‾│_‾. The function \\\\LLLL´´´´_N_c´´´´ draws a vertical line consisting of the (optional) character _c stacked vertically apart 1em (1 line in _n_r_o_f_f), with the first two characters overlapped, if necessary, to form a continuous line. The default character is the _b_o_x _r_u_l_e │ (\\\\((((bbbbrrrr); the other suitable character is the _b_o_l_d _v_e_r_t_i_c_a_l ⎪ (\\\\((((bbbbvvvv). The line is begun without any initial motion relative to the current base line. A positive _N specifies a line drawn down‐ ward and a negative _N specifies a line drawn upward. After the line is drawn _n_o compensating motions are made; the instantane‐ ous baseline is at the _e_n_d of the line. Motions of line drawing functions are local which means that the effect of these motions va_n_i_s_h_e_s__w_h_e_n__a__n_e_w__o_u_t_p_u_t__l_i_n_e__i_s__s_t_a_r_t_e_d_._________________________ T│he horizontal and vertical line drawing functions may be used in │ c│ombination to produce large boxes. The zero‐width _b_o_x‐_r_u_l_e and │ t│he ½‐em wide _u_n_d_e_r_r_u_l_e were _d_e_s_i_g_n_e_d to form corners when using │ 1│‐em vertical spacings. For example the macro │ │ ....ddddeeee eeeebbbb │ │ ....sssspppp ----1111 \\\\""""ccccoooommmmppppeeeennnnssssaaaatttteeee ffffoooorrrr nnnneeeexxxxtttt aaaauuuuttttoooommmmaaaattttiiiicccc bbbbaaaasssseeee‐lllliiiinnnneeee ssssppppaaaacccciiiinnnngggg │ │ ....nnnnffff \\\\""""aaaavvvvooooiiiidddd ppppoooossssssssiiiibbbbllllyyyy oooovvvveeeerrrrfffflllloooowwwwiiiinnnngggg wwwwoooorrrrdddd bbbbuuuuffffffffeeeerrrr │ │ \\\\hhhh´´´´----....5555nnnn´´´´\\\\LLLL´´´´||||\\\\\\\\nnnnaaaauuuu----1111´´´´\\\\llll´´´´\\\\\\\\nnnn((((....lllluuuu++++1111nnnn\\\\((((uuuullll´´´´\\\\LLLL´´´´----||||\\\\\\\\nnnnaaaauuuu++++1111´´´´\\\\llll´´´´||||0000uuuu----....5555nnnn\\\\(│(((uuuullll´´´´ \\\\""""ddddrrrraaaawwww bbbbooooxxxx │ ....ffffiiii │ │ ........ │ w│ill draw a box around some text whose beginning vertical place │ w│as saved in number register _a (e.g. using ....mmmmkkkk aaaa) as done for │ t_│h_i_s__p_a_r_a_g_r_a_p_h_._____________________________________________________│_ _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....ccccoooonnnnnnnneeeeccccttttcccchhhhaaaarrrr _c.. """"\\\\((((rrrruuuu\\\\((((uuuullll\o\\\(f(((rfrrrnEnnnConnected characters for line drawing. If there is a remainder to be drawn for a horizontal line, these characters are drawn over‐ lapping. The current set is avail‐ able in the ....ccccoooonnnnnnnneeeeccccttttcccchhhhaaaarrrr number register. _1_2._5._G_r_a_p_h_i_c_s. The function \\\\DDDD´_c...´ draws a graphic object of type _c according to a sequence of parameters, which are generally pairs of numbers. \\\\DDDD´´´´llll _d_h _d_v´ draw line from current position by _d_h,_d_v \\\\DDDD´´´´pppp _d_h_1 _d_v_1 _d_h_2 _d_v_2 ...´draw polygon, i.e. a line to _d_h_1,_d_v_1, then to _d_h_2,_d_v_2, then ... \\\\DDDD´´´´PPPP _d_h_1 _d_v_1 _d_h_2 _d_v_2 ...´draw filled polygon \\\\DDDD´´´´cccc _d´ draw circle of diameter _d with left side at current position \\\\DDDD´´´´CCCC _d´ draw filled circle \\\\DDDD´´´´eeee _u _v´ draw ellipse of diameters _u and _v \\\\DDDD´´´´EEEE _u _v´ draw filled ellipse \\\\DDDD´´´´aaaa _a _b _c _d´ draw arc from current position to _a+_c,_b+_d, with center at _a,_b from current position \\\\DDDD´´´´∼∼∼∼ _a _b _c _d...´draw B‐spline from current position by _a,_b, then by _c,_d, then by _c,_d, then ... For example,\\\\DDDD´´´´eeee0000....2222iiii 0000....1111iiii´´´´ draws the ellipse , and \\\\DDDD´´´´llll....2222iiii ----....1111iiii´´´´\\\\DDDD´´´´llll....1111iiii ....1111iiii´´´´ the line A \\\\DDDD with an unknown _c is processed and copied through to the output for unspecified interpretation; coordinates are interpreted alternately as horizontal and verti‐ cal values. ‐ 64 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 Numbers taken as horizontal (first, third, etc.) have default scaling of mmmm; vertical numbers (second, fourth, etc.) have default scaling of vvvv (§1.3). The position after a graphical object has been drawn is at its end; for circles and ellipses, the ‘‘end’’ is at the right side. 11113333.... HHHHyyyypppphhhheeeennnnaaaattttiiiioooonnnn.... Automatic hyphenation may be switched off and on. When switched on with hhhhyyyy, several variants may be set. A _h_y_p_h_e_n_a_t_i_o_n _i_n_d_i_c_a_t_o_r character, by default \\\\%%%%, may be imbedded in a word to specify desired hyphenation points, or may be prefixed to suppress hyphe‐ nation. The character \\\\:::: indicates that a line break may option‐ ally occur at a point, but that no hyphen is to be generated. In addition, the user may specify a small list of exception words. Only words that consist of a central alphabetic string surrounded by (usually null) non‐alphabetic strings are considered candi‐ dates for automatic hyphenation. Unless the set of optional line break characters is otherwise configured, words that contain hyphens (minus), em‐dashes (\\\\((((eeeemmmm), or hyphenation indicator char‐ acters are _a_l_w_a_y_s subject to splitting after those characters, whether automatic hyphenation is on or off. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....nnnnhhhh hyphenate – E Automatic hyphenation is turned off. ....hhhhyyyy _N on,_N=1 on,_N=1 E Automatic hyphenation is turned on for _N≥1, or off for _N=0. If _N=2, _l_a_s_t lines (ones that will cause a trap) are not hyphenated. For _N=4 and 8, the last and first two char‐ acters respectively of a word are not split off. For _N=16 and 32, the last and first characters respec‐ tively of a word are allowed to be split off; this is only effec‐ tive for explicit hyphenation points specified with \\\\%%%%, \\\\::::, or hhhhwwww. These values are additive; i.e. _N=14 will invoke the three restrictions. The current value is available in the ....hhhhyyyy number register. ....hhhhyyyyllllaaaannnngggg _n_a_m_e off off E Set the hyphenation language to _n_a_m_e, which is one of ddddeeee____DDDDEEEE, ddddeeee____DDDDEEEE@@@@ttttrrrraaaaddddiiiittttiiiioooonnnnaaaallll, eeeennnn____UUUUSSSS, ffffrrrr____FFFFRRRR, iiiitttt____IIIITTTT, llllaaaa____VVVVAAAA, or nnnnllll____NNNNLLLL. Other languages can be made available by adding hyphena‐ tion files to the directory ////uuuussssrrrr////uuuuccccbbbblllliiiibbbb////ddddooooccccttttoooooooollllssss////hhhhyyyypppphhhheeeennnn. If no _n_a_m_e argument is present, the hyphe‐ nation is reset to the traditional _t_r_o_f_f mechanism. The current value is available in the ....hhhhyyyyllllaaaannnngggg number register. This request also makes parts of ‐ 65 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 words composed by ‐ or \\\\((((eeeemmmm charac‐ ters subject to hyphenation, unless otherwise defined explicitly with the ....nnnnhhhhyyyycccchhhhaaaarrrr request. Tradition‐ ally, the only hyphenation points in such words had been the hyphens/dashes. ....sssshhhhcccc _c ‐ ‐ E Set the soft hyphenation character, i.e. the character that is inserted at the end of a hyphenated word. The current soft hyphenation charac‐ ter is available in the ....sssshhhhcccc number register. ....hhhhccccooooddddeeee _a_b_c_d... – E Hyphenation code. When determining the hyphenation points for an input word, _a is mapped to _b, etc. When no hyphenation code is specified for a character, it is mapped to its lower‐case variant if necessary, and the ‘‘long s’’ (\\\\[[[[lllloooonnnnggggssss]]]]) character is mapped to a ‘‘round s’’. ....hhhhyyyylllleeeennnn _N 5 5 E Hyphenate only words of at least _N characters in length. The current value is available in the ....hhhhyyyylllleeeennnn number register. ....hhhhllllmmmm _N off off E Maximum number of consecutive hyphenated lines. Each time a line is hyphenated automatically, the count of consecutive hyphenated lines (accessible in the ....hhhhllllcccc number register) is incremented; when‐ ever a line is not automatically hyphenated, it is reset to zero. This request allows to set a limit on the maximum number of consecutive hyphenated lines; when the count of consecutive lines has reached the maximum, the current line is not hyphenated. The default is no limit. The current value is acces‐ sible in the ....hhhhllllmmmm number register. ....hhhhyyyypppppppp _N _M _L 0 0 0 0 0 0 EDefine hyphenation penalties for aaaadddd pppp mode. Every inserted hyphen is given a penalty of _N when com‐ puting optimal break points; each hyphen that is followed by another hyphen gets an additional penalty of _M. A hyphen that is inserted in the last word of a paragraph gets an additional penalty of _L. A value of zero means no penalty. Effec‐ tive penalties correspond to values between 10 and 200. The current values are available in the ....hhhhyyyypppppppp, ‐ 66 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ....hhhhyyyypppppppp2222, and ....hhhhyyyypppppppp3333 number registers. ....bbbbrrrreeeeaaaakkkkcccchhhhaaaarrrr _c. ‐‐‐‐———— off E Optional line break characters. A line may always be split after one of these characters. The current set of optional line break charac‐ ters is available in the ....bbbbrrrreeeeaaaakkkkcccchhhhaaaarrrr number register. ....nnnnhhhhyyyycccchhhhaaaarrrr _c... ‐‐‐‐———— off E Hyphenation‐inhibiting characters. A word that contains one of the characters _c... is not hyphenated, except that it may be split across lines if one of these characters is also an optional line break character. The current set of hyphenation‐inhibiting characters is available in the ....nnnnhhhhyyyycccchhhhaaaarrrr number register. ....hhhhcccc _c \\\\%%%% \\\\%%%% E Hyphenation indicator character is set to _c or to the default \\\\%%%%. The indicator does not appear in the output. ....hhhhwwww _w_o_r_d_1 ... ignored–Specify hyphenation points in words with imbedded minus signs. Versions of a word with terminal _s are implied; i.e. _d_i_g-_i_t implies _d_i_g-_i_t_s. This list is examined ini‐ tially _a_n_d after each suffix strip‐ ping. 11114444.... TTTThhhhrrrreeeeeeee‐PPPPaaaarrrrtttt TTTTiiiittttlllleeeessss.... The titling function ttttllll provides for automatic placement of three fields at the left, center, and right of a line with a title‐ length specifiable with lllltttt. ttttllll may be used anywhere, and is independent of the normal text collecting process. A common use is in header and footer macros. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....ttttllll ´_l_e_f_t´_c_e_n_t_e_r´_r_i_g_h_t´ – – The strings _l_e_f_t, _c_e_n_t_e_r, and _r_i_g_h_t are respectively left‐ adjusted, centered, and right‐ adjusted in the current title‐ length. Any of the strings may be empty, and overlapping is permit‐ ted. If the page‐number character (initially %%%%) is found within any of the fields it is replaced by the current page number having the for‐ mat assigned to register %%%%. Any character may be used as the string delimiter. ....ppppcccc _c %%%% off – The page number character is set to _c, or removed. The page‐number register remains %%%%. ....lllltttt ±_N 6.5in previous E,mmmmLength of title set to ±_N. The line‐length and the title‐length are ‐ 67 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _i_n_d_e_p_e_n_d_e_n_t. Indents do not apply to titles; page‐offsets do. The current value is available in the ....lllltttt number register. 11115555.... OOOOuuuuttttppppuuuutttt LLLLiiiinnnneeee NNNNuuuummmmbbbbeeeerrrriiiinnnngggg.... Automatic sequence numbering of output lines may be requested with nnnnmmmm. When in effect, a three‐digit, arabic number plus 3 a digit‐space is prepended to output text lines. The text lines are thus offset by four digit‐spaces, and otherwise retain their line length; a reduction in line length may be 6 desired to keep the right margin aligned with an earlier mar‐ gin. Blank lines, other vertical spaces, and lines gen‐ erated by ttttllll are _n_o_t numbered. Numbering can be temporarily 9 suspended with nnnnnnnn, or with an ....nnnnmmmm followed by a later ....nnnnmmmm ++++0000. In addition, a line number indent _I, and the number‐text separation _S may be specified in digit‐spaces. Further, it 12 can be specified that only those line numbers that are mul‐ tiples of some number _M are to be printed (the others will appear as blank number fields). _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....nnnnmmmm ±_N _M _S _I off E Line number mode. If ±_N is given, line numbering is turned on, and the next output line numbered is numbered ±_N. Default values are _M=1, _S=1, and _I=0. Parameters corresponding to missing arguments are unaffected; a non‐numeric argu‐ ment is considered missing. In the absence of all arguments, numbering is turned off; the next line number is preserved for possible further use in number register llllnnnn. ....nnnnnnnn _N – _N=1 E The next _N text output lines are not numbered. 15 As an example, the paragraph portions of this section are numbered with _M=3: ....nnnnmmmm 1111 3333 was placed at the beginning; ....nnnnmmmm was placed at the end of the first paragraph; and ....nnnnmmmm ++++0000 was 18 placed in front of this paragraph; and ....nnnnmmmm finally placed at the end. Line lengths were also changed (by \\\\wwww´´´´0000000000000000´´´´uuuu) to keep the right side aligned. Another example is ....nnnnmmmm ++++5555 5555 xxxx 3333 21 which turns on numbering with the line number of the next line to be 5 greater than the last numbered line, with _M=5, with spacing _S untouched, and with the indent _I set to 3. 11116666.... CCCCoooonnnnddddiiiittttiiiioooonnnnaaaallll AAAAcccccccceeeeppppttttaaaannnncccceeee ooooffff IIIInnnnppppuuuutttt In the following, _c is a one‐character, built‐in _c_o_n_d_i_t_i_o_n name, !!!! signifies _n_o_t, _N is an integer numerical expression, _F is a floating‐point expression, _s_t_r_i_n_g_1 and _s_t_r_i_n_g_2 are strings delim‐ ited by any non‐blank, non‐numeric character _n_o_t in the strings, and _a_n_y_t_h_i_n_g represents what is conditionally accepted. ‐ 68 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....iiiiffff _c _a_n_y_t_h_i_n_g – – If condition _c true, accept _a_n_y_‐ _t_h_i_n_g as input; in multi‐line case use \{_a_n_y_t_h_i_n_g\}. ....iiiiffff !!!!_c _a_n_y_t_h_i_n_g – – If condition _c false, accept _a_n_y_‐ _t_h_i_n_g. ....iiiiffff _N _a_n_y_t_h_i_n_g – uuuu If expression _N > 0, accept _a_n_y_‐ _t_h_i_n_g. ....iiiiffff !!!!_N _a_n_y_t_h_i_n_g – uuuu If expression _N ≤ 0 [sic], accept _a_n_y_t_h_i_n_g. ....iiiiffff ffff_F _a_n_y_t_h_i_n_g – uuuu If floating‐point expression _F > 0, accept _a_n_y_t_h_i_n_g. ....iiiiffff !!!!ffff_F _a_n_y_t_h_i_n_g – uuuu If floating‐point expression _F ≤ 0 [sic], accept _a_n_y_t_h_i_n_g. ....iiiiffff ´_s_t_r_i_n_g_1´_s_t_r_i_n_g_2´ _a_n_y_t_h_i_n_g –If _s_t_r_i_n_g_1 identical to _s_t_r_i_n_g_2, accept _a_n_y_t_h_i_n_g. ....iiiiffff !!!!´_s_t_r_i_n_g_1´_s_t_r_i_n_g_2´ _a_n_y_t_h_i_n_g–If _s_t_r_i_n_g_1 not identical to _s_t_r_i_n_g_2, accept _a_n_y_t_h_i_n_g. ....iiiieeee _c _a_n_y_t_h_i_n_g – uuuu If portion of if‐else; all of the forms for iiiiffff above are valid. ....eeeellll _a_n_y_t_h_i_n_g – – Else portion of if‐else. ....wwwwhhhhiiiilllleeee _c _a_n_y_t_h_i_n_g – – Execute _a_n_y_t_h_i_n_g while _c is true; all of the forms for iiiiffff above are valid. _a_n_y_t_h_i_n_g is stored in an unnamed temporary macro each time a wwwwhhhhiiiilllleeee loop is prepared for execu‐ tion. In the multi‐line case, the \\\\}}}} ter‐ minating the loop must be placed at the end of a line. When _a_n_y_t_h_i_n_g is copied to the macro, neither copy mode nor regular escape interpretation apply. Refer‐ ences to number registers, strings, etc. must thus be written using a single escape character unless the wwwwhhhhiiiilllleeee request is contained in a macro definition. Nested loops will result in many macro definitions and may slow down execution, especially if their body is large. Recursive macros (§10.6) do not suffer from this problem. In contrast to recursive macro calls, there is no mechanism to terminate a loop automatically when a repetition limit has been reached. In case of doubt, an explicit limit termination condition should be added to prevent endless loops. ....bbbbrrrreeeeaaaakkkk _n – 1 – Break out of _n nested wwwwhhhhiiiilllleeee loops, or terminate the current loop if no argument is given. It is not ‐ 69 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 necessary that all of the loops are contained within the same macro; if there are any macros execut‐ ing inside the specified loop, con‐ trol also returns from these macros. In case of a non‐positive or non‐ numeric argument, _n=1 is assumed. If the number of levels requested is greater than the number of loops currently executing, control returns to the highest non‐looping level. ....ccccoooonnnnttttiiiinnnnuuuueeee _n – 1 – Continue at the _n‐th nested wwwwhhhhiiiilllleeee loop, or continue the current loop if no argument is given. Execu‐ tion resumes with the test of the specified wwwwhhhhiiiilllleeee loop; if this test fails, the request is effectively like bbbbrrrreeeeaaaakkkk. ccccoooonnnnttttiiiinnnnuuuueeee also returns from all inside macro calls until it has reached the specified loop. In case of a non‐positive or non‐ numeric argument, _n=1 is assumed. If the number of levels requested is greater than the number of loops currently executing, control returns to the highest non‐looping level, and no loop is continued. The built‐in condition names are: ‐ 70 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ─┌───────────┬─────────────────────────────────────────────┐ │Condition │ │ │ Name │ True if │ ─├───────────┼─────────────────────────────────────────────┤ │ cccc _G │Character _G exists in the current font, │ │ │where _G is either an ASCII or localized │ │ │input character, a _t_r_o_f_f special character │ │ │\\\\((((_x_x or \\\\[[[[_x_x_x]]]], or a \\\\UUUU´_X´ escape sequence │ │ dddd _x_x │There is a request, macro, or string _x_x │ │ rrrr _x_x │Number register _x_x has been accessed │ │ FFFF _f_o_n_t │Font named _f_o_n_t exists │ │ oooo │Current page number is odd │ │ eeee │Current page number is even │ │ tttt │Formatter is _t_r_o_f_f │ │ nnnn │Formatter is _n_r_o_f_f │ │ vvvv │Never. (vvvv is used by other roff variants.) │ ─└───────────┴─────────────────────────────────────────────┘ If the condition _c is _t_r_u_e, or if the number _N is greater than zero, or if the strings compare identically (including motions and character size and font), _a_n_y_t_h_i_n_g is accepted as input. If a !!!! precedes the condition, number, or string comparison, the sense of the acceptance is reversed. Any spaces between the condition and the beginning of _a_n_y_t_h_i_n_g are skipped over. The _a_n_y_t_h_i_n_g can be either a single input line (text, macro, or whatever) or a number of input lines. In the multi‐line case, the first line must begin with a left delimiter \\\\{{{{ and the last line must end with a right delimiter \\\\}}}}. The request iiiieeee (if‐else) is identical to iiiiffff except that the acceptance state is remembered. A subsequent and matching eeeellll (else) request then uses the reverse sense of that state. iiiieeee ‐ eeeellll pairs may be nested. Some examples are: ....iiiiffff eeee ....ttttllll ´´´´EEEEvvvveeeennnn PPPPaaaaggggeeee %%%%´´´´´´´´´´´´ which outputs a title if the page number is even; and ....iiiieeee \\\\nnnn%%%%>>>>1111 \\\\{{{{\\\\ ´´´´sssspppp 0000....5555iiii ....ttttllll ´´´´PPPPaaaaggggeeee %%%%´´´´´´´´´´´´ ´´´´sssspppp ||||1111....2222iiii \\\\}}}} ....eeeellll ....sssspppp ||||2222....5555iiii which treats page 1 differently from other pages. 11117777.... EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt SSSSwwwwiiiittttcccchhhhiiiinnnngggg.... A number of the parameters that control the text processing are gathered together into an _e_n_v_i_r_o_n_m_e_n_t, which can be switched by the user. The environment parameters are those associ‐ ated with requests noting E in their _N_o_t_e_s column; in addi‐ tion, partially collected lines and words are in the environment. Everything else is global; examples are page‐oriented parame‐ ters, diversion‐oriented parameters, number registers, and macro and string definitions. All environments are initialized with default parameter values. The number of possible environments is only limited by available memory. Inside each environment, a smaller set of parameters forms the _i_n_l_i_n_e _e_n_v_i_r_o_n_m_e_n_t. These are: the current and previous point ‐ 71 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 size, as set by ppppssss and \\\\ssss; the current and previous font, as set by fffftttt and \\\\ffff; the control and nobreak control character, as set by cccccccc and cccc2222, respectively; the optional hyphenation character, as set by hhhhcccc; the hyphenation flag, as set by hhhhyyyy; the tab and leader repetition characters, as set by ttttcccc and llllcccc, respectively; and the default line breaking penalty, as set by \\\\JJJJ. The inline environment is pushed by \\\\@@@@{{{{, meaning that the current values of these parameters are saved. When a \\\\@@@@}}}} occurs, the last pushed inline environment is popped, meaning that the previous values of the parameters are restored. Inline environments can be nested to arbitrary depths. They differ from \\\\ssss0000 and \\\\ffffPPPP since they form a stack. Thus, the current font is ‘‘B’’ again after the sequence ‘‘\fB...\@{\fR...\@{\fI...\@}...\@}’’, but ‘‘I’’ after the sequence ‘‘\fB...\fR...\fI...\fP...\fP’’. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....eeeevvvv _n_a_m_e _n_a_m_e=0 previous–Environment switched to environ‐ ment _n_a_m_e. Switching is done in push‐down fashion so that restor‐ ing a previous environment _m_u_s_t be done with ....eeeevvvv rather than specific reference. Note that what is pushed down and restored is the environment _n_a_m_e, not its contents. The name of the current environment is available in the ....eeeevvvv number register. ....eeeevvvvcccc _n_a_m_e – – Copy the environment _n_a_m_e to the current environment. The temporary state of the current environment is reset, and incompletely filled lines are discarded. 11118888.... IIIInnnnsssseeeerrrrttttiiiioooonnnnssss ffffrrrroooommmm tttthhhheeee SSSSttttaaaannnnddddaaaarrrrdddd IIIInnnnppppuuuutttt The input can be temporarily switched to the system _s_t_a_n_d_a_r_d _i_n_p_u_t with rrrrdddd, which will switch back when _t_w_o newlines in a row are found (the _e_x_t_r_a blank line is not used). This mechanism is intended for insertions in form‐letter‐like documentation. The _s_t_a_n_d_a_r_d _i_n_p_u_t can be the user’s keyboard, a _p_i_p_e, or a _f_i_l_e. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....rrrrdddd _p_r_o_m_p_t – _p_r_o_m_p_t=BEL–Read insertion from the stan‐ dard input until two newlines in a row are found. If the standard input is the user’s keyboard, _p_r_o_m_p_t (or a BEL) is written onto the user’s terminal. rrrrdddd behaves like a macro, and arguments may be placed after _p_r_o_m_p_t. ....eeeexxxx – – – Exit from _n_r_o_f_f/_t_r_o_f_f. Text pro‐ cessing is terminated exactly as if all input had ended. If insertions are to be taken from the terminal keyboard _w_h_i_l_e output is being printed on the terminal, the command line option ----qqqq will turn off the echoing of keyboard input and prompt only with BEL. The regular input and insertion input _c_a_n_n_o_t simul‐ ‐ 72 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 taneously come from the standard input. As an example, multiple copies of a form letter may be prepared by entering the insertions for all the copies in one file to be used as the standard input, and causing the file containing the letter to reinvoke itself using nnnnxxxx (§19); the process would ulti‐ mately be ended by an eeeexxxx in the insertion file. 11119999.... IIIInnnnppppuuuutttt////OOOOuuuuttttppppuuuutttt FFFFiiiilllleeee SSSSwwwwiiiittttcccchhhhiiiinnnngggg _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....ssssoooo _f_i_l_e_n_a_m_e – – Switch source file. The top input (file reading) level is switched to _f_i_l_e_n_a_m_e. When the new file ends, input is again taken from the ori‐ ginal file. It is a fatal error if _f_i_l_e_n_a_m_e cannot be opened. ssssoooo’s may be nested. ....ppppssssoooo _s_t_r_i_n_g – – Execute _s_t_r_i_n_g and read its stan‐ dard output as text input. ....nnnnxxxx _f_i_l_e_n_a_m_e end‐of‐file–Next file is _f_i_l_e_n_a_m_e. The current file is considered ended, and the input is immediately switched to _f_i_l_e_n_a_m_e. ....ssssyyyy _s_t_r_i_n_g – – Execute program from _s_t_r_i_n_g, which is the rest of the input line. The output is not collected automati‐ cally. The number register $$$$$$$$, which contains the process id of the _t_r_o_f_f process, may be useful in gen‐ erating unique filenames for output. ....ppppiiii _s_t_r_i_n_g – – Pipe output to _s_t_r_i_n_g, which is the rest of the input line. This request must occur _b_e_f_o_r_e any print‐ ing occurs; typically it is the first line of input. ....ccccffff _f_i_l_e_n_a_m_e – – Copy contents of file _f_i_l_e_n_a_m_e to output, completely unprocessed. The file is assumed to contain something meaningful to subsequent processes. ....ooooppppeeeennnn _s_t_r_e_a_m _f_i_l_e_n_a_m_e ignored–Open _f_i_l_e_n_a_m_e for writing while truncating existing contents and associates _s_t_r_e_a_m with it for latter use with wwwwrrrriiiitttteeee etc. ....ooooppppeeeennnnaaaa _s_t_r_e_a_m _f_i_l_e_n_a_m_e ignored–Like ooooppppeeeennnn but appends to _f_i_l_e_n_a_m_e instead of truncating an existing file. ....wwwwrrrriiiitttteeee _s_t_r_e_a_m _t_e_x_t ignored–Write _t_e_x_t to file _s_t_r_e_a_m, which must have been obtained by a previ‐ ous ooooppppeeeennnn request. _t_e_x_t is inter‐ preted in _c_o_p_y _m_o_d_e. ....wwwwrrrriiiitttteeeecccc _s_t_r_e_a_m _t_e_x_t ignored–Like wwwwrrrriiiitttteeee but does not write a terminating newline. ....wwwwrrrriiiitttteeeemmmm _s_t_r_e_a_m _x_x ignored–Write contents of string, macro, or diversion _x_x. No newline is appended, so if _x_x is a string, the ‐ 73 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 output does not terminate with a newline. ....cccclllloooosssseeee _s_t_r_e_a_m – – Close the file _s_t_r_e_a_m, which must have been obtained by a previous ooooppppeeeennnn request. 22220000.... MMMMiiiisssscccceeeellllllllaaaannnneeeeoooouuuussss The \\\\VVVV_x, \\\\VVVV((((_x_x, or \\\\VVVV[[[[_x_x_x]]]] escape sequence causes the value of the _x, _x_x, or _x_x_x environment variable, respectively, to be printed. It is interpreted in _c_o_p_y _m_o_d_e. _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....mmmmcccc _c _N – off E,mmmm Specifies that a _m_a_r_g_i_n character _c │ appear a distance _N to the right │ of the right margin after each non‐ │ empty text line (except those pro‐ │ duced by ttttllll). If the output line │ is too‐long (as can happen in nofill │ mode) the character will be appended │ to the line. If _N is not given, │ the previous _N is used; the initial │ _N is 0.2 inches in _n_r_o_f_f and 1em in │ _t_r_o_f_f. The margin character used │ with this paragraph was a 12‐point │ box‐rule. │ ....llllppppffffxxxx _s_t_r_i_n_g off off E Set the line prefix to _s_t_r_i_n_g. ‘‘‘‘Whenever a new output line is ‘‘started, _s_t_r_i_n_g is then printed at ‘‘its beginning. Font and size set‐ ‘‘tings as well as automatic liga‐ ‘‘tures in _s_t_r_i_n_g are retained ‘‘regardless of later changes. This ‘‘request is mainly useful to imple‐ ‘‘ment a historic form of block quo‐ ‘‘tation. The current value is ‘‘available in the ....llllppppffffxxxx register.’’ ....ttttmmmm _s_t_r_i_n_g – newline–After skipping initial blanks, _s_t_r_i_n_g (rest of the line) is read in _c_o_p_y _m_o_d_e and written on the stan‐ dard error. ....ttttmmmmcccc _s_t_r_i_n_g – newline–Like ttttmmmm but does not write a ter‐ minating newline. ....nnnnoooopppp _r_e_m_a_i_n_d_e_r _o_f _l_i_n_e – – Use _r_e_m_a_i_n_d_e_r _o_f _l_i_n_e as input. ....cccchhhhoooommmmpppp _r_e_m_a_i_n_d_e_r _o_f _l_i_n_e – –Use _r_e_m_a_i_n_d_e_r _o_f _l_i_n_e _w_i_t_h_o_u_t _n_e_w_l_i_n_e as input. ....aaaabbbb _s_t_r_i_n_g – newline–After skipping initial blanks, _s_t_r_i_n_g (rest of the line) is read in _c_o_p_y _m_o_d_e and written on the stan‐ dard error. _t_r_o_f_f or _n_r_o_f_f then exit. ....iiiigggg _y_y – ._y_y=........ – Ignore input lines. iiiigggg behaves exactly like ddddeeee (§7) except that the input is discarded. The input is read in _c_o_p_y _m_o_d_e, and any auto‐incremented registers will be ‐ 74 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 affected. ....llllffff _N _f_i_l_e_n_a_m_e – – Set line number to _N and filename to _f_i_l_e_n_a_m_e for purposes of sub‐ sequent error messages, etc. The number register [sic] ....FFFF contains the name of the current input file, as set by command line arguments, ssssoooo, nnnnxxxx, or llllffff. The number regis‐ ter ....cccc contains the number of input lines read from the current file, again perhaps as modified by llllffff. ....ppppmmmm _t – all – Print macros. The names and sizes of all of the defined macros and strings are printed on the standard error; if _t is given, only the total of the sizes is printed. The sizes is given in _b_l_o_c_k_s of 128 charac‐ ters. ....ffffllll – – B Flush output buffer. Force out‐ put, including any pending position information. 22221111.... OOOOuuuuttttppppuuuutttt aaaannnndddd EEEErrrrrrrroooorrrr MMMMeeeessssssssaaaaggggeeeessss,,,, DDDDeeeebbbbuuuuggggggggiiiinnnngggg.... _2_1._1._O_u_t_p_u_t _M_e_s_s_a_g_e_s. The output from ttttmmmm, ppppmmmm, and the prompt from rrrrdddd, as well as various _e_r_r_o_r messages are written onto the stan‐ dard error. The latter is different from the _s_t_a_n_d_a_r_d _o_u_t_p_u_t, where formatted text goes. By default, both are written onto the user’s terminal, but they can be independently redirected. An error message additionally includes the line number where the error occurred, the current input file name, the current physi‐ cal output page number (if any), and the names of the macros in the frames of the current execution stack. The eeeerrrrrrrrpppprrrriiiinnnntttt request allows to write custom messages in the same format. _2_1._2._W_a_r_n_i_n_g_s. _n_r_o_f_f and _t_r_o_f_f provide a mechanism to enable or disable warnings for several categories. When one of the selected conditions occurs, a _w_a_r_n_i_n_g message is written in the same format as an error message, but processing continues. ─┌────────┬──────────────┬─────────────────────────────────────────────────────────┐ │ Bit │ Name │ Description │ ─└├────────┴┼──────────────┴┼─────────────────────────────────────────────────────────┤┘ │ 0 │ nnnnoooonnnneeee │ No warnings at all. │ │ 1 │ cccchhhhaaaarrrr │ Warn when unknown character names like \\\\((((xxxxxxxx or \\\\[[[[xxxxxxxxxxxx]]]] │ │ │ │ are found. │ │ 2 │ nnnnuuuummmmbbbbeeeerrrr │ Warn when illegal numerical expressions occur. │ │ 4 │ bbbbrrrreeeeaaaakkkk │ Warn when a line in ....aaaadddd bbbb mode cannot be adjusted. │ │ 8 │ ddddeeeelllliiiimmmm │ Warn when a delimiter to an escape sequence is missing. │ │ 16 │ eeeellll │ Warn when a eeeellll request is found without a matching iiiieeee. │ │ 32 │ ssssccccaaaalllleeee │ Warn when an undefined scale indicator is used in a │ │ │ │ numerical expression. │ │ 64 │ rrrraaaannnnggggeeee │ Warn when an argument is out of range. │ │ 128 │ ssssyyyynnnnttttaaaaxxxx │ Warn about questionable syntax in numerical expres‐ │ │ │ │ sions. │ ─└────────┴──────────────┴─────────────────────────────────────────────────────────┘ ‐ 75 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ─┌────────┬──────────────┬─────────────────────────────────────────────────────────┐ │ Bit │ Name │ Description │ ─└├────────┴┼──────────────┴┼─────────────────────────────────────────────────────────┤┘ │ 256 │ ddddiiii │ Warn when a ddddiiii request is executed but no diversion is │ │ │ │ currently active. │ │ 512 │ mmmmaaaacccc │ Warn when an undefined request, macro or string is │ │ │ │ called. │ │ 1024 │ rrrreeeegggg │ Warn when an undefined number register is accessed. │ │ │ │ The number register will be set to zero immediately │ │ │ │ after the first access so this warning can be printed │ │ │ │ only once per register name. │ │ 4096 │ rrrriiiigggghhhhtttt‐bbbbrrrraaaacccceeee │ Warn when a \\\\}}}} terminates a numerical expression. │ │ 8192 │ mmmmiiiissssssssiiiinnnngggg │ Warn when a required argument to a request is missing. │ │ 16384 │ iiiinnnnppppuuuutttt │ Warn when illegal byte sequences or characters that │ │ │ │ have no known PostScript equivalent are read. │ │ 32768 │ eeeessssccccaaaappppeeee │ Warn when an undefined escape sequence is used. │ │ 65536 │ ssssppppaaaacccceeee │ Warn when an unknown long request name is used, but its │ │ │ │ first two characters form a known regular request. The │ │ │ │ regular request is then executed in extension level 2, │ │ │ │ or ignored in extension level 3. │ │131072 │ ffffoooonnnntttt │ Warn when a font cannot be found. This warning is │ │ │ │ enabled by default. │ │ │ aaaallllllll │ All warnings except ddddiiii, mmmmaaaacccc, and rrrreeeegggg. This may be the │ │ │ │ best choice when using existing macro packages. │ │ │ wwww │ All warnings. │ ─└────────┴──────────────┴─────────────────────────────────────────────────────────┘ _2_1._3._E_r_r_o_r_s. Various _e_r_r_o_r conditions may occur during the opera‐ tion of _n_r_o_f_f and _t_r_o_f_f. Certain less serious errors having only local impact do not cause processing to terminate. Two examples are _w_o_r_d _o_v_e_r_f_l_o_w, caused by a word that is too large to fit into the word buffer (in fill mode), and _l_i_n_e _o_v_e_r_f_l_o_w, caused by an output line that grew too large to fit in the line buffer; in both cases, a message is printed, the offending excess is dis‐ carded, and the affected word or line is marked at the point of truncation with a ∗ in _n_r_o_f_f and a ☜ in _t_r_o_f_f. Processing con‐ tinues if possible, on the grounds that output useful for debug‐ ging may be produced. If a serious error occurs, processing ter‐ minates, and an appropriate message is printed, along with a list of the macro names currently active. Examples are the inabil‐ ity to create, read, or write files, and the exceeding of certain internal limits that make future output unlikely to be useful. _2_1._4._D_e_b_u_g_g_i_n_g. Strings, macros, and number registers can be _w_a_t_c_h_e_d. Whenever a change of a watched object occurs, or when the object is renamed, removed, or aliased, a notification mes‐ sage is printed. It is formatted like an error message and includes the name of the current (or last previous) request, the name of the objects affected, and, in case of a change, the new contents of the object. When an object is removed, watching is disabled. If an object of the same name is created later, it is not watched unless watching is explicitly enabled for it again. ‐ 76 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....wwwwaaaarrrrnnnn ±_b_i_t_s|_n_a_m_e _w – Control warning messages, which may be given either numerically as bits or symbolically as names. With a ++++ sign, the respective bit or name is enabled in addition to the currently enabled categories; with a ---- sign, it is disabled. Omitting the sign sets the categories exactly to the given bit or name. ....wwwwaaaarrrrnnnn 0000 disables all warnings. The ....wwwwaaaarrrrnnnn register represents the currently activated warning categories as bits. ....sssspppprrrreeeeaaaaddddwwwwaaaarrrrnnnn _N toggle mmmm Set or toggle a limit that causes a warning to be printed when it is exceeded by the adjustment that is computed for the current out‐ put line in aaaadddd bbbb mode. The limit is initially 3m, but the warning message is disabled. Calling this request without an argument toggles the warning message; calling it with an argument enables the warning and sets the limit to _N (default scale m). ....eeeerrrrrrrrpppprrrriiiinnnntttt _s_t_r_i_n_g newline–Print _s_t_r_i_n_g like an error mes‐ sage. ....wwwwaaaattttcccchhhh _x_x off ignore –Notify on change of string or macro _x_x. If _x_x does not exist, it is created as an empty macro in order to watch future changes. ....uuuunnnnwwwwaaaattttcccchhhh _x_x off ignore –Disable notification for string or macro _x_x. ....wwwwaaaattttcccchhhhlllleeeennnnggggtttthhhh _N ignore – On change, report the contents of macros and strings up to length _N. When _N is zero or small, printing of macro and string contents is dis‐ abled. ....wwwwaaaattttcccchhhhnnnn _R off ignore –Notify on change of register _R. If _R does not exist, it is created in order to watch future changes. No effect on read‐only registers and some of the predefined general registers. ....uuuunnnnwwwwaaaattttcccchhhhnnnn _R off ignore –Disable notification for register _R. 22222222.... CCCCoooolllloooorrrr SSSSuuuuppppppppoooorrrrtttt While _t_r_o_f_f does not support colors directly, _d_p_o_s_t is able to embed arbitrary PostScript color instructions using the \\\\XXXX´´´´SSSSeeeettttCCCCoooolllloooorrrr:::: _c_o_l_o_r´´´´ escape sequence. Possible values for _c_o_l_o_r include: – ‘‘_n_a_m_e_d‐_c_o_l_o_r’’, e.g. ‘‘red’’. Named colors (RGB only) ‐ 77 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 must be listed in the ‘‘colordict’’ dictionary in file ////uuuussssrrrr////uuuuccccbbbblllliiiibbbb////ddddooooccccttttoooooooollllssss////ffffoooonnnntttt////ddddeeeevvvvppppssss////ppppoooossssttttssssccccrrrriiiipppptttt////ccccoooolllloooorrrr....ppppssss. Every _c_o_l_o_r argument that begins with a letter is treated as a named color. – ‘‘_r_e_d _g_r_e_e_n _b_l_u_e rrrrggggbbbb’’, e.g. ‘‘.2 .3 .4 rgb’’ (rrrrggggbbbb is an abbre‐ viation for the PostScript sssseeeettttrrrrggggbbbbccccoooolllloooorrrr operator) – ‘‘_h_u_e _s_a_t_u_r_a_t_i_o_n _b_r_i_g_h_t_n_e_s_s hhhhssssbbbb’’, e.g. ‘‘.5 .6 .7 hsb’’ (hhhhssssbbbb is an abbreviation for the PostScript sssseeeetttthhhhssssbbbbccccoooolllloooorrrr operator) – ‘‘_c_y_a_n _m_a_g_e_n_t_a _y_e_l_l_o_w _b_l_a_c_k ccccmmmmyyyykkkk’’, e.g. ‘‘.1 .2 .3 .4 cmyk’’ (ccccmmmmyyyykkkk is an abbreviation for the PostScript sssseeeettttccccmmmmyyyykkkkccccoooolllloooorrrr opera‐ tor) – ‘‘_g_r_a_y sssseeeettttggggrrrraaaayyyy’’, e.g. ‘‘.5 setgray’’ – ‘‘[$$$$_s_e_t_c_o_l_o_r_s_p_a_c_e] _c_o_m_p_1 _c_o_m_p_2 ... _c_o_m_p_n sssseeeettttccccoooolllloooorrrr’’, where $$$$_s_e_t_c_o_l_o_r_s_p_a_c_e may be a PostScript procedure defined in the setup section using a ‘\X´PSSetup: $setcolorspace {...} bind def´’ escape sequence. This parameter is required if the color space changes in the document. Otherwise, it may be sufficient to install the color space once in the setup section. Each parameter must be a number in the range between 0.0 and 1.0. In the most general case, the value of the _c_o_l_o_r argument is passed to the PostScript output without interpretation. Both the text and background color can be selected. A _c_o_l_o_r argument of ‘‘_c_o_l_o_r_1’’ oooonnnn ‘‘_c_o_l_o_r_2’’ prints text in _c_o_l_o_r_1 on a background in _c_o_l_o_r_2. The initial color is black in the _D_e_v_i_c_e_G_r_a_y color space, i.e. the same as ‘‘0 setgray’’. Once a color is in effect, it is re‐ installed at the top of each output page. The ----mmmmccccoooolllloooorrrr macro package adds another access method to the capa‐ bilities of color selection and reverse video printing. It includes the following macro: _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....CCCCLLLL _c_o_l_o_r _t_e_x_t RGB black – Print _t_e_x_t in _c_o_l_o_r. No argu‐ ments restores a default color (black in RGB color space; note that this is different from the ini‐ tial color). If _t_e_x_t is omitted the selected _c_o_l_o_r remains in effect until another _c_o_l_o_r is selected. If two arguments are given the _t_e_x_t is printed in _c_o_l_o_r and then the default color is restored. 22223333.... PPPPiiiiccccttttuuuurrrreeee IIIInnnncccclllluuuussssiiiioooonnnn _d_p_o_s_t can be advised to include other PostScript documents into the output it generates. In general, these documents should be EPS (Encapsulated PostScript) files; inclusion of more gen‐ eral PostScript documents, especially if they consist of multiple pages, will usually not lead to acceptable results. If a PostScript file lacks page‐delimiting comments, the entire file is included. If no %%%%%%%%BBBBoooouuuunnnnddddiiiinnnnggggBBBBooooxxxx or %%%%%%%%HHHHiiiiRRRReeeessssBBBBoooouuuunnnnddddiiiinnnnggggBBBBooooxxxx com‐ ment is present, the picture is assumed to fill an 8.5×11‐inch page. Nothing prevents the picture from being placed off the page. _d_p_o_s_t handles DSC font comments in the included files, but it ‐ 78 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 can only supply glyph data if a path to the respective font file has previously been specified with a _t_r_o_f_f ffffpppp request. It is not necessary that the font is otherwise used in the _t_r_o_f_f input text. If _d_p_o_s_t cannot retrieve a matching font by this mechan‐ ism, it indicates this in the %%%%%%%%DDDDooooccccuuuummmmeeeennnnttttNNNNeeeeeeeeddddeeeeddddRRRReeeessssoooouuuurrrrcccceeeessss comment so that a print manager at a later production stage may include the missing data. An example how to combine the following requests and macros is: ....ppppssssbbbbbbbb ppppiiiiccccttttuuuurrrreeee....eeeeppppssss ....nnnnrrrrffff ssssccccaaaalllleeee ....22225555 ....nnnnrrrrffff yyyy ((((\\\\nnnn[[[[uuuurrrryyyy]]]]pppp----\\\\nnnn[[[[llllllllyyyy]]]]pppp))))****\\\\nnnn[[[[ssssccccaaaalllleeee]]]] ....nnnnrrrrffff xxxx ((((\\\\nnnn[[[[uuuurrrrxxxx]]]]pppp----\\\\nnnn[[[[llllllllxxxx]]]]pppp))))****\\\\nnnn[[[[ssssccccaaaalllleeee]]]] ....PPPPIIII ppppiiiiccccttttuuuurrrreeee....eeeeppppssss """"\\\\nnnnyyyyuuuu,,,,\\\\nnnnxxxxuuuu"""" ....sssspppp \\\\nnnnyyyyuuuu ppppiiiiccccttttuuuurrrreeee ddddeeeessssccccrrrriiiippppttttiiiioooonnnn _t_r_o_f_f includes a request to assist the inclusion of EPS files: _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....ppppssssbbbbbbbb _f_i_l_e_n_a_m_e – – Read the %%%%%%%%HHHHiiiiRRRReeeessssBBBBoooouuuunnnnddddiiiinnnnggggBBBBooooxxxx DSC com‐ ment, or, if no such comment is found, %%%%%%%%BBBBoooouuuunnnnddddiiiinnnnggggBBBBooooxxxx, from the PostScript document _f_i_l_e_n_a_m_e and assign the lower left _x coordinate to the floating‐point register llllllllxxxx, the lower left _y coordinate to llllllllyyyy, the upper right _x coordinate to uuuurrrrxxxx, and the upper right _y coordinate to uuuurrrryyyy. All values are in points. If an error occurs, the registers are set to zero. The ----mmmmppppiiiiccccttttuuuurrrreeeessss macros insert the necessary advices to _d_p_o_s_t to include PostScript pictures into _t_r_o_f_f documents. The macros are: _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....BBBBPPPP _s_o_u_r_c_e _h_e_i_g_h_t _w_i_d_t_h _p_o_s_i_t_i_o_n _o_f_f_s_e_t _f_l_a_g_s _l_a_b_e_lDefine a frame and place a picture in it. The arguments are: _s_o_u_r_c_e Name of a PostScript picture file, optionally suffixed with (_n) to select page number _n from the file (first page by default). _h_e_i_g_h_t Vertical size of the frame, default 3333....0000iiii. This argument is interpreted as a value in inches unless it ends with a uuuu scale indi‐ cator. _w_i_d_t_h Horizontal size of the frame, current line length by default. This argument is interpreted as a value in inches unless it ends with a uuuu scale indicator. _p_o_s_i_t_i_o_n llll (default), cccc, or rrrr to left‐justify, center, or right‐ ‐ 79 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 justify the frame. _o_f_f_s_e_t Move the frame horizontally from the original _p_o_s_i_t_i_o_n by this amount, default 0000iiii. _f_l_a_g_s One or more of: aaaa _d Rotate the picture clockwise _d degrees, default _d =90. oooo Outline the picture with a box. ssss Freely scale both picture dimen‐ sions. wwww White out the area to be occupied by the picture. llll, rrrr, tttt, bbbb Attach the picture to the left right, top, or bottom of the frame. _l_a_b_e_l Place _l_a_b_e_l at distance 1111....5555vvvv below the frame. If there is room, BBBBPPPP fills text around the frame. Everything des‐ tined for either side of the frame goes into a diversion to be retrieved when the accumulated text sweeps past the trap set by BBBBPPPP or when the diversion is explicitly closed by EEEEPPPP. BBBBPPPP is not recommended for text fil‐ ling in aaaadddd pppp mode since its trap‐ based mechanism may result in less optimal output, and since it is not possible to define the shape of a complete paragraph with the informa‐ tion it has. Use a combination of ppppssssbbbbbbbb, ppppsssshhhhaaaappppeeee, and PPPPIIII instead. ....EEEEPPPP – – – End a picture started by BBBBPPPP; EEEEPPPP is usually called implicitly by a trap at frame bottom. A picture and associated text silently disappear if a diversion trap set by BBBBPPPP is not reached. Call EEEEPPPP at the end of the document to retrieve it. ....PPPPIIII _s_o_u_r_c_e _h_e_i_g_h_t,,,,_w_i_d_t_h,,,,_y_o_f_f_s_e_t,,,,_x_o_f_f_s_e_t _f_l_a_g_sThis low‐level macro, used by BBBBPPPP, can help do more complex things. The two arguments not already described are: _x_o_f_f_s_e_t Offset the frame from the left margin by this amount, default 0000iiii. This argument is interpreted as a value in inches unless it ends with a uuuu scale indicator. _y_o_f_f_s_e_t Offset the frame from the current baseline, measuring posi‐ tive downward, default 0000iiii. This argument is interpreted as a value in inches unless it ends with a uuuu ‐ 80 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 scale indicator. 22224444.... SSSSppppeeeecccciiiiaaaallll FFFFeeeeaaaattttuuuurrrreeeessss ffffoooorrrr PPPPDDDDFFFF DDDDooooccccuuuummmmeeeennnnttttssss _2_4._1._T_h_e _b_a_s_i_c_s. _t_r_o_f_f does not directly generate PDF documents; the _d_p_o_s_t postprocessor generates PostScript output which can be converted to PDF by utilities like Ghostscript’s _p_s_2_p_d_f or Adobe Distiller. But it is possible to include special advices to this conversion program in PostScript using the ppppddddffffmmmmaaaarrrrkkkk operator. Such advices are generated automatically by some _t_r_o_f_f requests, e.g. by ccccrrrrooooppppaaaatttt (§3). Other advices can be given explicitly using the \\\\XXXX´´´´PPPPSSSS::::...´´´´ or \\\\XXXX´´´´PPPPDDDDFFFFMMMMaaaarrrrkkkk::::...´´´´ escape sequences. _2_4._2._P_r_e_p_a_r_a_t_i_o_n_s. When generating PDF files, it is especially important to set the paper format using the mmmmeeeeddddiiiiaaaassssiiiizzzzeeee request (§3). This is because calculations in PDF documents are gen‐ erally performed in relation regard to the page bottom, while _t_r_o_f_f performs its calculations in relation to the page top. Failing to set the paper format correctly will thus usually result in vertical displacements of PDF‐specific elements. _2_4._3._S_p_e_c_i_f_y_i_n_g _d_o_c_u_m_e_n_t _d_e_s_c_r_i_p_t_i_o_n _i_t_e_m_s. PDF documents can include meta‐data about author, title etc. To generate such data, use the PPPPDDDDFFFFMMMMaaaarrrrkkkk device command of _d_p_o_s_t with the _t_r_o_f_f \\\\XXXX escape sequence, e.g. \\\\XXXX´´´´PPPPDDDDFFFFMMMMaaaarrrrkkkk:::: AAAAuuuutttthhhhoooorrrr _M_y _N_a_m_e´´´´ \\\\XXXX´´´´PPPPDDDDFFFFMMMMaaaarrrrkkkk:::: KKKKeeeeyyyywwwwoooorrrrddddssss _T_y_p_e_s_e_t_t_i_n_g, _P_D_F _d_o_c_u_m_e_n_t_s´´´´ \\\\XXXX´´´´PPPPDDDDFFFFMMMMaaaarrrrkkkk:::: SSSSuuuubbbbjjjjeeeecccctttt _t_r_o_f_f, _d_p_o_s_t, _a_n_d _p_d_f_m_a_r_k´´´´ \\\\XXXX´´´´PPPPDDDDFFFFMMMMaaaarrrrkkkk:::: TTTTiiiittttlllleeee _S_p_e_c_i_a_l _f_e_a_t_u_r_e_s _f_o_r _P_D_F _d_o_c_u_m_e_n_t_s´´´´ ....bbbbrrrr Unicode characters are accepted in these text strings. Note that whitespace and newlines surrounding \\\\XXXX escape sequences are considered to be input text by _t_r_o_f_f, and need a _b_r_e_a_k before they are output. To avoid inserting superfluous spaces or line breaks, specify this information before an initial ....sssspppp ||||\\\\nnnn[[[[ttttooooppppmmmmaaaarrrrggggiiiinnnn]]]]uuuu request or the like in the document. _2_4._4._D_i_r_e_c_t _u_s_e _o_f _t_h_e _p_d_f_m_a_r_k _o_p_e_r_a_t_o_r. In cases where _t_r_o_f_f or _d_p_o_s_t do not include an explicit mechanism for PDF features, it is possible to call the ppppddddffffmmmmaaaarrrrkkkk operator directly. Examples are: \\\\XXXX´´´´PPPPSSSS:::: [[[[ {{{{CCCCaaaattttaaaalllloooogggg}}}} <<<<<<<< ////VVVViiiieeeewwwweeeerrrrPPPPrrrreeeeffffeeeerrrreeeennnncccceeeessss <<<<<<<< ////DDDDiiiissssppppllllaaaayyyyDDDDooooccccTTTTiiiittttlllleeee ttttrrrruuuueeee >>>>>>>> >>>>>>>> ////PPPPUUUUTTTT ppppddddffffmmmmaaaarrrrkkkk\\\\’ This causes the PDF viewer to print the document title (as in §24.3) in the application title bar instead of the PDF file name. \\\\XXXX´´´´PPPPSSSS:::: [[[[ ////PPPPaaaaggggeeeeMMMMooooddddeeee ////UUUUsssseeeeOOOOuuuuttttlllliiiinnnneeeessss ////DDDDOOOOCCCCVVVVIIIIEEEEWWWW ppppddddffffmmmmaaaarrrrkkkk´´´´ This causes the PDF viewer to display the bookmarks toolbar when the document is opened. Other interesting values are ////UUUUsssseeeeNNNNoooonnnneeee (the default), ////UUUUsssseeeeTTTThhhhuuuummmmbbbbssss (display page thumbnails), and ////FFFFuuuullllllllSSSSccccrrrreeeeeeeennnn (open the document in full‐screen mode). \\\\XXXX´´´´PPPPSSSS:::: [[[[ ////PPPPaaaaggggeeeeMMMMooooddddeeee ////PPPPaaaaggggeeee _N ////VVVViiiieeeewwww [[[[////XXXXYYYYZZZZ nnnnuuuullllllll nnnnuuuullllllll nnnnuuuullllllll]]]] ////DDDDOOOOCCCCVVVVIIIIEEEEWWWW ppppddddffffmmmmaaaarrrrkkkk´´´´ Page _N is displayed instead of the first page when the document is opened. \\\\XXXX´´´´PPPPSSSS:::: [[[[ {{{{CCCCaaaattttaaaalllloooogggg}}}} <<<<<<<< ////PPPPaaaaggggeeeeLLLLaaaayyyyoooouuuutttt ////TTTTwwwwooooPPPPaaaaggggeeeeRRRRiiiigggghhhhtttt >>>>>>>> ////PPPPUUUUTTTT ppppddddffffmmmmaaaarrrrkkkk´´´´ With this command, the PDF viewer displays two pages at once. Other interesting values are ////SSSSiiiinnnngggglllleeeePPPPaaaaggggeeee (display one page at once), ////OOOOnnnneeeeCCCCoooolllluuuummmmnnnn (display one page in continuous mode), and ////TTTTwwwwooooCCCCoooolllluuuummmmnnnnRRRRiiiigggghhhhtttt (display two pages in continuous mode). ‐ 81 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 \\\\XXXX´´´´PPPPSSSS:::: [[[[ ////LLLLaaaabbbbeeeellll ((((_t_e_x_t)))) ////PPPPAAAAGGGGEEEELLLLAAAABBBBEEEELLLL ppppddddffffmmmmaaaarrrrkkkk´´´´ The given ASCII _t_e_x_t is shown next to the page number of the current page in the PDF viewer toolbar. This is particularly useful to implement roman page numbers in PDF documents in com‐ bination with the aaaaffff request. _2_4._5._C_r_e_a_t_i_n_g _b_o_o_k_m_a_r_k_s. Bookmarks are usually shown by the PDF viewer at the left of the window. When you create PDF files longer than a few pages for viewing on the screen, you should include bookmarks for each chapter or section because they enable the reader to navigate much more conveniently. Start with a bookmark for the title page. ‘‘0’’ is the level of the bookmark in the tree structure, and the following arguments form the name of the bookmark: \\\\XXXX´´´´PPPPDDDDFFFFMMMMaaaarrrrkkkk:::: BBBBooooooookkkkmmmmaaaarrrrkkkk _0 _T_i_t_l_e´´´´. Similar to the description specifications above, this bookmark should appear before the top margin of the title page. When generating bookmarks for chapters and sections, it is usu‐ ally most practical to include the command in the chapter/section macros: ....ddddeeee CCCCHHHH .... bbbbpppp \\\\vvvv´´´´||||----1111vvvv----4444pppp´´´´\\\\\\\\XXXX´´´´PPPPDDDDFFFFMMMMaaaarrrrkkkk:::: BBBBooooooookkkkmmmmaaaarrrrkkkk 0000 \\\\\\\\$$$$1111´´´´ .... sssspppp ||||\\\\\\\\nnnn[[[[ttttooooppppmmmmaaaarrrrggggiiiinnnn]]]]uuuu .... cccceeee .... sssspppp ........ ....ddddeeee SSSSHHHH .... cccceeee \\\\\\\\$$$$1111\\\\vvvv´´´´----1111vvvv´´´´\\\\\\\\XXXX´´´´PPPPDDDDFFFFMMMMaaaarrrrkkkk:::: BBBBooooooookkkkmmmmaaaarrrrkkkk 1111 \\\\\\\\$$$$1111´´´´ .... sssspppp ........ Unless the bookmark command occurs at the top of the page, it refers to the baseline of the text; this is why a \\\\vvvv´´´´----1111vvvv´´´´ command occurs before it in the section macro. \\\\vvvv´´´´----1111vvvv----4444pppp´´´´ at the top of the page is a special value that causes the upper left corner to be shown. The level of the first bookmark in a document must be of level 0. The levels of following bookmarks must be either – one higher than the level of the previous bookmark. The new bookmark then becomes a child of the previous bookmark. – equal to the level of the previous bookmark. In this case, both bookmarks are grouped below the first previous bookmark of the first higher level, or at the top level for level 0. – lower than the level of the previous bookmark. This terminates the list of children of the higher levels. As an example, the following level structure is legal, and causes the PDF viewer to group the bookmarks as shown: 0 title page 0 Chapter 1 •-1 Section 1.1 •-1 Section 1.2 | •--2 Subsection 1.2.1 | •--2 Subsection 1.2.2 | •--2 Subsection 1.2.3 •-1 Section 1.3 ‐ 82 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 •--2 Subsection 1.3.1 •--2 Subsection 1.3.2 0 Chapter 2 •-1 Section 2.1 0 Index In case of an illegal structure in which the level of a bookmark is raised by more than one above its predecessor, _d_p_o_s_t emits a warning and assigns the highest legal level. However, a garbled document structure may result: 0 •-2 ☜ the first level 2 is corrected to 1 by _d_p_o_s_t •--2 so the second bookmark becomes a child of the first Thus such _d_p_o_s_t warnings should usually be taken seriously, and the document should be corrected. An alternate form of bookmarks, \\\\XXXX´´´´PPPPDDDDFFFFMMMMaaaarrrrkkkk:::: BBBBooooooookkkkmmmmaaaarrrrkkkkCCCClllloooosssseeeedddd ...´´´´, is available. The syntax is the same, but the initial view in the tree structure is collapsed, i.e. no children are shown by default. It the bookmark has no children, there is no difference to a regular bookmark. _2_4._6._L_i_n_k_s. PDF documents can contain links that cause the viewer to jump to a certain location when the user clicks on an area of the page, as well as links to external documents in URI form. In _t_r_o_f_f, such links can be built as follows: The \\\\AAAA´_s_t_r_i_n_g´ escape sequence defines an anchor, i.e. a loca‐ tion to jump to, with the name _s_t_r_i_n_g (consisting of ASCII char‐ acters). The actual link is built using two \\\\TTTT escape sequences sur‐ rounding the text that forms the area to click on, e.g.: \\\\TTTT´_s_t_r_i_n_g´_t_e_x_t _o_f _l_i_n_k\\\\TTTT. _s_t_r_i_n_g must correspond to an anchor anywhere in the document. An URI link is built likewise using two \\\\WWWW escape sequences: \\\\WWWW´_u_r_i´_t_e_x_t _o_f _l_i_n_k\\\\WWWW. The _u_r_i part is not inter‐ preted by _t_r_o_f_f, but just written to the generated out‐ put. Typically, this will be a link to a web page, as in <\W’http://n‐t‐roff.github.io/heirloom/doctools.html’http://n‐ t‐roff.github.io/heirloom/doctools.html\W>. The appearance of links can be changed; links are normally sur‐ rounded by an 1 point wide blue border. The color can be set using \\\\XXXX’SSSSeeeettttLLLLiiiinnnnkkkkCCCCoooolllloooorrrr:::: _r_e_d _g_r_e_e_n _b_l_u_e’, where _r_e_d, _g_r_e_e_n, _a_n_d _b_l_u_e are values between 0 and 1. The border can be set using \\\\XXXX’SSSSeeeettttLLLLiiiinnnnkkkkBBBBoooorrrrddddeeeerrrr:::: _b_x _b_y _w_i_d_t_h’, where _b_x and _b_y define the horizontal and vertical corner radius, respectively, and _w_i_d_t_h defines the width. The border style can be changed with the \\\\XXXX''''SSSSeeeettttBBBBoooorrrrddddeeeerrrrSSSSttttyyyylllleeee:::: _a_r_g_u_‐ _m_e_n_t_s'''' command. The _a_r_g_u_m_e_n_t_s are the same as for the ////BBBBSSSS pdfmark operator or the LATEX hhhhyyyyppppeeeerrrrrrrreeeeffff ppppddddffffbbbboooorrrrddddeeeerrrrssssttttyyyylllleeee===={{{{}}}} vari‐ able. Likewise, SSSSeeeettttUUUULLLLiiiinnnnkkkkCCCCoooolllloooorrrr, SSSSeeeettttUUUULLLLiiiinnnnkkkkBBBBoooorrrrddddeeeerrrr, and SSSSeeeettttUUUUBBBBoooorrrrddddeeeerrrrSSSSttttyyyylllleeee are available for URI links. E.g. for this document the commands \\\\XXXX''''SSSSeeeettttBBBBoooorrrrddddeeeerrrrSSSSttttyyyylllleeee:::: ////SSSS////UUUU////WWWW 0000....1111'''' \\\\XXXX''''SSSSeeeettttUUUUBBBBoooorrrrddddeeeerrrrSSSSttttyyyylllleeee:::: ////SSSS////UUUU////WWWW 0000....1111'''' are used. ‐ 83 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 22225555.... _gggg_rrrr_oooo_ffff_ffff CCCCoooommmmppppaaaattttiiiibbbbiiiilllliiiittttyyyy Heirloom _t_r_o_f_f provides most of the extensions to the _t_r_o_f_f language introduced in _g_r_o_f_f10. Consequently, it is possible to create documents, macro sets, and preprocessors that can be used with both Heirloom _t_r_o_f_f and _g_r_o_f_f and use functionality beyond the features that were supported by traditional _t_r_o_f_f. Important differences to _g_r_o_f_f are: The concept of an _i_n_p_u_t _l_e_v_e_l regarding delimiters in escape sequences and macro argu‐ ments is not supported. Control characters are recognized at the beginning of a line even if preceded by escape sequences that do not result in formatting stream objects, such as \\\\ffff, \\\\ssss, or \\\\;;;;. Font handling, color support, picture inclusion, and PDF structuring are realized using different mechanisms. The _d_p_o_s_t post‐processor does not recognize the \\\\XXXX´´´´ppppssss::::...´´´´ escape sequence (or xxxx XXXX ppppssss:::: command, respectively) that is used for pass‐through PostScript with the _g_r_o_p_s post‐processor of _g_r_o_f_f (_d_p_o_s_t accepts \\\\XXXX’PPPPSSSS::::...´´´´ and xxxx XXXX PPPPSSSS::::); the PostScript output generated by _d_p_o_s_t is very different to that generated by _g_r_o_p_s. _d_p_o_s_t accepts the _g_r_o_f_f drawing command extensions and sets the horizontal and vertical positions accordingly, but otherwise ignores line width, color, and fill specifications. _2_5._1._C_o_n_d_i_t_i_o_n_a_l _g_r_o_f_f _c_o_m_p_a_t_i_b_i_l_i_t_y. A request is available to control additional functions for _g_r_o_f_f compatibility: _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....ccccpppp _N off – – Enable _g_r_o_f_f compatibility mode. This is the name of _g_r_o_f_f’_s own compatibility request with adapted semantics: Regardless of the argu‐ ment, _g_r_o_f_f compatibility mode is activated. If _N=0, compatibility with traditional _t_r_o_f_f is decreased, and Heirloom _t_r_o_f_f extension level 3 is set. If _N≠0 or missing, com‐ patibility with traditional _t_r_o_f_f is improved, and Heirloom _t_r_o_f_f exten‐ sion level 1 is set. Thus ....ccccpppp 0000 results in maximum _g_r_o_f_f compatibil‐ ity. The ccccpppp request sets the general number register ....gggg to 1 in _g_r_o_f_f compatibility mode and to 0 otherwise. The general number regis‐ ter ....CCCC is only assigned by the ....ccccpppp request and corresponds to its argument. Any use of the xxxxffffllllaaaagggg request disables _g_r_o_f_f compatibility and accordingly sets the ....gggg register to 0. The ....XXXX read‐only number register holds the current extension level after ccccpppp as usual. It can thus be used to determine whether running under _g_r_o_f_f or in the _g_r_o_f_f compatibility mode of Heirloom _t_r_o_f_f. Since they are read‐write, any convenient value can then be assigned to the ....CCCC and ....gggg registers. Nevertheless it is not recommend to do so without reason. For instance macro packages read \n(.g to test if they are processed with groff. Setting ....gggg to 1111 with the ....nnnnrrrr request also has some side effects in Heirloom _t_r_o_f_f: ‐ 84 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 • _g_r_o_f_f’s notation for accessing symbols with \\\\[[[[cccchhhhaaaarrrr_n]]]] and \\\\[[[[uuuu_X_X_X_X]]]] are enabled. • The escape \\\\%%%% marks optional hyphenation points inside a word or suppresses hyphenation prefixed to a word (_e_v_e_n _w_h_e_n _t_h_i_s _w_o_r_d _c_o_n_t_a_i_n_e_s _d_a_s_h_e_s). A problem in macro packages is that it cannot be guaranteed that no character is before word (e.g. quotes or parentheses). _g_r_o_f_f allows to force that \\\\%%%% acts as a hyphenation suppression escape when it follows the zero‐width characters \\\\)))) or \\\\&&&&. This does not work with traditional _t_r_o_f_f, unfortunately. The command ....nnnnrrrr....gggg1111 enables the _g_r_o_f_f behaviour. • The algorithm _g_r_o_f_f uses for the three part title request ....ttttllll leads to a different placement of the middle title ele‐ ment with _n_r_o_f_f under certain conditions. This is emulated by setting ....gggg to 1. • _g_r_o_f_f’s left italic correction escape \\\\,,,, is removed from the input instead of producing a ‘,,,,’. The ....xxxx and ....yyyy registers are read‐write in _g_r_o_f_f compatibility mode; they correspond to the emulated _g_r_o_f_f version number. The ccccpppp request sets them to 1 and 18, respectively. The ....kkkk number register behaves differently in _g_r_o_f_f compatibility mode: If the preceding text character was a newline, the width of a space character is added to the value. If the previous line was interrupted with \\\\cccc, the length of the partially collected word (as in the ....kkkkcccc number register) is part of the value. The space width always defaults to the value obtained from the font metrics file in _g_r_o_f_f compatibility mode; the ssssppppaaaacccceeeewwwwiiiiddddtttthhhh request is not effective. If the file specified with a ssssoooo request cannot be opened, pro‐ cessing continues with the current file in _g_r_o_f_f compatibility mode. A control or escape character written in a diversion has no spe‐ cial meaning if the diversion is re‐read in _g_r_o_f_f compatibility mode. Unless a string is interpolated with explicit arguments, the arguments to the surrounding macro instance remain visible and can be referenced by the \\\\$$$$ escape sequence inside the string in _g_r_o_f_f compatibility mode. Any call to the ccccpppp request activates the following _g_r_o_f_f compa‐ tibility escape sequences; any call to the xxxxffffllllaaaagggg request disables them. The \\\\AAAA’_s_t_r_i_n_g’ escape sequence checks whether _s_t_r_i_n_g is accept‐ able as the name of a string, macro, number register, or font, and evaluates to ‘‘1’ if it does and to ‘‘0’’ otherwise. The Heirloom _t_r_o_f_f anchoring escape sequence \\\\AAAA is not available in _g_r_o_f_f compatibility mode. The \\\\//// escape sequence inserts an italic correction, i.e. a small piece of horizontal motion (1/12em) that should be sufficient to separate an italic character from a following roman charac‐ ter. Similarly, \\\\,,,, adds a left italic correction, always a zero motion, that should be sufficient to separate a roman character from an immediately following italic character. Both exist to provide basic _g_r_o_f_f compatibility only. It is otherwise recom‐ mended that the kkkkeeeerrrrnnnnppppaaaaiiiirrrr request is used for these purposes; it ‐ 85 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 allows a more exact optical separation since the shape of both characters can be taken into account and also does not need to be be positioned directly in the input text at every occasion. The \\\\DDDD´´´´pppp ...´´´´ polygon drawing escape sequence is altered such that the path is always closed, i.e. if the last line part does not return to the starting position, an additional line is added that does. The escape sequences \\\\FFFF_x, \\\\FFFF((((_x_x, \\\\FFFF[[[[_x_x_x]]]], \\\\mmmm_x, \\\\mmmm((((_x_x, \\\\mmmm[[[[_x_x_x]]]], \\\\MMMM_x, \\\\MMMM((((_x_x, \\\\MMMM[[[[_x_x_x]]]], are read but discarded in _g_r_o_f_f compatibil‐ ity mode since the corresponding concepts of font families and built‐in color support are foreign to Heirloom _t_r_o_f_f. All of them generate a warning of the eeeessssccccaaaappppeeee category. _2_5._2._g_r_o_f_f _c_o_m_p_a_t_i_b_i_l_i_t_y _m_a_c_r_o_s. As an additional aid in format‐ ting documents that had originally been written with _g_r_o_f_f in mind, Heirloom _t_r_o_f_f provides the ----mmmmgggg compatibility macro pack‐ age. Specifically: ....ccccpppp 0000 is executed, so _t_r_o_f_f is operated in _g_r_o_f_f compatibility mode at extension level 3. The locale is set to eeeennnn____UUUUSSSS; this assumes that input to _g_r_o_f_f is conventionally in the ISO‐8859‐1 encoding. The hyphenation language is set to eeeennnn____UUUUSSSS. Since both _g_r_o_f_f and Heirloom _t_r_o_f_f then use the same hyphenation algorithm and pat‐ terns derived from _T_E_X, it can be assumed that words are subject to hyphenation at the same points. The ddddeeee1111, aaaammmm1111, ddddssss1111, and aaaassss1111 _g_r_o_f_f requests are emulated using ddddeeee, aaaammmm, ddddssss, and aaaassss, respectively. It is not expected that the _g_r_o_f_f compatibility macros are used to format documents that require compatibility with traditional _t_r_o_f_f. The ffffttttrrrr request is removed since the _g_r_o_f_f request with the same name provides completely different semantics. ffffaaaallllllllbbbbaaaacccckkkk is used to emulate ffffssssppppeeeecccciiiiaaaallll; these requests should be compatible. No emulation is provided for the ssssppppeeeecccciiiiaaaallll request; all other fonts are searched for missing characters in Heirloom _t_r_o_f_f by default. ttttrrrraaaacccckkkk is used to emulate ttttkkkkffff. These requests are not completely compatible: ttttrrrraaaacccckkkk does not affect the last character on a line and thus does not alter the visual length of lines like ttttkkkkffff does; ttttrrrraaaacccckkkk is applied when formatting an object defined with the cccchhhhaaaarrrr request; ttttrrrraaaacccckkkk needs to remain in effect until all affected char‐ acters have been physically output. Nevertheless, the replace‐ ment should suffice for most applications. _g_r_o_f_f characters with two‐character names are mapped to PostScript character names using the cccchhhhaaaarrrr request. The following macro is also provided as an emulation for the corresponding _g_r_o_f_f request: _RRRR_eeee_qqqq_uuuu_eeee_ssss_tttt _IIII_nnnn_iiii_tttt_iiii_aaaa_llll _IIII_ffff _NNNN_oooo _FFFF_oooo_rrrr_mmmm _VVVV_aaaa_llll_uuuu_eeee _AAAA_rrrr_gggg_uuuu_mmmm_eeee_nnnn_tttt _NNNN_oooo_tttt_eeee_ssss_EEEE_xxxx_pppp_llll_aaaa_nnnn_aaaa_tttt_iiii_oooo_nnnn ....mmmmssssoooo _n_a_m_e – ignored–Include the macro package _n_a_m_e. If the environment vari‐ able GGGGRRRROOOOFFFFFFFF____TTTTMMMMAAAACCCC____PPPPAAAATTTTHHHH is set, each of the colon‐separated directories in it is checked for the files _n_a_m_e, _n_a_m_e.tmac, m_n_a_m_e.tmac, and tmac._n_a_m_e. After this, the standard ‐ 86 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _t_r_o_f_f macro directories are checked in the same way. Once a file has been found, it is read in as with the ssssoooo request, and the search stops. 22226666.... OOOOuuuuttttppppuuuutttt LLLLaaaannnngggguuuuaaaaggggeeee.... _t_r_o_f_f produces its output in a language that is independent of any specific output device, except that the numbers in it have been computed on the basis of the resolution of the device, and the sizes, fonts, and characters that that device can print. Nevertheless it is quite possible to interpret that output on a different device, within the latter’s capabilities. ssss_n set point size to _n, fractional parts (if any) ignored ssss----22223333_d._d set point size to _d._d ffff_n set font to _n cccc_c print character _c CCCC_n_a_m_e print the character called _n_a_m_e; terminate _n_a_m_e by white space CCCCPPPPSSSS_n_a_m_e print the character with the given PostScript _n_a_m_e NNNN_n print character _n on current font HHHH_n go to absolute horizontal position _n (_n≥0) VVVV_n go to absolute vertical position _n (_n≥0, down is positive) hhhh_n go _n units horizontally; _n<0 is to the left vvvv_n go _n units vertically; _n<0 is up _n_n_c move right _n_n, then print ASCII character _c; _n_n must be exactly 2 digits pppp_n new page _n begins—set vertical position to 0 nnnn_b _a end of line (information only—no action); _b = space before line, _a = after wwww paddable word space (information only—no action) DDDD_c ...\_ngraphics function _c; see below xxxx ............\\\\nnnn device control functions; see below #### ............\\\\nnnn comment All position values are in units. Sequences that end in digits must be followed by a non‐digit. Blanks, tabs and newlines may occur as separators in the input, and are mandatory to separate constructions that would otherwise be confused. Graphics func‐ tions, device control functions, and comments extend to the end of the line they occur on. The device control and graphics commands are intended as open‐ ended families, to be expanded as needed. The graphics functions coincide directly with the \\\\DDDD sequences: DDDDllll _d_h _d_v draw line from current position by _d_h,_d_v DDDDpppp _a _b _c _d ...draw polygon, i.e. a line to _a,_b, then to _c,_d, then ... DDDDcccc _d draw circle of diameter _d with left side at current position DDDDeeee _u _v draw ellipse of diameters _u and _v DDDDaaaa _a _b _c _d draw arc from current position to _a+_c,_b+_d, with center at _a,_b from current position DDDD∼∼∼∼ _a _b _c _d...draw B‐spline from current position by _a,_b, then by _c,_d, then by _c,_d, then ... DDDDzzzz _a _b _c _d...for any other _z is uninterpreted In all of these, _x,_y is an increment on the current horizontal and vertical position, with down and right positive. All dis‐ tances and dimensions are in units. The device control functions begin with xxxx, then a command, then other parameters. xxxx TTTT _s name of typesetter is _s xxxx rrrr _n _h _v resolution is _n units/inch; _h = minimum horizontal motion, _v = minimum vertical motion ‐ 87 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 xxxx iiii initialize xxxx ffff _n _s mount font _s on font position _n xxxx ffff _n _s _f_i_l_e_n_a_m_e _f_l_a_g_s_f_i_l_e_n_a_m_e contains metrics for font _s on position _n using _f_l_a_g_s xxxx pppp pause—can restart xxxx ssss stop—done forever xxxx tttt generate trailer information, if any xxxx HHHH _n set character height to _n, fractional parts (if any) ignored xxxx HHHH ----22223333 _d._d set character height to _d._d xxxx SSSS _n set slant to _n xxxx XXXX _a_n_y generated by the \\\\XXXX and \\\\YYYY functions xxxx XXXX AAAAnnnncccchhhhoooorrrr _y,_x _i_dspecify PDF link anchor (generated by the \\\\AAAA request) xxxx XXXX AAAAnnnncccchhhhoooorrrr _i_d specify HTML link anchor xxxx XXXX BBBBlllleeeeeeeeddddAAAAtttt _L _T _W _Hgenerated by the bbbblllleeeeeeeeddddaaaatttt request xxxx XXXX CCCCrrrrooooppppAAAAtttt _L _T _W _Hgenerated by the ccccrrrrooooppppaaaatttt request xxxx XXXX HHHHoooorrrrSSSSccccaaaalllleeee _p_e_r_c_e_n_tscale letters horizontally by _p_e_r_c_e_n_t (with the lllleeeettttaaaaddddjjjj request) xxxx XXXX LLLLCCCC____CCCCTTTTYYYYPPPPEEEE _n_a_m_esets the LC_CTYPE locale to _n_a_m_e xxxx XXXX LLLLiiiinnnnkkkk _x_1,_y_1,_x_2,_y_2 _i_dspecify PDF link (generated by the \\\\TTTT''''_i_d'''' request) xxxx XXXX LLLLiiiinnnnkkkk _i_d begin HTML link (generates <<<>>>) xxxx XXXX LLLLiiiinnnnkkkk end HTML link (generates <<<>>>) xxxx XXXX PPPPaaaappppeeeerrrrSSSSiiiizzzzeeee _W _H _ngenerated by the mmmmeeeeddddiiiiaaaassssiiiizzzzeeee and ppppaaaappppeeeerrrrssssiiiizzzzeeee requests _n is non‐zero for mmmmeeeeddddiiiiaaaassssiiiizzzzeeee xxxx XXXX PPPPSSSS _c_o_m_m_a_n_d embed PostScript _c_o_m_m_a_n_d xxxx XXXX PPPPSSSSSSSSeeeettttuuuupppp _c_o_m_m_a_n_dembed PostScript _c_o_m_m_a_n_d in global setup section xxxx XXXX SSSSeeeettttCCCCoooolllloooorrrr _c_o_l_o_rchange printing _c_o_l_o_r xxxx XXXX SSSSuuuuppppppppllllyyyyFFFFoooonnnntttt _f_o_n_t _f_i_l_esupply data from _f_i_l_e for PostScript _f_o_n_t xxxx XXXX SSSSyyyynnnncccc instructs to flush position and font information immediately xxxx XXXX TTTTrrrraaaacccckkkk _n gives a hint that following characters are tracked by _n units interpretation is optional; following positions are not changed xxxx XXXX TTTTrrrriiiimmmmAAAAtttt _L _T _W _Hgenerated by the ttttrrrriiiimmmmaaaatttt request xxxx XXXX UUUULLLLiiiinnnnkkkk _x_1,_y_1,_x_2,_y_2 _U_R_Lspecify PDF URL link (generated by the \\\\WWWW''''_i_d'''' request) xxxx XXXX UUUULLLLiiiinnnnkkkk _U_R_L begin HTML URL link (generates <<<>>>) xxxx XXXX UUUULLLLiiiinnnnkkkk end HTML URL link (generates <<<>>>) xxxx _a_n_y to be ignored if not recognized Subcommands like ‘‘i’’ may be spelled out like ‘‘init’’. The commands xxxx TTTT, xxxx rrrr ..., and xxxx iiii fonts must be mounted before they can be used; xxxx ssss comes last. There are no other order requirements. The following is the output from ‘‘hello, world’’ for a typical printer, as described in §27: x T ps x res 72000 1 1 x init V0 p1 x font 1 R /usr/ucblib/doctools/font/devps/R.afm 4 x font 2 I /usr/ucblib/doctools/font/devps/I.afm 4 x font 3 B /usr/ucblib/doctools/font/devps/B.afm 4 x font 4 BI /usr/ucblib/doctools/font/devps/BI.afm 4 x font 5 CW /usr/ucblib/doctools/font/devps/CW.afm 4 x font 6 H /usr/ucblib/doctools/font/devps/H.afm 4 x font 7 HB /usr/ucblib/doctools/font/devps/HB.afm 4 x font 8 HX /usr/ucblib/doctools/font/devps/HX.afm 4 x font 9 S1 /usr/ucblib/doctools/font/devps/S1.afm 516 x font 10 S /usr/ucblib/doctools/font/devps/S.afm 1028 ‐ 88 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 s10 f1 x X LC_CTYPE de_DE.utf8 H72000 V12000 ch h5000ce h4440cl h2780cl h2780co h5000c, wh5830cw h7120co h5000cr h3330cl h2780cd n12000 0 x trailer V792000 x stop _t_r_o_f_f output is normally not redundant; size and font changes and position information are not included unless needed. Neverthe‐ less, each page is normally self‐contained, for the benefit of postprocessors that re‐order pages or process only a sub‐ set. The xxxx XXXX PPPPSSSSSSSSeeeettttuuuupppp command is an exception from this rule; it is included only once at the point where the corresponding \\\\XXXX’PPPPSSSSSSSSeeeettttuuuupppp::::...’ escape sequence occurs. 22227777.... DDDDeeeevvvviiiicccceeee aaaannnndddd FFFFoooonnnntttt DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn FFFFiiiilllleeeessss The parameters that describe a output device _n_a_m_e are read from the directory ////uuuussssrrrr////uuuuccccbbbblllliiiibbbb////ddddooooccccttttoooooooollllssss////ffffoooonnnntttt////ddddeeeevvvv_n_a_m_e, each time _t_r_o_f_f is invoked. The device name is provided by default, by the environment variable TTTTYYYYPPPPEEEESSSSEEEETTTTTTTTEEEERRRR, or by a command‐line argument ----TTTT_n_a_m_e. The default device name is ppppssss, for PostScript output at a resolution of 72000 dpi. The pre‐defined string ....TTTT contains the name of the device. The ----FFFF command‐line option may be used to change the default directory. _2_7._1._D_e_v_i_c_e _d_e_s_c_r_i_p_t_i_o_n _f_i_l_e. General parameters of the dev‐ ice are stored, one per line, in the file ////uuuussssrrrr////uuuuccccbbbblllliiiibbbb////ddddooooccccttttoooooooollllssss////ffffoooonnnntttt////ddddeeeevvvv_n_a_m_e////DDDDEEEESSSSCCCC, as a sequence of names and values. _t_r_o_f_f recognizes these parameters, and ignores any others that may be present for specific drivers: ffffoooonnnnttttssss _n _F _G _H ... _Z ssssiiiizzzzeeeessss _s _t ... 0000 rrrreeeessss _n hhhhoooorrrr _n vvvveeeerrrrtttt _n uuuunnnniiiittttwwwwiiiiddddtttthhhh _n cccchhhhaaaarrrrsssseeeetttt _l_i_s_t _o_f _m_u_l_t_i‐_c_h_a_r_a_c_t_e_r _c_h_a_r_a_c_t_e_r _n_a_m_e_s (_o_p_t_i_o_n_a_l) The F, G, ... are font names to be initially mounted. The list of sizes is a set of integers representing some or all of the legal sizes the device can produce, terminated by a zero. The rrrreeeessss parameter gives the resolution of the machine in units per inch; hhhhoooorrrr and vvvveeeerrrr give the minimum number of units that can be ‐ 89 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 moved horizontally and vertically. Character widths for each font are assumed to be given in machine units at point size uuuunnnniiiittttwwwwiiiiddddtttthhhh. (In other words, a character with a width of _n is _n units wide at size uuuunnnniiiittttwwwwiiiiddddtttthhhh.) All widths are integers at all sizes. A list of valid character names may be introduced by cccchhhhaaaarrrrsssseeeetttt; the list of names is optional. A line whose first non‐blank character is #### is a comment. Except that cccchhhhaaaarrrrsssseeeetttt must occur last, parameters may appear in any order. Here is a subset of the DDDDEEEESSSSCCCC file for a typical Postscript printer: # Description file for Postscript printers. fonts 10 R I B BI CW H HB HX S1 S sizes 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 38 40 44 48 54 60 72 0 anysize allpunct afmfonts lc_ctype res 72000 hor 1 vert 1 unitwidth 1 charset hy ct fi fl ff Fi Fl dg em 14 34 12 en aa ga ru sc dd ‐> br Sl ps cs cy as os =. ld rd le ge pp ‐+ ob vr rs dq sq bx ci fa te ** pl mi eq |= *A *B *X *D *E *F *G *Y *I *K *L *M *N *O *P *R *H *S *T *U *W *C *Q *Z ul rn *a *b *x *d *e *f *g *y *i *k *l *m *n *o *p *h *r *s *t *u *w *c *q *z _2_7._2._F_o_n_t _d_e_s_c_r_i_p_t_i_o_n _f_i_l_e_s. Note: This description applies to the old _t_r_o_f_f device‐independent font format. The current ver‐ sion of _t_r_o_f_f usually reads font metrics directly from Type 1, OpenType, or TrueType font files, as described for the ffffpppp request (§2) and in the separate fonts manual available from the project home page. Each font is described by an analogous description file, which begins with parameters of the font, one per line, followed by a list of characters and widths. The file for font _F is ////uuuussssrrrr////uuuuccccbbbblllliiiibbbb////ddddooooccccttttoooooooollllssss////ffffoooonnnntttt////ddddeeeevvvv_n_a_m_e////_F. nnnnaaaammmmeeee _s_t_r name of font is _s_t_r lllliiiiggggaaaattttuuuurrrreeeessss ............ 0000 list of ligatures ssssppppaaaacccceeeewwwwiiiiddddtttthhhh _n width of a space on this font ssssppppeeeecccciiiiaaaallll this is a special font cccchhhhaaaarrrrsssseeeetttt _l_i_s_t _o_f _c_h_a_r_a_c_t_e_r _n_a_m_e, _w_i_d_t_h, _a_s_c_e_n_d_e_r/_d_e_s_c_e_n_d_e_r, _c_o_d_e, tab separated The nnnnaaaammmmeeee and cccchhhhaaaarrrrsssseeeetttt fields are mandatory; cccchhhhaaaarrrrsssseeeetttt must be last. Comments are permitted, as are other unrecognized parameters. Each line following charset describes one character: its name, its width in units as described above, ascender/descender infor‐ mation, and a decimal, octal or hexadecimal value by which the output device knows it (the \\\\NNNN ‘‘number’’ of the character). The ‐ 90 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 character name is arbitrary, except that ------------ signifies an unnamed character. If the width field contains """", the name is a synonym for the previous character. The ascender/descender field is 1 if the character has a descender (hangs below the baseline, like yyyy), is 2 if it has an ascender (is tall, like YYYY), is 3 if both, and is 0 if neither. The value is returned in the cccctttt register, as computed by the \\\\wwww function (§11.2). Here are excerpts from a typical font description file for the same Postscript printer. hy 33 0 45 hyphen \(hy ‐ " ‐ is a synonym for \(hy Q 72 3 81 a 44 0 97 b 50 2 98 c 44 0 99 d 50 2 100 y 50 1 121 em 100 0 208 --- 44 2 220 English pound currency symbol \N’220’ --- 36 0 221 centered dot \N’221’ This says, for example, that the width of the letter aaaa is 44 units at point size 10, the value of uuuunnnniiiittttwwwwiiiiddddtttthhhh. Point sizes are scaled linearly and rounded, so the width of aaaa will be 44 at size 10, 40 at size 9, 35 at size 8, and so on. ‐ 91 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 TTTTUUUUTTTTOOOORRRRIIIIAAAALLLL EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS TTTT1111.... IIIInnnnttttrrrroooodddduuuuccccttttiiiioooonnnn top and bottom page margin Although _n_r_o_f_f and _t_r_o_f_f have areas respectively. A trap by design a syntax reminis‐ is planted at page position cent of earlier text proces‐ 0 for the header, and at -_N sors* with the intent of easing (_N from the page bottom) for their use, it is almost always the footer. The simplest such necessary to prepare at least a definitions might be small set of macro definitions ....ddddeeee hhhhdddd \\\\""""ddddeeeeffffiiiinnnneeee hhhheeeeaaaaddddeeeerrrr to describe most documents. ´´´´sssspppp 1111iiii Such common formatting needs ........ \\\\""""eeeennnndddd ddddeeeeffffiiiinnnniiiittttiiiioooonnnn as page margins and footnotes ....ddddeeee ffffoooo \\\\""""ddddeeeeffffiiiinnnneeee ffffooooooootttteeeerrrr are deliberately not built into ´´´´bbbbpppp _n_r_o_f_f and _t_r_o_f_f. Instead, ........ \\\\""""eeeennnndddd ddddeeeeffffiiiinnnniiiittttiiiioooonnnn the macro and string defini‐ ....wwwwhhhh 0000 hhhhdddd tion, number register, diver‐ ....wwwwhhhh ----1111iiii ffffoooo sion, environment switching, which provide blank 1 inch page‐position trap, and condi‐ top and bottom margins. The tional input mechanisms pro‐ header will occur on the _f_i_r_s_t vide the basis for user‐defined page, only if the defini‐ implementations. tion and trap exist prior to The examples to be discussed the initial pseudo‐page tran‐ are intended to be useful and sition (§3). In fill mode, somewhat realistic, but won’t the output line that springs necessarily cover all relevant the footer trap was typically contingencies. Explicit numer‐ forced out because some part or ical parameters are used in the whole word didn’t fit on it. examples to make them easier to If anything in the footer and read and to illustrate typical header that follows causes a values. In many cases, number _b_r_e_a_k, that word or part word registers would really be used will be forced out. In this to reduce the number of places and other examples, requests where numerical information is like bbbbpppp and sssspppp that normally kept, and to concentrate con‐ cause breaks are invoked using ditional parameter initializa‐ the _n_o‐_b_r_e_a_k control character tion like that which depends on ´´´´ to avoid this. When the whether _t_r_o_f_f or _n_r_o_f_f is being header/footer design contains used. material requiring independent TTTT2222.... PPPPaaaaggggeeee MMMMaaaarrrrggggiiiinnnnssss text processing, the environ‐ As discussed in §3, _h_e_a_d_e_r ment may be switched, avoiding and _f_o_o_t_e_r macros are usu‐ most interaction with the run‐ ally defined to describe the ning text. ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽ A more realistic example would *For example: P. A. Crisman, be Ed., _T_h_e _C_o_m_p_a_t_i_b_l_e _T_i_m_e‐ ....ddddeeee hhhhdddd \\\\""""hhhheeeeaaaaddddeeeerrrr _S_h_a_r_i_n_g _S_y_s_t_e_m, MIT Press, ....iiiiffff tttt ....ttttllll ´´´´\\\\((((rrrrnnnn´´´´´´´´\\\\((((rrrrnnnn´´´´ \\\\""""ttttrrrrooooffffffff ccccuuuutttt mmmmaaaarrrrkkkk 1965, Section AH9.01 (Descrip‐ ....iiiiffff \\\\\\\\nnnn%%%%>>>>1111 \\\\{{{{\\\\ tion of RUNOFF program on MIT’s ´´´´sssspppp ||||0000....5555iiii----1111\\\\""""ttttllll bbbbaaaasssseeee aaaatttt 0000....5555iiii CTSS system). ....ttttllll ´´´´´´´´---- %%%% ----´´´´´´´´\\\\""""cccceeeennnntttteeeerrrreeeedddd ppppaaaaggggeeee nnnnuuuummmmbbbbeeeerrrr ‐ 92 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ....ppppssss \\\\""""rrrreeeessssttttoooorrrreeee ssssiiiizzzzeeee .... ‐‐‐ \\\\""""rrrreeeesssstttt ooooffff ffffooooooootttteeeerrrr ....fffftttt \\\\""""rrrreeeessssttttoooorrrreeee ffffoooonnnntttt ........ ....vvvvssss \\\\}}}} \\\\""""rrrreeeessssttttoooorrrreeee vvvvssss ....ddddeeee hhhhdddd ´´´´sssspppp ||||1111....0000iiii \\\\""""ssssppppaaaacccceeee ttttoooo 1111....0000iiii .... ‐‐‐ \\\\""""hhhheeeeaaaaddddeeeerrrr ssssttttuuuuffffffff ....nnnnssss \\\\""""ttttuuuurrrrnnnn oooonnnn nnnnoooo‐ssssppppaaaacccceeee mmmmooooddddeeee ....ppppssss \\\\\\\\nnnn((((ssss2222\\\\""""rrrreeeessssttttoooorrrreeee pppprrrreeeevvvviiiioooouuuussss ssssiiiizzzzeeee ........ ....ppppssss \\\\\\\\nnnn((((ssss1111\\\\""""rrrreeeessssttttoooorrrreeee ccccuuuurrrrrrrreeeennnntttt ssssiiiizzzzeeee ....ddddeeee ffffoooo \\\\""""ffffooooooootttteeeerrrr ........ ....ppppssss 11110000 \\\\""""sssseeeetttt ffffooooooootttteeeerrrr////hhhheeeeaaaaddddeeeerrrr ssssiiiizPzzzeaeeege numbers may be printed ....fffftttt RRRR \\\\""""sssseeeetttt ffffoooonnnntttt in the bottom margin by a ....vvvvssss 11112222pppp \\\\""""sssseeeetttt bbbbaaaasssseeee‐lllliiiinnnneeee ssssppppaaaacccciiiinnnngsgggeparate macro triggered during ....iiiiffff \\\\\\\\nnnn%%%%====1111 \\\\{{{{\\\\ the footer’s page ejection: ´´´´sssspppp ||||\\\\\\\\nnnn((((....ppppuuuu----0000....5555iiii----1111 \\\\""""ttttllll bbbbaaaasssseeee 0000....5555i....iiiddddueeeeuuuppppbbbbnnnn \\\\""""bbbboooottttttttoooommmm nnnnuuuummmmbbbbeeeerrrr ....ttttllll ´´´´´´´´---- %%%% ----´´´´´´´´ \\\\}}}} \\\\""""ffffiiiirrrrsssstttt ppppaaaaggggeeee nnnnuuuummmmb....bbbetttteeerllllrrr ´´´´´´´´---- %%%% ----´´´´´´´´\\\\""""cccceeeennnntttteeeerrrreeeedddd ppppaaaaggggeeee nnnnuuuummmmbbbbeeeerrrr ´´´´bbbbpppp ........ ........ ....wwwwhhhh ----0000....5555iiii----1111vvvv bbbbnnnn \\\\""""ttttllll bbbbaaaasssseeee 0000....5555iiii uuuupppp ....wwwwhhhh 0000 hhhhdddd TTTT3333.... PPPPaaaarrrraaaaggggrrrraaaapppphhhhssss aaaannnndddd HHHHeeeeaaaaddddiiiinnnnggggssss ....wwwwhhhh ----1111iiii ffffoooo The housekeeping associated which sets the size, font, with starting a new paragraph and base‐line spacing for should be collected in a para‐ the header/footer material, and graph macro that, for example, ultimately restores them. The does the desired preparagraph material in this case is a spacing, forces the correct page number at the bottom of font, size, base‐line spacing, the first page and at the top and indent, checks that enough of the remaining pages. If space remains for _m_o_r_e _t_h_a_n _o_n_e _t_r_o_f_f is used, a _c_u_t _m_a_r_k is line, and requests a temporary drawn in the form of _r_o_o_t‐ indent. _e_n’s at each margin. The sssspppp’s ....ddddeeee ppppgggg \\\\""""ppppaaaarrrraaaaggggrrrraaaapppphhhh refer to absolute positions to ....bbbbrrrr \\\\""""bbbbrrrreeeeaaaakkkk avoid dependence on the base‐ ....fffftttt RRRR \\\\""""ffffoooorrrrcccceeee ffffoooonnnntttt,,,, line spacing. Another reason ....ppppssss 11110000 \\\\""""ssssiiiizzzzeeee,,,, for this in the footer is that ....vvvvssss 11112222pppp \\\\""""ssssppppaaaacccciiiinnnngggg,,,, the footer is invoked by print‐ ....iiiinnnn 0000 \\\\""""aaaannnndddd iiiinnnnddddeeeennnntttt ing a line whose vertical spac‐ ....sssspppp 0000....4444 \\\\""""pppprrrreeeessssppppaaaacccceeee ing swept past the trap posi‐ ....nnnneeee 1111++++\\\\\\\\nnnn((((....VVVVuuuu\\\\""""wwwwaaaannnntttt mmmmoooorrrreeee tttthhhhaaaannnn 1111 lllliiiinnnneeee tion by possibly as much as ....ttttiiii 0000....2222iiii \\\\""""tttteeeemmmmpppp iiiinnnnddddeeeennnntttt the base‐line spacing. The _n_o‐ ........ _s_p_a_c_e mode is turned on at the The first break in ppppgggg will end of hhhhdddd to render ineffective force out any previous par‐ accidental occurrences of sssspppp at tial lines, and must occur the top of the running text. before the vvvvssss. The forcing of The above method of restoring font, etc. is partly a defense size, font, etc. presupposes against prior error and partly that such requests (that set to permit things like section _p_r_e_v_i_o_u_s value) are _n_o_t used heading macros to set parame‐ in the running text. A better ters only once. The prespac‐ scheme is save and restore both ing parameter is suitable for the current _a_n_d previous values _t_r_o_f_f; a larger space, at least as shown for size in the fol‐ as big as the output device lowing: vertical resolution, would be ....ddddeeee ffffoooo more suitable in _n_r_o_f_f. The ....nnnnrrrr ssss1111 \\\\\\\\nnnn((((....ssss\\\\""""ccccuuuurrrrrrrreeeennnntttt ssssiiiizzzzeeee choice of remaining space to ....ppppssss test for in the nnnneeee is the smal‐ ....nnnnrrrr ssss2222 \\\\\\\\nnnn((((....ssss\\\\""""pppprrrreeeevvvviiiioooouuuussss ssssiiiizzzzeeee lest amount greater than one ‐ 93 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 line (the ....VVVV is the available will begin a new column rather vertical resolution). than produce the bottom margin. A macro to automatically number The header can initialize a section headings might look column register that the footer like: will increment and test. The ....ddddeeee sssscccc \\\\""""sssseeeeccccttttiiiioooonnnn following is arranged for two .... ‐‐‐ \\\\""""ffffoooorrrrcccceeee ffffoooonnnntttt,,,, eeeettttcccc.... columns, but is easily modified ....sssspppp 0000....4444 \\\\""""pppprrrreeeessssppppaaaacccceeee for more. ....nnnneeee 2222....4444++++\\\\\\\\nnnn((((....VVVVuuuu \\\\""""wwwwaaaannnntttt 2222....4444++++ lllliiiinnnneeeessss ....ddddeeee hhhhdddd \\\\""""hhhheeeeaaaaddddeeeerrrr ....ffffiiii .... ‐‐‐ \\\\\\\\nnnn++++SSSS.... ....nnnnrrrr ccccllll 0000 1111\\\\""""iiiinnnniiiitttt ccccoooolllluuuummmmnnnn ccccoooouuuunnnntttt ........ ....mmmmkkkk \\\\""""mmmmaaaarrrrkkkk ttttoooopppp ooooffff tttteeeexxxxtttt ....nnnnrrrr SSSS 0000 1111 \\\\""""iiiinnnniiiitttt SSSS ........ The usage is ....sssscccc, followed by ....ddddeeee ffffoooo \\\\""""ffffooooooootttteeeerrrr the section heading text, fol‐ ....iiiieeee \\\\\\\\nnnn++++((((ccccllll<<<<2222 \\\\{{{{\\\\ lowed by ....ppppgggg. The nnnneeee test ....ppppoooo ++++3333....4444iiii \\\\""""nnnneeeexxxxtttt ccccoooolllluuuummmmnnnn;;;; 3333....1111++++0000....3333 value includes one line of ....rrrrtttt \\\\""""bbbbaaaacccckkkk ttttoooo mmmmaaaarrrrkkkk heading, 0.4 line in the fol‐ ....nnnnssss \\\\}}}} \\\\""""nnnnoooo‐ssssppppaaaacccceeee mmmmooooddddeeee lowing ppppgggg, and one line of the ....eeeellll \\\\{{{{\\\\ paragraph text. A word con‐ ....ppppoooo \\\\\\\\nnnnMMMMuuuu \\\\""""rrrreeeessssttttoooorrrreeee lllleeeefffftttt mmmmaaaarrrrggggiiiinnnn sisting of the next section .... ‐‐‐ number and a period is produced ´´´´bbbbpppp \\\\}}}} to begin the heading line. The ........ format of the number may be set ....llllllll 3333....1111iiii \\\\""""ccccoooolllluuuummmmnnnn wwwwiiiiddddtttthhhh by aaaaffff (§8). ....nnnnrrrr MMMM \\\\\\\\nnnn((((....oooo\\\\""""ssssaaaavvvveeee lllleeeefffftttt mmmmaaaarrrrggggiiiinnnn Another common form is the Typically a portion of the top labeled, indented paragraph, of the first page contains full where the label protrudes left width text; the request for the into the indent space. narrower line length, as well ....ddddeeee llllpppp \\\\""""llllaaaabbbbeeeelllleeeedddd ppppaaaarrrraaaaggggrrrraaaapppphhhh as another ....mmmmkkkk would be made ....ppppgggg where the two column output was ....iiiinnnn 0000....5555iiii \\\\""""ppppaaaarrrraaaaggggrrrraaaapppphhhh iiiinnnnddddeeeennnntttt to begin. ....ttttaaaa 0000....2222iiii 0000....5555iiii\\\\""""llllaaaabbbbeeeellll,,,, ppppaaaarrrraaaaggggrrrraaaapppphhhh TTTT5555.... FFFFoooooooottttnnnnooootttteeee PPPPrrrroooocccceeeessssssssiiiinnnngggg ....ttttiiii 0000 The footnote mechanism to be \\\\tttt\\\\\\\\$$$$1111\\\\tttt\\\\cccc\\\\""""fffflllloooowwww iiiinnnnttttoooo ppppaaaarrrraaaaggggrrrraaaapppphhhh described is used by imbed‐ ........ ding the footnotes in the input The intended usage is "....llllpppp text at the point of reference, _l_a_b_e_l"; _l_a_b_e_l will begin at demarcated by an initial ....ffffnnnn 0.2inch, and cannot exceed and a terminal ....eeeeffff: a length of 0.3inch without ....ffffnnnn intruding into the paragraph. _F_o_o_t_n_o_t_e _t_e_x_t _a_n_d _c_o_n_t_r_o_l _l_i_n_e_s... The label could be right ....eeeeffff adjusted against 0.4inch by In the following, footnotes setting the tabs instead with are processed in a separate ....ttttaaaa 0000....4444iiiiRRRR 0000....5555iiii. The last line environment and diverted for of llllpppp ends with \\\\cccc so that it later printing in the space will become a part of the first immediately prior to the bot‐ line of the text that follows. tom margin. There is provi‐ TTTT4444.... MMMMuuuullllttttiiiipppplllleeee CCCCoooolllluuuummmmnnnn OOOOuuuuttttppppuuuutttt sion for the case where the The production of multiple last collected footnote doesn’t column pages requires the completely fit in the available footer macro to decide whether space. it was invoked by other than ....ddddeeee hhhhdddd \\\\""""hhhheeeeaaaaddddeeeerrrr the last column, so that it .... ‐‐‐ ‐ 94 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 ....nnnnrrrr xxxx 0000 1111 \\\\""""iiiinnnniiiitttt ffffoooooooottttnnnnooootttteeee ccccoooouuuunnnntttt The header hhhhdddd initializes a ....nnnnrrrr yyyy 0000----\\\\\\\\nnnnbbbb\\\\""""ccccuuuurrrrrrrreeeennnntttt ffffooooooootttteeeerrrr ppppllllaaaacfccceoeeeotnote count register xxxx, and ....cccchhhh ffffoooo ----\\\\\\\\nnnnbbbbuuuu\\\\""""rrrreeeesssseeeetttt ffffooooooootttteeeerrrr ttttrrrraaaappppsets both the current footer ....iiiiffff \\\\\\\\nnnn((((ddddnnnn ....ffffzzzz\\\\""""lllleeeeffffttttoooovvvveeeerrrr ffffoooooooottttnnnnooootttteteeerap position register yyyy and ........ the footer trap itself to ....ddddeeee ffffoooo \\\\""""ffffooooooootttteeeerrrr a nominal position specified ....nnnnrrrr ddddnnnn 0000 \\\\""""zzzzeeeerrrroooo llllaaaasssstttt ddddiiiivvvveeeerrrrssssiiiioooonnnn sisssiniiizzzzeeeeregister bbbb. In addi‐ ....iiiiffff \\\\\\\\nnnnxxxx \\\\{{{{\\\\ tion, if the register ddddnnnn indi‐ ....eeeevvvv 1111 \\\\""""eeeexxxxppppaaaannnndddd ffffoooooooottttnnnnooootttteeeessss iiiinnnn eceeevavvv1t111es a leftover footnote, ffffzzzz ....nnnnffff \\\\""""rrrreeeettttaaaaiiiinnnn vvvveeeerrrrttttiiiiccccaaaallll ssssiiiizzzzeeeeis invoked to reprocess it. ....FFFFNNNN \\\\""""ffffoooooooottttnnnnooootttteeeessss The footnote start macro ffffnnnn ....rrrrmmmm FFFFNNNN \\\\""""ddddeeeelllleeeetttteeee iiiitttt begins a diversion (append) in ....iiiiffff """"\\\\\\\\nnnn((((....zzzz""""ffffyyyy"""" ....ddddiiii \\\\""""eeeennnndddd oooovvvveeeerrrrfffflllloeooownwwwvdidddiriiivovvveneeermrrrsesssiniiiotooonnnn1, and increments ....nnnnrrrr xxxx 0000 \\\\""""ddddiiiissssaaaabbbblllleeee ffffxxxx the count xxxx; if the count is ....eeeevvvv \\\\}}}} \\\\""""ppppoooopppp eeeennnnvvvviiiirrrroooonnnnmmmmeeeennnntttt one, the footnote separator ffffssss .... ‐‐‐ is interpolated. The separator ´´´´bbbbpppp is kept in a separate macro to ........ permit user redefinition. The ....ddddeeee ffffxxxx \\\\""""pppprrrroooocccceeeessssssss ffffoooooooottttnnnnooootttteeee oooovvvveeeerfrrrfoffflolllotooownwwwote end macro eeeeffff restores ....iiiiffff \\\\\\\\nnnnxxxx ....ddddiiii ffffyyyy\\\\""""ddddiiiivvvveeeerrrrtttt oooovvvveeeerrrrfffflllloooowwwwthe previous environment and ........ ends the diversion after sav‐ ....ddddeeee ffffnnnn \\\\""""ssssttttaaaarrrrtttt ffffoooooooottttnnnnooootttteeee ing the spacing size in regis‐ ....ddddaaaa FFFFNNNN \\\\""""ddddiiiivvvveeeerrrrtttt ((((aaaappppppppeeeennnndddd)))) ffffoooooooottttntnnnoeoootrttteeeezzzz. yyyy is then decremented ....eeeevvvv 1111 \\\\""""iiiinnnn eeeennnnvvvviiiirrrroooonnnnmmmmeeeennnntttt 1111 by the size of the footnote, ....iiiiffff \\\\\\\\nnnn++++xxxx====1111 ....ffffssss \\\\""""iiiiffff ffffiiiirrrrsssstttt,,,, iiiinnnncccclllluauuudvdddeaeeeislssseaeeepbpppalaaarerrraaaatitttonooorrrrddddnnnn; then on the ....ffffiiii \\\\""""ffffiiiillllllll mmmmooooddddeeee first footnote, yyyy is further ........ decremented by the difference ....ddddeeee eeeeffff \\\\""""eeeennnndddd ffffoooooooottttnnnnooootttteeee in vertical base‐line spacings ....bbbbrrrr \\\\""""ffffiiiinnnniiiisssshhhh oooouuuuttttppppuuuutttt of the two environments, to ....nnnnrrrr zzzz \\\\\\\\nnnn((((....vvvv\\\\""""ssssaaaavvvveeee ssssppppaaaacccciiiinnnngggg prevent the late triggering the ....eeeevvvv \\\\""""ppppoooopppp eeeevvvv footer trap from causing the ....ddddiiii \\\\""""eeeennnndddd ddddiiiivvvveeeerrrrssssiiiioooonnnn last line of the combined foot‐ ....nnnnrrrr yyyy ----\\\\\\\\nnnn((((ddddnnnn\\\\""""nnnneeeewwww ffffooooooootttteeeerrrr ppppoooossssiiiittttiiiionooononnn,t,,,es to overflow. The footer ....iiiiffff \\\\\\\\nnnnxxxx====1111 ....nnnnrrrr yyyy ----((((\\\\\\\\nnnn((((....vvvv----\\\\\\\\nnnnzzzz)))) \t\\\rap is then set to the lower \\\\""""uuuunnnncccceeeerrrrttttaaaaiiiinnnnttttyyyy ccccoooorrrrrrrreeeeccccttttiiiio(ooononnnn the page) of yyyy or the ....cccchhhh ffffoooo \\\\\\\\nnnnyyyyuuuu\\\\""""yyyy iiiissss nnnneeeeggggaaaattttiiiivvvveeee current page position (nnnnllll) plus ....iiiiffff ((((\\\\\\\\nnnn((((nnnnllll++++1111vvvv))))>>>>((((\\\\\\\\nnnn((((....pppp++++\\\\\\\\nnnnyyyy)))) \\\\ one line, to allow for print‐ ....cccchhhh ffffoooo \\\\\\\\nnnn((((nnnnlllluuuu++++1111vvvv \\\\""""iiiitttt ddddiiiiddddnnnn’tttt ffffiiiititttng the reference line. If ........ indicated by xxxx, the footer ffffoooo ....ddddeeee ffffssss \\\\""""sssseeeeppppaaaarrrraaaattttoooorrrr rereads the footnotes from FFFFNNNN \\\\llll´´´´1111iiii´´´´ \\\\""""1111 iiiinnnncccchhhh rrrruuuulllleeee in nofill mode in environment ....bbbbrrrr 1, and deletes FFFFNNNN. If the ........ footnotes were too large to ....ddddeeee ffffzzzz \\\\""""ggggeeeetttt lllleeeeffffttttoooovvvveeeerrrr ffffoooooooottttnnnnoooottttefeeeit, the macro ffffxxxx will be trap‐ ....ffffnnnn invoked to redivert the over‐ ....nnnnffff \\\\""""rrrreeeettttaaaaiiiinnnn vvvveeeerrrrttttiiiiccccaaaallll ssssiiiizzzzeeeeflow into ffffyyyy, and the regis‐ ....ffffyyyy \\\\""""wwwwhhhheeeerrrreeee ffffxxxx ppppuuuutttt iiiitttt ter ddddnnnn will later indicate to ....eeeeffff the header whether ffffyyyy is empty. ........ Both ffffoooo and ffffxxxx are planted in ....nnnnrrrr bbbb 1111....0000iiii\\\\""""bbbboooottttttttoooommmm mmmmaaaarrrrggggiiiinnnn ssssiiiizzzzeeee the nominal footer trap posi‐ ....wwwwhhhh 0000 hhhhdddd \\\\""""hhhheeeeaaaaddddeeeerrrr ttttrrrraaaapppp tion in an order that causes ffffxxxx ....wwwwhhhh 11112222iiii ffffoooo\\\\""""ffffooooooootttteeeerrrr ttttrrrraaaapppp,,,, tttteeeemmmmpppp ppppoooostsssioiiittttiiiiobooonennn concealed unless the ffffoooo ....wwwwhhhh ----\\\\\\\\nnnnbbbbuuuu ffffxxxx\\\\""""ffffxxxx aaaatttt ffffooooooootttteeeerrrr ppppoooossssiiiitttttiriiioaooonpnnn is moved. The footer then ....cccchhhh ffffoooo ----\\\\\\\\nnnnbbbbuuuu\\\\""""ccccoooonnnncccceeeeaaaallll ffffxxxx wwwwiiiitttthhhh ffffotoooerminates the overflow diver‐ ‐ 95 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 sion, if necessary, and zeros xxxx to disable ffffxxxx, because the uncertainty correction together with a not‐too‐late trigger‐ ing of the footer can result in the footnote rereading fin‐ ishing before reaching the ffffxxxx trap. A good exercise for the student is to combine the multiple‐ column and footnote mechanisms. TTTT6666.... TTTThhhheeee LLLLaaaasssstttt PPPPaaaaggggeeee After the last input file has ended, _n_r_o_f_f and _t_r_o_f_f invoke the _e_n_d _m_a_c_r_o (§7), if any, and when it finishes, eject the remainder of the page. During the eject, any traps encoun‐ tered are processed normally. At the _e_n_d of this last page, processing terminates _u_n_l_e_s_s a partial line, word, or partial word remains. If it is desired that another page be started, the end‐macro ....ddddeeee eeeennnn \\\\""""eeeennnndddd‐mmmmaaaaccccrrrroooo \\\\cccc ´´´´bbbbpppp ........ ....eeeemmmm eeeennnn will deposit a null partial word, and effect another last page. ‐ 96 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 TTTTaaaabbbblllleeee IIII FFFFoooonnnntttt SSSSttttyyyylllleeee EEEExxxxaaaammmmpppplllleeeessss The following fonts are printed in 12‐point, with a verti‐ cal spacing of 14‐point, and with non‐alphanumeric characters separated by ¼em space. Note that this table only includes the historical CAT _t_r_o_f_f character set; PostScript devices can usu‐ ally print a much larger, although font‐dependent set of charac‐ ters. Times Roman abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 1234567890 ! $ % & ( ) ‘ ’ * + - . , / : ; = ? [ ] | • □ — ‐ ⎽ ¼ ½ ¾ fi fl ff ffi ffl ° † ′ ¢ ® © _T_i_m_e_s _I_t_a_l_i_c _a_b_c_d_e_f_g_h_i_j_k_l_m_n_o_p_q_r_s_t_u_v_w_x_y_z _A_B_C_D_E_F_G_H_I_J_K_L_M_N_O_P_Q_R_S_T_U_V_W_X_Y_Z _1_2_3_4_5_6_7_8_9_0 ! $ % & ( ) ‘ ’ * + - . , / : ; = ? [ ] | • □ — ‐ ⎽ ¼ ½ ¾ fi fl ff ffi ffl ° † ′ ¢ ® © TTTTiiiimmmmeeeessss BBBBoooolllldddd aaaabbbbccccddddeeeeffffgggghhhhiiiijjjjkkkkllllmmmmnnnnooooppppqqqqrrrrssssttttuuuuvvvvwwwwxxxxyyyyzzzz AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIIIIJJJJKKKKLLLLMMMMNNNNOOOOPPPPQQQQRRRRSSSSTTTTUUUUVVVVWWWWXXXXYYYYZZZZ 1111222233334444555566667777888899990000 !!!! $$$$ %%%% &&&& (((( )))) ‘ ’ **** ++++ - .... ,,,, //// :::: ;;;; ==== ???? [[[[ ]]]] |||| •••• □□□□ ———— ‐‐‐‐ ⎽⎽⎽⎽ ¼¼¼¼ ½½½½ ¾¾¾¾ ffffiiii ffffllll ffffffff ffffffffiiii ffffffffllll °°°° †††† ′′′′ ¢¢¢¢ ®®®® ©©©© Special Font " ´ \ ^ _ ` ~ / < > { } # @ + − = ∗ α β γ δ ε ζ η θ ι κ λ μ ν ξ ο π ρ σ ς τ υ ϕ χ ψ ω Γ Δ Θ Λ Ξ Π Σ Υ Φ Ψ Ω √ ‾ ≥ ≤ ≡ ∼ ≈ ≠ → ← ↑ ↓ × ÷ ± ∪ ∩ ⊂ ⊃ ⊆ ⊇ ∞ ∂ § ∇ ¬ ∫ ∝ ∅ ∈ ‡ ☞ ☜ | ○ ⎧ ⎩ ⎫ ⎭ ⎨ ⎬ ⎪ ⌊ ⌋ ⌈ ⌉ │ ‐ 97 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 TTTTaaaabbbblllleeee IIIIIIII IIIInnnnppppuuuutttt NNNNaaaammmmiiiinnnngggg CCCCoooonnnnvvvveeeennnnttttiiiioooonnnnssss ffffoooorrrr ´´´´,,,, ````,,,, aaaannnndddd ---- aaaannnndddd ffffoooorrrr NNNNoooonnnn‐AAAASSSSCCCCIIIIIIII SSSSppppeeeecccciiiiaaaallll CCCChhhhaaaarrrraaaacccctttteeeerrrrssss NNNNoooonnnn‐AAAASSSSCCCCIIIIIIII cccchhhhaaaarrrraaaacccctttteeeerrrrssss aaaannnndddd _mmmm_iiii_nnnn_uuuu_ssss oooonnnn tttthhhheeee ssssttttaaaannnnddddaaaarrrrdddd ffffoooonnnnttttssss.... _I_n_p_u_t _C_h_a_r_a_c_t_e_r _I_n_p_u_t_C_h_a_r_a_c_t_e_r _C_h_a_r _N_a_m_e _N_a_m_e _C_h_a_r_N_a_m_e _N_a_m_e ’ ' close quote ¾ \(34 3/4 ‘ ` open quote fi \(fi fi — \(em 3/4 Em dash fl \(fl fl ‐ - hyphen or ff \(ff ff ‐ \(hy hyphen ffi \(Fi ffi - \- current font minus ffl \(Fl ffl • \(bu bullet ° \(de degree □ \(sq square † \(dg dagger ⎽ \(ru rule ′ \(fm foot mark ¼ \(14 1/4 ¢ \(ct cent sign ½ \(12 1/2 ® \(rg registered © \(co copyright NNNNoooonnnn‐AAAASSSSCCCCIIIIIIII cccchhhhaaaarrrraaaacccctttteeeerrrrssss aaaannnndddd ´´´´,,,, ````,,,, ____,,,, ++++,,,, −−−−,,,, ====,,,, aaaannnndddd ∗∗∗∗ oooonnnn tttthhhheeee ssssppppeeeecccciiiiaaaallll ffffoooonnnntttt.... In traditional _t_r_o_f_f, the ASCII characters @, #, ", ´, `, <, >, \, {, }, ~, ^, and _ existed _o_n_l_y on the special font and were printed as a 1‐em space if that font was not mounted. The fol‐ lowing characters exist only on the special font. The special math plus, minus, and equals are provided to insulate the appear‐ ance of equations from the choice of standard fonts. _I_n_p_u_t _C_h_a_r_a_c_t_e_r _I_n_p_u_t_C_h_a_r_a_c_t_e_r _C_h_a_r _N_a_m_e _N_a_m_e _C_h_a_r_N_a_m_e _N_a_m_e + \(pl math plus θ \(*h theta − \(mi math minus ι \(*i iota = \(eq math equals κ \(*k kappa ∗ \(** math star λ \(*l lambda § \(sc section μ \(*m mu ´ \(aa acute accent ν \(*n nu ` \(ga grave accent ξ \(*c xi _ \(ul underrule ο \(*o omicron / \(sl slash (matching backslπash)\(*p pi \ \(rs backslash ρ \(*r rho α \(*a alpha σ \(*s sigma β \(*b beta ς \(ts terminal sigma γ \(*g gamma τ \(*t tau δ \(*d delta υ \(*u upsilon ε \(*e epsilon ϕ \(*f phi ζ \(*z zeta χ \(*x chi η \(*y eta ψ \(*q psi ‐ 98 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _I_n_p_u_t _C_h_a_r_a_c_t_e_r _I_n_p_u_t_C_h_a_r_a_c_t_e_r _C_h_a_r _N_a_m_e _N_a_m_e _C_h_a_r_N_a_m_e _N_a_m_e ω \(*w omega ∝ \(pt proportional to Α \(*A Alpha ∅ \(es empty set Β \(*B Beta ∈ \(mo member of Γ \(*G Gamma │ \(br box vertical rule Δ \(*D Delta ‡ \(dd double dagger Ε \(*E Epsilon ☞ \(rh right hand Ζ \(*Z Zeta ☜ \(lh left hand Η \(*Y Eta | \(or or Θ \(*H Theta ○ \(ci circle Ι \(*I Iota ⎧ \(lt left top of big curly bracket Κ \(*K Kappa ⎩ \(lb left bottom Λ \(*L Lambda ⎫ \(rt right top Μ \(*M Mu ⎭ \(rb right bot Ν \(*N Nu ⎨ \(lk left center of big curly bracket Ξ \(*C Xi ⎬ \(rk right center of big curly bracket Ο \(*O Omicron ⎪ \(bv bold vertical Π \(*P Pi ⌊ \(lf left floor (left bottom of big Ρ \(*R Rho square bracket) Σ \(*S Sigma ⌋ \(rf right floor (right bottom) Τ \(*T Tau ⌈ \(lc left ceiling (left top) Υ \(*U Upsilon ⌉ \(rc right ceiling (right top) Φ \(*F Phi Χ \(*X Chi Ψ \(*Q Psi Ω \(*W Omega √ \(sr square root ‾ \(rn root en extender ≥ \(>= >= ≤ \(<= <= ≡ \(== identically equal ≈ \(~= approx = ∼ \(ap approximates ≠ \(!= not equal → \(−> right arrow ← \(<− left arrow ↑ \(ua up arrow ↓ \(da down arrow × \(mu multiply ÷ \(di divide ± \(+− plus‐minus ∪ \(cu cup (union) ∩ \(ca cap (intersection) ⊂ \(sb subset of ⊃ \(sp superset of ⊆ \(ib improper subset ⊇ \(ip improper superset ∞ \(if infinity ∂ \(pd partial derivative ∇ \(gr gradient ¬ \(no not ∫ \(is integral sign ‐ 99 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 AAAAvvvvaaaaiiiillllaaaabbbblllleeee cccchhhhaaaarrrraaaacccctttteeeerrrrssss ffffrrrroooommmm ggggrrrrooooffffffff____cccchhhhaaaarrrr((((7777)))) The following table list the characters from the ggggrrrrooooffffffff____cccchhhhaaaarrrr(7) manual page which can be used with Heirloom _t_r_o_f_f. Special char‐ acters marked with a **** are only defined when _t_r_o_f_f is started with option ----mmmmggggcccchhhhaaaarrrr. If a glyph is actually available depends on the font and output device. _O_u_t_p_u_t _I_n_p_u_t _P_o_s_t_S_c_r_i_p_t_U_n_i_c_o_d_e_N_o_t_e_s ¡ ¡ \[exclamdown] \U'00A1'inverted exclamation mark ¢ ¢ \[cent] \U'00A2'currency unit £ £ \[sterling] \U'00A3'pound sterling ¤ ¤ \[currency] \U'00A4'generic currency symbol ¥ ¥ \[yen] \U'00A5'Japanese currency symbol ¦ ¦ \[brokenbar] \U'00A6'broken bar § § \[section] \U'00A7'section sign ¨ ¨ \[dieresis] \U'00A8'dieresis © © \[copyright] \U'00A9'copyright symbol ª ª \[ordfeminine] \U'00AA'feminine ordinal « « \[guillemotleft] \U'00AB'left guillemet [sic] ¬ ¬ \[logicalnot] \U'00AC'logical not ® ® \[registered] \U'00AE'registered mark symbol ¯ ¯ \[macron] \U'00AF'overbar accent ° ° \[degree] \U'00B0'degree ± ± \[plusminus] \U'00B1'plus‐minus sign ² ² \[twosuperior] \U'00B2'superscript 2 ³ ³ \[threesuperior] \U'00B3'superscript 3 ´ ´ \[acute] \U'00B4'acute accent µ µ \[mu] \U'00B5'micro sign ¶ ¶ \[paragraph] \U'00B6'end of paragraph marker · · \[periodcentered] \U'00B7'centered period ¸ ¸ \[cedilla] \U'00B8'cedilly accent ¹ ¹ \[onesuperior] \U'00B9'superscript 1 º º \[ordmasculine] \U'00BA'masculine ordinal » » \[guillemotright] \U'00BB'right guillemet [sic] ¼ ¼ \[onequarter] \U'00BC'1/4 symbol ½ ½ \[onehalf] \U'00BD'1/2 symbol ¾ ¾ \[threequarters] \U'00BE'3/4 symbol ¿ ¿ \[questiondown] \U'00BF'inverted question mark À À \[Agrave] \U'00C0'A grave Á Á \[Aacute] \U'00C1'A acute   \[Acircumflex] \U'00C2'A circumflex à à \[Atilde] \U'00C3'A tilde Ä Ä \[Adieresis] \U'00C4'A dieresis Å Å \[Aring] \U'00C5'A ring Æ Æ \[AE] \U'00C6'A+E combined Ç Ç \[Ccedilla] \U'00C7'C cedilla È È \[Egrave] \U'00C8'E grave É É \[Eacute] \U'00C9'E acute Ê Ê \[Ecircumflex] \U'00CA'E circumflex Ë Ë \[Edieresis] \U'00CB'E dieresis Ì Ì \[Igrave] \U'00CC'I grave Í Í \[Iacute] \U'00CD'I acute ‐ 100 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _O_u_t_p_u_t _I_n_p_u_t _P_o_s_t_S_c_r_i_p_t_U_n_i_c_o_d_e_N_o_t_e_s Î Î \[Icircumflex] \U'00CE'I circumflex Ï Ï \[Idieresis] \U'00CF'I dieresis Ð Ð \[Eth] \U'00D0'E th Ñ Ñ \[Ntilde] \U'00D1'N tilde Ò Ò \[Ograve] \U'00D2'O grave Ó Ó \[Oacute] \U'00D3'O acute Ô Ô \[Ocircumflex] \U'00D4'O circumflex Õ Õ \[Otilde] \U'00D5'O tilde Ö Ö \[Odieresis] \U'00D6'O dieresis × × \[multiply] \U'00D7'multiply Ø Ø \[Oslash] \U'00D8'O slash Ù Ù \[Ugrave] \U'00D9'U grave Ú Ú \[Uacute] \U'00DA'U acute Û Û \[Ucircumflex] \U'00DB'U circumflex Ü Ü \[Udieresis] \U'00DC'U dieresis Ý Ý \[Yacute] \U'00DD'Y acute Þ Þ \[Thorn] \U'00DE'Thorn ß ß \[germandbls] \U'00DF'German double s à à \[agrave] \U'00E0'a grave á á \[aacute] \U'00E1'a acute â â \[acircumflex] \U'00E2'a circumflex ã ã \[atilde] \U'00E3'a tilde ä ä \[adieresis] \U'00E4'a dieresis å å \[aring] \U'00E5'a ring æ æ \[ae] \U'00E6'a+e combined ç ç \[ccedilla] \U'00E7'c cedilla è è \[egrave] \U'00E8'e grave é é \[eacute] \U'00E9'e acute ê ê \[ecircumflex] \U'00EA'e circumflex ë ë \[edieresis] \U'00EB'e dieresis ì ì \[igrave] \U'00EC'i grave í í \[iacute] \U'00ED'i acute î î \[icircumflex] \U'00EE'i circumflex ï ï \[idieresis] \U'00EF'i dieresis ð ð \[eth] \U'00F0'e th ñ ñ \[ntilde] \U'00F1'n tilde ò ò \[ograve] \U'00F2'o grave ó ó \[oacute] \U'00F3'o acute ô ô \[ocircumflex] \U'00F4'o circumflex õ õ \[otilde] \U'00F5'o tilde ö ö \[odieresis] \U'00F6'o dieresis ÷ ÷ \[divide] \U'00F7'divide ø ø \[oslash] \U'00F8'o slash ù ù \[ugrave] \U'00F9'u grave ú ú \[uacute] \U'00FA'u acute û û \[ucircumflex] \U'00FB'u circumflex ü ü \[udieresis] \U'00FC'u dieresis ý ý \[yacute] \U'00FD'y acute þ þ \[thorn] \U'00FE'thorn ÿ ÿ \[ydieresis] \U'00FF'y dieresis Ð \(−D* \[Eth] \U'00D0'uppercase eth ð \(Sd* \[eth] \U'00F0'lowercase eth ‐ 101 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _O_u_t_p_u_t _I_n_p_u_t _P_o_s_t_S_c_r_i_p_t_U_n_i_c_o_d_e_N_o_t_e_s Þ \(TP* \[Thorn] \U'00DE'uppercase thorn þ \(Tp* \[thorn] \U'00FE'lowercase thorn ß \(ss* \[germandbls] \U'00DF'German double s Ł \(/L* \[Lslash] \U'0141'L slash ł \(/l* \[lslash] \U'0142'l slash Ø \(/O* \[Oslash] \U'00D8'O slash ø \(/o* \[oslash] \U'00F8'o slash Æ \(AE \[AE] \U'00C6'A+E combined æ \(ae \[ae] \U'00E6'a+e combined Œ \(OE \[OE] \U'0152'O+E combined œ \(oe \[oe] \U'0153'o+e combined IJ \(IJ \[IJ] \U'0132'I+J combined ij \(ij \[ij] \U'0133'i+j combined ı \(.i* \[dotlessi] \U'0131'i without a dot Á \('A* \[Aacute] \U'00C1'A acute Ć \('C* \[Cacute] \U'0106'C acute É \('E* \[Eacute] \U'00C9'E acute Í \('I* \[Iacute] \U'00CD'C acute Ó \('O* \[Oacute] \U'00D3'O acute Ú \('U* \[Uacute] \U'00DA'U acute Ý \('Y* \[Yacute] \U'00DD'Y acute á \('a* \[aacute] \U'00E1'a acute ć \('c* \[cacute] \U'0107'c acute é \('e* \[eacute] \U'00E9'e acute í \('i* \[iacute] \U'00ED'i acute ó \('o* \[oacute] \U'00F3'o acute ú \('u* \[uacute] \U'00FA'u acute ý \('y* \[yacute] \U'00FD'y acute Ä \(:A* \[Adieresis] \U'00C4'A dieresis Ë \(:E* \[Edieresis] \U'00CB'E dieresis Ï \(:I* \[Idieresis] \U'00CF'I dieresis Ö \(:O* \[Odieresis] \U'00D6'O dieresis Ü \(:U* \[Udieresis] \U'00FC'U dieresis Ÿ \(:Y* \[Ydieresis] \U'0178'Y dieresis ä \(:a* \[adieresis] \U'00E4'a dieresis ë \(:e* \[edieresis] \U'00EB'e dieresis ï \(:i* \[idieresis] \U'00EF'i dieresis ö \(:o* \[odieresis] \U'00F6'o dieresis ü \(:u* \[udieresis] \U'00FC'u dieresis ÿ \(:y* \[ydieresis] \U'00FF'y dieresis  \(^A* \[Acircumflex] \U'00C2'A circumflex Ê \(^E* \[Ecircumflex] \U'00CA'E circumflex Î \(^I* \[Icircumflex] \U'00CE'I circumflex Ô \(^O* \[Ocircumflex] \U'00D4'O circumflex Û \(^U* \[Ucircumflex] \U'00DB'U circumflex â \(^a* \[acircumflex] \U'00E2'a circumflex ê \(^e* \[ecircumflex] \U'00EA'e circumflex î \(^i* \[icircumflex] \U'00EE'i circumflex ô \(^o* \[ocircumflex] \U'00F4'o circumflex û \(^u* \[ucircumflex] \U'00FB'u circumflex À \(`A* \[Agrave] \U'00C0'A grave ‐ 102 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _O_u_t_p_u_t _I_n_p_u_t _P_o_s_t_S_c_r_i_p_t_U_n_i_c_o_d_e_N_o_t_e_s È \(`E* \[Egrave] \U'00C8'E grave Ì \(`I* \[Igrave] \U'00CC'I grave Ò \(`O* \[Ograve] \U'00D2'O grave Ù \(`U* \[Ugrave] \U'00D9'U grave à \(`a* \[agrave] \U'00E0'a grave è \(`e* \[egrave] \U'00E8'e grave ì \(`i* \[igrave] \U'00EC'i grave ò \(`o* \[ograve] \U'00F2'o grave ù \(`u* \[ugrave] \U'00F9'u grave à \(~A* \[Atilde] \U'00C3'A tilde Ñ \(~N* \[Ntilde] \U'00D1'N tilde Õ \(~O* \[Otilde] \U'00D5'O tilde ã \(~a* \[atilde] \U'00E3'a tilde ñ \(~n* \[ntilde] \U'00F1'n tilde õ \(~o* \[otilde] \U'00F5'o tilde Š \(vS* \[Scaron] \U'0160'S caron š \(vs* \[scaron] \U'0161's caron Ž \(vZ* \[Zcaron] \U'017D'Z caron ž \(vz* \[zcaron] \U'017E'z caron Ç \(,C* \[Ccedilla] \U'00C7'C cedilla ç \(,c* \[ccedilla] \U'00E7'c cedilla Å \(oA* \[Aring] \U'00C5'A ring å \(oa* \[aring] \U'00E5'a ring ˝ \(a"* \[hungarumlaut] \U'02DD'Hungarian umlaut ¯ \(a−* \[macron] \U'00AF'overbar accent ˙ \(a.* \[dotaccent] \U'02D9'dot accent ^ \(a^* \[circumflex] \U'005E'circumflex accent ´ \(aa \[acute] \U'00B4'acute accent ` \(ga \[grave] \U'0060'grave accent ˘ \(ab* \[breve] \U'02D8'breve accent ¸ \(ac* \[cedilla] \U'00B8'cedilla accent ¨ \(ad* \[dieresis] \U'00A8'umlaut accent ˇ \(ah* \[caron] \U'02C7'caron accent ˚ \(ao* \[ring] \U'02DA'ring accent ˜ \(a~* \[tilde] \U'007E'tilde accent ˛ \(ho* \[ogonek] \U'02dB'hook accent ^ \(ha* \[asciicircum] \U'005E'high circumflex ~ \(ti* \[asciitilde] \U'007E'tilde in the vertical middle „ \(Bq* \[quotedblbase] \U'201E'low double comma quote ‚ \(bq* \[quotesinglbase] \U'201A'low single comma quote “ \(lq \[quotedblleft] \U'201C'left double quote “ \(`` (_a_l_i_a_s) ” \(rq \[quotedblright] \U'201D'right double quote ” \('' (_a_l_i_a_s) ‘ \(oq \[quoteleft] \U'2018'single open quote ’ \(cq \[quoteright] \U'2019'single closing quote ' \(aq \[quotesingle] \U'0027'apostrophe quote " \(dq \[quotedbl] \U'0022'double quote « \(Fo* \[guillemotleft] \U'00AB'left guillemet » \(Fc* \[guillemotright] \U'00BB'right guillemet ‹ \(fo* \[guilsinglleft] \U'2039'single left angle quotation mark › \(fc* \[guilsinglright] \U'203A'single right angle quotation mark ‐ 103 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _O_u_t_p_u_t _I_n_p_u_t _P_o_s_t_S_c_r_i_p_t_U_n_i_c_o_d_e_N_o_t_e_s ¡ \(r!* \[exclamdown] \U'00A1'inverted exclamation mark ¿ \(r?* \[questiondown] \U'00BF'inverted question mark — \(em \[emdash] \U'2014'em‐dash symbol – \(en \[endash] \U'2013'en‐dash symbol ‐ \(hy \[hyphen] \U'2010'hyphen symbol [ \(lB* \[bracketleft] \U'005B'left square bracket ] \(rB* \[bracketright] \U'005D'right square bracket { \(lC* \[braceleft] \U'007B'left curly bracket } \(rC* \[braceright] \U'007D'right curly bracket ⟨ \(la* \[angleleft] \U'27E8'mathematical left angle bracket ⟩ \(ra* \[angleright] \U'27E9'mathematical right angle bracket ⎪ \(bv \[braceex] \U'23AA'curly brace vertical extension ⎡ \[bracketlefttp] \U'23A1'left square bracket top ⎣ \[bracketleftbt] \U'23A3'left square bracket bottom ⎢ \[bracketleftex] \U'23A2'left square bracket extension ⎤ \[bracketrighttp] \U'23A4'right square bracket top ⎦ \[bracketrightbt] \U'23A6'right square bracket bottom ⎥ \[bracketrightex] \U'23A5'right square bracket extension ⎧ \(lt \[bracelefttp] \U'23A7'left curly brace top ⎨ \(lk \[braceleftmid] \U'23A8'left curly brace middle ⎩ \(lb \[braceleftbt] \U'23A9'left curly brace bottom ⎪ \[braceleftex] \U'23AA'left curly brace extension ⎫ \(rt \[bracerighttp] \U'23AB'right curly brace top ⎬ \(rk \[bracerightmid] \U'23AC'right curly brace middle ⎭ \(rb \[bracerightbt] \U'23AD'right curly brace bottom ⎪ \[bracerightex] \U'23AA'right curly brace extension ⎛ \[parenlefttp] \U'239B'left parenthesis top ⎝ \[parenleftbt] \U'239D'left parenthesis bottom ⎜ \[parenleftex] \U'239C'left parenthesis extension ⎞ \[parenrighttp] \U'239E'right parenthesis top ⎠ \[parenrightbt] \U'23A0'right parenthesis bottom ⎟ \[parenrightex] \U'239F'right parenthesis extension ← \(<− \[arrowleft] \U'2190'arrow left → \(−> \[arrowright] \U'2192'arrow right ↔ \(<>* \[arrowboth] \U'2194'horizontal arrow in both directions ↓ \(da \[arrowdown] \U'2193'arrow down ↑ \(ua \[arrowup] \U'2191'arrow up ↕ \(va* \[arrowupdn] \U'2195'vertical arrow in both directions ⇐ \(lA* \[arrowdblleft] \U'21D0'double arrow left ⇒ \(rA* \[arrowdblright] \U'21D2'double arrow right ⇔ \(hA* \[arrowdblboth] \U'21D4'horizontal double arrow in both directions ⇓ \(dA* \[arrowdbldown] \U'21D3'double arrow down ⇑ \(uA* \[arrowdblup] \U'21D1'double arrow up ⇕ \(vA* \[uni21D5] \U'21D5'vertical double arrow in both directions ⎯ \(an* \[arrowhorizex] \U'23AF'horizontal arrow extension | \(ba* \[bar] \U'007C'bar │ \(br \[SF110000] \U'2502'box rule _ \(ul \[underscore] \U'005F'underscore ‾ \(rn \[overline] \U'203E'overline ⎽ \(ru baseline rule ¦ \(bb* \[brokenbar] \U'00A6'broken bar / \(sl \[slash] \U'002F'slash ‐ 104 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _O_u_t_p_u_t _I_n_p_u_t _P_o_s_t_S_c_r_i_p_t_U_n_i_c_o_d_e_N_o_t_e_s \ \(rs \[backslash] \U'005C'revers slash ○ \(ci \[circle] \U'25CB'circle • \(bu \[bullet] \U'2022'bullet ‡ \(dd \[daggerdbl] \U'2021'double dagger † \(dg \[dagger] \U'2020'dagger ◊ \(lz* \[lozenge] \U'25CA'diamond □ \(sq \[uni25A1] \U'25A1'square ¶ \(ps* \[paragraph] \U'00B6'end of paragraph marker § \(sc \[section] \U'00A7'section sign ☜ \(lh \[uni261C] \U'261C'hand pointing left ☞ \(rh \[a14] \U'261E'hand pointing right @ \(at \[at] \U'0040'at # \(sh* \[numbersign] \U'0023'number sign ↵ \(CR* \[carriagereturn] \U'21B5'carriage return ✓ \(OK* \[a19] \U'2713'check mark © \(co \[copyright] \U'00A9'copyright sign ® \(rg \[registered] \U'00AE'registered mark ™ \(tm \[trademark] \U'2122'trademark symbol \(bs AT&T Bell Labs logo $ \(Do* \[dollar] \U'0024'dollar ¢ \(ct \[cent] \U'00A2'cent € \(Eu* \[Euro] \U'20AC'font‐specific Euro glyph ¥ \(Ye* \[yen] \U'00A5'Japanese Yen £ \(Po* \[sterling] \U'00A3'pound sterling ¤ \(Cs* \[currency] \U'00A4'Scandinavian currency sign ƒ \(Fn* \[florin] \U'0192'Dutch currency sign ° \(de \[degree] \U'00B0'degree ‰ \(%0* \[perthousand] \U'2030'per thousand ′ \(fm \[minute] \U'2032'arc minute sign ″ \(sd* \[second] \U'2033'arc second sign µ \(mc* \[mu] \U'00B5'micro sign ª \(Of* \[ordfeminine] \U'00AA'feminine ordinal º \(Om* \[ordmasculine] \U'00BA'masculine ordinal ∧ \(AN* \[logicaland] \U'2227'logical and ∨ \(OR* \[logicalor] \U'2228'logical or ¬ \(no logical not ¬ \[tno]* \[logicalnot]\U'00AC'text variant of ‘no’ ∃ \(te \[existential] \U'2203'there exists ∀ \(fa \[universal] \U'2200'for all ∋ \(st* \[suchthat] \U'220B'such that ∴ \(3d* \[therefore] \U'2234'therefor ∴ \(tf* (_a_l_i_a_s) | \(or \[bar] \U'007C'bitwise OR ½ \(12 \[onehalf] \U'00BD'1/2 symbol ¼ \(14 \[onequarter] \U'00BC'1/4 symbol ¾ \(34 \[threequarters] \U'00BE'3/4 symbol ⅛ \(18* \[oneeighth] \U'215B'1/8 symbol ⅜ \(38* \[threeeighths] \U'215C'3/8 symbol ⅝ \(58* \[fiveeighths] \U'215D'5/8 symbol ⅞ \(78* \[seveneighths] \U'215E'7/8 symbol ¹ \(S1* \[onesuperior] \U'00B9'superscript 1 ² \(S2* \[twosuperior] \U'00B2'superscript 2 ‐ 105 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _O_u_t_p_u_t _I_n_p_u_t _P_o_s_t_S_c_r_i_p_t_U_n_i_c_o_d_e_N_o_t_e_s ³ \(S3* \[threesuperior] \U'00B3'superscript 2 + \(pl \[plus] \U'002B'plus − \(mi \[minus] \U'2212'minus ∓ \(−+* \[uni2213] \U'2213'minus‐plus ± \(+− plus‐minus ± \[t+−]* \[plusminus]\U'00B1'text variant of plus‐minus · \(pc* \[periodcentered] \U'00B7'period centered ⋅ \(md* \[dotmath] \U'22C5'multiplication dot × \(mu multiply sign × \[tmu]* \[multiply]\U'00D7'text variant of multiply sign ⊗ \(c** \[circlemultiply] \U'2297'multiply sign in circle ⊕ \(c+* \[circleplus] \U'2295'plus sign in circle ÷ \(di division sign ÷ \[tdi]* \[divide]\U'00F7'text variant of division sign \(f/* \[fraction] \U'2044'bar for fractions ∗ \(** \[asteriskmath] \U'2217'mathematical asterisk ≤ \(<= \[lessequal] \U'2264'less or equal ≥ \(>= \[greaterequal] \U'2265'greater or equal ≪ \(<<* \[uni226A] \U'226A'much less ≫ \(>>* \[uni226B] \U'226B'much greater = \(eq \[equal] \U'003D'equal ≠ \(!= \[notequal] \U'2260'not equal ≡ \(== \[equivalence] \U'2261'equivalent ≢ \(ne* \[uni2262] \U'2262'not equivalent ≅ \(=~* \[congruent] \U'2245'congruent ∼ \(ap \[similar] \U'223C'similar ≈ \(~~ \[approxequal] \U'2248'almost equal to ∝ \(pt \[proportional] \U'221D'proportional ∅ \(es \[emptyset] \U'2205'empty set ∈ \(mo \[element] \U'2208'element of ∉ \(nm* \[notelement] \U'2209'not element of ⊂ \(sb \[propersubset] \U'2282'proper subset ⊄ \(nb* \[notsubset] \U'2284'not subset ⊃ \(sp \[propersuperset] \U'2283'proper superset ⊅ \(nc* \[uni2285] \U'2285'not superset ⊆ \(ib \[reflexsubset] \U'2286'subset or equal ⊇ \(ip \[reflexsuperset] \U'2287'superset or equal ∩ \(ca \[intersection] \U'2229'intersection ∪ \(cu \[union] \U'222A'union ∠ \(/_* \[angle] \U'2220'angle ⊥ \(pp* \[perpendicular] \U'22A5'perpendicular ∫ \(is \[integral] \U'222B'integral Σ \(*S \[summation] \U'2211'summation ∑ \[sum]* (_a_l_i_a_s) Π \(*P \[product] \U'220F'product ∐ \[coproduct]* \U'2210'coproduct ∇ \(gr \[gradient] \U'2207'gradient √ \(sr \[radical] \U'221A'square root √ \[sqrt]* (_a_l_i_a_s) \[radicalex] square root continuation \[sqrtex]* (_a_l_i_a_s) ⌈ \(lc \[uni2308] \U'2308'left ceiling ‐ 106 ‐ _n_r_o_f_f/_t_r_o_f_f User’s Manual Heirloom Documentation Tools February 10, 2016 _O_u_t_p_u_t _I_n_p_u_t _P_o_s_t_S_c_r_i_p_t_U_n_i_c_o_d_e_N_o_t_e_s ⌉ \(rc \[uni2309] \U'2309'right ceiling ⌊ \(lf \[uni230A] \U'230A'left floor ⌋ \(rf \[uni230B] \U'230B'right floor ∞ \(if \[infinity] \U'221E'infinity ℵ \(Ah* \[aleph] \U'2135'aleph ℑ \(Im* \[Ifraktur] \U'2111'Gothic I, imaginary ℜ \(Re* \[Rfraktur] \U'211C'Gothic R, real ℘ \(wp* \[weierstrass] \U'2118'Weierstrass p ∂ \(pd \[partialdiff] \U'2202'partial differentiation ℏ \(−h* \[hbar] \U'210F'Planck constant / 2pi (h‐bar) ϑ \(+h* \[theta1] \U'03D1'variant theta φ \(+f* \[phi1] \U'03C6'variant phi ϖ \(+p* \[omega1] \U'03D6'variant pi ϵ \(+e* \[uni03F5] \U'03F5'variant epsilon ♣ \(CL* \[club] \U'2663'black club suit ♠ \(SP* \[spade] \U'2660'black spade suit ♥ \(HE* \[heart] \U'2665'black heart suit ♡ \[uni2661] \U'2661'white heart suit ♦ \(DI* \[diamond] \U'2666'black diamond suit ♢ \[uni2662] \U'2662'white diamond suit ‐ 107 ‐