1151497SruThis is groff, produced by makeinfo version 4.8 from ./groff.texinfo. 2104862Sru 3151497Sru This manual documents GNU `troff' version 1.19.2. 4104862Sru 5151497Sru Copyright (C) 1994-2000, 2001, 2002, 2003, 2004, 2005 Free Software 6151497SruFoundation, Inc. 7104862Sru 8104862Sru Permission is granted to copy, distribute and/or modify this 9104862Sru document under the terms of the GNU Free Documentation License, 10104862Sru Version 1.1 or any later version published by the Free Software 11104862Sru Foundation; with no Invariant Sections, with the Front-Cover texts 12104862Sru being `A GNU Manual," and with the Back-Cover Texts as in (a) 13104862Sru below. A copy of the license is included in the section entitled 14104862Sru `GNU Free Documentation License." 15104862Sru 16104862Sru (a) The FSF's Back-Cover Text is: `You have freedom to copy and 17104862Sru modify this GNU Manual, like GNU software. Copies published by 18104862Sru the Free Software Foundation raise funds for GNU development." 19151497Sru 20114402SruINFO-DIR-SECTION Typesetting 21104862SruSTART-INFO-DIR-ENTRY 22104862Sru* Groff: (groff). The GNU troff document formatting system. 23104862SruEND-INFO-DIR-ENTRY 24104862Sru 25104862Sru 26104862SruFile: groff, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) 27104862Sru 28104862SruGNU troff 29104862Sru********* 30104862Sru 31151497SruThis manual documents GNU `troff' version 1.19.2. 32104862Sru 33151497Sru Copyright (C) 1994-2000, 2001, 2002, 2003, 2004, 2005 Free Software 34151497SruFoundation, Inc. 35104862Sru 36104862Sru Permission is granted to copy, distribute and/or modify this 37104862Sru document under the terms of the GNU Free Documentation License, 38104862Sru Version 1.1 or any later version published by the Free Software 39104862Sru Foundation; with no Invariant Sections, with the Front-Cover texts 40104862Sru being `A GNU Manual," and with the Back-Cover Texts as in (a) 41104862Sru below. A copy of the license is included in the section entitled 42104862Sru `GNU Free Documentation License." 43104862Sru 44104862Sru (a) The FSF's Back-Cover Text is: `You have freedom to copy and 45104862Sru modify this GNU Manual, like GNU software. Copies published by 46104862Sru the Free Software Foundation raise funds for GNU development." 47151497Sru 48104862Sru* Menu: 49104862Sru 50104862Sru* Introduction:: 51104862Sru* Invoking groff:: 52104862Sru* Tutorial for Macro Users:: 53104862Sru* Macro Packages:: 54104862Sru* gtroff Reference:: 55104862Sru* Preprocessors:: 56104862Sru* Output Devices:: 57104862Sru* File formats:: 58104862Sru* Installation:: 59104862Sru* Copying This Manual:: 60104862Sru* Request Index:: 61104862Sru* Escape Index:: 62104862Sru* Operator Index:: 63104862Sru* Register Index:: 64104862Sru* Macro Index:: 65104862Sru* String Index:: 66104862Sru* Glyph Name Index:: 67104862Sru* Font File Keyword Index:: 68104862Sru* Program and File Index:: 69104862Sru* Concept Index:: 70104862Sru 71104862Sru 72104862SruFile: groff, Node: Introduction, Next: Invoking groff, Prev: Top, Up: Top 73104862Sru 74151497Sru1 Introduction 75151497Sru************** 76104862Sru 77151497SruGNU `troff' (or `groff') is a system for typesetting documents. 78104862Sru`troff' is very flexible and has been in existence (and use) for about 79104862Sru3 decades. It is quite widespread and firmly entrenched in the UNIX 80104862Srucommunity. 81104862Sru 82104862Sru* Menu: 83104862Sru 84104862Sru* What Is groff?:: 85104862Sru* History:: 86104862Sru* groff Capabilities:: 87104862Sru* Macro Package Intro:: 88104862Sru* Preprocessor Intro:: 89104862Sru* Output device intro:: 90104862Sru* Credits:: 91104862Sru 92104862Sru 93104862SruFile: groff, Node: What Is groff?, Next: History, Prev: Introduction, Up: Introduction 94104862Sru 95151497Sru1.1 What Is `groff'? 96151497Sru==================== 97104862Sru 98151497Sru`groff' belongs to an older generation of document preparation systems, 99151497Sruwhich operate more like compilers than the more recent interactive 100151497SruWYSIWYG(1) (*note What Is groff?-Footnote-1::) systems. `groff' and 101151497Sruits contemporary counterpart, TeX, both work using a "batch" paradigm: 102151497SruThe input (or "source") files are normal text files with embedded 103151497Sruformatting commands. These files can then be processed by `groff' to 104151497Sruproduce a typeset document on a variety of devices. 105104862Sru 106104862Sru Likewise, `groff' should not be confused with a "word processor", 107104862Srusince that term connotes an integrated system that includes an editor 108104862Sruand a text formatter. Also, many word processors follow the WYSIWYG 109104862Sruparadigm discussed earlier. 110104862Sru 111104862Sru Although WYSIWYG systems may be easier to use, they have a number of 112104862Srudisadvantages compared to `troff': 113104862Sru 114104862Sru * They must be used on a graphics display to work on a document. 115104862Sru 116104862Sru * Most of the WYSIWYG systems are either non-free or are not very 117104862Sru portable. 118104862Sru 119104862Sru * `troff' is firmly entrenched in all UNIX systems. 120104862Sru 121104862Sru * It is difficult to have a wide range of capabilities available 122104862Sru within the confines of a GUI/window system. 123104862Sru 124104862Sru * It is more difficult to make global changes to a document. 125104862Sru 126104862Sru "GUIs normally make it simple to accomplish simple actions and 127104862Sru impossible to accomplish complex actions." -Doug Gwyn (22/Jun/91 128104862Sru in `comp.unix.wizards') 129104862Sru 130104862Sru 131104862SruFile: groff, Node: What Is groff?-Footnotes, Up: What Is groff? 132104862Sru 133104862Sru (1) What You See Is What You Get 134104862Sru 135104862Sru 136104862SruFile: groff, Node: History, Next: groff Capabilities, Prev: What Is groff?, Up: Introduction 137104862Sru 138151497Sru1.2 History 139151497Sru=========== 140104862Sru 141151497Sru`troff' can trace its origins back to a formatting program called 142104862Sru`runoff', written by J. E. Saltzer, which ran on MIT's CTSS operating 143104862Srusystem in the mid-sixties. This name came from the common phrase of 144104862Sruthe time "I'll run off a document." Bob Morris ported it to the 635 145104862Sruarchitecture and called the program `roff' (an abbreviation of 146104862Sru`runoff'). It was rewritten as `rf' for the PDP-7 (before having 147104862SruUNIX), and at the same time (1969), Doug McIllroy rewrote an extended 148104862Sruand simplified version of `roff' in the BCPL programming language. 149104862Sru 150104862Sru The first version of UNIX was developed on a PDP-7 which was sitting 151104862Sruaround Bell Labs. In 1971 the developers wanted to get a PDP-11 for 152104862Srufurther work on the operating system. In order to justify the cost for 153104862Sruthis system, they proposed that they would implement a document 154104862Sruformatting system for the AT&T patents division. This first formatting 155104862Sruprogram was a reimplementation of McIllroy's `roff', written by 156104862SruJ. F. Ossanna. 157104862Sru 158104862Sru When they needed a more flexible language, a new version of `roff' 159104862Srucalled `nroff' ("Newer `roff'") was written. It had a much more 160104862Srucomplicated syntax, but provided the basis for all future versions. 161104862SruWhen they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a 162104862Sruversion of `nroff' that would drive it. It was dubbed `troff', for 163104862Sru"typesetter `roff'", although many people have speculated that it 164104862Sruactually means "Times `roff'" because of the use of the Times font 165104862Srufamily in `troff' by default. As such, the name `troff' is pronounced 166104862Sru`t-roff' rather than `trough'. 167104862Sru 168104862Sru With `troff' came `nroff' (they were actually the same program 169104862Sruexcept for some `#ifdef's), which was for producing output for line 170104862Sruprinters and character terminals. It understood everything `troff' 171104862Srudid, and ignored the commands which were not applicable (e.g. font 172104862Sruchanges). 173104862Sru 174104862Sru Since there are several things which cannot be done easily in 175104862Sru`troff', work on several preprocessors began. These programs would 176104862Srutransform certain parts of a document into `troff', which made a very 177104862Srunatural use of pipes in UNIX. 178104862Sru 179151497Sru The `eqn' preprocessor allowed mathematical formul� to be specified 180104862Sruin a much simpler and more intuitive manner. `tbl' is a preprocessor 181104862Srufor formatting tables. The `refer' preprocessor (and the similar 182104862Sruprogram, `bib') processes citations in a document according to a 183104862Srubibliographic database. 184104862Sru 185104862Sru Unfortunately, Ossanna's `troff' was written in PDP-11 assembly 186104862Srulanguage and produced output specifically for the CAT phototypesetter. 187104862SruHe rewrote it in C, although it was now 7000 lines of uncommented code 188104862Sruand still dependent on the CAT. As the CAT became less common, and was 189104862Sruno longer supported by the manufacturer, the need to make it support 190104862Sruother devices became a priority. However, before this could be done, 191104862SruOssanna was killed in a car accident. 192104862Sru 193104862Sru So, Brian Kernighan took on the task of rewriting `troff'. The 194104862Srunewly rewritten version produced device independent code which was very 195104862Srueasy for postprocessors to read and translate to the appropriate 196104862Sruprinter codes. Also, this new version of `troff' (called `ditroff' for 197104862Sru"device independent `troff'") had several extensions, which included 198104862Srudrawing functions. 199104862Sru 200104862Sru Due to the additional abilities of the new version of `troff', 201104862Sruseveral new preprocessors appeared. The `pic' preprocessor provides a 202104862Sruwide range of drawing functions. Likewise the `ideal' preprocessor did 203104862Sruthe same, although via a much different paradigm. The `grap' 204104862Srupreprocessor took specifications for graphs, but, unlike other 205104862Srupreprocessors, produced `pic' code. 206104862Sru 207104862Sru James Clark began work on a GNU implementation of `ditroff' in 208104862Sruearly 1989. The first version, `groff' 0.3.1, was released June 1990. 209104862Sru`groff' included: 210104862Sru 211104862Sru * A replacement for `ditroff' with many extensions. 212104862Sru 213104862Sru * The `soelim', `pic', `tbl', and `eqn' preprocessors. 214104862Sru 215104862Sru * Postprocessors for character devices, POSTSCRIPT, TeX DVI, and 216104862Sru X Windows. GNU `troff' also eliminated the need for a separate 217104862Sru `nroff' program with a postprocessor which would produce ASCII 218104862Sru output. 219104862Sru 220104862Sru * A version of the `me' macros and an implementation of the `man' 221104862Sru macros. 222104862Sru 223104862Sru Also, a front-end was included which could construct the, sometimes 224104862Srupainfully long, pipelines required for all the post- and preprocessors. 225104862Sru 226104862Sru Development of GNU `troff' progressed rapidly, and saw the additions 227104862Sruof a replacement for `refer', an implementation of the `ms' and `mm' 228104862Srumacros, and a program to deduce how to format a document (`grog'). 229104862Sru 230104862Sru It was declared a stable (i.e. non-beta) package with the release of 231104862Sruversion 1.04 around November 1991. 232104862Sru 233104862Sru Beginning in 1999, `groff' has new maintainers (the package was an 234104862Sruorphan for a few years). As a result, new features and programs like 235104862Sru`grn', a preprocessor for gremlin images, and an output device to 236104862Sruproduce HTML output have been added. 237104862Sru 238104862Sru 239104862SruFile: groff, Node: groff Capabilities, Next: Macro Package Intro, Prev: History, Up: Introduction 240104862Sru 241151497Sru1.3 `groff' Capabilities 242151497Sru======================== 243104862Sru 244151497SruSo what exactly is `groff' capable of doing? `groff' provides a wide 245151497Srurange of low-level text formatting operations. Using these, it is 246104862Srupossible to perform a wide range of formatting tasks, such as 247104862Srufootnotes, table of contents, multiple columns, etc. Here's a list of 248104862Sruthe most important operations supported by `groff': 249104862Sru 250104862Sru * text filling, adjusting, and centering 251104862Sru 252104862Sru * hyphenation 253104862Sru 254104862Sru * page control 255104862Sru 256104862Sru * font and glyph size control 257104862Sru 258104862Sru * vertical spacing (e.g. double-spacing) 259104862Sru 260104862Sru * line length and indenting 261104862Sru 262104862Sru * macros, strings, diversions, and traps 263104862Sru 264104862Sru * number registers 265104862Sru 266104862Sru * tabs, leaders, and fields 267104862Sru 268104862Sru * input and output conventions and character translation 269104862Sru 270104862Sru * overstrike, bracket, line drawing, and zero-width functions 271104862Sru 272104862Sru * local horizontal and vertical motions and the width function 273104862Sru 274104862Sru * three-part titles 275104862Sru 276104862Sru * output line numbering 277104862Sru 278104862Sru * conditional acceptance of input 279104862Sru 280104862Sru * environment switching 281104862Sru 282104862Sru * insertions from the standard input 283104862Sru 284104862Sru * input/output file switching 285104862Sru 286104862Sru * output and error messages 287104862Sru 288104862Sru 289104862SruFile: groff, Node: Macro Package Intro, Next: Preprocessor Intro, Prev: groff Capabilities, Up: Introduction 290104862Sru 291151497Sru1.4 Macro Packages 292151497Sru================== 293104862Sru 294151497SruSince `groff' provides such low-level facilities, it can be quite 295104862Srudifficult to use by itself. However, `groff' provides a "macro" 296104862Srufacility to specify how certain routine operations (e.g. starting 297114402Sruparagraphs, printing headers and footers, etc.) should be done. These 298104862Srumacros can be collected together into a "macro package". There are a 299104862Srunumber of macro packages available; the most common (and the ones 300104862Srudescribed in this manual) are `man', `mdoc', `me', `ms', and `mm'. 301104862Sru 302104862Sru 303104862SruFile: groff, Node: Preprocessor Intro, Next: Output device intro, Prev: Macro Package Intro, Up: Introduction 304104862Sru 305151497Sru1.5 Preprocessors 306151497Sru================= 307104862Sru 308151497SruAlthough `groff' provides most functions needed to format a document, 309151497Srusome operations would be unwieldy (e.g. to draw pictures). Therefore, 310151497Sruprograms called "preprocessors" were written which understand their own 311151497Srulanguage and produce the necessary `groff' operations. These 312151497Srupreprocessors are able to differentiate their own input from the rest 313151497Sruof the document via markers. 314104862Sru 315104862Sru To use a preprocessor, UNIX pipes are used to feed the output from 316104862Sruthe preprocessor into `groff'. Any number of preprocessors may be used 317104862Sruon a given document; in this case, the preprocessors are linked 318104862Srutogether into one pipeline. However, with `groff', the user does not 319104862Sruneed to construct the pipe, but only tell `groff' what preprocessors to 320104862Sruuse. 321104862Sru 322104862Sru `groff' currently has preprocessors for producing tables (`tbl'), 323104862Srutypesetting equations (`eqn'), drawing pictures (`pic' and `grn'), and 324104862Srufor processing bibliographies (`refer'). An associated program which 325104862Sruis useful when dealing with preprocessors is `soelim'. 326104862Sru 327104862Sru A free implementation of `grap', a preprocessor for drawing graphs, 328104862Srucan be obtained as an extra package; `groff' can use `grap' also. 329104862Sru 330104862Sru There are other preprocessors in existence, but, unfortunately, no 331104862Srufree implementations are available. Among them are preprocessors for 332104862Srudrawing mathematical pictures (`ideal') and chemical structures 333104862Sru(`chem'). 334104862Sru 335104862Sru 336104862SruFile: groff, Node: Output device intro, Next: Credits, Prev: Preprocessor Intro, Up: Introduction 337104862Sru 338151497Sru1.6 Output Devices 339151497Sru================== 340104862Sru 341151497Sru`groff' actually produces device independent code which may be fed into 342151497Srua postprocessor to produce output for a particular device. Currently, 343151497Sru`groff' has postprocessors for POSTSCRIPT devices, character terminals, 344151497SruX Windows (for previewing), TeX DVI format, HP LaserJet 4 and Canon LBP 345151497Sruprinters (which use CAPSL), and HTML. 346104862Sru 347104862Sru 348104862SruFile: groff, Node: Credits, Prev: Output device intro, Up: Introduction 349104862Sru 350151497Sru1.7 Credits 351151497Sru=========== 352104862Sru 353151497SruLarge portions of this manual were taken from existing documents, most 354151497Srunotably, the manual pages for the `groff' package by James Clark, and 355151497SruEric Allman's papers on the `me' macro package. 356104862Sru 357104862Sru The section on the `man' macro package is partly based on Susan G. 358104862SruKleinmann's `groff_man' manual page written for the Debian GNU/Linux 359104862Srusystem. 360104862Sru 361104862Sru Larry Kollar contributed the section in the `ms' macro package. 362104862Sru 363104862Sru 364104862SruFile: groff, Node: Invoking groff, Next: Tutorial for Macro Users, Prev: Introduction, Up: Top 365104862Sru 366151497Sru2 Invoking `groff' 367151497Sru****************** 368104862Sru 369151497SruThis section focuses on how to invoke the `groff' front end. This 370104862Srufront end takes care of the details of constructing the pipeline among 371104862Sruthe preprocessors, `gtroff' and the postprocessor. 372104862Sru 373104862Sru It has become a tradition that GNU programs get the prefix `g' to 374104862Srudistinguish it from its original counterparts provided by the host (see 375104862Sru*Note Environment::, for more details). Thus, for example, `geqn' is 376104862SruGNU `eqn'. On operating systems like GNU/Linux or the Hurd, which 377104862Srudon't contain proprietary versions of `troff', and on 378104862SruMS-DOS/MS-Windows, where `troff' and associated programs are not 379104862Sruavailable at all, this prefix is omitted since GNU `troff' is the only 380104862Sruused incarnation of `troff'. Exception: `groff' is never replaced by 381104862Sru`roff'. 382104862Sru 383104862Sru In this document, we consequently say `gtroff' when talking about 384104862Sruthe GNU `troff' program. All other implementations of `troff' are 385104862Srucalled AT&T `troff' which is the common origin of all `troff' derivates 386104862Sru(with more or less compatible changes). Similarly, we say `gpic', 387104862Sru`geqn', etc. 388104862Sru 389104862Sru* Menu: 390104862Sru 391104862Sru* Groff Options:: 392104862Sru* Environment:: 393104862Sru* Macro Directories:: 394104862Sru* Font Directories:: 395114402Sru* Paper Size:: 396104862Sru* Invocation Examples:: 397104862Sru 398104862Sru 399104862SruFile: groff, Node: Groff Options, Next: Environment, Prev: Invoking groff, Up: Invoking groff 400104862Sru 401151497Sru2.1 Options 402151497Sru=========== 403104862Sru 404151497Sru`groff' normally runs the `gtroff' program and a postprocessor 405104862Sruappropriate for the selected device. The default device is `ps' (but 406104862Sruit can be changed when `groff' is configured and built). It can 407104862Sruoptionally preprocess with any of `gpic', `geqn', `gtbl', `ggrn', 408104862Sru`grap', `grefer', or `gsoelim'. 409104862Sru 410104862Sru This section only documents options to the `groff' front end. Many 411104862Sruof the arguments to `groff' are passed on to `gtroff', therefore those 412104862Sruare also included. Arguments to pre- or postprocessors can be found in 413104862Sru*Note Invoking gpic::, *Note Invoking geqn::, *Note Invoking gtbl::, 414104862Sru*Note Invoking ggrn::, *Note Invoking grefer::, *Note Invoking 415104862Srugsoelim::, *Note Invoking grotty::, *Note Invoking grops::, *Note 416104862SruInvoking grohtml::, *Note Invoking grodvi::, *Note Invoking grolj4::, 417104862Sru*Note Invoking grolbp::, and *Note Invoking gxditview::. 418104862Sru 419104862Sru The command line format for `groff' is: 420104862Sru 421104862Sru 422104862Sru groff [ -abceghilpstvzCEGNRSUVXZ ] [ -FDIR ] [ -mNAME ] 423104862Sru [ -TDEF ] [ -fFAM ] [ -wNAME ] [ -WNAME ] 424104862Sru [ -MDIR ] [ -dCS ] [ -rCN ] [ -nNUM ] 425104862Sru [ -oLIST ] [ -PARG ] [ -LARG ] [ -IDIR ] 426104862Sru [ FILES... ] 427104862Sru 428104862Sru The command line format for `gtroff' is as follows. 429104862Sru 430104862Sru 431104862Sru gtroff [ -abcivzCERU ] [ -wNAME ] [ -WNAME ] [ -dCS ] 432104862Sru [ -fFAM ] [ -mNAME ] [ -nNUM ] 433104862Sru [ -oLIST ] [ -rCN ] [ -TNAME ] 434104862Sru [ -FDIR ] [ -MDIR ] [ FILES... ] 435104862Sru 436104862SruObviously, many of the options to `groff' are actually passed on to 437104862Sru`gtroff'. 438104862Sru 439104862Sru Options without an argument can be grouped behind a single `-'. A 440104862Srufilename of `-' denotes the standard input. It is possible to have 441104862Sruwhitespace between an option and its parameter. 442104862Sru 443104862Sru The `grog' command can be used to guess the correct `groff' command 444104862Sruto format a file. 445104862Sru 446104862Sru Here's the description of the command-line options: 447104862Sru 448104862Sru`-h' 449104862Sru Print a help message. 450104862Sru 451104862Sru`-e' 452104862Sru Preprocess with `geqn'. 453104862Sru 454104862Sru`-t' 455104862Sru Preprocess with `gtbl'. 456104862Sru 457104862Sru`-g' 458104862Sru Preprocess with `ggrn'. 459104862Sru 460104862Sru`-G' 461104862Sru Preprocess with `grap'. 462104862Sru 463104862Sru`-p' 464104862Sru Preprocess with `gpic'. 465104862Sru 466104862Sru`-s' 467104862Sru Preprocess with `gsoelim'. 468104862Sru 469104862Sru`-c' 470104862Sru Suppress color output. 471104862Sru 472104862Sru`-R' 473104862Sru Preprocess with `grefer'. No mechanism is provided for passing 474104862Sru arguments to `grefer' because most `grefer' options have 475104862Sru equivalent commands which can be included in the file. *Note 476104862Sru grefer::, for more details. 477104862Sru 478104862Sru Note that `gtroff' also accepts a `-R' option, which is not 479104862Sru accessible via `groff'. This option prevents the loading of the 480104862Sru `troffrc' and `troffrc-end' files. 481104862Sru 482104862Sru`-v' 483104862Sru Make programs run by `groff' print out their version number. 484104862Sru 485104862Sru`-V' 486151497Sru Print the pipeline on `stdout' instead of executing it. If 487151497Sru specified more than once, print the pipeline on `stderr' and 488151497Sru execute it. 489104862Sru 490104862Sru`-z' 491104862Sru Suppress output from `gtroff'. Only error messages are printed. 492104862Sru 493104862Sru`-Z' 494104862Sru Do not postprocess the output of `gtroff'. Normally `groff' 495104862Sru automatically runs the appropriate postprocessor. 496104862Sru 497104862Sru`-PARG' 498104862Sru Pass ARG to the postprocessor. Each argument should be passed 499104862Sru with a separate `-P' option. Note that `groff' does not prepend 500104862Sru `-' to ARG before passing it to the postprocessor. 501104862Sru 502104862Sru`-l' 503104862Sru Send the output to a spooler for printing. The command used for 504104862Sru this is specified by the `print' command in the device description 505104862Sru file (see *Note Font Files::, for more info). If not present, 506104862Sru `-l' is ignored. 507104862Sru 508104862Sru`-LARG' 509104862Sru Pass ARG to the spooler. Each argument should be passed with a 510104862Sru separate `-L' option. Note that `groff' does not prepend a `-' to 511104862Sru ARG before passing it to the postprocessor. If the `print' 512104862Sru keyword in the device description file is missing, `-L' is ignored. 513104862Sru 514104862Sru`-TDEV' 515104862Sru Prepare output for device DEV. The default device is `ps', unless 516104862Sru changed when `groff' was configured and built. The following are 517104862Sru the output devices currently available: 518104862Sru 519104862Sru `ps' 520104862Sru For POSTSCRIPT printers and previewers. 521104862Sru 522104862Sru `dvi' 523104862Sru For TeX DVI format. 524104862Sru 525104862Sru `X75' 526104862Sru For a 75dpi X11 previewer. 527104862Sru 528104862Sru `X75-12' 529104862Sru For a 75dpi X11 previewer with a 12pt base font in the 530104862Sru document. 531104862Sru 532104862Sru `X100' 533104862Sru For a 100dpi X11 previewer. 534104862Sru 535104862Sru `X100-12' 536104862Sru For a 100dpi X11 previewer with a 12pt base font in the 537104862Sru document. 538104862Sru 539104862Sru `ascii' 540104862Sru For typewriter-like devices using the (7-bit) ASCII character 541104862Sru set. 542104862Sru 543104862Sru `latin1' 544104862Sru For typewriter-like devices that support the Latin-1 545104862Sru (ISO 8859-1) character set. 546104862Sru 547104862Sru `utf8' 548104862Sru For typewriter-like devices which use the Unicode (ISO 10646) 549104862Sru character set with UTF-8 encoding. 550104862Sru 551104862Sru `cp1047' 552104862Sru For typewriter-like devices which use the EBCDIC encoding IBM 553104862Sru cp1047. 554104862Sru 555104862Sru `lj4' 556104862Sru For HP LaserJet4-compatible (or other PCL5-compatible) 557104862Sru printers. 558104862Sru 559104862Sru `lbp' 560104862Sru For Canon CAPSL printers (LBP-4 and LBP-8 series laser 561104862Sru printers). 562104862Sru 563104862Sru `html' 564104862Sru To produce HTML output. Note that the HTML driver consists 565104862Sru of two parts, a preprocessor (`pre-grohtml') and a 566104862Sru postprocessor (`post-grohtml'). 567104862Sru 568104862Sru The predefined `gtroff' string register `.T' contains the current 569104862Sru output device; the read-only number register `.T' is set to 1 if 570104862Sru this option is used (which is always true if `groff' is used to 571104862Sru call `gtroff'). *Note Built-in Registers::. 572104862Sru 573104862Sru The postprocessor to be used for a device is specified by the 574104862Sru `postpro' command in the device description file. (*Note Font 575104862Sru Files::, for more info.) This can be overridden with the `-X' 576104862Sru option. 577104862Sru 578104862Sru`-X' 579104862Sru Preview with `gxditview' instead of using the usual postprocessor. 580104862Sru This is unlikely to produce good results except with `-Tps'. 581104862Sru 582104862Sru Note that this is not the same as using `-TX75' or `-TX100' to 583104862Sru view a document with `gxditview': The former uses the metrics of 584104862Sru the specified device, whereas the latter uses X-specific fonts and 585104862Sru metrics. 586104862Sru 587104862Sru`-N' 588104862Sru Don't allow newlines with `eqn' delimiters. This is the same as 589104862Sru the `-N' option in `geqn'. 590104862Sru 591104862Sru`-S' 592104862Sru Safer mode. Pass the `-S' option to `gpic' and disable the 593104862Sru `open', `opena', `pso', `sy', and `pi' requests. For security 594104862Sru reasons, this is enabled by default. 595104862Sru 596104862Sru`-U' 597104862Sru Unsafe mode. This enables the `open', `opena', `pso', `sy', and 598104862Sru `pi' requests. 599104862Sru 600104862Sru`-a' 601104862Sru Generate an ASCII approximation of the typeset output. The 602104862Sru read-only register `.A' is then set to 1. *Note Built-in 603104862Sru Registers::. A typical example is 604104862Sru 605104862Sru 606104862Sru groff -a -man -Tdvi troff.man | less 607104862Sru 608104862Sru which shows how lines are broken for the DVI device. Note that 609104862Sru this option is rather useless today since graphic output devices 610104862Sru are available virtually everywhere. 611104862Sru 612104862Sru`-b' 613104862Sru Print a backtrace with each warning or error message. This 614104862Sru backtrace should help track down the cause of the error. The line 615104862Sru numbers given in the backtrace may not always be correct: `gtroff' 616104862Sru can get confused by `as' or `am' requests while counting line 617104862Sru numbers. 618104862Sru 619104862Sru`-i' 620104862Sru Read the standard input after all the named input files have been 621104862Sru processed. 622104862Sru 623104862Sru`-wNAME' 624104862Sru Enable warning NAME. Available warnings are described in *Note 625104862Sru Debugging::. Multiple `-w' options are allowed. 626104862Sru 627104862Sru`-WNAME' 628104862Sru Inhibit warning NAME. Multiple `-W' options are allowed. 629104862Sru 630104862Sru`-E' 631104862Sru Inhibit all error messages. 632104862Sru 633104862Sru`-C' 634104862Sru Enable compatibility mode. *Note Implementation Differences::, 635104862Sru for the list of incompatibilities between `groff' and AT&T `troff'. 636104862Sru 637104862Sru`-dCS' 638104862Sru`-dNAME=S' 639104862Sru Define C or NAME to be a string S. C must be a one-letter name; 640104862Sru NAME can be of arbitrary length. All string assignments happen 641104862Sru before loading any macro file (including the start-up file). 642104862Sru 643104862Sru`-fFAM' 644104862Sru Use FAM as the default font family. *Note Font Families::. 645104862Sru 646104862Sru`-mNAME' 647104862Sru Read in the file `NAME.tmac'. Normally `groff' searches for this 648104862Sru in its macro directories. If it isn't found, it tries `tmac.NAME' 649104862Sru (searching in the same directories). 650104862Sru 651104862Sru`-nNUM' 652104862Sru Number the first page NUM. 653104862Sru 654104862Sru`-oLIST' 655104862Sru Output only pages in LIST, which is a comma-separated list of page 656104862Sru ranges; `N' means print page N, `M-N' means print every page 657104862Sru between M and N, `-N' means print every page up to N, `N-' means 658104862Sru print every page beginning with N. `gtroff' exits after printing 659104862Sru the last page in the list. All the ranges are inclusive on both 660104862Sru ends. 661104862Sru 662104862Sru Within `gtroff', this information can be extracted with the `.P' 663104862Sru register. *Note Built-in Registers::. 664104862Sru 665104862Sru If your document restarts page numbering at the beginning of each 666104862Sru chapter, then `gtroff' prints the specified page range for each 667104862Sru chapter. 668104862Sru 669104862Sru`-rCN' 670104862Sru`-rNAME=N' 671104862Sru Set number register C or NAME to the value N. C must be a 672104862Sru one-letter name; NAME can be of arbitrary length. N can be any 673114402Sru `gtroff' numeric expression. All register assignments happen 674104862Sru before loading any macro file (including the start-up file). 675104862Sru 676104862Sru`-FDIR' 677104862Sru Search `DIR' for subdirectories `devNAME' (NAME is the name of the 678104862Sru device), for the `DESC' file, and for font files before looking in 679104862Sru the standard directories (*note Font Directories::). This option 680104862Sru is passed to all pre- and postprocessors using the 681104862Sru `GROFF_FONT_PATH' environment variable. 682104862Sru 683104862Sru`-MDIR' 684104862Sru Search directory `DIR' for macro files before the standard 685104862Sru directories (*note Macro Directories::). 686104862Sru 687104862Sru`-IDIR' 688151497Sru This option may be used to specify a directory to search for files. 689151497Sru It is passed to the following programs: 690104862Sru 691151497Sru * `gsoelim' (see *Note gsoelim:: for more details); it also 692151497Sru implies `groff''s `-s' option. 693151497Sru 694151497Sru * `gtroff'; it is used to search files named in the `psbb' and 695151497Sru `so' requests. 696151497Sru 697151497Sru * `grops'; it is used to search files named in the 698151497Sru `\X'ps: import' and `\X'ps: file' escapes. 699151497Sru 700151497Sru The current directory is always searched first. This option may be 701151497Sru specified more than once; the directories will be searched in the 702151497Sru order specified. No directory search is performed for files 703151497Sru specified using an absolute path. 704151497Sru 705104862Sru 706104862SruFile: groff, Node: Environment, Next: Macro Directories, Prev: Groff Options, Up: Invoking groff 707104862Sru 708151497Sru2.2 Environment 709151497Sru=============== 710104862Sru 711151497SruThere are also several environment variables (of the operating system, 712151497Srunot within `gtroff') which can modify the behavior of `groff'. 713104862Sru 714104862Sru`GROFF_COMMAND_PREFIX' 715104862Sru If this is set to X, then `groff' runs `Xtroff' instead of 716104862Sru `gtroff'. This also applies to `tbl', `pic', `eqn', `grn', 717104862Sru `refer', and `soelim'. It does not apply to `grops', `grodvi', 718104862Sru `grotty', `pre-grohtml', `post-grohtml', `grolj4', and `gxditview'. 719104862Sru 720104862Sru The default command prefix is determined during the installation 721104862Sru process. If a non-GNU troff system is found, prefix `g' is used, 722104862Sru none otherwise. 723104862Sru 724104862Sru`GROFF_TMAC_PATH' 725104862Sru A colon-separated list of directories in which to search for macro 726104862Sru files (before the default directories are tried). *Note Macro 727104862Sru Directories::. 728104862Sru 729104862Sru`GROFF_TYPESETTER' 730104862Sru The default output device. 731104862Sru 732104862Sru`GROFF_FONT_PATH' 733104862Sru A colon-separated list of directories in which to search for the 734104862Sru `dev'NAME directory (before the default directories are tried). 735104862Sru *Note Font Directories::. 736104862Sru 737104862Sru`GROFF_BIN_PATH' 738104862Sru This search path, followed by `PATH', is used for commands executed 739104862Sru by `groff'. 740104862Sru 741104862Sru`GROFF_TMPDIR' 742104862Sru The directory in which `groff' creates temporary files. If this is 743104862Sru not set and `TMPDIR' is set, temporary files are created in that 744104862Sru directory. Otherwise temporary files are created in a 745104862Sru system-dependent default directory (on Unix and GNU/Linux systems, 746104862Sru this is usually `/tmp'). `grops', `grefer', `pre-grohtml', and 747104862Sru `post-grohtml' can create temporary files in this directory. 748104862Sru 749104862Sru Note that MS-DOS and MS-Windows ports of `groff' use semi-colons, 750104862Srurather than colons, to separate the directories in the lists described 751104862Sruabove. 752104862Sru 753104862Sru 754104862SruFile: groff, Node: Macro Directories, Next: Font Directories, Prev: Environment, Up: Invoking groff 755104862Sru 756151497Sru2.3 Macro Directories 757151497Sru===================== 758104862Sru 759151497SruAll macro file names must be named `NAME.tmac' or `tmac.NAME' to make 760151497Sruthe `-mNAME' command line option work. The `mso' request doesn't have 761151497Sruthis restriction; any file name can be used, and `gtroff' won't try to 762151497Sruappend or prepend the `tmac' string. 763104862Sru 764104862Sru Macro files are kept in the "tmac directories", all of which 765104862Sruconstitute the "tmac path". The elements of the search path for macro 766104862Srufiles are (in that order): 767104862Sru 768104862Sru * The directories specified with `gtroff''s or `groff''s `-M' 769104862Sru command line option. 770104862Sru 771104862Sru * The directories given in the `GROFF_TMAC_PATH' environment 772104862Sru variable. 773104862Sru 774104862Sru * The current directory (only if in unsafe mode using the `-U' 775104862Sru command line switch). 776104862Sru 777104862Sru * The home directory. 778104862Sru 779104862Sru * A platform-dependent directory, a site-specific 780104862Sru (platform-independent) directory, and the main tmac directory; the 781104862Sru default locations are 782104862Sru 783104862Sru 784104862Sru /usr/local/lib/groff/site-tmac 785104862Sru /usr/local/share/groff/site-tmac 786114402Sru /usr/local/share/groff/1.18.2/tmac 787104862Sru 788114402Sru assuming that the version of `groff' is 1.18.2, and the 789114402Sru installation prefix was `/usr/local'. It is possible to fine-tune 790114402Sru those directories during the installation process. 791104862Sru 792104862Sru 793114402SruFile: groff, Node: Font Directories, Next: Paper Size, Prev: Macro Directories, Up: Invoking groff 794104862Sru 795151497Sru2.4 Font Directories 796151497Sru==================== 797104862Sru 798151497SruBasically, there is no restriction how font files for `groff' are named 799151497Sruand how long font names are; however, to make the font family mechanism 800151497Sruwork (*note Font Families::), fonts within a family should start with 801151497Sruthe family name, followed by the shape. For example, the Times family 802151497Sruuses `T' for the family name and `R', `B', `I', and `BI' to indicate 803151497Sruthe shapes `roman', `bold', `italic', and `bold italic', respectively. 804151497SruThus the final font names are `TR', `TB', `TI', and `TBI'. 805104862Sru 806104862Sru All font files are kept in the "font directories" which constitute 807104862Sruthe "font path". The file search functions will always append the 808104862Srudirectory `dev'NAME, where NAME is the name of the output device. 809104862SruAssuming, say, DVI output, and `/foo/bar' as a font directory, the font 810104862Srufiles for `grodvi' must be in `/foo/bar/devdvi'. 811104862Sru 812104862Sru The elements of the search path for font files are (in that order): 813104862Sru 814104862Sru * The directories specified with `gtroff''s or `groff''s `-F' 815104862Sru command line option. All device drivers and some preprocessors 816104862Sru also have this option. 817104862Sru 818104862Sru * The directories given in the `GROFF_FONT_PATH' environment 819104862Sru variable. 820104862Sru 821104862Sru * A site-specific directory and the main font directory; the default 822104862Sru locations are 823104862Sru 824104862Sru 825104862Sru /usr/local/share/groff/site-font 826114402Sru /usr/local/share/groff/1.18.2/font 827104862Sru 828114402Sru assuming that the version of `groff' is 1.18.2, and the 829114402Sru installation prefix was `/usr/local'. It is possible to fine-tune 830114402Sru those directories during the installation process. 831104862Sru 832104862Sru 833114402SruFile: groff, Node: Paper Size, Next: Invocation Examples, Prev: Font Directories, Up: Invoking groff 834104862Sru 835151497Sru2.5 Paper Size 836151497Sru============== 837114402Sru 838151497SruIn groff, the page size for `gtroff' and for output devices are handled 839151497Sruseparately. *Note Page Layout::, for vertical manipulation of the page 840151497Srusize. *Note Line Layout::, for horizontal changes. 841114402Sru 842114402Sru A default paper size can be set in the device's `DESC' file. Most 843114402Sruoutput devices also have a command line option `-p' to override the 844114402Srudefault paper size and option `-l' to use landscape orientation. *Note 845114402SruDESC File Format::, for a description of the `papersize' keyword which 846114402Srutakes the same argument as `-p'. 847114402Sru 848114402Sru A convenient shorthand to set a particular paper size for `gtroff' 849114402Sruis command line option `-dpaper=SIZE'. This defines string `paper' 850114402Sruwhich is processed in file `papersize.tmac' (loaded in the start-up 851114402Srufile `troffrc' by default). Possible values for SIZE are the same as 852114402Sruthe predefined values for the `papersize' keyword (but only in 853114402Srulowercase) except `a7'-`d7'. An appended `l' (ell) character denotes 854114402Srulandscape orientation. 855114402Sru 856114402Sru For example, use the following for PS output on A4 paper in landscape 857114402Sruorientation: 858114402Sru 859114402Sru 860114402Sru groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps 861114402Sru 862114402Sru Note that it is up to the particular macro package to respect default 863114402Srupage dimensions set in this way (most do). 864114402Sru 865114402Sru 866114402SruFile: groff, Node: Invocation Examples, Prev: Paper Size, Up: Invoking groff 867114402Sru 868151497Sru2.6 Invocation Examples 869151497Sru======================= 870104862Sru 871151497SruThis section lists several common uses of `groff' and the corresponding 872151497Srucommand lines. 873104862Sru 874104862Sru 875104862Sru groff file 876104862Sru 877104862SruThis command processes `file' without a macro package or a 878104862Srupreprocessor. The output device is the default, `ps', and the output 879104862Sruis sent to `stdout'. 880104862Sru 881104862Sru 882104862Sru groff -t -mandoc -Tascii file | less 883104862Sru 884104862SruThis is basically what a call to the `man' program does. `gtroff' 885104862Sruprocesses the manual page `file' with the `mandoc' macro file (which in 886104862Sruturn either calls the `man' or the `mdoc' macro package), using the 887104862Sru`tbl' preprocessor and the ASCII output device. Finally, the `less' 888104862Srupager displays the result. 889104862Sru 890104862Sru 891104862Sru groff -X -m me file 892104862Sru 893104862SruPreview `file' with `gxditview', using the `me' macro package. Since 894104862Sruno `-T' option is specified, use the default device (`ps'). Note that 895104862Sruyou can either say `-m me' or `-me'; the latter is an anachronism from 896104862Sruthe early days of UNIX.(1) (*note Invocation Examples-Footnote-1::) 897104862Sru 898104862Sru 899104862Sru groff -man -rD1 -z file 900104862Sru 901104862SruCheck `file' with the `man' macro package, forcing double-sided 902104862Sruprinting - don't produce any output. 903104862Sru 904104862Sru* Menu: 905104862Sru 906104862Sru* grog:: 907104862Sru 908104862Sru 909104862SruFile: groff, Node: Invocation Examples-Footnotes, Up: Invocation Examples 910104862Sru 911104862Sru (1) The same is true for the other main macro packages that come 912104862Sruwith `groff': `man', `mdoc', `ms', `mm', and `mandoc'. This won't work 913104862Sruin general; for example, to load `trace.tmac', either `-mtrace' or 914104862Sru`-m trace' must be used. 915104862Sru 916104862Sru 917104862SruFile: groff, Node: grog, Prev: Invocation Examples, Up: Invocation Examples 918104862Sru 919151497Sru2.6.1 `grog' 920151497Sru------------ 921104862Sru 922151497Sru`grog' reads files, guesses which of the `groff' preprocessors and/or 923151497Srumacro packages are required for formatting them, and prints the `groff' 924151497Srucommand including those options on the standard output. It generates 925151497Sruone or more of the options `-e', `-man', `-me', `-mm', `-mom', `-ms', 926151497Sru`-mdoc', `-mdoc-old', `-p', `-R', `-g', `-G', `-s', and `-t'. 927104862Sru 928104862Sru A special file name `-' refers to the standard input. Specifying no 929104862Srufiles also means to read the standard input. Any specified options are 930104862Sruincluded in the printed command. No space is allowed between options 931104862Sruand their arguments. The only options recognized are `-C' (which is 932104862Srualso passed on) to enable compatibility mode, and `-v' to print the 933104862Sruversion number and exit. 934104862Sru 935104862Sru For example, 936104862Sru 937104862Sru 938104862Sru grog -Tdvi paper.ms 939104862Sru 940104862Sruguesses the appropriate command to print `paper.ms' and then prints it 941104862Sruto the command line after adding the `-Tdvi' option. For direct 942104862Sruexecution, enclose the call to `grog' in backquotes at the UNIX shell 943104862Sruprompt: 944104862Sru 945104862Sru 946104862Sru `grog -Tdvi paper.ms` > paper.dvi 947104862Sru 948104862SruAs seen in the example, it is still necessary to redirect the output to 949104862Srusomething meaningful (i.e. either a file or a pager program like 950104862Sru`less'). 951104862Sru 952104862Sru 953104862SruFile: groff, Node: Tutorial for Macro Users, Next: Macro Packages, Prev: Invoking groff, Up: Top 954104862Sru 955151497Sru3 Tutorial for Macro Users 956151497Sru************************** 957104862Sru 958151497SruMost users tend to use a macro package to format their papers. This 959104862Srumeans that the whole breadth of `groff' is not necessary for most 960104862Srupeople. This chapter covers the material needed to efficiently use a 961104862Srumacro package. 962104862Sru 963104862Sru* Menu: 964104862Sru 965104862Sru* Basics:: 966104862Sru* Common Features:: 967104862Sru 968104862Sru 969104862SruFile: groff, Node: Basics, Next: Common Features, Prev: Tutorial for Macro Users, Up: Tutorial for Macro Users 970104862Sru 971151497Sru3.1 Basics 972151497Sru========== 973104862Sru 974151497SruThis section covers some of the basic concepts necessary to understand 975151497Sruhow to use a macro package.(1) (*note Basics-Footnote-1::) References 976151497Sruare made throughout to more detailed information, if desired. 977104862Sru 978104862Sru `gtroff' reads an input file prepared by the user and outputs a 979104862Sruformatted document suitable for publication or framing. The input 980104862Sruconsists of text, or words to be printed, and embedded commands 981104862Sru("requests" and "escapes"), which tell `gtroff' how to format the 982104862Sruoutput. For more detail on this, see *Note Embedded Commands::. 983104862Sru 984104862Sru The word "argument" is used in this chapter to mean a word or number 985104862Sruwhich appears on the same line as a request, and which modifies the 986104862Srumeaning of that request. For example, the request 987104862Sru 988104862Sru 989104862Sru .sp 990104862Sru 991104862Sruspaces one line, but 992104862Sru 993104862Sru 994104862Sru .sp 4 995104862Sru 996104862Sruspaces four lines. The number 4 is an argument to the `sp' request 997104862Sruwhich says to space four lines instead of one. Arguments are separated 998104862Srufrom the request and from each other by spaces (_no_ tabs). More 999114402Srudetails on this can be found in *Note Request and Macro Arguments::. 1000104862Sru 1001104862Sru The primary function of `gtroff' is to collect words from input 1002104862Srulines, fill output lines with those words, justify the right-hand margin 1003104862Sruby inserting extra spaces in the line, and output the result. For 1004104862Sruexample, the input: 1005104862Sru 1006104862Sru 1007104862Sru Now is the time 1008104862Sru for all good men 1009104862Sru to come to the aid 1010104862Sru of their party. 1011104862Sru Four score and seven 1012104862Sru years ago, etc. 1013104862Sru 1014104862Sruis read, packed onto output lines, and justified to produce: 1015104862Sru 1016104862Sru Now is the time for all good men to come to the aid of their party. 1017104862Sru Four score and seven years ago, etc. 1018104862Sru 1019104862Sru Sometimes a new output line should be started even though the current 1020104862Sruline is not yet full; for example, at the end of a paragraph. To do 1021104862Sruthis it is possible to cause a "break", which starts a new output line. 1022104862SruSome requests cause a break automatically, as normally do blank input 1023104862Srulines and input lines beginning with a space. 1024104862Sru 1025104862Sru Not all input lines are text to be formatted. Some input lines are 1026104862Srurequests which describe how to format the text. Requests always have a 1027104862Sruperiod (`.') or an apostrophe (`'') as the first character of the input 1028104862Sruline. 1029104862Sru 1030104862Sru The text formatter also does more complex things, such as 1031104862Sruautomatically numbering pages, skipping over page boundaries, putting 1032104862Srufootnotes in the correct place, and so forth. 1033104862Sru 1034104862Sru Here are a few hints for preparing text for input to `gtroff'. 1035104862Sru 1036104862Sru * First, keep the input lines short. Short input lines are easier to 1037104862Sru edit, and `gtroff' packs words onto longer lines anyhow. 1038104862Sru 1039104862Sru * In keeping with this, it is helpful to begin a new line after every 1040104862Sru comma or phrase, since common corrections are to add or delete 1041104862Sru sentences or phrases. 1042104862Sru 1043104862Sru * End each sentence with two spaces - or better, start each sentence 1044104862Sru on a new line. `gtroff' recognizes characters that usually end a 1045104862Sru sentence, and inserts sentence space accordingly. 1046104862Sru 1047104862Sru * Do not hyphenate words at the end of lines - `gtroff' is smart 1048104862Sru enough to hyphenate words as needed, but is not smart enough to 1049104862Sru take hyphens out and join a word back together. Also, words such 1050104862Sru as "mother-in-law" should not be broken over a line, since then a 1051104862Sru space can occur where not wanted, such as "mother- in-law". 1052104862Sru 1053104862Sru `gtroff' double-spaces output text automatically if you use the 1054104862Srurequest `.ls 2'. Reactivate single-spaced mode by typing `.ls 1'.(2) 1055104862Sru(*note Basics-Footnote-2::) 1056104862Sru 1057104862Sru A number of requests allow to change the way the output looks, 1058104862Srusometimes called the "layout" of the output page. Most of these 1059104862Srurequests adjust the placing of "whitespace" (blank lines or spaces). 1060104862Sru 1061104862Sru The `bp' request starts a new page, causing a line break. 1062104862Sru 1063104862Sru The request `.sp N' leaves N lines of blank space. N can be omitted 1064104862Sru(meaning skip a single line) or can be of the form Ni (for N inches) or 1065104862SruNc (for N centimeters). For example, the input: 1066104862Sru 1067104862Sru 1068104862Sru .sp 1.5i 1069104862Sru My thoughts on the subject 1070104862Sru .sp 1071104862Sru 1072104862Sruleaves one and a half inches of space, followed by the line "My 1073104862Sruthoughts on the subject", followed by a single blank line (more 1074104862Srumeasurement units are available, see *Note Measurements::). 1075104862Sru 1076104862Sru Text lines can be centered by using the `ce' request. The line 1077104862Sruafter `ce' is centered (horizontally) on the page. To center more than 1078104862Sruone line, use `.ce N' (where N is the number of lines to center), 1079104862Srufollowed by the N lines. To center many lines without counting them, 1080104862Srutype: 1081104862Sru 1082104862Sru 1083104862Sru .ce 1000 1084104862Sru lines to center 1085104862Sru .ce 0 1086104862Sru 1087104862SruThe `.ce 0' request tells `groff' to center zero more lines, in other 1088104862Sruwords, stop centering. 1089104862Sru 1090104862Sru All of these requests cause a break; that is, they always start a new 1091104862Sruline. To start a new line without performing any other action, use 1092104862Sru`br'. 1093104862Sru 1094104862Sru 1095104862SruFile: groff, Node: Basics-Footnotes, Up: Basics 1096104862Sru 1097104862Sru (1) This section is derived from `Writing Papers with nroff using 1098104862Sru-me' by Eric P. Allman. 1099104862Sru 1100104862Sru (2) If you need finer granularity of the vertical space, use the 1101104862Sru`pvs' request (*note Changing Type Sizes::). 1102104862Sru 1103104862Sru 1104104862SruFile: groff, Node: Common Features, Prev: Basics, Up: Tutorial for Macro Users 1105104862Sru 1106151497Sru3.2 Common Features 1107151497Sru=================== 1108104862Sru 1109151497Sru`gtroff' provides very low-level operations for formatting a document. 1110151497SruThere are many common routine operations which are done in all 1111151497Srudocuments. These common operations are written into "macros" and 1112104862Srucollected into a "macro package". 1113104862Sru 1114104862Sru All macro packages provide certain common capabilities which fall 1115104862Sruinto the following categories. 1116104862Sru 1117104862Sru* Menu: 1118104862Sru 1119104862Sru* Paragraphs:: 1120104862Sru* Sections and Chapters:: 1121104862Sru* Headers and Footers:: 1122104862Sru* Page Layout Adjustment:: 1123104862Sru* Displays:: 1124104862Sru* Footnotes and Annotations:: 1125104862Sru* Table of Contents:: 1126104862Sru* Indices:: 1127104862Sru* Paper Formats:: 1128104862Sru* Multiple Columns:: 1129104862Sru* Font and Size Changes:: 1130104862Sru* Predefined Strings:: 1131104862Sru* Preprocessor Support:: 1132104862Sru* Configuration and Customization:: 1133104862Sru 1134104862Sru 1135104862SruFile: groff, Node: Paragraphs, Next: Sections and Chapters, Prev: Common Features, Up: Common Features 1136104862Sru 1137151497Sru3.2.1 Paragraphs 1138151497Sru---------------- 1139104862Sru 1140151497SruOne of the most common and most used capability is starting a 1141104862Sruparagraph. There are a number of different types of paragraphs, any of 1142104862Sruwhich can be initiated with macros supplied by the macro package. 1143104862SruNormally, paragraphs start with a blank line and the first line 1144104862Sruindented, like the text in this manual. There are also block style 1145104862Sruparagraphs, which omit the indentation: 1146104862Sru 1147104862Sru 1148104862Sru Some men look at constitutions with sanctimonious 1149104862Sru reverence, and deem them like the ark of the covenant, too 1150104862Sru sacred to be touched. 1151104862Sru 1152104862SruAnd there are also indented paragraphs which begin with a tag or label 1153104862Sruat the margin and the remaining text indented. 1154104862Sru 1155104862Sru 1156104862Sru one This is the first paragraph. Notice how the first 1157104862Sru line of the resulting paragraph lines up with the 1158104862Sru other lines in the paragraph. 1159104862Sru 1160104862Sru 1161104862Sru longlabel 1162104862Sru This paragraph had a long label. The first 1163104862Sru character of text on the first line does not line up 1164104862Sru with the text on second and subsequent lines, 1165104862Sru although they line up with each other. 1166104862Sru 1167104862Sru A variation of this is a bulleted list. 1168104862Sru 1169104862Sru 1170104862Sru . Bulleted lists start with a bullet. It is possible 1171104862Sru to use other glyphs instead of the bullet. In nroff 1172104862Sru mode using the ASCII character set for output, a dot 1173104862Sru is used instead of a real bullet. 1174104862Sru 1175104862Sru 1176104862SruFile: groff, Node: Sections and Chapters, Next: Headers and Footers, Prev: Paragraphs, Up: Common Features 1177104862Sru 1178151497Sru3.2.2 Sections and Chapters 1179151497Sru--------------------------- 1180104862Sru 1181151497SruMost macro packages supply some form of section headers. The simplest 1182151497Srukind is simply the heading on a line by itself in bold type. Others 1183151497Srusupply automatically numbered section heading or different heading 1184151497Srustyles at different levels. Some, more sophisticated, macro packages 1185151497Srusupply macros for starting chapters and appendices. 1186104862Sru 1187104862Sru 1188104862SruFile: groff, Node: Headers and Footers, Next: Page Layout Adjustment, Prev: Sections and Chapters, Up: Common Features 1189104862Sru 1190151497Sru3.2.3 Headers and Footers 1191151497Sru------------------------- 1192104862Sru 1193151497SruEvery macro package gives some way to manipulate the "headers" and 1194104862Sru"footers" (also called "titles") on each page. This is text put at the 1195104862Srutop and bottom of each page, respectively, which contain data like the 1196104862Srucurrent page number, the current chapter title, and so on. Its 1197104862Sruappearance is not affected by the running text. Some packages allow 1198104862Srufor different ones on the even and odd pages (for material printed in a 1199104862Srubook form). 1200104862Sru 1201104862Sru The titles are called "three-part titles", that is, there is a 1202104862Sruleft-justified part, a centered part, and a right-justified part. An 1203104862Sruautomatically generated page number may be put in any of these fields 1204104862Sruwith the `%' character (see *Note Page Layout::, for more details). 1205104862Sru 1206104862Sru 1207104862SruFile: groff, Node: Page Layout Adjustment, Next: Displays, Prev: Headers and Footers, Up: Common Features 1208104862Sru 1209151497Sru3.2.4 Page Layout 1210151497Sru----------------- 1211104862Sru 1212151497SruMost macro packages let the user specify top and bottom margins and 1213104862Sruother details about the appearance of the printed pages. 1214104862Sru 1215104862Sru 1216104862SruFile: groff, Node: Displays, Next: Footnotes and Annotations, Prev: Page Layout Adjustment, Up: Common Features 1217104862Sru 1218151497Sru3.2.5 Displays 1219151497Sru-------------- 1220104862Sru 1221151497Sru"Displays" are sections of text to be set off from the body of the 1222104862Srupaper. Major quotes, tables, and figures are types of displays, as are 1223104862Sruall the examples used in this document. 1224104862Sru 1225104862Sru "Major quotes" are quotes which are several lines long, and hence 1226104862Sruare set in from the rest of the text without quote marks around them. 1227104862Sru 1228104862Sru A "list" is an indented, single-spaced, unfilled display. Lists 1229104862Srushould be used when the material to be printed should not be filled and 1230104862Srujustified like normal text, such as columns of figures or the examples 1231104862Sruused in this paper. 1232104862Sru 1233104862Sru A "keep" is a display of lines which are kept on a single page if 1234104862Srupossible. An example for a keep might be a diagram. Keeps differ from 1235104862Srulists in that lists may be broken over a page boundary whereas keeps are 1236104862Srunot. 1237104862Sru 1238104862Sru "Floating keeps" move relative to the text. Hence, they are good for 1239104862Sruthings which are referred to by name, such as "See figure 3". A 1240104862Srufloating keep appears at the bottom of the current page if it fits; 1241104862Sruotherwise, it appears at the top of the next page. Meanwhile, the 1242104862Srusurrounding text `flows' around the keep, thus leaving no blank areas. 1243104862Sru 1244104862Sru 1245104862SruFile: groff, Node: Footnotes and Annotations, Next: Table of Contents, Prev: Displays, Up: Common Features 1246104862Sru 1247151497Sru3.2.6 Footnotes and Annotations 1248151497Sru------------------------------- 1249104862Sru 1250151497SruThere are a number of requests to save text for later printing. 1251104862Sru 1252104862Sru "Footnotes" are printed at the bottom of the current page. 1253104862Sru 1254104862Sru "Delayed text" is very similar to a footnote except that it is 1255104862Sruprinted when called for explicitly. This allows a list of references to 1256104862Sruappear (for example) at the end of each chapter, as is the convention in 1257104862Srusome disciplines. 1258104862Sru 1259104862Sru Most macro packages which supply this functionality also supply a 1260104862Srumeans of automatically numbering either type of annotation. 1261104862Sru 1262104862Sru 1263104862SruFile: groff, Node: Table of Contents, Next: Indices, Prev: Footnotes and Annotations, Up: Common Features 1264104862Sru 1265151497Sru3.2.7 Table of Contents 1266151497Sru----------------------- 1267104862Sru 1268151497Sru"Tables of contents" are a type of delayed text having a tag (usually 1269151497Sruthe page number) attached to each entry after a row of dots. The table 1270151497Sruaccumulates throughout the paper until printed, usually after the paper 1271151497Sruhas ended. Many macro packages provide the ability to have several 1272151497Srutables of contents (e.g. a standard table of contents, a list of 1273151497Srutables, etc). 1274104862Sru 1275104862Sru 1276104862SruFile: groff, Node: Indices, Next: Paper Formats, Prev: Table of Contents, Up: Common Features 1277104862Sru 1278151497Sru3.2.8 Indices 1279151497Sru------------- 1280104862Sru 1281151497SruWhile some macro packages use the term "index", none actually provide 1282151497Sruthat functionality. The facilities they call indices are actually more 1283151497Sruappropriate for tables of contents. 1284104862Sru 1285104862Sru To produce a real index in a document, external tools like the 1286104862Sru`makeindex' program are necessary. 1287104862Sru 1288104862Sru 1289104862SruFile: groff, Node: Paper Formats, Next: Multiple Columns, Prev: Indices, Up: Common Features 1290104862Sru 1291151497Sru3.2.9 Paper Formats 1292151497Sru------------------- 1293104862Sru 1294151497SruSome macro packages provide stock formats for various kinds of 1295104862Srudocuments. Many of them provide a common format for the title and 1296104862Sruopening pages of a technical paper. The `mm' macros in particular 1297104862Sruprovide formats for letters and memoranda. 1298104862Sru 1299104862Sru 1300104862SruFile: groff, Node: Multiple Columns, Next: Font and Size Changes, Prev: Paper Formats, Up: Common Features 1301104862Sru 1302151497Sru3.2.10 Multiple Columns 1303151497Sru----------------------- 1304104862Sru 1305151497SruSome macro packages (but not `man') provide the ability to have two or 1306151497Srumore columns on a page. 1307104862Sru 1308104862Sru 1309104862SruFile: groff, Node: Font and Size Changes, Next: Predefined Strings, Prev: Multiple Columns, Up: Common Features 1310104862Sru 1311151497Sru3.2.11 Font and Size Changes 1312151497Sru---------------------------- 1313104862Sru 1314151497SruThe built-in font and size functions are not always intuitive, so all 1315104862Srumacro packages provide macros to make these operations simpler. 1316104862Sru 1317104862Sru 1318104862SruFile: groff, Node: Predefined Strings, Next: Preprocessor Support, Prev: Font and Size Changes, Up: Common Features 1319104862Sru 1320151497Sru3.2.12 Predefined Strings 1321151497Sru------------------------- 1322104862Sru 1323151497SruMost macro packages provide various predefined strings for a variety of 1324151497Sruuses; examples are sub- and superscripts, printable dates, quotes and 1325104862Sruvarious special characters. 1326104862Sru 1327104862Sru 1328104862SruFile: groff, Node: Preprocessor Support, Next: Configuration and Customization, Prev: Predefined Strings, Up: Common Features 1329104862Sru 1330151497Sru3.2.13 Preprocessor Support 1331151497Sru--------------------------- 1332104862Sru 1333151497SruAll macro packages provide support for various preprocessors and may 1334104862Sruextend their functionality. 1335104862Sru 1336104862Sru For example, all macro packages mark tables (which are processed with 1337104862Sru`gtbl') by placing them between `TS' and `TE' macros. The `ms' macro 1338104862Srupackage has an option, `.TS H', that prints a caption at the top of a 1339104862Srunew page (when the table is too long to fit on a single page). 1340104862Sru 1341104862Sru 1342104862SruFile: groff, Node: Configuration and Customization, Prev: Preprocessor Support, Up: Common Features 1343104862Sru 1344151497Sru3.2.14 Configuration and Customization 1345151497Sru-------------------------------------- 1346104862Sru 1347151497SruSome macro packages provide means of customizing many of the details of 1348151497Sruhow the package behaves. This ranges from setting the default type size 1349151497Sruto changing the appearance of section headers. 1350104862Sru 1351104862Sru 1352104862SruFile: groff, Node: Macro Packages, Next: gtroff Reference, Prev: Tutorial for Macro Users, Up: Top 1353104862Sru 1354151497Sru4 Macro Packages 1355151497Sru**************** 1356104862Sru 1357151497SruThis chapter documents the main macro packages that come with `groff'. 1358104862Sru 1359114402Sru Different main macro packages can't be used at the same time; for 1360114402Sruexample 1361114402Sru 1362114402Sru 1363114402Sru groff -m man foo.man -m ms bar.doc 1364114402Sru 1365114402Srudoesn't work. Note that option arguments are processed before 1366114402Srunon-option arguments; the above (failing) sample is thus reordered to 1367114402Sru 1368114402Sru 1369114402Sru groff -m man -m ms foo.man bar.doc 1370114402Sru 1371104862Sru* Menu: 1372104862Sru 1373104862Sru* man:: 1374104862Sru* mdoc:: 1375104862Sru* ms:: 1376104862Sru* me:: 1377104862Sru* mm:: 1378104862Sru 1379104862Sru 1380104862SruFile: groff, Node: man, Next: mdoc, Prev: Macro Packages, Up: Macro Packages 1381104862Sru 1382151497Sru4.1 `man' 1383151497Sru========= 1384104862Sru 1385151497SruThis is the most popular and probably the most important macro package 1386151497Sruof `groff'. It is easy to use, and a vast majority of manual pages are 1387151497Srubased on it. 1388104862Sru 1389104862Sru* Menu: 1390104862Sru 1391104862Sru* Man options:: 1392104862Sru* Man usage:: 1393104862Sru* Man font macros:: 1394104862Sru* Miscellaneous man macros:: 1395104862Sru* Predefined man strings:: 1396104862Sru* Preprocessors in man pages:: 1397114402Sru* Optional man extensions:: 1398104862Sru 1399151497Sru 1400151497SruFile: groff, Node: Man options, Next: Man usage, Prev: man, Up: man 1401151497Sru 1402151497Sru4.1.1 Options 1403151497Sru------------- 1404151497Sru 1405151497SruThe command line format for using the `man' macros with `groff' is: 1406151497Sru 1407151497Sru 1408151497Sru groff -m man [ -rLL=LENGTH ] [ -rLT=LENGTH ] [ -rFT=DIST ] 1409151497Sru [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=FLAGS ] 1410151497Sru [ -rPNNN ] [ -rSXX ] [ -rXNNN ] 1411151497Sru [ -rIN=LENGTH ] [ -rSN=LENGTH ] [ FILES... ] 1412151497Sru 1413151497SruIt is possible to use `-man' instead of `-m man'. 1414151497Sru 1415151497Sru`-rcR=1' 1416151497Sru This option (the default if a TTY output device is used) creates a 1417151497Sru single, very long page instead of multiple pages. Use `-rcR=0' to 1418151497Sru disable it. 1419151497Sru 1420151497Sru`-rC1' 1421151497Sru If more than one manual page is given on the command line, number 1422151497Sru the pages continuously, rather than starting each at 1. 1423151497Sru 1424151497Sru`-rD1' 1425151497Sru Double-sided printing. Footers for even and odd pages are 1426151497Sru formatted differently. 1427151497Sru 1428151497Sru`-rFT=DIST' 1429151497Sru Set the position of the footer text to DIST. If positive, the 1430151497Sru distance is measured relative to the top of the page, otherwise it 1431151497Sru is relative to the bottom. The default is -0.5i. 1432151497Sru 1433151497Sru`-rHY=FLAGS' 1434151497Sru Set hyphenation flags. Possible values are 1 to hyphenate without 1435151497Sru restrictions, 2 to not hyphenate the last word on a page, 4 to 1436151497Sru not hyphenate the last two characters of a word, and 8 to not 1437151497Sru hyphenate the first two characters of a word. These values are 1438151497Sru additive; the default is 14. 1439151497Sru 1440151497Sru`-rIN=LENGTH' 1441151497Sru Set the body text indentation to LENGTH. If not specified, the 1442151497Sru indentation defaults to 7n (7 characters) in nroff mode and 7.2n 1443151497Sru otherwise. For nroff, this value should always be an integer 1444151497Sru multiple of unit `n' to get consistent indentation. 1445151497Sru 1446151497Sru`-rLL=LENGTH' 1447151497Sru Set line length to LENGTH. If not specified, the line length is 1448151497Sru set to respect any value set by a prior `ll' request (which _must_ 1449151497Sru be in effect when the `TH' macro is invoked), if this differs from 1450151497Sru the built-in default for the formatter; otherwise it defaults to 1451151497Sru 78n in nroff mode (this is 78 characters per line) and 6.5i in 1452151497Sru troff mode.(1) (*note Man options-Footnote-1::) 1453151497Sru 1454151497Sru`-rLT=LENGTH' 1455151497Sru Set title length to LENGTH. If not specified, the title length 1456151497Sru defaults to the line length. 1457151497Sru 1458151497Sru`-rPNNN' 1459151497Sru Page numbering starts with NNN rather than with 1. 1460151497Sru 1461151497Sru`-rSXX' 1462151497Sru Use XX (which can be 10, 11, or 12pt) as the base document font 1463151497Sru size instead of the default value of 10pt. 1464151497Sru 1465151497Sru`-rSN=LENGTH' 1466151497Sru Set the indentation for sub-subheadings to LENGTH. If not 1467151497Sru specified, the indentation defaults to 3n. 1468151497Sru 1469151497Sru`-rXNNN' 1470151497Sru After page NNN, number pages as NNNa, NNNb, NNNc, etc. For 1471151497Sru example, the option `-rX2' produces the following page numbers: 1, 1472151497Sru 2, 2a, 2b, 2c, etc. 1473151497Sru 1474151497Sru 1475151497SruFile: groff, Node: Man options-Footnotes, Up: Man options 1476151497Sru 1477151497Sru (1) Note that the use of a `.ll LENGTH' request to initialize the 1478151497Sruline length, prior to use of the `TH' macro, is supported for backward 1479151497Srucompatibility with some versions of the `man' program. _Always_ use the 1480151497Sru`-rLL=LENGTH' option, or an equivalent `.nr LL LENGTH' request, in 1481151497Srupreference to such a `.ll LENGTH' request. In particular, note that in 1482151497Srunroff mode, the request `.ll 65n', (with any LENGTH expression which 1483151497Sruevaluates equal to 65n, i.e., the formatter's default line length in 1484151497Srunroff mode), will _not_ set the line length to 65n (it will be adjusted 1485151497Sruto the `man' macro package's default setting of 78n), whereas the use 1486151497Sruof the `-rLL=65n' option, or the `.nr LL 65n' request _will_ establish 1487151497Srua line length of 65n. 1488151497Sru 1489151497Sru 1490151497SruFile: groff, Node: Man usage, Next: Man font macros, Prev: Man options, Up: man 1491151497Sru 1492151497Sru4.1.2 Usage 1493151497Sru----------- 1494151497Sru 1495151497SruThis section describes the available macros for manual pages. For 1496151497Srufurther customization, put additional macros and requests into the file 1497151497Sru`man.local' which is loaded immediately after the `man' package. 1498151497Sru 1499151497Sru -- Macro: .TH title section [extra1 [extra2 [extra3]]] 1500151497Sru Set the title of the man page to TITLE and the section to SECTION, 1501151497Sru which must have a value between 1 and 8. The value of SECTION may 1502151497Sru also have a string appended, e.g. `.pm', to indicate a specific 1503151497Sru subsection of the man pages. 1504151497Sru 1505151497Sru Both TITLE and SECTION are positioned at the left and right in the 1506151497Sru header line (with SECTION in parentheses immediately appended to 1507151497Sru TITLE. EXTRA1 is positioned in the middle of the footer line. 1508151497Sru EXTRA2 is positioned at the left in the footer line (or at the 1509151497Sru left on even pages and at the right on odd pages if double-sided 1510151497Sru printing is active). EXTRA3 is centered in the header line. 1511151497Sru 1512151497Sru For HTML output, headers and footers are completely suppressed. 1513151497Sru 1514151497Sru Additionally, this macro starts a new page; the new line number 1515151497Sru is 1 again (except if the `-rC1' option is given on the command 1516151497Sru line) - this feature is intended only for formatting multiple man 1517151497Sru pages; a single man page should contain exactly one `TH' macro at 1518151497Sru the beginning of the file. 1519151497Sru 1520151497Sru -- Macro: .SH [heading] 1521151497Sru Set up an unnumbered section heading sticking out to the left. 1522151497Sru Prints out all the text following `SH' up to the end of the line 1523151497Sru (or the text in the next line if there is no argument to `SH') in 1524151497Sru bold face (or the font specified by the string `HF'), one size 1525151497Sru larger than the base document size. Additionally, the left margin 1526151497Sru and the indentation for the following text is reset to its default 1527151497Sru value. 1528151497Sru 1529151497Sru -- Macro: .SS [heading] 1530151497Sru Set up an unnumbered (sub)section heading. Prints out all the text 1531151497Sru following `SS' up to the end of the line (or the text in the next 1532151497Sru line if there is no argument to `SS') in bold face (or the font 1533151497Sru specified by the string `HF'), at the same size as the base 1534151497Sru document size. Additionally, the left margin and the indentation 1535151497Sru for the following text is reset to its default value. 1536151497Sru 1537151497Sru -- Macro: .TP [nnn] 1538151497Sru Set up an indented paragraph with label. The indentation is set to 1539151497Sru NNN if that argument is supplied (the default unit is `n' if 1540151497Sru omitted), otherwise it is set to the previous indentation value 1541151497Sru specified with `TP', `IP', or `HP' (or to the default value if 1542151497Sru none of them have been used yet). 1543151497Sru 1544151497Sru The first line of text following this macro is interpreted as a 1545151497Sru string to be printed flush-left, as it is appropriate for a label. 1546151497Sru It is not interpreted as part of a paragraph, so there is no 1547151497Sru attempt to fill the first line with text from the following input 1548151497Sru lines. Nevertheless, if the label is not as wide as the 1549151497Sru indentation the paragraph starts at the same line (but indented), 1550151497Sru continuing on the following lines. If the label is wider than the 1551151497Sru indentation the descriptive part of the paragraph begins on the 1552151497Sru line following the label, entirely indented. Note that neither 1553151497Sru font shape nor font size of the label is set to a default value; 1554151497Sru on the other hand, the rest of the text has default font settings. 1555151497Sru 1556151497Sru -- Macro: .LP 1557151497Sru -- Macro: .PP 1558151497Sru -- Macro: .P 1559151497Sru These macros are mutual aliases. Any of them causes a line break 1560151497Sru at the current position, followed by a vertical space downwards by 1561151497Sru the amount specified by the `PD' macro. The font size and shape 1562151497Sru are reset to the default value (10pt roman if no `-rS' option is 1563151497Sru given on the command line). Finally, the current left margin and 1564151497Sru the indentation is restored. 1565151497Sru 1566151497Sru -- Macro: .IP [designator [nnn]] 1567151497Sru Set up an indented paragraph, using DESIGNATOR as a tag to mark 1568151497Sru its beginning. The indentation is set to NNN if that argument is 1569151497Sru supplied (default unit is `n'), otherwise it is set to the 1570151497Sru previous indentation value specified with `TP', `IP', or `HP' (or 1571151497Sru the default value if none of them have been used yet). Font size 1572151497Sru and face of the paragraph (but not the designator) are reset to 1573151497Sru their default values. 1574151497Sru 1575151497Sru To start an indented paragraph with a particular indentation but 1576151497Sru without a designator, use `""' (two double quotes) as the first 1577151497Sru argument of `IP'. 1578151497Sru 1579151497Sru For example, to start a paragraph with bullets as the designator 1580151497Sru and 4 en indentation, write 1581151497Sru 1582151497Sru 1583151497Sru .IP \(bu 4 1584151497Sru 1585151497Sru 1586151497Sru -- Macro: .HP [nnn] 1587151497Sru Set up a paragraph with hanging left indentation. The indentation 1588151497Sru is set to NNN if that argument is supplied (default unit is `n'), 1589151497Sru otherwise it is set to the previous indentation value specified 1590151497Sru with `TP', `IP', or `HP' (or the default value if non of them have 1591151497Sru been used yet). Font size and face are reset to their default 1592151497Sru values. 1593151497Sru 1594151497Sru -- Macro: .RS [nnn] 1595151497Sru Move the left margin to the right by the value NNN if specified 1596151497Sru (default unit is `n'); otherwise it is set to the previous 1597151497Sru indentation value specified with `TP', `IP', or `HP' (or to the 1598151497Sru default value if none of them have been used yet). The 1599151497Sru indentation value is then set to the default. 1600151497Sru 1601151497Sru Calls to the `RS' macro can be nested. 1602151497Sru 1603151497Sru -- Macro: .RE [nnn] 1604151497Sru Move the left margin back to level NNN, restoring the previous left 1605151497Sru margin. If no argument is given, it moves one level back. The 1606151497Sru first level (i.e., no call to `RS' yet) has number 1, and each call 1607151497Sru to `RS' increases the level by 1. 1608151497Sru 1609151497Sru To summarize, the following macros cause a line break with the 1610151497Sruinsertion of vertical space (which amount can be changed with the `PD' 1611151497Srumacro): `SH', `SS', `TP', `LP' (`PP', `P'), `IP', and `HP'. 1612151497Sru 1613151497Sru The macros `RS' and `RE' also cause a break but do not insert 1614151497Sruvertical space. 1615151497Sru 1616151497Sru Finally, the macros `SH', `SS', `LP' (`PP', `P'), and `RS' reset the 1617151497Sruindentation to its default value. 1618151497Sru 1619151497Sru 1620151497SruFile: groff, Node: Man font macros, Next: Miscellaneous man macros, Prev: Man usage, Up: man 1621151497Sru 1622151497Sru4.1.3 Macros to set fonts 1623151497Sru------------------------- 1624151497Sru 1625151497SruThe standard font is roman; the default text size is 10 point. If 1626151497Srucommand line option `-rS=N' is given, use Npt as the default text size. 1627151497Sru 1628151497Sru -- Macro: .SM [text] 1629151497Sru Set the text on the same line or the text on the next line in a 1630151497Sru font that is one point size smaller than the default font. 1631151497Sru 1632151497Sru -- Macro: .SB [text] 1633151497Sru Set the text on the same line or the text on the next line in bold 1634151497Sru face font, one point size smaller than the default font. 1635151497Sru 1636151497Sru -- Macro: .BI text 1637151497Sru Set its arguments alternately in bold face and italic, without a 1638151497Sru space between the arguments. Thus, 1639151497Sru 1640151497Sru 1641151497Sru .BI this "word and" that 1642151497Sru 1643151497Sru produces "thisword andthat" with "this" and "that" in bold face, 1644151497Sru and "word and" in italics. 1645151497Sru 1646151497Sru -- Macro: .IB text 1647151497Sru Set its arguments alternately in italic and bold face, without a 1648151497Sru space between the arguments. 1649151497Sru 1650151497Sru -- Macro: .RI text 1651151497Sru Set its arguments alternately in roman and italic, without a space 1652151497Sru between the arguments. 1653151497Sru 1654151497Sru -- Macro: .IR text 1655151497Sru Set its arguments alternately in italic and roman, without a space 1656151497Sru between the arguments. 1657151497Sru 1658151497Sru -- Macro: .BR text 1659151497Sru Set its arguments alternately in bold face and roman, without a 1660151497Sru space between the arguments. 1661151497Sru 1662151497Sru -- Macro: .RB text 1663151497Sru Set its arguments alternately in roman and bold face, without a 1664151497Sru space between the arguments. 1665151497Sru 1666151497Sru -- Macro: .B [text] 1667151497Sru Set TEXT in bold face. If no text is present on the line where 1668151497Sru the macro is called, then the text of the next line appears in bold 1669151497Sru face. 1670151497Sru 1671151497Sru -- Macro: .I [text] 1672151497Sru Set TEXT in italic. If no text is present on the line where the 1673151497Sru macro is called, then the text of the next line appears in italic. 1674151497Sru 1675151497Sru 1676151497SruFile: groff, Node: Miscellaneous man macros, Next: Predefined man strings, Prev: Man font macros, Up: man 1677151497Sru 1678151497Sru4.1.4 Miscellaneous macros 1679151497Sru-------------------------- 1680151497Sru 1681151497SruThe default indentation is 7.2n in troff mode and 7n in nroff mode 1682151497Sruexcept for `grohtml' which ignores indentation. 1683151497Sru 1684151497Sru -- Macro: .DT 1685151497Sru Set tabs every 0.5 inches. Since this macro is always executed 1686151497Sru during a call to the `TH' macro, it makes sense to call it only if 1687151497Sru the tab positions have been changed. 1688151497Sru 1689151497Sru -- Macro: .PD [nnn] 1690151497Sru Adjust the empty space before a new paragraph (or section). The 1691151497Sru optional argument gives the amount of space (default unit is `v'); 1692151497Sru without parameter, the value is reset to its default value (1 line 1693151497Sru in nroff mode, 0.4v otherwise). 1694151497Sru 1695151497Sru This affects the macros `SH', `SS', `TP', `LP' (as well as `PP' 1696151497Sru and `P'), `IP', and `HP'. 1697151497Sru 1698151497Sru The following two macros are included for BSD compatibility. 1699151497Sru 1700151497Sru -- Macro: .AT [system [release]] 1701151497Sru Alter the footer for use with AT&T manpages. This command exists 1702151497Sru only for compatibility; don't use it. The first argument SYSTEM 1703151497Sru can be: 1704151497Sru 1705151497Sru `3' 1706151497Sru 7th Edition (the default) 1707151497Sru 1708151497Sru `4' 1709151497Sru System III 1710151497Sru 1711151497Sru `5' 1712151497Sru System V 1713151497Sru 1714151497Sru An optional second argument RELEASE to `AT' specifies the release 1715151497Sru number (such as "System V Release 3"). 1716151497Sru 1717151497Sru -- Macro: .UC [version] 1718151497Sru Alters the footer for use with BSD manpages. This command exists 1719151497Sru only for compatibility; don't use it. The argument can be: 1720151497Sru 1721151497Sru `3' 1722151497Sru 3rd Berkeley Distribution (the default) 1723151497Sru 1724151497Sru `4' 1725151497Sru 4th Berkeley Distribution 1726151497Sru 1727151497Sru `5' 1728151497Sru 4.2 Berkeley Distribution 1729151497Sru 1730151497Sru `6' 1731151497Sru 4.3 Berkeley Distribution 1732151497Sru 1733151497Sru `7' 1734151497Sru 4.4 Berkeley Distribution 1735151497Sru 1736151497Sru 1737151497SruFile: groff, Node: Predefined man strings, Next: Preprocessors in man pages, Prev: Miscellaneous man macros, Up: man 1738151497Sru 1739151497Sru4.1.5 Predefined strings 1740151497Sru------------------------ 1741151497Sru 1742151497SruThe following strings are defined: 1743151497Sru 1744151497Sru -- String: \*[S] 1745151497Sru Switch back to the default font size. 1746151497Sru 1747151497Sru -- String: \*[HF] 1748151497Sru The typeface used for headings. The default is `B'. 1749151497Sru 1750151497Sru -- String: \*[R] 1751151497Sru The `registered' sign. 1752151497Sru 1753151497Sru -- String: \*[Tm] 1754151497Sru The `trademark' sign. 1755151497Sru 1756151497Sru -- String: \*[lq] 1757151497Sru -- String: \*[rq] 1758151497Sru Left and right quote. This is equal to `\(lq' and `\(rq', 1759151497Sru respectively. 1760151497Sru 1761151497Sru 1762151497SruFile: groff, Node: Preprocessors in man pages, Next: Optional man extensions, Prev: Predefined man strings, Up: man 1763151497Sru 1764151497Sru4.1.6 Preprocessors in `man' pages 1765151497Sru---------------------------------- 1766151497Sru 1767151497SruIf a preprocessor like `gtbl' or `geqn' is needed, it has become common 1768151497Sruusage to make the first line of the man page look like this: 1769151497Sru 1770151497Sru 1771151497Sru '\" WORD 1772151497Sru 1773151497SruNote the single space character after the double quote. WORD consists 1774151497Sruof letters for the needed preprocessors: `e' for `geqn', `r' for 1775151497Sru`grefer', `t' for `gtbl'. Modern implementations of the `man' program 1776151497Sruread this first line and automatically call the right preprocessor(s). 1777151497Sru 1778151497Sru 1779151497SruFile: groff, Node: Optional man extensions, Prev: Preprocessors in man pages, Up: man 1780151497Sru 1781151497Sru4.1.7 Optional `man' extensions 1782151497Sru------------------------------- 1783151497Sru 1784151497SruUse the file `man.local' for local extensions to the `man' macros or 1785151497Srufor style changes. 1786151497Sru 1787151497SruCustom headers and footers 1788151497Sru.......................... 1789151497Sru 1790151497SruIn groff versions 1.18.2 and later, you can specify custom headers and 1791151497Srufooters by redefining the following macros in `man.local'. 1792151497Sru 1793151497Sru -- Macro: .PT 1794151497Sru Control the content of the headers. Normally, the header prints 1795151497Sru the command name and section number on either side, and the 1796151497Sru optional fifth argument to `TH' in the center. 1797151497Sru 1798151497Sru -- Macro: .BT 1799151497Sru Control the content of the footers. Normally, the footer prints 1800151497Sru the page number and the third and fourth arguments to `TH'. 1801151497Sru 1802151497Sru Use the `FT' number register to specify the footer position. The 1803151497Sru default is -0.5i. 1804151497Sru 1805151497SruUltrix-specific man macros 1806151497Sru.......................... 1807151497Sru 1808151497SruThe `groff' source distribution includes a file named `man.ultrix', 1809151497Srucontaining macros compatible with the Ultrix variant of `man'. Copy 1810151497Sruthis file into `man.local' (or use the `mso' request to load it) to 1811151497Sruenable the following macros. 1812151497Sru 1813151497Sru -- Macro: .CT key 1814151497Sru Print `<CTRL/KEY>'. 1815151497Sru 1816151497Sru -- Macro: .CW 1817151497Sru Print subsequent text using the constant width (Courier) typeface. 1818151497Sru 1819151497Sru -- Macro: .Ds 1820151497Sru Begin a non-filled display. 1821151497Sru 1822151497Sru -- Macro: .De 1823151497Sru End a non-filled display started with `Ds'. 1824151497Sru 1825151497Sru -- Macro: .EX [indent] 1826151497Sru Begins a non-filled display using the constant width (Courier) 1827151497Sru typeface. Use the optional INDENT argument to indent the display. 1828151497Sru 1829151497Sru -- Macro: .EE 1830151497Sru End a non-filled display started with `EX'. 1831151497Sru 1832151497Sru -- Macro: .G [text] 1833151497Sru Sets TEXT in Helvetica. If no text is present on the line where 1834151497Sru the macro is called, then the text of the next line appears in 1835151497Sru Helvetica. 1836151497Sru 1837151497Sru -- Macro: .GL [text] 1838151497Sru Sets TEXT in Helvetica Oblique. If no text is present on the line 1839151497Sru where the macro is called, then the text of the next line appears 1840151497Sru in Helvetica Oblique. 1841151497Sru 1842151497Sru -- Macro: .HB [text] 1843151497Sru Sets TEXT in Helvetica Bold. If no text is present on the line 1844151497Sru where the macro is called, then all text up to the next `HB' 1845151497Sru appears in Helvetica Bold. 1846151497Sru 1847151497Sru -- Macro: .TB [text] 1848151497Sru Identical to `HB'. 1849151497Sru 1850151497Sru -- Macro: .MS title sect [punct] 1851151497Sru Set a manpage reference in Ultrix format. The TITLE is in Courier 1852151497Sru instead of italic. Optional punctuation follows the section 1853151497Sru number without an intervening space. 1854151497Sru 1855151497Sru -- Macro: .NT [`C'] [title] 1856151497Sru Begin a note. Print the optional title, or the word "Note", 1857151497Sru centered on the page. Text following the macro makes up the body 1858151497Sru of the note, and is indented on both sides. If the first argument 1859151497Sru is `C', the body of the note is printed centered (the second 1860151497Sru argument replaces the word "Note" if specified). 1861151497Sru 1862151497Sru -- Macro: .NE 1863151497Sru End a note begun with `NT'. 1864151497Sru 1865151497Sru -- Macro: .PN path [punct] 1866151497Sru Set the path name in constant width (Courier), followed by 1867151497Sru optional punctuation. 1868151497Sru 1869151497Sru -- Macro: .Pn [punct] path [punct] 1870151497Sru When called with two arguments, identical to `PN'. When called 1871151497Sru with three arguments, set the second argument in constant width 1872151497Sru (Courier), bracketed by the first and third arguments in the 1873151497Sru current font. 1874151497Sru 1875151497Sru -- Macro: .R 1876151497Sru Switch to roman font and turn off any underlining in effect. 1877151497Sru 1878151497Sru -- Macro: .RN 1879151497Sru Print the string `<RETURN>'. 1880151497Sru 1881151497Sru -- Macro: .VS [`4'] 1882151497Sru Start printing a change bar in the margin if the number `4' is 1883151497Sru specified. Otherwise, this macro does nothing. 1884151497Sru 1885151497Sru -- Macro: .VE 1886151497Sru End printing the change bar begun by `VS'. 1887151497Sru 1888151497SruSimple example 1889151497Sru.............. 1890151497Sru 1891151497SruThe following example `man.local' file alters the `SH' macro to add 1892151497Srusome extra vertical space before printing the heading. Headings are 1893151497Sruprinted in Helvetica Bold. 1894151497Sru 1895151497Sru 1896151497Sru .\" Make the heading fonts Helvetica 1897151497Sru .ds HF HB 1898151497Sru . 1899151497Sru .\" Put more whitespace in front of headings. 1900151497Sru .rn SH SH-orig 1901151497Sru .de SH 1902151497Sru . if t .sp (u;\\n[PD]*2) 1903151497Sru . SH-orig \\$* 1904151497Sru .. 1905151497Sru 1906151497Sru 1907151497SruFile: groff, Node: mdoc, Next: ms, Prev: man, Up: Macro Packages 1908151497Sru 1909151497Sru4.2 `mdoc' 1910151497Sru========== 1911151497Sru 1912151497SruSee the `groff_mdoc(7)' man page (type `man groff_mdoc' at the command 1913151497Sruline). 1914151497Sru 1915151497Sru 1916151497SruFile: groff, Node: ms, Next: me, Prev: mdoc, Up: Macro Packages 1917151497Sru 1918151497Sru4.3 `ms' 1919151497Sru======== 1920151497Sru 1921151497SruThe `-ms' macros are suitable for reports, letters, books, user 1922151497Srumanuals, and so forth. The package provides macros for cover pages, 1923151497Srusection headings, paragraphs, lists, footnotes, pagination, and a table 1924151497Sruof contents. 1925151497Sru 1926151497Sru* Menu: 1927151497Sru 1928151497Sru* ms Intro:: 1929151497Sru* General ms Structure:: 1930151497Sru* ms Document Control Registers:: 1931151497Sru* ms Cover Page Macros:: 1932151497Sru* ms Body Text:: 1933151497Sru* ms Page Layout:: 1934151497Sru* Differences from AT&T ms:: 1935151497Sru* Naming Conventions:: 1936151497Sru 1937151497Sru 1938151497SruFile: groff, Node: ms Intro, Next: General ms Structure, Prev: ms, Up: ms 1939151497Sru 1940151497Sru4.3.1 Introduction to `ms' 1941151497Sru-------------------------- 1942151497Sru 1943151497SruThe original `-ms' macros were included with AT&T `troff' as well as 1944151497Sruthe `man' macros. While the `man' package is intended for brief 1945151497Srudocuments that can be read on-line as well as printed, the `ms' macros 1946151497Sruare suitable for longer documents that are meant to be printed rather 1947151497Sruthan read on-line. 1948151497Sru 1949151497Sru The `ms' macro package included with `groff' is a complete, 1950151497Srubottom-up re-implementation. Several macros (specific to AT&T or 1951151497SruBerkeley) are not included, while several new commands are. *Note 1952151497SruDifferences from AT&T ms::, for more information. 1953151497Sru 1954151497Sru 1955151497SruFile: groff, Node: General ms Structure, Next: ms Document Control Registers, Prev: ms Intro, Up: ms 1956151497Sru 1957151497Sru4.3.2 General structure of an `ms' document 1958151497Sru------------------------------------------- 1959151497Sru 1960151497SruThe `ms' macro package expects a certain amount of structure, but not 1961151497Sruas much as packages such as `man' or `mdoc'. 1962151497Sru 1963151497Sru The simplest documents can begin with a paragraph macro (such as 1964151497Sru`LP' or `PP'), and consist of text separated by paragraph macros or 1965151497Srueven blank lines. Longer documents have a structure as follows: 1966151497Sru 1967151497Sru*Document type* 1968151497Sru If you invoke the `RP' (report) macro on the first line of the 1969151497Sru document, `groff' prints the cover page information on its own 1970151497Sru page; otherwise it prints the information on the first page with 1971151497Sru your document text immediately following. Other document formats 1972151497Sru found in AT&T `troff' are specific to AT&T or Berkeley, and are 1973151497Sru not supported in `groff'. 1974151497Sru 1975151497Sru*Format and layout* 1976151497Sru By setting number registers, you can change your document's type 1977151497Sru (font and size), margins, spacing, headers and footers, and 1978151497Sru footnotes. *Note ms Document Control Registers::, for more 1979151497Sru details. 1980151497Sru 1981151497Sru*Cover page* 1982151497Sru A cover page consists of a title, the author's name and 1983151497Sru institution, an abstract, and the date.(1) (*note General ms 1984151497Sru Structure-Footnote-1::) *Note ms Cover Page Macros::, for more 1985151497Sru details. 1986151497Sru 1987151497Sru*Body* 1988151497Sru Following the cover page is your document. You can use the `ms' 1989151497Sru macros to write reports, letters, books, and so forth. The 1990151497Sru package is designed for structured documents, consisting of 1991151497Sru paragraphs interspersed with headings and augmented by lists, 1992151497Sru footnotes, tables, and other common constructs. *Note ms Body 1993151497Sru Text::, for more details. 1994151497Sru 1995151497Sru*Table of contents* 1996151497Sru Longer documents usually include a table of contents, which you can 1997151497Sru invoke by placing the `TC' macro at the end of your document. The 1998151497Sru `ms' macros have minimal indexing facilities, consisting of the 1999151497Sru `IX' macro, which prints an entry on standard error. Printing the 2000151497Sru table of contents at the end is necessary since `groff' is a 2001151497Sru single-pass text formatter, thus it cannot determine the page 2002151497Sru number of each section until that section has actually been set 2003151497Sru and printed. Since `ms' output is intended for hardcopy, you can 2004151497Sru manually relocate the pages containing the table of contents 2005151497Sru between the cover page and the body text after printing. 2006151497Sru 2007151497Sru 2008151497SruFile: groff, Node: General ms Structure-Footnotes, Up: General ms Structure 2009151497Sru 2010151497Sru (1) Actually, only the title is required. 2011151497Sru 2012151497Sru 2013151497SruFile: groff, Node: ms Document Control Registers, Next: ms Cover Page Macros, Prev: General ms Structure, Up: ms 2014151497Sru 2015151497Sru4.3.3 Document control registers 2016151497Sru-------------------------------- 2017151497Sru 2018151497SruThe following is a list of document control number registers. For the 2019151497Srusake of consistency, set registers related to margins at the beginning 2020151497Sruof your document, or just after the `RP' macro. You can set other 2021151497Sruregisters later in your document, but you should keep them together at 2022151497Sruthe beginning to make them easy to find and edit as necessary. 2023151497Sru 2024151497SruMargin Settings 2025151497Sru............... 2026151497Sru 2027151497Sru -- Register: \n[PO] 2028151497Sru Defines the page offset (i.e., the left margin). There is no 2029151497Sru explicit right margin setting; the combination of the `PO' and `LL' 2030151497Sru registers implicitly define the right margin width. 2031151497Sru 2032151497Sru Effective: next page. 2033151497Sru 2034151497Sru Default value: 1i. 2035151497Sru 2036151497Sru -- Register: \n[LL] 2037151497Sru Defines the line length (i.e., the width of the body text). 2038151497Sru 2039151497Sru Effective: next paragraph. 2040151497Sru 2041151497Sru Default: 6i. 2042151497Sru 2043151497Sru -- Register: \n[LT] 2044151497Sru Defines the title length (i.e., the header and footer width). This 2045151497Sru is usually the same as `LL', but not necessarily. 2046151497Sru 2047151497Sru Effective: next paragraph. 2048151497Sru 2049151497Sru Default: 6i. 2050151497Sru 2051151497Sru -- Register: \n[HM] 2052151497Sru Defines the header margin height at the top of the page. 2053151497Sru 2054151497Sru Effective: next page. 2055151497Sru 2056151497Sru Default: 1i. 2057151497Sru 2058151497Sru -- Register: \n[FM] 2059151497Sru Defines the footer margin height at the bottom of the page. 2060151497Sru 2061151497Sru Effective: next page. 2062151497Sru 2063151497Sru Default: 1i. 2064151497Sru 2065151497SruText Settings 2066151497Sru............. 2067151497Sru 2068151497Sru -- Register: \n[PS] 2069151497Sru Defines the point size of the body text. If the value is larger 2070151497Sru than or equal to 1000, divide it by 1000 to get a fractional point 2071151497Sru size. For example, `.nr PS 10250' sets the document's point size 2072151497Sru to 10.25p. 2073151497Sru 2074151497Sru Effective: next paragraph. 2075151497Sru 2076151497Sru Default: 10p. 2077151497Sru 2078151497Sru -- Register: \n[VS] 2079151497Sru Defines the space between lines (line height plus leading). If the 2080151497Sru value is larger than or equal to 1000, divide it by 1000 to get a 2081151497Sru fractional point size. Due to backwards compatibility, `VS' must 2082151497Sru be smaller than 40000 (this is 40.0p). 2083151497Sru 2084151497Sru Effective: next paragraph. 2085151497Sru 2086151497Sru Default: 12p. 2087151497Sru 2088151497Sru -- Register: \n[PSINCR] 2089151497Sru Defines an increment in point size, which will be applied to 2090151497Sru section headings at nesting levels below the value specified in 2091151497Sru `GROWPS'. The value of `PSINCR' should be specified in points, 2092151497Sru with the p scaling factor, and may include a fractional component; 2093151497Sru for example, `.nr PSINCR 1.5p' sets a point size increment of 1.5p. 2094151497Sru 2095151497Sru Effective: next section heading. 2096151497Sru 2097151497Sru Default: 1p. 2098151497Sru 2099151497Sru -- Register: \n[GROWPS] 2100151497Sru Defines the heading level below which the point size increment set 2101151497Sru by `PSINCR' becomes effective. Section headings at and above the 2102151497Sru level specified by `GROWPS' will be printed at the point size set 2103151497Sru by `PS'; for each level below the value of `GROWPS', the point 2104151497Sru size will be increased in steps equal to the value of `PSINCR'. 2105151497Sru Setting `GROWPS' to any value less than 2 disables the incremental 2106151497Sru heading size feature. 2107151497Sru 2108151497Sru Effective: next section heading. 2109151497Sru 2110151497Sru Default: 0. 2111151497Sru 2112151497Sru -- Register: \n[HY] 2113151497Sru Defines the hyphenation level. `HY' sets safely the value of the 2114151497Sru low-level `hy' register. Setting the value of `HY' to 0 is 2115151497Sru equivalent to using the `nh' request. 2116151497Sru 2117151497Sru Effective: next paragraph. 2118151497Sru 2119151497Sru Default: 14. 2120151497Sru 2121151497Sru -- Register: \n[FAM] 2122151497Sru Defines the font family used to typeset the document. 2123151497Sru 2124151497Sru Effective: next paragraph. 2125151497Sru 2126151497Sru Default: as defined in the output device. 2127151497Sru 2128151497SruParagraph Settings 2129151497Sru.................. 2130151497Sru 2131151497Sru -- Register: \n[PI] 2132151497Sru Defines the initial indentation of a (`PP' macro) paragraph. 2133151497Sru 2134151497Sru Effective: next paragraph. 2135151497Sru 2136151497Sru Default: 5n. 2137151497Sru 2138151497Sru -- Register: \n[PD] 2139151497Sru Defines the space between paragraphs. 2140151497Sru 2141151497Sru Effective: next paragraph. 2142151497Sru 2143151497Sru Default: 0.3v. 2144151497Sru 2145151497Sru -- Register: \n[QI] 2146151497Sru Defines the indentation on both sides of a quoted (`QP' macro) 2147151497Sru paragraph. 2148151497Sru 2149151497Sru Effective: next paragraph. 2150151497Sru 2151151497Sru Default: 5n. 2152151497Sru 2153151497Sru -- Register: \n[PORPHANS] 2154151497Sru Defines the minimum number of initial lines of any paragraph which 2155151497Sru should be kept together, to avoid orphan lines at the bottom of a 2156151497Sru page. If a new paragraph is started close to the bottom of a page, 2157151497Sru and there is insufficient space to accommodate `PORPHANS' lines 2158151497Sru before an automatic page break, then the page break will be forced, 2159151497Sru before the start of the paragraph. 2160151497Sru 2161151497Sru Effective: next paragraph. 2162151497Sru 2163151497Sru Default: 1. 2164151497Sru 2165151497Sru -- Register: \n[HORPHANS] 2166151497Sru Defines the minimum number of lines of the following paragraph 2167151497Sru which should be kept together with any section heading introduced 2168151497Sru by the `NH' or `SH' macros. If a section heading is placed close 2169151497Sru to the bottom of a page, and there is insufficient space to 2170151497Sru accommodate both the heading and at least `HORPHANS' lines of the 2171151497Sru following paragraph, before an automatic page break, then the page 2172151497Sru break will be forced before the heading. 2173151497Sru 2174151497Sru Effective: next paragraph. 2175151497Sru 2176151497Sru Default: 1. 2177151497Sru 2178151497SruFootnote Settings 2179151497Sru................. 2180151497Sru 2181151497Sru -- Register: \n[FL] 2182151497Sru Defines the length of a footnote. 2183151497Sru 2184151497Sru Effective: next footnote. 2185151497Sru 2186151497Sru Default: `\n[LL]' * 5 / 6. 2187151497Sru 2188151497Sru -- Register: \n[FI] 2189151497Sru Defines the footnote indentation. 2190151497Sru 2191151497Sru Effective: next footnote. 2192151497Sru 2193151497Sru Default: 2n. 2194151497Sru 2195151497Sru -- Register: \n[FF] 2196151497Sru The footnote format: 2197151497Sru `0' 2198151497Sru Print the footnote number as a superscript; indent the 2199151497Sru footnote (default). 2200151497Sru 2201151497Sru `1' 2202151497Sru Print the number followed by a period (like 1.) and indent the 2203151497Sru footnote. 2204151497Sru 2205151497Sru `2' 2206151497Sru Like 1, without an indentation. 2207151497Sru 2208151497Sru `3' 2209151497Sru Like 1, but print the footnote number as a hanging paragraph. 2210151497Sru 2211151497Sru Effective: next footnote. 2212151497Sru 2213151497Sru Default: 0. 2214151497Sru 2215151497Sru -- Register: \n[FPS] 2216151497Sru Defines the footnote point size. If the value is larger than or 2217151497Sru equal to 1000, divide it by 1000 to get a fractional point size. 2218151497Sru 2219151497Sru Effective: next footnote. 2220151497Sru 2221151497Sru Default: `\n[PS]' - 2. 2222151497Sru 2223151497Sru -- Register: \n[FVS] 2224151497Sru Defines the footnote vertical spacing. If the value is larger 2225151497Sru than or equal to 1000, divide it by 1000 to get a fractional point 2226151497Sru size. 2227151497Sru 2228151497Sru Effective: next footnote. 2229151497Sru 2230151497Sru Default: `\n[FPS]' + 2. 2231151497Sru 2232151497Sru -- Register: \n[FPD] 2233151497Sru Defines the footnote paragraph spacing. 2234151497Sru 2235151497Sru Effective: next footnote. 2236151497Sru 2237151497Sru Default: `\n[PD]' / 2. 2238151497Sru 2239151497SruMiscellaneous Number Registers 2240151497Sru.............................. 2241151497Sru 2242151497Sru -- Register: \n[MINGW] 2243151497Sru Defines the minimum width between columns in a multi-column 2244151497Sru document. 2245151497Sru 2246151497Sru Effective: next page. 2247151497Sru 2248151497Sru Default: 2n. 2249151497Sru 2250151497Sru 2251151497SruFile: groff, Node: ms Cover Page Macros, Next: ms Body Text, Prev: ms Document Control Registers, Up: ms 2252151497Sru 2253151497Sru4.3.4 Cover page macros 2254151497Sru----------------------- 2255151497Sru 2256151497SruUse the following macros to create a cover page for your document in 2257151497Sruthe order shown. 2258151497Sru 2259151497Sru -- Macro: .RP [`no'] 2260151497Sru Specifies the report format for your document. The report format 2261151497Sru creates a separate cover page. The default action (no `RP' macro) 2262151497Sru is to print a subset of the cover page on page 1 of your document. 2263151497Sru 2264151497Sru If you use the word `no' as an optional argument, `groff' prints a 2265151497Sru title page but does not repeat any of the title page information 2266151497Sru (title, author, abstract, etc.) on page 1 of the document. 2267151497Sru 2268151497Sru -- Macro: .P1 2269151497Sru (P-one) Prints the header on page 1. The default is to suppress 2270151497Sru the header. 2271151497Sru 2272151497Sru -- Macro: .DA [...] 2273151497Sru (optional) Prints the current date, or the arguments to the macro 2274151497Sru if any, on the title page (if specified) and in the footers. This 2275151497Sru is the default for `nroff'. 2276151497Sru 2277151497Sru -- Macro: .ND [...] 2278151497Sru (optional) Prints the current date, or the arguments to the macro 2279151497Sru if any, on the title page (if specified) but not in the footers. 2280151497Sru This is the default for `troff'. 2281151497Sru 2282151497Sru -- Macro: .TL 2283151497Sru Specifies the document title. `groff' collects text following the 2284151497Sru `TL' macro into the title, until reaching the author name or 2285151497Sru abstract. 2286151497Sru 2287151497Sru -- Macro: .AU 2288151497Sru Specifies the author's name, which appears on the line (or lines) 2289151497Sru immediately following. You can specify multiple authors as 2290151497Sru follows: 2291151497Sru 2292151497Sru 2293151497Sru .AU 2294151497Sru John Doe 2295151497Sru .AI 2296151497Sru University of West Bumblefuzz 2297151497Sru .AU 2298151497Sru Martha Buck 2299151497Sru .AI 2300151497Sru Monolithic Corporation 2301151497Sru 2302151497Sru ... 2303151497Sru 2304151497Sru 2305151497Sru -- Macro: .AI 2306151497Sru Specifies the author's institution. You can specify multiple 2307151497Sru institutions in the same way that you specify multiple authors. 2308151497Sru 2309151497Sru -- Macro: .AB [`no'] 2310151497Sru Begins the abstract. The default is to print the word ABSTRACT, 2311151497Sru centered and in italics, above the text of the abstract. The word 2312151497Sru `no' as an optional argument suppresses this heading. 2313151497Sru 2314151497Sru -- Macro: .AE 2315151497Sru Ends the abstract. 2316151497Sru 2317151497Sru The following is example mark-up for a title page. 2318151497Sru 2319151497Sru 2320151497Sru .RP 2321151497Sru .TL 2322151497Sru The Inevitability of Code Bloat 2323151497Sru in Commercial and Free Software 2324151497Sru .AU 2325151497Sru J. Random Luser 2326151497Sru .AI 2327151497Sru University of West Bumblefuzz 2328151497Sru .AB 2329151497Sru This report examines the long-term growth 2330151497Sru of the code bases in two large, popular software 2331151497Sru packages; the free Emacs and the commercial 2332151497Sru Microsoft Word. 2333151497Sru While differences appear in the type or order 2334151497Sru of features added, due to the different 2335151497Sru methodologies used, the results are the same 2336151497Sru in the end. 2337151497Sru .PP 2338151497Sru The free software approach is shown to be 2339151497Sru superior in that while free software can 2340151497Sru become as bloated as commercial offerings, 2341151497Sru free software tends to have fewer serious 2342151497Sru bugs and the added features are in line with 2343151497Sru user demand. 2344151497Sru .AE 2345151497Sru 2346151497Sru ... the rest of the paper follows ... 2347151497Sru 2348151497Sru 2349151497SruFile: groff, Node: ms Body Text, Next: ms Page Layout, Prev: ms Cover Page Macros, Up: ms 2350151497Sru 2351151497Sru4.3.5 Body text 2352151497Sru--------------- 2353151497Sru 2354151497SruThis section describes macros used to mark up the body of your 2355151497Srudocument. Examples include paragraphs, sections, and other groups. 2356151497Sru 2357151497Sru* Menu: 2358151497Sru 2359151497Sru* Paragraphs in ms:: 2360151497Sru* Headings in ms:: 2361151497Sru* Highlighting in ms:: 2362151497Sru* Lists in ms:: 2363151497Sru* Indentation values in ms:: 2364151497Sru* Tabstops in ms:: 2365151497Sru* ms Displays and Keeps:: 2366151497Sru* ms Insertions:: 2367151497Sru* Example multi-page table:: 2368151497Sru* ms Footnotes:: 2369151497Sru 2370151497Sru 2371151497SruFile: groff, Node: Paragraphs in ms, Next: Headings in ms, Prev: ms Body Text, Up: ms Body Text 2372151497Sru 2373151497Sru4.3.5.1 Paragraphs 2374151497Sru.................. 2375151497Sru 2376151497SruThe following paragraph types are available. 2377151497Sru 2378151497Sru -- Macro: .PP 2379151497Sru -- Macro: .LP 2380151497Sru Sets a paragraph with an initial indentation. 2381151497Sru 2382151497Sru -- Macro: .QP 2383151497Sru Sets a paragraph that is indented at both left and right margins. 2384151497Sru The effect is identical to the HTML `<BLOCKQUOTE>' element. The 2385151497Sru next paragraph or heading returns margins to normal. 2386151497Sru 2387151497Sru -- Macro: .XP 2388151497Sru Sets a paragraph whose lines are indented, except for the first 2389151497Sru line. This is a Berkeley extension. 2390151497Sru 2391151497Sru The following markup uses all four paragraph macros. 2392151497Sru 2393151497Sru 2394151497Sru .NH 2 2395151497Sru Cases used in the study 2396151497Sru .LP 2397151497Sru The following software and versions were 2398151497Sru considered for this report. 2399151497Sru .PP 2400151497Sru For commercial software, we chose 2401151497Sru .B "Microsoft Word for Windows" , 2402151497Sru starting with version 1.0 through the 2403151497Sru current version (Word 2000). 2404151497Sru .PP 2405151497Sru For free software, we chose 2406151497Sru .B Emacs , 2407151497Sru from its first appearance as a standalone 2408151497Sru editor through the current version (v20). 2409151497Sru See [Bloggs 2002] for details. 2410151497Sru .QP 2411151497Sru Franklin's Law applied to software: 2412151497Sru software expands to outgrow both 2413151497Sru RAM and disk space over time. 2414151497Sru .LP 2415151497Sru Bibliography: 2416151497Sru .XP 2417151497Sru Bloggs, Joseph R., 2418151497Sru .I "Everyone's a Critic" , 2419151497Sru Underground Press, March 2002. 2420151497Sru A definitive work that answers all questions 2421151497Sru and criticisms about the quality and usability of 2422151497Sru free software. 2423151497Sru 2424151497Sru The `PORPHANS' register (*note ms Document Control Registers::) 2425151497Sruoperates in conjunction with each of these macros, to inhibit the 2426151497Sruprinting of orphan lines at the bottom of any page. 2427151497Sru 2428151497Sru 2429151497SruFile: groff, Node: Headings in ms, Next: Highlighting in ms, Prev: Paragraphs in ms, Up: ms Body Text 2430151497Sru 2431151497Sru4.3.5.2 Headings 2432151497Sru................ 2433151497Sru 2434151497SruUse headings to create a hierarchical structure for your document. The 2435151497Sru`ms' macros print headings in *bold*, using the same font family and 2436151497Srupoint size as the body text. 2437151497Sru 2438151497Sru The following describes the heading macros: 2439151497Sru 2440151497Sru -- Macro: .NH curr-level 2441151497Sru -- Macro: .NH S level0 ... 2442151497Sru Numbered heading. The argument is either a numeric argument to 2443151497Sru indicate the level of the heading, or the letter `S' followed by 2444151497Sru numeric arguments to set the heading level explicitly. 2445151497Sru 2446151497Sru If you specify heading levels out of sequence, such as invoking 2447151497Sru `.NH 3' after `.NH 1', `groff' prints a warning on standard error. 2448151497Sru 2449151497Sru -- String: \*[SN] 2450151497Sru -- String: \*[SN-DOT] 2451151497Sru -- String: \*[SN-NO-DOT] 2452151497Sru After invocation of `NH', the assigned section number is made 2453151497Sru available in the strings `SN-DOT' (exactly as it appears in the 2454151497Sru printed section heading) and `SN-NO-DOT' (with the final period 2455151497Sru omitted). The string `SN' is also defined, as an alias for 2456151497Sru `SN-DOT'; if preferred, you may redefine it as an alias for 2457151497Sru `SN-NO-DOT', by including the initialization 2458151497Sru 2459151497Sru 2460151497Sru .ds SN-NO-DOT 2461151497Sru .als SN SN-NO-DOT 2462151497Sru 2463151497Sru *before* your first use of `NH', or simply 2464151497Sru 2465151497Sru 2466151497Sru .als SN SN-NO-DOT 2467151497Sru 2468151497Sru *after* your first use of `NH'. 2469151497Sru 2470151497Sru -- Macro: .SH [match-level] 2471151497Sru Unnumbered subheading. 2472151497Sru 2473151497Sru The optional MATCH-LEVEL argument is a GNU extension. It is a 2474151497Sru number indicating the level of the heading, in a manner analogous 2475151497Sru to the CURR-LEVEL argument to `.NH'. Its purpose is to match the 2476151497Sru point size, at which the heading is printed, to the size of a 2477151497Sru numbered heading at the same level, when the `GROWPS' and `PSINCR' 2478151497Sru heading size adjustment mechanism is in effect. *Note ms Document 2479151497Sru Control Registers::. 2480151497Sru 2481151497Sru The `HORPHANS' register (*note ms Document Control Registers::) 2482151497Sruoperates in conjunction with the `NH' and `SH' macros, to inhibit the 2483151497Sruprinting of orphaned section headings at the bottom of any page. 2484151497Sru 2485151497Sru 2486151497SruFile: groff, Node: Highlighting in ms, Next: Lists in ms, Prev: Headings in ms, Up: ms Body Text 2487151497Sru 2488151497Sru4.3.5.3 Highlighting 2489151497Sru.................... 2490151497Sru 2491151497SruThe `ms' macros provide a variety of methods to highlight or emphasize 2492151497Srutext: 2493151497Sru 2494151497Sru -- Macro: .B [txt [post [pre]]] 2495151497Sru Sets its first argument in *bold type*. If you specify a second 2496151497Sru argument, `groff' prints it in the previous font after the bold 2497151497Sru text, with no intervening space (this allows you to set 2498151497Sru punctuation after the highlighted text without highlighting the 2499151497Sru punctuation). Similarly, it prints the third argument (if any) in 2500151497Sru the previous font *before* the first argument. For example, 2501151497Sru 2502151497Sru 2503151497Sru .B foo ) ( 2504151497Sru 2505151497Sru prints (*foo*). 2506151497Sru 2507151497Sru If you give this macro no arguments, `groff' prints all text 2508151497Sru following in bold until the next highlighting, paragraph, or 2509151497Sru heading macro. 2510151497Sru 2511151497Sru -- Macro: .R [txt [post [pre]]] 2512151497Sru Sets its first argument in roman (or regular) type. It operates 2513151497Sru similarly to the `B' macro otherwise. 2514151497Sru 2515151497Sru -- Macro: .I [txt [post [pre]]] 2516151497Sru Sets its first argument in _italic type_. It operates similarly 2517151497Sru to the `B' macro otherwise. 2518151497Sru 2519151497Sru -- Macro: .CW [txt [post [pre]]] 2520151497Sru Sets its first argument in a `constant width face'. It operates 2521151497Sru similarly to the `B' macro otherwise. 2522151497Sru 2523151497Sru -- Macro: .BI [txt [post [pre]]] 2524151497Sru Sets its first argument in bold italic type. It operates 2525151497Sru similarly to the `B' macro otherwise. 2526151497Sru 2527151497Sru -- Macro: .BX [txt] 2528151497Sru Prints its argument and draws a box around it. If you want to box 2529151497Sru a string that contains spaces, use a digit-width space (`\0'). 2530151497Sru 2531151497Sru -- Macro: .UL [txt [post]] 2532151497Sru Prints its first argument with an underline. If you specify a 2533151497Sru second argument, `groff' prints it in the previous font after the 2534151497Sru underlined text, with no intervening space. 2535151497Sru 2536151497Sru -- Macro: .LG 2537151497Sru Prints all text following in larger type (two points larger than 2538151497Sru the current point size) until the next font size, highlighting, 2539151497Sru paragraph, or heading macro. You can specify this macro multiple 2540151497Sru times to enlarge the point size as needed. 2541151497Sru 2542151497Sru -- Macro: .SM 2543151497Sru Prints all text following in smaller type (two points smaller than 2544151497Sru the current point size) until the next type size, highlighting, 2545151497Sru paragraph, or heading macro. You can specify this macro multiple 2546151497Sru times to reduce the point size as needed. 2547151497Sru 2548151497Sru -- Macro: .NL 2549151497Sru Prints all text following in the normal point size (that is, the 2550151497Sru value of the `PS' register). 2551151497Sru 2552151497Sru -- String: \*[{] 2553151497Sru -- String: \*[}] 2554151497Sru Text enclosed with `\*{' and `\*}' is printed as a superscript. 2555151497Sru 2556151497Sru 2557151497SruFile: groff, Node: Lists in ms, Next: Indentation values in ms, Prev: Highlighting in ms, Up: ms Body Text 2558151497Sru 2559151497Sru4.3.5.4 Lists 2560151497Sru............. 2561151497Sru 2562151497SruThe `IP' macro handles duties for all lists. 2563151497Sru 2564151497Sru -- Macro: .IP [marker [width]] 2565151497Sru The MARKER is usually a bullet glyph (`\[bu]') for unordered 2566151497Sru lists, a number (or auto-incrementing number register) for 2567151497Sru numbered lists, or a word or phrase for indented (glossary-style) 2568151497Sru lists. 2569151497Sru 2570151497Sru The WIDTH specifies the indentation for the body of each list 2571151497Sru item; its default unit is `n'. Once specified, the indentation 2572151497Sru remains the same for all list items in the document until specified 2573151497Sru again. 2574151497Sru 2575151497Sru The `PORPHANS' register (*note ms Document Control Registers::) 2576151497Sru operates in conjunction with the `IP' macro, to inhibit the 2577151497Sru printing of orphaned list markers at the bottom of any page. 2578151497Sru 2579151497Sru The following is an example of a bulleted list. 2580151497Sru 2581151497Sru 2582151497Sru A bulleted list: 2583151497Sru .IP \[bu] 2 2584151497Sru lawyers 2585151497Sru .IP \[bu] 2586151497Sru guns 2587151497Sru .IP \[bu] 2588151497Sru money 2589151497Sru 2590151497Sru Produces: 2591151497Sru 2592151497Sru 2593151497Sru A bulleted list: 2594151497Sru 2595151497Sru o lawyers 2596151497Sru 2597151497Sru o guns 2598151497Sru 2599151497Sru o money 2600151497Sru 2601151497Sru The following is an example of a numbered list. 2602151497Sru 2603151497Sru 2604151497Sru .nr step 1 1 2605151497Sru A numbered list: 2606151497Sru .IP \n[step] 3 2607151497Sru lawyers 2608151497Sru .IP \n+[step] 2609151497Sru guns 2610151497Sru .IP \n+[step] 2611151497Sru money 2612151497Sru 2613151497Sru Produces: 2614151497Sru 2615151497Sru 2616151497Sru A numbered list: 2617151497Sru 2618151497Sru 1. lawyers 2619151497Sru 2620151497Sru 2. guns 2621151497Sru 2622151497Sru 3. money 2623151497Sru 2624151497Sru Note the use of the auto-incrementing number register in this 2625151497Sruexample. 2626151497Sru 2627151497Sru The following is an example of a glossary-style list. 2628151497Sru 2629151497Sru 2630151497Sru A glossary-style list: 2631151497Sru .IP lawyers 0.4i 2632151497Sru Two or more attorneys. 2633151497Sru .IP guns 2634151497Sru Firearms, preferably 2635151497Sru large-caliber. 2636151497Sru .IP money 2637151497Sru Gotta pay for those 2638151497Sru lawyers and guns! 2639151497Sru 2640151497Sru Produces: 2641151497Sru 2642151497Sru 2643151497Sru A glossary-style list: 2644151497Sru 2645151497Sru lawyers 2646151497Sru Two or more attorneys. 2647151497Sru 2648151497Sru guns Firearms, preferably large-caliber. 2649151497Sru 2650151497Sru money 2651151497Sru Gotta pay for those lawyers and guns! 2652151497Sru 2653151497Sru In the last example, the `IP' macro places the definition on the 2654151497Srusame line as the term if it has enough space; otherwise, it breaks to 2655151497Sruthe next line and starts the definition below the term. This may or 2656151497Srumay not be the effect you want, especially if some of the definitions 2657151497Srubreak and some do not. The following examples show two possible ways 2658151497Sruto force a break. 2659151497Sru 2660151497Sru The first workaround uses the `br' request to force a break after 2661151497Sruprinting the term or label. 2662151497Sru 2663151497Sru 2664151497Sru A glossary-style list: 2665151497Sru .IP lawyers 0.4i 2666151497Sru Two or more attorneys. 2667151497Sru .IP guns 2668151497Sru .br 2669151497Sru Firearms, preferably large-caliber. 2670151497Sru .IP money 2671151497Sru Gotta pay for those lawyers and guns! 2672151497Sru 2673151497Sru The second workaround uses the `\p' escape to force the break. Note 2674151497Sruthe space following the escape; this is important. If you omit the 2675151497Sruspace, `groff' prints the first word on the same line as the term or 2676151497Srulabel (if it fits) *then* breaks the line. 2677151497Sru 2678151497Sru 2679151497Sru A glossary-style list: 2680151497Sru .IP lawyers 0.4i 2681151497Sru Two or more attorneys. 2682151497Sru .IP guns 2683151497Sru \p Firearms, preferably large-caliber. 2684151497Sru .IP money 2685151497Sru Gotta pay for those lawyers and guns! 2686151497Sru 2687151497Sru To set nested lists, use the `RS' and `RE' macros. *Note 2688151497SruIndentation values in ms::, for more information. 2689151497Sru 2690151497Sru For example: 2691151497Sru 2692151497Sru 2693151497Sru .IP \[bu] 2 2694151497Sru Lawyers: 2695151497Sru .RS 2696151497Sru .IP \[bu] 2697151497Sru Dewey, 2698151497Sru .IP \[bu] 2699151497Sru Cheatham, 2700151497Sru .IP \[bu] 2701151497Sru and Howe. 2702151497Sru .RE 2703151497Sru .IP \[bu] 2704151497Sru Guns 2705151497Sru 2706151497Sru Produces: 2707151497Sru 2708151497Sru 2709151497Sru o Lawyers: 2710151497Sru 2711151497Sru o Dewey, 2712151497Sru 2713151497Sru o Cheatham, 2714151497Sru 2715151497Sru o and Howe. 2716151497Sru 2717151497Sru o Guns 2718151497Sru 2719151497Sru 2720151497SruFile: groff, Node: Indentation values in ms, Next: Tabstops in ms, Prev: Lists in ms, Up: ms Body Text 2721151497Sru 2722151497Sru4.3.5.5 Indentation values 2723151497Sru.......................... 2724151497Sru 2725151497SruIn many situations, you may need to indentation a section of text while 2726151497Srustill wrapping and filling. *Note Lists in ms::, for an example of 2727151497Srunested lists. 2728151497Sru 2729151497Sru -- Macro: .RS 2730151497Sru -- Macro: .RE 2731151497Sru These macros begin and end an indented section. The `PI' register 2732151497Sru controls the amount of indentation, allowing the indented text to 2733151497Sru line up under hanging and indented paragraphs. 2734151497Sru 2735151497Sru *Note ms Displays and Keeps::, for macros to indentation and turn off 2736151497Srufilling. 2737151497Sru 2738151497Sru 2739151497SruFile: groff, Node: Tabstops in ms, Next: ms Displays and Keeps, Prev: Indentation values in ms, Up: ms Body Text 2740151497Sru 2741151497Sru4.3.5.6 Tab Stops 2742151497Sru................. 2743151497Sru 2744151497SruUse the `ta' request to define tab stops as needed. *Note Tabs and 2745151497SruFields::. 2746151497Sru 2747151497Sru -- Macro: .TA 2748151497Sru Use this macro to reset the tab stops to the default for `ms' 2749151497Sru (every 5n). You can redefine the `TA' macro to create a different 2750151497Sru set of default tab stops. 2751151497Sru 2752151497Sru 2753151497SruFile: groff, Node: ms Displays and Keeps, Next: ms Insertions, Prev: Tabstops in ms, Up: ms Body Text 2754151497Sru 2755151497Sru4.3.5.7 Displays and keeps 2756151497Sru.......................... 2757151497Sru 2758151497SruUse displays to show text-based examples or figures (such as code 2759151497Srulistings). 2760151497Sru 2761151497Sru Displays turn off filling, so lines of code are displayed as-is 2762151497Sruwithout inserting `br' requests in between each line. Displays can be 2763151497Sru"kept" on a single page, or allowed to break across pages. 2764151497Sru 2765151497Sru -- Macro: .DS L 2766151497Sru -- Macro: .LD 2767151497Sru -- Macro: .DE 2768151497Sru Left-justified display. The `.DS L' call generates a page break, 2769151497Sru if necessary, to keep the entire display on one page. The `LD' 2770151497Sru macro allows the display to break across pages. The `DE' macro 2771151497Sru ends the display. 2772151497Sru 2773151497Sru -- Macro: .DS I 2774151497Sru -- Macro: .ID 2775151497Sru -- Macro: .DE 2776151497Sru Indents the display as defined by the `DI' register. The `.DS I' 2777151497Sru call generates a page break, if necessary, to keep the entire 2778151497Sru display on one page. The `ID' macro allows the display to break 2779151497Sru across pages. The `DE' macro ends the display. 2780151497Sru 2781151497Sru -- Macro: .DS B 2782151497Sru -- Macro: .BD 2783151497Sru -- Macro: .DE 2784151497Sru Sets a block-centered display: the entire display is 2785151497Sru left-justified, but indented so that the longest line in the 2786151497Sru display is centered on the page. The `.DS B' call generates a 2787151497Sru page break, if necessary, to keep the entire display on one page. 2788151497Sru The `BD' macro allows the display to break across pages. The `DE' 2789151497Sru macro ends the display. 2790151497Sru 2791151497Sru -- Macro: .DS C 2792151497Sru -- Macro: .CD 2793151497Sru -- Macro: .DE 2794151497Sru Sets a centered display: each line in the display is centered. The 2795151497Sru `.DS C' call generates a page break, if necessary, to keep the 2796151497Sru entire display on one page. The `CD' macro allows the display to 2797151497Sru break across pages. The `DE' macro ends the display. 2798151497Sru 2799151497Sru -- Macro: .DS R 2800151497Sru -- Macro: .RD 2801151497Sru -- Macro: .DE 2802151497Sru Right-justifies each line in the display. The `.DS R' call 2803151497Sru generates a page break, if necessary, to keep the entire display on 2804151497Sru one page. The `RD' macro allows the display to break across 2805151497Sru pages. The `DE' macro ends the display. 2806151497Sru 2807151497Sru -- Macro: .Ds 2808151497Sru -- Macro: .De 2809151497Sru These two macros were formerly provided as aliases for `DS' and 2810151497Sru `DE', respectively. They have been removed, and should no longer 2811151497Sru be used. The original implementations of `DS' and `DE' are 2812151497Sru retained, and should be used instead. X11 documents which actually 2813151497Sru use `Ds' and `De' always load a specific macro file from the X11 2814151497Sru distribution (`macros.t') which provides proper definitions for 2815151497Sru the two macros. 2816151497Sru 2817151497Sru On occasion, you may want to "keep" other text together on a page. 2818151497SruFor example, you may want to keep two paragraphs together, or a 2819151497Sruparagraph that refers to a table (or list, or other item) immediately 2820151497Srufollowing. The `ms' macros provide the `KS' and `KE' macros for this 2821151497Srupurpose. 2822151497Sru 2823151497Sru -- Macro: .KS 2824151497Sru -- Macro: .KE 2825151497Sru The `KS' macro begins a block of text to be kept on a single page, 2826151497Sru and the `KE' macro ends the block. 2827151497Sru 2828151497Sru -- Macro: .KF 2829151497Sru -- Macro: .KE 2830151497Sru Specifies a "floating keep"; if the keep cannot fit on the current 2831151497Sru page, `groff' holds the contents of the keep and allows text 2832151497Sru following the keep (in the source file) to fill in the remainder of 2833151497Sru the current page. When the page breaks, whether by an explicit 2834151497Sru `bp' request or by reaching the end of the page, `groff' prints 2835151497Sru the floating keep at the top of the new page. This is useful for 2836151497Sru printing large graphics or tables that do not need to appear 2837151497Sru exactly where specified. 2838151497Sru 2839151497Sru You can also use the `ne' request to force a page break if there is 2840151497Srunot enough vertical space remaining on the page. 2841151497Sru 2842151497Sru Use the following macros to draw a box around a section of text (such 2843151497Sruas a display). 2844151497Sru 2845151497Sru -- Macro: .B1 2846151497Sru -- Macro: .B2 2847151497Sru Marks the beginning and ending of text that is to have a box drawn 2848151497Sru around it. The `B1' macro begins the box; the `B2' macro ends it. 2849151497Sru Text in the box is automatically placed in a diversion (keep). 2850151497Sru 2851151497Sru 2852151497SruFile: groff, Node: ms Insertions, Next: Example multi-page table, Prev: ms Displays and Keeps, Up: ms Body Text 2853151497Sru 2854151497Sru4.3.5.8 Tables, figures, equations, and references 2855151497Sru.................................................. 2856151497Sru 2857151497SruThe `ms' macros support the standard `groff' preprocessors: `tbl', 2858151497Sru`pic', `eqn', and `refer'. You mark text meant for preprocessors by 2859151497Sruenclosing it in pairs of tags as follows. 2860151497Sru 2861151497Sru -- Macro: .TS [`H'] 2862151497Sru -- Macro: .TE 2863151497Sru Denotes a table, to be processed by the `tbl' preprocessor. The 2864151497Sru optional argument `H' to `TS' instructs `groff' to create a 2865151497Sru running header with the information up to the `TH' macro. `groff' 2866151497Sru prints the header at the beginning of the table; if the table runs 2867151497Sru onto another page, `groff' prints the header on the next page as 2868151497Sru well. 2869151497Sru 2870151497Sru -- Macro: .PS 2871151497Sru -- Macro: .PE 2872151497Sru Denotes a graphic, to be processed by the `pic' preprocessor. You 2873151497Sru can create a `pic' file by hand, using the AT&T `pic' manual 2874151497Sru available on the Web as a reference, or by using a graphics 2875151497Sru program such as `xfig'. 2876151497Sru 2877151497Sru -- Macro: .EQ [align] 2878151497Sru -- Macro: .EN 2879151497Sru Denotes an equation, to be processed by the `eqn' preprocessor. 2880151497Sru The optional ALIGN argument can be `C', `L', or `I' to center (the 2881151497Sru default), left-justify, or indent the equation. 2882151497Sru 2883151497Sru -- Macro: .[ 2884151497Sru -- Macro: .] 2885151497Sru Denotes a reference, to be processed by the `refer' preprocessor. 2886151497Sru The GNU `refer(1)' man page provides a comprehensive reference to 2887151497Sru the preprocessor and the format of the bibliographic database. 2888151497Sru 2889151497Sru* Menu: 2890151497Sru 2891151497Sru* Example multi-page table:: 2892151497Sru 2893151497Sru 2894151497SruFile: groff, Node: Example multi-page table, Next: ms Footnotes, Prev: ms Insertions, Up: ms Body Text 2895151497Sru 2896151497Sru4.3.5.9 An example multi-page table 2897151497Sru................................... 2898151497Sru 2899151497SruThe following is an example of how to set up a table that may print 2900151497Sruacross two or more pages. 2901151497Sru 2902151497Sru 2903151497Sru .TS H 2904151497Sru allbox expand; 2905151497Sru cb | cb . 2906151497Sru Text ...of heading... 2907151497Sru _ 2908151497Sru .TH 2909151497Sru .T& 2910151497Sru l | l . 2911151497Sru ... the rest of the table follows... 2912151497Sru .CW 2913151497Sru .TE 2914151497Sru 2915151497Sru 2916151497SruFile: groff, Node: ms Footnotes, Prev: Example multi-page table, Up: ms Body Text 2917151497Sru 2918151497Sru4.3.5.10 Footnotes 2919151497Sru.................. 2920151497Sru 2921151497SruThe `ms' macro package has a flexible footnote system. You can specify 2922151497Srueither numbered footnotes or symbolic footnotes (that is, using a 2923151497Srumarker such as a dagger symbol). 2924151497Sru 2925151497Sru -- String: \*[*] 2926151497Sru Specifies the location of a numbered footnote marker in the text. 2927151497Sru 2928151497Sru -- Macro: .FS 2929151497Sru -- Macro: .FE 2930151497Sru Specifies the text of the footnote. The default action is to 2931151497Sru create a numbered footnote; you can create a symbolic footnote by 2932151497Sru specifying a "mark" glyph (such as `\[dg]' for the dagger glyph) 2933151497Sru in the body text and as an argument to the `FS' macro, followed by 2934151497Sru the text of the footnote and the `FE' macro. 2935151497Sru 2936151497Sru You can control how `groff' prints footnote numbers by changing the 2937151497Sruvalue of the `FF' register. *Note ms Document Control Registers::. 2938151497Sru 2939151497Sru Footnotes can be safely used within keeps and displays, but you 2940151497Srushould avoid using numbered footnotes within floating keeps. You can 2941151497Sruset a second `\**' marker between a `\**' and its corresponding `.FS' 2942151497Sruentry; as long as each `FS' macro occurs _after_ the corresponding 2943151497Sru`\**' and the occurrences of `.FS' are in the same order as the 2944151497Srucorresponding occurrences of `\**'. 2945151497Sru 2946151497Sru 2947151497SruFile: groff, Node: ms Page Layout, Next: Differences from AT&T ms, Prev: ms Body Text, Up: ms 2948151497Sru 2949151497Sru4.3.6 Page layout 2950151497Sru----------------- 2951151497Sru 2952151497SruThe default output from the `ms' macros provides a minimalist page 2953151497Srulayout: it prints a single column, with the page number centered at the 2954151497Srutop of each page. It prints no footers. 2955151497Sru 2956151497Sru You can change the layout by setting the proper number registers and 2957151497Srustrings. 2958151497Sru 2959151497Sru* Menu: 2960151497Sru 2961151497Sru* ms Headers and Footers:: 2962151497Sru* ms Margins:: 2963151497Sru* ms Multiple Columns:: 2964151497Sru* ms TOC:: 2965151497Sru* ms Strings and Special Characters:: 2966151497Sru 2967151497Sru 2968151497SruFile: groff, Node: ms Headers and Footers, Next: ms Margins, Prev: ms Page Layout, Up: ms Page Layout 2969151497Sru 2970151497Sru4.3.6.1 Headers and footers 2971151497Sru........................... 2972151497Sru 2973151497SruFor documents that do not distinguish between odd and even pages, set 2974151497Sruthe following strings: 2975151497Sru 2976151497Sru -- String: \*[LH] 2977151497Sru -- String: \*[CH] 2978151497Sru -- String: \*[RH] 2979151497Sru Sets the left, center, and right headers. 2980151497Sru 2981151497Sru -- String: \*[LF] 2982151497Sru -- String: \*[CF] 2983151497Sru -- String: \*[RF] 2984151497Sru Sets the left, center, and right footers. 2985151497Sru 2986151497Sru For documents that need different information printed in the even and 2987151497Sruodd pages, use the following macros: 2988151497Sru 2989151497Sru -- Macro: .OH 'left'center'right' 2990151497Sru -- Macro: .EH 'left'center'right' 2991151497Sru -- Macro: .OF 'left'center'right' 2992151497Sru -- Macro: .EF 'left'center'right' 2993151497Sru The `OH' and `EH' macros define headers for the odd and even 2994151497Sru pages; the `OF' and `EF' macros define footers for the odd and 2995151497Sru even pages. This is more flexible than defining the individual 2996151497Sru strings. 2997151497Sru 2998151497Sru You can replace the quote (`'') marks with any character not 2999151497Sru appearing in the header or footer text. 3000151497Sru 3001151497Sru 3002151497SruFile: groff, Node: ms Margins, Next: ms Multiple Columns, Prev: ms Headers and Footers, Up: ms Page Layout 3003151497Sru 3004151497Sru4.3.6.2 Margins 3005151497Sru............... 3006151497Sru 3007151497SruYou control margins using a set of number registers. *Note ms Document 3008151497SruControl Registers::, for details. 3009151497Sru 3010151497Sru 3011151497SruFile: groff, Node: ms Multiple Columns, Next: ms TOC, Prev: ms Margins, Up: ms Page Layout 3012151497Sru 3013151497Sru4.3.6.3 Multiple columns 3014151497Sru........................ 3015151497Sru 3016151497SruThe `ms' macros can set text in as many columns as will reasonably fit 3017151497Sruon the page. The following macros are available; all of them force a 3018151497Srupage break if a multi-column mode is already set. However, if the 3019151497Srucurrent mode is single-column, starting a multi-column mode does _not_ 3020151497Sruforce a page break. 3021151497Sru 3022151497Sru -- Macro: .1C 3023151497Sru Single-column mode. 3024151497Sru 3025151497Sru -- Macro: .2C 3026151497Sru Two-column mode. 3027151497Sru 3028151497Sru -- Macro: .MC [width [gutter]] 3029151497Sru Multi-column mode. If you specify no arguments, it is equivalent 3030151497Sru to the `2C' macro. Otherwise, WIDTH is the width of each column 3031151497Sru and GUTTER is the space between columns. The `MINGW' number 3032151497Sru register controls the default gutter width. 3033151497Sru 3034151497Sru 3035151497SruFile: groff, Node: ms TOC, Next: ms Strings and Special Characters, Prev: ms Multiple Columns, Up: ms Page Layout 3036151497Sru 3037151497Sru4.3.6.4 Creating a table of contents 3038151497Sru.................................... 3039151497Sru 3040151497SruThe facilities in the `ms' macro package for creating a table of 3041151497Srucontents are semi-automated at best. Assuming that you want the table 3042151497Sruof contents to consist of the document's headings, you need to repeat 3043151497Sruthose headings wrapped in `XS' and `XE' macros. 3044151497Sru 3045151497Sru -- Macro: .XS [page] 3046151497Sru -- Macro: .XA [page] 3047151497Sru -- Macro: .XE 3048151497Sru These macros define a table of contents or an individual entry in 3049151497Sru the table of contents, depending on their use. The macros are very 3050151497Sru simple; they cannot indent a heading based on its level. The 3051151497Sru easiest way to work around this is to add tabs to the table of 3052151497Sru contents string. The following is an example: 3053151497Sru 3054151497Sru 3055151497Sru .NH 1 3056151497Sru Introduction 3057151497Sru .XS 3058151497Sru Introduction 3059151497Sru .XE 3060151497Sru .LP 3061151497Sru ... 3062151497Sru .CW 3063151497Sru .NH 2 3064151497Sru Methodology 3065151497Sru .XS 3066151497Sru Methodology 3067151497Sru .XE 3068151497Sru .LP 3069151497Sru ... 3070151497Sru 3071151497Sru You can manually create a table of contents by beginning with the 3072151497Sru `XS' macro for the first entry, specifying the page number for 3073151497Sru that entry as the argument to `XS'. Add subsequent entries using 3074151497Sru the `XA' macro, specifying the page number for that entry as the 3075151497Sru argument to `XA'. The following is an example: 3076151497Sru 3077151497Sru 3078151497Sru .XS 1 3079151497Sru Introduction 3080151497Sru .XA 2 3081151497Sru A Brief History of the Universe 3082151497Sru .XA 729 3083151497Sru Details of Galactic Formation 3084151497Sru ... 3085151497Sru .XE 3086151497Sru 3087151497Sru 3088151497Sru -- Macro: .TC [`no'] 3089151497Sru Prints the table of contents on a new page, setting the page number 3090151497Sru to *i* (Roman lowercase numeral one). You should usually place 3091151497Sru this macro at the end of the file, since `groff' is a single-pass 3092151497Sru formatter and can only print what has been collected up to the 3093151497Sru point that the `TC' macro appears. 3094151497Sru 3095151497Sru The optional argument `no' suppresses printing the title specified 3096151497Sru by the string register `TOC'. 3097151497Sru 3098151497Sru -- Macro: .PX [`no'] 3099151497Sru Prints the table of contents on a new page, using the current page 3100151497Sru numbering sequence. Use this macro to print a manually-generated 3101151497Sru table of contents at the beginning of your document. 3102151497Sru 3103151497Sru The optional argument `no' suppresses printing the title specified 3104151497Sru by the string register `TOC'. 3105151497Sru 3106151497Sru The `Groff and Friends HOWTO' includes a `sed' script that 3107151497Sruautomatically inserts `XS' and `XE' macro entries after each heading in 3108151497Srua document. 3109151497Sru 3110151497Sru Altering the `NH' macro to automatically build the table of contents 3111151497Sruis perhaps initially more difficult, but would save a great deal of 3112151497Srutime in the long run if you use `ms' regularly. 3113151497Sru 3114151497Sru 3115151497SruFile: groff, Node: ms Strings and Special Characters, Prev: ms TOC, Up: ms Page Layout 3116151497Sru 3117151497Sru4.3.6.5 Strings and Special Characters 3118151497Sru...................................... 3119151497Sru 3120151497SruThe `ms' macros provide the following predefined strings. You can 3121151497Sruchange the string definitions to help in creating documents in 3122151497Srulanguages other than English. 3123151497Sru 3124151497Sru -- String: \*[REFERENCES] 3125151497Sru Contains the string printed at the beginning of the references 3126151497Sru (bibliography) page. The default is `References'. 3127151497Sru 3128151497Sru -- String: \*[ABSTRACT] 3129151497Sru Contains the string printed at the beginning of the abstract. The 3130151497Sru default is `ABSTRACT'. 3131151497Sru 3132151497Sru -- String: \*[TOC] 3133151497Sru Contains the string printed at the beginning of the table of 3134151497Sru contents. 3135151497Sru 3136151497Sru -- String: \*[MONTH1] 3137151497Sru -- String: \*[MONTH2] 3138151497Sru -- String: \*[MONTH3] 3139151497Sru -- String: \*[MONTH4] 3140151497Sru -- String: \*[MONTH5] 3141151497Sru -- String: \*[MONTH6] 3142151497Sru -- String: \*[MONTH7] 3143151497Sru -- String: \*[MONTH8] 3144151497Sru -- String: \*[MONTH9] 3145151497Sru -- String: \*[MONTH10] 3146151497Sru -- String: \*[MONTH11] 3147151497Sru -- String: \*[MONTH12] 3148151497Sru Prints the full name of the month in dates. The default is 3149151497Sru `January', `February', etc. 3150151497Sru 3151151497Sru The following special characters are available(1) (*note ms Strings 3152151497Sruand Special Characters-Footnote-1::): 3153151497Sru 3154151497Sru -- String: \*[-] 3155151497Sru Prints an em dash. 3156151497Sru 3157151497Sru -- String: \*[Q] 3158151497Sru -- String: \*[U] 3159151497Sru Prints typographer's quotes in troff, and plain quotes in nroff. 3160151497Sru `\*Q' is the left quote and `\*U' is the right quote. 3161151497Sru 3162151497Sru Improved accent marks are available in the `ms' macros. 3163151497Sru 3164151497Sru -- Macro: .AM 3165151497Sru Specify this macro at the beginning of your document to enable 3166151497Sru extended accent marks and special characters. This is a Berkeley 3167151497Sru extension. 3168151497Sru 3169151497Sru To use the accent marks, place them *after* the character being 3170151497Sru accented. 3171151497Sru 3172151497Sru Note that groff's native support for accents is superior to the 3173151497Sru following definitions. 3174151497Sru 3175151497Sru The following accent marks are available after invoking the `AM' 3176151497Srumacro: 3177151497Sru 3178151497Sru -- String: \*['] 3179151497Sru Acute accent. 3180151497Sru 3181151497Sru -- String: \*[`] 3182151497Sru Grave accent. 3183151497Sru 3184151497Sru -- String: \*[^] 3185151497Sru Circumflex. 3186151497Sru 3187151497Sru -- String: \*[,] 3188151497Sru Cedilla. 3189151497Sru 3190151497Sru -- String: \*[~] 3191151497Sru Tilde. 3192151497Sru 3193151497Sru -- String: \*[:] 3194151497Sru Umlaut. 3195151497Sru 3196151497Sru -- String: \*[v] 3197151497Sru Hacek. 3198151497Sru 3199151497Sru -- String: \*[_] 3200151497Sru Macron (overbar). 3201151497Sru 3202151497Sru -- String: \*[.] 3203151497Sru Underdot. 3204151497Sru 3205151497Sru -- String: \*[o] 3206151497Sru Ring above. 3207151497Sru 3208151497Sru The following are standalone characters available after invoking the 3209151497Sru`AM' macro: 3210151497Sru 3211151497Sru -- String: \*[?] 3212151497Sru Upside-down question mark. 3213151497Sru 3214151497Sru -- String: \*[!] 3215151497Sru Upside-down exclamation point. 3216151497Sru 3217151497Sru -- String: \*[8] 3218151497Sru German � ligature. 3219151497Sru 3220151497Sru -- String: \*[3] 3221151497Sru Yogh. 3222151497Sru 3223151497Sru -- String: \*[Th] 3224151497Sru Uppercase thorn. 3225151497Sru 3226151497Sru -- String: \*[th] 3227151497Sru Lowercase thorn. 3228151497Sru 3229151497Sru -- String: \*[D-] 3230151497Sru Uppercase eth. 3231151497Sru 3232151497Sru -- String: \*[d-] 3233151497Sru Lowercase eth. 3234151497Sru 3235151497Sru -- String: \*[q] 3236151497Sru Hooked o. 3237151497Sru 3238151497Sru -- String: \*[ae] 3239151497Sru Lowercase � ligature. 3240151497Sru 3241151497Sru -- String: \*[Ae] 3242151497Sru Uppercase � ligature. 3243151497Sru 3244151497Sru 3245151497SruFile: groff, Node: ms Strings and Special Characters-Footnotes, Up: ms Strings and Special Characters 3246151497Sru 3247151497Sru (1) For an explanation what special characters are see *Note Special 3248151497SruCharacters::. 3249151497Sru 3250151497Sru 3251151497SruFile: groff, Node: Differences from AT&T ms, Next: Naming Conventions, Prev: ms Page Layout, Up: ms 3252151497Sru 3253151497Sru4.3.7 Differences from AT&T `ms' 3254151497Sru-------------------------------- 3255151497Sru 3256151497SruThis section lists the (minor) differences between the `groff -ms' 3257151497Srumacros and AT&T `troff -ms' macros. 3258151497Sru 3259151497Sru * The internals of `groff -ms' differ from the internals of AT&T 3260151497Sru `troff -ms'. Documents that depend upon implementation details of 3261151497Sru AT&T `troff -ms' may not format properly with `groff -ms'. 3262151497Sru 3263151497Sru * The general error-handling policy of `groff -ms' is to detect and 3264151497Sru report errors, rather than silently to ignore them. 3265151497Sru 3266151497Sru * `groff -ms' does not work in compatibility mode (this is, with the 3267151497Sru `-C' option). 3268151497Sru 3269151497Sru * There is no special support for typewriter-like devices. 3270151497Sru 3271151497Sru * `groff -ms' does not provide cut marks. 3272151497Sru 3273151497Sru * Multiple line spacing is not supported. Use a larger vertical 3274151497Sru spacing instead. 3275151497Sru 3276151497Sru * Some UNIX `ms' documentation says that the `CW' and `GW' number 3277151497Sru registers can be used to control the column width and gutter 3278151497Sru width, respectively. These number registers are not used in 3279151497Sru `groff -ms'. 3280151497Sru 3281151497Sru * Macros that cause a reset (paragraphs, headings, etc.) may change 3282151497Sru the indentation. Macros that change the indentation do not 3283151497Sru increment or decrement the indentation, but rather set it 3284151497Sru absolutely. This can cause problems for documents that define 3285151497Sru additional macros of their own. The solution is to use not the 3286151497Sru `in' request but instead the `RS' and `RE' macros. 3287151497Sru 3288151497Sru * To make `groff -ms' use the default page offset (which also 3289151497Sru specifies the left margin), the `PO' register must stay undefined 3290151497Sru until the first `-ms' macro is evaluated. This implies that `PO' 3291151497Sru should not be used early in the document, unless it is changed 3292151497Sru also: Remember that accessing an undefined register automatically 3293151497Sru defines it. 3294151497Sru 3295151497Sru -- Register: \n[GS] 3296151497Sru This number register is set to 1 by the `groff -ms' macros, but it 3297151497Sru is not used by the `AT&T' `troff -ms' macros. Documents that need 3298151497Sru to determine whether they are being formatted with `AT&T' `troff 3299151497Sru -ms' or `groff -ms' should use this number register. 3300151497Sru 3301151497Sru* Menu: 3302151497Sru 3303151497Sru* Missing ms Macros:: 3304151497Sru* Additional ms Macros:: 3305151497Sru 3306151497Sru 3307151497SruFile: groff, Node: Missing ms Macros, Next: Additional ms Macros, Prev: Differences from AT&T ms, Up: Differences from AT&T ms 3308151497Sru 3309151497Sru4.3.7.1 `troff' macros not appearing in `groff' 3310151497Sru............................................... 3311151497Sru 3312151497SruMacros missing from `groff -ms' are cover page macros specific to Bell 3313151497SruLabs and Berkeley. The macros known to be missing are: 3314151497Sru 3315151497Sru`.TM' 3316151497Sru Technical memorandum; a cover sheet style 3317151497Sru 3318151497Sru`.IM' 3319151497Sru Internal memorandum; a cover sheet style 3320151497Sru 3321151497Sru`.MR' 3322151497Sru Memo for record; a cover sheet style 3323151497Sru 3324151497Sru`.MF' 3325151497Sru Memo for file; a cover sheet style 3326151497Sru 3327151497Sru`.EG' 3328151497Sru Engineer's notes; a cover sheet style 3329151497Sru 3330151497Sru`.TR' 3331151497Sru Computing Science Tech Report; a cover sheet style 3332151497Sru 3333151497Sru`.OK' 3334151497Sru Other keywords 3335151497Sru 3336151497Sru`.CS' 3337151497Sru Cover sheet information 3338151497Sru 3339151497Sru`.MH' 3340151497Sru A cover sheet macro 3341151497Sru 3342151497Sru 3343151497SruFile: groff, Node: Additional ms Macros, Prev: Missing ms Macros, Up: Differences from AT&T ms 3344151497Sru 3345151497Sru4.3.7.2 `groff' macros not appearing in AT&T `troff' 3346151497Sru.................................................... 3347151497Sru 3348151497SruThe `groff -ms' macros have a few minor extensions compared to the AT&T 3349151497Sru`troff -ms' macros. 3350151497Sru 3351151497Sru -- Macro: .AM 3352151497Sru Improved accent marks. *Note ms Strings and Special Characters::, 3353151497Sru for details. 3354151497Sru 3355151497Sru -- Macro: .DS I 3356151497Sru Indented display. The default behavior of AT&T `troff -ms' was to 3357151497Sru indent; the `groff' default prints displays flush left with the 3358151497Sru body text. 3359151497Sru 3360151497Sru -- Macro: .CW 3361151497Sru Print text in `constant width' (Courier) font. 3362151497Sru 3363151497Sru -- Macro: .IX 3364151497Sru Indexing term (printed on standard error). You can write a script 3365151497Sru to capture and process an index generated in this manner. 3366151497Sru 3367151497Sru The following additional number registers appear in `groff -ms': 3368151497Sru 3369151497Sru -- Register: \n[MINGW] 3370151497Sru Specifies a minimum space between columns (for multi-column 3371151497Sru output); this takes the place of the `GW' register that was 3372151497Sru documented but apparently not implemented in AT&T `troff'. 3373151497Sru 3374151497Sru Several new string registers are available as well. You can change 3375151497Sruthese to handle (for example) the local language. *Note ms Strings and 3376151497SruSpecial Characters::, for details. 3377151497Sru 3378151497Sru 3379151497SruFile: groff, Node: Naming Conventions, Prev: Differences from AT&T ms, Up: ms 3380151497Sru 3381151497Sru4.3.8 Naming Conventions 3382151497Sru------------------------ 3383151497Sru 3384151497SruThe following conventions are used for names of macros, strings and 3385151497Srunumber registers. External names available to documents that use the 3386151497Sru`groff -ms' macros contain only uppercase letters and digits. 3387151497Sru 3388151497Sru Internally the macros are divided into modules; naming conventions 3389151497Sruare as follows: 3390151497Sru 3391151497Sru * Names used only within one module are of the form MODULE`*'NAME. 3392151497Sru 3393151497Sru * Names used outside the module in which they are defined are of the 3394151497Sru form MODULE`@'NAME. 3395151497Sru 3396151497Sru * Names associated with a particular environment are of the form 3397151497Sru ENVIRONMENT`:'NAME; these are used only within the `par' module. 3398151497Sru 3399151497Sru * NAME does not have a module prefix. 3400151497Sru 3401151497Sru * Constructed names used to implement arrays are of the form 3402151497Sru ARRAY`!'INDEX. 3403151497Sru 3404151497Sru Thus the groff ms macros reserve the following names: 3405151497Sru 3406151497Sru * Names containing the characters `*', `@', and `:'. 3407151497Sru 3408151497Sru * Names containing only uppercase letters and digits. 3409151497Sru 3410151497Sru 3411151497SruFile: groff, Node: me, Next: mm, Prev: ms, Up: Macro Packages 3412151497Sru 3413151497Sru4.4 `me' 3414151497Sru======== 3415151497Sru 3416151497SruSee the `meintro.me' and `meref.me' documents in groff's `doc' 3417151497Srudirectory. 3418151497Sru 3419151497Sru 3420151497SruFile: groff, Node: mm, Prev: me, Up: Macro Packages 3421151497Sru 3422151497Sru4.5 `mm' 3423151497Sru======== 3424151497Sru 3425151497SruSee the `groff_mm(7)' man page (type `man groff_mm' at the command 3426151497Sruline). 3427151497Sru 3428151497Sru 3429151497SruFile: groff, Node: gtroff Reference, Next: Preprocessors, Prev: Macro Packages, Up: Top 3430151497Sru 3431151497Sru5 `gtroff' Reference 3432151497Sru******************** 3433151497Sru 3434151497SruThis chapter covers *all* of the facilities of `gtroff'. Users of 3435151497Srumacro packages may skip it if not interested in details. 3436151497Sru 3437151497Sru* Menu: 3438151497Sru 3439151497Sru* Text:: 3440151497Sru* Measurements:: 3441151497Sru* Expressions:: 3442151497Sru* Identifiers:: 3443151497Sru* Embedded Commands:: 3444151497Sru* Registers:: 3445151497Sru* Manipulating Filling and Adjusting:: 3446151497Sru* Manipulating Hyphenation:: 3447151497Sru* Manipulating Spacing:: 3448151497Sru* Tabs and Fields:: 3449151497Sru* Character Translations:: 3450151497Sru* Troff and Nroff Mode:: 3451151497Sru* Line Layout:: 3452151497Sru* Line Control:: 3453151497Sru* Page Layout:: 3454151497Sru* Page Control:: 3455151497Sru* Fonts and Symbols:: 3456151497Sru* Sizes:: 3457151497Sru* Strings:: 3458151497Sru* Conditionals and Loops:: 3459151497Sru* Writing Macros:: 3460151497Sru* Page Motions:: 3461151497Sru* Drawing Requests:: 3462151497Sru* Traps:: 3463151497Sru* Diversions:: 3464151497Sru* Environments:: 3465151497Sru* Suppressing output:: 3466151497Sru* Colors:: 3467151497Sru* I/O:: 3468151497Sru* Postprocessor Access:: 3469151497Sru* Miscellaneous:: 3470151497Sru* Gtroff Internals:: 3471151497Sru* Debugging:: 3472151497Sru* Implementation Differences:: 3473151497Sru 3474151497Sru 3475151497SruFile: groff, Node: Text, Next: Measurements, Prev: gtroff Reference, Up: gtroff Reference 3476151497Sru 3477151497Sru5.1 Text 3478151497Sru======== 3479151497Sru 3480151497Sru`gtroff' input files contain text with control commands interspersed 3481151497Sruthroughout. But, even without control codes, `gtroff' still does 3482151497Sruseveral things with the input text: 3483151497Sru 3484151497Sru * filling and adjusting 3485151497Sru 3486151497Sru * adding additional space after sentences 3487151497Sru 3488151497Sru * hyphenating 3489151497Sru 3490151497Sru * inserting implicit line breaks 3491151497Sru 3492151497Sru* Menu: 3493151497Sru 3494151497Sru* Filling and Adjusting:: 3495151497Sru* Hyphenation:: 3496151497Sru* Sentences:: 3497151497Sru* Tab Stops:: 3498151497Sru* Implicit Line Breaks:: 3499151497Sru* Input Conventions:: 3500151497Sru* Input Encodings:: 3501151497Sru 3502151497Sru 3503151497SruFile: groff, Node: Filling and Adjusting, Next: Hyphenation, Prev: Text, Up: Text 3504151497Sru 3505151497Sru5.1.1 Filling and Adjusting 3506151497Sru--------------------------- 3507151497Sru 3508151497SruWhen `gtroff' reads text, it collects words from the input and fits as 3509151497Srumany of them together on one output line as it can. This is known as 3510151497Sru"filling". 3511151497Sru 3512151497Sru Once `gtroff' has a "filled" line, it tries to "adjust" it. This 3513151497Srumeans it widens the spacing between words until the text reaches the 3514151497Sruright margin (in the default adjustment mode). Extra spaces between 3515151497Sruwords are preserved, but spaces at the end of lines are ignored. 3516151497SruSpaces at the front of a line cause a "break" (breaks are explained in 3517151497Sru*Note Implicit Line Breaks::). 3518151497Sru 3519151497Sru *Note Manipulating Filling and Adjusting::. 3520151497Sru 3521151497Sru 3522151497SruFile: groff, Node: Hyphenation, Next: Sentences, Prev: Filling and Adjusting, Up: Text 3523151497Sru 3524151497Sru5.1.2 Hyphenation 3525151497Sru----------------- 3526151497Sru 3527151497SruSince the odds are not great for finding a set of words, for every 3528151497Sruoutput line, which fit nicely on a line without inserting excessive 3529151497Sruamounts of space between words, `gtroff' hyphenates words so that it 3530151497Srucan justify lines without inserting too much space between words. It 3531151497Sruuses an internal hyphenation algorithm (a simplified version of the 3532151497Srualgorithm used within TeX) to indicate which words can be hyphenated 3533151497Sruand how to do so. When a word is hyphenated, the first part of the 3534151497Sruword is added to the current filled line being output (with an attached 3535151497Sruhyphen), and the other portion is added to the next line to be filled. 3536151497Sru 3537151497Sru *Note Manipulating Hyphenation::. 3538151497Sru 3539151497Sru 3540151497SruFile: groff, Node: Sentences, Next: Tab Stops, Prev: Hyphenation, Up: Text 3541151497Sru 3542151497Sru5.1.3 Sentences 3543151497Sru--------------- 3544151497Sru 3545151497SruAlthough it is often debated, some typesetting rules say there should be 3546151497Srudifferent amounts of space after various punctuation marks. For 3547151497Sruexample, the `Chicago typsetting manual' says that a period at the end 3548151497Sruof a sentence should have twice as much space following it as would a 3549151497Srucomma or a period as part of an abbreviation. 3550151497Sru 3551151497Sru `gtroff' does this by flagging certain characters (normally `!', 3552151497Sru`?', and `.') as "end-of-sentence" characters. When `gtroff' 3553151497Sruencounters one of these characters at the end of a line, it appends a 3554151497Srunormal space followed by a "sentence space" in the formatted output. 3555151497Sru(This justifies one of the conventions mentioned in *Note Input 3556151497SruConventions::.) 3557151497Sru 3558151497Sru In addition, the following characters and symbols are treated 3559151497Srutransparently while handling end-of-sentence characters: `"', `'', `)', 3560151497Sru`]', `*', `\[dg]', and `\[rq]'. 3561151497Sru 3562151497Sru See the `cflags' request in *Note Using Symbols::, for more details. 3563151497Sru 3564151497Sru To prevent the insertion of extra space after an end-of-sentence 3565151497Srucharacter (at the end of a line), append `\&'. 3566151497Sru 3567151497Sru 3568151497SruFile: groff, Node: Tab Stops, Next: Implicit Line Breaks, Prev: Sentences, Up: Text 3569151497Sru 3570151497Sru5.1.4 Tab Stops 3571151497Sru--------------- 3572151497Sru 3573151497Sru`gtroff' translates "tabulator characters", also called "tabs" 3574151497Sru(normally code point ASCII `0x09' or EBCDIC `0x05'), in the input into 3575151497Srumovements to the next tabulator stop. These tab stops are initially 3576151497Srulocated every half inch across the page. Using this, simple tables can 3577151497Srube made easily. However, it can often be deceptive as the appearance 3578151497Sru(and width) of the text on a terminal and the results from `gtroff' can 3579151497Sruvary greatly. 3580151497Sru 3581151497Sru Also, a possible sticking point is that lines beginning with tab 3582151497Srucharacters are still filled, again producing unexpected results. For 3583151497Sruexample, the following input 3584151497Sru 3585151497Sru 1 2 3 3586151497Sru 4 5 3587151497Sru 3588151497Sruproduces 3589151497Sru 3590151497Sru 1 2 3 4 5 3591151497Sru 3592151497Sru *Note Tabs and Fields::. 3593151497Sru 3594151497Sru 3595151497SruFile: groff, Node: Implicit Line Breaks, Next: Input Conventions, Prev: Tab Stops, Up: Text 3596151497Sru 3597151497Sru5.1.5 Implicit Line Breaks 3598151497Sru-------------------------- 3599151497Sru 3600151497SruAn important concept in `gtroff' is the "break". When a break occurs, 3601151497Sru`gtroff' outputs the partially filled line (unjustified), and resumes 3602151497Srucollecting and filling text on the next output line. 3603151497Sru 3604151497Sru There are several ways to cause a break in `gtroff'. A blank line 3605151497Srunot only causes a break, but it also outputs a one-line vertical space 3606151497Sru(effectively a blank line). Note that this behaviour can be modified 3607151497Sruwith the blank line macro request `blm'. *Note Blank Line Traps::. 3608151497Sru 3609151497Sru A line that begins with a space causes a break and the space is 3610151497Sruoutput at the beginning of the next line. Note that this space isn't 3611151497Sruadjusted, even in fill mode. 3612151497Sru 3613151497Sru The end of file also causes a break - otherwise the last line of the 3614151497Srudocument may vanish! 3615151497Sru 3616151497Sru Certain requests also cause breaks, implicitly or explicitly. This 3617151497Sruis discussed in *Note Manipulating Filling and Adjusting::. 3618151497Sru 3619151497Sru 3620151497SruFile: groff, Node: Input Conventions, Next: Input Encodings, Prev: Implicit Line Breaks, Up: Text 3621151497Sru 3622151497Sru5.1.6 Input Conventions 3623151497Sru----------------------- 3624151497Sru 3625151497SruSince `gtroff' does filling automatically, it is traditional in `groff' 3626151497Srunot to try and type things in as nicely formatted paragraphs. These 3627151497Sruare some conventions commonly used when typing `gtroff' text: 3628151497Sru 3629151497Sru * Break lines after punctuation, particularly at the end of a 3630151497Sru sentence and in other logical places. Keep separate phrases on 3631151497Sru lines by themselves, as entire phrases are often added or deleted 3632151497Sru when editing. 3633151497Sru 3634151497Sru * Try to keep lines less than 40-60 characters, to allow space for 3635151497Sru inserting more text. 3636151497Sru 3637151497Sru * Do not try to do any formatting in a WYSIWYG manner (i.e., don't 3638151497Sru try using spaces to get proper indentation). 3639151497Sru 3640151497Sru 3641151497SruFile: groff, Node: Input Encodings, Prev: Input Conventions, Up: Text 3642151497Sru 3643151497Sru5.1.7 Input Encodings 3644151497Sru--------------------- 3645151497Sru 3646151497SruCurrently, the following input encodings are available. 3647151497Sru 3648151497Srucp1047 3649151497Sru This input encoding works only on EBCDIC platforms (and vice 3650151497Sru versa, the other input encodings don't work with EBCDIC); the file 3651151497Sru `cp1047.tmac' is by default loaded at start-up. 3652151497Sru 3653151497Srulatin-1 3654151497Sru This is the default input encoding on non-EBCDIC platforms; the 3655151497Sru file `latin1.tmac' is loaded at start-up. 3656151497Sru 3657151497Srulatin-2 3658151497Sru To use this encoding, either say `.mso latin2.tmac' at the very 3659151497Sru beginning of your document or use `-mlatin2' as a command line 3660151497Sru argument for `groff'. 3661151497Sru 3662151497Srulatin-9 (latin-0) 3663151497Sru This encoding is intended (at least in Europe) to replace latin-1 3664151497Sru encoding. The main difference to latin-1 is that latin-9 contains 3665151497Sru the Euro character. To use this encoding, either say 3666151497Sru `.mso latin9.tmac' at the very beginning of your document or use 3667151497Sru `-mlatin9' as a command line argument for `groff'. 3668151497Sru 3669151497Sru Note that it can happen that some input encoding characters are not 3670151497Sruavailable for a particular output device. For example, saying 3671151497Sru 3672151497Sru 3673151497Sru groff -Tlatin1 -mlatin9 ... 3674151497Sru 3675151497Sruwill fail if you use the Euro character in the input. Usually, this 3676151497Srulimitation is present only for devices which have a limited set of 3677151497Sruoutput glyphs (e.g. `-Tascii' and `-Tlatin1'); for other devices it is 3678151497Sruusually sufficient to install proper fonts which contain the necessary 3679151497Sruglyphs. 3680151497Sru 3681151497Sru Due to the importance of the Euro glyph in Europe, the groff package 3682151497Srunow comes with a POSTSCRIPT font called `freeeuro.pfa' which provides 3683151497Sruvarious glyph shapes for the Euro. With other words, latin-9 encoding 3684151497Sruis supported for the `-Tps' device out of the box (latin-2 isn't). 3685151497Sru 3686151497Sru By its very nature, `-Tutf8' supports all input encodings; `-Tdvi' 3687151497Sruhas support for both latin-2 and latin-9 if the command line `-mec' is 3688151497Sruused also to load the file `ec.tmac' (which flips to the EC fonts). 3689151497Sru 3690151497Sru 3691151497SruFile: groff, Node: Measurements, Next: Expressions, Prev: Text, Up: gtroff Reference 3692151497Sru 3693151497Sru5.2 Measurements 3694151497Sru================ 3695151497Sru 3696151497Sru`gtroff' (like many other programs) requires numeric parameters to 3697151497Sruspecify various measurements. Most numeric parameters(1) (*note 3698151497SruMeasurements-Footnote-1::) may have a "measurement unit" attached. 3699151497SruThese units are specified as a single character which immediately 3700151497Srufollows the number or expression. Each of these units are understood, 3701151497Sruby `gtroff', to be a multiple of its "basic unit". So, whenever a 3702151497Srudifferent measurement unit is specified `gtroff' converts this into its 3703151497Sru"basic units". This basic unit, represented by a `u', is a device 3704151497Srudependent measurement which is quite small, ranging from 1/75th to 3705151497Sru1/72000th of an inch. The values may be given as fractional numbers; 3706151497Sruhowever, fractional basic units are always rounded to integers. 3707151497Sru 3708151497Sru Some of the measurement units are completely independent of any of 3709151497Sruthe current settings (e.g. type size) of `gtroff'. 3710151497Sru 3711151497Sru`i' 3712151497Sru Inches. An antiquated measurement unit still in use in certain 3713151497Sru backwards countries with incredibly low-cost computer equipment. 3714151497Sru One inch is equal to 2.54cm. 3715151497Sru 3716151497Sru`c' 3717151497Sru Centimeters. One centimeter is equal to 0.3937in. 3718151497Sru 3719151497Sru`p' 3720151497Sru Points. This is a typesetter's measurement used for measure type 3721151497Sru size. It is 72 points to an inch. 3722151497Sru 3723151497Sru`P' 3724151497Sru Pica. Another typesetting measurement. 6 Picas to an inch (and 3725151497Sru 12 points to a pica). 3726151497Sru 3727151497Sru`s' 3728151497Sru`z' 3729151497Sru *Note Fractional Type Sizes::, for a discussion of these units. 3730151497Sru 3731151497Sru`f' 3732151497Sru Fractions. Value is 65536. *Note Colors::, for usage. 3733151497Sru 3734151497Sru The other measurements understood by `gtroff' depend on settings 3735151497Srucurrently in effect in `gtroff'. These are very useful for specifying 3736151497Srumeasurements which should look proper with any size of text. 3737151497Sru 3738151497Sru`m' 3739151497Sru Ems. This unit is equal to the current font size in points. So 3740151497Sru called because it is _approximately_ the width of the letter `m' 3741151497Sru in the current font. 3742151497Sru 3743151497Sru`n' 3744151497Sru Ens. In `groff', this is half of an em. 3745151497Sru 3746151497Sru`v' 3747151497Sru Vertical space. This is equivalent to the current line spacing. 3748151497Sru *Note Sizes::, for more information about this. 3749151497Sru 3750151497Sru`M' 3751151497Sru 100ths of an em. 3752151497Sru 3753151497Sru* Menu: 3754151497Sru 3755151497Sru* Default Units:: 3756151497Sru 3757151497Sru 3758151497SruFile: groff, Node: Measurements-Footnotes, Up: Measurements 3759151497Sru 3760151497Sru (1) those that specify vertical or horizontal motion or a type size 3761151497Sru 3762151497Sru 3763151497SruFile: groff, Node: Default Units, Prev: Measurements, Up: Measurements 3764151497Sru 3765151497Sru5.2.1 Default Units 3766151497Sru------------------- 3767151497Sru 3768151497SruMany requests take a default unit. While this can be helpful at times, 3769151497Sruit can cause strange errors in some expressions. For example, the line 3770151497Srulength request expects em units. Here are several attempts to get a 3771151497Sruline length of 3.5 inches and their results: 3772151497Sru 3773151497Sru 3774151497Sru 3.5i => 3.5i 3775151497Sru 7/2 => 0i 3776151497Sru 7/2i => 0i 3777151497Sru (7 / 2)u => 0i 3778151497Sru 7i/2 => 0.1i 3779151497Sru 7i/2u => 3.5i 3780151497Sru 3781151497SruEverything is converted to basic units first. In the above example it 3782151497Sruis assumed that 1i equals 240u, and 1m equals 10p (thus 1m equals 33u). 3783151497SruThe value 7i/2 is first handled as 7i/2m, then converted to 1680u/66u 3784151497Sruwhich is 25u, and this is approximately 0.1i. As can be seen, a 3785151497Sruscaling indicator after a closing parenthesis is simply ignored. 3786151497Sru 3787151497Sru Thus, the safest way to specify measurements is to always attach a 3788151497Sruscaling indicator. If you want to multiply or divide by a certain 3789151497Sruscalar value, use `u' as the unit for that value. 3790151497Sru 3791151497Sru 3792151497SruFile: groff, Node: Expressions, Next: Identifiers, Prev: Measurements, Up: gtroff Reference 3793151497Sru 3794151497Sru5.3 Expressions 3795151497Sru=============== 3796151497Sru 3797151497Sru`gtroff' has most arithmetic operators common to other languages: 3798151497Sru 3799151497Sru * Arithmetic: `+' (addition), `-' (subtraction), `/' (division), `*' 3800151497Sru (multiplication), `%' (modulo). 3801151497Sru 3802151497Sru `gtroff' only provides integer arithmetic. The internal type used 3803151497Sru for computing results is `int', which is usually a 32bit signed 3804151497Sru integer. 3805151497Sru 3806151497Sru * Comparison: `<' (less than), `>' (greater than), `<=' (less than 3807151497Sru or equal), `>=' (greater than or equal), `=' (equal), `==' (the 3808151497Sru same as `='). 3809151497Sru 3810151497Sru * Logical: `&' (logical and), `:' (logical or). 3811151497Sru 3812151497Sru * Unary operators: `-' (negating, i.e. changing the sign), `+' (just 3813151497Sru for completeness; does nothing in expressions), `!' (logical not; 3814151497Sru this works only within `if' and `while' requests). See below for 3815151497Sru the use of unary operators in motion requests. 3816151497Sru 3817151497Sru * Extrema: `>?' (maximum), `<?' (minimum). 3818151497Sru 3819151497Sru Example: 3820151497Sru 3821151497Sru 3822151497Sru .nr x 5 3823151497Sru .nr y 3 3824151497Sru .nr z (\n[x] >? \n[y]) 3825151497Sru 3826151497Sru The register `z' now contains 5. 3827151497Sru 3828151497Sru * Scaling: `(C;E)'. Evaluate E using C as the default scaling 3829151497Sru indicator. If C is missing, ignore scaling indicators in the 3830151497Sru evaluation of E. 3831151497Sru 3832151497Sru Parentheses may be used as in any other language. However, in 3833151497Sru`gtroff' they are necessary to ensure order of evaluation. `gtroff' 3834151497Sruhas no operator precedence; expressions are evaluated left to right. 3835151497SruThis means that `gtroff' evaluates `3+5*4' as if it were parenthesized 3836151497Srulike `(3+5)*4', not as `3+(5*4)', as might be expected. 3837151497Sru 3838151497Sru For many requests which cause a motion on the page, the unary 3839151497Sruoperators `+' and `-' work differently if leading an expression. They 3840151497Sruthen indicate a motion relative to the current position (down or up, 3841151497Srurespectively). 3842151497Sru 3843151497Sru Similarly, a leading `|' operator indicates an absolute position. 3844151497SruFor vertical movements, it specifies the distance from the top of the 3845151497Srupage; for horizontal movements, it gives the distance from the beginning 3846151497Sruof the _input_ line. 3847151497Sru 3848151497Sru `+' and `-' are also treated differently by the following requests 3849151497Sruand escapes: `bp', `in', `ll', `lt', `nm', `nr', `pl', `pn', `po', `ps', 3850151497Sru`pvs', `rt', `ti', `\H', `\R', and `\s'. Here, leading plus and minus 3851151497Srusigns indicate increments and decrements. 3852151497Sru 3853151497Sru *Note Setting Registers::, for some examples. 3854151497Sru 3855151497Sru -- Escape: \B'anything' 3856151497Sru Return 1 if ANYTHING is a valid numeric expression; or 0 if 3857151497Sru ANYTHING is empty or not a valid numeric expression. 3858151497Sru 3859151497Sru Due to the way arguments are parsed, spaces are not allowed in 3860151497Sruexpressions, unless the entire expression is surrounded by parentheses. 3861151497Sru 3862151497Sru *Note Request and Macro Arguments::, and *Note Conditionals and 3863151497SruLoops::. 3864151497Sru 3865151497Sru 3866151497SruFile: groff, Node: Identifiers, Next: Embedded Commands, Prev: Expressions, Up: gtroff Reference 3867151497Sru 3868151497Sru5.4 Identifiers 3869151497Sru=============== 3870151497Sru 3871151497SruLike any other language, `gtroff' has rules for properly formed 3872151497Sru"identifiers". In `gtroff', an identifier can be made up of almost any 3873151497Sruprintable character, with the exception of the following characters: 3874151497Sru 3875151497Sru * Whitespace characters (spaces, tabs, and newlines). 3876151497Sru 3877151497Sru * Backspace (ASCII `0x08' or EBCDIC `0x16') and character code 3878151497Sru `0x01'. 3879151497Sru 3880151497Sru * The following input characters are invalid and are ignored if 3881151497Sru `groff' runs on a machine based on ASCII, causing a warning 3882151497Sru message of type `input' (see *Note Debugging::, for more details): 3883151497Sru `0x00', `0x0B', `0x0D'-`0x1F', `0x80'-`0x9F'. 3884151497Sru 3885151497Sru And here are the invalid input characters if `groff' runs on an 3886151497Sru EBCDIC host: `0x00', `0x08', `0x09', `0x0B', `0x0D'-`0x14', 3887151497Sru `0x17'-`0x1F', `0x30'-`0x3F'. 3888151497Sru 3889151497Sru Currently, some of these reserved codepoints are used internally, 3890151497Sru thus making it non-trivial to extend `gtroff' to cover Unicode or 3891151497Sru other character sets and encodings which use characters of these 3892151497Sru ranges. 3893151497Sru 3894151497Sru Note that invalid characters are removed before parsing; an 3895151497Sru identifier `foo', followed by an invalid character, followed by 3896151497Sru `bar' is treated as `foobar'. 3897151497Sru 3898151497Sru For example, any of the following is valid. 3899151497Sru 3900151497Sru 3901151497Sru br 3902151497Sru PP 3903151497Sru (l 3904151497Sru end-list 3905151497Sru @_ 3906151497Sru 3907151497SruNote that identifiers longer than two characters with a closing bracket 3908151497Sru(`]') in its name can't be accessed with escape sequences which expect 3909151497Sruan identifier as a parameter. For example, `\[foo]]' accesses the 3910151497Sruglyph `foo', followed by `]', whereas `\C'foo]'' really asks for glyph 3911151497Sru`foo]'. 3912151497Sru 3913151497Sru To avoid problems with the `refer' preprocessor, macro names should 3914151497Srunot start with `[' or `]'. Due to backwards compatibility, everything 3915151497Sruafter `.[' and `.]' is handled as a special argument to `refer'. For 3916151497Sruexample, `.[foo' makes `refer' to start a reference, using `foo' as a 3917151497Sruparameter. 3918151497Sru 3919151497Sru -- Escape: \A'ident' 3920151497Sru Test whether an identifier IDENT is valid in `gtroff'. It expands 3921151497Sru to the character 1 or 0 according to whether its argument (usually 3922151497Sru delimited by quotes) is or is not acceptable as the name of a 3923151497Sru string, macro, diversion, number register, environment, or font. 3924151497Sru It returns 0 if no argument is given. This is useful for looking 3925151497Sru up user input in some sort of associative table. 3926151497Sru 3927151497Sru 3928151497Sru \A'end-list' 3929151497Sru => 1 3930151497Sru 3931151497Sru 3932151497Sru *Note Escapes::, for details on parameter delimiting characters. 3933151497Sru 3934151497Sru Identifiers in `gtroff' can be any length, but, in some contexts, 3935151497Sru`gtroff' needs to be told where identifiers end and text begins (and in 3936151497Srudifferent ways depending on their length): 3937151497Sru 3938151497Sru * Single character. 3939151497Sru 3940151497Sru * Two characters. Must be prefixed with `(' in some situations. 3941151497Sru 3942151497Sru * Arbitrary length (`gtroff' only). Must be bracketed with `[' 3943151497Sru and `]' in some situations. Any length identifier can be put in 3944151497Sru brackets. 3945151497Sru 3946151497Sru Unlike many other programming languages, undefined identifiers are 3947151497Srusilently ignored or expanded to nothing. When `gtroff' finds an 3948151497Sruundefined identifier, it emits a warning, doing the following: 3949151497Sru 3950151497Sru * If the identifier is a string, macro, or diversion, `gtroff' 3951151497Sru defines it as empty. 3952151497Sru 3953151497Sru * If the identifier is a number register, `gtroff' defines it with a 3954151497Sru value of 0. 3955151497Sru 3956151497Sru *Note Warnings::., *Note Interpolating Registers::, and *Note 3957151497SruStrings::. 3958151497Sru 3959151497Sru Note that macros, strings, and diversions share the same name space. 3960151497Sru 3961151497Sru 3962151497Sru .de xxx 3963151497Sru . nop foo 3964151497Sru .. 3965151497Sru . 3966151497Sru .di xxx 3967151497Sru bar 3968151497Sru .br 3969151497Sru .di 3970151497Sru . 3971151497Sru .xxx 3972151497Sru => bar 3973151497Sru 3974151497SruAs can be seen in the previous example, `gtroff' reuses the identifier 3975151497Sru`xxx', changing it from a macro to a diversion. No warning is emitted! 3976151497SruThe contents of the first macro definition is lost. 3977151497Sru 3978151497Sru *Note Interpolating Registers::, and *Note Strings::. 3979151497Sru 3980151497Sru 3981151497SruFile: groff, Node: Embedded Commands, Next: Registers, Prev: Identifiers, Up: gtroff Reference 3982151497Sru 3983151497Sru5.5 Embedded Commands 3984151497Sru===================== 3985151497Sru 3986151497SruMost documents need more functionality beyond filling, adjusting and 3987151497Sruimplicit line breaking. In order to gain further functionality, 3988151497Sru`gtroff' allows commands to be embedded into the text, in two ways. 3989151497Sru 3990151497Sru The first is a "request" which takes up an entire line, and does 3991151497Srusome large-scale operation (e.g. break lines, start new pages). 3992151497Sru 3993151497Sru The other is an "escape" which can be usually embedded anywhere in 3994151497Sruthe text; most requests can accept it even as an argument. Escapes 3995151497Srugenerally do more minor operations like sub- and superscripts, print a 3996151497Srusymbol, etc. 3997151497Sru 3998151497Sru* Menu: 3999151497Sru 4000151497Sru* Requests:: 4001151497Sru* Macros:: 4002151497Sru* Escapes:: 4003151497Sru 4004151497Sru 4005151497SruFile: groff, Node: Requests, Next: Macros, Prev: Embedded Commands, Up: Embedded Commands 4006151497Sru 4007151497Sru5.5.1 Requests 4008151497Sru-------------- 4009151497Sru 4010151497SruA request line begins with a control character, which is either a single 4011151497Sruquote (`'', the "no-break control character") or a period (`.', the 4012151497Srunormal "control character"). These can be changed; see *Note Character 4013151497SruTranslations::, for details. After this there may be optional tabs or 4014151497Sruspaces followed by an identifier which is the name of the request. 4015151497SruThis may be followed by any number of space-separated arguments (_no_ 4016151497Srutabs here). 4017151497Sru 4018151497Sru Since a control character followed by whitespace only is ignored, it 4019151497Sruis common practice to use this feature for structuring the source code 4020151497Sruof documents or macro packages. 4021151497Sru 4022151497Sru 4023151497Sru .de foo 4024151497Sru . tm This is foo. 4025151497Sru .. 4026151497Sru . 4027151497Sru . 4028151497Sru .de bar 4029151497Sru . tm This is bar. 4030151497Sru .. 4031151497Sru 4032151497Sru Another possibility is to use the blank line macro request `blm' by 4033151497Sruassigning an empty macro to it. 4034151497Sru 4035151497Sru 4036151497Sru .de do-nothing 4037151497Sru .. 4038151497Sru .blm do-nothing \" activate blank line macro 4039151497Sru 4040151497Sru .de foo 4041151497Sru . tm This is foo. 4042151497Sru .. 4043151497Sru 4044151497Sru 4045151497Sru .de bar 4046151497Sru . tm This is bar. 4047151497Sru .. 4048151497Sru 4049151497Sru .blm \" deactivate blank line macro 4050151497Sru 4051151497Sru *Note Blank Line Traps::. 4052151497Sru 4053151497Sru To begin a line with a control character without it being 4054151497Sruinterpreted, precede it with `\&'. This represents a zero width space, 4055151497Sruwhich means it does not affect the output. 4056151497Sru 4057151497Sru In most cases the period is used as a control character. Several 4058151497Srurequests cause a break implicitly; using the single quote control 4059151497Srucharacter prevents this. 4060151497Sru 4061151497Sru* Menu: 4062151497Sru 4063151497Sru* Request and Macro Arguments:: 4064151497Sru 4065151497Sru 4066151497SruFile: groff, Node: Request and Macro Arguments, Prev: Requests, Up: Requests 4067151497Sru 4068151497Sru5.5.1.1 Request and Macro Arguments 4069151497Sru................................... 4070151497Sru 4071151497SruArguments to requests and macros are processed much like the shell: The 4072151497Sruline is split into arguments according to spaces.(1) (*note Request and 4073151497SruMacro Arguments-Footnote-1::) 4074151497Sru 4075151497Sru An argument to a macro which is intended to contain spaces can 4076151497Srueither be enclosed in double quotes, or have the spaces "escaped" with 4077151497Srubackslashes. This is _not_ true for requests. 4078151497Sru 4079151497Sru Here are a few examples for a hypothetical macro `uh': 4080151497Sru 4081151497Sru 4082151497Sru .uh The Mouse Problem 4083151497Sru .uh "The Mouse Problem" 4084151497Sru .uh The\ Mouse\ Problem 4085151497Sru 4086151497SruThe first line is the `uh' macro being called with 3 arguments, `The', 4087151497Sru`Mouse', and `Problem'. The latter two have the same effect of calling 4088151497Sruthe `uh' macro with one argument, `The Mouse Problem'.(2) (*note 4089151497SruRequest and Macro Arguments-Footnote-2::) 4090151497Sru 4091151497Sru A double quote which isn't preceded by a space doesn't start a macro 4092151497Sruargument. If not closing a string, it is printed literally. 4093151497Sru 4094151497Sru For example, 4095151497Sru 4096151497Sru 4097151497Sru .xxx a" "b c" "de"fg" 4098151497Sru 4099151497Sruhas the arguments `a"', `b c', `de', and `fg"'. Don't rely on this 4100151497Sruobscure behaviour! 4101151497Sru 4102151497Sru There are two possibilities to get a double quote reliably. 4103151497Sru 4104151497Sru * Enclose the whole argument with double quotes and use two 4105151497Sru consecutive double quotes to represent a single one. This 4106151497Sru traditional solution has the disadvantage that double quotes don't 4107151497Sru survive argument expansion again if called in compatibility mode 4108151497Sru (using the `-C' option of `groff'): 4109151497Sru 4110151497Sru 4111151497Sru .de xx 4112151497Sru . tm xx: `\\$1' `\\$2' `\\$3' 4113151497Sru . 4114151497Sru . yy "\\$1" "\\$2" "\\$3" 4115151497Sru .. 4116151497Sru .de yy 4117151497Sru . tm yy: `\\$1' `\\$2' `\\$3' 4118151497Sru .. 4119151497Sru .xx A "test with ""quotes""" . 4120151497Sru => xx: `A' `test with "quotes"' `.' 4121151497Sru => yy: `A' `test with ' `quotes""' 4122151497Sru 4123151497Sru If not in compatibility mode, you get the expected result 4124151497Sru 4125151497Sru 4126151497Sru xx: `A' `test with "quotes"' `.' 4127151497Sru yy: `A' `test with "quotes"' `.' 4128151497Sru 4129151497Sru since `gtroff' preserves the input level. 4130151497Sru 4131151497Sru * Use the double quote glyph `\(dq'. This works with and without 4132151497Sru compatibility mode enabled since `gtroff' doesn't convert `\(dq' 4133151497Sru back to a double quote input character. 4134151497Sru 4135151497Sru Not that this method won't work with UNIX `troff' in general since 4136151497Sru the glyph `dq' isn't defined normally. 4137151497Sru 4138151497Sru Double quotes in the `ds' request are handled differently. *Note 4139151497SruStrings::, for more details. 4140151497Sru 4141151497Sru 4142151497SruFile: groff, Node: Request and Macro Arguments-Footnotes, Up: Request and Macro Arguments 4143151497Sru 4144151497Sru (1) Plan 9's `troff' implementation also allows tabs for argument 4145151497Sruseparation - `gtroff' intentionally doesn't support this. 4146151497Sru 4147151497Sru (2) The last solution, i.e., using escaped spaces, is "classical" in 4148151497Sruthe sense that it can be found in most `troff' documents. 4149151497SruNevertheless, it is not optimal in all situations, since `\ ' inserts a 4150151497Srufixed-width, non-breaking space character which can't stretch. 4151151497Sru`gtroff' provides a different command `\~' to insert a stretchable, 4152151497Srunon-breaking space. 4153151497Sru 4154151497Sru 4155151497SruFile: groff, Node: Macros, Next: Escapes, Prev: Requests, Up: Embedded Commands 4156151497Sru 4157151497Sru5.5.2 Macros 4158151497Sru------------ 4159151497Sru 4160151497Sru`gtroff' has a "macro" facility for defining a series of lines which 4161151497Srucan be invoked by name. They are called in the same manner as requests 4162151497Sru- arguments also may be passed basically in the same manner. 4163151497Sru 4164151497Sru *Note Writing Macros::, and *Note Request and Macro Arguments::. 4165151497Sru 4166151497Sru 4167151497SruFile: groff, Node: Escapes, Prev: Macros, Up: Embedded Commands 4168151497Sru 4169151497Sru5.5.3 Escapes 4170151497Sru------------- 4171151497Sru 4172151497SruEscapes may occur anywhere in the input to `gtroff'. They usually 4173151497Srubegin with a backslash and are followed by a single character which 4174151497Sruindicates the function to be performed. The escape character can be 4175151497Sruchanged; see *Note Character Translations::. 4176151497Sru 4177151497Sru Escape sequences which require an identifier as a parameter accept 4178151497Sruthree possible syntax forms. 4179151497Sru 4180151497Sru * The next single character is the identifier. 4181151497Sru 4182151497Sru * If this single character is an opening parenthesis, take the 4183151497Sru following two characters as the identifier. Note that there is no 4184151497Sru closing parenthesis after the identifier. 4185151497Sru 4186151497Sru * If this single character is an opening bracket, take all characters 4187151497Sru until a closing bracket as the identifier. 4188151497Sru 4189151497SruExamples: 4190151497Sru 4191151497Sru 4192151497Sru \fB 4193151497Sru \n(XX 4194151497Sru \*[TeX] 4195151497Sru 4196151497Sru Other escapes may require several arguments and/or some special 4197151497Sruformat. In such cases the argument is traditionally enclosed in single 4198151497Sruquotes (and quotes are always used in this manual for the definitions 4199151497Sruof escape sequences). The enclosed text is then processed according to 4200151497Sruwhat that escape expects. Example: 4201151497Sru 4202151497Sru 4203151497Sru \l'1.5i\(bu' 4204151497Sru 4205151497Sru Note that the quote character can be replaced with any other 4206151497Srucharacter which does not occur in the argument (even a newline or a 4207151497Sruspace character) in the following escapes: `\o', `\b', and `\X'. This 4208151497Srumakes e.g. 4209151497Sru 4210151497Sru 4211151497Sru A caf 4212151497Sru \o 4213151497Sru e\' 4214151497Sru 4215151497Sru 4216151497Sru in Paris 4217151497Sru => A caf� in Paris 4218151497Sru 4219151497Srupossible, but it is better not to use this feature to avoid confusion. 4220151497Sru 4221151497Sru The following escapes sequences (which are handled similarly to 4222151497Srucharacters since they don't take a parameter) are also allowed as 4223151497Srudelimiters: `\%', `\ ', `\|', `\^', `\{', `\}', `\'', `\`', `\-', `\_', 4224151497Sru`\!', `\?', `\@', `\)', `\/', `\,', `\&', `\:', `\~', `\0', `\a', `\c', 4225151497Sru`\d', `\e', `\E', `\p', `\r', `\t', and `\u'. Again, don't use these 4226151497Sruif possible. 4227151497Sru 4228151497Sru No newline characters as delimiters are allowed in the following 4229151497Sruescapes: `\A', `\B', `\Z', `\C', and `\w'. 4230151497Sru 4231151497Sru Finally, the escapes `\D', `\h', `\H', `\l', `\L', `\N', `\R', `\s', 4232151497Sru`\S', `\v', and `\x' can't use the following characters as delimiters: 4233151497Sru 4234151497Sru * The digits `0'-`9'. 4235151497Sru 4236151497Sru * The (single-character) operators `+-/*%<>=&:().'. 4237151497Sru 4238151497Sru * The space, tab, and newline characters. 4239151497Sru 4240151497Sru * All escape sequences except `\%', `\:', `\{', `\}', `\'', `\`', 4241151497Sru `\-', `\_', `\!', `\@', `\/', `\c', `\e', and `\p'. 4242151497Sru 4243151497Sru To have a backslash (actually, the current escape character) appear 4244151497Sruin the output several escapes are defined: `\\', `\e' or `\E'. These 4245151497Sruare very similar, and only differ with respect to being used in macros 4246151497Sruor diversions. *Note Character Translations::, for an exact 4247151497Srudescription of those escapes. 4248151497Sru 4249151497Sru *Note Implementation Differences::, *Note Copy-in Mode::, and *Note 4250151497SruDiversions::, *Note Identifiers::, for more information. 4251151497Sru 4252151497Sru* Menu: 4253151497Sru 4254151497Sru* Comments:: 4255151497Sru 4256151497Sru 4257151497SruFile: groff, Node: Comments, Prev: Escapes, Up: Escapes 4258151497Sru 4259151497Sru5.5.3.1 Comments 4260151497Sru................ 4261151497Sru 4262151497SruProbably one of the most(1) (*note Comments-Footnote-1::) common forms 4263151497Sruof escapes is the comment. 4264151497Sru 4265151497Sru -- Escape: \" 4266151497Sru Start a comment. Everything to the end of the input line is 4267151497Sru ignored. 4268151497Sru 4269151497Sru This may sound simple, but it can be tricky to keep the comments 4270151497Sru from interfering with the appearance of the final output. 4271151497Sru 4272151497Sru If the escape is to the right of some text or a request, that 4273151497Sru portion of the line is ignored, but the space leading up to it is 4274151497Sru noticed by `gtroff'. This only affects the `ds' and `as' request 4275151497Sru and its variants. 4276151497Sru 4277151497Sru One possibly irritating idiosyncracy is that tabs must not be used 4278151497Sru to line up comments. Tabs are not treated as whitespace between 4279151497Sru the request and macro arguments. 4280151497Sru 4281151497Sru A comment on a line by itself is treated as a blank line, because 4282151497Sru after eliminating the comment, that is all that remains: 4283151497Sru 4284151497Sru 4285151497Sru Test 4286151497Sru \" comment 4287151497Sru Test 4288151497Sru 4289151497Sru produces 4290151497Sru 4291151497Sru 4292151497Sru Test 4293151497Sru 4294151497Sru Test 4295151497Sru 4296151497Sru To avoid this, it is common to start the line with `.\"' which 4297151497Sru causes the line to be treated as an undefined request and thus 4298151497Sru ignored completely. 4299151497Sru 4300151497Sru Another commenting scheme seen sometimes is three consecutive 4301151497Sru single quotes (`'''') at the beginning of a line. This works, but 4302151497Sru `gtroff' gives a warning about an undefined macro (namely `'''), 4303151497Sru which is harmless, but irritating. 4304151497Sru 4305151497Sru -- Escape: \# 4306151497Sru To avoid all this, `gtroff' has a new comment mechanism using the 4307151497Sru `\#' escape. This escape works the same as `\"' except that the 4308151497Sru newline is also ignored: 4309151497Sru 4310151497Sru 4311151497Sru Test 4312151497Sru \# comment 4313151497Sru Test 4314151497Sru 4315151497Sru produces 4316151497Sru 4317151497Sru 4318151497Sru Test Test 4319151497Sru 4320151497Sru as expected. 4321151497Sru 4322151497Sru -- Request: .ig [end] 4323151497Sru Ignore all input until `gtroff' encounters the macro named `.'END 4324151497Sru on a line by itself (or `..' if END is not specified). This is 4325151497Sru useful for commenting out large blocks of text: 4326151497Sru 4327151497Sru 4328151497Sru text text text... 4329151497Sru .ig 4330151497Sru This is part of a large block 4331151497Sru of text that has been 4332151497Sru temporarily(?) commented out. 4333151497Sru 4334151497Sru We can restore it simply by removing 4335151497Sru the .ig request and the ".." at the 4336151497Sru end of the block. 4337151497Sru .. 4338151497Sru More text text text... 4339151497Sru 4340151497Sru produces 4341151497Sru 4342151497Sru 4343151497Sru text text text... More text text text... 4344151497Sru 4345151497Sru Note that the commented-out block of text does not cause a break. 4346151497Sru 4347151497Sru The input is read in copy-mode; auto-incremented registers _are_ 4348151497Sru affected (*note Auto-increment::). 4349151497Sru 4350151497Sru 4351151497SruFile: groff, Node: Comments-Footnotes, Up: Comments 4352151497Sru 4353151497Sru (1) Unfortunately, this is a lie. But hopefully future `gtroff' 4354151497Sruhackers will believe it `:-)' 4355151497Sru 4356151497Sru 4357151497SruFile: groff, Node: Registers, Next: Manipulating Filling and Adjusting, Prev: Embedded Commands, Up: gtroff Reference 4358151497Sru 4359151497Sru5.6 Registers 4360151497Sru============= 4361151497Sru 4362151497SruNumeric variables in `gtroff' are called "registers". There are a 4363151497Srunumber of built-in registers, supplying anything from the date to 4364151497Srudetails of formatting parameters. 4365151497Sru 4366151497Sru *Note Identifiers::, for details on register identifiers. 4367151497Sru 4368151497Sru* Menu: 4369151497Sru 4370151497Sru* Setting Registers:: 4371151497Sru* Interpolating Registers:: 4372151497Sru* Auto-increment:: 4373151497Sru* Assigning Formats:: 4374151497Sru* Built-in Registers:: 4375151497Sru 4376151497Sru 4377151497SruFile: groff, Node: Setting Registers, Next: Interpolating Registers, Prev: Registers, Up: Registers 4378151497Sru 4379151497Sru5.6.1 Setting Registers 4380151497Sru----------------------- 4381151497Sru 4382151497SruDefine or set registers using the `nr' request or the `\R' escape. 4383151497Sru 4384151497Sru -- Request: .nr ident value 4385151497Sru -- Escape: \R'ident value' 4386151497Sru Set number register IDENT to VALUE. If IDENT doesn't exist, 4387151497Sru `gtroff' creates it. 4388151497Sru 4389151497Sru The argument to `\R' usually has to be enclosed in quotes. *Note 4390151497Sru Escapes::, for details on parameter delimiting characters. 4391151497Sru 4392151497Sru The `\R' escape doesn't produce an input token in `gtroff'; with 4393151497Sru other words, it vanishes completely after `gtroff' has processed 4394151497Sru it. 4395151497Sru 4396151497Sru For example, the following two lines are equivalent: 4397151497Sru 4398151497Sru 4399151497Sru .nr a (((17 + (3 * 4))) % 4) 4400151497Sru \R'a (((17 + (3 * 4))) % 4)' 4401151497Sru => 1 4402151497Sru 4403151497Sru Both `nr' and `\R' have two additional special forms to increment or 4404151497Srudecrement a register. 4405151497Sru 4406151497Sru -- Request: .nr ident +value 4407151497Sru -- Request: .nr ident -value 4408151497Sru -- Escape: \R'ident +value' 4409151497Sru -- Escape: \R'ident -value' 4410151497Sru Increment (decrement) register IDENT by VALUE. 4411151497Sru 4412151497Sru 4413151497Sru .nr a 1 4414151497Sru .nr a +1 4415151497Sru \na 4416151497Sru => 2 4417151497Sru 4418151497Sru To assign the negated value of a register to another register, 4419151497Sru some care must be taken to get the desired result: 4420151497Sru 4421151497Sru 4422151497Sru .nr a 7 4423151497Sru .nr b 3 4424151497Sru .nr a -\nb 4425151497Sru \na 4426151497Sru => 4 4427151497Sru .nr a (-\nb) 4428151497Sru \na 4429151497Sru => -3 4430151497Sru 4431151497Sru The surrounding parentheses prevent the interpretation of the 4432151497Sru minus sign as a decrementing operator. An alternative is to start 4433151497Sru the assignment with a `0': 4434151497Sru 4435151497Sru 4436151497Sru .nr a 7 4437151497Sru .nr b -3 4438151497Sru .nr a \nb 4439151497Sru \na 4440151497Sru => 4 4441151497Sru .nr a 0\nb 4442151497Sru \na 4443151497Sru => -3 4444151497Sru 4445151497Sru 4446151497Sru -- Request: .rr ident 4447151497Sru Remove number register IDENT. If IDENT doesn't exist, the request 4448151497Sru is ignored. 4449151497Sru 4450151497Sru -- Request: .rnn ident1 ident2 4451151497Sru Rename number register IDENT1 to IDENT2. If either IDENT1 or 4452151497Sru IDENT2 doesn't exist, the request is ignored. 4453151497Sru 4454151497Sru -- Request: .aln ident1 ident2 4455151497Sru Create an alias IDENT1 for a number register IDENT2. The new name 4456151497Sru and the old name are exactly equivalent. If IDENT1 is undefined, 4457151497Sru a warning of type `reg' is generated, and the request is ignored. 4458151497Sru *Note Debugging::, for information about warnings. 4459151497Sru 4460151497Sru 4461151497SruFile: groff, Node: Interpolating Registers, Next: Auto-increment, Prev: Setting Registers, Up: Registers 4462151497Sru 4463151497Sru5.6.2 Interpolating Registers 4464151497Sru----------------------------- 4465151497Sru 4466151497SruNumeric registers can be accessed via the `\n' escape. 4467151497Sru 4468151497Sru -- Escape: \ni 4469151497Sru -- Escape: \n(id 4470151497Sru -- Escape: \n[ident] 4471151497Sru Interpolate number register with name IDENT (one-character name I, 4472151497Sru two-character name ID). This means that the value of the register 4473151497Sru is expanded in-place while `gtroff' is parsing the input line. 4474151497Sru Nested assignments (also called indirect assignments) are possible. 4475151497Sru 4476151497Sru 4477151497Sru .nr a 5 4478151497Sru .nr as \na+\na 4479151497Sru \n(as 4480151497Sru => 10 4481151497Sru 4482151497Sru 4483151497Sru .nr a1 5 4484151497Sru .nr ab 6 4485151497Sru .ds str b 4486151497Sru .ds num 1 4487151497Sru \n[a\n[num]] 4488151497Sru => 5 4489151497Sru \n[a\*[str]] 4490151497Sru => 6 4491151497Sru 4492151497Sru 4493151497Sru 4494151497SruFile: groff, Node: Auto-increment, Next: Assigning Formats, Prev: Interpolating Registers, Up: Registers 4495151497Sru 4496151497Sru5.6.3 Auto-increment 4497151497Sru-------------------- 4498151497Sru 4499151497SruNumber registers can also be auto-incremented and auto-decremented. 4500151497SruThe increment or decrement value can be specified with a third argument 4501151497Sruto the `nr' request or `\R' escape. 4502151497Sru 4503151497Sru -- Request: .nr ident value incr 4504151497Sru Set number register IDENT to VALUE; the increment for 4505151497Sru auto-incrementing is set to INCR. Note that the `\R' escape 4506151497Sru doesn't support this notation. 4507151497Sru 4508151497Sru To activate auto-incrementing, the escape `\n' has a special syntax 4509151497Sruform. 4510151497Sru 4511151497Sru -- Escape: \n+i 4512151497Sru -- Escape: \n-i 4513151497Sru -- Escape: \n(+id 4514151497Sru -- Escape: \n(-id 4515151497Sru -- Escape: \n+(id 4516151497Sru -- Escape: \n-(id 4517151497Sru -- Escape: \n[+ident] 4518151497Sru -- Escape: \n[-ident] 4519151497Sru -- Escape: \n+[ident] 4520151497Sru -- Escape: \n-[ident] 4521151497Sru Before interpolating, increment or decrement IDENT (one-character 4522151497Sru name I, two-character name ID) by the auto-increment value as 4523151497Sru specified with the `nr' request (or the `\R' escape). If no 4524151497Sru auto-increment value has been specified, these syntax forms are 4525151497Sru identical to `\n'. 4526151497Sru 4527151497Sru For example, 4528151497Sru 4529151497Sru 4530151497Sru .nr a 0 1 4531151497Sru .nr xx 0 5 4532151497Sru .nr foo 0 -2 4533151497Sru \n+a, \n+a, \n+a, \n+a, \n+a 4534151497Sru .br 4535151497Sru \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx 4536151497Sru .br 4537151497Sru \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] 4538151497Sru 4539151497Sruproduces 4540151497Sru 4541151497Sru 4542151497Sru 1, 2, 3, 4, 5 4543151497Sru -5, -10, -15, -20, -25 4544151497Sru -2, -4, -6, -8, -10 4545151497Sru 4546151497Sru To change the increment value without changing the value of a 4547151497Sruregister (A in the example), the following can be used: 4548151497Sru 4549151497Sru 4550151497Sru .nr a \na 10 4551151497Sru 4552151497Sru 4553151497SruFile: groff, Node: Assigning Formats, Next: Built-in Registers, Prev: Auto-increment, Up: Registers 4554151497Sru 4555151497Sru5.6.4 Assigning Formats 4556151497Sru----------------------- 4557151497Sru 4558151497SruWhen a register is used in the text of an input file (as opposed to 4559151497Srupart of an expression), it is textually replaced (or interpolated) with 4560151497Srua representation of that number. This output format can be changed to 4561151497Srua variety of formats (numbers, Roman numerals, etc.). This is done 4562151497Sruusing the `af' request. 4563151497Sru 4564151497Sru -- Request: .af ident format 4565151497Sru Change the output format of a number register. The first argument 4566151497Sru IDENT is the name of the number register to be changed, and the 4567151497Sru second argument FORMAT is the output format. The following output 4568151497Sru formats are available: 4569151497Sru 4570151497Sru `1' 4571151497Sru Decimal arabic numbers. This is the default format: 0, 1, 2, 4572151497Sru 3, .... 4573151497Sru 4574151497Sru `0...0' 4575151497Sru Decimal numbers with as many digits as specified. So, `00' 4576151497Sru would result in printing numbers as 01, 02, 03, .... 4577151497Sru 4578151497Sru In fact, any digit instead of zero will do; `gtroff' only 4579151497Sru counts how many digits are specified. As a consequence, 4580151497Sru `af''s default format `1' could be specified as `0' also (and 4581151497Sru exactly this is returned by the `\g' escape, see below). 4582151497Sru 4583151497Sru `I' 4584151497Sru Upper-case Roman numerals: 0, I, II, III, IV, .... 4585151497Sru 4586151497Sru `i' 4587151497Sru Lower-case Roman numerals: 0, i, ii, iii, iv, .... 4588151497Sru 4589151497Sru `A' 4590151497Sru Upper-case letters: 0, A, B, C, ..., Z, AA, AB, .... 4591151497Sru 4592151497Sru `a' 4593151497Sru Lower-case letters: 0, a, b, c, ..., z, aa, ab, .... 4594151497Sru 4595151497Sru Omitting the number register format causes a warning of type 4596151497Sru `missing'. *Note Debugging::, for more details. Specifying a 4597151497Sru nonexistent format causes an error. 4598151497Sru 4599151497Sru The following example produces `10, X, j, 010': 4600151497Sru 4601151497Sru 4602151497Sru .nr a 10 4603151497Sru .af a 1 \" the default format 4604151497Sru \na, 4605151497Sru .af a I 4606151497Sru \na, 4607151497Sru .af a a 4608151497Sru \na, 4609151497Sru .af a 001 4610151497Sru \na 4611151497Sru 4612151497Sru The largest number representable for the `i' and `I' formats is 4613151497Sru 39999 (or -39999); UNIX `troff' uses `z' and `w' to represent 4614151497Sru 10000 and 5000 in Roman numerals, and so does `gtroff'. 4615151497Sru Currently, the correct glyphs of Roman numeral five thousand and 4616151497Sru Roman numeral ten thousand (Unicode code points `U+2182' and 4617151497Sru `U+2181', respectively) are not available. 4618151497Sru 4619151497Sru If IDENT doesn't exist, it is created. 4620151497Sru 4621151497Sru Changing the output format of a read-only register causes an 4622151497Sru error. It is necessary to first copy the register's value to a 4623151497Sru writeable register, then apply the `af' request to this other 4624151497Sru register. 4625151497Sru 4626151497Sru -- Escape: \gi 4627151497Sru -- Escape: \g(id 4628151497Sru -- Escape: \g[ident] 4629151497Sru Return the current format of the specified register IDENT 4630151497Sru (one-character name I, two-character name ID). For example, `\ga' 4631151497Sru after the previous example would produce the string `000'. If the 4632151497Sru register hasn't been defined yet, nothing is returned. 4633151497Sru 4634151497Sru 4635151497SruFile: groff, Node: Built-in Registers, Prev: Assigning Formats, Up: Registers 4636151497Sru 4637151497Sru5.6.5 Built-in Registers 4638151497Sru------------------------ 4639151497Sru 4640151497SruThe following lists some built-in registers which are not described 4641151497Sruelsewhere in this manual. Any register which begins with a `.' is 4642151497Sruread-only. A complete listing of all built-in registers can be found in 4643151497Sru*Note Register Index::. 4644151497Sru 4645151497Sru`\n[.F]' 4646151497Sru This string-valued register returns the current input file name. 4647151497Sru 4648151497Sru`\n[.H]' 4649151497Sru Horizontal resolution in basic units. 4650151497Sru 4651151497Sru`\n[.U]' 4652151497Sru If `gtroff' is called with the `-U' command line option, the 4653151497Sru number register `.U' is set to 1, and zero otherwise. *Note Groff 4654151497Sru Options::. 4655151497Sru 4656151497Sru`\n[.V]' 4657151497Sru Vertical resolution in basic units. 4658151497Sru 4659151497Sru`\n[seconds]' 4660151497Sru The number of seconds after the minute, normally in the range 0 4661151497Sru to 59, but can be up to 61 to allow for leap seconds. Initialized 4662151497Sru at start-up of `gtroff'. 4663151497Sru 4664151497Sru`\n[minutes]' 4665151497Sru The number of minutes after the hour, in the range 0 to 59. 4666151497Sru Initialized at start-up of `gtroff'. 4667151497Sru 4668151497Sru`\n[hours]' 4669151497Sru The number of hours past midnight, in the range 0 to 23. 4670151497Sru Initialized at start-up of `gtroff'. 4671151497Sru 4672151497Sru`\n[dw]' 4673151497Sru Day of the week (1-7). 4674151497Sru 4675151497Sru`\n[dy]' 4676151497Sru Day of the month (1-31). 4677151497Sru 4678151497Sru`\n[mo]' 4679151497Sru Current month (1-12). 4680151497Sru 4681151497Sru`\n[year]' 4682151497Sru The current year. 4683151497Sru 4684151497Sru`\n[yr]' 4685151497Sru The current year minus 1900. Unfortunately, the documentation of 4686151497Sru UNIX Version 7's `troff' had a year 2000 bug: It incorrectly 4687151497Sru claimed that `yr' contains the last two digits of the year. That 4688151497Sru claim has never been true of either AT&T `troff' or GNU `troff'. 4689151497Sru Old `troff' input that looks like this: 4690151497Sru 4691151497Sru 4692151497Sru '\" The following line stopped working after 1999 4693151497Sru This document was formatted in 19\n(yr. 4694151497Sru 4695151497Sru can be corrected as follows: 4696151497Sru 4697151497Sru 4698151497Sru This document was formatted in \n[year]. 4699151497Sru 4700151497Sru or, to be portable to older `troff' versions, as follows: 4701151497Sru 4702151497Sru 4703151497Sru .nr y4 1900+\n(yr 4704151497Sru This document was formatted in \n(y4. 4705151497Sru 4706151497Sru`\n[.c]' 4707151497Sru`\n[c.]' 4708151497Sru The current _input_ line number. Register `.c' is read-only, 4709151497Sru whereas `c.' (a `gtroff' extension) is writable also, affecting 4710151497Sru both `.c' and `c.'. 4711151497Sru 4712151497Sru`\n[ln]' 4713151497Sru The current _output_ line number after a call to the `nm' request 4714151497Sru to activate line numbering. 4715151497Sru 4716151497Sru *Note Miscellaneous::, for more information about line numbering. 4717151497Sru 4718151497Sru`\n[.x]' 4719151497Sru The major version number. For example, if the version number is 4720151497Sru 1.03 then `.x' contains `1'. 4721151497Sru 4722151497Sru`\n[.y]' 4723151497Sru The minor version number. For example, if the version number is 4724151497Sru 1.03 then `.y' contains `03'. 4725151497Sru 4726151497Sru`\n[.Y]' 4727151497Sru The revision number of `groff'. 4728151497Sru 4729151497Sru`\n[$$]' 4730151497Sru The process ID of `gtroff'. 4731151497Sru 4732151497Sru`\n[.g]' 4733151497Sru Always 1. Macros should use this to determine whether they are 4734151497Sru running under GNU `troff'. 4735151497Sru 4736151497Sru`\n[.A]' 4737151497Sru If the command line option `-a' is used to produce an ASCII 4738151497Sru approximation of the output, this is set to 1, zero otherwise. 4739151497Sru *Note Groff Options::. 4740151497Sru 4741151497Sru`\n[.P]' 4742151497Sru This register is set to 1 (and to 0 otherwise) if the current page 4743151497Sru is actually being printed, i.e., if the `-o' option is being used 4744151497Sru to only print selected pages. *Note Groff Options::, for more 4745151497Sru information. 4746151497Sru 4747151497Sru`\n[.T]' 4748151497Sru If `gtroff' is called with the `-T' command line option, the 4749151497Sru number register `.T' is set to 1, and zero otherwise. *Note Groff 4750151497Sru Options::. 4751151497Sru 4752151497Sru`\*[.T]' 4753151497Sru A single read-write string register which contains the current 4754151497Sru output device (for example, `latin1' or `ps'). This is the only 4755151497Sru string register defined by `gtroff'. 4756151497Sru 4757151497Sru 4758151497SruFile: groff, Node: Manipulating Filling and Adjusting, Next: Manipulating Hyphenation, Prev: Registers, Up: gtroff Reference 4759151497Sru 4760151497Sru5.7 Manipulating Filling and Adjusting 4761151497Sru====================================== 4762151497Sru 4763151497SruVarious ways of causing "breaks" were given in *Note Implicit Line 4764151497SruBreaks::. The `br' request likewise causes a break. Several other 4765151497Srurequests also cause breaks, but implicitly. These are `bp', `ce', 4766151497Sru`cf', `fi', `fl', `in', `nf', `rj', `sp', `ti', and `trf'. 4767151497Sru 4768151497Sru -- Request: .br 4769151497Sru Break the current line, i.e., the input collected so far is emitted 4770151497Sru without adjustment. 4771151497Sru 4772151497Sru If the no-break control character is used, `gtroff' suppresses the 4773151497Sru break: 4774151497Sru 4775151497Sru 4776151497Sru a 4777151497Sru 'br 4778151497Sru b 4779151497Sru => a b 4780151497Sru 4781151497Sru 4782151497Sru Initially, `gtroff' fills and adjusts text to both margins. Filling 4783151497Srucan be disabled via the `nf' request and re-enabled with the `fi' 4784151497Srurequest. 4785151497Sru 4786151497Sru -- Request: .fi 4787151497Sru -- Register: \n[.u] 4788151497Sru Activate fill mode (which is the default). This request implicitly 4789151497Sru enables adjusting; it also inserts a break in the text currently 4790151497Sru being filled. The read-only number register `.u' is set to 1. 4791151497Sru 4792151497Sru The fill mode status is associated with the current environment 4793151497Sru (*note Environments::). 4794151497Sru 4795151497Sru See *Note Line Control::, for interaction with the `\c' escape. 4796151497Sru 4797151497Sru -- Request: .nf 4798151497Sru Activate no-fill mode. Input lines are output as-is, retaining 4799151497Sru line breaks and ignoring the current line length. This command 4800151497Sru implicitly disables adjusting; it also causes a break. The number 4801151497Sru register `.u' is set to 0. 4802151497Sru 4803151497Sru The fill mode status is associated with the current environment 4804151497Sru (*note Environments::). 4805151497Sru 4806151497Sru See *Note Line Control::, for interaction with the `\c' escape. 4807151497Sru 4808151497Sru -- Request: .ad [mode] 4809151497Sru -- Register: \n[.j] 4810151497Sru Set adjusting mode. 4811151497Sru 4812151497Sru Activation and deactivation of adjusting is done implicitly with 4813151497Sru calls to the `fi' or `nf' requests. 4814151497Sru 4815151497Sru MODE can have one of the following values: 4816151497Sru 4817151497Sru `l' 4818151497Sru Adjust text to the left margin. This produces what is 4819151497Sru traditionally called ragged-right text. 4820151497Sru 4821151497Sru `r' 4822151497Sru Adjust text to the right margin, producing ragged-left text. 4823151497Sru 4824151497Sru `c' 4825151497Sru Center filled text. This is different to the `ce' request 4826151497Sru which only centers text without filling. 4827151497Sru 4828151497Sru `b' 4829151497Sru `n' 4830151497Sru Justify to both margins. This is the default used by 4831151497Sru `gtroff'. 4832151497Sru 4833151497Sru Finally, MODE can be the numeric argument returned by the `.j' 4834151497Sru register. 4835151497Sru 4836151497Sru With no argument, `gtroff' adjusts lines in the same way it did 4837151497Sru before adjusting was deactivated (with a call to `na', for 4838151497Sru example). 4839151497Sru 4840151497Sru 4841151497Sru text 4842151497Sru .ad r 4843151497Sru .nr ad \n[.j] 4844151497Sru text 4845151497Sru .ad c 4846151497Sru text 4847151497Sru .na 4848151497Sru text 4849151497Sru .ad \" back to centering 4850151497Sru text 4851151497Sru .ad \n[ad] \" back to right justifying 4852151497Sru 4853151497Sru The current adjustment mode is available in the read-only number 4854151497Sru register `.j'; it can be stored and subsequently used to set 4855151497Sru adjustment. 4856151497Sru 4857151497Sru The adjustment mode status is associated with the current 4858151497Sru environment (*note Environments::). 4859151497Sru 4860151497Sru -- Request: .na 4861151497Sru Disable adjusting. This request won't change the current 4862151497Sru adjustment mode: A subsequent call to `ad' uses the previous 4863151497Sru adjustment setting. 4864151497Sru 4865151497Sru The adjustment mode status is associated with the current 4866151497Sru environment (*note Environments::). 4867151497Sru 4868151497Sru -- Request: .brp 4869151497Sru -- Escape: \p 4870151497Sru Adjust the current line and cause a break. 4871151497Sru 4872151497Sru In most cases this produces very ugly results since `gtroff' 4873151497Sru doesn't have a sophisticated paragraph building algorithm (as TeX 4874151497Sru have, for example); instead, `gtroff' fills and adjusts a paragraph 4875151497Sru line by line: 4876151497Sru 4877151497Sru 4878151497Sru This is an uninteresting sentence. 4879151497Sru This is an uninteresting sentence.\p 4880151497Sru This is an uninteresting sentence. 4881151497Sru 4882151497Sru is formatted as 4883151497Sru 4884151497Sru 4885151497Sru This is an uninteresting sentence. This is an 4886151497Sru uninteresting sentence. 4887151497Sru This is an uninteresting sentence. 4888151497Sru 4889151497Sru 4890151497Sru -- Request: .ss word_space_size [sentence_space_size] 4891151497Sru -- Register: \n[.ss] 4892151497Sru -- Register: \n[.sss] 4893151497Sru Change the size of a space between words. It takes its units as 4894151497Sru one twelfth of the space width parameter for the current font. 4895151497Sru Initially both the WORD_SPACE_SIZE and SENTENCE_SPACE_SIZE are 12. 4896151497Sru In fill mode, the values specify the minimum distance. 4897151497Sru 4898151497Sru If two arguments are given to the `ss' request, the second 4899151497Sru argument sets the sentence space size. If the second argument is 4900151497Sru not given, sentence space size is set to WORD_SPACE_SIZE. The 4901151497Sru sentence space size is used in two circumstances: If the end of a 4902151497Sru sentence occurs at the end of a line in fill mode, then both an 4903151497Sru inter-word space and a sentence space are added; if two spaces 4904151497Sru follow the end of a sentence in the middle of a line, then the 4905151497Sru second space is a sentence space. If a second argument is never 4906151497Sru given to the `ss' request, the behaviour of UNIX `troff' is the 4907151497Sru same as that exhibited by GNU `troff'. In GNU `troff', as in UNIX 4908151497Sru `troff', a sentence should always be followed by either a newline 4909151497Sru or two spaces. 4910151497Sru 4911151497Sru The read-only number registers `.ss' and `.sss' hold the values of 4912151497Sru the parameters set by the first and second arguments of the `ss' 4913151497Sru request. 4914151497Sru 4915151497Sru The word space and sentence space values are associated with the 4916151497Sru current environment (*note Environments::). 4917151497Sru 4918151497Sru Contrary to AT&T `troff', this request is _not_ ignored if a TTY 4919151497Sru output device is used; the given values are then rounded down to a 4920151497Sru multiple of 12 (*note Implementation Differences::). 4921151497Sru 4922151497Sru The request is ignored if there is no parameter. 4923151497Sru 4924151497Sru Another useful application of the `ss' request is to insert 4925151497Sru discardable horizontal space, i.e., space which is discarded at a 4926151497Sru line break. For example, paragraph-style footnotes could be 4927151497Sru separated this way: 4928151497Sru 4929151497Sru 4930151497Sru .ll 4.5i 4931151497Sru 1.\ This is the first footnote.\c 4932151497Sru .ss 48 4933151497Sru .nop 4934151497Sru .ss 12 4935151497Sru 2.\ This is the second footnote. 4936151497Sru 4937151497Sru The result: 4938151497Sru 4939151497Sru 4940151497Sru 1. This is the first footnote. 2. This 4941151497Sru is the second footnote. 4942151497Sru 4943151497Sru Note that the `\h' escape produces unbreakable space. 4944151497Sru 4945151497Sru -- Request: .ce [nnn] 4946151497Sru -- Register: \n[.ce] 4947151497Sru Center text. While the `.ad c' request also centers text, it 4948151497Sru fills the text as well. `ce' does not fill the text it affects. 4949151497Sru This request causes a break. The number of lines still to be 4950151497Sru centered is associated with the current environment (*note 4951151497Sru Environments::). 4952151497Sru 4953151497Sru The following example demonstrates the differences. Here the 4954151497Sru input: 4955151497Sru 4956151497Sru 4957151497Sru .ll 4i 4958151497Sru .ce 1000 4959151497Sru This is a small text fragment which shows the differences 4960151497Sru between the `.ce' and the `.ad c' request. 4961151497Sru .ce 0 4962151497Sru 4963151497Sru .ad c 4964151497Sru This is a small text fragment which shows the differences 4965151497Sru between the `.ce' and the `.ad c' request. 4966151497Sru 4967151497Sru And here the result: 4968151497Sru 4969151497Sru 4970151497Sru This is a small text fragment which 4971151497Sru shows the differences 4972151497Sru between the `.ce' and the `.ad c' request. 4973151497Sru 4974151497Sru This is a small text fragment which 4975151497Sru shows the differences between the `.ce' 4976151497Sru and the `.ad c' request. 4977151497Sru 4978151497Sru With no arguments, `ce' centers the next line of text. NNN 4979151497Sru specifies the number of lines to be centered. If the argument is 4980151497Sru zero or negative, centering is disabled. 4981151497Sru 4982151497Sru The basic length for centering text is the line length (as set 4983151497Sru with the `ll' request) minus the indentation (as set with the `in' 4984151497Sru request). Temporary indentation is ignored. 4985151497Sru 4986151497Sru As can be seen in the previous example, it is a common idiom to 4987151497Sru turn on centering for a large number of lines, and to turn off 4988151497Sru centering after text to be centered. This is useful for any 4989151497Sru request which takes a number of lines as an argument. 4990151497Sru 4991151497Sru The `.ce' read-only number register contains the number of lines 4992151497Sru remaining to be centered, as set by the `ce' request. 4993151497Sru 4994151497Sru -- Request: .rj [nnn] 4995151497Sru -- Register: \n[.rj] 4996151497Sru Justify unfilled text to the right margin. Arguments are 4997151497Sru identical to the `ce' request. The `.rj' read-only number 4998151497Sru register is the number of lines to be right-justified as set by 4999151497Sru the `rj' request. This request causes a break. The number of 5000151497Sru lines still to be right-justified is associated with the current 5001151497Sru environment (*note Environments::). 5002151497Sru 5003151497Sru 5004151497SruFile: groff, Node: Manipulating Hyphenation, Next: Manipulating Spacing, Prev: Manipulating Filling and Adjusting, Up: gtroff Reference 5005151497Sru 5006151497Sru5.8 Manipulating Hyphenation 5007151497Sru============================ 5008151497Sru 5009151497SruHere a description of requests which influence hyphenation. 5010151497Sru 5011151497Sru -- Request: .hy [mode] 5012151497Sru -- Register: \n[.hy] 5013151497Sru Enable hyphenation. The request has an optional numeric argument, 5014151497Sru MODE, to restrict hyphenation if necessary: 5015151497Sru 5016151497Sru `1' 5017151497Sru The default argument if MODE is omitted. Hyphenate without 5018151497Sru restrictions. This is also the start-up value of `gtroff'. 5019151497Sru 5020151497Sru `2' 5021151497Sru Do not hyphenate the last word on a page or column. 5022151497Sru 5023151497Sru `4' 5024151497Sru Do not hyphenate the last two characters of a word. 5025151497Sru 5026151497Sru `8' 5027151497Sru Do not hyphenate the first two characters of a word. 5028151497Sru 5029151497Sru Values in the previous table are additive. For example, the 5030151497Sru value 12 causes `gtroff' to neither hyphenate the last two nor the 5031151497Sru first two characters of a word. 5032151497Sru 5033151497Sru The current hyphenation restrictions can be found in the read-only 5034151497Sru number register `.hy'. 5035151497Sru 5036151497Sru The hyphenation mode is associated with the current environment 5037151497Sru (*note Environments::). 5038151497Sru 5039151497Sru -- Request: .nh 5040151497Sru Disable hyphenation (i.e., set the hyphenation mode to zero). Note 5041151497Sru that the hyphenation mode of the last call to `hy' is not 5042151497Sru remembered. 5043151497Sru 5044151497Sru The hyphenation mode is associated with the current environment 5045151497Sru (*note Environments::). 5046151497Sru 5047151497Sru -- Request: .hlm [nnn] 5048151497Sru -- Register: \n[.hlm] 5049151497Sru -- Register: \n[.hlc] 5050151497Sru Set the maximum number of consecutive hyphenated lines to NNN. If 5051151497Sru this number is negative, there is no maximum. The default value 5052151497Sru is -1 if NNN is omitted. This value is associated with the 5053151497Sru current environment (*note Environments::). Only lines output 5054151497Sru from a given environment count towards the maximum associated with 5055151497Sru that environment. Hyphens resulting from `\%' are counted; 5056151497Sru explicit hyphens are not. 5057151497Sru 5058151497Sru The current setting of `hlm' is available in the `.hlm' read-only 5059151497Sru number register. Also the number of immediately preceding 5060151497Sru consecutive hyphenated lines are available in the read-only number 5061151497Sru register `.hlc'. 5062151497Sru 5063151497Sru -- Request: .hw word1 word2 ... 5064151497Sru Define how WORD1, WORD2, etc. are to be hyphenated. The words 5065151497Sru must be given with hyphens at the hyphenation points. For example: 5066151497Sru 5067151497Sru 5068151497Sru .hw in-sa-lub-rious 5069151497Sru 5070151497Sru Besides the space character, any character whose hyphenation code 5071151497Sru value is zero can be used to separate the arguments of `hw' (see 5072151497Sru the documentation for the `hcode' request below for more 5073151497Sru information). In addition, this request can be used more than 5074151497Sru once. 5075151497Sru 5076151497Sru Hyphenation exceptions specified with the `hw' request are 5077151497Sru associated with the current hyphenation language; it causes an 5078151497Sru error if there is no current hyphenation language. 5079151497Sru 5080151497Sru This request is ignored if there is no parameter. 5081151497Sru 5082151497Sru In old versions of `troff' there was a limited amount of space to 5083151497Sru store such information; fortunately, with `gtroff', this is no 5084151497Sru longer a restriction. 5085151497Sru 5086151497Sru -- Escape: \% 5087151497Sru -- Escape: \: 5088151497Sru To tell `gtroff' how to hyphenate words on the fly, use the `\%' 5089151497Sru escape, also known as the "hyphenation character". Preceding a 5090151497Sru word with this character prevents it from being hyphenated; 5091151497Sru putting it inside a word indicates to `gtroff' that the word may 5092151497Sru be hyphenated at that point. Note that this mechanism only 5093151497Sru affects that one occurrence of the word; to change the hyphenation 5094151497Sru of a word for the entire document, use the `hw' request. 5095151497Sru 5096151497Sru The `\:' escape inserts a zero-width break point (that is, the 5097151497Sru word breaks but without adding a hyphen). 5098151497Sru 5099151497Sru 5100151497Sru ... check the /var/log/\:httpd/\:access_log file ... 5101151497Sru 5102151497Sru Note that `\X' and `\Y' start a word, that is, the `\%' escape in 5103151497Sru (say) `\X'...'\%foobar' and `\Y'...'\%foobar' no longer prevents 5104151497Sru hyphenation but inserts a hyphenation point at the beginning of 5105151497Sru `foobar'; most likely this isn't what you want to do. 5106151497Sru 5107151497Sru -- Request: .hc [char] 5108151497Sru Change the hyphenation character to CHAR. This character then 5109151497Sru works the same as the `\%' escape, and thus, no longer appears in 5110151497Sru the output. Without an argument, `hc' resets the hyphenation 5111151497Sru character to be `\%' (the default) only. 5112151497Sru 5113151497Sru The hyphenation character is associated with the current 5114151497Sru environment (*note Environments::). 5115151497Sru 5116151497Sru -- Request: .hpf pattern_file 5117151497Sru -- Request: .hpfa pattern_file 5118151497Sru -- Request: .hpfcode a b [c d ...] 5119151497Sru Read in a file of hyphenation patterns. This file is searched for 5120151497Sru in the same way as `NAME.tmac' (or `tmac.NAME') is searched for if 5121151497Sru the `-mNAME' option is specified. 5122151497Sru 5123151497Sru It should have the same format as (simple) TeX patterns files. 5124151497Sru More specifically, the following scanning rules are implemented. 5125151497Sru 5126151497Sru * A percent sign starts a comment (up to the end of the line) 5127151497Sru even if preceded by a backslash. 5128151497Sru 5129151497Sru * No support for `digraphs' like `\$'. 5130151497Sru 5131151497Sru * `^^XX' (X is 0-9 or a-f) and `^^X' (character code of X in 5132151497Sru the range 0-127) are recognized; other use of `^' causes an 5133151497Sru error. 5134151497Sru 5135151497Sru * No macro expansion. 5136151497Sru 5137151497Sru * `hpf' checks for the expression `\patterns{...}' (possibly 5138151497Sru with whitespace before and after the braces). Everything 5139151497Sru between the braces is taken as hyphenation patterns. 5140151497Sru Consequently, `{' and `}' are not allowed in patterns. 5141151497Sru 5142151497Sru * Similarly, `\hyphenation{...}' gives a list of hyphenation 5143151497Sru exceptions. 5144151497Sru 5145151497Sru * `\endinput' is recognized also. 5146151497Sru 5147151497Sru * For backwards compatibility, if `\patterns' is missing, the 5148151497Sru whole file is treated as a list of hyphenation patterns (only 5149151497Sru recognizing the `%' character as the start of a comment). 5150151497Sru 5151151497Sru If no `hpf' request is specified (either in the document or in a 5152151497Sru macro package), `gtroff' won't hyphenate at all. 5153151497Sru 5154151497Sru The `hpfa' request appends a file of patterns to the current list. 5155151497Sru 5156151497Sru The `hpfcode' request defines mapping values for character codes in 5157151497Sru hyphenation patterns. `hpf' or `hpfa' then apply the mapping 5158151497Sru (after reading the patterns) before replacing or appending them to 5159151497Sru the current list of patterns. Its arguments are pairs of 5160151497Sru character codes - integers from 0 to 255. The request maps 5161151497Sru character code A to code B, code C to code D, and so on. You can 5162151497Sru use character codes which would be invalid otherwise. 5163151497Sru 5164151497Sru The set of hyphenation patterns is associated with the current 5165151497Sru language set by the `hla' request. The `hpf' request is usually 5166151497Sru invoked by the `troffrc' or `troffrc-end' file; by default, 5167151497Sru `troffrc' loads hyphenation patterns and exceptions for American 5168151497Sru English (in files `hyphen.us' and `hyphenex.us'). 5169151497Sru 5170151497Sru A second call to `hpf' (for the same language) will replace the 5171151497Sru hyphenation patterns with the new ones. 5172151497Sru 5173151497Sru Invoking `hpf' causes an error if there is no current hyphenation 5174151497Sru language. 5175151497Sru 5176151497Sru -- Request: .hcode c1 code1 [c2 code2 ...] 5177151497Sru Set the hyphenation code of character C1 to CODE1, that of C2 to 5178151497Sru CODE2, etc. A hyphenation code must be a single input character 5179151497Sru (not a special character) other than a digit or a space. 5180151497Sru 5181151497Sru To make hyphenation work, hyphenation codes must be set up. At 5182151497Sru start-up, groff only assigns hyphenation codes to the letters 5183151497Sru `a'-`z' (mapped to themselves) and to the letters `A'-`Z' (mapped 5184151497Sru to `a'-`z'); all other hyphenation codes are set to zero. 5185151497Sru Normally, hyphenation patterns contain only lowercase letters 5186151497Sru which should be applied regardless of case. With other words, the 5187151497Sru words `FOO' and `Foo' should be hyphenated exactly the same way as 5188151497Sru the word `foo' is hyphenated, and this is what `hcode' is good 5189151497Sru for. Words which contain other letters won't be hyphenated 5190151497Sru properly if the corresponding hyphenation patterns actually do 5191151497Sru contain them. For example, the following `hcode' requests are 5192151497Sru necessary to assign hyphenation codes to the letters `�������' 5193151497Sru (this is needed for German): 5194151497Sru 5195151497Sru 5196151497Sru .hcode � � � � 5197151497Sru .hcode � � � � 5198151497Sru .hcode � � � � 5199151497Sru .hcode � � 5200151497Sru 5201151497Sru Without those assignments, groff treats German words like 5202151497Sru `Kinderg�rten' (the plural form of `kindergarten') as two 5203151497Sru substrings `kinderg' and `rten' because the hyphenation code of 5204151497Sru the umlaut a is zero by default. There is a German hyphenation 5205151497Sru pattern which covers `kinder', so groff finds the hyphenation 5206151497Sru `kin-der'. The other two hyphenation points (`kin-der-g�r-ten') 5207151497Sru are missed. 5208151497Sru 5209151497Sru This request is ignored if it has no parameter. 5210151497Sru 5211151497Sru -- Request: .hym [length] 5212151497Sru -- Register: \n[.hym] 5213151497Sru Set the (right) hyphenation margin to LENGTH. If the current 5214151497Sru adjustment mode is not `b' or `n', the line is not hyphenated if 5215151497Sru it is shorter than LENGTH. Without an argument, the hyphenation 5216151497Sru margin is reset to its default value, which is 0. The default 5217151497Sru scaling indicator for this request is `m'. The hyphenation margin 5218151497Sru is associated with the current environment (*note Environments::). 5219151497Sru 5220151497Sru A negative argument resets the hyphenation margin to zero, emitting 5221151497Sru a warning of type `range'. 5222151497Sru 5223151497Sru The current hyphenation margin is available in the `.hym' read-only 5224151497Sru number register. 5225151497Sru 5226151497Sru -- Request: .hys [hyphenation_space] 5227151497Sru -- Register: \n[.hys] 5228151497Sru Set the hyphenation space to HYPHENATION_SPACE. If the current 5229151497Sru adjustment mode is `b' or `n', don't hyphenate the line if it can 5230151497Sru be justified by adding no more than HYPHENATION_SPACE extra space 5231151497Sru to each word space. Without argument, the hyphenation space is 5232151497Sru set to its default value, which is 0. The default scaling 5233151497Sru indicator for this request is `m'. The hyphenation space is 5234151497Sru associated with the current environment (*note Environments::). 5235151497Sru 5236151497Sru A negative argument resets the hyphenation space to zero, emitting 5237151497Sru a warning of type `range'. 5238151497Sru 5239151497Sru The current hyphenation space is available in the `.hys' read-only 5240151497Sru number register. 5241151497Sru 5242151497Sru -- Request: .shc [glyph] 5243151497Sru Set the "soft hyphen character" to GLYPH.(1) (*note Manipulating 5244151497Sru Hyphenation-Footnote-1::) If the argument is omitted, the soft 5245151497Sru hyphen character is set to the default glyph `\(hy' (this is the 5246151497Sru start-up value of `gtroff' also). The soft hyphen character is 5247151497Sru the glyph that is inserted when a word is hyphenated at a line 5248151497Sru break. If the soft hyphen character does not exist in the font of 5249151497Sru the character immediately preceding a potential break point, then 5250151497Sru the line is not broken at that point. Neither definitions 5251151497Sru (specified with the `char' request) nor translations (specified 5252151497Sru with the `tr' request) are considered when finding the soft hyphen 5253151497Sru character. 5254151497Sru 5255151497Sru -- Request: .hla language 5256151497Sru -- Register: \n[.hla] 5257151497Sru Set the current hyphenation language to the string LANGUAGE. 5258151497Sru Hyphenation exceptions specified with the `hw' request and 5259151497Sru hyphenation patterns specified with the `hpf' and `hpfa' requests 5260151497Sru are both associated with the current hyphenation language. The 5261151497Sru `hla' request is usually invoked by the `troffrc' or the 5262151497Sru `troffrc-end' files; `troffrc' sets the default language to `us'. 5263151497Sru 5264151497Sru The current hyphenation language is available as a string in the 5265151497Sru read-only number register `.hla'. 5266151497Sru 5267151497Sru 5268151497Sru .ds curr_language \n[.hla] 5269151497Sru \*[curr_language] 5270151497Sru => us 5271151497Sru 5272151497Sru 5273151497Sru 5274151497SruFile: groff, Node: Manipulating Hyphenation-Footnotes, Up: Manipulating Hyphenation 5275151497Sru 5276151497Sru (1) "Soft hyphen character" is a misnomer since it is an output 5277151497Sruglyph. 5278151497Sru 5279151497Sru 5280151497SruFile: groff, Node: Manipulating Spacing, Next: Tabs and Fields, Prev: Manipulating Hyphenation, Up: gtroff Reference 5281151497Sru 5282151497Sru5.9 Manipulating Spacing 5283151497Sru======================== 5284151497Sru 5285151497Sru -- Request: .sp [distance] 5286151497Sru Space downwards DISTANCE. With no argument it advances 1 line. A 5287151497Sru negative argument causes `gtroff' to move up the page the 5288151497Sru specified distance. If the argument is preceded by a `|' then 5289151497Sru `gtroff' moves that distance from the top of the page. This 5290151497Sru request causes a line break. The default scaling indicator is `v'. 5291151497Sru 5292151497Sru If a vertical trap is sprung during execution of `sp', the amount 5293151497Sru of vertical space after the trap is discarded. For example, this 5294151497Sru 5295151497Sru 5296151497Sru .de xxx 5297151497Sru .. 5298151497Sru . 5299151497Sru .wh 0 xxx 5300151497Sru . 5301151497Sru .pl 5v 5302151497Sru foo 5303151497Sru .sp 2 5304151497Sru bar 5305151497Sru .sp 50 5306151497Sru baz 5307151497Sru 5308151497Sru results in 5309151497Sru 5310151497Sru 5311151497Sru foo 5312151497Sru 5313151497Sru 5314151497Sru bar 5315151497Sru 5316151497Sru baz 5317151497Sru 5318151497Sru The amount of discarded space is available in the number register 5319151497Sru `.trunc'. 5320151497Sru 5321151497Sru To protect `sp' against vertical traps, use the `vpt' request: 5322151497Sru 5323151497Sru 5324151497Sru .vpt 0 5325151497Sru .sp -3 5326151497Sru .vpt 1 5327151497Sru 5328151497Sru 5329151497Sru -- Request: .ls [nnn] 5330151497Sru -- Register: \n[.L] 5331151497Sru Output NNN-1 blank lines after each line of text. With no 5332151497Sru argument, `gtroff' uses the previous value before the last `ls' 5333151497Sru call. 5334151497Sru 5335151497Sru 5336151497Sru .ls 2 \" This causes double-spaced output 5337151497Sru .ls 3 \" This causes triple-spaced output 5338151497Sru .ls \" Again double-spaced 5339151497Sru 5340151497Sru The line spacing is associated with the current environment (*note 5341151497Sru Environments::). 5342151497Sru 5343151497Sru The read-only number register `.L' contains the current line 5344151497Sru spacing setting. 5345151497Sru 5346151497Sru *Note Changing Type Sizes::, for the requests `vs' and `pvs' as 5347151497Srualternatives to `ls'. 5348151497Sru 5349151497Sru -- Escape: \x'spacing' 5350151497Sru -- Register: \n[.a] 5351151497Sru Sometimes, extra vertical spacing is only needed occasionally, e.g. 5352151497Sru to allow space for a tall construct (like an equation). The `\x' 5353151497Sru escape does this. The escape is given a numerical argument, 5354151497Sru usually enclosed in quotes (like `\x'3p''); the default scaling 5355151497Sru indicator is `v'. If this number is positive extra vertical space 5356151497Sru is inserted below the current line. A negative number adds space 5357151497Sru above. If this escape is used multiple times on the same line, 5358151497Sru the maximum of the values is used. 5359151497Sru 5360151497Sru *Note Escapes::, for details on parameter delimiting characters. 5361151497Sru 5362151497Sru The `.a' read-only number register contains the most recent 5363151497Sru (nonnegative) extra vertical line space. 5364151497Sru 5365151497Sru Using `\x' can be necessary in combination with the `\b' escape, 5366151497Sru as the following example shows. 5367151497Sru 5368151497Sru 5369151497Sru This is a test with the \[rs]b escape. 5370151497Sru .br 5371151497Sru This is a test with the \[rs]b escape. 5372151497Sru .br 5373151497Sru This is a test with \b'xyz'\x'-1m'\x'1m'. 5374151497Sru .br 5375151497Sru This is a test with the \[rs]b escape. 5376151497Sru .br 5377151497Sru This is a test with the \[rs]b escape. 5378151497Sru 5379151497Sru produces 5380151497Sru 5381151497Sru 5382151497Sru This is a test with the \b escape. 5383151497Sru This is a test with the \b escape. 5384151497Sru x 5385151497Sru This is a test with y. 5386151497Sru z 5387151497Sru This is a test with the \b escape. 5388151497Sru This is a test with the \b escape. 5389151497Sru 5390151497Sru 5391151497Sru -- Request: .ns 5392151497Sru -- Request: .rs 5393151497Sru -- Register: \n[.ns] 5394151497Sru Enable "no-space mode". In this mode, spacing (either via `sp' or 5395151497Sru via blank lines) is disabled. The `bp' request to advance to the 5396151497Sru next page is also disabled, except if it is accompanied by a page 5397151497Sru number (see *Note Page Control::, for more information). This 5398151497Sru mode ends when actual text is output or the `rs' request is 5399151497Sru encountered which ends no-space mode. The read-only number 5400151497Sru register `.ns' is set to 1 as long as no-space mode is active. 5401151497Sru 5402151497Sru This request is useful for macros that conditionally insert 5403151497Sru vertical space before the text starts (for example, a paragraph 5404151497Sru macro could insert some space except when it is the first 5405151497Sru paragraph after a section header). 5406151497Sru 5407151497Sru 5408151497SruFile: groff, Node: Tabs and Fields, Next: Character Translations, Prev: Manipulating Spacing, Up: gtroff Reference 5409151497Sru 5410151497Sru5.10 Tabs and Fields 5411151497Sru==================== 5412151497Sru 5413151497SruA tab character (ASCII char 9, EBCDIC char 5) causes a horizontal 5414151497Srumovement to the next tab stop (much like it did on a typewriter). 5415151497Sru 5416151497Sru -- Escape: \t 5417151497Sru This escape is a non-interpreted tab character. In copy mode 5418151497Sru (*note Copy-in Mode::), `\t' is the same as a real tab character. 5419151497Sru 5420151497Sru -- Request: .ta [n1 n2 ... nn T r1 r2 ... rn] 5421151497Sru -- Register: \n[.tabs] 5422151497Sru Change tab stop positions. This request takes a series of tab 5423151497Sru specifiers as arguments (optionally divided into two groups with 5424151497Sru the letter `T') which indicate where each tab stop is to be 5425151497Sru (overriding any previous settings). 5426151497Sru 5427151497Sru Tab stops can be specified absolutely, i.e., as the distance from 5428151497Sru the left margin. For example, the following sets 6 tab stops every 5429151497Sru one inch. 5430151497Sru 5431151497Sru 5432151497Sru .ta 1i 2i 3i 4i 5i 6i 5433151497Sru 5434151497Sru Tab stops can also be specified using a leading `+' which means 5435151497Sru that the specified tab stop is set relative to the previous tab 5436151497Sru stop. For example, the following is equivalent to the previous 5437151497Sru example. 5438151497Sru 5439151497Sru 5440151497Sru .ta 1i +1i +1i +1i +1i +1i 5441151497Sru 5442151497Sru `gtroff' supports an extended syntax to specify repeat values after 5443151497Sru the `T' mark (these values are always taken as relative) - this is 5444151497Sru the usual way to specify tabs set at equal intervals. The 5445151497Sru following is, yet again, the same as the previous examples. It 5446151497Sru does even more since it defines an infinite number of tab stops 5447151497Sru separated by one inch. 5448151497Sru 5449151497Sru 5450151497Sru .ta T 1i 5451151497Sru 5452151497Sru Now we are ready to interpret the full syntax given at the 5453151497Sru beginning: Set tabs at positions N1, N2, ..., NN and then set tabs 5454151497Sru at NN+R1, NN+R2, ..., NN+RN and then at NN+RN+R1, NN+RN+R2, ..., 5455151497Sru NN+RN+RN, and so on. 5456151497Sru 5457151497Sru Example: `4c +6c T 3c 5c 2c' is equivalent to `4c 10c 13c 18c 20c 5458151497Sru 23c 28c 30c ...'. 5459151497Sru 5460151497Sru The material in each tab column (i.e., the column between two tab 5461151497Sru stops) may be justified to the right or left or centered in the 5462151497Sru column. This is specified by appending `R', `L', or `C' to the tab 5463151497Sru specifier. The default justification is `L'. Example: 5464151497Sru 5465151497Sru 5466151497Sru .ta 1i 2iC 3iR 5467151497Sru 5468151497Sru Some notes: 5469151497Sru 5470151497Sru * The default unit of the `ta' request is `m'. 5471151497Sru 5472151497Sru * A tab stop is converted into a non-breakable horizontal 5473151497Sru movement which can be neither stretched nor squeezed. For 5474151497Sru example, 5475151497Sru 5476151497Sru 5477151497Sru .ds foo a\tb\tc 5478151497Sru .ta T 5i 5479151497Sru \*[foo] 5480151497Sru 5481151497Sru creates a single line which is a bit longer than 10 inches (a 5482151497Sru string is used to show exactly where the tab characters are). 5483151497Sru Now consider the following: 5484151497Sru 5485151497Sru 5486151497Sru .ds bar a\tb b\tc 5487151497Sru .ta T 5i 5488151497Sru \*[bar] 5489151497Sru 5490151497Sru `gtroff' first converts the tab stops of the line into 5491151497Sru unbreakable horizontal movements, then splits the line after 5492151497Sru the second `b' (assuming a sufficiently short line length). 5493151497Sru Usually, this isn't what the user wants. 5494151497Sru 5495151497Sru * Superfluous tabs (i.e., tab characters which do not 5496151497Sru correspond to a tab stop) are ignored except the first one 5497151497Sru which delimits the characters belonging to the last tab stop 5498151497Sru for right-justifying or centering. Consider the following 5499151497Sru example 5500151497Sru 5501151497Sru 5502151497Sru .ds Z foo\tbar\tfoo 5503151497Sru .ds ZZ foo\tbar\tfoobar 5504151497Sru .ds ZZZ foo\tbar\tfoo\tbar 5505151497Sru .ta 2i 4iR 5506151497Sru \*[Z] 5507151497Sru .br 5508151497Sru \*[ZZ] 5509151497Sru .br 5510151497Sru \*[ZZZ] 5511151497Sru .br 5512151497Sru 5513151497Sru which produces the following output: 5514151497Sru 5515151497Sru 5516151497Sru foo bar foo 5517151497Sru foo bar foobar 5518151497Sru foo bar foobar 5519151497Sru 5520151497Sru The first line right-justifies the second `foo' relative to 5521151497Sru the tab stop. The second line right-justifies `foobar'. The 5522151497Sru third line finally right-justifies only `foo' because of the 5523151497Sru additional tab character which marks the end of the string 5524151497Sru belonging to the last defined tab stop. 5525151497Sru 5526151497Sru * Tab stops are associated with the current environment (*note 5527151497Sru Environments::). 5528151497Sru 5529151497Sru * Calling `ta' without an argument removes all tab stops. 5530151497Sru 5531151497Sru * The start-up value of `gtroff' is `T 0.8i'. 5532151497Sru 5533151497Sru The read-only number register `.tabs' contains a string 5534151497Sru representation of the current tab settings suitable for use as an 5535151497Sru argument to the `ta' request. 5536151497Sru 5537151497Sru 5538151497Sru .ds tab-string \n[.tabs] 5539151497Sru \*[tab-string] 5540151497Sru => T120u 5541151497Sru 5542151497Sru The `troff' version of the Plan 9 operating system uses register 5543151497Sru `.S' for the same purpose. 5544151497Sru 5545151497Sru -- Request: .tc [fill-glyph] 5546151497Sru Normally `gtroff' fills the space to the next tab stop with 5547151497Sru whitespace. This can be changed with the `tc' request. With no 5548151497Sru argument `gtroff' reverts to using whitespace, which is the 5549151497Sru default. The value of this "tab repetition character" is 5550151497Sru associated with the current environment (*note Environments::).(1) 5551151497Sru (*note Tabs and Fields-Footnote-1::) 5552151497Sru 5553151497Sru -- Request: .linetabs n 5554151497Sru -- Register: \n[.linetabs] 5555151497Sru If N is missing or not zero, enable "line-tabs" mode, or disable 5556151497Sru it otherwise (the default). In line-tabs mode, `gtroff' computes 5557151497Sru tab distances relative to the (current) output line instead of the 5558151497Sru input line. 5559151497Sru 5560151497Sru For example, the following code: 5561151497Sru 5562151497Sru 5563151497Sru .ds x a\t\c 5564151497Sru .ds y b\t\c 5565151497Sru .ds z c 5566151497Sru .ta 1i 3i 5567151497Sru \*x 5568151497Sru \*y 5569151497Sru \*z 5570151497Sru 5571151497Sru in normal mode, results in the output 5572151497Sru 5573151497Sru 5574151497Sru a b c 5575151497Sru 5576151497Sru in line-tabs mode, the same code outputs 5577151497Sru 5578151497Sru 5579151497Sru a b c 5580151497Sru 5581151497Sru Line-tabs mode is associated with the current environment. The 5582151497Sru read-only register `.linetabs' is set to 1 if in line-tabs mode, 5583151497Sru and 0 in normal mode. 5584151497Sru 5585151497Sru* Menu: 5586151497Sru 5587151497Sru* Leaders:: 5588151497Sru* Fields:: 5589151497Sru 5590151497Sru 5591151497SruFile: groff, Node: Tabs and Fields-Footnotes, Up: Tabs and Fields 5592151497Sru 5593151497Sru (1) "Tab repetition character" is a misnomer since it is an output 5594151497Sruglyph. 5595151497Sru 5596151497Sru 5597151497SruFile: groff, Node: Leaders, Next: Fields, Prev: Tabs and Fields, Up: Tabs and Fields 5598151497Sru 5599151497Sru5.10.1 Leaders 5600151497Sru-------------- 5601151497Sru 5602151497SruSometimes it may may be desirable to use the `tc' request to fill a 5603151497Sruparticular tab stop with a given glyph (for example dots in a table of 5604151497Srucontents), but also normal tab stops on the rest of the line. For this 5605151497Sru`gtroff' provides an alternate tab mechanism, called "leaders" which 5606151497Srudoes just that. 5607151497Sru 5608151497Sru A leader character (character code 1) behaves similarly to a tab 5609151497Srucharacter: It moves to the next tab stop. The only difference is that 5610151497Srufor this movement, the fill glyph defaults to a period character and 5611151497Srunot to space. 5612151497Sru 5613151497Sru -- Escape: \a 5614151497Sru This escape is a non-interpreted leader character. In copy mode 5615151497Sru (*note Copy-in Mode::), `\a' is the same as a real leader 5616151497Sru character. 5617151497Sru 5618151497Sru -- Request: .lc [fill-glyph] 5619151497Sru Declare the "leader repetition character".(1) (*note 5620151497Sru Leaders-Footnote-1::) Without an argument, leaders act the same as 5621151497Sru tabs (i.e., using whitespace for filling). `gtroff''s start-up 5622151497Sru value is a dot (`.'). The value of the leader repetition 5623151497Sru character is associated with the current environment (*note 5624151497Sru Environments::). 5625151497Sru 5626151497Sru For a table of contents, to name an example, tab stops may be 5627151497Srudefined so that the section number is one tab stop, the title is the 5628151497Srusecond with the remaining space being filled with a line of dots, and 5629151497Sruthen the page number slightly separated from the dots. 5630151497Sru 5631151497Sru 5632151497Sru .ds entry 1.1\tFoo\a\t12 5633151497Sru .lc . 5634151497Sru .ta 1i 5i +.25i 5635151497Sru \*[entry] 5636151497Sru 5637151497SruThis produces 5638151497Sru 5639151497Sru 5640151497Sru 1.1 Foo.......................................... 12 5641151497Sru 5642151497Sru 5643151497SruFile: groff, Node: Leaders-Footnotes, Up: Leaders 5644151497Sru 5645151497Sru (1) "Leader repetition character" is a misnomer since it is an 5646151497Sruoutput glyph. 5647151497Sru 5648151497Sru 5649151497SruFile: groff, Node: Fields, Prev: Leaders, Up: Tabs and Fields 5650151497Sru 5651151497Sru5.10.2 Fields 5652151497Sru------------- 5653151497Sru 5654151497Sru"Fields" are a more general way of laying out tabular data. A field is 5655151497Srudefined as the data between a pair of "delimiting characters". It 5656151497Srucontains substrings which are separated by "padding characters". The 5657151497Sruwidth of a field is the distance on the _input_ line from the position 5658151497Sruwhere the field starts to the next tab stop. A padding character 5659151497Sruinserts stretchable space similar to TeX's `\hss' command (thus it can 5660151497Srueven be negative) to make the sum of all substring lengths plus the 5661151497Srustretchable space equal to the field width. If more than one padding 5662151497Srucharacter is inserted, the available space is evenly distributed among 5663151497Sruthem. 5664151497Sru 5665151497Sru -- Request: .fc [delim-char [padding-char]] 5666151497Sru Define a delimiting and a padding character for fields. If the 5667151497Sru latter is missing, the padding character defaults to a space 5668151497Sru character. If there is no argument at all, the field mechanism is 5669151497Sru disabled (which is the default). Note that contrary to e.g. the 5670151497Sru tab repetition character, delimiting and padding characters are 5671151497Sru _not_ associated to the current environment (*note Environments::). 5672151497Sru 5673151497Sru Example: 5674151497Sru 5675151497Sru 5676151497Sru .fc # ^ 5677151497Sru .ta T 3i 5678151497Sru #foo^bar^smurf# 5679151497Sru .br 5680151497Sru #foo^^bar^smurf# 5681151497Sru 5682151497Sru and here the result: 5683151497Sru 5684151497Sru 5685151497Sru foo bar smurf 5686151497Sru foo bar smurf 5687151497Sru 5688151497Sru 5689151497Sru 5690151497SruFile: groff, Node: Character Translations, Next: Troff and Nroff Mode, Prev: Tabs and Fields, Up: gtroff Reference 5691151497Sru 5692151497Sru5.11 Character Translations 5693151497Sru=========================== 5694151497Sru 5695151497SruThe control character (`.') and the no-break control character (`'') 5696151497Srucan be changed with the `cc' and `c2' requests, respectively. 5697151497Sru 5698151497Sru -- Request: .cc [c] 5699151497Sru Set the control character to C. With no argument the default 5700151497Sru control character `.' is restored. The value of the control 5701151497Sru character is associated with the current environment (*note 5702151497Sru Environments::). 5703151497Sru 5704151497Sru -- Request: .c2 [c] 5705151497Sru Set the no-break control character to C. With no argument the 5706151497Sru default control character `'' is restored. The value of the 5707151497Sru no-break control character is associated with the current 5708151497Sru environment (*note Environments::). 5709151497Sru 5710151497Sru -- Request: .eo 5711151497Sru Disable the escape mechanism completely. After executing this 5712151497Sru request, the backslash character `\' no longer starts an escape 5713151497Sru sequence. 5714151497Sru 5715151497Sru This request can be very helpful in writing macros since it is not 5716151497Sru necessary then to double the escape character. Here an example: 5717151497Sru 5718151497Sru 5719151497Sru .\" This is a simplified version of the 5720151497Sru .\" .BR request from the man macro package 5721151497Sru .eo 5722151497Sru .de BR 5723151497Sru . ds result \& 5724151497Sru . while (\n[.$] >= 2) \{\ 5725151497Sru . as result \fB\$1\fR\$2 5726151497Sru . shift 2 5727151497Sru . \} 5728151497Sru . if \n[.$] .as result \fB\$1 5729151497Sru \*[result] 5730151497Sru . ft R 5731151497Sru .. 5732151497Sru .ec 5733151497Sru 5734151497Sru 5735151497Sru -- Request: .ec [c] 5736151497Sru Set the escape character to C. With no argument the default 5737151497Sru escape character `\' is restored. It can be also used to 5738151497Sru re-enable the escape mechanism after an `eo' request. 5739151497Sru 5740151497Sru Note that changing the escape character globally will likely break 5741151497Sru macro packages since `gtroff' has no mechanism to `intern' macros, 5742151497Sru i.e., to convert a macro definition into an internal form which is 5743151497Sru independent of its representation (TeX has this mechanism). If a 5744151497Sru macro is called, it is executed literally. 5745151497Sru 5746151497Sru -- Request: .ecs 5747151497Sru -- Request: .ecr 5748151497Sru The `ecs' request saves the current escape character in an 5749151497Sru internal register. Use this request in combination with the `ec' 5750151497Sru request to temporarily change the escape character. 5751151497Sru 5752151497Sru The `ecr' request restores the escape character saved with `ecs'. 5753151497Sru Without a previous call to `ecs', this request sets the escape 5754151497Sru character to `\'. 5755151497Sru 5756151497Sru -- Escape: \\ 5757151497Sru -- Escape: \e 5758151497Sru -- Escape: \E 5759151497Sru Print the current escape character (which is the backslash 5760151497Sru character `\' by default). 5761151497Sru 5762151497Sru `\\' is a `delayed' backslash; more precisely, it is the default 5763151497Sru escape character followed by a backslash, which no longer has 5764151497Sru special meaning due to the leading escape character. It is _not_ 5765151497Sru an escape sequence in the usual sense! In any unknown escape 5766151497Sru sequence `\X' the escape character is ignored and X is printed. 5767151497Sru But if X is equal to the current escape character, no warning is 5768151497Sru emitted. 5769151497Sru 5770151497Sru As a consequence, only at top-level or in a diversion a backslash 5771151497Sru glyph is printed; in copy-in mode, it expands to a single 5772151497Sru backslash which then combines with the following character to an 5773151497Sru escape sequence. 5774151497Sru 5775151497Sru The `\E' escape differs from `\e' by printing an escape character 5776151497Sru that is not interpreted in copy mode. Use this to define strings 5777151497Sru with escapes that work when used in copy mode (for example, as a 5778151497Sru macro argument). The following example defines strings to begin 5779151497Sru and end a superscript: 5780151497Sru 5781151497Sru 5782151497Sru .ds { \v'-.3m'\s'\En[.s]*60/100' 5783151497Sru .ds } \s0\v'.3m' 5784151497Sru 5785151497Sru Another example to demonstrate the differences between the various 5786151497Sru escape sequences, using a strange escape character, `-'. 5787151497Sru 5788151497Sru 5789151497Sru .ec - 5790151497Sru .de xxx 5791151497Sru --A'123' 5792151497Sru .. 5793151497Sru .xxx 5794151497Sru => -A'foo' 5795151497Sru 5796151497Sru The result is surprising for most users, expecting `1' since `foo' 5797151497Sru is a valid identifier. What has happened? As mentioned above, 5798151497Sru the leading escape character makes the following character 5799151497Sru ordinary. Written with the default escape character the sequence 5800151497Sru `--' becomes `\-' - this is the minus sign. 5801151497Sru 5802151497Sru If the escape character followed by itself is a valid escape 5803151497Sru sequence, only `\E' yields the expected result: 5804151497Sru 5805151497Sru 5806151497Sru .ec - 5807151497Sru .de xxx 5808151497Sru -EA'123' 5809151497Sru .. 5810151497Sru .xxx 5811151497Sru => 1 5812151497Sru 5813151497Sru 5814151497Sru -- Escape: \. 5815151497Sru Similar to `\\', the sequence `\.' isn't a real escape sequence. 5816151497Sru As before, a warning message is suppressed if the escape character 5817151497Sru is followed by a dot, and the dot itself is printed. 5818151497Sru 5819151497Sru 5820151497Sru .de foo 5821151497Sru . nop foo 5822151497Sru . 5823151497Sru . de bar 5824151497Sru . nop bar 5825151497Sru \\.. 5826151497Sru . 5827151497Sru .. 5828151497Sru .foo 5829151497Sru .bar 5830151497Sru => foo bar 5831151497Sru 5832151497Sru The first backslash is consumed while the macro is read, and the 5833151497Sru second is swallowed while exexuting macro `foo'. 5834151497Sru 5835151497Sru A "translation" is a mapping of an input character to an output 5836151497Sruglyph. The mapping occurs at output time, i.e., the input character 5837151497Srugets assigned the metric information of the mapped output character 5838151497Sruright before input tokens are converted to nodes (*note Gtroff 5839151497SruInternals::, for more on this process). 5840151497Sru 5841151497Sru -- Request: .tr abcd... 5842151497Sru -- Request: .trin abcd... 5843151497Sru Translate character A to glyph B, character C to glyph D, etc. If 5844151497Sru there is an odd number of arguments, the last one is translated to 5845151497Sru an unstretchable space (`\ '). 5846151497Sru 5847151497Sru The `trin' request is identical to `tr', but when you unformat a 5848151497Sru diversion with `asciify' it ignores the translation. *Note 5849151497Sru Diversions::, for details about the `asciify' request. 5850151497Sru 5851151497Sru Some notes: 5852151497Sru 5853151497Sru * Special characters (`\(XX', `\[XXX]', `\C'XXX'', `\'', `\`', 5854151497Sru `\-', `\_'), glyphs defined with the `char' request, and 5855151497Sru numbered glyphs (`\N'XXX'') can be translated also. 5856151497Sru 5857151497Sru * The `\e' escape can be translated also. 5858151497Sru 5859151497Sru * Characters can be mapped onto the `\%' and `\~' escapes (but 5860151497Sru `\%' and `\~' can't be mapped onto another glyph). 5861151497Sru 5862151497Sru * The following characters can't be translated: space (with one 5863151497Sru exception, see below), backspace, newline, leader (and `\a'), 5864151497Sru tab (and `\t'). 5865151497Sru 5866151497Sru * Translations are not considered for finding the soft hyphen 5867151497Sru character set with the `shc' request. 5868151497Sru 5869151497Sru * The pair `C\&' (this is an arbitrary character C followed by 5870151497Sru the zero width space character) maps this character to 5871151497Sru nothing. 5872151497Sru 5873151497Sru 5874151497Sru .tr a\& 5875151497Sru foo bar 5876151497Sru => foo br 5877151497Sru 5878151497Sru It is even possible to map the space character to nothing: 5879151497Sru 5880151497Sru 5881151497Sru .tr aa \& 5882151497Sru foo bar 5883151497Sru => foobar 5884151497Sru 5885151497Sru As shown in the example, the space character can't be the 5886151497Sru first character/glyph pair as an argument of `tr'. 5887151497Sru Additionally, it is not possible to map the space character 5888151497Sru to any other glyph; requests like `.tr aa x' undo `.tr aa \&' 5889151497Sru instead. 5890151497Sru 5891151497Sru If justification is active, lines are justified in spite of 5892151497Sru the `empty' space character (but there is no minimal 5893151497Sru distance, i.e. the space character, between words). 5894151497Sru 5895151497Sru * After an output glyph has been constructed (this happens at 5896151497Sru the moment immediately before the glyph is appended to an 5897151497Sru output glyph list, either by direct output, in a macro, 5898151497Sru diversion, or string), it is no longer affected by `tr'. 5899151497Sru 5900151497Sru * Translating character to glyphs where one of them or both are 5901151497Sru undefined is possible also; `tr' does not check whether the 5902151497Sru entities in its argument do exist. 5903151497Sru 5904151497Sru *Note Gtroff Internals::. 5905151497Sru 5906151497Sru * `troff' no longer has a hard-coded dependency on Latin-1; all 5907151497Sru `charXXX' entities have been removed from the font 5908151497Sru description files. This has a notable consequence which 5909151497Sru shows up in warnings like `can't find character with input 5910151497Sru code XXX' if the `tr' request isn't handled properly. 5911151497Sru 5912151497Sru Consider the following translation: 5913151497Sru 5914151497Sru 5915151497Sru .tr �� 5916151497Sru 5917151497Sru This maps input character `�' onto glyph `�', which is 5918151497Sru identical to glyph `char201'. But this glyph intentionally 5919151497Sru doesn't exist! Instead, `\[char201]' is treated as an input 5920151497Sru character entity and is by default mapped onto `\['E]', and 5921151497Sru `gtroff' doesn't handle translations of translations. 5922151497Sru 5923151497Sru The right way to write the above translation is 5924151497Sru 5925151497Sru 5926151497Sru .tr �\['E] 5927151497Sru 5928151497Sru With other words, the first argument of `tr' should be an 5929151497Sru input character or entity, and the second one a glyph entity. 5930151497Sru 5931151497Sru * Without an argument, the `tr' request is ignored. 5932151497Sru 5933151497Sru -- Request: .trnt abcd... 5934151497Sru `trnt' is the same as the `tr' request except that the 5935151497Sru translations do not apply to text that is transparently throughput 5936151497Sru into a diversion with `\!'. *Note Diversions::, for more 5937151497Sru information. 5938151497Sru 5939151497Sru For example, 5940151497Sru 5941151497Sru 5942151497Sru .tr ab 5943151497Sru .di x 5944151497Sru \!.tm a 5945151497Sru .di 5946151497Sru .x 5947151497Sru 5948151497Sru prints `b' to the standard error stream; if `trnt' is used instead 5949151497Sru of `tr' it prints `a'. 5950151497Sru 5951151497Sru 5952151497SruFile: groff, Node: Troff and Nroff Mode, Next: Line Layout, Prev: Character Translations, Up: gtroff Reference 5953151497Sru 5954151497Sru5.12 Troff and Nroff Mode 5955151497Sru========================= 5956151497Sru 5957151497SruOriginally, `nroff' and `troff' were two separate programs, the former 5958151497Srufor TTY output, the latter for everything else. With GNU `troff', both 5959151497Sruprograms are merged into one executable, sending its output to a device 5960151497Srudriver (`grotty' for TTY devices, `grops' for POSTSCRIPT, etc.) which 5961151497Sruinterprets the intermediate output of `gtroff'. For UNIX `troff' it 5962151497Srumakes sense to talk about "Nroff mode" and "Troff mode" since the 5963151497Srudifferences are hardcoded. For GNU `troff', this distinction is not 5964151497Sruappropriate because `gtroff' simply takes the information given in the 5965151497Srufont files for a particular device without handling requests specially 5966151497Sruif a TTY output device is used. 5967151497Sru 5968151497Sru Usually, a macro package can be used with all output devices. 5969151497SruNevertheless, it is sometimes necessary to make a distinction between 5970151497SruTTY and non-TTY devices: `gtroff' provides two built-in conditions `n' 5971151497Sruand `t' for the `if', `ie', and `while' requests to decide whether 5972151497Sru`gtroff' shall behave like `nroff' or like `troff'. 5973151497Sru 5974151497Sru -- Request: .troff 5975151497Sru Make the `t' built-in condition true (and the `n' built-in 5976151497Sru condition false) for `if', `ie', and `while' conditional requests. 5977151497Sru This is the default if `gtroff' (_not_ `groff') is started with 5978151497Sru the `-R' switch to avoid loading of the start-up files `troffrc' 5979151497Sru and `troffrc-end'. Without `-R', `gtroff' stays in troff mode if 5980151497Sru the output device is not a TTY (e.g. `ps'). 5981151497Sru 5982151497Sru -- Request: .nroff 5983151497Sru Make the `n' built-in condition true (and the `t' built-in 5984151497Sru condition false) for `if', `ie', and `while' conditional requests. 5985151497Sru This is the default if `gtroff' uses a TTY output device; the 5986151497Sru code for switching to nroff mode is in the file `tty.tmac' which 5987151497Sru is loaded by the start-up file `troffrc'. 5988151497Sru 5989151497Sru *Note Conditionals and Loops::, for more details on built-in 5990151497Sruconditions. 5991151497Sru 5992151497Sru 5993151497SruFile: groff, Node: Line Layout, Next: Line Control, Prev: Troff and Nroff Mode, Up: gtroff Reference 5994151497Sru 5995151497Sru5.13 Line Layout 5996151497Sru================ 5997151497Sru 5998151497SruThe following drawing shows the dimensions which `gtroff' uses for 5999151497Sruplacing a line of output onto the page. They are labeled with the 6000151497Srurequest which manipulates each dimension. 6001151497Sru 6002151497Sru 6003151497Sru -->| in |<-- 6004151497Sru |<-----------ll------------>| 6005151497Sru +----+----+----------------------+----+ 6006151497Sru | : : : | 6007151497Sru +----+----+----------------------+----+ 6008151497Sru -->| po |<-- 6009151497Sru |<--------paper width---------------->| 6010151497Sru 6011151497SruThese dimensions are: 6012151497Sru 6013151497Sru`po' 6014151497Sru "Page offset" - this is the leftmost position of text on the final 6015151497Sru output, defining the "left margin". 6016151497Sru 6017151497Sru`in' 6018151497Sru "Indentation" - this is the distance from the left margin where 6019151497Sru text is printed. 6020151497Sru 6021151497Sru`ll' 6022151497Sru "Line length" - this is the distance from the left margin to right 6023151497Sru margin. 6024151497Sru 6025151497Sru A simple demonstration: 6026151497Sru 6027151497Sru 6028151497Sru .ll 3i 6029151497Sru This is text without indentation. 6030151497Sru The line length has been set to 3\~inch. 6031151497Sru .in +.5i 6032151497Sru .ll -.5i 6033151497Sru Now the left and right margins are both increased. 6034151497Sru .in 6035151497Sru .ll 6036151497Sru Calling .in and .ll without parameters restore 6037151497Sru the previous values. 6038151497Sru 6039151497Sru Result: 6040151497Sru 6041151497Sru 6042151497Sru This is text without indenta- 6043151497Sru tion. The line length has 6044151497Sru been set to 3 inch. 6045151497Sru Now the left and 6046151497Sru right margins are 6047151497Sru both increased. 6048151497Sru Calling .in and .ll without 6049151497Sru parameters restore the previ- 6050151497Sru ous values. 6051151497Sru 6052151497Sru -- Request: .po [offset] 6053151497Sru -- Request: .po +offset 6054151497Sru -- Request: .po -offset 6055151497Sru -- Register: \n[.o] 6056151497Sru Set horizontal page offset to OFFSET (or increment or decrement 6057151497Sru the current value by OFFSET). Note that this request does not 6058151497Sru cause a break, so changing the page offset in the middle of text 6059151497Sru being filled may not yield the expected result. The initial value 6060151497Sru is 1i. For TTY output devices, it is set to 0 in the startup file 6061151497Sru `troffrc'; the default scaling indicator is `m' (and not `v' as 6062151497Sru incorrectly documented in the original UNIX troff manual). 6063151497Sru 6064151497Sru The current page offset can be found in the read-only number 6065151497Sru register `.o'. 6066151497Sru 6067151497Sru If `po' is called without an argument, the page offset is reset to 6068151497Sru the previous value before the last call to `po'. 6069151497Sru 6070151497Sru 6071151497Sru .po 3i 6072151497Sru \n[.o] 6073151497Sru => 720 6074151497Sru .po -1i 6075151497Sru \n[.o] 6076151497Sru => 480 6077151497Sru .po 6078151497Sru \n[.o] 6079151497Sru => 720 6080151497Sru 6081151497Sru 6082151497Sru -- Request: .in [indent] 6083151497Sru -- Request: .in +indent 6084151497Sru -- Request: .in -indent 6085151497Sru -- Register: \n[.i] 6086151497Sru Set indentation to INDENT (or increment or decrement the current 6087151497Sru value by INDENT). This request causes a break. Initially, there 6088151497Sru is no indentation. 6089151497Sru 6090151497Sru If `in' is called without an argument, the indentation is reset to 6091151497Sru the previous value before the last call to `in'. The default 6092151497Sru scaling indicator is `m'. 6093151497Sru 6094151497Sru The indentation is associated with the current environment (*note 6095151497Sru Environments::). 6096151497Sru 6097151497Sru If a negative indentation value is specified (which is not 6098151497Sru allowed), `gtroff' emits a warning of type `range' and sets the 6099151497Sru indentation to zero. 6100151497Sru 6101151497Sru The effect of `in' is delayed until a partially collected line (if 6102151497Sru it exists) is output. A temporary indentation value is reset to 6103151497Sru zero also. 6104151497Sru 6105151497Sru The current indentation (as set by `in') can be found in the 6106151497Sru read-only number register `.i'. 6107151497Sru 6108151497Sru -- Request: .ti offset 6109151497Sru -- Request: .ti +offset 6110151497Sru -- Request: .ti -offset 6111151497Sru -- Register: \n[.in] 6112151497Sru Temporarily indent the next output line by OFFSET. If an 6113151497Sru increment or decrement value is specified, adjust the temporary 6114151497Sru indentation relative to the value set by the `in' request. 6115151497Sru 6116151497Sru This request causes a break; its value is associated with the 6117151497Sru current environment (*note Environments::). The default scaling 6118151497Sru indicator is `m'. A call of `ti' without an argument is ignored. 6119151497Sru 6120151497Sru If the total indentation value is negative (which is not allowed), 6121151497Sru `gtroff' emits a warning of type `range' and sets the temporary 6122151497Sru indentation to zero. `Total indentation' is either OFFSET if 6123151497Sru specified as an absolute value, or the temporary plus normal 6124151497Sru indentation, if OFFSET is given as a relative value. 6125151497Sru 6126151497Sru The effect of `ti' is delayed until a partially collected line (if 6127151497Sru it exists) is output. 6128151497Sru 6129151497Sru The read-only number register `.in' is the indentation that applies 6130151497Sru to the current output line. 6131151497Sru 6132151497Sru The difference between `.i' and `.in' is that the latter takes 6133151497Sru into account whether a partially collected line still uses the old 6134151497Sru indentation value or a temporary indentation value is active. 6135151497Sru 6136151497Sru -- Request: .ll [length] 6137151497Sru -- Request: .ll +length 6138151497Sru -- Request: .ll -length 6139151497Sru -- Register: \n[.l] 6140151497Sru -- Register: \n[.ll] 6141151497Sru Set the line length to LENGTH (or increment or decrement the 6142151497Sru current value by LENGTH). Initially, the line length is set to 6143151497Sru 6.5i. The effect of `ll' is delayed until a partially collected 6144151497Sru line (if it exists) is output. The default scaling indicator is 6145151497Sru `m'. 6146151497Sru 6147151497Sru If `ll' is called without an argument, the line length is reset to 6148151497Sru the previous value before the last call to `ll'. If a negative 6149151497Sru line length is specified (which is not allowed), `gtroff' emits a 6150151497Sru warning of type `range' and sets the line length to zero. 6151151497Sru 6152151497Sru The line length is associated with the current environment (*note 6153151497Sru Environments::). 6154151497Sru 6155151497Sru The current line length (as set by `ll') can be found in the 6156151497Sru read-only number register `.l'. The read-only number register 6157151497Sru `.ll' is the line length that applies to the current output line. 6158151497Sru 6159151497Sru Similar to `.i' and `.in', the difference between `.l' and `.ll' 6160151497Sru is that the latter takes into account whether a partially 6161151497Sru collected line still uses the old line length value. 6162151497Sru 6163151497Sru 6164151497SruFile: groff, Node: Line Control, Next: Page Layout, Prev: Line Layout, Up: gtroff Reference 6165151497Sru 6166151497Sru5.14 Line Control 6167151497Sru================= 6168151497Sru 6169151497SruIt is important to understand how `gtroff' handles input and output 6170151497Srulines. 6171151497Sru 6172151497Sru Many escapes use positioning relative to the input line. For 6173151497Sruexample, this 6174151497Sru 6175151497Sru 6176151497Sru This is a \h'|1.2i'test. 6177151497Sru 6178151497Sru This is a 6179151497Sru \h'|1.2i'test. 6180151497Sru 6181151497Sruproduces 6182151497Sru 6183151497Sru 6184151497Sru This is a test. 6185151497Sru 6186151497Sru This is a test. 6187151497Sru 6188151497Sru The main usage of this feature is to define macros which act exactly 6189151497Sruat the place where called. 6190151497Sru 6191151497Sru 6192151497Sru .\" A simple macro to underline a word 6193151497Sru .de underline 6194151497Sru . nop \\$1\l'|0\[ul]' 6195151497Sru .. 6196151497Sru 6197151497SruIn the above example, `|0' specifies a negative distance from the 6198151497Srucurrent position (at the end of the just emitted argument `\$1') back 6199151497Sruto the beginning of the input line. Thus, the `\l' escape draws a line 6200151497Srufrom right to left. 6201151497Sru 6202151497Sru `gtroff' makes a difference between input and output line 6203151497Srucontinuation; the latter is also called "interrupting" a line. 6204151497Sru 6205151497Sru -- Escape: \<RET> 6206151497Sru -- Escape: \c 6207151497Sru -- Register: \n[.int] 6208151497Sru Continue a line. `\<RET>' (this is a backslash at the end of a 6209151497Sru line immediately followed by a newline) works on the input level, 6210151497Sru suppressing the effects of the following newline in the input. 6211151497Sru 6212151497Sru 6213151497Sru This is a \ 6214151497Sru .test 6215151497Sru => This is a .test 6216151497Sru 6217151497Sru The `|' operator is also affected. 6218151497Sru 6219151497Sru `\c' works on the output level. Anything after this escape on the 6220151497Sru same line is ignored, except `\R' which works as usual. Anything 6221151497Sru before `\c' on the same line will be appended to the current 6222151497Sru partial output line. The next non-command line after an 6223151497Sru interrupted line counts as a new input line. 6224151497Sru 6225151497Sru The visual results depend on whether no-fill mode is active. 6226151497Sru 6227151497Sru * If no-fill mode is active (using the `nf' request), the next 6228151497Sru input text line after `\c' will be handled as a continuation 6229151497Sru of the same input text line. 6230151497Sru 6231151497Sru 6232151497Sru .nf 6233151497Sru This is a \c 6234151497Sru test. 6235151497Sru => This is a test. 6236151497Sru 6237151497Sru * If fill mode is active (using the `fi' request), a word 6238151497Sru interrupted with `\c' will be continued with the text on the 6239151497Sru next input text line, without an intervening space. 6240151497Sru 6241151497Sru 6242151497Sru This is a te\c 6243151497Sru st. 6244151497Sru => This is a test. 6245151497Sru 6246151497Sru 6247151497Sru Note that an intervening control line which causes a break is 6248151497Sru stronger than `\c', flushing out the current partial line in the 6249151497Sru usual way. 6250151497Sru 6251151497Sru The `.int' register contains a positive value if the last output 6252151497Sru line was interrupted with `\c'; this is associated with the 6253151497Sru current environment (*note Environments::). 6254151497Sru 6255151497Sru 6256151497SruFile: groff, Node: Page Layout, Next: Page Control, Prev: Line Control, Up: gtroff Reference 6257151497Sru 6258151497Sru5.15 Page Layout 6259151497Sru================ 6260151497Sru 6261151497Sru`gtroff' provides some very primitive operations for controlling page 6262151497Srulayout. 6263151497Sru 6264151497Sru -- Request: .pl [length] 6265151497Sru -- Request: .pl +length 6266151497Sru -- Request: .pl -length 6267151497Sru -- Register: \n[.p] 6268151497Sru Set the "page length" to LENGTH (or increment or decrement the 6269151497Sru current value by LENGTH). This is the length of the physical 6270151497Sru output page. The default scaling indicator is `v'. 6271151497Sru 6272151497Sru The current setting can be found in the read-only number register 6273151497Sru `.p'. 6274151497Sru 6275151497Sru Note that this only specifies the size of the page, not the top and 6276151497Sru bottom margins. Those are not set by `gtroff' directly. *Note 6277151497Sru Traps::, for further information on how to do this. 6278151497Sru 6279151497Sru Negative `pl' values are possible also, but not very useful: No 6280151497Sru trap is sprung, and each line is output on a single page (thus 6281151497Sru suppressing all vertical spacing). 6282151497Sru 6283151497Sru If no argument or an invalid argument is given, `pl' sets the page 6284151497Sru length to 11i. 6285151497Sru 6286151497Sru `gtroff' provides several operations which help in setting up top 6287151497Sruand bottom titles (or headers and footers). 6288151497Sru 6289151497Sru -- Request: .tl 'left'center'right' 6290151497Sru Print a "title line". It consists of three parts: a left 6291151497Sru justified portion, a centered portion, and a right justified 6292151497Sru portion. The argument separator `'' can be replaced with any 6293151497Sru character not occurring in the title line. The `%' character is 6294151497Sru replaced with the current page number. This character can be 6295151497Sru changed with the `pc' request (see below). 6296151497Sru 6297151497Sru Without argument, `tl' is ignored. 6298151497Sru 6299151497Sru Some notes: 6300151497Sru 6301151497Sru * A title line is not restricted to the top or bottom of a page. 6302151497Sru 6303151497Sru * `tl' prints the title line immediately, ignoring a partially 6304151497Sru filled line (which stays untouched). 6305151497Sru 6306151497Sru * It is not an error to omit closing delimiters. For example, 6307151497Sru `.tl /foo' is equivalent to `.tl /foo///': It prints a title 6308151497Sru line with the left justified word `foo'; the centered and 6309151497Sru right justfied parts are empty. 6310151497Sru 6311151497Sru * `tl' accepts the same parameter delimiting characters as the 6312151497Sru `\A' escape; see *Note Escapes::. 6313151497Sru 6314151497Sru -- Request: .lt [length] 6315151497Sru -- Request: .lt +length 6316151497Sru -- Request: .lt -length 6317151497Sru -- Register: \n[.lt] 6318151497Sru The title line is printed using its own line length, which is 6319151497Sru specified (or incremented or decremented) with the `lt' request. 6320151497Sru Initially, the title line length is set to 6.5i. If a negative 6321151497Sru line length is specified (which is not allowed), `gtroff' emits a 6322151497Sru warning of type `range' and sets the title line length to zero. 6323151497Sru The default scaling indicator is `m'. If `lt' is called without 6324151497Sru an argument, the title length is reset to the previous value 6325151497Sru before the last call to `lt'. 6326151497Sru 6327151497Sru The current setting of this is available in the `.lt' read-only 6328151497Sru number register; it is associated with the current environment 6329151497Sru (*note Environments::). 6330151497Sru 6331151497Sru -- Request: .pn page 6332151497Sru -- Request: .pn +page 6333151497Sru -- Request: .pn -page 6334151497Sru -- Register: \n[.pn] 6335151497Sru Change (increase or decrease) the page number of the _next_ page. 6336151497Sru The only argument is the page number; the request is ignored 6337151497Sru without a parameter. 6338151497Sru 6339151497Sru The read-only number register `.pn' contains the number of the next 6340151497Sru page: either the value set by a `pn' request, or the number of the 6341151497Sru current page plus 1. 6342151497Sru 6343151497Sru -- Request: .pc [char] 6344151497Sru Change the page number character (used by the `tl' request) to a 6345151497Sru different character. With no argument, this mechanism is disabled. 6346151497Sru Note that this doesn't affect the number register `%'. 6347151497Sru 6348151497Sru *Note Traps::. 6349151497Sru 6350151497Sru 6351151497SruFile: groff, Node: Page Control, Next: Fonts and Symbols, Prev: Page Layout, Up: gtroff Reference 6352151497Sru 6353151497Sru5.16 Page Control 6354151497Sru================= 6355151497Sru 6356151497Sru -- Request: .bp [page] 6357151497Sru -- Request: .bp +page 6358151497Sru -- Request: .bp -page 6359151497Sru -- Register: \n[%] 6360151497Sru Stop processing the current page and move to the next page. This 6361151497Sru request causes a break. It can also take an argument to set 6362151497Sru (increase, decrease) the page number of the next page (which 6363151497Sru actually becomes the current page after `bp' has finished). The 6364151497Sru difference between `bp' and `pn' is that `pn' does not cause a 6365151497Sru break or actually eject a page. *Note Page Layout::. 6366151497Sru 6367151497Sru 6368151497Sru .de newpage \" define macro 6369151497Sru 'bp \" begin page 6370151497Sru 'sp .5i \" vertical space 6371151497Sru .tl 'left top'center top'right top' \" title 6372151497Sru 'sp .3i \" vertical space 6373151497Sru .. \" end macro 6374151497Sru 6375151497Sru `bp' has no effect if not called within the top-level diversion 6376151497Sru (*note Diversions::). 6377151497Sru 6378151497Sru The read-write register `%' holds the current page number. 6379151497Sru 6380151497Sru The number register `.pe' is set to 1 while `bp' is active. *Note 6381151497Sru Page Location Traps::. 6382151497Sru 6383151497Sru -- Request: .ne [space] 6384151497Sru It is often necessary to force a certain amount of space before a 6385151497Sru new page occurs. This is most useful to make sure that there is 6386151497Sru not a single "orphan" line left at the bottom of a page. The `ne' 6387151497Sru request ensures that there is a certain distance, specified by the 6388151497Sru first argument, before the next page is triggered (see *Note 6389151497Sru Traps::, for further information). The default scaling indicator 6390151497Sru for `ne' is `v'; the default value of SPACE is 1v if no argument 6391151497Sru is given. 6392151497Sru 6393151497Sru For example, to make sure that no fewer than 2 lines get orphaned, 6394151497Sru do the following before each paragraph: 6395151497Sru 6396151497Sru 6397151497Sru .ne 2 6398151497Sru text text text 6399151497Sru 6400151497Sru `ne' will then automatically cause a page break if there is space 6401151497Sru for one line only. 6402151497Sru 6403151497Sru -- Request: .sv [space] 6404151497Sru -- Request: .os 6405151497Sru `sv' is similar to the `ne' request; it reserves the specified 6406151497Sru amount of vertical space. If the desired amount of space exists 6407151497Sru before the next trap (or the bottom page boundary if no trap is 6408151497Sru set), the space is output immediately (ignoring a partially filled 6409151497Sru line which stays untouched). If there is not enough space, it is 6410151497Sru stored for later output via the `os' request. The default value 6411151497Sru is 1v if no argument is given; the default scaling indicator is 6412151497Sru `v'. 6413151497Sru 6414151497Sru Both `sv' and `os' ignore no-space mode. While the `sv' request 6415151497Sru allows negative values for SPACE, `os' will ignore them. 6416151497Sru 6417151497Sru -- Register: \n[nl] 6418151497Sru This register contains the current vertical position. If the 6419151497Sru vertical position is zero and the top of page transition hasn't 6420151497Sru happened yet, `nl' is set to negative value. `gtroff' itself does 6421151497Sru this at the very beginning of a document before anything has been 6422151497Sru printed, but the main usage is to plant a header trap on a page if 6423151497Sru this page has already started. 6424151497Sru 6425151497Sru Consider the following: 6426151497Sru 6427151497Sru 6428151497Sru .de xxx 6429151497Sru . sp 6430151497Sru . tl ''Header'' 6431151497Sru . sp 6432151497Sru .. 6433151497Sru . 6434151497Sru First page. 6435151497Sru .bp 6436151497Sru .wh 0 xxx 6437151497Sru .nr nl (-1) 6438151497Sru Second page. 6439151497Sru 6440151497Sru Result: 6441151497Sru 6442151497Sru 6443151497Sru First page. 6444151497Sru 6445151497Sru ... 6446151497Sru 6447151497Sru Header 6448151497Sru 6449151497Sru Second page. 6450151497Sru 6451151497Sru ... 6452151497Sru 6453151497Sru Without resetting `nl' to a negative value, the just planted trap 6454151497Sru would be active beginning with the _next_ page, not the current 6455151497Sru one. 6456151497Sru 6457151497Sru *Note Diversions::, for a comparison with the `.h' and `.d' 6458151497Sru registers. 6459151497Sru 6460151497Sru 6461151497SruFile: groff, Node: Fonts and Symbols, Next: Sizes, Prev: Page Control, Up: gtroff Reference 6462151497Sru 6463151497Sru5.17 Fonts and Symbols 6464151497Sru====================== 6465151497Sru 6466151497Sru`gtroff' can switch fonts at any point in the text. 6467151497Sru 6468151497Sru The basic set of fonts is `R', `I', `B', and `BI'. These are Times 6469151497SruRoman, Italic, Bold, and Bold Italic. For non-TTY devices, there is 6470151497Srualso at least one symbol font which contains various special symbols 6471151497Sru(Greek, mathematics). 6472151497Sru 6473151497Sru* Menu: 6474151497Sru 6475151497Sru* Changing Fonts:: 6476151497Sru* Font Families:: 6477151497Sru* Font Positions:: 6478151497Sru* Using Symbols:: 6479151497Sru* Special Fonts:: 6480151497Sru* Artificial Fonts:: 6481151497Sru* Ligatures and Kerning:: 6482151497Sru 6483151497Sru 6484151497SruFile: groff, Node: Changing Fonts, Next: Font Families, Prev: Fonts and Symbols, Up: Fonts and Symbols 6485151497Sru 6486151497Sru5.17.1 Changing Fonts 6487151497Sru--------------------- 6488151497Sru 6489151497Sru -- Request: .ft [font] 6490151497Sru -- Escape: \ff 6491151497Sru -- Escape: \f(fn 6492151497Sru -- Escape: \f[font] 6493151497Sru -- Register: \n[.sty] 6494151497Sru The `ft' request and the `\f' escape change the current font to 6495151497Sru FONT (one-character name F, two-character name FN). 6496151497Sru 6497151497Sru If FONT is a style name (as set with the `sty' request or with the 6498151497Sru `styles' command in the `DESC' file), use it within the current 6499151497Sru font family (as set with the `fam' request, `\F' escape, or with 6500151497Sru the `family' command in the `DESC' file). 6501151497Sru 6502151497Sru With no argument or using `P' as an argument, `.ft' switches to 6503151497Sru the previous font. Use `\f[]' to do this with the escape. The 6504151497Sru old syntax forms `\fP' or `\f[P]' are also supported. 6505151497Sru 6506151497Sru Fonts are generally specified as upper-case strings, which are 6507151497Sru usually 1 to 4 characters representing an abbreviation or acronym 6508151497Sru of the font name. This is no limitation, just a convention. 6509151497Sru 6510151497Sru The example below produces two identical lines. 6511151497Sru 6512151497Sru 6513151497Sru eggs, bacon, 6514151497Sru .ft B 6515151497Sru spam 6516151497Sru .ft 6517151497Sru and sausage. 6518151497Sru 6519151497Sru eggs, bacon, \fBspam\fP and sausage. 6520151497Sru 6521151497Sru Note that `\f' doesn't produce an input token in `gtroff'. As a 6522151497Sru consequence, it can be used in requests like `mc' (which expects a 6523151497Sru single character as an argument) to change the font on the fly: 6524151497Sru 6525151497Sru 6526151497Sru .mc \f[I]x\f[] 6527151497Sru 6528151497Sru The current style name is available in the read-only number 6529151497Sru register `.sty' (this is a string-valued register); if the current 6530151497Sru font isn't a style, the empty string is returned. It is 6531151497Sru associated with the current environment. 6532151497Sru 6533151497Sru *Note Font Positions::, for an alternative syntax. 6534151497Sru 6535151497Sru -- Request: .ftr f [g] 6536151497Sru Translate font F to font G. Whenever a font named F is referred 6537151497Sru to in a `\f' escape sequence, in the `F' and `S' conditional 6538151497Sru operators, or in the `ft', `ul', `bd', `cs', `tkf', `special', 6539151497Sru `fspecial', `fp', or `sty' requests, font G is used. If G is 6540151497Sru missing or equal to F the translation is undone. 6541151497Sru 6542151497Sru 6543151497SruFile: groff, Node: Font Families, Next: Font Positions, Prev: Changing Fonts, Up: Fonts and Symbols 6544151497Sru 6545151497Sru5.17.2 Font Families 6546151497Sru-------------------- 6547151497Sru 6548151497SruDue to the variety of fonts available, `gtroff' has added the concept 6549151497Sruof "font families" and "font styles". The fonts are specified as the 6550151497Sruconcatenation of the font family and style. Specifying a font without 6551151497Sruthe family part causes `gtroff' to use that style of the current family. 6552151497Sru 6553151497Sru Currently, fonts for the devices `-Tps', `-Tdvi', `-Tlj4', `-Tlbp', 6554151497Sruand the X11 fonts are set up to this mechanism. By default, `gtroff' 6555151497Sruuses the Times family with the four styles `R', `I', `B', and `BI'. 6556151497Sru 6557151497Sru This way, it is possible to use the basic four fonts and to select a 6558151497Srudifferent font family on the command line (*note Groff Options::). 6559151497Sru 6560151497Sru -- Request: .fam [family] 6561151497Sru -- Register: \n[.fam] 6562151497Sru -- Escape: \Ff 6563151497Sru -- Escape: \F(fm 6564151497Sru -- Escape: \F[family] 6565151497Sru -- Register: \n[.fn] 6566151497Sru Switch font family to FAMILY (one-character name F, two-character 6567151497Sru name FM). If no argument is given, switch back to the previous 6568151497Sru font family. Use `\F[]' to do this with the escape. Note that 6569151497Sru `\FP' doesn't work; it selects font family `P' instead. 6570151497Sru 6571151497Sru The value at start-up is `T'. The current font family is 6572151497Sru available in the read-only number register `.fam' (this is a 6573151497Sru string-valued register); it is associated with the current 6574151497Sru environment. 6575151497Sru 6576151497Sru 6577151497Sru spam, 6578151497Sru .fam H \" helvetica family 6579151497Sru spam, \" used font is family H + style R = HR 6580151497Sru .ft B \" family H + style B = font HB 6581151497Sru spam, 6582151497Sru .fam T \" times family 6583151497Sru spam, \" used font is family T + style B = TB 6584151497Sru .ft AR \" font AR (not a style) 6585151497Sru baked beans, 6586151497Sru .ft R \" family T + style R = font TR 6587151497Sru and spam. 6588151497Sru 6589151497Sru Note that `\F' doesn't produce an input token in `gtroff'. As a 6590151497Sru consequence, it can be used in requests like `mc' (which expects a 6591151497Sru single character as an argument) to change the font family on the 6592151497Sru fly: 6593151497Sru 6594151497Sru 6595151497Sru .mc \F[P]x\F[] 6596151497Sru 6597151497Sru The `.fn' register contains the current "real font name" of the 6598151497Sru current font. This is a string-valued register. If the current 6599151497Sru font is a style, the value of `\n[.fn]' is the proper 6600151497Sru concatenation of family and style name. 6601151497Sru 6602151497Sru -- Request: .sty n style 6603151497Sru Associate STYLE with font position N. A font position can be 6604151497Sru associated either with a font or with a style. The current font 6605151497Sru is the index of a font position and so is also either a font or a 6606151497Sru style. If it is a style, the font that is actually used is the 6607151497Sru font which name is the concatenation of the name of the current 6608151497Sru family and the name of the current style. For example, if the 6609151497Sru current font is 1 and font position 1 is associated with style `R' 6610151497Sru and the current font family is `T', then font `TR' will be used. 6611151497Sru If the current font is not a style, then the current family is 6612151497Sru ignored. If the requests `cs', `bd', `tkf', `uf', or `fspecial' 6613151497Sru are applied to a style, they will instead be applied to the member 6614151497Sru of the current family corresponding to that style. 6615151497Sru 6616151497Sru N must be a non-negative integer value. 6617151497Sru 6618151497Sru The default family can be set with the `-f' option (*note Groff 6619151497Sru Options::). The `styles' command in the `DESC' file controls 6620151497Sru which font positions (if any) are initially associated with styles 6621151497Sru rather than fonts. For example, the default setting for 6622151497Sru POSTSCRIPT fonts 6623151497Sru 6624151497Sru 6625151497Sru styles R I B BI 6626151497Sru 6627151497Sru is equivalent to 6628151497Sru 6629151497Sru 6630151497Sru .sty 1 R 6631151497Sru .sty 2 I 6632151497Sru .sty 3 B 6633151497Sru .sty 4 BI 6634151497Sru 6635151497Sru `fam' and `\F' always check whether the current font position is 6636151497Sru valid; this can give surprising results if the current font 6637151497Sru position is associated with a style. 6638151497Sru 6639151497Sru In the following example, we want to access the POSTSCRIPT font 6640151497Sru `FooBar' from the font family `Foo': 6641151497Sru 6642151497Sru 6643151497Sru .sty \n[.fp] Bar 6644151497Sru .fam Foo 6645151497Sru => warning: can't find font `FooR' 6646151497Sru 6647151497Sru The default font position at start-up is 1; for the POSTSCRIPT 6648151497Sru device, this is associated with style `R', so `gtroff' tries to 6649151497Sru open `FooR'. 6650151497Sru 6651151497Sru A solution to this problem is to use a dummy font like the 6652151497Sru following: 6653151497Sru 6654151497Sru 6655151497Sru .fp 0 dummy TR \" set up dummy font at position 0 6656151497Sru .sty \n[.fp] Bar \" register style `Bar' 6657151497Sru .ft 0 \" switch to font at position 0 6658151497Sru .fam Foo \" activate family `Foo' 6659151497Sru .ft Bar \" switch to font `FooBar' 6660151497Sru 6661151497Sru *Note Font Positions::. 6662151497Sru 6663151497Sru 6664151497SruFile: groff, Node: Font Positions, Next: Using Symbols, Prev: Font Families, Up: Fonts and Symbols 6665151497Sru 6666151497Sru5.17.3 Font Positions 6667151497Sru--------------------- 6668151497Sru 6669151497SruFor the sake of old phototypesetters and compatibility with old versions 6670151497Sruof `troff', `gtroff' has the concept of font "positions", on which 6671151497Sruvarious fonts are mounted. 6672151497Sru 6673151497Sru -- Request: .fp pos font [external-name] 6674151497Sru -- Register: \n[.f] 6675151497Sru -- Register: \n[.fp] 6676151497Sru Mount font FONT at position POS (which must be a non-negative 6677151497Sru integer). This numeric position can then be referred to with font 6678151497Sru changing commands. When `gtroff' starts it is using font 6679151497Sru position 1 (which must exist; position 0 is unused usually at 6680151497Sru start-up). 6681151497Sru 6682151497Sru The current font in use, as a font position, is available in the 6683151497Sru read-only number register `.f'. This can be useful to remember the 6684151497Sru current font for later recall. It is associated with the current 6685151497Sru environment (*note Environments::). 6686151497Sru 6687151497Sru 6688151497Sru .nr save-font \n[.f] 6689151497Sru .ft B 6690151497Sru ... text text text ... 6691151497Sru .ft \n[save-font] 6692151497Sru 6693151497Sru The number of the next free font position is available in the 6694151497Sru read-only number register `.fp'. This is useful when mounting a 6695151497Sru new font, like so: 6696151497Sru 6697151497Sru 6698151497Sru .fp \n[.fp] NEATOFONT 6699151497Sru 6700151497Sru Fonts not listed in the `DESC' file are automatically mounted on 6701151497Sru the next available font position when they are referenced. If a 6702151497Sru font is to be mounted explicitly with the `fp' request on an unused 6703151497Sru font position, it should be mounted on the first unused font 6704151497Sru position, which can be found in the `.fp' register. Although 6705151497Sru `gtroff' does not enforce this strictly, it is not allowed to 6706151497Sru mount a font at a position whose number is much greater (approx. 6707151497Sru 1000 positions) than that of any currently used position. 6708151497Sru 6709151497Sru The `fp' request has an optional third argument. This argument 6710151497Sru gives the external name of the font, which is used for finding the 6711151497Sru font description file. The second argument gives the internal 6712151497Sru name of the font which is used to refer to the font in `gtroff' 6713151497Sru after it has been mounted. If there is no third argument then the 6714151497Sru internal name is used as the external name. This feature makes it 6715151497Sru possible to use fonts with long names in compatibility mode. 6716151497Sru 6717151497Sru Both the `ft' request and the `\f' escape have alternative syntax 6718151497Sruforms to access font positions. 6719151497Sru 6720151497Sru -- Request: .ft nnn 6721151497Sru -- Escape: \fn 6722151497Sru -- Escape: \f(nn 6723151497Sru -- Escape: \f[nnn] 6724151497Sru Change the current font position to NNN (one-digit position N, 6725151497Sru two-digit position NN), which must be a non-negative integer. 6726151497Sru 6727151497Sru If NNN is associated with a style (as set with the `sty' request 6728151497Sru or with the `styles' command in the `DESC' file), use it within 6729151497Sru the current font family (as set with the `fam' request, the `\F' 6730151497Sru escape, or with the `family' command in the `DESC' file). 6731151497Sru 6732151497Sru 6733151497Sru this is font 1 6734151497Sru .ft 2 6735151497Sru this is font 2 6736151497Sru .ft \" switch back to font 1 6737151497Sru .ft 3 6738151497Sru this is font 3 6739151497Sru .ft 6740151497Sru this is font 1 again 6741151497Sru 6742151497Sru *Note Changing Fonts::, for the standard syntax form. 6743151497Sru 6744151497Sru 6745151497SruFile: groff, Node: Using Symbols, Next: Special Fonts, Prev: Font Positions, Up: Fonts and Symbols 6746151497Sru 6747151497Sru5.17.4 Using Symbols 6748151497Sru-------------------- 6749151497Sru 6750151497SruA "glyph" is a graphical representation of a "character". While a 6751151497Srucharacter is an abstract entity containing semantic information, a 6752151497Sruglyph is something which can be actually seen on screen or paper. It 6753151497Sruis possible that a character has multiple glyph representation forms 6754151497Sru(for example, the character `A' can be either written in a roman or an 6755151497Sruitalic font, yielding two different glyphs); sometimes more than one 6756151497Srucharacter maps to a single glyph (this is a "ligature" - the most 6757151497Srucommon is `fi'). 6758151497Sru 6759151497Sru A "symbol" is simply a named glyph. Within `gtroff', all glyph 6760151497Srunames of a particular font are defined in its font file. If the user 6761151497Srurequests a glyph not available in this font, `gtroff' looks up an 6762151497Sruordered list of "special fonts". By default, the POSTSCRIPT output 6763151497Srudevice supports the two special fonts `SS' (slanted symbols) and `S' 6764151497Sru(symbols) (the former is looked up before the latter). Other output 6765151497Srudevices use different names for special fonts. Fonts mounted with the 6766151497Sru`fonts' keyword in the `DESC' file are globally available. To install 6767151497Sruadditional special fonts locally (i.e. for a particular font), use the 6768151497Sru`fspecial' request. 6769151497Sru 6770151497Sru Here the exact rules how `gtroff' searches a given symbol: 6771151497Sru 6772151497Sru * If the symbol has been defined with the `char' request, use it. 6773151497Sru This hides a symbol with the same name in the current font. 6774151497Sru 6775151497Sru * Check the current font. 6776151497Sru 6777151497Sru * If the symbol has been defined with the `fchar' request, use it. 6778151497Sru 6779151497Sru * Check whether the current font has a font-specific list of special 6780151497Sru fonts; test all fonts in the order of appearance in the last 6781151497Sru `fspecial' call if appropriate. 6782151497Sru 6783151497Sru * If the symbol has been defined with the `fschar' request for the 6784151497Sru current font, use it. 6785151497Sru 6786151497Sru * Check all fonts in the order of appearance in the last `special' 6787151497Sru call. 6788151497Sru 6789151497Sru * If the symbol has been defined with the `schar' request, use it. 6790151497Sru 6791151497Sru * As a last resort, consult all fonts loaded up to now for special 6792151497Sru fonts and check them, starting with the lowest font number. Note 6793151497Sru that this can sometimes lead to surprising results since the 6794151497Sru `fonts' line in the `DESC' file often contains empty positions 6795151497Sru which are filled later on. For example, consider the following: 6796151497Sru 6797151497Sru 6798151497Sru fonts 3 0 0 FOO 6799151497Sru 6800151497Sru This mounts font `foo' at font position 3. We assume that `FOO' 6801151497Sru is a special font, containing glyph `foo', and that no font has 6802151497Sru been loaded yet. The line 6803151497Sru 6804151497Sru 6805151497Sru .fspecial BAR BAZ 6806151497Sru 6807151497Sru makes font `BAZ' special only if font `BAR' is active. We further 6808151497Sru assume that `BAZ' is really a special font, i.e., the font 6809151497Sru description file contains the `special' keyword, and that it also 6810151497Sru contains glyph `foo' with a special shape fitting to font `BAR'. 6811151497Sru After executing `fspecial', font `BAR' is loaded at font 6812151497Sru position 1, and `BAZ' at position 2. 6813151497Sru 6814151497Sru We now switch to a new font `XXX', trying to access glyph `foo' 6815151497Sru which is assumed to be missing. There are neither font-specific 6816151497Sru special fonts for `XXX' nor any other fonts made special with the 6817151497Sru `special' request, so `gtroff' starts the search for special fonts 6818151497Sru in the list of already mounted fonts, with increasing font 6819151497Sru positions. Consequently, it finds `BAZ' before `FOO' even for 6820151497Sru `XXX' which is not the intended behaviour. 6821151497Sru 6822151497Sru *Note Font Files::, and *Note Special Fonts::, for more details. 6823151497Sru 6824151497Sru The list of available symbols is device dependent; see the 6825151497Sru`groff_char(7)' man page for a complete list of all glyphs. For 6826151497Sruexample, say 6827151497Sru 6828151497Sru 6829151497Sru man -Tdvi groff_char > groff_char.dvi 6830151497Sru 6831151497Srufor a list using the default DVI fonts (not all versions of the `man' 6832151497Sruprogram support the `-T' option). If you want to use an additional 6833151497Srumacro package to change the used fonts, `groff' must be called directly: 6834151497Sru 6835151497Sru 6836151497Sru groff -Tdvi -mec -man groff_char.7 > groff_char.dvi 6837151497Sru 6838151497Sru Glyph names not listed in groff_char(7) are derived algorithmically, 6839151497Sruusing a simplified version of the Adobe Glyph List (AGL) algorithm 6840151497Sruwhich is described in 6841151497Sru`http://partners.adobe.com/asn/tech/type/unicodegn.jsp'. The (frozen) 6842151497Sruset of glyph names which can't be derived algorithmically is called 6843151497Sru"groff glyph list (GGL)". 6844151497Sru 6845151497Sru * A glyph for Unicode character U+XXXX[X[X]] which is not a 6846151497Sru composite character will be named `uXXXX[X[X]]'. X must be an 6847151497Sru uppercase hexadecimal digit. Examples: `u1234', `u008E', 6848151497Sru `u12DB8'. The largest Unicode value is 0x10FFFF. There must be at 6849151497Sru least four `X' digits; if necessary, add leading zeroes (after the 6850151497Sru `u'). No zero padding is allowed for character codes greater than 6851151497Sru 0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF 6852151497Sru represented with character codes from the surrogate area 6853151497Sru U+D800-U+DFFF) are not allowed too. 6854151497Sru 6855151497Sru * A glyph representing more than a single input character will be 6856151497Sru named 6857151497Sru 6858151497Sru `u' COMPONENT1 `_' COMPONENT2 `_' COMPONENT3 ... 6859151497Sru 6860151497Sru Example: `u0045_0302_0301'. 6861151497Sru 6862151497Sru For simplicity, all Unicode characters which are composites must be 6863151497Sru decomposed maximally (this is normalization form D in the Unicode 6864151497Sru standard); for example, `u00CA_0301' is not a valid glyph name 6865151497Sru since U+00CA (LATIN CAPITAL LETTER E WITH CIRCUMFLEX) can be 6866151497Sru further decomposed into U+0045 (LATIN CAPITAL LETTER E) and U+0302 6867151497Sru (COMBINING CIRCUMFLEX ACCENT). `u0045_0302_0301' is thus the 6868151497Sru glyph name for U+1EBE, LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND 6869151497Sru ACUTE. 6870151497Sru 6871151497Sru * groff maintains a table to decompose all algorithmically derived 6872151497Sru glyph names which are composites itself. For example, `u0100' 6873151497Sru (LATIN LETTER A WITH MACRON) will be automatically decomposed into 6874151497Sru `u0041_0304'. Additionally, a glyph name of the GGL is preferred 6875151497Sru to an algorithmically derived glyph name; groff also automatically 6876151497Sru does the mapping. Example: The glyph `u0045_0302' will be mapped 6877151497Sru to `^E'. 6878151497Sru 6879151497Sru * glyph names of the GGL can't be used in composite glyph names; for 6880151497Sru example, `^E_u0301' is invalid. 6881151497Sru 6882151497Sru -- Escape: \(nm 6883151497Sru -- Escape: \[name] 6884151497Sru -- Escape: \[component1 component2 ...] 6885151497Sru Insert a symbol NAME (two-character name NM) or a composite glyph 6886151497Sru with component glyphs COMPONENT1, COMPONENT2, .... There is no 6887151497Sru special syntax for one-character names - the natural form `\N' 6888151497Sru would collide with escapes.(1) (*note Using Symbols-Footnote-1::) 6889151497Sru 6890151497Sru If NAME is undefined, a warning of type `char' is generated, and 6891151497Sru the escape is ignored. *Note Debugging::, for information about 6892151497Sru warnings. 6893151497Sru 6894151497Sru groff resolves `\[...]' with more than a single component as 6895151497Sru follows: 6896151497Sru 6897151497Sru * Any component which is found in the GGL will be converted to 6898151497Sru the `uXXXX' form. 6899151497Sru 6900151497Sru * Any component `uXXXX' which is found in the list of 6901151497Sru decomposable glyphs will be decomposed. 6902151497Sru 6903151497Sru * The resulting elements are then concatenated with `_' 6904151497Sru inbetween, dropping the leading `u' in all elements but the 6905151497Sru first. 6906151497Sru 6907151497Sru No check for the existence of any component (similar to `tr' 6908151497Sru request) will be done. 6909151497Sru 6910151497Sru Examples: 6911151497Sru 6912151497Sru `\[A ho]' 6913151497Sru `A' maps to `u0041', `ho' maps to `u02DB', thus the final 6914151497Sru glyph name would be `u0041_02DB'. Note this is not the 6915151497Sru expected result: The ogonek glyph `ho' is a spacing ogonek, 6916151497Sru but for a proper composite a non-spacing ogonek (U+0328) is 6917151497Sru necessary. Looking into the file `composite.tmac' one can 6918151497Sru find `.composite ho u0328' which changes the mapping of `ho' 6919151497Sru while a composite glyph name is constructed, causing the 6920151497Sru final glyph name to be `u0041_0328'. 6921151497Sru 6922151497Sru `\[^E u0301]' 6923151497Sru `\[^E aa]' 6924151497Sru `\[E a^ aa]' 6925151497Sru `\[E ^ ']' 6926151497Sru `^E' maps to `u0045_0302', thus the final glyph name is 6927151497Sru `u0045_0302_0301' in all forms (assuming proper calls of the 6928151497Sru `composite' request). 6929151497Sru 6930151497Sru It is not possible to define glyphs with names like `A ho' within 6931151497Sru a groff font file. This is not really a limitation; instead, you 6932151497Sru have to define `u0041_0328'. 6933151497Sru 6934151497Sru -- Escape: \C'xxx' 6935151497Sru Typeset the glyph named XXX.(2) (*note Using Symbols-Footnote-2::) 6936151497Sru Normally it is more convenient to use `\[XXX]', but `\C' has the 6937151497Sru advantage that it is compatible with newer versions of AT&T 6938151497Sru `troff' and is available in compatibility mode. 6939151497Sru 6940151497Sru -- Request: .composite from to 6941151497Sru Map glyph name FROM to glyph name TO if it is used in `\[...]' 6942151497Sru with more than one component. See above for examples. 6943151497Sru 6944151497Sru This mapping is based on glyph names only; no check for the 6945151497Sru existence of either glyph is done. 6946151497Sru 6947151497Sru A set of default mappings for many accents can be found in the file 6948151497Sru `composite.tmac' which is loaded at start-up. 6949151497Sru 6950151497Sru -- Escape: \N'n' 6951151497Sru Typeset the glyph with code N in the current font (`n' is *not* 6952151497Sru the input character code). The number N can be any non-negative 6953151497Sru decimal integer. Most devices only have glyphs with codes between 6954151497Sru 0 and 255; the Unicode output device uses codes in the range 6955151497Sru 0-65535. If the current font does not contain a glyph with that 6956151497Sru code, special fonts are _not_ searched. The `\N' escape sequence 6957151497Sru can be conveniently used in conjunction with the `char' request: 6958151497Sru 6959151497Sru 6960151497Sru .char \[phone] \f[ZD]\N'37' 6961151497Sru 6962151497Sru The code of each glyph is given in the fourth column in the font 6963151497Sru description file after the `charset' command. It is possible to 6964151497Sru include unnamed glyphs in the font description file by using a 6965151497Sru name of `---'; the `\N' escape sequence is the only way to use 6966151497Sru these. 6967151497Sru 6968151497Sru No kerning is applied to glyphs accessed with `\N'. 6969151497Sru 6970151497Sru Some escape sequences directly map onto special glyphs. 6971151497Sru 6972151497Sru -- Escape: \' 6973151497Sru This is a backslash followed by the apostrophe character, ASCII 6974151497Sru character `0x27' (EBCDIC character `0x7D'). The same as `\[aa]', 6975151497Sru the acute accent. 6976151497Sru 6977151497Sru -- Escape: \` 6978151497Sru This is a backslash followed by ASCII character `0x60' (EBCDIC 6979151497Sru character `0x79' usually). The same as `\[ga]', the grave accent. 6980151497Sru 6981151497Sru -- Escape: \- 6982151497Sru This is the same as `\[-]', the minus sign in the current font. 6983151497Sru 6984151497Sru -- Request: .cflags n c1 c2 ... 6985151497Sru Input characters and symbols have certain properties associated 6986151497Sru with it.(3) (*note Using Symbols-Footnote-3::) These properties 6987151497Sru can be modified with the `cflags' request. The first argument is 6988151497Sru the sum of the desired flags and the remaining arguments are the 6989151497Sru characters or symbols to have those properties. It is possible to 6990151497Sru omit the spaces between the characters or symbols. 6991151497Sru 6992151497Sru `1' 6993151497Sru The character ends sentences (initially characters `.?!' have 6994151497Sru this property). 6995151497Sru 6996151497Sru `2' 6997151497Sru Lines can be broken before the character (initially no 6998151497Sru characters have this property). 6999151497Sru 7000151497Sru `4' 7001151497Sru Lines can be broken after the character (initially the 7002151497Sru character `-' and the symbols `\[hy]' and `\[em]' have this 7003151497Sru property). 7004151497Sru 7005151497Sru `8' 7006151497Sru The character overlaps horizontally if used as a horizontal 7007151497Sru line building element. Initially the symbols `\[ul]', 7008151497Sru `\[rn]', `\[ru]', `\[radicalex]', and `\[sqrtex]' have this 7009151497Sru property. 7010151497Sru 7011151497Sru `16' 7012151497Sru The character overlaps vertically if used as vertical line 7013151497Sru building element. Initially symbol `\[br]' has this property. 7014151497Sru 7015151497Sru `32' 7016151497Sru An end-of-sentence character followed by any number of 7017151497Sru characters with this property is treated as the end of a 7018151497Sru sentence if followed by a newline or two spaces; in other 7019151497Sru words the character is "transparent" for the purposes of 7020151497Sru end-of-sentence recognition - this is the same as having a 7021151497Sru zero space factor in TeX (initially characters `"')]*' and 7022151497Sru the symbols `\[dg]' and `\[rq]' have this property). 7023151497Sru 7024151497Sru -- Request: .char g [string] 7025151497Sru -- Request: .fchar g [string] 7026151497Sru -- Request: .fschar f g [string] 7027151497Sru -- Request: .schar g [string] 7028151497Sru Define a new glyph G to be STRING (which can be empty).(4) (*note 7029151497Sru Using Symbols-Footnote-4::) Every time glyph G needs to be 7030151497Sru printed, STRING is processed in a temporary environment and the 7031151497Sru result is wrapped up into a single object. Compatibility mode is 7032151497Sru turned off and the escape character is set to `\' while STRING is 7033151497Sru being processed. Any emboldening, constant spacing or track 7034151497Sru kerning is applied to this object rather than to individual 7035151497Sru characters in STRING. 7036151497Sru 7037151497Sru A glyph defined by these requests can be used just like a normal 7038151497Sru glyph provided by the output device. In particular, other 7039151497Sru characters can be translated to it with the `tr' or `trin' 7040151497Sru requests; it can be made the leader character by the `lc' request; 7041151497Sru repeated patterns can be drawn with the glyph using the `\l' and 7042151497Sru `\L' escape sequences; words containing the glyph can be 7043151497Sru hyphenated correctly if the `hcode' request is used to give the 7044151497Sru glyph's symbol a hyphenation code. 7045151497Sru 7046151497Sru There is a special anti-recursion feature: Use of `g' within the 7047151497Sru glyph's definition is handled like normal characters and symbols 7048151497Sru not defined with `char'. 7049151497Sru 7050151497Sru Note that the `tr' and `trin' requests take precedence if `char' 7051151497Sru accesses the same symbol. 7052151497Sru 7053151497Sru 7054151497Sru .tr XY 7055151497Sru X 7056151497Sru => Y 7057151497Sru .char X Z 7058151497Sru X 7059151497Sru => Y 7060151497Sru .tr XX 7061151497Sru X 7062151497Sru => Z 7063151497Sru 7064151497Sru The `fchar' request defines a fallback glyph: `gtroff' only checks 7065151497Sru for glyphs defined with `fchar' if it cannot find the glyph in the 7066151497Sru current font. `gtroff' carries out this test before checking 7067151497Sru special fonts. 7068151497Sru 7069151497Sru `fschar' defines a fallback glyph for font F: `gtroff' checks for 7070151497Sru glyphs defined with `fschar' after the list of fonts declared as 7071151497Sru font-specific special fonts with the `fspecial' request, but 7072151497Sru before the list of fonts declared as global special fonts with the 7073151497Sru `special' request. 7074151497Sru 7075151497Sru Finally, the `schar' request defines a global fallback glyph: 7076151497Sru `gtroff' checks for glyphs defined with `schar' after the list of 7077151497Sru fonts declared as global special fonts with the `special' request, 7078151497Sru but before the already mounted special fonts. 7079151497Sru 7080151497Sru *Note Using Symbols::, for a detailed description of the glyph 7081151497Sru searching mechanism in `gtroff'. 7082151497Sru 7083151497Sru -- Request: .rchar c1 c2 ... 7084151497Sru -- Request: .rfschar f c1 c2 ... 7085151497Sru Remove the definitions of glyphs C1, C2, .... This undoes the 7086151497Sru effect of a `char', `fchar', or `schar' request. 7087151497Sru 7088151497Sru It is possible to omit the whitespace between arguments. 7089151497Sru 7090151497Sru The request `rfschar' removes glyph definitions defined with 7091151497Sru `fschar' for glyph f. 7092151497Sru 7093151497Sru *Note Special Characters::. 7094151497Sru 7095151497Sru 7096151497SruFile: groff, Node: Using Symbols-Footnotes, Up: Using Symbols 7097151497Sru 7098151497Sru (1) Note that a one-character symbol is not the same as an input 7099151497Srucharacter, i.e., the character `a' is not the same as `\[a]'. By 7100151497Srudefault, `groff' defines only a single one-character symbol, `\[-]'; it 7101151497Sruis usually accessed as `\-'. On the other hand, `gtroff' has the 7102151497Sruspecial feature that `\[charXXX]' is the same as the input character 7103151497Sruwith character code XXX. For example, `\[char97]' is identical to the 7104151497Sruletter `a' if ASCII encoding is active. 7105151497Sru 7106151497Sru (2) `\C' is actually a misnomer since it accesses an output glyph. 7107151497Sru 7108151497Sru (3) Note that the output glyphs themselves don't have such 7109151497Sruproperties. For `gtroff', a glyph is a numbered box with a given 7110151497Sruwidth, depth, and height, nothing else. All manipulations with the 7111151497Sru`cflags' request work on the input level. 7112151497Sru 7113151497Sru (4) `char' is a misnomer since an output glyph is defined. 7114151497Sru 7115151497Sru 7116151497SruFile: groff, Node: Special Fonts, Next: Artificial Fonts, Prev: Using Symbols, Up: Fonts and Symbols 7117151497Sru 7118151497Sru5.17.5 Special Fonts 7119151497Sru-------------------- 7120151497Sru 7121151497SruSpecial fonts are those that `gtroff' searches when it cannot find the 7122151497Srurequested glyph in the current font. The Symbol font is usually a 7123151497Sruspecial font. 7124151497Sru 7125151497Sru `gtroff' provides the following two requests to add more special 7126151497Srufonts. *Note Using Symbols::, for a detailed description of the glyph 7127151497Srusearching mechanism in `gtroff'. 7128151497Sru 7129151497Sru Usually, only non-TTY devices have special fonts. 7130151497Sru 7131151497Sru -- Request: .special [s1 s2 ...] 7132151497Sru -- Request: .fspecial f [s1 s2 ...] 7133151497Sru Use the `special' request to define special fonts. Initially, this 7134151497Sru list is empty. 7135151497Sru 7136151497Sru Use the `fspecial' request to designate special fonts only when 7137151497Sru font F is active. Initially, this list is empty. 7138151497Sru 7139151497Sru Previous calls to `special' or `fspecial' are overwritten; without 7140151497Sru arguments, the particular list of special fonts is set to empty. 7141151497Sru Special fonts are searched in the order they appear as arguments. 7142151497Sru 7143151497Sru All fonts which appear in a call to `special' or `fspecial' are 7144151497Sru loaded. 7145151497Sru 7146151497Sru *Note Using Symbols::, for the exact search order of glyphs. 7147151497Sru 7148151497Sru 7149151497SruFile: groff, Node: Artificial Fonts, Next: Ligatures and Kerning, Prev: Special Fonts, Up: Fonts and Symbols 7150151497Sru 7151151497Sru5.17.6 Artificial Fonts 7152151497Sru----------------------- 7153151497Sru 7154151497SruThere are a number of requests and escapes for artificially creating 7155151497Srufonts. These are largely vestiges of the days when output devices did 7156151497Srunot have a wide variety of fonts, and when `nroff' and `troff' were 7157151497Sruseparate programs. Most of them are no longer necessary in GNU 7158151497Sru`troff'. Nevertheless, they are supported. 7159151497Sru 7160151497Sru -- Escape: \H'height' 7161151497Sru -- Escape: \H'+height' 7162151497Sru -- Escape: \H'-height' 7163151497Sru -- Register: \n[.height] 7164151497Sru Change (increment, decrement) the height of the current font, but 7165151497Sru not the width. If HEIGHT is zero, restore the original height. 7166151497Sru Default scaling indicator is `z'. 7167151497Sru 7168151497Sru The read-only number register `.height' contains the font height as 7169151497Sru set by `\H'. 7170151497Sru 7171151497Sru Currently, only the `-Tps' device supports this feature. 7172151497Sru 7173151497Sru Note that `\H' doesn't produce an input token in `gtroff'. As a 7174151497Sru consequence, it can be used in requests like `mc' (which expects a 7175151497Sru single character as an argument) to change the font on the fly: 7176151497Sru 7177151497Sru 7178151497Sru .mc \H'+5z'x\H'0' 7179151497Sru 7180151497Sru In compatibility mode, `gtroff' behaves differently: If an 7181151497Sru increment or decrement is used, it is always taken relative to the 7182151497Sru current point size and not relative to the previously selected font 7183151497Sru height. Thus, 7184151497Sru 7185151497Sru 7186151497Sru .cp 1 7187151497Sru \H'+5'test \H'+5'test 7188151497Sru 7189151497Sru prints the word `test' twice with the same font height (five 7190151497Sru points larger than the current font size). 7191151497Sru 7192151497Sru -- Escape: \S'slant' 7193151497Sru -- Register: \n[.slant] 7194151497Sru Slant the current font by SLANT degrees. Positive values slant to 7195151497Sru the right. Only integer values are possible. 7196151497Sru 7197151497Sru The read-only number register `.slant' contains the font slant as 7198151497Sru set by `\S'. 7199151497Sru 7200151497Sru Currently, only the `-Tps' device supports this feature. 7201151497Sru 7202151497Sru Note that `\S' doesn't produce an input token in `gtroff'. As a 7203151497Sru consequence, it can be used in requests like `mc' (which expects a 7204151497Sru single character as an argument) to change the font on the fly: 7205151497Sru 7206151497Sru 7207151497Sru .mc \S'20'x\S'0' 7208151497Sru 7209151497Sru This request is incorrectly documented in the original UNIX troff 7210151497Sru manual; the slant is always set to an absolute value. 7211151497Sru 7212151497Sru -- Request: .ul [lines] 7213151497Sru The `ul' request normally underlines subsequent lines if a TTY 7214151497Sru output device is used. Otherwise, the lines are printed in italics 7215151497Sru (only the term `underlined' is used in the following). The single 7216151497Sru argument is the number of input lines to be underlined; with no 7217151497Sru argument, the next line is underlined. If LINES is zero or 7218151497Sru negative, stop the effects of `ul' (if it was active). Requests 7219151497Sru and empty lines do not count for computing the number of underlined 7220151497Sru input lines, even if they produce some output like `tl'. Lines 7221151497Sru inserted by macros (e.g. invoked by a trap) do count. 7222151497Sru 7223151497Sru At the beginning of `ul', the current font is stored and the 7224151497Sru underline font is activated. Within the span of a `ul' request, 7225151497Sru it is possible to change fonts, but after the last line affected by 7226151497Sru `ul' the saved font is restored. 7227151497Sru 7228151497Sru This number of lines still to be underlined is associated with the 7229151497Sru current environment (*note Environments::). The underline font 7230151497Sru can be changed with the `uf' request. 7231151497Sru 7232151497Sru The `ul' request does not underline spaces. 7233151497Sru 7234151497Sru -- Request: .cu [lines] 7235151497Sru The `cu' request is similar to `ul' but underlines spaces as well 7236151497Sru (if a TTY output device is used). 7237151497Sru 7238151497Sru -- Request: .uf font 7239151497Sru Set the underline font (globally) used by `ul' and `cu'. By 7240151497Sru default, this is the font at position 2. FONT can be either a 7241151497Sru non-negative font position or the name of a font. 7242151497Sru 7243151497Sru -- Request: .bd font [offset] 7244151497Sru -- Request: .bd font1 font2 [offset] 7245151497Sru -- Register: \n[.b] 7246151497Sru Artificially create a bold font by printing each glyph twice, 7247151497Sru slightly offset. 7248151497Sru 7249151497Sru Two syntax forms are available. 7250151497Sru 7251151497Sru * Imitate a bold font unconditionally. The first argument 7252151497Sru specifies the font to embolden, and the second is the number 7253151497Sru of basic units, minus one, by which the two glyphs are 7254151497Sru offset. If the second argument is missing, emboldening is 7255151497Sru turned off. 7256151497Sru 7257151497Sru FONT can be either a non-negative font position or the name 7258151497Sru of a font. 7259151497Sru 7260151497Sru OFFSET is available in the `.b' read-only register if a 7261151497Sru special font is active; in the `bd' request, its default unit 7262151497Sru is `u'. 7263151497Sru 7264151497Sru * Imitate a bold form conditionally. Embolden FONT1 by OFFSET 7265151497Sru only if font FONT2 is the current font. This command can be 7266151497Sru issued repeatedly to set up different emboldening values for 7267151497Sru different current fonts. If the second argument is missing, 7268151497Sru emboldening is turned off for this particular current font. 7269151497Sru 7270151497Sru This affects special fonts only (either set up with the 7271151497Sru `special' command in font files or with the `fspecial' 7272151497Sru request). 7273151497Sru 7274151497Sru -- Request: .cs font [width [em-size]] 7275151497Sru Switch to and from "constant glyph space mode". If activated, the 7276151497Sru width of every glyph is WIDTH/36 ems. The em size is given 7277151497Sru absolutely by EM-SIZE; if this argument is missing, the em value 7278151497Sru is taken from the current font size (as set with the `ps' request) 7279151497Sru when the font is effectively in use. Without second and third 7280151497Sru argument, constant glyph space mode is deactivated. 7281151497Sru 7282151497Sru Default scaling indicator for EM-SIZE is `z'; WIDTH is an integer. 7283151497Sru 7284151497Sru 7285151497SruFile: groff, Node: Ligatures and Kerning, Prev: Artificial Fonts, Up: Fonts and Symbols 7286151497Sru 7287151497Sru5.17.7 Ligatures and Kerning 7288151497Sru---------------------------- 7289151497Sru 7290151497SruLigatures are groups of characters that are run together, i.e, producing 7291151497Srua single glyph. For example, the letters `f' and `i' can form a 7292151497Sruligature `fi' as in the word `file'. This produces a cleaner look 7293151497Sru(albeit subtle) to the printed output. Usually, ligatures are not 7294151497Sruavailable in fonts for TTY output devices. 7295151497Sru 7296151497Sru Most POSTSCRIPT fonts support the fi and fl ligatures. The C/A/T 7297151497Srutypesetter that was the target of AT&T `troff' also supported `ff', 7298151497Sru`ffi', and `ffl' ligatures. Advanced typesetters or `expert' fonts may 7299151497Sruinclude ligatures for `ft' and `ct', although GNU `troff' does not 7300151497Srusupport these (yet). 7301151497Sru 7302151497Sru Only the current font is checked for ligatures and kerns; neither 7303151497Sruspecial fonts nor entities defined with the `char' request (and its 7304151497Srusiblings) are taken into account. 7305151497Sru 7306151497Sru -- Request: .lg [flag] 7307151497Sru -- Register: \n[.lg] 7308151497Sru Switch the ligature mechanism on or off; if the parameter is 7309151497Sru non-zero or missing, ligatures are enabled, otherwise disabled. 7310151497Sru Default is on. The current ligature mode can be found in the 7311151497Sru read-only number register `.lg' (set to 1 or 2 if ligatures are 7312151497Sru enabled, 0 otherwise). 7313151497Sru 7314151497Sru Setting the ligature mode to 2 enables the two-character ligatures 7315151497Sru (fi, fl, and ff) and disables the three-character ligatures (ffi 7316151497Sru and ffl). 7317151497Sru 7318151497Sru "Pairwise kerning" is another subtle typesetting mechanism that 7319151497Srumodifies the distance between a glyph pair to improve readability. In 7320151497Srumost cases (but not always) the distance is decreased. Typewriter-like 7321151497Srufonts and fonts for terminals where all glyphs have the same width 7322151497Srudon't use kerning. 7323151497Sru 7324151497Sru -- Request: .kern [flag] 7325151497Sru -- Register: \n[.kern] 7326151497Sru Switch kerning on or off. If the parameter is non-zero or missing, 7327151497Sru enable pairwise kerning, otherwise disable it. The read-only 7328151497Sru number register `.kern' is set to 1 if pairwise kerning is enabled, 7329151497Sru 0 otherwise. 7330151497Sru 7331151497Sru If the font description file contains pairwise kerning information, 7332151497Sru glyphs from that font are kerned. Kerning between two glyphs can 7333151497Sru be inhibited by placing `\&' between them: `V\&A'. 7334151497Sru 7335151497Sru *Note Font File Format::. 7336151497Sru 7337151497Sru "Track kerning" expands or reduces the space between glyphs. This 7338151497Srucan be handy, for example, if you need to squeeze a long word onto a 7339151497Srusingle line or spread some text to fill a narrow column. It must be 7340151497Sruused with great care since it is usually considered bad typography if 7341151497Sruthe reader notices the effect. 7342151497Sru 7343151497Sru -- Request: .tkf f s1 n1 s2 n2 7344151497Sru Enable track kerning for font F. If the current font is F the 7345151497Sru width of every glyph is increased by an amount between N1 and N2 7346151497Sru (N1, N2 can be negative); if the current point size is less than 7347151497Sru or equal to S1 the width is increased by N1; if it is greater than 7348151497Sru or equal to S2 the width is increased by N2; if the point size is 7349151497Sru greater than or equal to S1 and less than or equal to S2 the 7350151497Sru increase in width is a linear function of the point size. 7351151497Sru 7352151497Sru The default scaling indicator is `z' for S1 and S2, `p' for N1 and 7353151497Sru N2. 7354151497Sru 7355151497Sru Note that the track kerning amount is added even to the rightmost 7356151497Sru glyph in a line; for large values it is thus recommended to 7357151497Sru increase the line length by the same amount to compensate it. 7358151497Sru 7359151497Sru Sometimes, when typesetting letters of different fonts, more or less 7360151497Sruspace at such boundaries are needed. There are two escapes to help 7361151497Sruwith this. 7362151497Sru 7363151497Sru -- Escape: \/ 7364151497Sru Increase the width of the preceding glyph so that the spacing 7365151497Sru between that glyph and the following glyph is correct if the 7366151497Sru following glyph is a roman glyph. For example, if an italic `f' 7367151497Sru is immediately followed by a roman right parenthesis, then in many 7368151497Sru fonts the top right portion of the `f' overlaps the top left of 7369151497Sru the right parenthesis. Use this escape sequence whenever an 7370151497Sru italic glyph is immediately followed by a roman glyph without any 7371151497Sru intervening space. This small amount of space is also called 7372151497Sru "italic correction". 7373151497Sru 7374151497Sru 7375151497Sru -- Escape: \, 7376151497Sru Modify the spacing of the following glyph so that the spacing 7377151497Sru between that glyph and the preceding glyph is correct if the 7378151497Sru preceding glyph is a roman glyph. Use this escape sequence 7379151497Sru whenever a roman glyph is immediately followed by an italic glyph 7380151497Sru without any intervening space. In analogy to above, this space 7381151497Sru could be called "left italic correction", but this term isn't used 7382151497Sru widely. 7383151497Sru 7384151497Sru 7385151497Sru -- Escape: \& 7386151497Sru Insert a zero-width character, which is invisible. Its intended 7387151497Sru use is to stop interaction of a character with its surrounding. 7388151497Sru 7389151497Sru * It prevents the insertion of extra space after an 7390151497Sru end-of-sentence character. 7391151497Sru 7392151497Sru 7393151497Sru Test. 7394151497Sru Test. 7395151497Sru => Test. Test. 7396151497Sru Test.\& 7397151497Sru Test. 7398151497Sru => Test. Test. 7399151497Sru 7400151497Sru * It prevents interpretation of a control character at the 7401151497Sru beginning of an input line. 7402151497Sru 7403151497Sru 7404151497Sru .Test 7405151497Sru => warning: `Test' not defined 7406151497Sru \&.Test 7407151497Sru => .Test 7408151497Sru 7409151497Sru * It prevents kerning between two glyphs. 7410151497Sru 7411151497Sru * It is needed to map an arbitrary character to nothing in the 7412151497Sru `tr' request (*note Character Translations::). 7413151497Sru 7414151497Sru -- Escape: \) 7415151497Sru This escape is similar to `\&' except that it behaves like a 7416151497Sru character declared with the `cflags' request to be transparent for 7417151497Sru the purposes of an end-of-sentence character. 7418151497Sru 7419151497Sru Its main usage is in macro definitions to protect against arguments 7420151497Sru starting with a control character. 7421151497Sru 7422151497Sru 7423151497Sru .de xxx 7424151497Sru \)\\$1 7425151497Sru .. 7426151497Sru .de yyy 7427151497Sru \&\\$1 7428151497Sru .. 7429151497Sru This is a test.\c 7430151497Sru .xxx ' 7431151497Sru This is a test. 7432151497Sru =>This is a test.' This is a test. 7433151497Sru This is a test.\c 7434151497Sru .yyy ' 7435151497Sru This is a test. 7436151497Sru =>This is a test.' This is a test. 7437151497Sru 7438151497Sru 7439151497Sru 7440151497SruFile: groff, Node: Sizes, Next: Strings, Prev: Fonts and Symbols, Up: gtroff Reference 7441151497Sru 7442151497Sru5.18 Sizes 7443151497Sru========== 7444151497Sru 7445151497Sru`gtroff' uses two dimensions with each line of text, type size and 7446151497Sruvertical spacing. The "type size" is approximately the height of the 7447151497Srutallest glyph.(1) (*note Sizes-Footnote-1::) "Vertical spacing" is the 7448151497Sruamount of space `gtroff' allows for a line of text; normally, this is 7449151497Sruabout 20% larger than the current type size. Ratios smaller than this 7450151497Srucan result in hard-to-read text; larger than this, it spreads the text 7451151497Sruout more vertically (useful for term papers). By default, `gtroff' 7452151497Sruuses 10 point type on 12 point spacing. 7453151497Sru 7454151497Sru The difference between type size and vertical spacing is known, by 7455151497Srutypesetters, as "leading" (this is pronounced `ledding'). 7456151497Sru 7457151497Sru* Menu: 7458151497Sru 7459151497Sru* Changing Type Sizes:: 7460151497Sru* Fractional Type Sizes:: 7461151497Sru 7462151497Sru 7463151497SruFile: groff, Node: Sizes-Footnotes, Up: Sizes 7464151497Sru 7465151497Sru (1) This is usually the parenthesis. Note that in most cases the 7466151497Srureal dimensions of the glyphs in a font are _not_ related to its type 7467151497Srusize! For example, the standard POSTSCRIPT font families `Times 7468151497SruRoman', `Helvetica', and `Courier' can't be used together at 10pt; to 7469151497Sruget acceptable output, the size of `Helvetica' has to be reduced by one 7470151497Srupoint, and the size of `Courier' must be increased by one point. 7471151497Sru 7472151497Sru 7473151497SruFile: groff, Node: Changing Type Sizes, Next: Fractional Type Sizes, Prev: Sizes, Up: Sizes 7474151497Sru 7475151497Sru5.18.1 Changing Type Sizes 7476151497Sru-------------------------- 7477151497Sru 7478151497Sru -- Request: .ps [size] 7479151497Sru -- Request: .ps +size 7480151497Sru -- Request: .ps -size 7481151497Sru -- Escape: \ssize 7482151497Sru -- Register: \n[.s] 7483151497Sru Use the `ps' request or the `\s' escape to change (increase, 7484151497Sru decrease) the type size (in points). Specify SIZE as either an 7485151497Sru absolute point size, or as a relative change from the current size. 7486151497Sru The size 0, or no argument, goes back to the previous size. 7487151497Sru 7488151497Sru Default scaling indicator of `size' is `z'. If `size' is zero or 7489151497Sru negative, it is set to 1u. 7490151497Sru 7491151497Sru The read-only number register `.s' returns the point size in 7492151497Sru points as a decimal fraction. This is a string. To get the point 7493151497Sru size in scaled points, use the `.ps' register instead. 7494151497Sru 7495151497Sru `.s' is associated with the current environment (*note 7496151497Sru Environments::). 7497151497Sru 7498151497Sru 7499151497Sru snap, snap, 7500151497Sru .ps +2 7501151497Sru grin, grin, 7502151497Sru .ps +2 7503151497Sru wink, wink, \s+2nudge, nudge,\s+8 say no more! 7504151497Sru .ps 10 7505151497Sru 7506151497Sru The `\s' escape may be called in a variety of ways. Much like 7507151497Sru other escapes there must be a way to determine where the argument 7508151497Sru ends and the text begins. Any of the following forms are valid: 7509151497Sru 7510151497Sru `\sN' 7511151497Sru Set the point size to N points. N must be either 0 or in the 7512151497Sru range 4 to 39. 7513151497Sru 7514151497Sru `\s+N' 7515151497Sru `\s-N' 7516151497Sru Increase or decrease the point size by N points. N must be 7517151497Sru exactly one digit. 7518151497Sru 7519151497Sru `\s(NN' 7520151497Sru Set the point size to NN points. NN must be exactly two 7521151497Sru digits. 7522151497Sru 7523151497Sru `\s+(NN' 7524151497Sru `\s-(NN' 7525151497Sru `\s(+NN' 7526151497Sru `\s(-NN' 7527151497Sru Increase or decrease the point size by NN points. NN must be 7528151497Sru exactly two digits. 7529151497Sru 7530151497Sru Note that `\s' doesn't produce an input token in `gtroff'. As a 7531151497Sru consequence, it can be used in requests like `mc' (which expects a 7532151497Sru single character as an argument) to change the font on the fly: 7533151497Sru 7534151497Sru 7535151497Sru .mc \s[20]x\s[0] 7536151497Sru 7537151497Sru *Note Fractional Type Sizes::, for yet another syntactical form of 7538151497Sru using the `\s' escape. 7539151497Sru 7540151497Sru -- Request: .sizes s1 s2 ... sn [0] 7541151497Sru Some devices may only have certain permissible sizes, in which case 7542151497Sru `gtroff' rounds to the nearest permissible size. The `DESC' file 7543151497Sru specifies which sizes are permissible for the device. 7544151497Sru 7545151497Sru Use the `sizes' request to change the permissible sizes for the 7546151497Sru current output device. Arguments are in scaled points; the 7547151497Sru `sizescale' line in the `DESC' file for the output device provides 7548151497Sru the scaling factor. For example, if the scaling factor is 1000, 7549151497Sru then the value 12000 is 12 points. 7550151497Sru 7551151497Sru Each argument can be a single point size (such as `12000'), or a 7552151497Sru range of sizes (such as `4000-72000'). You can optionally end the 7553151497Sru list with a zero. 7554151497Sru 7555151497Sru -- Request: .vs [space] 7556151497Sru -- Request: .vs +space 7557151497Sru -- Request: .vs -space 7558151497Sru -- Register: \n[.v] 7559151497Sru Change (increase, decrease) the vertical spacing by SPACE. The 7560151497Sru default scaling indicator is `p'. 7561151497Sru 7562151497Sru If `vs' is called without an argument, the vertical spacing is 7563151497Sru reset to the previous value before the last call to `vs'. 7564151497Sru 7565151497Sru `gtroff' creates a warning of type `range' if SPACE is negative; 7566151497Sru the vertical spacing is then set to smallest positive value, the 7567151497Sru vertical resolution (as given in the `.V' register). 7568151497Sru 7569151497Sru Note that `.vs 0' isn't saved in a diversion since it doesn't 7570151497Sru result in a vertical motion. You explicitly have to repeat this 7571151497Sru command before inserting the diversion. 7572151497Sru 7573151497Sru The read-only number register `.v' contains the current vertical 7574151497Sru spacing; it is associated with the current environment (*note 7575151497Sru Environments::). 7576151497Sru 7577151497Sru The effective vertical line spacing consists of four components. 7578151497SruBreaking a line causes the following actions (in the given order). 7579151497Sru 7580151497Sru * Move the current point vertically by the "extra pre-vertical line 7581151497Sru space". This is the minimum value of all `\x' escapes with a 7582151497Sru negative argument in the current output line. 7583151497Sru 7584151497Sru * Move the current point vertically by the vertical line spacing as 7585151497Sru set with the `vs' request. 7586151497Sru 7587151497Sru * Output the current line. 7588151497Sru 7589151497Sru * Move the current point vertically by the "extra post-vertical line 7590151497Sru space". This is the maximum value of all `\x' escapes with a 7591151497Sru positive argument in the line which has just been output. 7592151497Sru 7593151497Sru * Move the current point vertically by the "post-vertical line 7594151497Sru spacing" as set with the `pvs' request. 7595151497Sru 7596151497Sru It is usually better to use `vs' or `pvs' instead of `ls' to produce 7597151497Srudouble-spaced documents: `vs' and `pvs' have a finer granularity for 7598151497Sruthe inserted vertical space compared to `ls'; furthermore, certain 7599151497Srupreprocessors assume single-spacing. 7600151497Sru 7601151497Sru *Note Manipulating Spacing::, for more details on the `\x' escape 7602151497Sruand the `ls' request. 7603151497Sru 7604151497Sru -- Request: .pvs [space] 7605151497Sru -- Request: .pvs +space 7606151497Sru -- Request: .pvs -space 7607151497Sru -- Register: \n[.pvs] 7608151497Sru Change (increase, decrease) the post-vertical spacing by SPACE. 7609151497Sru The default scaling indicator is `p'. 7610151497Sru 7611151497Sru If `pvs' is called without an argument, the post-vertical spacing 7612151497Sru is reset to the previous value before the last call to `pvs'. 7613151497Sru 7614151497Sru `gtroff' creates a warning of type `range' if SPACE is zero or 7615151497Sru negative; the vertical spacing is then set to zero. 7616151497Sru 7617151497Sru The read-only number register `.pvs' contains the current 7618151497Sru post-vertical spacing; it is associated with the current 7619151497Sru environment (*note Environments::). 7620151497Sru 7621151497Sru 7622151497SruFile: groff, Node: Fractional Type Sizes, Prev: Changing Type Sizes, Up: Sizes 7623151497Sru 7624151497Sru5.18.2 Fractional Type Sizes 7625151497Sru---------------------------- 7626151497Sru 7627151497SruA "scaled point" is equal to 1/SIZESCALE points, where SIZESCALE is 7628151497Sruspecified in the `DESC' file (1 by default). There is a new scale 7629151497Sruindicator `z' which has the effect of multiplying by SIZESCALE. 7630151497SruRequests and escape sequences in `gtroff' interpret arguments that 7631151497Srurepresent a point size as being in units of scaled points, but they 7632151497Sruevaluate each such argument using a default scale indicator of `z'. 7633151497SruArguments treated in this way are the argument to the `ps' request, the 7634151497Sruthird argument to the `cs' request, the second and fourth arguments to 7635151497Sruthe `tkf' request, the argument to the `\H' escape sequence, and those 7636151497Sruvariants of the `\s' escape sequence that take a numeric expression as 7637151497Srutheir argument (see below). 7638151497Sru 7639151497Sru For example, suppose SIZESCALE is 1000; then a scaled point is 7640151497Sruequivalent to a millipoint; the request `.ps 10.25' is equivalent to 7641151497Sru`.ps 10.25z' and thus sets the point size to 10250 scaled points, which 7642151497Sruis equal to 10.25 points. 7643151497Sru 7644151497Sru `gtroff' disallows the use of the `z' scale indicator in instances 7645151497Sruwhere it would make no sense, such as a numeric expression whose 7646151497Srudefault scale indicator was neither `u' nor `z'. Similarly it would 7647151497Srumake no sense to use a scaling indicator other than `z' or `u' in a 7648151497Srunumeric expression whose default scale indicator was `z', and so 7649151497Sru`gtroff' disallows this as well. 7650151497Sru 7651151497Sru There is also new scale indicator `s' which multiplies by the number 7652151497Sruof units in a scaled point. So, for example, `\n[.ps]s' is equal to 7653151497Sru`1m'. Be sure not to confuse the `s' and `z' scale indicators. 7654151497Sru 7655151497Sru -- Register: \n[.ps] 7656151497Sru A read-only number register returning the point size in scaled 7657151497Sru points. 7658151497Sru 7659151497Sru `.ps' is associated with the current environment (*note 7660151497Sru Environments::). 7661151497Sru 7662151497Sru -- Register: \n[.psr] 7663151497Sru -- Register: \n[.sr] 7664151497Sru The last-requested point size in scaled points is contained in the 7665151497Sru `.psr' read-only number register. The last requested point size 7666151497Sru in points as a decimal fraction can be found in `.sr'. This is a 7667151497Sru string-valued read-only number register. 7668151497Sru 7669151497Sru Note that the requested point sizes are device-independent, whereas 7670151497Sru the values returned by the `.ps' and `.s' registers are not. For 7671151497Sru example, if a point size of 11pt is requested, and a `sizes' 7672151497Sru request (or a `sizescale' line in a `DESC' file) specifies 10.95pt 7673151497Sru instead, this value is actually used. 7674151497Sru 7675151497Sru Both registers are associated with the current environment (*note 7676151497Sru Environments::). 7677151497Sru 7678151497Sru The `\s' escape has the following syntax for working with fractional 7679151497Srutype sizes: 7680151497Sru 7681151497Sru`\s[N]' 7682151497Sru`\s'N'' 7683151497Sru Set the point size to N scaled points; N is a numeric expression 7684151497Sru with a default scale indicator of `z'. 7685151497Sru 7686151497Sru`\s[+N]' 7687151497Sru`\s[-N]' 7688151497Sru`\s+[N]' 7689151497Sru`\s-[N]' 7690151497Sru`\s'+N'' 7691151497Sru`\s'-N'' 7692151497Sru`\s+'N'' 7693151497Sru`\s-'N'' 7694151497Sru Increase or or decrease the point size by N scaled points; N is a 7695151497Sru numeric expression with a default scale indicator of `z'. 7696151497Sru 7697151497Sru *Note Font Files::. 7698151497Sru 7699151497Sru 7700151497SruFile: groff, Node: Strings, Next: Conditionals and Loops, Prev: Sizes, Up: gtroff Reference 7701151497Sru 7702151497Sru5.19 Strings 7703151497Sru============ 7704151497Sru 7705151497Sru`gtroff' has string variables, which are entirely for user convenience 7706151497Sru(i.e. there are no built-in strings exept `.T', but even this is a 7707151497Sruread-write string variable). 7708151497Sru 7709151497Sru -- Request: .ds name [string] 7710151497Sru -- Request: .ds1 name [string] 7711151497Sru -- Escape: \*n 7712151497Sru -- Escape: \*(nm 7713151497Sru -- Escape: \*[name arg1 arg2 ...] 7714151497Sru Define and access a string variable NAME (one-character name N, 7715151497Sru two-character name NM). If NAME already exists, `ds' overwrites 7716151497Sru the previous definition. Only the syntax form using brackets can 7717151497Sru take arguments which are handled identically to macro arguments; 7718151497Sru the single exception is that a closing bracket as an argument must 7719151497Sru be enclosed in double quotes. *Note Request and Macro 7720151497Sru Arguments::, and *Note Parameters::. 7721151497Sru 7722151497Sru Example: 7723151497Sru 7724151497Sru 7725151497Sru .ds foo a \\$1 test 7726151497Sru . 7727151497Sru This is \*[foo nice]. 7728151497Sru => This is a nice test. 7729151497Sru 7730151497Sru The `\*' escape "interpolates" (expands in-place) a 7731151497Sru previously-defined string variable. To be more precise, the stored 7732151497Sru string is pushed onto the input stack which is then parsed by 7733151497Sru `gtroff'. Similar to number registers, it is possible to nest 7734151497Sru strings, i.e. string variables can be called within string 7735151497Sru variables. 7736151497Sru 7737151497Sru If the string named by the `\*' escape does not exist, it is 7738151497Sru defined as empty, and a warning of type `mac' is emitted (see 7739151497Sru *Note Debugging::, for more details). 7740151497Sru 7741151497Sru *Caution:* Unlike other requests, the second argument to the `ds' 7742151497Sru request takes up the entire line including trailing spaces. This 7743151497Sru means that comments on a line with such a request can introduce 7744151497Sru unwanted space into a string. 7745151497Sru 7746151497Sru 7747151497Sru .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark 7748151497Sru 7749151497Sru Instead the comment should be put on another line or have the 7750151497Sru comment escape adjacent with the end of the string. 7751151497Sru 7752151497Sru 7753151497Sru .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark 7754151497Sru 7755151497Sru To produce leading space the string can be started with a double 7756151497Sru quote. No trailing quote is needed; in fact, any trailing quote is 7757151497Sru included in your string. 7758151497Sru 7759151497Sru 7760151497Sru .ds sign " Yours in a white wine sauce, 7761151497Sru 7762151497Sru Strings are not limited to a single line of text. A string can 7763151497Sru span several lines by escaping the newlines with a backslash. The 7764151497Sru resulting string is stored _without_ the newlines. 7765151497Sru 7766151497Sru 7767151497Sru .ds foo lots and lots \ 7768151497Sru of text are on these \ 7769151497Sru next several lines 7770151497Sru 7771151497Sru It is not possible to have real newlines in a string. To put a 7772151497Sru single double quote character into a string, use two consecutive 7773151497Sru double quote characters. 7774151497Sru 7775151497Sru The `ds1' request turns off compatibility mode while interpreting 7776151497Sru a string. To be more precise, a "compatibility save" input token 7777151497Sru is inserted at the beginning of the string, and a "compatibility 7778151497Sru restore" input token at the end. 7779151497Sru 7780151497Sru 7781151497Sru .nr xxx 12345 7782151497Sru .ds aa The value of xxx is \\n[xxx]. 7783151497Sru .ds1 bb The value of xxx ix \\n[xxx]. 7784151497Sru . 7785151497Sru .cp 1 7786151497Sru . 7787151497Sru \*(aa 7788151497Sru => warning: number register `[' not defined 7789151497Sru => The value of xxx is 0xxx]. 7790151497Sru \*(bb 7791151497Sru => The value of xxx ix 12345. 7792151497Sru 7793151497Sru Strings, macros, and diversions (and boxes) share the same name 7794151497Sru space. Internally, even the same mechanism is used to store them. 7795151497Sru This has some interesting consequences. For example, it is 7796151497Sru possible to call a macro with string syntax and vice versa. 7797151497Sru 7798151497Sru 7799151497Sru .de xxx 7800151497Sru a funny test. 7801151497Sru .. 7802151497Sru This is \*[xxx] 7803151497Sru => This is a funny test. 7804151497Sru 7805151497Sru .ds yyy a funny test 7806151497Sru This is 7807151497Sru .yyy 7808151497Sru => This is a funny test. 7809151497Sru 7810151497Sru Diversions and boxes can be also called with string syntax. 7811151497Sru 7812151497Sru Another consequence is that you can copy one-line diversions or 7813151497Sru boxes to a string. 7814151497Sru 7815151497Sru 7816151497Sru .di xxx 7817151497Sru a \fItest\fR 7818151497Sru .br 7819151497Sru .di 7820151497Sru .ds yyy This is \*[xxx]\c 7821151497Sru \*[yyy]. 7822151497Sru => This is a test. 7823151497Sru 7824151497Sru As the previous example shows, it is possible to store formatted 7825151497Sru output in strings. The `\c' escape prevents the insertion of an 7826151497Sru additional blank line in the output. 7827151497Sru 7828151497Sru Copying diversions longer than a single output line produces 7829151497Sru unexpected results. 7830151497Sru 7831151497Sru 7832151497Sru .di xxx 7833151497Sru a funny 7834151497Sru .br 7835151497Sru test 7836151497Sru .br 7837151497Sru .di 7838151497Sru .ds yyy This is \*[xxx]\c 7839151497Sru \*[yyy]. 7840151497Sru => test This is a funny. 7841151497Sru 7842151497Sru Usually, it is not predictable whether a diversion contains one or 7843151497Sru more output lines, so this mechanism should be avoided. With UNIX 7844151497Sru `troff', this was the only solution to strip off a final newline 7845151497Sru from a diversion. Another disadvantage is that the spaces in the 7846151497Sru copied string are already formatted, making them unstretchable. 7847151497Sru This can cause ugly results. 7848151497Sru 7849151497Sru A clean solution to this problem is available in GNU `troff', 7850151497Sru using the requests `chop' to remove the final newline of a 7851151497Sru diversion, and `unformat' to make the horizontal spaces 7852151497Sru stretchable again. 7853151497Sru 7854151497Sru 7855151497Sru .box xxx 7856151497Sru a funny 7857151497Sru .br 7858151497Sru test 7859151497Sru .br 7860151497Sru .box 7861151497Sru .chop xxx 7862151497Sru .unformat xxx 7863151497Sru This is \*[xxx]. 7864151497Sru => This is a funny test. 7865151497Sru 7866151497Sru *Note Gtroff Internals::, for more information. 7867151497Sru 7868151497Sru -- Request: .as name [string] 7869151497Sru -- Request: .as1 name [string] 7870151497Sru The `as' request is similar to `ds' but appends STRING to the 7871151497Sru string stored as NAME instead of redefining it. If NAME doesn't 7872151497Sru exist yet, it is created. 7873151497Sru 7874151497Sru 7875151497Sru .as sign " with shallots, onions and garlic, 7876151497Sru 7877151497Sru The `as1' request is similar to `as', but compatibility mode is 7878151497Sru switched off while the appended string is interpreted. To be more 7879151497Sru precise, a "compatibility save" input token is inserted at the 7880151497Sru beginning of the appended string, and a "compatibility restore" 7881151497Sru input token at the end. 7882151497Sru 7883151497Sru Rudimentary string manipulation routines are given with the next two 7884151497Srurequests. 7885151497Sru 7886151497Sru -- Request: .substring str n1 [n2] 7887151497Sru Replace the string named STR with the substring defined by the 7888151497Sru indices N1 and N2. The first character in the string has index 0. 7889151497Sru If N2 is omitted, it is taken to be equal to the string's length. 7890151497Sru If the index value N1 or N2 is negative, it is counted from the 7891151497Sru end of the string, going backwards: The last character has 7892151497Sru index -1, the character before the last character has index -2, 7893151497Sru etc. 7894151497Sru 7895151497Sru 7896151497Sru .ds xxx abcdefgh 7897151497Sru .substring xxx 1 -4 7898151497Sru \*[xxx] 7899151497Sru => bcde 7900151497Sru 7901151497Sru 7902151497Sru -- Request: .length reg str 7903151497Sru Compute the number of characters of STR and return it in the 7904151497Sru number register REG. If REG doesn't exist, it is created. `str' 7905151497Sru is read in copy mode. 7906151497Sru 7907151497Sru 7908151497Sru .ds xxx abcd\h'3i'efgh 7909151497Sru .length yyy \*[xxx] 7910151497Sru \n[yyy] 7911151497Sru => 14 7912151497Sru 7913151497Sru 7914151497Sru -- Request: .rn xx yy 7915151497Sru Rename the request, macro, diversion, or string XX to YY. 7916151497Sru 7917151497Sru -- Request: .rm xx 7918151497Sru Remove the request, macro, diversion, or string XX. `gtroff' 7919151497Sru treats subsequent invocations as if the object had never been 7920151497Sru defined. 7921151497Sru 7922151497Sru -- Request: .als new old 7923151497Sru Create an alias named NEW for the request, string, macro, or 7924151497Sru diversion object named OLD. The new name and the old name are 7925151497Sru exactly equivalent (it is similar to a hard rather than a soft 7926151497Sru link). If OLD is undefined, `gtroff' generates a warning of type 7927151497Sru `mac' and ignores the request. 7928151497Sru 7929151497Sru -- Request: .chop xx 7930151497Sru Remove (chop) the last character from the macro, string, or 7931151497Sru diversion named XX. This is useful for removing the newline from 7932151497Sru the end of diversions that are to be interpolated as strings. 7933151497Sru This command can be used repeatedly; see *Note Gtroff Internals::, 7934151497Sru for details on nodes inserted additionally by `gtroff'. 7935151497Sru 7936151497Sru *Note Identifiers::, and *Note Comments::. 7937151497Sru 7938151497Sru 7939151497SruFile: groff, Node: Conditionals and Loops, Next: Writing Macros, Prev: Strings, Up: gtroff Reference 7940151497Sru 7941151497Sru5.20 Conditionals and Loops 7942151497Sru=========================== 7943151497Sru 7944151497Sru* Menu: 7945151497Sru 7946151497Sru* Operators in Conditionals:: 7947151497Sru* if-else:: 7948151497Sru* while:: 7949151497Sru 7950151497Sru 7951151497SruFile: groff, Node: Operators in Conditionals, Next: if-else, Prev: Conditionals and Loops, Up: Conditionals and Loops 7952151497Sru 7953151497Sru5.20.1 Operators in Conditionals 7954151497Sru-------------------------------- 7955151497Sru 7956151497SruIn `if' and `while' requests, there are several more operators 7957151497Sruavailable: 7958151497Sru 7959151497Sru`e' 7960151497Sru`o' 7961151497Sru True if the current page is even or odd numbered (respectively). 7962151497Sru 7963151497Sru`n' 7964151497Sru True if the document is being processed in nroff mode (i.e., the 7965151497Sru `.nroff' command has been issued). 7966151497Sru 7967151497Sru`t' 7968151497Sru True if the document is being processed in troff mode (i.e., the 7969151497Sru `.troff' command has been issued). 7970151497Sru 7971151497Sru`v' 7972151497Sru Always false. This condition is for compatibility with other 7973151497Sru `troff' versions only (identifying a `-Tversatec' device). 7974151497Sru 7975151497Sru`'XXX'YYY'' 7976151497Sru True if the string XXX is equal to the string YYY. Other 7977151497Sru characters can be used in place of the single quotes; the same set 7978151497Sru of delimiters as for the `\D' escape is used (*note Escapes::). 7979151497Sru `gtroff' formats the strings before being compared: 7980151497Sru 7981151497Sru 7982151497Sru .ie "|"\fR|\fP" \ 7983151497Sru true 7984151497Sru .el \ 7985151497Sru false 7986151497Sru => true 7987151497Sru 7988151497Sru The resulting motions, glyph sizes, and fonts have to match,(1) 7989151497Sru (*note Operators in Conditionals-Footnote-1::) and not the 7990151497Sru individual motion, size, and font requests. In the previous 7991151497Sru example, `|' and `\fR|\fP' both result in a roman `|' glyph with 7992151497Sru the same point size and at the same location on the page, so the 7993151497Sru strings are equal. If `.ft I' had been added before the `.ie', 7994151497Sru the result would be "false" because (the first) `|' produces an 7995151497Sru italic `|' rather than a roman one. 7996151497Sru 7997151497Sru`r XXX' 7998151497Sru True if there is a number register named XXX. 7999151497Sru 8000151497Sru`d XXX' 8001151497Sru True if there is a string, macro, diversion, or request named XXX. 8002151497Sru 8003151497Sru`m XXX' 8004151497Sru True if there is a color named XXX. 8005151497Sru 8006151497Sru`c G' 8007151497Sru True if there is a glyph G available(2) (*note Operators in 8008151497Sru Conditionals-Footnote-2::); G is either an ASCII character or a 8009151497Sru special character (`\(GG' or `\[GGG]'); the condition is also true 8010151497Sru if G has been defined by the `char' request. 8011151497Sru 8012151497Sru`F FONT' 8013151497Sru True if a font named FONT exists. FONT is handled as if it was 8014151497Sru opened with the `ft' request (this is, font translation and styles 8015151497Sru are applied), without actually mounting it. 8016151497Sru 8017151497Sru This test doesn't load the complete font but only its header to 8018151497Sru verify its validity. 8019151497Sru 8020151497Sru`S STYLE' 8021151497Sru True if style STYLE has been registered. Font translation is 8022151497Sru applied. 8023151497Sru 8024151497Sru Note that these operators can't be combined with other operators like 8025151497Sru`:' or `&'; only a leading `!' (without whitespace between the 8026151497Sruexclamation mark and the operator) can be used to negate the result. 8027151497Sru 8028151497Sru 8029151497Sru .nr xxx 1 8030151497Sru .ie !r xxx \ 8031151497Sru true 8032151497Sru .el \ 8033151497Sru false 8034151497Sru => false 8035151497Sru 8036151497Sru A whitespace after `!' always evaluates to zero (this bizarre 8037151497Srubehaviour is due to compatibility with UNIX `troff'). 8038151497Sru 8039151497Sru 8040151497Sru .nr xxx 1 8041151497Sru .ie ! r xxx \ 8042151497Sru true 8043151497Sru .el \ 8044151497Sru false 8045151497Sru => r xxx true 8046151497Sru 8047151497Sru It is possible to omit the whitespace before the argument to the 8048151497Sru`r', `d', and `c' operators. 8049151497Sru 8050151497Sru *Note Expressions::. 8051151497Sru 8052151497Sru 8053151497SruFile: groff, Node: Operators in Conditionals-Footnotes, Up: Operators in Conditionals 8054151497Sru 8055151497Sru (1) The created output nodes must be identical. *Note Gtroff 8056151497SruInternals::. 8057151497Sru 8058151497Sru (2) The name of this conditional operator is a misnomer since it 8059151497Srutests names of output glyphs. 8060151497Sru 8061151497Sru 8062151497SruFile: groff, Node: if-else, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops 8063151497Sru 8064151497Sru5.20.2 if-else 8065151497Sru-------------- 8066151497Sru 8067151497Sru`gtroff' has if-then-else constructs like other languages, although the 8068151497Sruformatting can be painful. 8069151497Sru 8070151497Sru -- Request: .if expr anything 8071151497Sru Evaluate the expression EXPR, and executes ANYTHING (the remainder 8072151497Sru of the line) if EXPR evaluates to a value greater than zero 8073151497Sru (true). ANYTHING is interpreted as though it was on a line by 8074151497Sru itself (except that leading spaces are swallowed). *Note 8075151497Sru Expressions::, for more info. 8076151497Sru 8077151497Sru 8078151497Sru .nr xxx 1 8079151497Sru .nr yyy 2 8080151497Sru .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true 8081151497Sru => true 8082151497Sru 8083151497Sru 8084151497Sru -- Request: .nop anything 8085151497Sru Executes ANYTHING. This is similar to `.if 1'. 8086151497Sru 8087151497Sru -- Request: .ie expr anything 8088151497Sru -- Request: .el anything 8089151497Sru Use the `ie' and `el' requests to write an if-then-else. The 8090151497Sru first request is the `if' part and the latter is the `else' part. 8091151497Sru 8092151497Sru 8093151497Sru .ie n .ls 2 \" double-spacing in nroff 8094151497Sru .el .ls 1 \" single-spacing in troff 8095151497Sru 8096151497Sru 8097151497Sru -- Escape: \{ 8098151497Sru -- Escape: \} 8099151497Sru In many cases, an if (or if-else) construct needs to execute more 8100151497Sru than one request. This can be done using the `\{' and `\}' 8101151497Sru escapes. The following example shows the possible ways to use 8102151497Sru these escapes (note the position of the opening and closing 8103151497Sru braces). 8104151497Sru 8105151497Sru 8106151497Sru .ie t \{\ 8107151497Sru . ds lq `` 8108151497Sru . ds rq '' 8109151497Sru .\} 8110151497Sru .el \ 8111151497Sru .\{\ 8112151497Sru . ds lq " 8113151497Sru . ds rq "\} 8114151497Sru 8115151497Sru 8116151497Sru *Note Expressions::. 8117151497Sru 8118151497Sru 8119151497SruFile: groff, Node: while, Prev: if-else, Up: Conditionals and Loops 8120151497Sru 8121151497Sru5.20.3 while 8122151497Sru------------ 8123151497Sru 8124151497Sru`gtroff' provides a looping construct using the `while' request, which 8125151497Sruis used much like the `if' (and related) requests. 8126151497Sru 8127151497Sru -- Request: .while expr anything 8128151497Sru Evaluate the expression EXPR, and repeatedly execute ANYTHING (the 8129151497Sru remainder of the line) until EXPR evaluates to 0. 8130151497Sru 8131151497Sru 8132151497Sru .nr a 0 1 8133151497Sru .while (\na < 9) \{\ 8134151497Sru \n+a, 8135151497Sru .\} 8136151497Sru \n+a 8137151497Sru => 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 8138151497Sru 8139151497Sru Some remarks. 8140151497Sru 8141151497Sru * The body of a `while' request is treated like the body of a 8142151497Sru `de' request: `gtroff' temporarily stores it in a macro which 8143151497Sru is deleted after the loop has been exited. It can 8144151497Sru considerably slow down a macro if the body of the `while' 8145151497Sru request (within the macro) is large. Each time the macro is 8146151497Sru executed, the `while' body is parsed and stored again as a 8147151497Sru temporary macro. 8148151497Sru 8149151497Sru 8150151497Sru .de xxx 8151151497Sru . nr num 10 8152151497Sru . while (\\n[num] > 0) \{\ 8153151497Sru . \" many lines of code 8154151497Sru . nr num -1 8155151497Sru . \} 8156151497Sru .. 8157151497Sru 8158151497Sru The traditional and ofter better solution (UNIX `troff' 8159151497Sru doesn't have the `while' request) is to use a recursive macro 8160151497Sru instead which is parsed only once during its definition. 8161151497Sru 8162151497Sru 8163151497Sru .de yyy 8164151497Sru . if (\\n[num] > 0) \{\ 8165151497Sru . \" many lines of code 8166151497Sru . nr num -1 8167151497Sru . yyy 8168151497Sru . \} 8169151497Sru .. 8170151497Sru . 8171151497Sru .de xxx 8172151497Sru . nr num 10 8173151497Sru . yyy 8174151497Sru .. 8175151497Sru 8176151497Sru Note that the number of available recursion levels is set 8177151497Sru to 1000 (this is a compile-time constant value of `gtroff'). 8178151497Sru 8179151497Sru * The closing brace of a `while' body must end a line. 8180151497Sru 8181151497Sru 8182151497Sru .if 1 \{\ 8183151497Sru . nr a 0 1 8184151497Sru . while (\n[a] < 10) \{\ 8185151497Sru . nop \n+[a] 8186151497Sru .\}\} 8187151497Sru => unbalanced \{ \} 8188151497Sru 8189151497Sru 8190151497Sru -- Request: .break 8191151497Sru Break out of a `while' loop. Be sure not to confuse this with the 8192151497Sru `br' request (causing a line break). 8193151497Sru 8194151497Sru -- Request: .continue 8195151497Sru Finish the current iteration of a `while' loop, immediately 8196151497Sru restarting the next iteration. 8197151497Sru 8198151497Sru *Note Expressions::. 8199151497Sru 8200151497Sru 8201151497SruFile: groff, Node: Writing Macros, Next: Page Motions, Prev: Conditionals and Loops, Up: gtroff Reference 8202151497Sru 8203151497Sru5.21 Writing Macros 8204151497Sru=================== 8205151497Sru 8206151497SruA "macro" is a collection of text and embedded commands which can be 8207151497Sruinvoked multiple times. Use macros to define common operations. 8208151497Sru 8209151497Sru -- Request: .de name [end] 8210151497Sru -- Request: .de1 name [end] 8211151497Sru -- Request: .dei name [end] 8212151497Sru -- Request: .dei1 name [end] 8213151497Sru Define a new macro named NAME. `gtroff' copies subsequent lines 8214151497Sru (starting with the next one) into an internal buffer until it 8215151497Sru encounters the line `..' (two dots). The optional second argument 8216151497Sru to `de' changes this to a macro to `.END'. 8217151497Sru 8218151497Sru There can be whitespace after the first dot in the line containing 8219151497Sru the ending token (either `.' or macro `END'). 8220151497Sru 8221151497Sru Here a small example macro called `P' which causes a break and 8222151497Sru inserts some vertical space. It could be used to separate 8223151497Sru paragraphs. 8224151497Sru 8225151497Sru 8226151497Sru .de P 8227151497Sru . br 8228151497Sru . sp .8v 8229151497Sru .. 8230151497Sru 8231151497Sru The following example defines a macro within another. Remember 8232151497Sru that expansion must be protected twice; once for reading the macro 8233151497Sru and once for executing. 8234151497Sru 8235151497Sru 8236151497Sru \# a dummy macro to avoid a warning 8237151497Sru .de end 8238151497Sru .. 8239151497Sru . 8240151497Sru .de foo 8241151497Sru . de bar end 8242151497Sru . nop \f[B]Hallo \\\\$1!\f[] 8243151497Sru . end 8244151497Sru .. 8245151497Sru . 8246151497Sru .foo 8247151497Sru .bar Joe 8248151497Sru => Hallo Joe! 8249151497Sru 8250151497Sru Since `\f' has no expansion, it isn't necessary to protect its 8251151497Sru backslash. Had we defined another macro within `bar' which takes 8252151497Sru a parameter, eight backslashes would be necessary before `$1'. 8253151497Sru 8254151497Sru The `de1' request turns off compatibility mode while executing the 8255151497Sru macro. On entry, the current compatibility mode is saved and 8256151497Sru restored at exit. 8257151497Sru 8258151497Sru 8259151497Sru .nr xxx 12345 8260151497Sru . 8261151497Sru .de aa 8262151497Sru The value of xxx is \\n[xxx]. 8263151497Sru .. 8264151497Sru .de1 bb 8265151497Sru The value of xxx ix \\n[xxx]. 8266151497Sru .. 8267151497Sru . 8268151497Sru .cp 1 8269151497Sru . 8270151497Sru .aa 8271151497Sru => warning: number register `[' not defined 8272151497Sru => The value of xxx is 0xxx]. 8273151497Sru .bb 8274151497Sru => The value of xxx ix 12345. 8275151497Sru 8276151497Sru The `dei' request defines a macro indirectly. That is, it expands 8277151497Sru strings whose names are NAME or END before performing the append. 8278151497Sru 8279151497Sru This: 8280151497Sru 8281151497Sru 8282151497Sru .ds xx aa 8283151497Sru .ds yy bb 8284151497Sru .dei xx yy 8285151497Sru 8286151497Sru is equivalent to: 8287151497Sru 8288151497Sru 8289151497Sru .de aa bb 8290151497Sru 8291151497Sru The `dei1' request is similar to `dei' but with compatibility mode 8292151497Sru switched off during execution of the defined macro. 8293151497Sru 8294151497Sru If compatibility mode is on, `de' (and `dei') behave similar to 8295151497Sru `de1' (and `dei1'): A `compatibility save' token is inserted at 8296151497Sru the beginning, and a `compatibility restore' token at the end, with 8297151497Sru compatibility mode switched on during execution. *Note Gtroff 8298151497Sru Internals::, for more information on switching compatibility mode 8299151497Sru on and off in a single document. 8300151497Sru 8301151497Sru Using `trace.tmac', you can trace calls to `de' and `de1'. 8302151497Sru 8303151497Sru Note that macro identifiers are shared with identifiers for 8304151497Sru strings and diversions. 8305151497Sru 8306151497Sru -- Request: .am name [end] 8307151497Sru -- Request: .am1 name [end] 8308151497Sru -- Request: .ami name [end] 8309151497Sru -- Request: .ami1 name [end] 8310151497Sru Works similarly to `de' except it appends onto the macro named 8311151497Sru NAME. So, to make the previously defined `P' macro actually do 8312151497Sru indented instead of block paragraphs, add the necessary code to the 8313151497Sru existing macro like this: 8314151497Sru 8315151497Sru 8316151497Sru .am P 8317151497Sru .ti +5n 8318151497Sru .. 8319151497Sru 8320151497Sru The `am1' request turns off compatibility mode while executing the 8321151497Sru appended macro piece. To be more precise, a "compatibility save" 8322151497Sru input token is inserted at the beginning of the appended code, and 8323151497Sru a "compatibility restore" input token at the end. 8324151497Sru 8325151497Sru The `ami' request appends indirectly, meaning that `gtroff' 8326151497Sru expands strings whose names are NAME or END before performing the 8327151497Sru append. 8328151497Sru 8329151497Sru The `ami1' request is similar to `ami' but compatibility mode is 8330151497Sru switched off during execution of the defined macro. 8331151497Sru 8332151497Sru Using `trace.tmac', you can trace calls to `am' and `am1'. 8333151497Sru 8334151497Sru *Note Strings::, for the `als' request to rename a macro. 8335151497Sru 8336151497Sru The `de', `am', `di', `da', `ds', and `as' requests (together with 8337151497Sruits variants) only create a new object if the name of the macro, 8338151497Srudiversion or string diversion is currently undefined or if it is 8339151497Srudefined to be a request; normally they modify the value of an existing 8340151497Sruobject. 8341151497Sru 8342151497Sru -- Request: .return [anything] 8343151497Sru Exit a macro, immediately returning to the caller. 8344151497Sru 8345151497Sru If called with an argument, exit twice, namely the current macro 8346151497Sru and the macro one level higher. This is used to define a wrapper 8347151497Sru macro for `return' in `trace.tmac'. 8348151497Sru 8349151497Sru* Menu: 8350151497Sru 8351151497Sru* Copy-in Mode:: 8352151497Sru* Parameters:: 8353151497Sru 8354151497Sru 8355151497SruFile: groff, Node: Copy-in Mode, Next: Parameters, Prev: Writing Macros, Up: Writing Macros 8356151497Sru 8357151497Sru5.21.1 Copy-in Mode 8358151497Sru------------------- 8359151497Sru 8360151497SruWhen `gtroff' reads in the text for a macro, string, or diversion, it 8361151497Srucopies the text (including request lines, but excluding escapes) into 8362151497Sruan internal buffer. Escapes are converted into an internal form, 8363151497Sruexcept for `\n', `\$', `\*', `\\' and `\<RET>' which are evaluated and 8364151497Sruinserted into the text where the escape was located. This is known as 8365151497Sru"copy-in" mode or "copy" mode. 8366151497Sru 8367151497Sru What this means is that you can specify when these escapes are to be 8368151497Sruevaluated (either at copy-in time or at the time of use) by insulating 8369151497Sruthe escapes with an extra backslash. Compare this to the `\def' and 8370151497Sru`\edef' commands in TeX. 8371151497Sru 8372151497Sru The following example prints the numbers 20 and 10: 8373151497Sru 8374151497Sru 8375151497Sru .nr x 20 8376151497Sru .de y 8377151497Sru .nr x 10 8378151497Sru \&\nx 8379151497Sru \&\\nx 8380151497Sru .. 8381151497Sru .y 8382151497Sru 8383151497Sru 8384151497SruFile: groff, Node: Parameters, Prev: Copy-in Mode, Up: Writing Macros 8385151497Sru 8386151497Sru5.21.2 Parameters 8387151497Sru----------------- 8388151497Sru 8389151497SruThe arguments to a macro or string can be examined using a variety of 8390151497Sruescapes. 8391151497Sru 8392151497Sru -- Register: \n[.$] 8393151497Sru The number of arguments passed to a macro or string. This is a 8394151497Sru read-only number register. 8395151497Sru 8396151497Sru Note that the `shift' request can change its value. 8397151497Sru 8398151497Sru Any individual argument can be retrieved with one of the following 8399151497Sruescapes: 8400151497Sru 8401151497Sru -- Escape: \$n 8402151497Sru -- Escape: \$(nn 8403151497Sru -- Escape: \$[nnn] 8404151497Sru Retrieve the Nth, NNth or NNNth argument. As usual, the first 8405151497Sru form only accepts a single number (larger than zero), the second a 8406151497Sru two-digit number (larger or equal to 10), and the third any 8407151497Sru positive integer value (larger than zero). Macros and strings can 8408151497Sru have an unlimited number of arguments. Note that due to copy-in 8409151497Sru mode, use two backslashes on these in actual use to prevent 8410151497Sru interpolation until the macro is actually invoked. 8411151497Sru 8412151497Sru -- Request: .shift [n] 8413151497Sru Shift the arguments 1 position, or as many positions as specified 8414151497Sru by its argument. After executing this request, argument I becomes 8415151497Sru argument I-N; arguments 1 to N are no longer available. Shifting 8416151497Sru by negative amounts is currently undefined. 8417151497Sru 8418151497Sru The register `.$' is adjusted accordingly. 8419151497Sru 8420151497Sru -- Escape: \$* 8421151497Sru -- Escape: \$@ 8422151497Sru In some cases it is convenient to use all of the arguments at once 8423151497Sru (for example, to pass the arguments along to another macro). The 8424151497Sru `\$*' escape concatenates all the arguments separated by spaces. A 8425151497Sru similar escape is `\$@', which concatenates all the arguments with 8426151497Sru each surrounded by double quotes, and separated by spaces. If not 8427151497Sru in compatibility mode, the input level of double quotes is 8428151497Sru preserved (see *Note Request and Macro Arguments::). 8429151497Sru 8430151497Sru -- Escape: \$0 8431151497Sru The name used to invoke the current macro. The `als' request can 8432151497Sru make a macro have more than one name. 8433151497Sru 8434151497Sru 8435151497Sru .de generic-macro 8436151497Sru . ... 8437151497Sru . if \\n[error] \{\ 8438151497Sru . tm \\$0: Houston, we have a problem. 8439151497Sru . return 8440151497Sru . \} 8441151497Sru .. 8442151497Sru . 8443151497Sru .als foo generic-macro 8444151497Sru .als bar generic-macro 8445151497Sru 8446151497Sru 8447151497Sru *Note Request and Macro Arguments::. 8448151497Sru 8449151497Sru 8450151497SruFile: groff, Node: Page Motions, Next: Drawing Requests, Prev: Writing Macros, Up: gtroff Reference 8451151497Sru 8452151497Sru5.22 Page Motions 8453151497Sru================= 8454151497Sru 8455151497Sru*Note Manipulating Spacing::, for a discussion of the main request for 8456151497Sruvertical motion, `sp'. 8457151497Sru 8458151497Sru -- Request: .mk [reg] 8459151497Sru -- Request: .rt [dist] 8460151497Sru The request `mk' can be used to mark a location on a page, for 8461151497Sru movement to later. This request takes a register name as an 8462151497Sru argument in which to store the current page location. With no 8463151497Sru argument it stores the location in an internal register. The 8464151497Sru results of this can be used later by the `rt' or the `sp' request 8465151497Sru (or the `\v' escape). 8466151497Sru 8467151497Sru The `rt' request returns _upwards_ to the location marked with the 8468151497Sru last `mk' request. If used with an argument, return to a position 8469151497Sru which distance from the top of the page is DIST (no previous call 8470151497Sru to `mk' is necessary in this case). Default scaling indicator is 8471151497Sru `v'. 8472151497Sru 8473151497Sru Here a primitive solution for a two-column macro. 8474151497Sru 8475151497Sru 8476151497Sru .nr column-length 1.5i 8477151497Sru .nr column-gap 4m 8478151497Sru .nr bottom-margin 1m 8479151497Sru . 8480151497Sru 8481151497Sru 8482151497Sru .de 2c 8483151497Sru . br 8484151497Sru . mk 8485151497Sru . ll \\n[column-length]u 8486151497Sru . wh -\\n[bottom-margin]u 2c-trap 8487151497Sru . nr right-side 0 8488151497Sru .. 8489151497Sru . 8490151497Sru 8491151497Sru 8492151497Sru .de 2c-trap 8493151497Sru . ie \\n[right-side] \{\ 8494151497Sru . nr right-side 0 8495151497Sru . po -(\\n[column-length]u + \\n[column-gap]u) 8496151497Sru . \" remove trap 8497151497Sru . wh -\\n[bottom-margin]u 8498151497Sru . \} 8499151497Sru . el \{\ 8500151497Sru . \" switch to right side 8501151497Sru . nr right-side 1 8502151497Sru . po +(\\n[column-length]u + \\n[column-gap]u) 8503151497Sru . rt 8504151497Sru . \} 8505151497Sru .. 8506151497Sru . 8507151497Sru 8508151497Sru 8509151497Sru .pl 1.5i 8510151497Sru .ll 4i 8511151497Sru This is a small test which shows how the 8512151497Sru rt request works in combination with mk. 8513151497Sru 8514151497Sru .2c 8515151497Sru Starting here, text is typeset in two columns. 8516151497Sru Note that this implementation isn't robust 8517151497Sru and thus not suited for a real two-column 8518151497Sru macro. 8519151497Sru 8520151497Sru Result: 8521151497Sru 8522151497Sru 8523151497Sru This is a small test which shows how the 8524151497Sru rt request works in combination with mk. 8525151497Sru 8526151497Sru Starting here, isn't robust 8527151497Sru text is typeset and thus not 8528151497Sru in two columns. suited for a 8529151497Sru Note that this real two-column 8530151497Sru implementation macro. 8531151497Sru 8532151497Sru 8533151497Sru The following escapes give fine control of movements about the page. 8534151497Sru 8535151497Sru -- Escape: \v'e' 8536151497Sru Move vertically, usually from the current location on the page (if 8537151497Sru no absolute position operator `|' is used). The argument E 8538151497Sru specifies the distance to move; positive is downwards and negative 8539151497Sru upwards. The default scaling indicator for this escape is `v'. 8540151497Sru Beware, however, that `gtroff' continues text processing at the 8541151497Sru point where the motion ends, so you should always balance motions 8542151497Sru to avoid interference with text processing. 8543151497Sru 8544151497Sru `\v' doesn't trigger a trap. This can be quite useful; for 8545151497Sru example, consider a page bottom trap macro which prints a marker 8546151497Sru in the margin to indicate continuation of a footnote or something 8547151497Sru similar. 8548151497Sru 8549151497Sru There are some special-case escapes for vertical motion. 8550151497Sru 8551151497Sru -- Escape: \r 8552151497Sru Move upwards 1v. 8553151497Sru 8554151497Sru -- Escape: \u 8555151497Sru Move upwards .5v. 8556151497Sru 8557151497Sru -- Escape: \d 8558151497Sru Move down .5v. 8559151497Sru 8560151497Sru -- Escape: \h'e' 8561151497Sru Move horizontally, usually from the current location (if no 8562151497Sru absolute position operator `|' is used). The expression E 8563151497Sru indicates how far to move: positive is rightwards and negative 8564151497Sru leftwards. The default scaling indicator for this escape is `m'. 8565151497Sru 8566151497Sru This horizontal space is not discarded at the end of a line. To 8567151497Sru insert discardable space of a certain length use the `ss' request. 8568151497Sru 8569151497Sru There are a number of special-case escapes for horizontal motion. 8570151497Sru 8571151497Sru -- Escape: \<SP> 8572151497Sru An unbreakable and unpaddable (i.e. not expanded during filling) 8573151497Sru space. (Note: This is a backslash followed by a space.) 8574151497Sru 8575151497Sru -- Escape: \~ 8576151497Sru An unbreakable space that stretches like a normal inter-word space 8577151497Sru when a line is adjusted. 8578151497Sru 8579151497Sru -- Escape: \| 8580151497Sru A 1/6th em space. Ignored for TTY output devices (rounded to 8581151497Sru zero). 8582151497Sru 8583151497Sru -- Escape: \^ 8584151497Sru A 1/12th em space. Ignored for TTY output devices (rounded to 8585151497Sru zero). 8586151497Sru 8587151497Sru -- Escape: \0 8588151497Sru A space the size of a digit. 8589151497Sru 8590151497Sru The following string sets the TeX logo: 8591151497Sru 8592151497Sru 8593151497Sru .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 8594151497Sru 8595151497Sru -- Escape: \w'text' 8596151497Sru -- Register: \n[st] 8597151497Sru -- Register: \n[sb] 8598151497Sru -- Register: \n[rst] 8599151497Sru -- Register: \n[rsb] 8600151497Sru -- Register: \n[ct] 8601151497Sru -- Register: \n[ssc] 8602151497Sru -- Register: \n[skw] 8603151497Sru Return the width of the specified TEXT in basic units. This 8604151497Sru allows horizontal movement based on the width of some arbitrary 8605151497Sru text (e.g. given as an argument to a macro). 8606151497Sru 8607151497Sru 8608151497Sru The length of the string `abc' is \w'abc'u. 8609151497Sru => The length of the string `abc' is 72u. 8610151497Sru 8611151497Sru Font changes may occur in TEXT which don't affect current settings. 8612151497Sru 8613151497Sru After use, `\w' sets several registers: 8614151497Sru 8615151497Sru `st' 8616151497Sru `sb' 8617151497Sru The highest and lowest point of the baseline, respectively, 8618151497Sru in TEXT. 8619151497Sru 8620151497Sru `rst' 8621151497Sru `rsb' 8622151497Sru Like the `st' and `sb' registers, but takes account of the 8623151497Sru heights and depths of glyphs. With other words, this gives 8624151497Sru the highest and lowest point of TEXT. Values below the 8625151497Sru baseline are negative. 8626151497Sru 8627151497Sru `ct' 8628151497Sru Defines the kinds of glyphs occurring in TEXT: 8629151497Sru 8630151497Sru 0 8631151497Sru only short glyphs, no descenders or tall glyphs. 8632151497Sru 8633151497Sru 1 8634151497Sru at least one descender. 8635151497Sru 8636151497Sru 2 8637151497Sru at least one tall glyph. 8638151497Sru 8639151497Sru 3 8640151497Sru at least one each of a descender and a tall glyph. 8641151497Sru 8642151497Sru `ssc' 8643151497Sru The amount of horizontal space (possibly negative) that 8644151497Sru should be added to the last glyph before a subscript. 8645151497Sru 8646151497Sru `skw' 8647151497Sru How far to right of the center of the last glyph in the `\w' 8648151497Sru argument, the center of an accent from a roman font should be 8649151497Sru placed over that glyph. 8650151497Sru 8651151497Sru -- Escape: \kp 8652151497Sru -- Escape: \k(ps 8653151497Sru -- Escape: \k[position] 8654151497Sru Store the current horizontal position in the _input_ line in 8655151497Sru number register with name POSITION (one-character name P, 8656151497Sru two-character name PS). Use this, for example, to return to the 8657151497Sru beginning of a string for highlighting or other decoration. 8658151497Sru 8659151497Sru -- Register: \n[hp] 8660151497Sru The current horizontal position at the input line. 8661151497Sru 8662151497Sru -- Register: \n[.k] 8663151497Sru A read-only number register containing the current horizontal 8664151497Sru output position (relative to the current indentation). 8665151497Sru 8666151497Sru -- Escape: \o'abc' 8667151497Sru Overstrike glyphs A, B, C, ...; the glyphs are centered, and the 8668151497Sru resulting spacing is the largest width of the affected glyphs. 8669151497Sru 8670151497Sru -- Escape: \zg 8671151497Sru Print glyph G with zero width, i.e., without spacing. Use this to 8672151497Sru overstrike glyphs left-aligned. 8673151497Sru 8674151497Sru -- Escape: \Z'anything' 8675151497Sru Print ANYTHING, then restore the horizontal and vertical position. 8676151497Sru The argument may not contain tabs or leaders. 8677151497Sru 8678151497Sru The following is an example of a strike-through macro: 8679151497Sru 8680151497Sru 8681151497Sru .de ST 8682151497Sru .nr ww \w'\\$1' 8683151497Sru \Z@\v'-.25m'\l'\\n[ww]u'@\\$1 8684151497Sru .. 8685151497Sru . 8686151497Sru This is 8687151497Sru .ST "a test" 8688151497Sru an actual emergency! 8689151497Sru 8690151497Sru 8691151497Sru 8692151497Sru 8693151497SruLocal Variables: 8694151497Srucoding: iso-8859-1 8695151497SruEnd: 8696