groff The GNU implementation of troff Edition 1.20.1 Spring 2009 by Trent A. Fisher and Werner Lemberg ([email protected]) This manual documents GNU troff version 1.20.1. Copyright c 1994-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 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.3 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 the freedom to copy and modify this GNU manual. Buying copies from the FSF sup- ports it in developing GNU and promoting software freedom." 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 :::::::::::::::::::::::::::::::::::::::::::::::::: 12 2.3 Macro Directories ::::::::::::::::::::::::::::::::::::::::::::: 12 2.4 Font Directories::::::::::::::::::::::::::::::::::::::::::::::: 13 2.5 Paper Size :::::::::::::::::::::::::::::::::::::::::::::::::::: 13 2.6 Invocation Examples :::::::::::::::::::::::::::::::::::::::::: 14 2.6.1 grog ::::::::::::::::::::::::::::::::::::::::::::::::::::: 15 3 Tutorial for Macro Users ::::::::::::::::::::: 17 3.1 Basics :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 17 3.2 Common Features::::::::::::::::::::::::::::::::::::::::::::: 19 3.2.1 Paragraphs::::::::::::::::::::::::::::::::::::::::::::::: 19 3.2.2 Sections and Chapters:::::::::::::::::::::::::::::::::::: 20 3.2.3 Headers and Footers:::::::::::::::::::::::::::::::::::::: 20 3.2.4 Page Layout ::::::::::::::::::::::::::::::::::::::::::::: 20 3.2.5 Displays ::::::::::::::::::::::::::::::::::::::::::::::::: 20 3.2.6 Footnotes and Annotations ::::::::::::::::::::::::::::::: 20 3.2.7 Table of Contents :::::::::::::::::::::::::::::::::::::::: 21 3.2.8 Indices ::::::::::::::::::::::::::::::::::::::::::::::::::: 21 3.2.9 Paper Formats ::::::::::::::::::::::::::::::::::::::::::: 21 3.2.10 Multiple Columns ::::::::::::::::::::::::::::::::::::::: 21 3.2.11 Font and Size Changes :::::::::::::::::::::::::::::::::: 21 3.2.12 Predefined Strings::::::::::::::::::::::::::::::::::::::: 21 3.2.13 Preprocessor Support ::::::::::::::::::::::::::::::::::: 21 3.2.14 Configuration and Customization:::::::::::::::::::::::: 22 4 Macro Packages:::::::::::::::::::::::::::::::: 23 4.1 `man' :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 23 4.1.1 Options :::::::::::::::::::::::::::::::::::::::::::::::::: 23 4.1.2 Usage :::::::::::::::::::::::::::::::::::::::::::::::::::: 24 4.1.3 Macros to set fonts ::::::::::::::::::::::::::::::::::::::: 26 ii The GNU Troff Manual 4.1.4 Miscellaneous macros::::::::::::::::::::::::::::::::::::: 27 4.1.5 Predefined strings :::::::::::::::::::::::::::::::::::::::: 28 4.1.6 Preprocessors in `man' pages :::::::::::::::::::::::::::::: 29 4.1.7 Optional `man' extensions::::::::::::::::::::::::::::::::: 29 Custom headers and footers :::::::::::::::::::::::::::::::::: 29 Ultrix-specific man macros ::::::::::::::::::::::::::::::::::: 29 Simple example :::::::::::::::::::::::::::::::::::::::::::::: 31 4.2 `mdoc'::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 31 4.3 `ms' ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 31 4.3.1 Introduction to `ms' :::::::::::::::::::::::::::::::::::::: 31 4.3.2 General structure of an `ms' document :::::::::::::::::::: 32 4.3.3 Document control registers ::::::::::::::::::::::::::::::: 33 Margin Settings :::::::::::::::::::::::::::::::::::::::::::::: 33 Text Settings :::::::::::::::::::::::::::::::::::::::::::::::: 33 Paragraph Settings::::::::::::::::::::::::::::::::::::::::::: 34 Footnote Settings :::::::::::::::::::::::::::::::::::::::::::: 35 Miscellaneous Number Registers:::::::::::::::::::::::::::::: 36 4.3.4 Cover page macros ::::::::::::::::::::::::::::::::::::::: 36 4.3.5 Body text :::::::::::::::::::::::::::::::::::::::::::::::: 38 4.3.5.1 Paragraphs :::::::::::::::::::::::::::::::::::::::::: 38 4.3.5.2 Headings :::::::::::::::::::::::::::::::::::::::::::: 39 4.3.5.3 Highlighting ::::::::::::::::::::::::::::::::::::::::: 41 4.3.5.4 Lists :::::::::::::::::::::::::::::::::::::::::::::::: 42 4.3.5.5 Indentation values ::::::::::::::::::::::::::::::::::: 45 4.3.5.6 Tab Stops ::::::::::::::::::::::::::::::::::::::::::: 45 4.3.5.7 Displays and keeps :::::::::::::::::::::::::::::::::: 45 4.3.5.8 Tables, figures, equations, and references ::::::::::::: 47 4.3.5.9 An example multi-page table :::::::::::::::::::::::: 48 4.3.5.10 Footnotes :::::::::::::::::::::::::::::::::::::::::: 48 4.3.6 Page layout :::::::::::::::::::::::::::::::::::::::::::::: 49 4.3.6.1 Headers and footers ::::::::::::::::::::::::::::::::: 49 4.3.6.2 Margins ::::::::::::::::::::::::::::::::::::::::::::: 50 4.3.6.3 Multiple columns :::::::::::::::::::::::::::::::::::: 50 4.3.6.4 Creating a table of contents ::::::::::::::::::::::::: 50 4.3.6.5 Strings and Special Characters::::::::::::::::::::::: 52 4.3.7 Differences from AT&T `ms'::::::::::::::::::::::::::::::: 54 4.3.7.1 troff macros not appearing in groff:::::::::::::::: 55 4.3.7.2 groff macros not appearing in AT&T troff ::::::::: 56 4.3.8 Naming Conventions ::::::::::::::::::::::::::::::::::::: 56 4.4 `me' ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 57 4.5 `mm' ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 57 iii 5 gtroff Reference::::::::::::::::::::::::::::::: 59 5.1 Text :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 59 5.1.1 Filling and Adjusting::::::::::::::::::::::::::::::::::::: 59 5.1.2 Hyphenation ::::::::::::::::::::::::::::::::::::::::::::: 59 5.1.3 Sentences :::::::::::::::::::::::::::::::::::::::::::::::: 59 5.1.4 Tab Stops :::::::::::::::::::::::::::::::::::::::::::::::: 60 5.1.5 Implicit Line Breaks:::::::::::::::::::::::::::::::::::::: 60 5.1.6 Input Conventions:::::::::::::::::::::::::::::::::::::::: 61 5.1.7 Input Encodings ::::::::::::::::::::::::::::::::::::::::: 61 5.2 Measurements::::::::::::::::::::::::::::::::::::::::::::::::: 62 5.2.1 Default Units :::::::::::::::::::::::::::::::::::::::::::: 63 5.3 Expressions ::::::::::::::::::::::::::::::::::::::::::::::::::: 63 5.4 Identifiers ::::::::::::::::::::::::::::::::::::::::::::::::::::: 64 5.5 Embedded Commands :::::::::::::::::::::::::::::::::::::::: 66 5.5.1 Requests ::::::::::::::::::::::::::::::::::::::::::::::::: 66 5.5.1.1 Request and Macro Arguments :::::::::::::::::::::: 68 5.5.2 Macros::::::::::::::::::::::::::::::::::::::::::::::::::: 69 5.5.3 Escapes :::::::::::::::::::::::::::::::::::::::::::::::::: 69 5.5.3.1 Comments :::::::::::::::::::::::::::::::::::::::::: 71 5.6 Registers:::::::::::::::::::::::::::::::::::::::::::::::::::::: 72 5.6.1 Setting Registers ::::::::::::::::::::::::::::::::::::::::: 72 5.6.2 Interpolating Registers ::::::::::::::::::::::::::::::::::: 74 5.6.3 Auto-increment :::::::::::::::::::::::::::::::::::::::::: 74 5.6.4 Assigning Formats ::::::::::::::::::::::::::::::::::::::: 75 5.6.5 Built-in Registers :::::::::::::::::::::::::::::::::::::::: 76 5.7 Manipulating Filling and Adjusting ::::::::::::::::::::::::::: 78 5.8 Manipulating Hyphenation :::::::::::::::::::::::::::::::::::: 82 5.9 Manipulating Spacing ::::::::::::::::::::::::::::::::::::::::: 87 5.10 Tabs and Fields :::::::::::::::::::::::::::::::::::::::::::::: 89 5.10.1 Leaders ::::::::::::::::::::::::::::::::::::::::::::::::: 92 5.10.2 Fields ::::::::::::::::::::::::::::::::::::::::::::::::::: 93 5.11 Character Translations ::::::::::::::::::::::::::::::::::::::: 93 5.12 Troff and Nroff Mode :::::::::::::::::::::::::::::::::::::::: 98 5.13 Line Layout:::::::::::::::::::::::::::::::::::::::::::::::::: 98 5.14 Line Control :::::::::::::::::::::::::::::::::::::::::::::::: 101 5.15 Page Layout :::::::::::::::::::::::::::::::::::::::::::::::: 103 5.16 Page Control ::::::::::::::::::::::::::::::::::::::::::::::: 104 5.17 Fonts and Symbols:::::::::::::::::::::::::::::::::::::::::: 106 5.17.1 Changing Fonts :::::::::::::::::::::::::::::::::::::::: 106 5.17.2 Font Families :::::::::::::::::::::::::::::::::::::::::: 108 5.17.3 Font Positions ::::::::::::::::::::::::::::::::::::::::: 110 5.17.4 Using Symbols ::::::::::::::::::::::::::::::::::::::::: 111 5.17.5 Special Fonts :::::::::::::::::::::::::::::::::::::::::: 118 5.17.6 Artificial Fonts::::::::::::::::::::::::::::::::::::::::: 118 5.17.7 Ligatures and Kerning ::::::::::::::::::::::::::::::::: 120 5.18 Sizes:::::::::::::::::::::::::::::::::::::::::::::::::::::::: 123 iv The GNU Troff Manual 5.18.1 Changing Type Sizes ::::::::::::::::::::::::::::::::::: 124 5.18.2 Fractional Type Sizes :::::::::::::::::::::::::::::::::: 126 5.19 Strings ::::::::::::::::::::::::::::::::::::::::::::::::::::: 127 5.20 Conditionals and