By Trent A. Fisher and Werner Lemberg ([email protected]) This Manual Documents GNU Troff Version 1.18
Total Page:16
File Type:pdf, Size:1020Kb
groff The GNU implementation of troff Edition 1.18 Spring 2002 by Trent A. Fisher and Werner Lemberg ([email protected]) This manual documents GNU troff version 1.18. Copyright c 1994-2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this doc- ument under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being `A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled `GNU Free Documentation License." (a) The FSF's Back-Cover Text is: `You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development." i Table of Contents 1 Introduction............................... 1 1.1 What Is groff? ......................................... 1 1.2 History ................................................. 1 1.3 groff Capabilities....................................... 3 1.4 Macro Packages ......................................... 4 1.5 Preprocessors ........................................... 4 1.6 Output Devices ......................................... 4 1.7 Credits ................................................. 5 2 Invoking groff ............................. 7 2.1 Options ................................................ 7 2.2 Environment ........................................... 11 2.3 Macro Directories ...................................... 12 2.4 Font Directories ........................................ 13 2.5 Invocation Examples ................................... 13 2.5.1 grog.......................................... 14 3 Tutorial for Macro Users .................. 15 3.1 Basics ................................................. 15 3.2 Common Features ...................................... 17 3.2.1 Paragraphs.................................... 17 3.2.2 Sections and Chapters ......................... 18 3.2.3 Headers and Footers ........................... 18 3.2.4 Page Layout .................................. 18 3.2.5 Displays ...................................... 18 3.2.6 Footnotes and Annotations ..................... 19 3.2.7 Table of Contents.............................. 19 3.2.8 Indices........................................ 19 3.2.9 Paper Formats ................................ 19 3.2.10 Multiple Columns ............................ 19 3.2.11 Font and Size Changes ........................ 20 3.2.12 Predefined Strings ............................ 20 3.2.13 Preprocessor Support ......................... 20 3.2.14 Configuration and Customization .............. 20 ii The GNU Troff Manual 4 Macro Packages .......................... 21 4.1 `man' .................................................. 21 4.1.1 Options ....................................... 21 4.1.2 Usage......................................... 22 4.1.3 Macros to set fonts ............................ 24 4.1.4 Miscellaneous macros .......................... 25 4.1.5 Predefined strings ............................. 25 4.1.6 Preprocessors in `man' pages .................... 25 4.2 `mdoc' ................................................. 26 4.3 `ms' ................................................... 26 4.3.1 Introduction to `ms' ............................ 26 4.3.2 General structure of an `ms' document........... 26 4.3.3 Document control registers ..................... 27 Margin Settings ............................... 27 Text Settings ................................. 28 Paragraph Settings ............................ 28 Footnote Settings ............................. 29 Miscellaneous Number Registers................ 29 4.3.4 Cover page macros............................. 29 4.3.5 Body text ..................................... 31 4.3.5.1 Paragraphs ........................... 31 4.3.5.2 Headings ............................. 33 4.3.5.3 Highlighting .......................... 33 4.3.5.4 Lists ................................. 34 4.3.5.5 Indents............................... 38 4.3.5.6 Tab Stops ............................ 38 4.3.5.7 Displays and keeps .................... 38 4.3.5.8 Tables, figures, equations, and references ......................................... 40 4.3.5.9 An example multi-page table........... 41 4.3.5.10 Footnotes ........................... 41 4.3.6 Page layout ................................... 41 4.3.6.1 Headers and footers ................... 42 4.3.6.2 Margins .............................. 42 4.3.6.3 Multiple columns ..................... 42 4.3.6.4 Creating a table of contents............ 43 4.3.6.5 Strings and Special Characters ......... 44 4.3.7 Differences from at&t `ms' ..................... 47 4.3.7.1 troff macros not appearing in groff .. 47 4.3.7.2 groff macros not appearing in at&t troff .................................... 48 4.4 `me' ................................................... 48 4.5 `mm' ................................................... 48 iii 5 gtroff Reference.......................... 49 5.1 Text .................................................. 49 5.1.1 Filling and Adjusting .......................... 49 5.1.2 Hyphenation .................................. 49 5.1.3 Sentences ..................................... 49 5.1.4 Tab Stops ..................................... 50 5.1.5 Implicit Line Breaks ........................... 50 5.2 Input Conventions...................................... 51 5.3 Measurements ......................................... 51 5.3.1 Default Units.................................. 52 5.4 Expressions ............................................ 52 5.5 Identifiers ............................................. 54 5.6 Embedded Commands .................................. 56 5.6.1 Requests ...................................... 56 5.6.1.1 Request Arguments ................... 57 5.6.2 Macros ....................................... 58 5.6.3 Escapes ....................................... 58 5.6.3.1 Comments............................ 60 5.7 Registers .............................................. 61 5.7.1 Setting Registers .............................. 61 5.7.2 Interpolating Registers ......................... 63 5.7.3 Auto-increment................................ 64 5.7.4 Assigning Formats ............................. 65 5.7.5 Built-in Registers .............................. 66 5.8 Manipulating Filling and Adjusting ...................... 68 5.9 Manipulating Hyphenation.............................. 71 5.10 Manipulating Spacing ................................. 76 5.11 Tabs and Fields ....................................... 77 5.11.1 Leaders ...................................... 80 5.11.2 Fields ....................................... 81 5.12 Character Translations ................................ 82 5.13 Troff and Nroff Mode .................................. 86 5.14 Line Layout .......................................... 87 5.15 Line Control .......................................... 90 5.16 Page Layout .......................................... 91 5.17 Page Control ......................................... 93 5.18 Fonts................................................. 95 5.18.1 Changing Fonts .............................. 95 5.18.2 Font Families................................. 96 5.18.3 Font Positions ................................ 98 5.18.4 Using Symbols ............................... 99 5.18.5 Special Fonts................................ 103 5.18.6 Artificial Fonts .............................. 103 5.18.7 Ligatures and Kerning ....................... 106 5.19 Sizes ................................................ 109 5.19.1 Changing Type Sizes......................... 109 iv The GNU Troff Manual 5.19.2 Fractional Type Sizes ........................ 111 5.20 Strings .............................................. 113 5.21 Conditionals and Loops............................... 117 5.21.1 Operators in Conditionals .................... 117 5.21.2 if-else ....................................... 118 5.21.3 while ....................................... 119 5.22 Writing Macros ...................................... 121 5.22.1 Copy-in Mode ............................... 123 5.22.2 Parameters.................................. 123 5.23 Page Motions ........................................ 125 5.24 Drawing Requests .................................... 129 5.25 Traps ............................................... 133 5.25.1 Page Location Traps ......................... 133 5.25.2 Diversion Traps ............................. 135 5.25.3 Input Line Traps ............................ 136 5.25.4 Blank Line Traps ............................ 136 5.25.5 End-of-input Traps .......................... 136 5.26 Diversions ........................................... 137 5.27 Environments ........................................ 141 5.28 Suppressing output................................... 143 5.29 Colors............................................... 144 5.30 I/O ................................................. 145 5.31 Postprocessor Access ................................. 149 5.32 Miscellaneous ........................................ 150 5.33 gtroff Internals ..................................... 152 5.34 Debugging........................................... 154 5.34.1 Warnings ................................... 157 5.35 Implementation Differences ........................... 159 6 Preprocessors ........................... 163 6.1 geqn ................................................