1
0

troff.html 108 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348
  1. <html>
  2. <title>
  3. -
  4. </title>
  5. <body BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#330088" ALINK="#FF0044">
  6. <H1>Troff User's Manual
  7. </H1>
  8. <DL><DD><I>Joseph F. Ossanna<br>
  9. Brian W. Kernighan<br>
  10. <br>&#32;<br>
  11. bwk@research.bell-labs.com<br>
  12. </I></DL>
  13. <H4>Introduction
  14. </H4>
  15. <P>
  16. <I>Troff</I> and <I>nroff</I> are text processors
  17. that format text for typesetter- and
  18. typewriter-like terminals, respectively.
  19. They accept lines of text interspersed with lines of
  20. format control information and
  21. format the text into a printable, paginated document
  22. having a user-designed style.
  23. <I>Troff</I> and <I>nroff</I> offer
  24. unusual freedom in document styling:
  25. arbitrary style headers and footers;
  26. arbitrary style footnotes;
  27. multiple automatic sequence numbering for paragraphs, sections, etc;
  28. multiple column output;
  29. dynamic font and point-size control;
  30. arbitrary horizontal and vertical local motions at any point;
  31. and
  32. a family of automatic overstriking, bracket construction, and
  33. line-drawing functions.
  34. </P>
  35. <P>
  36. <I>Troff</I>
  37. produces its output in a device-independent form,
  38. although parameterized for a specific device;
  39. <I>troff</I> output must be processed by a driver for that
  40. device to produce printed output.
  41. </P>
  42. <P>
  43. <I>Troff</I> and <I>nroff</I> are highly compatible with each other and it is almost always
  44. possible to prepare input acceptable to both.
  45. Conditional input is provided to enable
  46. the user to embed input expressly destined for either program.
  47. <I>Nroff</I> can prepare output directly for a variety of terminal types and
  48. is capable of utilizing the full resolution of each terminal.
  49. <I>Nroff</I> is the same program as <I>troff</I>; in fact, on Plan 9
  50. <I>nroff</I> is a shell script that calls <I>troff</I> with the
  51. argument.
  52. </P>
  53. <H4>Background to the Plan 9 Edition
  54. </H4>
  55. <P>
  56. The primary change to <I>troff</I> and <I>nroff</I> for Plan 9 is
  57. support of the Unicode Standard, which was added during
  58. 1992 and 1993. There are two results. First, there is much
  59. less need for the myriad of two-character names that are so
  60. much a part of <I>troff</I> lore; in Plan 9, for example, one naturally uses the
  61. Unicode character &#189; instead of <I>troff</I>'s
  62. Second, the output device, though called
  63. is almost always a form of PostScript printer;
  64. the panoply of special drivers for different typesetters
  65. has largely disappeared.
  66. Unfortunately, not all PostScript printers can cope
  67. with Unicode characters, so there remains a need for
  68. programs that synthesize PostScript characters from bitmaps;
  69. this is especially true for Asian languages.
  70. </P>
  71. <H4>Background to the Second Edition
  72. </H4>
  73. <P>
  74. <I>Troff</I>
  75. was originally written by the late Joe Ossanna
  76. in about 1973, in assembly language for the
  77. PDP-11,
  78. to drive the Graphic Systems CAT typesetter.
  79. It was rewritten in C around 1975,
  80. and underwent slow but steady evolution until
  81. Ossanna's death late in 1977.
  82. </P>
  83. <P>
  84. In 1979, Brian Kernighan
  85. modified
  86. <I>troff</I>
  87. so that it would produce output for a variety of typesetters,
  88. while retaining its input specifications.
  89. Over the decade from 1979 to 1989,
  90. the internals
  91. have been modestly revised,
  92. though much of the code remains as it was when Ossanna wrote it.
  93. </P>
  94. <P>
  95. <I>Troff</I>
  96. reads parameter files
  97. each time it is invoked, to
  98. set values for machine resolution,
  99. legal type sizes and fonts, and character names,
  100. character widths
  101. and the like.
  102. <I>Troff</I>
  103. output is
  104. ASCII
  105. characters
  106. in a simple language
  107. that describes where each character is to be placed
  108. and in what size and font.
  109. A post-processor must be written for each device
  110. to convert this typesetter-independent language
  111. into specific instructions for that device.
  112. </P>
  113. <P>
  114. The output language contains information that was not readily
  115. identifiable in the older output.
  116. In the newer language, the beginning of each page, line, and word
  117. is marked,
  118. so post-processors can do device-specific optimizations
  119. such as sorting the data vertically or printing it boustrophedonically,
  120. independent of
  121. <I>troff</I>.
  122. </P>
  123. <P>
  124. Capabilities for graphics have been added:
  125. <I>troff</I>
  126. recognizes commands for drawing diagonal lines,
  127. circles, ellipses, circular arcs,
  128. and quadratic B-splines.
  129. There are also ways to pass arbitrary information to the output,
  130. unprocessed by
  131. <I>troff</I>.
  132. </P>
  133. <P>
  134. A number of limitations have been eased or eliminated.
  135. A document may have an arbitrary number of fonts on any page
  136. (if the output device permits it, of course).
  137. Fonts may be accessed merely by naming them;
  138. ``mounting'' is no longer necessary.
  139. There are no limits on the number of characters.
  140. Character height and slant may be set
  141. independently of width.
  142. </P>
  143. <P>
  144. The remainder of this document contains a description of
  145. usage and command-line options;
  146. a summary of requests, escape sequences, and pre-defined number registers;
  147. a reference manual;
  148. tutorial examples;
  149. and a list of commonly-available characters.
  150. </P>
  151. <H4>Acknowledgements
  152. </H4>
  153. <P>
  154. Joe Ossanna's
  155. <I>troff</I>
  156. remains a remarkable accomplishment.
  157. For more than twenty years, it has proven a robust tool,
  158. taking unbelievable abuse from a variety of preprocessors
  159. and being forced into uses that were never conceived of
  160. in the original design,
  161. all with considerable grace under fire.
  162. </P>
  163. <P>
  164. Recent versions of <I>troff</I> have profited from
  165. significant code improvements by
  166. Jaap Akkerhuis, Dennis Ritchie, Ken Thompson, and Molly Wagner.
  167. UTF facilities owe much to Jaap Akkerhuis.
  168. Andrew Hume, Doug McIlroy, Peter Nelson and Ravi Sethi made valuable suggestions on the manual.
  169. I fear that the remaining bugs are my fault.
  170. <br>&#32;<br>
  171. <HR>
  172. <br>&#32;<br>
  173. </P>
  174. <br>&#32;<br>
  175. <B>Usage
  176. </B><P>
  177. <I>Troff</I> or <I>nroff</I> is invoked as
  178. <DL><DT><DD><TT><PRE>
  179. troff <I>options files</I>
  180. nroff <I>options files</I>
  181. </PRE></TT></DL>
  182. where <I>options</I> represents any of a number of option arguments
  183. and <I>files</I> represents the list of files containing the document
  184. to be formatted.
  185. An argument consisting of a single minus
  186. represents standard input.
  187. If no filenames are given input is taken from the standard input.
  188. The options, which may appear in any order so long as they appear
  189. before the files, are:
  190. <br><img src="-.16251.gif"><br>
  191. </P>
  192. <P>
  193. Each option is a separate argument;
  194. for example,
  195. <DL><DT><DD><TT><PRE>
  196. troff -Tutf -ms -mpictures -o4,6,8-10 <I>file1 file2</I>
  197. </PRE></TT></DL>
  198. requests formatting of pages 4, 6, and 8 through 10 of a document contained in the files
  199. named <I>file1</I> and <I>file2</I>,
  200. specifies the output in UTF,
  201. and invokes the macro packages
  202. and
  203. </P>
  204. <P>
  205. Various pre- and post-processors are available for use with <I>nroff</I> and <I>troff</I>.
  206. These include the equation preprocessor
  207. <I>eqn</I>
  208. (for <I>troff</I> only),
  209. the table-construction preprocessor
  210. <I>tbl</I>,
  211. and
  212. <I>pic</I>
  213. and
  214. <I>grap</I>
  215. for various forms of graphics.
  216. <br>&#32;<br>
  217. <HR>
  218. <br>&#32;<br>
  219. </P>
  220. <br>&#32;<br>
  221. <B>Request Summary
  222. </B><P>
  223. In the following table,
  224. the notation &#177;<I>N</I> in the
  225. <B><I>column means that the forms </I></B><I>N</I><B><I>, </I></B><I>+N</I><B><I>, or </I></B><I>-N</I><B><I> are permitted,
  226. to set the parameter to </I></B><I>N</I><B><I>, increment it by </I></B><I>N</I><B><I>, or decrement it by </I></B><I>N</I><B><I>,
  227. respectively.
  228. Plain </I></B><I>N</I><B><I> means that the value is used to set the parameter.
  229. </I></B><B><I>separated by
  230. </I></B>are for
  231. <I>troff</I>
  232. and
  233. <I>nroff</I>
  234. respectively.
  235. In the
  236. <B><I>column,
  237. <br><img src="-.16252.gif"><br>
  238. <br>&#32;<br>
  239. <br><img src="-.16253.gif"><br>
  240. <br>
  241. <DL><DT><DD><TT><PRE>
  242. </I></B><TT>ab</TT><B><I> 20
  243. </I></B><TT>ad</TT><B><I> 4
  244. </I></B><TT>af</TT><B><I> 8
  245. </I></B><TT>am</TT><B><I> 7
  246. </I></B><TT>as</TT><B><I> 7
  247. </I></B><TT>bd</TT><B><I> 2
  248. </I></B><TT>bp</TT><B><I> 3
  249. </I></B><TT>br</TT><B><I> 4
  250. </I></B><TT>c2</TT><B><I> 10
  251. </I></B><TT>cc</TT><B><I> 10
  252. </I></B><TT>ce</TT><B><I> 4
  253. </I></B><TT>cf</TT><B><I> 19
  254. </I></B><TT>ch</TT><B><I> 7
  255. </I></B><TT>cs</TT><B><I> 2
  256. </I></B><TT>cu</TT><B><I> 10
  257. </I></B><TT>da</TT><B><I> 7
  258. </I></B><TT>de</TT><B><I> 7
  259. </I></B><TT>di</TT><B><I> 7
  260. </I></B><TT>ds</TT><B><I> 7
  261. </I></B><TT>dt</TT><B><I> 7
  262. </I></B><TT>ec</TT><B><I> 10
  263. </I></B><TT>el</TT><B><I> 16
  264. </I></B><TT>em</TT><B><I> 7
  265. </I></B><TT>eo</TT><B><I> 10
  266. </I></B><TT>ev</TT><B><I> 17
  267. </I></B><TT>ex</TT><B><I> 18
  268. </I></B><TT>fc</TT><B><I> 9
  269. </I></B><TT>fi</TT><B><I> 4
  270. </I></B><TT>fl</TT><B><I> 20
  271. </I></B><TT>fp</TT><B><I> 2
  272. </I></B><TT>ft</TT><B><I> 2
  273. </I></B><TT>hc</TT><B><I> 13
  274. </I></B><TT>hw</TT><B><I> 13
  275. </I></B><TT>hy</TT><B><I> 13
  276. </I></B><TT>ie</TT><B><I> 16
  277. </I></B><TT>if</TT><B><I> 16
  278. </I></B><TT>ig</TT><B><I> 20
  279. </I></B><TT>in</TT><B><I> 6
  280. </I></B><TT>it</TT><B><I> 7
  281. </I></B><TT>lc</TT><B><I> 9
  282. </I></B><TT>lg</TT><B><I> 10
  283. </I></B><TT>lf</TT><B><I> 20
  284. </I></B><TT>ll</TT><B><I> 6
  285. </I></B><TT>ls</TT><B><I> 5
  286. </I></B><TT>lt</TT><B><I> 14
  287. </I></B><TT>mc</TT><B><I> 20
  288. </I></B><TT>mk</TT><B><I> 3
  289. </I></B><TT>na</TT><B><I> 4
  290. </I></B><TT>ne</TT><B><I> 3
  291. </I></B><TT>nf</TT><B><I> 4
  292. </I></B><TT>nh</TT><B><I> 13
  293. </I></B><TT>nm</TT><B><I> 15
  294. </I></B><TT>nn</TT><B><I> 15
  295. </I></B><TT>nr</TT><B><I> 8
  296. </I></B><TT>ns</TT><B><I> 5
  297. </I></B><TT>nx</TT><B><I> 19
  298. </I></B><TT>os</TT><B><I> 5
  299. </I></B><TT>pc</TT><B><I> 14
  300. </I></B><TT>pi</TT><B><I> 19
  301. </I></B><TT>pl</TT><B><I> 3
  302. </I></B><TT>pm</TT><B><I> 20
  303. </I></B><TT>pn</TT><B><I> 3
  304. </I></B><TT>po</TT><B><I> 3
  305. </I></B><TT>ps</TT><B><I> 2
  306. </I></B><TT>rd</TT><B><I> 18
  307. </I></B><TT>rm</TT><B><I> 7
  308. </I></B><TT>rn</TT><B><I> 7
  309. </I></B><TT>rr</TT><B><I> 8
  310. </I></B><TT>rs</TT><B><I> 5
  311. </I></B><TT>rt</TT><B><I> 3
  312. </I></B><TT>so</TT><B><I> 19
  313. </I></B><TT>sp</TT><B><I> 5
  314. </I></B><TT>ss</TT><B><I> 2
  315. </I></B><TT>sv</TT><B><I> 5
  316. </I></B><TT>sy</TT><B><I> 19
  317. </I></B><TT>ta</TT><B><I> 9
  318. </I></B><TT>tc</TT><B><I> 9
  319. </I></B><TT>ti</TT><B><I> 6
  320. </I></B><TT>tl</TT><B><I> 14
  321. </I></B><TT>tm</TT><B><I> 20
  322. </I></B><TT>tr</TT><B><I> 10
  323. </I></B><TT>uf</TT><B><I> 10
  324. </I></B><TT>ul</TT><B><I> 10
  325. </I></B><TT>vs</TT><B><I> 5
  326. </I></B><TT>wh</TT><B><I> 7
  327. <br>&#32;<br>
  328. </PRE></TT></DL>
  329. </P>
  330. </I></B><br>&#32;<br>
  331. <B>Alphabetical Request and Section Number Cross Reference
  332. </B><br>&#32;<br>
  333. <br>&#32;<br>
  334. <DL><DT><DD><TT><PRE>
  335. <br>&#32;<br>
  336. <br>&#32;<br>
  337. <HR>
  338. <br>&#32;<br>
  339. </PRE></TT></DL>
  340. <br>&#32;<br>
  341. <B>Escape Sequences for Characters, Indicators, and Functions
  342. </B><br>&#32;<br>
  343. <br><img src="-.16254.gif"><br>
  344. <br>&#32;<br>
  345. The escape sequences
  346. and
  347. are interpreted in copy mode (&#167;7.2).
  348. <br>&#32;<br>
  349. <HR>
  350. <br>&#32;<br>
  351. <br>&#32;<br>
  352. <B>Predefined Number Registers
  353. </B><br>&#32;<br>
  354. <br><img src="-.16255.gif"><br>
  355. <br>&#32;<br>
  356. <B>Predefined Read-Only Number Registers
  357. </B><br>&#32;<br>
  358. <br><img src="-.16256.gif"><br>
  359. <br>&#32;<br>
  360. <HR>
  361. <br>&#32;<br>
  362. <br>&#32;<br>
  363. <B>Reference Manual
  364. </B><H4>1 General Explanation
  365. </H4>
  366. <br>&#32;<br>
  367. <B><I>0.0s. Form of input.</I></B>
  368. Input consists of <I>text lines</I>, which are destined to be printed,
  369. interspersed with <I>control lines</I>,
  370. which set parameters or otherwise control subsequent processing.
  371. Control lines begin with a <I>control character</I>&#173;
  372. normally <TT>.</TT> (period) or <TT>'</TT> (single quote)&#173;
  373. followed by a one or two character name that specifies
  374. a basic <I>request</I> or the substitution of
  375. a user-defined <I>macro</I> in place of the control line.
  376. The control character <TT>'</TT> suppresses the <I>break</I> function&#173;
  377. the forced output of a partially filled line&#173;
  378. caused by certain requests.
  379. The control character may be separated from the request/macro name by
  380. white space (spaces and/or tabs) for aesthetic reasons.
  381. Names should be followed by either
  382. space or newline.
  383. Control lines with unrecognized names are ignored.
  384. <P>
  385. Various special functions may be introduced anywhere in the input by
  386. means of an <I>escape</I> character, normally <TT>\</TT>.
  387. For example, the function
  388. causes the interpolation of the contents of the
  389. <I>number register R</I>
  390. in place of the function;
  391. here <I>R</I> is either a single character name
  392. as in <TT>\n</TT><I>x</I>,
  393. or a two-character name introduced by
  394. a left-parenthesis, as in <TT>\n(</TT><I>xx</I>.
  395. </P>
  396. <br>&#32;<br>
  397. <B><I>0.0s. Formatter and device resolution.</I></B>
  398. <I>Troff</I> internally stores and processes dimensions in units that correspond to
  399. the particular device for which output is being prepared;
  400. values from 300 to 1200/inch are typical.
  401. See &#167;23.
  402. <I>Nroff</I> internally uses 240 units/inch,
  403. corresponding to the least common multiple of the
  404. horizontal and vertical resolutions of various
  405. typewriter-like output devices.
  406. <I>Troff</I> rounds horizontal/vertical numerical parameter input to the actual
  407. horizontal/vertical resolution of the output device indicated by the <TT>-T</TT> option
  408. (default
  409. <I>Nroff</I> similarly rounds numerical input to the actual resolution
  410. of its output device
  411. (default Model 37 Teletype).
  412. <br>&#32;<br>
  413. <B><I>0.0s. Numerical parameter input.</I></B>
  414. Both <I>nroff</I> and <I>troff</I>
  415. accept numerical input with the appended scale
  416. indicators
  417. shown in the following table,
  418. where
  419. <I>S</I> is the current type size in points and
  420. <I>V</I> is the current vertical line spacing in
  421. basic units.
  422. <br><img src="-.16257.gif"><br>
  423. In <I>nroff</I>, both the em and the en are taken to be equal to the
  424. nominal character width,
  425. which is output-device dependent;
  426. common values are 1/10 and 1/12 inch.
  427. Actual character widths in <I>nroff</I> need not be all the same and constructed characters
  428. such as -&#62; (->) are often extra wide.
  429. The default scaling is
  430. for the horizontally-oriented requests
  431. and functions
  432. and horizontal coordinates of
  433. for the vertically-oriented requests and functions
  434. and vertical coordinates of
  435. for the
  436. request;
  437. and
  438. for the requests
  439. and
  440. <I>All</I> other requests ignore any scale indicators.
  441. When a number register containing an already appropriately scaled number
  442. is interpolated to provide numerical input,
  443. the unit scale indicator
  444. <TT>u</TT> may need to be appended to prevent
  445. an additional inappropriate default scaling.
  446. The number, <I>N</I>, may be specified in decimal-fraction form
  447. but the parameter finally stored is rounded to an integer number of basic units.
  448. Internal computations are performed in integer arithmetic.
  449. <P>
  450. The <I>absolute position</I> indicator <TT>|</TT> may be prefixed
  451. to a number <I>N</I>
  452. to generate the distance to the vertical or horizontal place <I>N</I>.
  453. For vertically-oriented requests and functions, <TT>|</TT><I>N</I>
  454. becomes the distance in basic units from the current vertical place on the page or in a <I>diversion</I> (&#167;7.4)
  455. to the vertical place <I>N</I>.
  456. For <I>all</I> other requests and functions,
  457. <TT>|</TT><I>N</I>
  458. becomes the distance from
  459. the current horizontal place on the <I>input</I> line to the horizontal place <I>N</I>.
  460. For example,
  461. <DL><DT><DD><TT><PRE>
  462. .sp |3.2c
  463. </PRE></TT></DL>
  464. will space in the required direction to 3.2 centimeters from the top of the page.
  465. </P>
  466. <br>&#32;<br>
  467. <B><I>0.0s. Numerical expressions.</I></B>
  468. Wherever numerical input is expected,
  469. an expression involving parentheses,
  470. the arithmetic operators <TT>+</TT>, <TT>-</TT>, <TT>/</TT>, <TT>*</TT>, <TT>%</TT> (mod),
  471. and the logical operators
  472. <TT>&#60;</TT>,
  473. <TT>&#62;</TT>,
  474. <TT>&#60;=</TT>,
  475. <TT>&#62;=</TT>,
  476. <TT>=</TT> (or <TT>==</TT>),
  477. <TT>&amp;</TT> (and),
  478. <TT>:</TT> (or)
  479. may be used.
  480. Except where controlled by parentheses, evaluation of expressions is left-to-right;
  481. there is no operator precedence.
  482. In the case of certain requests, an initial <TT>+</TT> or <TT>-</TT> is stripped
  483. and interpreted as an increment or decrement indicator respectively.
  484. In the presence of default scaling, the desired scale indicator must be
  485. attached to <I>every</I> number in an expression
  486. for which the desired and default scaling differ.
  487. For example,
  488. if the number register <TT>x</TT> contains 2
  489. and the current point size is 10,
  490. then
  491. <DL><DT><DD><TT><PRE>
  492. .ll (4.25i+\nxP+3)/2u
  493. </PRE></TT></DL>
  494. will set the line length to 1/2 the sum of 4.25 inches + 2 picas + 3 ems.
  495. <br>&#32;<br>
  496. <B><I>0.0s. Notation.</I></B>
  497. Numerical parameters are indicated in this manual in two ways.
  498. &#177;<I>N</I> means that the argument may take the forms <I>N</I>, <I>+N</I>, or <I>-N</I> and
  499. that the corresponding effect is to set the parameter
  500. to <I>N</I>, to increment it by <I>N</I>, or to decrement it by <I>N</I> respectively.
  501. Plain <I>N</I> means that an initial algebraic sign is <I>not</I>
  502. an increment indicator,
  503. but merely the sign of <I>N</I>.
  504. Generally, unreasonable numerical input is either ignored
  505. or truncated to a reasonable value.
  506. For example,
  507. most requests expect to set parameters to non-negative
  508. values;
  509. exceptions are
  510. and
  511. The requests
  512. and
  513. restore the previous parameter value in the absence
  514. of an argument.
  515. <P>
  516. Single character arguments are indicated by single lower case letters
  517. and
  518. one/two character arguments are indicated by a pair of lower case letters.
  519. Character string arguments are indicated by multi-character mnemonics.
  520. </P>
  521. <H4>2 Font and Character Size Control
  522. </H4>
  523. <br>&#32;<br>
  524. <B><I>0.0s. Character set.</I></B>
  525. The <I>troff</I> character set is defined by a description file specific to each output device (&#167;23).
  526. There are normally several regular fonts and one or more special fonts.
  527. Characters are input as themselves,
  528. as <I></I><TT>&#191;TT><I>xx</I>, as <I></I><TT>C'</TT><I>name</I><I></I><TT>'</TT>,
  529. or as
  530. The form
  531. permits a name of any length;
  532. the form
  533. refers to the <I>n</I>-th character on the current font,
  534. whether named or not.
  535. <P>
  536. Normally the input characters
  537. and
  538. are printed as `, ', and - respectively;
  539. and
  540. produce `, ', and -.
  541. If the character does not exist in the font, <I>troff</I> assumes the width is 1 em and
  542. outputs the character with a
  543. name as defined in Section 22.
  544. (This is independent of how the device handles characters unknown to it.)
  545. </P>
  546. <P>
  547. <I>Nroff</I> has an analogous, but different, mechanism for defining legal characters
  548. and how to print them.
  549. By default all characters are valid.
  550. There are such
  551. additional characters as may be available on
  552. the output device,
  553. such characters as may be constructed
  554. by overstriking or other combination,
  555. and those that can reasonably be mapped
  556. into other printable characters.
  557. The exact behavior is determined by a driving
  558. table prepared for each device.
  559. </P>
  560. <br>&#32;<br>
  561. <B><I>0.0s. Fonts.</I></B>
  562. <I>Troff</I>
  563. begins execution by reading information for a set of defaults fonts,
  564. said to be
  565. <I>mounted</I>;
  566. conventionally, the first four are
  567. Times Roman (<TT>R</TT>),
  568. Times Italic
  569. (<TT>I</TT>),
  570. Times Bold
  571. (<TT>B</TT>),
  572. and
  573. Times Bold Italic
  574. (<TT>BI</TT>) ,
  575. and the last is a Special font
  576. containing miscellaneous characters.
  577. (This document uses Lucida Sans in place of Times.)
  578. The set of fonts and positions is determined by the device description file,
  579. described in &#167;23.
  580. <P>
  581. The current font, initially Roman, may be changed
  582. by the <TT>ft</TT> request,
  583. or by embedding at any desired point
  584. <TT>/TT><I>x</I>, <TT>TT><I>xx</I>, or <TT>/TT><I>N</I>,
  585. where
  586. <I>x</I> and <I>xx</I> are the name of a font
  587. and <I>N</I> is a numerical font position.
  588. </P>
  589. <P>
  590. It is not necessary to change to the Special font;
  591. characters on that font are automatically handled
  592. as if they were physically part of the current font.
  593. The Special font may actually be several fonts;
  594. the name
  595. is reserved and is generally used for one of these.
  596. All special fonts must be mounted after regular fonts.
  597. </P>
  598. <P>
  599. <I>Troff</I> can be informed that any particular font is mounted
  600. by use of the <TT>fp</TT> request.
  601. The list of known fonts is installation dependent.
  602. In the subsequent discussion of font-related requests,
  603. <I>F</I> represents either a one/two-character
  604. font name or the numerical font position.
  605. The current font is available (as a numerical position) in the read-only number register <TT>.f</TT>.
  606. </P>
  607. <P>
  608. A request for a named but not-mounted font is honored
  609. if the font description information exists.
  610. In this way, there is no limit on the number of fonts that may be printed
  611. in any part of a document.
  612. Mounted fonts may be handled more efficiently,
  613. and they may be referred to by their mount positions,
  614. but there is no other difference.
  615. Mention of an unmounted font loads it temporarily at font position
  616. zero, which serves as a one-font cache.
  617. </P>
  618. <P>
  619. The function
  620. causes the current font to be slanted by
  621. &#177;<I>N</I>
  622. degrees.
  623. Not all devices support slanting.
  624. </P>
  625. <P>
  626. <I>Nroff</I> understands font control
  627. and normally underlines italic characters (see &#167;10.5).
  628. </P>
  629. <br>&#32;<br>
  630. <B><I>0.0s. Character size.</I></B>
  631. Character point sizes available depend on the specific output device;
  632. a typical (historical) set of values is
  633. 6, 7, 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, and 36.
  634. This is a range of 1/12 inch to 1/2 inch.
  635. The <TT>ps</TT> request is used to change or restore the point size.
  636. Alternatively the point size may be changed between any two characters
  637. by embedding a
  638. at the desired point
  639. to set the size to <I>N</I>,
  640. or a
  641. </TT>(1<=<I>N</I><=9)
  642. to increment/decrement the size by <I>N</I>;
  643. restores the previous size.
  644. Requested point size values that are between two valid
  645. sizes yield the larger of the two.
  646. <P>
  647. Note that through an accident of history, a construction like
  648. is parsed as size 39, and thus converted to size 36 (given the sizes above),
  649. while
  650. is parsed as size 4 followed by
  651. The forms
  652. <I></I><TT></TT><I>nn</I> and <I></I><TT></TT>&#177;<I></I><TT>(</TT><I>nn</I>
  653. permit specification of sizes that would otherwise be ambiguous.
  654. </P>
  655. <P>
  656. The current size is available in the <TT>.s</TT> register.
  657. <I>Nroff</I> ignores type size requests.
  658. </P>
  659. <P>
  660. The function
  661. sets the height of the current font to
  662. <I>N</I>, or increments it by <I>+N</I>, or decrements it by <I>-N</I>;
  663. if <I>N=</I>0, the height is restored to the current point size.
  664. In each case, the width is unchanged.
  665. Not all devices support independent height and width for characters.
  666. </P>
  667. <DL>
  668. <DT><DT>&#32;<DD>
  669. NOTE:<I> *The fields have the same meaning as described earlier in the Request Summary.
  670. </I><DT>&#32;<DD></dl>
  671. <br>
  672. <br>&#32;<br>
  673. <I>Request</I> <I>Initial</I> <I>If No</I>
  674. <br>
  675. <I>Form</I> <I>Value</I> <I>Argument</I> <I>Notes</I>
  676. <br>&#32;<br>
  677. <TT>.ps</TT><I> &#177;N</I>* 10point previous E
  678. <DL COMPACT>
  679. <DT><DD>
  680. Point size
  681. set to &#177;<I>N</I>.
  682. Alternatively, embed
  683. or
  684. </TT>Any positive size value may be requested;
  685. if invalid, the next larger valid size will result, with a
  686. maximum of 36.
  687. A paired sequence
  688. <I>+N</I>, <I>-N</I>
  689. will work because the previous requested value is also remembered.
  690. Ignored in <I>nroff</I>.
  691. </dl>
  692. <br>&#32;<br>
  693. <TT>.ss</TT><I> N</I> 12/36em ignored E
  694. <DL COMPACT>
  695. <DT><DD>
  696. Space-character size
  697. (i.e., inter-word gap)
  698. is set to <I>N</I>/36 ems.
  699. This size is the minimum word spacing in adjusted text.
  700. Ignored in <I>nroff</I>.
  701. </dl>
  702. <br>&#32;<br>
  703. <TT>.cs</TT><I>FNM</I> off - P
  704. <DL COMPACT>
  705. <DT><DD>
  706. Constant character space
  707. (width) mode is
  708. set on for font <I>F</I> (if mounted); the width of every character will be
  709. taken to be <I>N</I>/36 ems.
  710. If <I>M</I> is absent,
  711. the em is that of the character's point size;
  712. if <I>M</I> is given,
  713. the em is <I>M</I> points.
  714. All affected characters
  715. are centered in this space, including those with an actual width
  716. larger than this space.
  717. Special Font characters occurring while the current font
  718. is <I>F</I> are also so treated.
  719. If <I>N</I> is absent, the mode is turned off.
  720. The mode must be in effect when the characters are physically printed.
  721. Ignored in <I>nroff</I>.
  722. </dl>
  723. <br>&#32;<br>
  724. <TT>.bd</TT><I> F N</I> off - P
  725. <DL COMPACT>
  726. <DT><DD>
  727. The characters in font <I>F</I> will be artificially
  728. emboldened by printing each one twice, separated by <I>N-</I>1 basic units.
  729. A reasonable value for <I>N</I> is 3 when the character size is near 10 points.
  730. If <I>N</I> is missing the embolden mode is turned off.
  731. The emboldening value <I>N</I> is in the <TT>.b</TT> register.
  732. <DT><DT>&#32;<DD>
  733. This paragraph is printed with <TT>.bd R 3</TT>.
  734. The mode must be in effect when the characters are physically printed.
  735. Ignored in <I>nroff</I>.
  736. <br>
  737. </dl>
  738. <br>&#32;<br>
  739. <TT>.bd S </TT><I>F N</I> off - P
  740. <DL COMPACT>
  741. <DT><DD>
  742. The characters in the Special font
  743. will be emboldened whenever the current font is <I>F</I>.
  744. The mode must be in effect when the characters are physically printed.
  745. Ignored in <I>nroff</I>.
  746. </dl>
  747. <br>&#32;<br>
  748. <TT>.ft</TT> <I>F</I> Roman previous E
  749. <DL COMPACT>
  750. <DT><DD>
  751. Font changed to
  752. <I>F</I>.
  753. Alternatively, embed
  754. The font name <TT>P</TT> is reserved to mean the previous font,
  755. and the name
  756. for the special font.
  757. </dl>
  758. <br>&#32;<br>
  759. <TT>.fp </TT><I>N F L</I> R,I,B,...,S ignored -
  760. <DL COMPACT>
  761. <DT><DD>
  762. Font position.
  763. This is a statement
  764. that a font named <I>F</I> is associated with position <I>N</I>.
  765. It is a fatal error if <I>F</I> is not known.
  766. For fonts with names longer than two characters,
  767. <I>L</I>
  768. refers to the long name,
  769. and
  770. <I>F</I>
  771. becomes a synonym.
  772. There is generally a limit of about 10 mounted fonts.
  773. </dl>
  774. <H4>3 Page control
  775. </H4>
  776. <P>
  777. Top and bottom margins are not automatically provided;
  778. it is conventional to define two <I>macros</I> and to set <I>traps</I>
  779. for them at vertical positions 0 (top) and <I>-N</I> (distance <I>N</I> up from the bottom).
  780. See &#167;7 and Tutorial Examples &#167;T2.
  781. A pseudo-page transition onto the first page occurs
  782. either when the first <I>break</I> occurs or
  783. when the first <I>non-diverted</I> text processing occurs.
  784. Arrangements
  785. for a trap to occur at the top of the first page
  786. must be completed before this transition.
  787. In the following, references to the <I>current diversion</I> (&#167;7.4)
  788. mean that the mechanism being described works during both
  789. ordinary and diverted output (the former considered as the top diversion level).
  790. </P>
  791. <P>
  792. The limitations on <I>troff</I> and <I>nroff</I> output dimensions
  793. are device dependent.
  794. </P>
  795. <br>&#32;<br>
  796. <TT>.pl</TT><I> &#177;N</I> 11in 11in <B>v</B>
  797. <DL COMPACT>
  798. <DT><DD>
  799. Page length set to &#177;<I>N</I>.
  800. The current page length is available in the <TT>.p</TT> register.
  801. </dl>
  802. <br>&#32;<br>
  803. <TT>.bp</TT><I> &#177;N</I> <I>N=</I>1 - B,<B>v</B>
  804. <DL COMPACT>
  805. <DT><DD>
  806. Begin page.
  807. The current page is ejected and a new page is begun.
  808. If &#177;<I>N</I> is given, the new page number will be &#177;<I>N</I>.
  809. Also see request <TT>ns</TT>.
  810. </dl>
  811. <br>&#32;<br>
  812. <TT>.pn</TT><I> &#177;N</I> <I>N</I>=1 ignored -
  813. <DL COMPACT>
  814. <DT><DD>
  815. Page number.
  816. The next page (when it occurs) will have the page number &#177;<I>N</I>.
  817. A <TT>pn</TT> must occur before the initial pseudo-page transition
  818. to affect the page number of the first page.
  819. The current page number is in the <TT>%</TT> register.
  820. </dl>
  821. <br>&#32;<br>
  822. <TT>.po</TT><I> &#177;N</I> 1in; 0 previous <B>v</B>
  823. <DL COMPACT>
  824. <DT><DD>
  825. Page offset.
  826. The current <I>left margin</I> is set to &#177;<I>N</I>.
  827. The <I>troff</I> initial value provides 1 inch of paper margin
  828. on a typical device.
  829. The current page offset is available in the <TT>.o</TT> register.
  830. </dl>
  831. <br>&#32;<br>
  832. <TT>.ne</TT><I> N</I> - <I>N=</I>1<I>V</I> D,<B>v</B>
  833. <DL COMPACT>
  834. <DT><DD>
  835. Need <I>N</I> vertical space.
  836. If the distance <I>D</I> to the next trap position (see &#167;7.5) is less than <I>N</I>,
  837. a forward vertical space of size <I>D</I> occurs,
  838. which will spring the trap.
  839. If there are no remaining
  840. traps on the page,
  841. <I>D</I> is the distance to the bottom of the page.
  842. If <I>D&#60;V</I>, another line could still be output
  843. and spring the trap.
  844. In a diversion, <I>D</I> is the distance to the <I>diversion trap</I>, if any,
  845. or is very large.
  846. </dl>
  847. <br>&#32;<br>
  848. <TT>.mk</TT><I> R</I> none internal D
  849. <DL COMPACT>
  850. <DT><DD>
  851. Mark the current vertical place
  852. in an internal register (both associated with the current diversion level),
  853. or in register <I>R</I>, if given.
  854. See <TT>rt</TT> request.
  855. </dl>
  856. <br>&#32;<br>
  857. <TT>.rt</TT><I> &#177;N</I> none internal D,<B>v</B>
  858. <DL COMPACT>
  859. <DT><DD>
  860. Return <I>upward only</I> to a marked vertical place
  861. in the current diversion.
  862. If &#177;<I>N</I> (with respect to current place) is given,
  863. the place is &#177;<I>N</I> from the top of the page or diversion
  864. or, if <I>N</I> is absent, to a
  865. place marked by a previous <TT>mk</TT>.
  866. The <TT>sp</TT> request (&#167;5.3) may be used
  867. instead of <TT>rt</TT>
  868. by spacing to the absolute place stored in a explicit register,
  869. e.g., using
  870. <I>R</I> ...
  871. this also works when the motion is downwards.
  872. </dl>
  873. <H4>4 Text Filling, Adjusting, and Centering
  874. </H4>
  875. <br>&#32;<br>
  876. <B><I>0.0s. Filling and adjusting.</I></B>
  877. Normally,
  878. words are collected from input text lines
  879. and assembled into a output text line
  880. until some word does not fit.
  881. An attempt is then made
  882. to hyphenate the word to put part
  883. of it into the output line.
  884. The spaces between the words on the output line
  885. are then increased to spread out the line
  886. to the current <I>line length</I>
  887. minus any current <I>indent</I>.
  888. A <I>word</I> is any string of characters delimited by
  889. the <I>space</I> character or the beginning/end of the input line.
  890. Any adjacent pair of words that must be kept together
  891. (neither split across output lines nor spread apart
  892. in the adjustment process)
  893. can be tied together by separating them with the
  894. <I>unpaddable space</I> character
  895. ``<TT>\ </TT>'' (backslash-space).
  896. The adjusted word spacings are uniform in <I>troff</I>
  897. and the minimum interword spacing can be controlled
  898. with the <TT>ss</TT> request (&#167;2).
  899. In <I>nroff</I>, they are normally nonuniform because of
  900. quantization to character-size spaces;
  901. however,
  902. the command line option <TT>-e</TT> causes uniform
  903. spacing with full output device resolution.
  904. Filling, adjustment, and hyphenation (&#167;13) can all be
  905. prevented or controlled.
  906. The text length on the last line output is available in the <TT>.n</TT> register,
  907. and text baseline position on the page for this line is in the <TT>nl</TT> register.
  908. The text baseline high-water mark (lowest place) on the current page is in
  909. the <TT>.h</TT> register.
  910. The current horizontal output position is in the <TT>.k</TT> register.
  911. <P>
  912. An input text line
  913. <I>ending</I>
  914. with <TT>.</TT>, <TT>?</TT>, or <TT>!</TT>,
  915. optionally followed by any number of
  916. or
  917. &#191;,
  918. is taken
  919. to be the end of a sentence, and an additional space character is
  920. automatically provided during filling.
  921. To prevent this, add
  922. to the end of the input line.
  923. Multiple inter-word space characters found in the input are retained,
  924. except for trailing spaces;
  925. initial spaces also cause a break.
  926. </P>
  927. <P>
  928. When filling is in effect, a <TT>\p</TT> may be embedded or attached to a word to
  929. cause a break at the end of the word and have the resulting output
  930. line spread out to fill the current line length.
  931. </P>
  932. <P>
  933. A text input line that happens to begin
  934. with a control character can
  935. be made not to look like a control line
  936. by prefixing it with
  937. the non-printing, zero-width filler character <TT>\&amp;</TT>.
  938. Still another way is to specify output translation of some
  939. convenient character into the control character
  940. using <TT>tr</TT> (&#167;10.5).
  941. </P>
  942. <br>&#32;<br>
  943. <B><I>0.0s. Interrupted text.</I></B>
  944. The copying of a input line in <I>nofill</I>(non-fill) mode can be interrupted
  945. by terminating
  946. the partial line with a <TT>\c</TT>.
  947. The next encountered input text line will be considered to be a continuation
  948. of the same line of input text.
  949. Similarly,
  950. a word within <I>filled</I> text may be interrupted by terminating the
  951. word (and line) with <TT>\c</TT>;
  952. the next encountered text will be taken as a continuation of the
  953. interrupted word.
  954. If the intervening control lines cause a break,
  955. any partial line will be forced out along with any partial word.
  956. <br>&#32;<br>
  957. <TT>.br</TT> - - B
  958. <DL COMPACT>
  959. <DT><DD>
  960. Break.
  961. The filling of the line currently
  962. being collected is stopped and
  963. the line is output without adjustment.
  964. Text lines beginning with space characters
  965. (but not tabs)
  966. and empty text lines (blank lines) also cause a break.
  967. </dl>
  968. <br>&#32;<br>
  969. <TT>.fi</TT> fill on - B,E
  970. <DL COMPACT>
  971. <DT><DD>
  972. Fill subsequent output lines.
  973. The register <TT>.u</TT> is 1 in fill mode and 0 in nofill mode.
  974. </dl>
  975. <br>&#32;<br>
  976. <TT>.nf</TT> fill on - B,E
  977. <DL COMPACT>
  978. <DT><DD>
  979. Nofill.
  980. Subsequent output lines are neither filled nor adjusted.
  981. Input text lines are copied directly to output lines
  982. without regard for the current line length.
  983. </dl>
  984. <br>&#32;<br>
  985. <TT>.ad</TT><I> c</I> adj, both adjust E
  986. <DL COMPACT>
  987. <DT><DD>
  988. Line adjustment is begun.
  989. If fill mode is not on, adjustment will be deferred until
  990. fill mode is back on.
  991. If the type indicator <I>c</I> is present,
  992. the adjustment type is changed as shown in the following table.
  993. <br><img src="-.16258.gif"><br>
  994. The number register
  995. contains the current value of the
  996. setting;
  997. its value can be recorded and used subsequently to set adjustment.
  998. </dl>
  999. <br>&#32;<br>
  1000. <TT>.na</TT> adjust - E
  1001. <DL COMPACT>
  1002. <DT><DD>
  1003. Noadjust.
  1004. Adjustment is turned off;
  1005. the right margin will be ragged.
  1006. The adjustment type for <TT>ad</TT> is not changed.
  1007. Output line filling still occurs if fill mode is on.
  1008. </dl>
  1009. <br>&#32;<br>
  1010. <TT>.ce</TT><I> N</I> off <I>N=</I>1 B,E
  1011. <DL COMPACT>
  1012. <DT><DD>
  1013. Center the next <I>N</I> input text lines
  1014. within the current available horizontal space (line-length minus indent).
  1015. If <I>N=</I>0, any residual count is cleared.
  1016. A break occurs after each of the <I>N</I> input lines.
  1017. If the input line is too long,
  1018. it will be left adjusted.
  1019. </dl>
  1020. <H4>5 Vertical Spacing
  1021. </H4>
  1022. <br>&#32;<br>
  1023. <B><I>0.0s. Baseline spacing.</I></B>
  1024. The vertical spacing (<I>V</I>) between the baselines of successive
  1025. output lines can be set
  1026. using the <TT>vs</TT> request.
  1027. <I>V</I> should be large enough to accommodate the character sizes
  1028. on the affected output lines.
  1029. For the common type sizes (9-12 points),
  1030. usual typesetting practice is to set <I>V</I> to 2 points greater than the
  1031. point size;
  1032. <I>troff</I> default is 10-point type on a 12-point spacing
  1033. (as in this document).
  1034. The current <I>V</I> is available in the <TT>.v</TT> register.
  1035. Multiple-<I>V</I> line separation (e.g., double spacing) may be requested
  1036. with <TT>ls</TT>,
  1037. but it is better to use a large
  1038. instead;
  1039. certain preprocessors assume single spacing.
  1040. The current line spacing is available in the <TT>.L</TT> register.
  1041. <br>&#32;<br>
  1042. <B><I>0.0s. Extra line-space.</I></B>
  1043. If a word contains a tall construct requiring
  1044. the output line containing it to have extra vertical space
  1045. before and/or after it,
  1046. the <I>extra-line-space</I> function <TT>\x'</TT><I>N</I><TT>'</TT>
  1047. can be embedded in or attached to that word.
  1048. If <I>N</I> is negative,
  1049. the output line containing the word will
  1050. be preceded by <I>N</I> extra vertical space;
  1051. if <I>N</I> is positive,
  1052. the output line containing the word
  1053. will be followed by <I>N</I> extra vertical space.
  1054. If successive requests for extra space apply to the same line,
  1055. the maximum values are used.
  1056. The most recently utilized post-line extra line-space is available in the <TT>.a</TT> register.
  1057. <P>
  1058. In
  1059. and other functions having a pair of delimiters around
  1060. their parameter,
  1061. the delimiter choice (here
  1062. is arbitrary,
  1063. except that it can not look like the continuation of a number expression for <I>N</I>.
  1064. </P>
  1065. <br>&#32;<br>
  1066. <B><I>0.0s. Blocks of vertical space.</I></B>
  1067. A block of vertical space is ordinarily requested using <TT>sp</TT>,
  1068. which honors the <I>no-space</I> mode and which does
  1069. not space past a trap.
  1070. A contiguous block of vertical space may be reserved using <TT>sv</TT>.
  1071. <br>&#32;<br>
  1072. <TT>.vs </TT><I>N</I> 12pts; 1/6in previous E,<B>p</B>
  1073. <DL COMPACT>
  1074. <DT><DD>
  1075. Set vertical baseline spacing size <I>V</I>.
  1076. Transient extra vertical space is available with <TT>\x</TT><I>'N'</I> (see above).
  1077. </dl>
  1078. <br>&#32;<br>
  1079. <TT>.ls </TT><I>N</I> <I>N=</I>1 previous E
  1080. <DL COMPACT>
  1081. <DT><DD>
  1082. <I>Line</I> spacing
  1083. set to &#177;<I>N</I>.
  1084. <I>N-</I>1 <I>V</I>s (blank lines) are
  1085. appended to each output text line.
  1086. Appended blank lines are omitted, if the text or previous appended blank line reached a trap position.
  1087. </dl>
  1088. <br>&#32;<br>
  1089. <TT>.sp </TT><I>N</I> - <I>N=</I>1 <I>V</I> B,<B>v</B>
  1090. <DL COMPACT>
  1091. <DT><DD>
  1092. Space vertically in either direction.
  1093. If <I>N</I> is negative, the motion is backward (upward)
  1094. and is limited to the distance to the top of the page.
  1095. Forward (downward) motion is truncated to the distance to the
  1096. nearest trap.
  1097. (Recall the use of
  1098. from &#167;1.3.)
  1099. If the no-space mode is on,
  1100. no spacing occurs (see <TT>ns</TT> and <TT>rs</TT> below).
  1101. </dl>
  1102. <br>&#32;<br>
  1103. <TT>.sv</TT><I> N</I> - <I>N=</I>1 <I>V</I> <B>v</B>
  1104. <DL COMPACT>
  1105. <DT><DD>
  1106. Save a contiguous vertical block of size <I>N</I>.
  1107. If the distance to the next trap is greater
  1108. than <I>N</I>, <I>N</I> vertical space is output.
  1109. No-space mode has no effect.
  1110. If this distance is less than <I>N</I>,
  1111. no vertical space is immediately output,
  1112. but <I>N</I> is remembered for later output (see <TT>os</TT>).
  1113. Subsequent <TT>sv</TT> requests will overwrite any still remembered <I>N</I>.
  1114. </dl>
  1115. <br>&#32;<br>
  1116. <TT>.os</TT> - - -
  1117. <DL COMPACT>
  1118. <DT><DD>
  1119. Output saved vertical space.
  1120. No-space mode has no effect.
  1121. Used to finally output a block of vertical space requested
  1122. by an earlier <TT>sv</TT> request.
  1123. </dl>
  1124. <br>&#32;<br>
  1125. <TT>.ns</TT> space - D
  1126. <DL COMPACT>
  1127. <DT><DD>
  1128. No-space mode turned on.
  1129. When on, no-space mode inhibits <TT>sp</TT> requests and
  1130. <TT>bp</TT> requests <I>without</I> a next page number.
  1131. No-space mode is turned off when a line of
  1132. output occurs, or with <TT>rs</TT>.
  1133. </dl>
  1134. <br>&#32;<br>
  1135. <TT>.rs</TT> space - D
  1136. <DL COMPACT>
  1137. <DT><DD>
  1138. Restore spacing.
  1139. The no-space mode is turned off.
  1140. </dl>
  1141. <br>&#32;<br>
  1142. Blank text line. - B
  1143. <DL COMPACT>
  1144. <DT><DD>
  1145. Causes a break and
  1146. output of a blank line exactly like <TT>sp 1</TT>.
  1147. </dl>
  1148. <H4>6 Line Length and Indenting
  1149. </H4>
  1150. <P>
  1151. The maximum line length for fill mode may be set with <TT>ll</TT>.
  1152. The indent may be set with <TT>in</TT>;
  1153. an indent applicable to only the next output line may be set with <TT>ti</TT>.
  1154. The line length includes indent space but not
  1155. page offset space.
  1156. The line length minus the indent is the basis for centering with <TT>ce</TT>.
  1157. The effect of <TT>ll</TT>, <TT>in</TT>, or <TT>ti</TT>
  1158. is delayed, if a partially collected line exists,
  1159. until after that line is output.
  1160. In fill mode the length of text on an output line is less than or equal to
  1161. the line length minus the indent.
  1162. The current line length and indent are available in registers <TT>.l</TT> and <TT>.i</TT> respectively.
  1163. The length of <I>three-part titles</I> produced by <TT>tl</TT>
  1164. (see &#167;14) is independently set by <TT>lt</TT>.
  1165. </P>
  1166. <br>&#32;<br>
  1167. <TT>.ll</TT><I> &#177;N</I> 6.5in previous E,<B>m</B>
  1168. <DL COMPACT>
  1169. <DT><DD>
  1170. Line length is set to &#177;<I>N</I>.
  1171. </dl>
  1172. <br>&#32;<br>
  1173. <TT>.in</TT><I> &#177;N</I> <I>N=</I>0 previous B,E,<B>m</B>
  1174. <DL COMPACT>
  1175. <DT><DD>
  1176. Indent is set to &#177;<I>N</I>.
  1177. The indent is prefixed to each output line.
  1178. </dl>
  1179. <br>&#32;<br>
  1180. <TT>.ti</TT><I> &#177;N</I> - ignored B,E,<B>m</B>
  1181. <DL COMPACT>
  1182. <DT><DD>
  1183. Temporary indent.
  1184. The next output text line will be indented a distance &#177;<I>N</I>
  1185. with respect to the current indent.
  1186. The resulting total indent may not be negative.
  1187. The current indent is not changed.
  1188. </dl>
  1189. <H4>7 Macros, Strings, Diversion, and Position Traps
  1190. </H4>
  1191. <br>&#32;<br>
  1192. <B><I>0.0s. Macros and strings.</I></B>
  1193. A <I>macro</I> is a named set of arbitrary <I>lines</I> that may be invoked by name or
  1194. with a <I>trap</I>.
  1195. A <I>string</I> is a named string of <I>characters</I>,
  1196. not including a newline character,
  1197. that may be interpolated by name at any point.
  1198. Request, macro, and string names share the same name list.
  1199. Macro and string names
  1200. may be one or two characters long and may usurp previously defined
  1201. request, macro, or string names;
  1202. this implies that built-in operations may be (irrevocably) redefined.
  1203. Any of these entities may be renamed with <TT>rn</TT>
  1204. or removed with <TT>rm</TT>.
  1205. <P>
  1206. Macros are created by <TT>de</TT> and <TT>di</TT>, and appended to by <TT>am</TT> and <TT>da</TT>;
  1207. <TT>di</TT> and <TT>da</TT> cause normal output to be stored in a macro.
  1208. A macro is invoked in the same way as a request;
  1209. a control line beginning <TT>.</TT><I>xx</I> will interpolate the contents of macro <I>xx</I>.
  1210. The remainder of the line may contain up to nine <I>arguments</I>.
  1211. </P>
  1212. <P>
  1213. Strings are created by <TT>ds</TT> and appended to by <TT>as</TT>.
  1214. The strings <I>x</I> and <I>xx</I> are interpolated at any desired point with
  1215. <TT>\*</TT><I>x</I> and <TT>\*(</TT><I>xx</I> respectively.
  1216. String references and macro invocations may be nested.
  1217. </P>
  1218. <br>&#32;<br>
  1219. <B><I>0.0s. Copy mode input interpretation.</I></B>
  1220. During the definition and extension
  1221. of strings and macros (not by diversion)
  1222. the input is read in <I>copy mode</I>.
  1223. In copy mode, input is copied without interpretation
  1224. except that:
  1225. <DL>
  1226. <DT><DT>&#32;<DD>
  1227. <DL><DT><DD><TT><PRE>
  1228. ^* The contents of number registers indicated by <TT>\n</TT> are interpolated.
  1229. ^* Strings indicated by <TT>\*</TT> are interpolated.
  1230. ^* Arguments indicated by <TT>\$</TT> are interpolated.
  1231. ^* Concealed newlines indicated by <TT>\</TT><I>newline</I> are eliminated.
  1232. ^* Comments indicated by <TT>\"</TT> are eliminated.
  1233. ^* <TT>\t</TT> and <TT>\a</TT> are interpreted as ASCII horizontal tab and SOH respectively (&#167;9).
  1234. ^* <TT>\\</TT> is interpreted as <TT>\</TT>.
  1235. ^* <TT>\.</TT> is interpreted as ``<TT>.</TT>''.
  1236. </PRE></TT></DL>
  1237. </dl>
  1238. <br>&#32;<br>
  1239. These interpretations can be suppressed by
  1240. prefixing
  1241. a <TT>\</TT>.
  1242. For example, since <TT>\\</TT> maps into a <TT>\</TT>, <TT>\\n</TT> will copy as <TT>\n</TT>, which
  1243. will be interpreted as a number register indicator when the
  1244. macro or string is reread.
  1245. <br>&#32;<br>
  1246. <B><I>0.0s. Arguments.</I></B>
  1247. When a macro is invoked by name, the remainder of the line is
  1248. taken to contain up to nine arguments.
  1249. The argument separator is the space character (not tab), and arguments
  1250. may be surrounded by double quotes to permit embedded space characters.
  1251. Pairs of double quotes may be embedded in double-quoted arguments to
  1252. represent a single double-quote character.
  1253. The argument
  1254. is explicitly null.
  1255. If the desired arguments won't fit on a line,
  1256. a concealed newline may be used to continue on the next line.
  1257. A trailing double quote may be omitted.
  1258. <P>
  1259. When a macro is invoked the <I>input level</I> is <I>pushed down</I> and
  1260. any arguments available at the previous level become unavailable
  1261. until the macro is completely read and the previous level is restored.
  1262. A macro's own arguments can be interpolated at any point
  1263. within the macro with
  1264. which interpolates the <I>N</I>th
  1265. argument
  1266. (1<=<I>N</I><=9).
  1267. If an invoked argument does not exist,
  1268. a null string results.
  1269. For example, the macro <I>xx</I> may be defined by
  1270. <DL><DT><DD><TT><PRE>
  1271. &amp;de xx \" begin definition
  1272. Today is \\$1 the \\$2.
  1273. &amp;. \" end definition
  1274. </PRE></TT></DL>
  1275. and called by
  1276. <DL><DT><DD><TT><PRE>
  1277. &amp;xx Monday 14th
  1278. </PRE></TT></DL>
  1279. to produce the text
  1280. <DL><DT><DD><TT><PRE>
  1281. Today is Monday the 14th.
  1282. </PRE></TT></DL>
  1283. Note that each <TT>\$</TT>
  1284. was concealed in the definition with a prefixed <TT>\</TT>.
  1285. The number of
  1286. arguments is in the <TT>.$</TT> register.
  1287. </P>
  1288. <P>
  1289. No arguments are available at the top (non-macro) level,
  1290. within a string, or within a trap-invoked macro.
  1291. </P>
  1292. <P>
  1293. Arguments are copied in copy mode onto a stack
  1294. where they are available for reference.
  1295. It is advisable to
  1296. conceal string references (with an extra <TT>\</TT>)
  1297. to delay interpolation until argument reference time.
  1298. </P>
  1299. <br>&#32;<br>
  1300. <B><I>0.0s. Diversions.</I></B>
  1301. Processed output may be diverted into a macro for purposes
  1302. such as footnote processing (see Tutorial &#167;T5)
  1303. or determining the horizontal and vertical size of some text for
  1304. conditional changing of pages or columns.
  1305. A single diversion trap may be set at a specified vertical position.
  1306. The number registers <TT>dn</TT> and <TT>dl</TT> respectively contain the
  1307. vertical and horizontal size of the most
  1308. recently ended diversion.
  1309. Processed text that is diverted into a macro
  1310. retains the vertical size of each of its lines when reread
  1311. in <I>nofill</I> mode
  1312. regardless of the current <I>V</I>.
  1313. Constant-spaced (<TT>cs</TT>) or emboldened (<TT>bd</TT>) text that is diverted
  1314. can be reread correctly only if these modes are again or still in effect
  1315. at reread time.
  1316. One way to do this is to embed in the diversion the appropriate
  1317. <TT>cs</TT> or <TT>bd</TT> requests with the <I>transparent</I>
  1318. mechanism described in &#167;10.6.
  1319. <P>
  1320. Diversions may be nested
  1321. and certain parameters and registers
  1322. are associated
  1323. with the current diversion level
  1324. (the top non-diversion level may be thought of as the
  1325. 0th diversion level).
  1326. These are the diversion trap and associated macro,
  1327. no-space mode,
  1328. the internally-saved marked place (see <TT>mk</TT> and <TT>rt</TT>),
  1329. the current vertical place (<TT>.d</TT> register),
  1330. the current high-water text baseline (<TT>.h</TT> register),
  1331. and the current diversion name (<TT>.z</TT> register).
  1332. </P>
  1333. <br>&#32;<br>
  1334. <B><I>0.0s. Traps.</I></B>
  1335. Three types of trap mechanisms are available&#173;page traps, a diversion trap, and
  1336. an input-line-count trap.
  1337. Macro-invocation traps may be planted using <TT>wh</TT> at any page position including the top.
  1338. This trap position may be changed using <TT>ch</TT>.
  1339. Trap positions at or below the bottom of the page
  1340. have no effect unless or until
  1341. moved to within the page or rendered effective by an increase in page length.
  1342. Two traps may be planted at the same position only by first planting them at different
  1343. positions and then moving one of the traps;
  1344. the first planted trap will conceal the second unless and until the first one is moved
  1345. (see Tutorial Examples).
  1346. If the first one is moved back, it again conceals the second trap.
  1347. The macro associated with a page trap is automatically
  1348. invoked when a line of text is output whose vertical size reaches
  1349. or sweeps past the trap position.
  1350. Reaching the bottom of a page springs the top-of-page trap, if any,
  1351. provided there is a next page.
  1352. The distance to the next trap position is available in the <TT>.t</TT> register;
  1353. if there are no traps between the current position and the bottom of the page,
  1354. the distance returned is the distance to the page bottom.
  1355. <P>
  1356. A macro-invocation trap effective in the current diversion may be planted using <TT>dt</TT>.
  1357. The <TT>.t</TT> register works in a diversion; if there is no subsequent trap a large
  1358. distance is returned.
  1359. For a description of input-line-count traps, see <TT>it</TT> below.
  1360. </P>
  1361. <br>&#32;<br>
  1362. <TT>&de</TT><I> xx yy</I> - <I>.yy=</I><TT>..</TT> -
  1363. <DL COMPACT>
  1364. <DT><DD>
  1365. Define or redefine the macro <I>xx</I>.
  1366. The contents of the macro begin on the next input line.
  1367. Input lines are copied in <I>copy mode</I> until the definition is terminated by a
  1368. line beginning with <TT>.</TT><I>yy</I>,
  1369. whereupon the macro <I>yy</I> is called.
  1370. In the absence of <I>yy</I>, the definition
  1371. is terminated by a
  1372. line beginning with ``<TT>..</TT>''.
  1373. A macro may contain <TT>de</TT> requests
  1374. provided the terminating macros differ
  1375. or the contained definition terminator is concealed.
  1376. ``<TT>..</TT>'' can be concealed as
  1377. <TT>\\..</TT> which will copy as <TT>\..</TT> and be reread as ``<TT>..</TT>''.
  1378. </dl>
  1379. <br>&#32;<br>
  1380. <TT>&am</TT><I> xx yy</I> - <I>.yy=</I><TT>..</TT> -
  1381. <DL COMPACT>
  1382. <DT><DD>
  1383. Append to macro
  1384. <I>xx</I>
  1385. (append version of <TT>de</TT>).
  1386. </dl>
  1387. <br>&#32;<br>
  1388. <TT>&ds</TT><I> xx string</I> - ignored -
  1389. <DL COMPACT>
  1390. <DT><DD>
  1391. Define a string
  1392. <I>xx</I> containing <I>string</I>.
  1393. Any initial double quote in <I>string</I> is stripped off to permit
  1394. initial blanks.
  1395. </dl>
  1396. <br>&#32;<br>
  1397. <TT>&as</TT><I> xx string</I> - ignored -
  1398. <DL COMPACT>
  1399. <DT><DD>
  1400. Append
  1401. <I>string</I> to string <I>xx</I>
  1402. (append version of <TT>ds</TT>).
  1403. </dl>
  1404. <br>&#32;<br>
  1405. <TT>&rm</TT><I> xx</I> - ignored -
  1406. <DL COMPACT>
  1407. <DT><DD>
  1408. Remove
  1409. request, macro, or string.
  1410. The name <I>xx</I> is removed from the name list and
  1411. any related storage space is freed.
  1412. Subsequent references will have no effect.
  1413. If many macros and strings are being created dynamically, it
  1414. may become necessary to remove unused ones
  1415. to recapture internal storage space for newer registers.
  1416. </dl>
  1417. <br>&#32;<br>
  1418. <TT>&rn</TT><I> xx yy</I> - ignored -
  1419. <DL COMPACT>
  1420. <DT><DD>
  1421. Rename request, macro, or string
  1422. <I>xx</I> to <I>yy</I>.
  1423. If <I>yy</I> exists, it is first removed.
  1424. </dl>
  1425. <br>&#32;<br>
  1426. <TT>&di</TT><I> xx</I> - end D
  1427. <DL COMPACT>
  1428. <DT><DD>
  1429. Divert output to macro <I>xx</I>.
  1430. Normal text processing occurs during diversion
  1431. except that page offsetting is not done.
  1432. The diversion ends when the request <TT>di</TT> or <TT>da</TT> is encountered without an argument;
  1433. extraneous
  1434. requests of this type should not appear when nested diversions are being used.
  1435. </dl>
  1436. <br>&#32;<br>
  1437. <TT>&da </TT><I>xx</I> - end D
  1438. <DL COMPACT>
  1439. <DT><DD>
  1440. Divert, appending to macro <I>xx</I>
  1441. (append version of <TT>di</TT>).
  1442. </dl>
  1443. <br>&#32;<br>
  1444. <TT>&wh</TT><I> N xx</I> - - <B>v</B>
  1445. <DL COMPACT>
  1446. <DT><DD>
  1447. Install
  1448. a trap to invoke <I>xx</I> at page position <I>N</I>;
  1449. a negative N will be interpreted as a distance from the
  1450. page bottom.
  1451. Any macro previously planted at <I>N</I> is replaced by <I>xx</I>.
  1452. A zero <I>N</I> refers to the top of a page.
  1453. In the absence of <I>xx</I>, the first trap found at <I>N</I>, if any, is removed.
  1454. </dl>
  1455. <br>&#32;<br>
  1456. <TT>&ch</TT><I> xx N</I> - - <B>v</B>
  1457. <DL COMPACT>
  1458. <DT><DD>
  1459. Change
  1460. the trap position for macro <I>xx</I> to be <I>N</I>.
  1461. In the absence of <I>N</I>, the trap, if any, is removed.
  1462. </dl>
  1463. <br>&#32;<br>
  1464. <TT>&dt</TT><I> N xx</I> - off D,<B>v</B>
  1465. <DL COMPACT>
  1466. <DT><DD>
  1467. Install a diversion trap
  1468. at position <I>N</I> in the <I>current</I> diversion to invoke
  1469. macro <I>xx</I>.
  1470. Another <TT>dt</TT> will redefine the diversion trap.
  1471. If no arguments are given, the diversion trap is removed.
  1472. </dl>
  1473. <br>&#32;<br>
  1474. <TT>&it</TT><I> N xx</I> - off E
  1475. <DL COMPACT>
  1476. <DT><DD>
  1477. Set an input-line-count trap
  1478. to invoke the macro <I>xx</I> after <I>N</I> lines of <I>text</I> input
  1479. have been read
  1480. (control or request lines do not count).
  1481. The text may be inline text or
  1482. text interpolated by inline or trap-invoked macros.
  1483. </dl>
  1484. <br>&#32;<br>
  1485. <TT>&em</TT><I> xx</I> none none -
  1486. <DL COMPACT>
  1487. <DT><DD>
  1488. The
  1489. macro <I>xx</I> will be invoked
  1490. when all input has ended.
  1491. The effect is almost as if the contents of <I>xx</I> had been at the end
  1492. of the last file processed,
  1493. but all processing ceases at the next page eject.
  1494. </dl>
  1495. <H4>8 Number Registers
  1496. </H4>
  1497. <P>
  1498. A variety of parameters are available to the user as
  1499. predefined <I>number registers</I> (see Summary, page 0u+7u).
  1500. In addition, users may define their own registers.
  1501. Register names are one or two characters long and do not conflict
  1502. with request, macro, or string names.
  1503. Except for certain predefined read-only registers,
  1504. a number register can be read, written, automatically
  1505. incremented or decremented, and interpolated
  1506. into the input in a variety of formats.
  1507. One common use of user-defined registers is to
  1508. automatically number sections, paragraphs, lines, etc.
  1509. A number register may be used any time numerical input is expected or desired
  1510. and may be used in numerical <I>expressions</I> (&#167;1.4).
  1511. </P>
  1512. <P>
  1513. Number registers are created and modified using <TT>nr</TT>, which
  1514. specifies the name, numerical value, and the auto-increment size.
  1515. Registers are also modified, if accessed
  1516. with an auto-incrementing sequence.
  1517. If the registers <I>x</I> and <I>xx</I> both contain
  1518. <I>N</I> and have the auto-increment size <I>M</I>,
  1519. the following access sequences have the effect shown:
  1520. <br><img src="-.16259.gif"><br>
  1521. When interpolated, a number register is converted to
  1522. decimal (default),
  1523. decimal with leading zeros,
  1524. lower-case Roman,
  1525. upper-case Roman,
  1526. lower-case sequential alphabetic,
  1527. or
  1528. upper-case sequential alphabetic
  1529. according to the format specified by <TT>af</TT>.
  1530. </P>
  1531. <br>&#32;<br>
  1532. <TT>&nr</TT><I> R &#177;N M</I> - <B>u</B>
  1533. <DL COMPACT>
  1534. <DT><DD>
  1535. The number register
  1536. <I>R</I> is assigned the value &#177;<I>N</I>
  1537. with respect to the previous value, if any.
  1538. The increment for auto-incrementing is set to <I>M</I>.
  1539. </dl>
  1540. <br>&#32;<br>
  1541. <TT>&af</TT><I> R c</I> arabic - -
  1542. <DL COMPACT>
  1543. <DT><DD>
  1544. Assign
  1545. format <I>c</I> to register <I>R</I>.
  1546. The available formats are:
  1547. <br><img src="-.162510.gif"><br>
  1548. An arabic format having <I>N</I> digits
  1549. specifies a field width of <I>N</I> digits (example 2 above).
  1550. The read-only registers and the width function
  1551. (&#167;11.2)
  1552. are always arabic.
  1553. Warning: the value of a number register in a non-Arabic format
  1554. is not numeric, and will not produce the expected results in expressions.
  1555. <DT><DT>&#32;<DD>
  1556. The function
  1557. or
  1558. returns the format of a number register in a form suitable for
  1559. it returns nothing if the register has not been used.
  1560. </dl>
  1561. <br>&#32;<br>
  1562. <TT>&rr</TT><I> R</I> - ignored -
  1563. <DL COMPACT>
  1564. <DT><DD>
  1565. Remove number register <I>R</I>.
  1566. If many registers are being created dynamically, it
  1567. may become necessary to remove unused registers
  1568. to recapture internal storage space for newer registers.
  1569. The register
  1570. contains the number of number registers still available.
  1571. </dl>
  1572. <H4>9 Tabs, Leaders, and Fields
  1573. </H4>
  1574. <br>&#32;<br>
  1575. <B><I>0.0s. Tabs and leaders.</I></B>
  1576. The ASCII horizontal tab character and the ASCII
  1577. SOH (control-A, hereafter called the <I>leader</I> character)
  1578. can both be used to generate either horizontal motion or
  1579. a string of repeated characters.
  1580. The length of the generated entity is governed
  1581. by internal <I>tab stops</I> specifiable
  1582. with <TT>ta</TT>.
  1583. The default difference is that tabs generate motion and leaders generate
  1584. a string of periods;
  1585. <TT>tc</TT> and <TT>lc</TT>
  1586. offer the choice of repeated character or motion.
  1587. There are three types of internal tab stops&#173;
  1588. <I>left</I> adjusting, <I>right</I> adjusting,
  1589. and <I>centering</I>.
  1590. In the following table,
  1591. <I>D</I> is the distance from the current position on the <I>input</I> line
  1592. (where a tab or leader was found)
  1593. to the next tab stop,
  1594. <I>next-string</I> consists
  1595. of the input characters following the tab (or leader) up to the next tab (or leader) or end of line,
  1596. and
  1597. <I>W</I> is the width of <I>next-string</I>.
  1598. <br><img src="-.162511.gif"><br>
  1599. The length of generated motion is allowed to be negative, but
  1600. that of a repeated character string cannot be.
  1601. Repeated character strings contain an integer number of characters, and
  1602. any residual distance is prepended as motion.
  1603. Tabs or leaders found after the last tab stop are ignored, but may be used
  1604. as <I>next-string</I> terminators.
  1605. <P>
  1606. Tabs and leaders are not interpreted in copy mode.
  1607. <TT>\t</TT> and <TT>\a</TT> always generate a non-interpreted
  1608. tab and leader respectively, and
  1609. are equivalent to actual tabs and leaders in copy mode.
  1610. </P>
  1611. <br>&#32;<br>
  1612. <B><I>0.0s. Fields.</I></B>
  1613. A <I>field</I> is contained between
  1614. a pair of <I>field delimiter</I> characters,
  1615. and consists of substrings
  1616. separated by <I>padding</I> indicator characters.
  1617. The field length is the distance on the
  1618. <I>input</I> line from the position where the field begins to the next tab stop.
  1619. The difference between the total length of all the substrings
  1620. and the field length is incorporated as horizontal
  1621. padding space that is divided among the indicated
  1622. padding places.
  1623. The incorporated padding is allowed to be negative.
  1624. For example,
  1625. if the field delimiter is <TT>#</TT> and the padding indicator is <TT>^</TT>,
  1626. <TT>#^</TT><I>xxx</I><TT>^</TT><I>right</I><TT>#</TT>
  1627. specifies a right-adjusted string with the string <I>xxx</I> centered
  1628. in the remaining space.
  1629. <br>&#32;<br>
  1630. <TT>&ta</TT><I> Nt ...</I> 0.8; 0.5in none E,<B>m</B>
  1631. <DL COMPACT>
  1632. <DT><DD>
  1633. Set tab stops and types.
  1634. <I>t=</I><TT>R</TT>, right adjusting;
  1635. <I>t=</I><TT>C</TT>, centering;
  1636. <I>t</I> absent, left adjusting.
  1637. <I>Troff</I> tab stops are preset every 0.5in.,
  1638. <I>nroff</I> every 0.8in.
  1639. The stop values are separated by spaces, and
  1640. a value preceded by <TT>+</TT>
  1641. is treated as an increment to the previous stop value.
  1642. </dl>
  1643. <br>&#32;<br>
  1644. <TT>&tc</TT><I> c</I> none none E
  1645. <DL COMPACT>
  1646. <DT><DD>
  1647. The tab repetition character
  1648. becomes <I>c</I>,
  1649. or is removed, thus specifying motion.
  1650. </dl>
  1651. <br>&#32;<br>
  1652. <TT>&lc</TT><I> c</I> <TT>.</TT> none E
  1653. <DL COMPACT>
  1654. <DT><DD>
  1655. The leader repetition character
  1656. becomes <I>c</I>,
  1657. or is removed, thus specifying motion.
  1658. </dl>
  1659. <br>&#32;<br>
  1660. <TT>&fc</TT><I> a b</I> off off -
  1661. <DL COMPACT>
  1662. <DT><DD>
  1663. The field delimiter
  1664. is set to <I>a</I>;
  1665. the padding indicator is set to the space character or to
  1666. <I>b</I>, if given.
  1667. In the absence of arguments the field mechanism is turned off.
  1668. </dl>
  1669. <H4>10 Input and Output Conventions and Character Translations
  1670. </H4>
  1671. <br>&#32;<br>
  1672. <B><I>0.0s. Input character translations.</I></B>
  1673. Ways of inputting the valid character set were
  1674. discussed in &#167;2.1.
  1675. The ASCII control characters horizontal tab (&#167;9.1),
  1676. SOH (&#167;9.1), and backspace (&#167;10.3) are discussed elsewhere.
  1677. The newline delimits input lines.
  1678. In addition,
  1679. STX, ETX, ENQ, ACK, and BEL
  1680. are accepted,
  1681. and may be used as delimiters or translated into a graphic with <TT>tr</TT> (&#167;10.5).
  1682. All others are ignored.
  1683. <P>
  1684. The <I>escape</I> character <TT>\</TT>
  1685. introduces <I>escape sequences</I>,
  1686. which cause the following character to mean
  1687. another character, or to indicate
  1688. some function.
  1689. A complete list of such sequences is given in the Summary on page 0u+7u.
  1690. The escape character <TT>\</TT>
  1691. should not be confused with the ASCII control character ESC.
  1692. The escape character <TT>\</TT> can be input with the sequence <TT>\\</TT>.
  1693. The escape character can be changed with <TT>ec</TT>,
  1694. and all that has been said about the default <TT>\</TT> becomes true
  1695. for the new escape character.
  1696. <TT>\e</TT> can be used to print whatever the current escape character is.
  1697. The escape mechanism may be turned off with <TT>eo</TT>,
  1698. and restored with <TT>ec</TT>.
  1699. </P>
  1700. <br>&#32;<br>
  1701. <TT>&ec</TT><I> c</I> <TT></TT> <TT></TT> -
  1702. <DL COMPACT>
  1703. <DT><DD>
  1704. Set escape character
  1705. to <TT></TT>, or to <I>c</I>, if given.
  1706. </dl>
  1707. <br>&#32;<br>
  1708. <TT>&eo</TT> on - -
  1709. <DL COMPACT>
  1710. <DT><DD>
  1711. Turn escape mechanism off.
  1712. </dl>
  1713. <br>&#32;<br>
  1714. <B><I>0.0s. Ligatures.</I></B>
  1715. The set of available ligatures is device and font dependent,
  1716. but is often a subset of
  1717. <B>fi</B>, <B>fl</B>, <B>ff</B>, <B>ffi</B>, and <B>ffl</B>.
  1718. They may be input by
  1719. <TT>\(fi</TT>, <TT>\(fl</TT>, <TT>\(ff</TT>, <TT>\(Fi</TT>, and <TT>\(Fl</TT> respectively.
  1720. The ligature mode is normally on in <I>troff</I>, and automatically invokes
  1721. ligatures during input.
  1722. <br>&#32;<br>
  1723. <TT>&lg</TT><I> N</I> on; off on -
  1724. <DL COMPACT>
  1725. <DT><DD>
  1726. Ligature mode
  1727. is turned on if <I>N</I> is absent or non-zero,
  1728. and turned off if <I>N=</I>0.
  1729. If <I>N=</I>2, only the two-character ligatures are automatically invoked.
  1730. Ligature mode is inhibited for
  1731. request, macro, string, register, or file names,
  1732. and in copy mode.
  1733. No effect in <I>nroff</I>.
  1734. </dl>
  1735. <br>&#32;<br>
  1736. <B><I>0.0s. Backspacing, underlining, overstriking, etc.</I></B>
  1737. Unless in copy mode, the ASCII backspace character is replaced
  1738. by a backward horizontal motion having the width of the
  1739. space character.
  1740. Underlining as a form of line-drawing is discussed in &#167;12.4.
  1741. A generalized overstriking function is described in &#167;12.1.
  1742. <P>
  1743. <I>Nroff</I> automatically underlines
  1744. characters in the <I>underline</I> font,
  1745. specifiable with <TT>uf</TT>,
  1746. normally that on font position 2.
  1747. In addition to <TT>ft</TT> and
  1748. the underline font may be selected by <TT>ul</TT> and <TT>cu</TT>.
  1749. Underlining is restricted to an output-device-dependent
  1750. subset of reasonable characters.
  1751. </P>
  1752. <br>&#32;<br>
  1753. <TT>&ul</TT><I> N</I> off <I>N=</I>1 E
  1754. <DL COMPACT>
  1755. <DT><DD>
  1756. Italicize in <I>troff</I>
  1757. (underline in <I>nroff</I>) the next <I>N</I>
  1758. input text lines.
  1759. Actually, switch to underline font, saving the
  1760. current font for later restoration;
  1761. other font changes within the span of a <TT>ul</TT>
  1762. will take effect,
  1763. but the restoration will undo the last change.
  1764. Output generated by <TT>tl</TT> (&#167;14) is affected by the
  1765. font change, but does not decrement <I>N</I>.
  1766. If <I>N&#62;</I>1, there is the risk that
  1767. a trap interpolated macro may provide text
  1768. lines within the span;
  1769. environment switching can prevent this.
  1770. </dl>
  1771. <br>&#32;<br>
  1772. <TT>&cu</TT><I> N</I> off <I>N=</I>1 E
  1773. <DL COMPACT>
  1774. <DT><DD>
  1775. Continuous underline.
  1776. A variant
  1777. of <TT>ul</TT> that causes <I>every</I> character to be underlined in <I>nroff</I>.
  1778. Identical to <TT>ul</TT> in <I>troff</I>.
  1779. </dl>
  1780. <br>&#32;<br>
  1781. <TT>&uf</TT><I> F</I> Italic Italic -
  1782. <DL COMPACT>
  1783. <DT><DD>
  1784. Underline font set to <I>F</I>.
  1785. In <I>nroff</I>,
  1786. <I>F</I> may not be on position 1.
  1787. </dl>
  1788. <br>&#32;<br>
  1789. <B><I>0.0s. Control characters.</I></B>
  1790. Both the control character <TT>.</TT> and the <I>no-break</I>
  1791. control character <TT>'</TT> may be changed.
  1792. Such a change must be compatible with the design
  1793. of any macros used in the span of the change,
  1794. and
  1795. particularly of any trap-invoked macros.
  1796. <br>&#32;<br>
  1797. <TT>&cc</TT><I> c</I> <TT>.</TT> <TT>.</TT> E
  1798. <DL COMPACT>
  1799. <DT><DD>
  1800. The basic control character
  1801. is set to <I>c</I>,
  1802. or reset to ``<TT>.</TT>''.
  1803. </dl>
  1804. <br>&#32;<br>
  1805. <TT>&c2</TT><I> c</I> <TT>' '</TT> E
  1806. <DL COMPACT>
  1807. <DT><DD>
  1808. The <I>no-break</I> control character is set
  1809. to <I>c</I>, or reset to ``<TT>'</TT>''.
  1810. </dl>
  1811. <br>&#32;<br>
  1812. <B><I>0.0s. Output translation.</I></B>
  1813. One character can be made a stand-in for another character using <TT>tr</TT>.
  1814. All text processing (e.g., character comparisons) takes place
  1815. with the input (stand-in) character, which appears to have the width of the final
  1816. character.
  1817. The graphic translation occurs at the moment of output
  1818. (including diversion).
  1819. <br>&#32;<br>
  1820. <TT>&tr</TT><I> abcd....</I> none - O
  1821. <DL COMPACT>
  1822. <DT><DD>
  1823. Translate
  1824. <I>a</I> into <I>b</I>, <I>c</I> into <I>d</I>, etc.
  1825. If an odd number of characters is given,
  1826. the last one will be mapped into the space character.
  1827. To be consistent, a particular translation
  1828. must stay in effect from <I>input</I> to <I>output</I> time.
  1829. </dl>
  1830. <br>&#32;<br>
  1831. <B><I>0.0s. Transparent throughput.</I></B>
  1832. An input line beginning with a <TT>\!</TT> is read in copy mode and <I>transparently</I> output
  1833. (without the initial <TT>\!</TT>);
  1834. the text processor is otherwise unaware of the line's presence.
  1835. This mechanism may be used to pass control information to a post-processor
  1836. or to embed control lines in a macro created by a diversion.
  1837. <br>&#32;<br>
  1838. <B><I>0.0s. Transparent output</I></B>
  1839. The sequence
  1840. copies
  1841. <I>anything</I>
  1842. to the output, as a device control function of the form
  1843. <I>anything</I>
  1844. (&#167;22).
  1845. Escape sequences in
  1846. <I>anything</I>
  1847. are processed.
  1848. <br>&#32;<br>
  1849. <B><I>0.0s. Comments and concealed newlines.</I></B>
  1850. An uncomfortably long input line that must stay
  1851. one line (e.g., a string definition, or nofilled text)
  1852. can be split into several physical lines by ending all but
  1853. the last one with the escape <TT>\</TT>.
  1854. The sequence <TT></TT><I>newline</I> is always ignored,
  1855. except in a comment.
  1856. Comments may be embedded at the end of any line by
  1857. prefacing them with <TT>\"</TT>.
  1858. The newline at the end of a comment cannot be concealed.
  1859. A line beginning with <TT>\"</TT> will appear as a blank line and
  1860. behave like
  1861. a comment can be on a line by itself by beginning the line with <TT>.\"</TT>.
  1862. <H4>11 Local Horizontal and Vertical Motions, and the Width Function
  1863. </H4>
  1864. <br>&#32;<br>
  1865. <B><I>0.0s. Local Motions.</I></B>
  1866. The functions <TT>\v'</TT><I>N</I><TT>'</TT> and
  1867. <TT>\h'</TT><I>N</I><TT>'</TT>
  1868. can be used for <I>local</I> vertical and horizontal motion respectively.
  1869. The distance <I>N</I> may be negative; the positive directions
  1870. are rightward and downward.
  1871. A local motion is one contained within a line.
  1872. To avoid unexpected vertical dislocations, it is necessary that
  1873. the net vertical local motion within a word in filled text
  1874. and otherwise within a line balance to zero.
  1875. The escape sequences providing local motion are
  1876. summarized in the following table.
  1877. <br><img src="-.162512.gif"><br>
  1878. As an example,
  1879. <TT>E^2</TT>
  1880. could be generated by a sequence of size changes and motions:
  1881. <TT>E\s-2\v'-0.4m'2\v'0.4m'\s+2</TT>;
  1882. note that
  1883. the 0.4 em vertical motions are at the smaller size.
  1884. <br>&#32;<br>
  1885. <B><I>0.0s. Width Function.</I></B>
  1886. The <I>width</I> function <TT>\w'</TT><I>string</I><TT>'</TT>
  1887. generates the numerical width of <I>string</I> (in basic units).
  1888. Size and font changes may be embedded in <I>string</I>,
  1889. and will not affect the current environment.
  1890. For example,
  1891. <TT>.ti -\w'\fB1. 'u</TT> could be used to
  1892. temporarily indent leftward a distance equal to the
  1893. size of the string ``<TT>1. </TT>'' in font
  1894. <P>
  1895. The width function also sets three number registers.
  1896. The registers <TT>st</TT> and <TT>sb</TT> are set respectively to the highest and
  1897. lowest extent of <I>string</I> relative to the baseline;
  1898. then, for example,
  1899. the total height of the string is <TT>\n(stu-\n(sbu</TT>.
  1900. In <I>troff</I> the number register <TT>ct</TT> is set to a value
  1901. between 0 and 3.
  1902. The value
  1903. 0 means that all of the characters in <I>string</I> were short lower
  1904. case characters without descenders (like <TT>e</TT>);
  1905. 1 means that at least one character has a descender (like <TT>y</TT>);
  1906. 2 means that at least one character is tall (like <TT>H</TT>);
  1907. and 3 means that both tall characters and characters with
  1908. descenders are present.
  1909. </P>
  1910. <br>&#32;<br>
  1911. <B><I>0.0s. Mark horizontal place.</I></B>
  1912. The function <TT>\k</TT><I>x</I> causes the current horizontal
  1913. position in the <I>input line</I> to be stored in register <I>x</I>.
  1914. For example,
  1915. the construction <TT>\kx</TT><I>word</I><TT>\h'|\nxu+3u'</TT><I>word</I><TT></TT>
  1916. will embolden <I>word</I> by backing up to almost its beginning and overprinting it,
  1917. resulting in <I>word</I>h'|0u+3u'<I>word</I>.
  1918. <H4>12 Overstrike, Bracket, Line-drawing, Graphics, and Zero-width Functions
  1919. </H4>
  1920. <br>&#32;<br>
  1921. <B><I>0.0s. Overstriking.</I></B>
  1922. Automatically centered overstriking of up to nine characters
  1923. is provided by the <I>overstrike</I> function
  1924. <TT>\o'</TT><I>string</I><TT>'</TT>.
  1925. The characters in <I>string</I> are overprinted with centers aligned; the total width
  1926. is that of the widest character.
  1927. <I>string</I> may not contain local vertical motion.
  1928. As examples,
  1929. <TT>\o'e\''</TT> produces o'e'', and
  1930. <TT>\o'\(mo\(sl'</TT> produces o'C/'.
  1931. <br>&#32;<br>
  1932. <B><I>0.0s. Zero-width characters.</I></B>
  1933. The function
  1934. will output <I>c</I> without spacing over
  1935. it, and can be used to produce left-aligned overstruck
  1936. combinations.
  1937. As examples,
  1938. <TT>\z&#164;+</TT> will produce z&#164;+, and
  1939. <TT>\(br\z\(rn\(ul\(br</TT> will produce a small
  1940. badly constructed box |z _|.
  1941. <br>&#32;<br>
  1942. <B><I>0.0s. Large Brackets.</I></B>
  1943. The Special Font usually contains a number of bracket construction pieces
  1944. (())|||||||
  1945. that can be combined into various bracket styles.
  1946. The function <TT>\b'</TT><I>string</I><TT>'</TT> may be used to pile
  1947. up vertically the characters in <I>string</I>
  1948. (the first character on top and the last at the bottom);
  1949. the characters are vertically separated by 1 em and the total
  1950. pile is centered 1/2 em above the current baseline
  1951. (&#189; line in <I>nroff</I>).
  1952. For example,
  1953. <DL><DT><DD><TT><PRE>
  1954. \b'\(lc\(lf'E\b'\(rc\(rf'\x'-0.5m'\x'0.5m'
  1955. </PRE></TT></DL>
  1956. produces
  1957. x'-.5m'x'.5m'b'||'Eb'||'.
  1958. <br>&#32;<br>
  1959. <B><I>0.0s. Line drawing.</I></B>
  1960. The function <TT><HR></TT> (backslash-ell) draws a string of repeated <I>c</I>'s towards the right for a distance <I>N</I>.
  1961. If <I>c</I> looks like a continuation of
  1962. an expression for <I>N</I>, it may be insulated from <I>N</I> with <TT></TT>.
  1963. If <I>c</I> is not specified, the <TT>_</TT> (baseline rule) is used
  1964. (underline character in <I>nroff</I>).
  1965. If <I>N</I> is negative, a backward horizontal motion
  1966. of size <I>N</I> is made before drawing the string.
  1967. Any space resulting from <I>N</I>/(size of <I>c</I>) having a remainder is put at the beginning (left end)
  1968. of the string.
  1969. If <I>N</I> is less than the width of <I>c</I>,
  1970. a single <I>c</I> is centered on a distance <I>N</I>.
  1971. In the case of characters
  1972. that are designed to be connected, such as
  1973. baseline-rule <TT>_</TT>,
  1974. under-rule <TT>_</TT>,
  1975. and
  1976. root-en <TT> </TT>,
  1977. the remainder space is covered by overlapping.
  1978. As an example, a macro to underscore a string can be written
  1979. <DL><DT><DD><TT><PRE>
  1980. &amp;de us
  1981. \\$1\l'|0\(ul'
  1982. &amp;&amp;
  1983. </PRE></TT></DL>
  1984. or one to draw a box around a string
  1985. <DL><DT><DD><TT><PRE>
  1986. &amp;de bx
  1987. \(br\|\\$1\|\(br\l'|0\(rn'\l'|0\(ul'
  1988. &amp;&amp;
  1989. </PRE></TT></DL>
  1990. such that
  1991. <DL><DT><DD><TT><PRE>
  1992. &amp;ul "underlined words"
  1993. </PRE></TT></DL>
  1994. and
  1995. <DL><DT><DD><TT><PRE>
  1996. &amp;bx "words in a box"
  1997. </PRE></TT></DL>
  1998. yield
  1999. underlined words<HR>
  2000. and
  2001. |words in a box|<HR><HR>
  2002. h'-w'.'u'.
  2003. <P>
  2004. The function <TT>\L'</TT><I>Nc</I><TT>'</TT> draws a vertical line consisting
  2005. of the (optional) character <I>c</I> stacked vertically apart 1em
  2006. (1 line in <I>nroff</I>),
  2007. with the first two characters overlapped,
  2008. if necessary, to form a continuous line.
  2009. The default character is the <I>box rule</I> | (<TT>\(br</TT>);
  2010. the other suitable character is the <I>bold vertical</I> | (<TT>\(bv</TT>).
  2011. The line is begun without any initial motion relative to the
  2012. current baseline.
  2013. A positive <I>N</I> specifies a line drawn downward and
  2014. a negative <I>N</I> specifies a line drawn upward.
  2015. After the line is drawn no compensating
  2016. motions are made;
  2017. the instantaneous baseline is at the end of the line.
  2018. </P>
  2019. <P>
  2020. The horizontal and vertical line drawing functions may be used
  2021. in combination to produce large boxes.
  2022. The zero-width <I>box-rule</I> and the &#189;-em wide <I>under-rule</I>
  2023. were designed to form corners when using 1-em vertical
  2024. spacings.
  2025. For example the macro
  2026. <DL><DT><DD><TT><PRE>
  2027. .de eb
  2028. .sp -1 \"compensate for next automatic baseline spacing
  2029. .nf \"avoid possibly overflowing word buffer
  2030. \h'-.5n'\L'|\\nau-1'\l'\\n(.lu+1n\(ul'\L'-|\\nau+1'\l'|0u-.5n\(ul'
  2031. .fi
  2032. ..
  2033. </PRE></TT></DL>
  2034. will draw a box around some text whose beginning vertical place was
  2035. saved in number register <I>a</I>
  2036. (e.g., using <TT>.mk a</TT>)
  2037. as was done for this paragraph.
  2038. <br>&#32;<br>
  2039. <DL><DT><DD><TT><PRE>
  2040. h'-.5n'L'|0+1u-1'<HR>L'-|0+1u+1'<HR>
  2041. </PRE></TT></DL>
  2042. </P>
  2043. <br>&#32;<br>
  2044. <B><I>0.0s. Graphics.</I></B>
  2045. The function
  2046. draws a graphic object of type <I>c</I>
  2047. according to a sequence of parameters,
  2048. which are generally pairs of numbers.
  2049. <DL>
  2050. <DT><DT>&#32;<DD>
  2051. <DL><DT><DD><TT><PRE>
  2052. <TT>D'l </TT><I>dh</I><TT> </TT><I>dv</I><TT>' </TT>draw line from current position by <I>dh</I>, <I>dv</I><TT>
  2053. </TT><TT>D'c </TT><I>d</I><TT>' </TT>draw circle of diameter <I>d</I> with left side at current position<TT>
  2054. </TT><TT>D'e </TT><I>d</I><TT></TT>1<TT></TT><I>d</I><TT></TT>2<TT>' </TT>draw ellipse of diameters <I>d</I>1 and <I>d</I>2<TT>
  2055. </TT><TT>D'a </TT><I>dh</I><TT></TT>1<TT> </TT><I>dv</I><TT></TT>1<TT> </TT><I>dh</I><TT></TT>2<TT> </TT><I>dv</I><TT></TT>2<TT>'</TT><TT> </TT>draw arc from current position to <I>dh</I>1<I>+dh</I>2, <I>dv</I>1<I>+dv</I>2,<TT>
  2056. </TT>with center at <I>dh</I>1, <I>dv</I>1 from current position<TT>
  2057. </TT><TT>D'~ </TT><I>dh</I><TT></TT>1<TT></TT><I>dv</I><TT></TT>1<TT></TT><I>dh</I><TT></TT>2<TT></TT><I>dv</I><TT></TT>2<TT></TT><I>...</I><TT>'</TT><TT> </TT>draw B-spline from current position by <I>dh</I>1<I></I>,<I>dv</I>1,<TT>
  2058. </TT>then by <I>dh</I>2,<I>dv</I>2, then by <I>dh</I>2,<I>dv</I>2, then ...<TT>
  2059. </PRE></TT></DL>
  2060. </dl>
  2061. </TT><br>&#32;<br>
  2062. For example,
  2063. draws the ellipse
  2064. D'e.2i .1i',
  2065. and
  2066. the line
  2067. D'l.2i -.1i'D'l.1i .1i'.
  2068. A
  2069. with an unknown <I>c</I> is processed and copied through to the output
  2070. for unspecified interpretation;
  2071. coordinates are interpreted alternately as horizontal and vertical
  2072. values.
  2073. <P>
  2074. Numbers taken as horizontal (first, third, etc.) have default scaling of ems;
  2075. vertical numbers (second, fourth, etc.) have default scaling of <I>V</I>s (&#167;1.3).
  2076. The position after a graphical object has been drawn is
  2077. at its end; for circles and ellipses, the ``end''
  2078. is at the right side.
  2079. </P>
  2080. <H4>13 Hyphenation.
  2081. </H4>
  2082. <P>
  2083. Automatic hyphenation may be switched off and on.
  2084. When switched on with <TT>hy</TT>,
  2085. several variants may be set.
  2086. A <I>hyphenation indicator</I> character may be embedded in a word to
  2087. specify desired hyphenation points,
  2088. or may be prefixed to suppress hyphenation.
  2089. In addition,
  2090. the user may specify a small list of exception words.
  2091. </P>
  2092. <P>
  2093. Only words that consist of a central alphabetic string
  2094. surrounded by (usually null) non-alphabetic strings
  2095. are candidates for automatic hyphenation.
  2096. Words that contain hyphens
  2097. (minus),
  2098. em-dashes (<TT>\(em</TT>),
  2099. or hyphenation indicator characters
  2100. are always subject to splitting after those characters,
  2101. whether automatic hyphenation is on or off.
  2102. </P>
  2103. <br>&#32;<br>
  2104. <TT>&nh</TT> hyphenate - E
  2105. <DL COMPACT>
  2106. <DT><DD>
  2107. Automatic hyphenation is turned off.
  2108. </dl>
  2109. <br>&#32;<br>
  2110. <TT>&hy</TT> <I>N</I> on, <I>N=</I>1 on, <I>N=</I>1 E
  2111. <DL COMPACT>
  2112. <DT><DD>
  2113. Automatic hyphenation is turned on
  2114. for <I>N</I>>=1, or off for <I>N=</I>0.
  2115. If <I>N=</I>2, last lines (ones that will cause a trap)
  2116. are not hyphenated.
  2117. For <I>N=</I>4 and 8, the last and first two characters
  2118. respectively of a word are not split off.
  2119. These values are additive;
  2120. i.e., <I>N=</I>14 will invoke all three restrictions.
  2121. </dl>
  2122. <br>&#32;<br>
  2123. <TT>&hc</TT><I> c</I> <TT> </TT> E
  2124. <DL COMPACT>
  2125. <DT><DD>
  2126. Hyphenation indicator character is set
  2127. to <I>c</I> or to the default <TT></TT>.
  2128. The indicator does not appear in the output.
  2129. </dl>
  2130. <br>&#32;<br>
  2131. <TT>&hw</TT><I> word ...</I> ignored -
  2132. <DL COMPACT>
  2133. <DT><DD>
  2134. Specify
  2135. hyphenation points in words
  2136. with embedded minus signs.
  2137. Versions of a word with terminal <I>s</I> are implied;
  2138. i.e.,
  2139. implies
  2140. This list is examined initially and after
  2141. each suffix stripping.
  2142. The space available is small.
  2143. </dl>
  2144. <H4>14 Three-Part Titles.
  2145. </H4>
  2146. <P>
  2147. The titling function <TT>tl</TT> provides for automatic placement
  2148. of three fields at the left, center, and right of a line
  2149. with a title length
  2150. specifiable with <TT>lt</TT>.
  2151. <TT>tl</TT> may be used anywhere, and is independent of the
  2152. normal text collecting process.
  2153. A common use is in header and footer macros.
  2154. </P>
  2155. <br>&#32;<br>
  2156. <TT>&tl '</TT><I>left</I><TT>'</TT><I>center</I><TT>'</TT><I>right</I><TT>'</TT> - -
  2157. <DL COMPACT>
  2158. <DT><DD>
  2159. The strings
  2160. <I>left</I>, <I>center</I>, and <I>right</I> are
  2161. respectively left-adjusted, centered, and right-adjusted
  2162. in the current title length.
  2163. Any of the strings may be empty,
  2164. and overlapping is permitted.
  2165. If the page-number character (initially <TT>%</TT>) is found within any of the fields it is replaced
  2166. by the current page number in the format assigned to register <TT>%</TT>.
  2167. Any character may be used in place of
  2168. as the string delimiter.
  2169. </dl>
  2170. <br>&#32;<br>
  2171. <TT>&pc</TT><I> c</I> <TT>%</TT> off -
  2172. <DL COMPACT>
  2173. <DT><DD>
  2174. The page number character is set to <I>c</I>,
  2175. or removed.
  2176. The page number register remains <TT>%</TT>.
  2177. </dl>
  2178. <br>&#32;<br>
  2179. <TT>&lt</TT><I> &#177;N</I> 6.5in previous E,<B>m</B>
  2180. <DL COMPACT>
  2181. <DT><DD>
  2182. Length of title
  2183. is set to &#177;<I>N</I>.
  2184. The line length and the title length are independent.
  2185. Indents do not apply to titles; page offsets do.
  2186. </dl>
  2187. <H4>15 Output Line Numbering.
  2188. </H4>
  2189. <P>
  2190. Automatic sequence numbering of output lines may be
  2191. requested with <TT>nm</TT>.
  2192. When in effect,
  2193. a three-digit, arabic number plus a digit-space
  2194. is prefixed to output text lines.
  2195. The text lines are thus offset by four digit-spaces,
  2196. and otherwise retain their line length;
  2197. a reduction in line length may be desired to keep the right margin
  2198. aligned with an earlier margin.
  2199. Blank lines, other vertical spaces, and lines generated by <TT>tl</TT>
  2200. are not numbered.
  2201. Numbering can be temporarily suspended with <TT>nn</TT>,
  2202. or with an <TT>.nm</TT> followed by a later <TT>.nm +0</TT>.
  2203. In addition,
  2204. a line number indent <I>I</I>, and the number-text separation <I>S</I>
  2205. may be specified in digit-spaces.
  2206. Further, it can be specified that only those line numbers that are
  2207. multiples of some number <I>M</I> are to be printed (the others will appear
  2208. as blank number fields).
  2209. <br>
  2210. </P>
  2211. <br>&#32;<br>
  2212. <TT>&nm</TT><I> &#177;N M S I</I> off E
  2213. <DL COMPACT>
  2214. <DT><DD>
  2215. Line number mode.
  2216. If &#177;<I>N</I> is given,
  2217. line numbering is turned on,
  2218. and the next output line numbered is numbered &#177;<I>N</I>.
  2219. Default values are <I>M=</I>1, <I>S=</I>1, and <I>I=</I>0.
  2220. Parameters corresponding to missing arguments are unaffected;
  2221. a non-numeric argument is considered missing.
  2222. In the absence of all arguments, numbering is turned off;
  2223. the next line number is preserved for possible further use
  2224. in number register <TT>ln</TT>.
  2225. </dl>
  2226. <br>&#32;<br>
  2227. <TT>&nn</TT><I> N</I> - <I>N=</I>1 E
  2228. <DL COMPACT>
  2229. <DT><DD>
  2230. The next <I>N</I> text output lines are not
  2231. numbered.
  2232. </dl>
  2233. <P>
  2234. As an example, the paragraph portions of this section
  2235. are numbered with <I>M=</I>3:
  2236. <TT>.nm 1 3</TT> was placed at the beginning;
  2237. <TT>.nm</TT> was placed at the end of the first paragraph;
  2238. and <TT>.nm +0</TT> was placed in front of this paragraph;
  2239. and <TT>.nm</TT> finally placed at the end.
  2240. Line lengths were also changed (by <TT>\w'0000'u</TT>) to keep the right side aligned.
  2241. Another example is
  2242. which turns on numbering with the line number of the next
  2243. line to be 5 greater than the last numbered line,
  2244. with <I>M=</I>5, with spacing <I>S</I> untouched, and with the indent <I>I</I> set to 3.
  2245. <br>
  2246. </P>
  2247. <H4>16 Conditional Acceptance of Input
  2248. </H4>
  2249. <P>
  2250. In the following,
  2251. <I>c</I> is a one-character built-in <I>condition</I> name,
  2252. <TT>!</TT> signifies <I>not</I>,
  2253. <I>N</I> is a numerical expression,
  2254. <I>string1</I> and <I>string2</I> are strings delimited by any non-blank, non-numeric character not in the strings,
  2255. and
  2256. <I>anything</I> represents what is conditionally accepted.
  2257. </P>
  2258. <br>&#32;<br>
  2259. <TT>&if</TT><I> c anything</I> - -
  2260. <DL COMPACT>
  2261. <DT><DD>
  2262. If condition
  2263. <I>c</I> true, accept <I>anything</I> as input;
  2264. in multi-line case use \{<I>anything</I>\}.
  2265. </dl>
  2266. <br>&#32;<br>
  2267. <TT>&if !</TT><I>c anything</I> - -
  2268. <DL COMPACT>
  2269. <DT><DD>
  2270. If condition <I>c</I> false, accept <I>anything</I>.
  2271. </dl>
  2272. <br>&#32;<br>
  2273. <TT>&if</TT><I> N anything</I> - <B>u</B>
  2274. <DL COMPACT>
  2275. <DT><DD>
  2276. If expression <I>N</I> > 0, accept <I>anything</I>.
  2277. </dl>
  2278. <br>&#32;<br>
  2279. <TT>&if !</TT><I>N anything</I> - <B>u</B>
  2280. <DL COMPACT>
  2281. <DT><DD>
  2282. If expression <I>N</I> <= 0 [sic], accept <I>anything</I>.
  2283. </dl>
  2284. <br>&#32;<br>
  2285. <TT>&if '</TT><I>string1</I><TT>'</TT><I>string2</I><TT>'</TT><I> anything</I> -
  2286. <DL COMPACT>
  2287. <DT><DD>
  2288. If <I>string1</I> identical to <I>string2</I>,
  2289. accept <I>anything</I>.
  2290. </dl>
  2291. <br>&#32;<br>
  2292. <TT>&if !'</TT><I>string1</I><TT>'</TT><I>string2</I><TT>'</TT><I> anything</I> -
  2293. <DL COMPACT>
  2294. <DT><DD>
  2295. If <I>string1</I> not identical to <I>string2</I>,
  2296. accept <I>anything</I>.
  2297. </dl>
  2298. <br>&#32;<br>
  2299. <TT>&ie</TT><I> c anything</I> - <B>u</B>
  2300. <DL COMPACT>
  2301. <DT><DD>
  2302. If portion of if-else;
  2303. all of the forms for <TT>if</TT> above are valid.
  2304. </dl>
  2305. <br>&#32;<br>
  2306. <TT>&el</TT><I> anything</I> - -
  2307. <DL COMPACT>
  2308. <DT><DD>
  2309. Else portion of if-else.
  2310. </dl>
  2311. <P>
  2312. The built-in condition names are:
  2313. <br><img src="-.162513.gif"><br>
  2314. If the condition <I>c</I> is true, or if the number <I>N</I> is greater than zero,
  2315. or if the strings compare identically (including motions and character size and font),
  2316. <I>anything</I> is accepted as input.
  2317. If a <TT>!</TT> precedes the condition, number, or string comparison,
  2318. the sense of the acceptance is reversed.
  2319. </P>
  2320. <P>
  2321. Any spaces between the condition and the beginning of <I>anything</I> are skipped over.
  2322. The <I>anything</I> can be either a single input line (text, macro, or whatever)
  2323. or a number of input lines.
  2324. In the multi-line case,
  2325. the first line must begin with a left delimiter <TT>\{</TT> and
  2326. the last line must end with a right delimiter <TT>\}</TT>.
  2327. </P>
  2328. <P>
  2329. The request <TT>ie</TT> (if-else) is identical to <TT>if</TT>
  2330. except that the acceptance state is remembered.
  2331. A subsequent and matching <TT>el</TT> (else) request then uses the reverse sense of that state.
  2332. <TT>ie</TT>-<TT>el</TT> pairs may be nested.
  2333. </P>
  2334. <P>
  2335. Some examples are:
  2336. <DL><DT><DD><TT><PRE>
  2337. &amp;if e .tl 'Even Page %'''
  2338. </PRE></TT></DL>
  2339. which outputs a title if the page number is even; and
  2340. <DL><DT><DD><TT><PRE>
  2341. &amp;ie \n%&#62;1 \{\
  2342. ' sp 0.5i
  2343. &amp; tl 'Page %'''
  2344. ' sp |1.2i \}
  2345. &amp;el .sp |2.5i
  2346. </PRE></TT></DL>
  2347. which treats page 1 differently from other pages.
  2348. </P>
  2349. <H4>17 Environment Switching.
  2350. </H4>
  2351. <P>
  2352. A number of the parameters that
  2353. control the text processing are gathered together into an
  2354. <I>environment</I>, which can be switched by the user.
  2355. The environment parameters are those associated
  2356. with requests noting E in their <I>Notes</I> column;
  2357. in addition, partially collected lines and words are in the environment.
  2358. Everything else is global; examples are page-oriented parameters,
  2359. diversion-oriented parameters, number registers, and macro and string definitions.
  2360. All environments are initialized with default parameter values.
  2361. </P>
  2362. <br>&#32;<br>
  2363. <TT>&ev</TT><I> N</I> <I>N=</I>0 previous -
  2364. <DL COMPACT>
  2365. <DT><DD>
  2366. Environment switched to
  2367. environment 0<=<I>N</I><=2.
  2368. Switching is done in push-down fashion so that
  2369. restoring a previous environment <I>must</I> be done with <TT>.ev</TT>
  2370. rather than specific reference.
  2371. Note that what is pushed down and restored is the environment
  2372. <I>number,</I>
  2373. not its contents.
  2374. </dl>
  2375. <H4>18 Insertions from the Standard Input
  2376. </H4>
  2377. <P>
  2378. The input can be temporarily switched to the system standard input
  2379. with <TT>rd</TT>,
  2380. which will switch back when two consecutive newlines
  2381. are found (the extra blank line is not used).
  2382. This mechanism is intended for insertions in form-letter-like documentation.
  2383. The standard input can be the user's keyboard,
  2384. a pipe, or a file.
  2385. </P>
  2386. <br>&#32;<br>
  2387. <TT>&rd</TT><I> prompt</I> - <I>prompt=</I>BEL" -"
  2388. <DL COMPACT>
  2389. <DT><DD>
  2390. Read insertion
  2391. from the standard input until two newlines in a row are found.
  2392. If the standard input is the user's keyboard, <I>prompt</I> (or a BEL)
  2393. is written onto the standard output.
  2394. <TT>rd</TT> behaves like a macro,
  2395. and arguments may be placed after <I>prompt</I>.
  2396. </dl>
  2397. <br>&#32;<br>
  2398. <TT>&ex</TT> - - -
  2399. <DL COMPACT>
  2400. <DT><DD>
  2401. Exit from <I>nroff</I>/<I>troff</I>.
  2402. Text processing is terminated exactly as if all input had ended.
  2403. </dl>
  2404. <P>
  2405. If insertions are to be
  2406. taken from the terminal keyboard while output is being printed
  2407. on the terminal, the command line option <TT>-q</TT> will turn off the echoing
  2408. of keyboard input and prompt only with BEL.
  2409. The regular input and insertion input cannot
  2410. simultaneously come from the standard input.
  2411. </P>
  2412. <P>
  2413. As an example,
  2414. multiple copies of a form letter may be prepared by entering the insertions
  2415. for all the copies in one file to be used as the standard input,
  2416. and causing the file containing the letter to reinvoke itself with <TT>nx</TT> (&#167;19);
  2417. the process would ultimately be ended by an <TT>ex</TT> in the insertion file.
  2418. </P>
  2419. <H4>19 Input/Output File Switching
  2420. </H4>
  2421. <br>&#32;<br>
  2422. <TT>&so</TT><I> filename</I> - -
  2423. <DL COMPACT>
  2424. <DT><DD>
  2425. Switch source file.
  2426. The top input (file reading) level is switched to <I>filename</I>.
  2427. When the new file ends,
  2428. input is again taken from the original file.
  2429. <TT>so</TT>'s may be nested.
  2430. </dl>
  2431. <br>&#32;<br>
  2432. <TT>&nx</TT><I> filename</I> end-of-file -
  2433. <DL COMPACT>
  2434. <DT><DD>
  2435. Next file is <I>filename</I>.
  2436. The current file is considered ended, and the input is immediately switched
  2437. to <I>filename</I>.
  2438. </dl>
  2439. <br>&#32;<br>
  2440. <TT>&sy</TT><I> string</I> - -
  2441. <DL COMPACT>
  2442. <DT><DD>
  2443. Execute program from <I>string</I>,
  2444. which is the rest of the input line.
  2445. The output is not collected automatically.
  2446. The number register
  2447. which contains the process id of the <I>troff</I> process,
  2448. may be useful in generating unique filenames for output.
  2449. </dl>
  2450. <br>&#32;<br>
  2451. <TT>&pi</TT><I> string</I> - -
  2452. <DL COMPACT>
  2453. <DT><DD>
  2454. Pipe output to <I>string</I>,
  2455. which is the rest of the input line.
  2456. This request must occur before any printing occurs;
  2457. typically it is the first line of input.
  2458. </dl>
  2459. <br>&#32;<br>
  2460. <TT>&cf</TT><I> filename</I> - -
  2461. <DL COMPACT>
  2462. <DT><DD>
  2463. Copy
  2464. contents of file
  2465. <I>filename</I>
  2466. to output, completely unprocessed.
  2467. The file is assumed to contain something meaningful
  2468. to subsequent processes.
  2469. </dl>
  2470. <H4>20 Miscellaneous
  2471. <br>
  2472. that a <I>margin</I> character <I>c</I> appear a distance
  2473. <I>N</I> to the right of the right margin
  2474. after each non-empty text line (except those produced by <TT>tl</TT>).
  2475. If the output line is too long (as can happen in nofill mode)
  2476. the character will be appended to the line.
  2477. If <I>N</I> is not given, the previous <I>N</I> is used; the initial <I>N</I> is
  2478. 0.2 inches in <I>nroff</I> and 1 em in <I>troff</I>.
  2479. The margin character used with this paragraph was a 12-point box-rule.
  2480. <br>
  2481. </H4>
  2482. <br>&#32;<br>
  2483. <TT>.tm</TT><I> string</I> - newline -
  2484. <DL COMPACT>
  2485. <DT><DD>
  2486. After skipping initial blanks,
  2487. <I>string</I> (rest of the line) is read in copy mode
  2488. and written on the standard error.
  2489. </dl>
  2490. <br>&#32;<br>
  2491. <TT>&ab</TT><I> string</I> - newline -
  2492. <DL COMPACT>
  2493. <DT><DD>
  2494. After skipping initial blanks,
  2495. <I>string</I> (rest of the line) is read in copy mode
  2496. and written on the standard error.
  2497. <I>Troff</I> or <I>nroff</I> then exit.
  2498. </dl>
  2499. <br>&#32;<br>
  2500. <TT>.ig</TT><I> yy</I> - <I>.yy=</I><TT>..</TT> -
  2501. <DL COMPACT>
  2502. <DT><DD>
  2503. Ignore
  2504. input lines.
  2505. <TT>ig</TT> behaves exactly like <TT>de</TT> (&#167;7) except that the
  2506. input is discarded.
  2507. The input is read in copy mode, and any auto-incremented
  2508. registers will be affected.
  2509. </dl>
  2510. <br>&#32;<br>
  2511. <TT>.lf</TT><I> N filename</I> - -
  2512. <DL COMPACT>
  2513. <DT><DD>
  2514. Set
  2515. line number to <I>N</I> and filename to <I>filename</I>
  2516. for purposes of subsequent error messages, etc.
  2517. The number register [sic]
  2518. contains the name of the current input file,
  2519. as set by command line argument,
  2520. or
  2521. The number register
  2522. contains the number of input lines read from the current file,
  2523. again perhaps as modified by
  2524. </dl>
  2525. <br>&#32;<br>
  2526. <TT>.pm</TT><I> t</I> - all -
  2527. <DL COMPACT>
  2528. <DT><DD>
  2529. Print macros.
  2530. The names and sizes of all of the defined macros and strings are printed
  2531. on the standard error;
  2532. if <I>t</I> is given, only the total of the sizes is printed.
  2533. The sizes is given in blocks
  2534. of 128 characters.
  2535. </dl>
  2536. <br>&#32;<br>
  2537. <TT>.fl</TT> - - B
  2538. <DL COMPACT>
  2539. <DT><DD>
  2540. Flush output buffer.
  2541. Force output, including any pending position information.
  2542. </dl>
  2543. <H4>21 Output and Error Messages.
  2544. </H4>
  2545. <P>
  2546. The output from <TT>tm</TT>, <TT>pm</TT>, and the prompt from <TT>rd</TT>,
  2547. as well as various error messages, are written onto
  2548. the standard error.
  2549. The latter is different from the standard output,
  2550. where formatted text goes.
  2551. By default, both are written onto the user's terminal,
  2552. but they can be independently redirected.
  2553. </P>
  2554. <P>
  2555. Various error conditions may occur during
  2556. the operation of <I>nroff</I> and <I>troff</I>.
  2557. Certain less serious errors having only local impact do not
  2558. cause processing to terminate.
  2559. Two examples are <I>word overflow</I>, caused by a word that is too large
  2560. to fit into the word buffer (in fill mode), and
  2561. <I>line overflow</I>, caused by an output line that grew too large
  2562. to fit in the line buffer.
  2563. In both cases, a message is printed, the offending excess
  2564. is discarded,
  2565. and the affected word or line is marked at the point of truncation
  2566. with a * in <I>nroff</I> and a <= in <I>troff</I>.
  2567. Processing continues if possible,
  2568. on the grounds that output useful for debugging may be produced.
  2569. If a serious error occurs, processing terminates,
  2570. and a message is printed, along with a list of the macro names currently active.
  2571. Examples of serious errors include the inability to create, read, or write files,
  2572. and the exceeding of certain internal limits that
  2573. make future output unlikely to be useful.
  2574. </P>
  2575. <H4>22 Output Language
  2576. </H4>
  2577. <P>
  2578. <I>Troff</I>
  2579. produces its output in a language that is independent of any
  2580. specific output device,
  2581. except that the numbers in it have been computed on the basis
  2582. of the resolution of the device,
  2583. and the sizes, fonts, and characters that that device can print.
  2584. Nevertheless it is quite possible to interpret that output
  2585. on a different device, within the latter's capabilities.
  2586. </P>
  2587. <DL>
  2588. <DT><DT>&#32;<DD>
  2589. <DL><DT><DD><TT><PRE>
  2590. <I></I><TT>s</TT><I>n</I> set point size to <I>n</I>
  2591. <I></I><TT>f</TT><I>n</I> set font to <I>n</I>
  2592. <I></I><TT>c</TT><I>c</I> print character <I>c</I>
  2593. <I></I><TT>C</TT><I>name</I> print the character called <I>name</I>; terminate <I>name</I> by white space
  2594. <I></I><TT>N</TT><I>n</I> print character <I>n</I> on current font
  2595. <I></I><TT>H</TT><I>n</I> go to absolute horizontal position <I>n</I> (<I>n</I>>=0)
  2596. <I></I><TT>V</TT><I>n</I> go to absolute vertical position <I>n</I> (<I>n</I>>=0, down is positive)
  2597. <I></I><TT>h</TT><I>n</I> go <I>n</I> units horizontally; <I>n</I><I><</I>0 is to the left
  2598. <I></I><TT>v</TT><I>n</I> go <I>n</I> units vertically; <I>n</I><I><</I>0 is up
  2599. <I>nnc</I> move right <I>nn</I>, then print UTF character <I>c</I>; <I>nn</I> must be exactly 2 digits
  2600. <I></I><TT>p</TT><I>n</I> new page <I>n</I> begins&#173;set vertical position to 0
  2601. <I></I><TT>n</TT><I>b</I> <I>a</I> end of line (information only&#173;no action); <I>b</I> = space before line, <I>a</I> = after
  2602. <I></I><TT>w</TT> paddable word space (information only&#173;no action)
  2603. <I></I><TT>D</TT><I>c</I> ...0graphics function <I>c</I>; see below
  2604. <I></I><TT>x</TT> ...0device control functions; see below
  2605. <I></I><TT>#</TT> ...0comment
  2606. </PRE></TT></DL>
  2607. </dl>
  2608. <br>&#32;<br>
  2609. All position values are in units.
  2610. Sequences that end in digits must be followed by a non-digit.
  2611. Blanks, tabs and newlines may occur as separators
  2612. in the input, and are mandatory to separate constructions
  2613. that would otherwise be confused.
  2614. Graphics functions, device control functions, and comments extend to the
  2615. end of the line they occur on.
  2616. <P>
  2617. The device control and graphics commands are intended as open-ended
  2618. families, to be expanded as needed.
  2619. The graphics functions coincide directly with the
  2620. sequences:
  2621. </P>
  2622. <DL>
  2623. <DT><DT>&#32;<DD>
  2624. <DL><DT><DD><TT><PRE>
  2625. <I></I><TT>Dl</TT> <I>dh dv</I> draw line from current position by <I>dh</I>, <I>dv</I>
  2626. <I></I><TT>Dc</TT> <I>d</I> draw circle of diameter <I>d</I> with left side here
  2627. <I></I><TT>De</TT> <I>dh</I>1 <I>dv</I>2 draw ellipse of diameters <I>dh</I>1 and <I>dv</I>2
  2628. <I></I><TT>Da</TT> <I>dh</I>1 <I>dv</I>1 <I>dh</I>2 <I>dv</I>2 draw arc from current position to <I>dh</I>1<I>+dh</I>2, <I>dv</I>1<I>+dv</I>2,
  2629. center at <I>dh</I>1, <I>dv</I>1 from current position
  2630. <I></I><TT>D~</TT> <I>dh</I>1 <I>dv</I>1 <I>dh</I>2 <I>dv</I>2 ... draw B-spline from current position to <I>dh</I>1, <I>dv</I>1,
  2631. then to <I>dh</I>2, <I>dv</I>2, then to ...
  2632. <I></I><TT>D</TT><I>z</I> <I>dh</I>1 <I>dv</I>1 <I>dh</I>2 <I>dv</I>2 ... for any other <I>z</I> is uninterpreted
  2633. </PRE></TT></DL>
  2634. </dl>
  2635. <br>&#32;<br>
  2636. In all of these, <I>dh</I>, <I>dv</I> is an increment on the current horizontal and
  2637. vertical position,
  2638. with down and right positive.
  2639. All distances and dimensions are in units.
  2640. <P>
  2641. The device control functions begin with
  2642. then a command, then other parameters.
  2643. </P>
  2644. <DL>
  2645. <DT><DT>&#32;<DD>
  2646. <DL><DT><DD><TT><PRE>
  2647. x T <I>s</I> name of typesetter is <I>s</I><TT>
  2648. x r </TT><I>n h v</I><TT> </TT>resolution is <I>n</I> units/inch;<TT>
  2649. </TT><I>h</I> = minimum horizontal motion, <I>v</I> = minimum vertical<TT>
  2650. x i </TT>initialize<TT>
  2651. x f </TT><I>n s</I><TT> </TT>mount font <I>s</I> on font position <I>n</I><TT>
  2652. x p </TT>pause&#173;can restart<TT>
  2653. x s </TT>stop&#173;done forever<TT>
  2654. x t </TT>generate trailer information, if any<TT>
  2655. x H </TT><I>n</I><TT> </TT>set character height to <I>n</I><TT>
  2656. x S </TT><I>n</I><TT> </TT>set slant to <I>n</I><TT>
  2657. x X </TT><I>any</I><TT> </TT>generated by the <TT>\X</TT> function<TT>
  2658. x </TT><I>any</I><TT> </TT>to be ignored if not recognized<TT>
  2659. </PRE></TT></DL>
  2660. </dl>
  2661. </TT><br>&#32;<br>
  2662. Subcommands like
  2663. may be spelled out like
  2664. <P>
  2665. The commands
  2666. and
  2667. must occur first;
  2668. fonts must be mounted before they can be used;
  2669. comes last.
  2670. There are no other order requirements.
  2671. </P>
  2672. <P>
  2673. The following is the output from
  2674. for a typical printer,
  2675. as described in &#167;23:
  2676. <DL><DT><DD><TT><PRE>
  2677. x T utf
  2678. x res 720 1 1
  2679. x init
  2680. V0
  2681. p1
  2682. </PRE></TT></DL>
  2683. <DL><DT><DD><TT><PRE>
  2684. x font 1 R
  2685. x font 2 I
  2686. x font 3 B
  2687. x font 4 BI
  2688. x font 5 CW
  2689. x font 6 H
  2690. x font 7 HB
  2691. x font 8 HX
  2692. x font 9 S1
  2693. x font 10 S
  2694. </PRE></TT></DL>
  2695. <DL><DT><DD><TT><PRE>
  2696. s10
  2697. f1
  2698. H0
  2699. s10
  2700. f1
  2701. V0
  2702. H720
  2703. V120
  2704. ch
  2705. 50e44l28l28o50,w58w72o50r33l28dn120 0
  2706. x trailer
  2707. V7920
  2708. x stop
  2709. </PRE></TT></DL>
  2710. </P>
  2711. <P>
  2712. <I>Troff</I> output is normally not redundant;
  2713. size and font changes and position information are not included
  2714. unless needed.
  2715. Nevertheless, each page is self-contained, for the benefit of postprocessors
  2716. that re-order pages or process only a subset.
  2717. </P>
  2718. <H4>23 Device and Font Description Files
  2719. </H4>
  2720. <P>
  2721. The parameters that describe a output device
  2722. <I>name</I>
  2723. are read
  2724. from the directory
  2725. each time
  2726. <I>troff</I>
  2727. is invoked.
  2728. The device name is provided by default,
  2729. by the environment variable
  2730. or by a command-line argument
  2731. The default device name is
  2732. for UTFencoded Unicode characters.
  2733. The pre-defined string
  2734. contains the name of the device.
  2735. The
  2736. command-line option may be used to change the default directory.
  2737. </P>
  2738. <br>&#32;<br>
  2739. <B><I>0.0s. Device description file.</I></B>
  2740. General parameters of the device are stored, one per line, in
  2741. the file
  2742. as a sequence of names and values.
  2743. <I>Troff</I> recognizes these parameters, and ignores any
  2744. others that may be present for specific drivers:
  2745. <DL>
  2746. <DT><DT>&#32;<DD>
  2747. <DL><DT><DD><TT><PRE>
  2748. <I></I><TT>fonts</TT> <I>n</I> <I>F</I>1 <I>F</I>2 <I>.</I><I>.</I><I>.</I> <I>F</I><I>n</I>
  2749. <I></I><TT>sizes</TT> <I>s</I>1 <I>s</I>2 <I>.</I><I>.</I><I>.</I><I></I><TT>0</TT>
  2750. <I></I><TT>res</TT> <I>n</I>
  2751. <I></I><TT>hor</TT> <I>n</I>
  2752. <I></I><TT>vert</TT> <I>n</I>
  2753. <I></I><TT>unitwidth</TT> <I>n</I>
  2754. <I></I><TT>charset</TT>
  2755. <I>list of multi-character character names (optional)</I>
  2756. </PRE></TT></DL>
  2757. </dl>
  2758. <br>&#32;<br>
  2759. The <I>F</I><I>i</I> are font names
  2760. to be initially mounted.
  2761. The list of sizes is a set of integers representing
  2762. some or all of the legal sizes the device can produce,
  2763. terminated by a zero.
  2764. The
  2765. parameter gives the resolution of the machine in units per inch;
  2766. and
  2767. give the minimum number of units that can be moved
  2768. horizontally and vertically.
  2769. <P>
  2770. Character widths for each font are assumed to be given in machine units
  2771. at point size
  2772. (In other words, a character with a width of
  2773. <I>n</I> is <I>n</I> units wide at size
  2774. All widths are integers at all sizes.
  2775. </P>
  2776. <P>
  2777. A list of valid character names may be introduced by
  2778. the list of names is optional.
  2779. </P>
  2780. <P>
  2781. A line whose first non-blank character is
  2782. is a comment.
  2783. Except that
  2784. must occur last, parameters may appear in any order.
  2785. </P>
  2786. <P>
  2787. Here is a subset of the
  2788. file for a typical Postscript printer:
  2789. <DL><DT><DD><TT><PRE>
  2790. # Description file for Postscript printers.
  2791. fonts 10 R I B BI CW H HB HX S1 S
  2792. sizes 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
  2793. 24 25 26 27 28 29 30 31 32 33 34 35 36 38 40 44 48 54 60 72 0
  2794. res 720
  2795. hor 1
  2796. vert 1
  2797. unitwidth 10
  2798. charset
  2799. hy ct fi fl ff Fi Fl dg em 14 34 12 en aa
  2800. ga ru sc dd -&#62; br Sl ps cs cy as os =. ld
  2801. rd le ge pp -+ ob vr
  2802. sq bx ci fa te ** pl mi eq ~= *A *B *X *D
  2803. *E *F *G *Y *I *K *L *M *N *O *P *R *H *S *T *U *W
  2804. *C *Q *Z ul rn *a *b *x *d *e *f *g *y *i *k
  2805. *l *m *n *o *p *h *r *s *t *u *w *c *q *z
  2806. </PRE></TT></DL>
  2807. </P>
  2808. <br>&#32;<br>
  2809. <B><I>0.0s. Font description files.</I></B>
  2810. Each font is described by an analogous description file,
  2811. which begins with parameters of the font, one per line, followed by a
  2812. list of characters and widths.
  2813. The file for font
  2814. <I>f</I>
  2815. is
  2816. <DL>
  2817. <DT><DT>&#32;<DD>
  2818. <DL><DT><DD><TT><PRE>
  2819. <I></I><TT>name</TT> <I>str</I> name of font is <I>str</I>
  2820. <I></I><TT>ligatures</TT> <I>. . .</I> <I></I><TT>0</TT> list of ligatures
  2821. <I></I><TT>spacewidth</TT> <I>n</I> width of a space on this font
  2822. <I></I><TT>special</TT> this is a special font
  2823. <I></I><TT>charset</TT>
  2824. <I>list of character name, width, ascender/descender, code</I>, tab separated
  2825. </PRE></TT></DL>
  2826. </dl>
  2827. <br>&#32;<br>
  2828. The
  2829. and
  2830. fields are mandatory;
  2831. must be last.
  2832. Comments are permitted,
  2833. as are other unrecognized parameters.
  2834. <P>
  2835. Each line following
  2836. describes one character: its name, its width in units as described above,
  2837. ascender/descender information, and a decimal, octal or hexadecimal value
  2838. by which the output device knows it
  2839. (the
  2840. ``number'' of the character).
  2841. The character name is arbitrary, except that
  2842. signifies an unnamed character.
  2843. If the width field contains
  2844. the name is a synonym for the previous character.
  2845. The ascender/descender field is 1 if
  2846. the character has a descender (hangs below the baseline, like
  2847. is 2 if it has an ascender (is tall, like
  2848. is 3 if both,
  2849. and is 0 if neither.
  2850. The value is returned
  2851. in the
  2852. register, as computed by the
  2853. function (&#167;11.2).
  2854. </P>
  2855. <P>
  2856. Here are excerpts from a typical font description file
  2857. for the same Postscript printer.
  2858. <DL><DT><DD><TT><PRE>
  2859. hy 33 0 45 hyphen \(hy
  2860. - " - is a synonym for \(hy
  2861. <br>&#32;<br>
  2862. Q 72 3 81
  2863. <br>&#32;<br>
  2864. a 44 0 97
  2865. b 50 2 98
  2866. c 44 0 99
  2867. d 50 2 100
  2868. y 50 1 121
  2869. <br>&#32;<br>
  2870. em 100 0 208
  2871. --- 44 2 220 Pound symbol &#163;, \N'220'
  2872. --- 36 0 221 centered dot \N'221'
  2873. </PRE></TT></DL>
  2874. This says, for example, that the width of the letter
  2875. is 44 units at point size 10,
  2876. the value of
  2877. Point sizes are scaled linearly and rounded, so the width of
  2878. will be 44 at size 10, 40 at size 9, 35 at size 8,
  2879. and so on.
  2880. <br>&#32;<br>
  2881. <HR>
  2882. <br>&#32;<br>
  2883. </P>
  2884. <br>&#32;<br>
  2885. <B>Tutorial Examples
  2886. <br>&#32;<br>
  2887. <br>&#32;<br>
  2888. <br>&#32;<br>
  2889. <br>&#32;<br>
  2890. </B><H4>Introduction
  2891. </H4>
  2892. <P>
  2893. It is almost always necessary to
  2894. prepare at least a small set of macro definitions
  2895. to describe a document.
  2896. Such common formatting needs
  2897. as page margins and footnotes
  2898. are deliberately not built into <I>nroff</I> and <I>troff</I>.
  2899. Instead,
  2900. the macro and string definition, number register, diversion,
  2901. environment switching, page-position trap, and conditional input mechanisms
  2902. provide the basis for user-defined implementations.
  2903. </P>
  2904. <P>
  2905. For most uses, a standard package like
  2906. or
  2907. is the right choice.
  2908. The next stage is to augment that,
  2909. or to selectively replace macros from the standard package.
  2910. The last stage, much harder,
  2911. is to write one's own from scratch.
  2912. This is not a task for the novice.
  2913. </P>
  2914. <P>
  2915. The examples discussed here are intended to be useful and somewhat realistic,
  2916. but will not necessarily cover all relevant contingencies.
  2917. Explicit numerical parameters are used
  2918. in the examples
  2919. to make them easier to read and to
  2920. illustrate typical values.
  2921. In many cases, number registers would be used
  2922. to reduce the number of places where numerical
  2923. information is kept,
  2924. and to concentrate conditional parameter initialization
  2925. like that which depends on whether <I>troff</I> or <I>nroff</I> is being used.
  2926. </P>
  2927. <H4>Page Margins
  2928. </H4>
  2929. <P>
  2930. As discussed in &#167;3,
  2931. header and footer macros are usually defined
  2932. to describe the top and bottom page margin areas respectively.
  2933. A trap is planted at page position 0 for the header, and at
  2934. <I>-N</I> (<I>N</I> from the page bottom) for the footer.
  2935. The simplest such definitions might be
  2936. <DL><DT><DD><TT><PRE>
  2937. &amp;de hd \"define header
  2938. 'sp 1i
  2939. &amp;&amp; \"end definition
  2940. &amp;de fo \"define footer
  2941. 'bp
  2942. &amp;&amp; \"end definition
  2943. &amp;wh 0 hd
  2944. &amp;wh -1i fo
  2945. </PRE></TT></DL>
  2946. which provide blank 1 inch top and bottom margins.
  2947. The header will occur on the <I>first</I> page
  2948. only if the definition and trap exist prior to
  2949. the initial pseudo-page transition (&#167;3).
  2950. In fill mode, the output line that springs the footer trap
  2951. was typically forced out because some part or whole word didn't fit on it.
  2952. If anything in the footer and header that follows causes a break,
  2953. that word or part word will be forced out.
  2954. In this and other examples,
  2955. requests like <TT>bp</TT> and <TT>sp</TT> that normally cause breaks are invoked using
  2956. the no-break control character <TT>'</TT>
  2957. to avoid this.
  2958. When the header/footer design contains material
  2959. requiring independent text processing, the
  2960. environment may be switched, avoiding
  2961. most interaction with the running text.
  2962. </P>
  2963. <P>
  2964. A more realistic example would be
  2965. <DL><DT><DD><TT><PRE>
  2966. &amp;de hd \"header
  2967. &amp;if \\n%&#62;1 \{\
  2968. 'sp ~0.5i-1 \"tl base at 0.5i
  2969. &amp;tl ''- % -'' \"centered page number
  2970. &amp;ps \"restore size
  2971. &amp;ft \"restore font
  2972. &amp;vs \} \"restore vs
  2973. 'sp ~1.0i \"space to 1.0i
  2974. &amp;ns \"turn on no-space mode
  2975. &amp;&amp;
  2976. &amp;de fo \"footer
  2977. &amp;ps 10 \"set footer/header size
  2978. &amp;ft R \"set font
  2979. &amp;vs 12p \"set baseline spacing
  2980. &amp;if \\n%=1 \{\
  2981. 'sp ~\\n(.pu-0.5i-1 \"tl base 0.5i up
  2982. &amp;tl ''- % -'' \} \"first page number
  2983. 'bp
  2984. &amp;&amp;
  2985. &amp;wh 0 hd
  2986. &amp;wh -1i fo
  2987. </PRE></TT></DL>
  2988. which sets the size, font, and baseline spacing for the
  2989. header/footer material, and ultimately restores them.
  2990. The material in this case is a page number at the bottom of the
  2991. first page and at the top of the remaining pages.
  2992. The <TT>sp</TT>'s refer to absolute positions to avoid
  2993. dependence on the baseline spacing.
  2994. Another reason for doing this in the footer
  2995. is that the footer is invoked by printing a line whose
  2996. vertical spacing swept past the trap position by possibly
  2997. as much as the baseline spacing.
  2998. No-space mode is turned on at the end of <TT>hd</TT>
  2999. to render ineffective
  3000. accidental occurrences of <TT>sp</TT> at the top of the running text.
  3001. </P>
  3002. <P>
  3003. This method of restoring size, font, etc., presupposes
  3004. that such requests (that set <I>previous</I> value) are <I>not</I>
  3005. used in the running text.
  3006. A better scheme is to save and restore both the current <I>and</I>
  3007. previous values as shown for size in the following:
  3008. <DL><DT><DD><TT><PRE>
  3009. &amp;de fo
  3010. &amp;nr s1 \\n(.s \"current size
  3011. &amp;ps
  3012. &amp;nr s2 \\n(.s \"previous size
  3013. &amp; --- \"rest of footer
  3014. &amp;&amp;
  3015. &amp;de hd
  3016. &amp; --- \"header stuff
  3017. &amp;ps \\n(s2 \"restore previous size
  3018. &amp;ps \\n(s1 \"restore current size
  3019. &amp;&amp;
  3020. </PRE></TT></DL>
  3021. Page numbers may be printed in the bottom margin
  3022. by a separate macro triggered during the footer's
  3023. page ejection:
  3024. <DL><DT><DD><TT><PRE>
  3025. &amp;de bn \"bottom number
  3026. &amp;tl ''- % -'' \"centered page number
  3027. &amp;&amp;
  3028. &amp;wh -0.5i-1v bn \"tl base 0.5i up
  3029. </PRE></TT></DL>
  3030. </P>
  3031. <H4>Paragraphs and Headings
  3032. </H4>
  3033. <P>
  3034. The housekeeping
  3035. associated with starting a new paragraph should be collected
  3036. in a paragraph macro
  3037. that, for example,
  3038. does the desired preparagraph spacing,
  3039. forces the correct font, size, baseline spacing, and indent,
  3040. checks that enough space remains for <I>more than one</I> line,
  3041. and
  3042. requests a temporary indent.
  3043. <DL><DT><DD><TT><PRE>
  3044. &amp;de pg \"paragraph
  3045. &amp;br \"break
  3046. &amp;ft R \"force font,
  3047. &amp;ps 10 \"size,
  3048. &amp;vs 12p \"spacing,
  3049. &amp;in 0 \"and indent
  3050. &amp;sp 0.4 \"prespace
  3051. &amp;ne 1+\\n(.Vu \"want more than 1 line
  3052. &amp;ti 0.2i \"temp indent
  3053. &amp;&amp;
  3054. </PRE></TT></DL>
  3055. The first break in <TT>pg</TT>
  3056. will force out any previous partial lines,
  3057. and must occur before the <TT>vs</TT>.
  3058. The forcing of font, etc., is
  3059. partly a defense against prior error and
  3060. partly to permit
  3061. things like section heading macros to
  3062. set parameters only once.
  3063. The prespacing parameter is suitable for <I>troff</I>;
  3064. a larger space, at least as big as the output device vertical resolution, would be
  3065. more suitable in <I>nroff</I>.
  3066. The choice of remaining space to test for in the <TT>ne</TT>
  3067. is the smallest amount greater than one line
  3068. (the <TT>.V</TT> is the available vertical resolution).
  3069. </P>
  3070. <P>
  3071. A macro to automatically number section headings
  3072. might look like:
  3073. <DL><DT><DD><TT><PRE>
  3074. &amp;de sc \"section
  3075. &amp; --- \"force font, etc.
  3076. &amp;sp 0.4 \"prespace
  3077. &amp;ne 2.4+\\n(.Vu \"want 2.4+ lines
  3078. &amp;fi
  3079. \\n+S.
  3080. &amp;&amp;
  3081. &amp;nr S 0 1 \"init S
  3082. </PRE></TT></DL>
  3083. The usage is <TT>.sc</TT>,
  3084. followed by the section heading text,
  3085. followed by <TT>.pg</TT>.
  3086. The <TT>ne</TT> test value includes one line of heading,
  3087. 0.4 line in the following <TT>pg</TT>, and
  3088. one line of the paragraph text.
  3089. A word consisting of the next section number and a period is
  3090. produced to begin the heading line.
  3091. The format of the number may be set by <TT>af</TT> (&#167;8).
  3092. </P>
  3093. <P>
  3094. Another common form is the labeled, indented paragraph,
  3095. where the label protrudes left into the indent space.
  3096. <DL><DT><DD><TT><PRE>
  3097. &amp;de lp \"labeled paragraph
  3098. &amp;pg
  3099. &amp;in 0.5i \"paragraph indent
  3100. &amp;ta 0.2i 0.5i \"label, paragraph
  3101. &amp;ti 0
  3102. \t\\$1\t\c \"flow into paragraph
  3103. &amp;&amp;
  3104. </PRE></TT></DL>
  3105. The intended usage is ``<TT>.lp</TT> <I>label</I>'';
  3106. <I>label</I> will begin at 0.2 inch, and
  3107. cannot exceed a length of 0.3 inch without intruding into
  3108. the paragraph.
  3109. The label could be right adjusted against 0.4 inch by
  3110. setting the tabs instead with <TT>.ta|0.4iR|0.5i</TT>.
  3111. The last line of <TT>lp</TT> ends with <TT>\c</TT> so that
  3112. it will become a part of the first line of the text
  3113. that follows.
  3114. </P>
  3115. <H4>Multiple Column Output
  3116. </H4>
  3117. <P>
  3118. The production of multiple column pages requires
  3119. the footer macro to decide whether it was
  3120. invoked by other than the last column,
  3121. so that it will begin a new column rather than
  3122. produce the bottom margin.
  3123. The header can initialize a column register that
  3124. the footer will increment and test.
  3125. The following is arranged for two columns, but
  3126. is easily modified for more.
  3127. <DL><DT><DD><TT><PRE>
  3128. &amp;de hd \"header
  3129. &amp; ---
  3130. &amp;nr cl 0 1 \"init column count
  3131. &amp;mk \"mark top of text
  3132. &amp;&amp;
  3133. </PRE></TT></DL>
  3134. <DL><DT><DD><TT><PRE>
  3135. &amp;de fo \"footer
  3136. &amp;ie \\n+(cl&#60;2 \{\
  3137. &amp;po +3.4i \"next column; 3.1+0.3
  3138. &amp;rt \"back to mark
  3139. &amp;ns \} \"no-space mode
  3140. &amp;el \{\
  3141. &amp;po \\nMu \"restore left margin
  3142. &amp; ---
  3143. 'bp \}
  3144. &amp;&amp;
  3145. &amp;ll 3.1i \"column width
  3146. &amp;nr M \\n(.o \"save left margin
  3147. </PRE></TT></DL>
  3148. Typically a portion of the top of the first page
  3149. contains full width text;
  3150. the request for the narrower line length,
  3151. as well as another <TT>.mk</TT> would
  3152. be made where the two column output was to begin.
  3153. </P>
  3154. <H4>Footnotes
  3155. </H4>
  3156. <P>
  3157. The footnote mechanism to be described is used by
  3158. embedding the footnotes in the input text at the
  3159. point of reference,
  3160. demarcated by an initial <TT>.fn</TT> and a terminal <TT>.ef</TT>:
  3161. <DL><DT><DD><TT><PRE>
  3162. &amp;fn
  3163. <I>Footnote text and control lines...</I>
  3164. &amp;ef
  3165. </PRE></TT></DL>
  3166. In the following,
  3167. footnotes are processed in a separate environment and diverted
  3168. for later printing in the space immediately prior to the bottom
  3169. margin.
  3170. There is provision for the case where the last collected
  3171. footnote doesn't completely fit in the available space.
  3172. <DL><DT><DD><TT><PRE>
  3173. &amp;de hd \"header
  3174. &amp; ---
  3175. &amp;nr x 0 1 \"init footnote count
  3176. &amp;nr y 0-\\nb \"current footer place
  3177. &amp;ch fo -\\nbu \"reset footer trap
  3178. &amp;if \\n(dn .fz \"leftover footnote
  3179. &amp;&amp;
  3180. </PRE></TT></DL>
  3181. <DL><DT><DD><TT><PRE>
  3182. &amp;de fo \"footer
  3183. &amp;nr dn 0 \"zero last diversion size
  3184. &amp;if \\nx \{\
  3185. &amp;ev 1 \"expand footnotes in ev1
  3186. &amp;nf \"retain vertical size
  3187. &amp;FN \"footnotes
  3188. &amp;rm FN \"delete it
  3189. </PRE></TT></DL>
  3190. <DL><DT><DD><TT><PRE>
  3191. &amp;if "\\n(.z"fy" .di \"end overflow di
  3192. &amp;nr x 0 \"disable fx
  3193. &amp;ev \} \"pop environment
  3194. &amp; ---
  3195. 'bp
  3196. &amp;&amp;
  3197. </PRE></TT></DL>
  3198. <DL><DT><DD><TT><PRE>
  3199. &amp;de fx \"process footnote overflow
  3200. &amp;if \\nx .di fy \"divert overflow
  3201. &amp;&amp;
  3202. </PRE></TT></DL>
  3203. <DL><DT><DD><TT><PRE>
  3204. &amp;de fn \"start footnote
  3205. &amp;da FN \"divert (append) footnote
  3206. &amp;ev 1 \"in environment 1
  3207. &amp;if \\n+x=1 .fs \"if 1st, separator
  3208. &amp;fi \"fill mode
  3209. &amp;&amp;
  3210. </PRE></TT></DL>
  3211. <DL><DT><DD><TT><PRE>
  3212. &amp;de ef \"end footnote
  3213. &amp;br \"finish output
  3214. &amp;nr z \\n(.v \"save spacing
  3215. &amp;ev \"pop ev
  3216. &amp;di \"end diversion
  3217. &amp;nr y -\\n(dn \"new footer position,
  3218. &amp;if \\nx=1 .nr y -(\\n(.v-\\nz) \
  3219. \"uncertainty correction
  3220. &amp;ch fo \\nyu \"y is negative
  3221. &amp;if (\\n(nl+1v)&#62;(\\n(.p+\\ny) \
  3222. &amp;ch fo \\n(nlu+1v \"didn't fit
  3223. &amp;&amp;
  3224. </PRE></TT></DL>
  3225. <DL><DT><DD><TT><PRE>
  3226. &amp;de fs \"separator
  3227. \l'1i' \"1 inch rule
  3228. &amp;br
  3229. &amp;&amp;
  3230. </PRE></TT></DL>
  3231. <DL><DT><DD><TT><PRE>
  3232. &amp;de fz \"get leftover footnote
  3233. &amp;fn
  3234. &amp;nf \"retain vertical size
  3235. &amp;fy \"where fx put it
  3236. &amp;ef
  3237. &amp;&amp;
  3238. </PRE></TT></DL>
  3239. <DL><DT><DD><TT><PRE>
  3240. &amp;nr b 1.0i \"bottom margin size
  3241. &amp;wh 0 hd \"header trap
  3242. &amp;wh 12i fo \"footer trap-&#62;temp pos
  3243. &amp;wh -\\nbu fx \"fx at footer position
  3244. &amp;ch fo -\\nbu \"conceal fx with fo
  3245. </PRE></TT></DL>
  3246. </P>
  3247. <P>
  3248. The header <TT>hd</TT> initializes a footnote count register <TT>x</TT>,
  3249. and sets both the current footer trap position register <TT>y</TT> and
  3250. the footer trap itself to a nominal position specified in
  3251. register <TT>b</TT>.
  3252. In addition, if the register <TT>dn</TT> indicates a leftover footnote,
  3253. <TT>fz</TT> is invoked to reprocess it.
  3254. The footnote start macro <TT>fn</TT> begins a diversion (append) in environment 1,
  3255. and increments the count <TT>x</TT>; if the count is one, the footnote separator <TT>fs</TT>
  3256. is interpolated.
  3257. The separator is kept in a separate macro to permit user redefinition.
  3258. </P>
  3259. <P>
  3260. The footnote end macro <TT>ef</TT> restores
  3261. the previous environment and ends the diversion after saving the spacing size in register <TT>z</TT>.
  3262. <TT>y</TT> is then decremented by the size of the footnote, available in <TT>dn</TT>;
  3263. then on the first footnote, <TT>y</TT> is further decremented by the difference
  3264. in vertical baseline spacings of the two environments, to
  3265. prevent the late triggering of the footer trap from causing the last
  3266. line of the combined footnotes to overflow.
  3267. The footer trap is then set to the lower (on the page) of <TT>y</TT> or the current page position (<TT>nl</TT>)
  3268. plus one line, to allow for printing the reference line.
  3269. </P>
  3270. <P>
  3271. If indicated by <TT>x</TT>, the footer <TT>fo</TT> rereads the footnotes from <TT>FN</TT> in nofill mode
  3272. in environment 1,
  3273. and deletes <TT>FN</TT>.
  3274. If the footnotes were too large to fit, the macro <TT>fx</TT> will be trap-invoked to redivert
  3275. the overflow into <TT>fy</TT>,
  3276. and the register <TT>dn</TT> will later indicate to the header whether <TT>fy</TT> is empty.
  3277. </P>
  3278. <P>
  3279. Both <TT>fo</TT> and <TT>fx</TT> are planted in the nominal footer trap position in an order
  3280. that causes <TT>fx</TT> to be concealed unless the <TT>fo</TT> trap is moved.
  3281. The footer then terminates the overflow diversion, if necessary, and
  3282. zeros <TT>x</TT> to disable <TT>fx</TT>,
  3283. because the uncertainty correction
  3284. together with a not-too-late triggering of the footer can result
  3285. in the footnote rereading finishing before reaching the <TT>fx</TT> trap.
  3286. </P>
  3287. <P>
  3288. A good exercise for the student is to combine the multiple-column and footnote mechanisms.
  3289. </P>
  3290. <H4>The Last Page
  3291. </H4>
  3292. <P>
  3293. After the last input file has ended, <I>nroff</I> and <I>troff</I>
  3294. invoke the <I>end macro</I> (&#167;7), if any,
  3295. and when it finishes, eject the remainder of the page.
  3296. During the eject, any traps encountered are processed normally.
  3297. At the end of this last page, processing terminates
  3298. unless a partial line, word, or partial word remains.
  3299. If it is desired that another page be started, the end-macro
  3300. <DL><DT><DD><TT><PRE>
  3301. &amp;de en \"end-macro
  3302. \c
  3303. 'bp
  3304. &amp;&amp;
  3305. &amp;em en
  3306. </PRE></TT></DL>
  3307. will deposit a null partial word,
  3308. and produce another last page.
  3309. <br>&#32;<br>
  3310. <HR>
  3311. <br>&#32;<br>
  3312. </P>
  3313. <br>&#32;<br>
  3314. <B>Special Character Names
  3315. </B><P>
  3316. The following table lists names for a set of characters,
  3317. most of which have traditionally been provided by <I>troff</I> using
  3318. the `special' or `symbol' font.
  3319. Many of these sequences are old ways to get what are now Unicode
  3320. characters;
  3321. Lucida Sans, for example, has glyphs corresponding to many of these
  3322. but does not have the special sequences.
  3323. Therefore
  3324. the <I>troff</I> sequence
  3325. gives the character &#191; from the Times font instead of the
  3326. character &#191; from the current font, in this case Lucida Sans.
  3327. Not all sequences print on any particular device, including this one; Peter
  3328. faces appear in their place.
  3329. <br><img src="-.162514.gif"><br>
  3330. </P>
  3331. <br>&#32;<br>
  3332. <A href=http://www.lucent.com/copyright.html>
  3333. Copyright</A> &#169; 2000 Lucent Technologies Inc. All rights reserved.
  3334. </body></html>