From d318611dd6f23fcfedd50e9b9e24620b102ba96a Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:44:05 +0200 Subject: Adding upstream version 1.23.0. Signed-off-by: Daniel Baumann --- doc/automake.mom | 789 + doc/doc.am | 711 + doc/fdl.texi | 505 + doc/gnu.eps | 784 + doc/gnu.xpm | 198 + doc/grnexmpl.g | 3250 +++ doc/grnexmpl.me | 88 + doc/groff.css | 17 + doc/groff.dvi | Bin 0 -> 1369752 bytes doc/groff.html | 24945 +++++++++++++++++++ doc/groff.html.node/Adjustment.html | 57 + doc/groff.html.node/Argument-Units.html | 68 + doc/groff.html.node/Artificial-Fonts.html | 252 + .../Assigning-Register-Formats.html | 188 + doc/groff.html.node/Auto_002dincrement.html | 124 + doc/groff.html.node/Background.html | 96 + doc/groff.html.node/Basics.html | 232 + doc/groff.html.node/Blank-Line-Traps.html | 71 + doc/groff.html.node/Breaking.html | 119 + doc/groff.html.node/Built_002din-Registers.html | 253 + doc/groff.html.node/Calling-Macros.html | 164 + doc/groff.html.node/Changing-the-Type-Size.html | 159 + .../Changing-the-Vertical-Spacing.html | 146 + doc/groff.html.node/Character-Classes.html | 140 + doc/groff.html.node/Character-Translations.html | 200 + doc/groff.html.node/Colors.html | 208 + doc/groff.html.node/Columnation.html | 53 + doc/groff.html.node/Command-Reference.html | 60 + doc/groff.html.node/Comment-Command.html | 65 + doc/groff.html.node/Comments.html | 157 + doc/groff.html.node/Common-Features.html | 89 + doc/groff.html.node/Compatibility-Mode.html | 221 + doc/groff.html.node/Concept-Index.html | 2359 ++ doc/groff.html.node/Conditional-Blocks.html | 174 + doc/groff.html.node/Conditionals-and-Loops.html | 64 + .../Configuration-and-Customization.html | 56 + doc/groff.html.node/Control-Characters.html | 137 + .../Conventions-Used-in-This-Manual.html | 124 + doc/groff.html.node/Copy-Mode.html | 256 + doc/groff.html.node/Copying-This-Manual.html | 534 + doc/groff.html.node/Credits.html | 58 + doc/groff.html.node/DESC-File-Format.html | 258 + doc/groff.html.node/Debugging.html | 317 + doc/groff.html.node/Default-Units.html | 87 + doc/groff.html.node/Deferring-Output.html | 106 + doc/groff.html.node/Delimiters.html | 233 + doc/groff.html.node/Device-Control-Commands.html | 185 + .../Device-and-Font-Description-Files.html | 77 + .../Differences-from-AT_0026T-ms.html | 171 + doc/groff.html.node/Displays-and-Keeps.html | 74 + doc/groff.html.node/Diversion-Traps.html | 79 + doc/groff.html.node/Diversions.html | 394 + doc/groff.html.node/Document-Formats.html | 57 + doc/groff.html.node/Document-Parts.html | 84 + doc/groff.html.node/Drawing-Geometric-Objects.html | 361 + doc/groff.html.node/Dummy-Characters.html | 166 + .../End_002dof_002dinput-Traps.html | 187 + doc/groff.html.node/Environment.html | 151 + doc/groff.html.node/Environments.html | 250 + doc/groff.html.node/Escape-Sequence-Index.html | 162 + doc/groff.html.node/Fields.html | 98 + doc/groff.html.node/File-Formats.html | 62 + doc/groff.html.node/File-Keyword-Index.html | 215 + doc/groff.html.node/Filling.html | 79 + .../Font-Description-File-Format.html | 280 + doc/groff.html.node/Font-Directories.html | 113 + doc/groff.html.node/Font-Families.html | 182 + doc/groff.html.node/Font-Positions.html | 138 + doc/groff.html.node/Font-and-Size-Changes.html | 56 + doc/groff.html.node/Footnotes-and-Endnotes.html | 60 + doc/groff.html.node/Formatter-Instructions.html | 83 + doc/groff.html.node/GNU-troff-Reference.html | 99 + doc/groff.html.node/Graphics-Commands.html | 247 + doc/groff.html.node/Groff-Options.html | 536 + doc/groff.html.node/Gtroff-Internals.html | 187 + doc/groff.html.node/Headers-and-Footers.html | 61 + doc/groff.html.node/Headings-in-ms.html | 214 + doc/groff.html.node/Hyphenation.html | 66 + doc/groff.html.node/I_002fO.html | 457 + doc/groff.html.node/Identifiers.html | 210 + .../Implementation-Differences.html | 64 + doc/groff.html.node/Indented-regions-in-ms.html | 112 + doc/groff.html.node/Indexing.html | 58 + doc/groff.html.node/Input-Conventions.html | 171 + doc/groff.html.node/Input-Encodings.html | 154 + doc/groff.html.node/Input-Line-Traps.html | 185 + doc/groff.html.node/Installation.html | 57 + .../Intermediate-Output-Examples.html | 171 + doc/groff.html.node/Interpolating-Registers.html | 99 + doc/groff.html.node/Introduction.html | 68 + doc/groff.html.node/Invocation-Examples.html | 120 + doc/groff.html.node/Invoking-Requests.html | 143 + doc/groff.html.node/Invoking-groff.html | 82 + doc/groff.html.node/Italic-Corrections.html | 96 + doc/groff.html.node/Language-Concepts.html | 70 + doc/groff.html.node/Leaders.html | 126 + doc/groff.html.node/Leading-Space-Traps.html | 82 + doc/groff.html.node/Ligatures-and-Kerning.html | 157 + doc/groff.html.node/Line-Continuation.html | 166 + doc/groff.html.node/Line-Layout.html | 267 + doc/groff.html.node/Lists-in-ms.html | 216 + doc/groff.html.node/Macro-Directories.html | 125 + doc/groff.html.node/Macro-Index.html | 335 + doc/groff.html.node/Macro-Package-Intro.html | 63 + doc/groff.html.node/Macro-Packages.html | 64 + doc/groff.html.node/Major-Macro-Packages.html | 103 + .../Manipulating-Filling-and-Adjustment.html | 501 + doc/groff.html.node/Manipulating-Hyphenation.html | 580 + doc/groff.html.node/Manipulating-Spacing.html | 220 + ...anipulating-Type-Size-and-Vertical-Spacing.html | 74 + doc/groff.html.node/Measurements.html | 177 + doc/groff.html.node/Miscellaneous.html | 275 + .../Missing-Unix-Version-7-ms-Macros.html | 78 + doc/groff.html.node/Motion-Quanta.html | 93 + doc/groff.html.node/Numeric-Expressions.html | 395 + doc/groff.html.node/Obsolete-Command.html | 74 + doc/groff.html.node/Operator-Index.html | 188 + doc/groff.html.node/Operators-in-Conditionals.html | 222 + doc/groff.html.node/Optional-man-extensions.html | 264 + doc/groff.html.node/Other-Differences.html | 248 + doc/groff.html.node/Output-Device-Intro.html | 63 + .../Output-Language-Compatibility.html | 103 + doc/groff.html.node/Page-Control.html | 218 + doc/groff.html.node/Page-Geometry.html | 140 + doc/groff.html.node/Page-Layout-Adjustment.html | 57 + doc/groff.html.node/Page-Layout.html | 188 + doc/groff.html.node/Page-Location-Traps.html | 326 + doc/groff.html.node/Page-Motions.html | 454 + doc/groff.html.node/Paper-Format.html | 101 + doc/groff.html.node/Paragraphs-in-ms.html | 160 + doc/groff.html.node/Paragraphs.html | 109 + doc/groff.html.node/Parameters.html | 195 + doc/groff.html.node/Postprocessor-Access.html | 144 + doc/groff.html.node/Predefined-Text.html | 53 + doc/groff.html.node/Preprocessor-Intro.html | 78 + doc/groff.html.node/Preprocessor-Support.html | 56 + doc/groff.html.node/Program-and-File-Index.html | 239 + doc/groff.html.node/Punning-Names.html | 190 + doc/groff.html.node/Register-Index.html | 349 + doc/groff.html.node/Registers.html | 65 + doc/groff.html.node/Request-Index.html | 394 + doc/groff.html.node/Requests-and-Macros.html | 221 + doc/groff.html.node/Safer-Mode.html | 61 + doc/groff.html.node/Sections-and-Chapters.html | 56 + doc/groff.html.node/Selecting-Fonts.html | 227 + doc/groff.html.node/Sentences.html | 174 + doc/groff.html.node/Separation.html | 94 + doc/groff.html.node/Setting-Registers.html | 215 + doc/groff.html.node/Simple-Commands.html | 207 + doc/groff.html.node/Special-Fonts.html | 93 + doc/groff.html.node/String-Index.html | 344 + doc/groff.html.node/Strings.html | 429 + doc/groff.html.node/Suppressing-Output.html | 147 + doc/groff.html.node/Tab-Stops-in-ms.html | 67 + doc/groff.html.node/Table-of-Contents.html | 71 + doc/groff.html.node/Tabs-and-Fields.html | 276 + doc/groff.html.node/Tabs-and-Leaders.html | 87 + doc/groff.html.node/Text-settings-in-ms.html | 76 + doc/groff.html.node/Text.html | 81 + doc/groff.html.node/The-Implicit-Page-Trap.html | 74 + doc/groff.html.node/Traps.html | 73 + doc/groff.html.node/Tutorial-for-Macro-Users.html | 68 + doc/groff.html.node/Typeface-and-decoration.html | 212 + .../Typographical-symbols-in-ms.html | 80 + doc/groff.html.node/Using-Escape-Sequences.html | 206 + doc/groff.html.node/Using-Fonts.html | 148 + .../Using-Fractional-Type-Sizes.html | 172 + doc/groff.html.node/Using-Symbols.html | 632 + doc/groff.html.node/Vertical-Position-Traps.html | 94 + doc/groff.html.node/Warnings.html | 246 + doc/groff.html.node/What-Is-groff_003f.html | 68 + doc/groff.html.node/Writing-Macros.html | 267 + doc/groff.html.node/als.html | 33 + doc/groff.html.node/groff-Capabilities.html | 91 + doc/groff.html.node/groff.html_fot.html | 525 + doc/groff.html.node/gtroff-Output.html | 100 + doc/groff.html.node/if_002delse.html | 97 + doc/groff.html.node/if_002dthen.html | 111 + doc/groff.html.node/index.html | 453 + doc/groff.html.node/man.html | 71 + doc/groff.html.node/mdoc.html | 61 + doc/groff.html.node/me.html | 67 + doc/groff.html.node/mm.html | 64 + doc/groff.html.node/mom.html | 85 + doc/groff.html.node/ms-Body-Text.html | 70 + .../ms-Document-Control-Settings.html | 524 + .../ms-Document-Description-Macros.html | 189 + doc/groff.html.node/ms-Document-Structure.html | 106 + doc/groff.html.node/ms-Footnotes.html | 155 + doc/groff.html.node/ms-Headers-and-Footers.html | 122 + doc/groff.html.node/ms-Insertions.html | 181 + doc/groff.html.node/ms-Introduction.html | 60 + doc/groff.html.node/ms-Legacy-Features.html | 285 + doc/groff.html.node/ms-Margins.html | 56 + doc/groff.html.node/ms-Multiple-Columns.html | 88 + doc/groff.html.node/ms-Naming-Conventions.html | 89 + doc/groff.html.node/ms-Page-Layout.html | 64 + doc/groff.html.node/ms-TOC.html | 242 + doc/groff.html.node/ms-basic-information.html | 211 + doc/groff.html.node/ms-keeps-and-displays.html | 207 + .../ms-language-and-localization.html | 135 + doc/groff.html.node/ms.html | 75 + doc/groff.html.node/troff-and-nroff-Modes.html | 114 + doc/groff.html.node/while.html | 161 + doc/groff.info | 423 + doc/groff.info-1 | 7824 ++++++ doc/groff.info-2 | 7529 ++++++ doc/groff.info-3 | Bin 0 -> 238373 bytes doc/groff.pdf | Bin 0 -> 1148308 bytes doc/groff.texi | 18927 ++++++++++++++ doc/groff.txt | 18123 ++++++++++++++ doc/me-revisions | 261 + doc/meintro.me.in | 2266 ++ doc/meintro_fr.me.in | 2374 ++ doc/meref.me.in | 2439 ++ doc/ms.ms | 4486 ++++ doc/pic.ms | 3287 +++ doc/txi-en.tex | 74 + doc/webpage.ms | 2580 ++ 219 files changed, 136189 insertions(+) create mode 100644 doc/automake.mom create mode 100644 doc/doc.am create mode 100644 doc/fdl.texi create mode 100644 doc/gnu.eps create mode 100644 doc/gnu.xpm create mode 100644 doc/grnexmpl.g create mode 100644 doc/grnexmpl.me create mode 100644 doc/groff.css create mode 100644 doc/groff.dvi create mode 100644 doc/groff.html create mode 100644 doc/groff.html.node/Adjustment.html create mode 100644 doc/groff.html.node/Argument-Units.html create mode 100644 doc/groff.html.node/Artificial-Fonts.html create mode 100644 doc/groff.html.node/Assigning-Register-Formats.html create mode 100644 doc/groff.html.node/Auto_002dincrement.html create mode 100644 doc/groff.html.node/Background.html create mode 100644 doc/groff.html.node/Basics.html create mode 100644 doc/groff.html.node/Blank-Line-Traps.html create mode 100644 doc/groff.html.node/Breaking.html create mode 100644 doc/groff.html.node/Built_002din-Registers.html create mode 100644 doc/groff.html.node/Calling-Macros.html create mode 100644 doc/groff.html.node/Changing-the-Type-Size.html create mode 100644 doc/groff.html.node/Changing-the-Vertical-Spacing.html create mode 100644 doc/groff.html.node/Character-Classes.html create mode 100644 doc/groff.html.node/Character-Translations.html create mode 100644 doc/groff.html.node/Colors.html create mode 100644 doc/groff.html.node/Columnation.html create mode 100644 doc/groff.html.node/Command-Reference.html create mode 100644 doc/groff.html.node/Comment-Command.html create mode 100644 doc/groff.html.node/Comments.html create mode 100644 doc/groff.html.node/Common-Features.html create mode 100644 doc/groff.html.node/Compatibility-Mode.html create mode 100644 doc/groff.html.node/Concept-Index.html create mode 100644 doc/groff.html.node/Conditional-Blocks.html create mode 100644 doc/groff.html.node/Conditionals-and-Loops.html create mode 100644 doc/groff.html.node/Configuration-and-Customization.html create mode 100644 doc/groff.html.node/Control-Characters.html create mode 100644 doc/groff.html.node/Conventions-Used-in-This-Manual.html create mode 100644 doc/groff.html.node/Copy-Mode.html create mode 100644 doc/groff.html.node/Copying-This-Manual.html create mode 100644 doc/groff.html.node/Credits.html create mode 100644 doc/groff.html.node/DESC-File-Format.html create mode 100644 doc/groff.html.node/Debugging.html create mode 100644 doc/groff.html.node/Default-Units.html create mode 100644 doc/groff.html.node/Deferring-Output.html create mode 100644 doc/groff.html.node/Delimiters.html create mode 100644 doc/groff.html.node/Device-Control-Commands.html create mode 100644 doc/groff.html.node/Device-and-Font-Description-Files.html create mode 100644 doc/groff.html.node/Differences-from-AT_0026T-ms.html create mode 100644 doc/groff.html.node/Displays-and-Keeps.html create mode 100644 doc/groff.html.node/Diversion-Traps.html create mode 100644 doc/groff.html.node/Diversions.html create mode 100644 doc/groff.html.node/Document-Formats.html create mode 100644 doc/groff.html.node/Document-Parts.html create mode 100644 doc/groff.html.node/Drawing-Geometric-Objects.html create mode 100644 doc/groff.html.node/Dummy-Characters.html create mode 100644 doc/groff.html.node/End_002dof_002dinput-Traps.html create mode 100644 doc/groff.html.node/Environment.html create mode 100644 doc/groff.html.node/Environments.html create mode 100644 doc/groff.html.node/Escape-Sequence-Index.html create mode 100644 doc/groff.html.node/Fields.html create mode 100644 doc/groff.html.node/File-Formats.html create mode 100644 doc/groff.html.node/File-Keyword-Index.html create mode 100644 doc/groff.html.node/Filling.html create mode 100644 doc/groff.html.node/Font-Description-File-Format.html create mode 100644 doc/groff.html.node/Font-Directories.html create mode 100644 doc/groff.html.node/Font-Families.html create mode 100644 doc/groff.html.node/Font-Positions.html create mode 100644 doc/groff.html.node/Font-and-Size-Changes.html create mode 100644 doc/groff.html.node/Footnotes-and-Endnotes.html create mode 100644 doc/groff.html.node/Formatter-Instructions.html create mode 100644 doc/groff.html.node/GNU-troff-Reference.html create mode 100644 doc/groff.html.node/Graphics-Commands.html create mode 100644 doc/groff.html.node/Groff-Options.html create mode 100644 doc/groff.html.node/Gtroff-Internals.html create mode 100644 doc/groff.html.node/Headers-and-Footers.html create mode 100644 doc/groff.html.node/Headings-in-ms.html create mode 100644 doc/groff.html.node/Hyphenation.html create mode 100644 doc/groff.html.node/I_002fO.html create mode 100644 doc/groff.html.node/Identifiers.html create mode 100644 doc/groff.html.node/Implementation-Differences.html create mode 100644 doc/groff.html.node/Indented-regions-in-ms.html create mode 100644 doc/groff.html.node/Indexing.html create mode 100644 doc/groff.html.node/Input-Conventions.html create mode 100644 doc/groff.html.node/Input-Encodings.html create mode 100644 doc/groff.html.node/Input-Line-Traps.html create mode 100644 doc/groff.html.node/Installation.html create mode 100644 doc/groff.html.node/Intermediate-Output-Examples.html create mode 100644 doc/groff.html.node/Interpolating-Registers.html create mode 100644 doc/groff.html.node/Introduction.html create mode 100644 doc/groff.html.node/Invocation-Examples.html create mode 100644 doc/groff.html.node/Invoking-Requests.html create mode 100644 doc/groff.html.node/Invoking-groff.html create mode 100644 doc/groff.html.node/Italic-Corrections.html create mode 100644 doc/groff.html.node/Language-Concepts.html create mode 100644 doc/groff.html.node/Leaders.html create mode 100644 doc/groff.html.node/Leading-Space-Traps.html create mode 100644 doc/groff.html.node/Ligatures-and-Kerning.html create mode 100644 doc/groff.html.node/Line-Continuation.html create mode 100644 doc/groff.html.node/Line-Layout.html create mode 100644 doc/groff.html.node/Lists-in-ms.html create mode 100644 doc/groff.html.node/Macro-Directories.html create mode 100644 doc/groff.html.node/Macro-Index.html create mode 100644 doc/groff.html.node/Macro-Package-Intro.html create mode 100644 doc/groff.html.node/Macro-Packages.html create mode 100644 doc/groff.html.node/Major-Macro-Packages.html create mode 100644 doc/groff.html.node/Manipulating-Filling-and-Adjustment.html create mode 100644 doc/groff.html.node/Manipulating-Hyphenation.html create mode 100644 doc/groff.html.node/Manipulating-Spacing.html create mode 100644 doc/groff.html.node/Manipulating-Type-Size-and-Vertical-Spacing.html create mode 100644 doc/groff.html.node/Measurements.html create mode 100644 doc/groff.html.node/Miscellaneous.html create mode 100644 doc/groff.html.node/Missing-Unix-Version-7-ms-Macros.html create mode 100644 doc/groff.html.node/Motion-Quanta.html create mode 100644 doc/groff.html.node/Numeric-Expressions.html create mode 100644 doc/groff.html.node/Obsolete-Command.html create mode 100644 doc/groff.html.node/Operator-Index.html create mode 100644 doc/groff.html.node/Operators-in-Conditionals.html create mode 100644 doc/groff.html.node/Optional-man-extensions.html create mode 100644 doc/groff.html.node/Other-Differences.html create mode 100644 doc/groff.html.node/Output-Device-Intro.html create mode 100644 doc/groff.html.node/Output-Language-Compatibility.html create mode 100644 doc/groff.html.node/Page-Control.html create mode 100644 doc/groff.html.node/Page-Geometry.html create mode 100644 doc/groff.html.node/Page-Layout-Adjustment.html create mode 100644 doc/groff.html.node/Page-Layout.html create mode 100644 doc/groff.html.node/Page-Location-Traps.html create mode 100644 doc/groff.html.node/Page-Motions.html create mode 100644 doc/groff.html.node/Paper-Format.html create mode 100644 doc/groff.html.node/Paragraphs-in-ms.html create mode 100644 doc/groff.html.node/Paragraphs.html create mode 100644 doc/groff.html.node/Parameters.html create mode 100644 doc/groff.html.node/Postprocessor-Access.html create mode 100644 doc/groff.html.node/Predefined-Text.html create mode 100644 doc/groff.html.node/Preprocessor-Intro.html create mode 100644 doc/groff.html.node/Preprocessor-Support.html create mode 100644 doc/groff.html.node/Program-and-File-Index.html create mode 100644 doc/groff.html.node/Punning-Names.html create mode 100644 doc/groff.html.node/Register-Index.html create mode 100644 doc/groff.html.node/Registers.html create mode 100644 doc/groff.html.node/Request-Index.html create mode 100644 doc/groff.html.node/Requests-and-Macros.html create mode 100644 doc/groff.html.node/Safer-Mode.html create mode 100644 doc/groff.html.node/Sections-and-Chapters.html create mode 100644 doc/groff.html.node/Selecting-Fonts.html create mode 100644 doc/groff.html.node/Sentences.html create mode 100644 doc/groff.html.node/Separation.html create mode 100644 doc/groff.html.node/Setting-Registers.html create mode 100644 doc/groff.html.node/Simple-Commands.html create mode 100644 doc/groff.html.node/Special-Fonts.html create mode 100644 doc/groff.html.node/String-Index.html create mode 100644 doc/groff.html.node/Strings.html create mode 100644 doc/groff.html.node/Suppressing-Output.html create mode 100644 doc/groff.html.node/Tab-Stops-in-ms.html create mode 100644 doc/groff.html.node/Table-of-Contents.html create mode 100644 doc/groff.html.node/Tabs-and-Fields.html create mode 100644 doc/groff.html.node/Tabs-and-Leaders.html create mode 100644 doc/groff.html.node/Text-settings-in-ms.html create mode 100644 doc/groff.html.node/Text.html create mode 100644 doc/groff.html.node/The-Implicit-Page-Trap.html create mode 100644 doc/groff.html.node/Traps.html create mode 100644 doc/groff.html.node/Tutorial-for-Macro-Users.html create mode 100644 doc/groff.html.node/Typeface-and-decoration.html create mode 100644 doc/groff.html.node/Typographical-symbols-in-ms.html create mode 100644 doc/groff.html.node/Using-Escape-Sequences.html create mode 100644 doc/groff.html.node/Using-Fonts.html create mode 100644 doc/groff.html.node/Using-Fractional-Type-Sizes.html create mode 100644 doc/groff.html.node/Using-Symbols.html create mode 100644 doc/groff.html.node/Vertical-Position-Traps.html create mode 100644 doc/groff.html.node/Warnings.html create mode 100644 doc/groff.html.node/What-Is-groff_003f.html create mode 100644 doc/groff.html.node/Writing-Macros.html create mode 100644 doc/groff.html.node/als.html create mode 100644 doc/groff.html.node/groff-Capabilities.html create mode 100644 doc/groff.html.node/groff.html_fot.html create mode 100644 doc/groff.html.node/gtroff-Output.html create mode 100644 doc/groff.html.node/if_002delse.html create mode 100644 doc/groff.html.node/if_002dthen.html create mode 100644 doc/groff.html.node/index.html create mode 100644 doc/groff.html.node/man.html create mode 100644 doc/groff.html.node/mdoc.html create mode 100644 doc/groff.html.node/me.html create mode 100644 doc/groff.html.node/mm.html create mode 100644 doc/groff.html.node/mom.html create mode 100644 doc/groff.html.node/ms-Body-Text.html create mode 100644 doc/groff.html.node/ms-Document-Control-Settings.html create mode 100644 doc/groff.html.node/ms-Document-Description-Macros.html create mode 100644 doc/groff.html.node/ms-Document-Structure.html create mode 100644 doc/groff.html.node/ms-Footnotes.html create mode 100644 doc/groff.html.node/ms-Headers-and-Footers.html create mode 100644 doc/groff.html.node/ms-Insertions.html create mode 100644 doc/groff.html.node/ms-Introduction.html create mode 100644 doc/groff.html.node/ms-Legacy-Features.html create mode 100644 doc/groff.html.node/ms-Margins.html create mode 100644 doc/groff.html.node/ms-Multiple-Columns.html create mode 100644 doc/groff.html.node/ms-Naming-Conventions.html create mode 100644 doc/groff.html.node/ms-Page-Layout.html create mode 100644 doc/groff.html.node/ms-TOC.html create mode 100644 doc/groff.html.node/ms-basic-information.html create mode 100644 doc/groff.html.node/ms-keeps-and-displays.html create mode 100644 doc/groff.html.node/ms-language-and-localization.html create mode 100644 doc/groff.html.node/ms.html create mode 100644 doc/groff.html.node/troff-and-nroff-Modes.html create mode 100644 doc/groff.html.node/while.html create mode 100644 doc/groff.info create mode 100644 doc/groff.info-1 create mode 100644 doc/groff.info-2 create mode 100644 doc/groff.info-3 create mode 100644 doc/groff.pdf create mode 100644 doc/groff.texi create mode 100644 doc/groff.txt create mode 100644 doc/me-revisions create mode 100644 doc/meintro.me.in create mode 100644 doc/meintro_fr.me.in create mode 100644 doc/meref.me.in create mode 100644 doc/ms.ms create mode 100644 doc/pic.ms create mode 100644 doc/txi-en.tex create mode 100644 doc/webpage.ms (limited to 'doc') diff --git a/doc/automake.mom b/doc/automake.mom new file mode 100644 index 0000000..5609e19 --- /dev/null +++ b/doc/automake.mom @@ -0,0 +1,789 @@ +.\" -*- mode: text; coding: utf-8; -*- +.\" +.\" Copyright ©2014 - 2022 Free Software Foundation +.\" 51 Franklin St, Fifth Floor, Boston, MA 02110, USA +.\" +.\" Permission is hereby granted, free of charge, to any person +.\" obtaining a copy of this software and associated documentation +.\" files (the "Software"), to deal in the Software without restriction, +.\" including, without limitation, the rights to use, copy, modify, +.\" merge, publish, distribute, sublicense, and sell copies of +.\" the Software, and to permit persons to whom the Software is +.\" furnished to do so, subject to the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies, or substantial portions, of the Software; +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +.\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND +.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +.\" HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, +.\" WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING +.\" FROM, OUT OF, OR IN CONNECTION WITH, THE SOFTWARE, OR THE USE OF, +.\" OR OTHER DEALINGS IN, THE SOFTWARE. +.\" +.\" Formatted with the mom macros +.\" .RW (reduce) and .EW (expand) control track kerning +.\" .WS controls word spacing +.\" Hanging punctuation and hyphens are inserted manually +.\" +.TITLE "Using Automake in the Groff project" +.AUTHOR "Bertrand Garrigues" +.COPYRIGHT "2014, 2017 Free Software Foundation" +.COVER TITLE AUTHOR DOCTYPE COPYRIGHT +. +.PAPER LETTER +.PRINTSTYLE TYPESET +. +.HEADING_STYLE 1 NUMBER +.HEADING_STYLE 2 NUMBER +.HEADING_STYLE 3 NUMBER +.HEADING_STYLE 4 NUMBER +. +.QUOTE_INDENT 2m +.CODE_FONT CB +. +\# Table of contents +.TOC_PADDING 2 +.SPACE_TOC_ITEMS +.AUTO_RELOCATE_TOC +.TOC_ENTRY_STYLE 2 FONT I +.TOC_LEAD 14 +. +.NO_SHIM \" Flex-spaced +. +.START +. +.PP +This is a quick overview of how to use `automake' in the groff +project, and is intended to help the developers and contributors +find their way when they have to make changes to the sources files +or to the data that are installed. If you need more details on +`automake', here are some reading suggestions: +. +.LEFT +.SP 3p +. +.LIST +.SHIFT_LIST 1m +.ITEM +The Automake Manual: +\*[FWD 1m]\c +.PDF_WWW_LINK https://www.gnu.org/software/automake/manual/automake.html +.SP 3p +.ITEM +A book by John Calcote, with good practical examples: +\*[FWD 1m]\c +.PDF_WWW_LINK http://fsmsh.com/2753 +.SP 3p +.ITEM +This site, by Diego Petteno, with good practical examples too: +\*[FWD 1m]\c +.PDF_WWW_LINK https://autotools.io/index.html +.LIST OFF +. +.JUSTIFY +.HY DEFAULT +. +.HEADING 1 "Overview, the initial build" +. +.HEADING 2 "First build" +. +.PP +Groff integrates the `gnulib' and uses its `bootstrap' script. When +compiling from the git repository, you should first invoke this +script: +.QUOTE +.CODE +$ ./bootstrap +.CODE OFF +.QUOTE OFF +This will: +. +.QUAD LEFT +.HY OFF +. +.LIST +.SHIFT_LIST 1m +.ITEM +.SP 3p +Clone the gnulib repository as a git submodule in `gnulib', +add the needed gnulib sources files in `lib', +add the needed gnulib m4 macros in `gnulib_m4'. +.SP 3p +.ITEM +Invoke autoreconf that will call all the `GNU autotools' (`aclocal', +`autoheader', `autoconf', `automake') in the right order for +creating the following files: +.LIST DASH +.SHIFT_LIST .5m +.SP 3p +.ITEM +INSTALL (a symlink to gnulib's INSTALL file) +.ITEM +Makefile.in +.ITEM +aclocal.m4 +.ITEM +autom4te.cache/ +.ITEM +build-aux/ (that contains all the helper scripts) +.ITEM +configure +.ITEM +src/include/config.hin +.LIST BACK +.LIST OFF +. +.SP 3p +.JUSTIFY +.HY DEFAULT +. +.WS +2 +.EW .5 +The file aclocal.m4 is generated and the groff m4 macros are +included via the acinclude.m4 file. +.WS DEFAULT +.EW 0 +. +.PP +At this point you can invoke the `configure' script and call `make' +to build the groff project. You can do it in the source tree: +.QUOTE +.CODE +$ ./configure +$ make +.CODE OFF +.QUOTE OFF +You can also build groff in an out-of-source build tree, which is +cleaner: +.QUOTE +.CODE +$ mkdir build +$ cd build +$ ../configure +$ make +.CODE OFF +.QUOTE OFF +Parallel build is also supported: `make' can be invoked +with the -j option, which will greatly speed up the build. +. +.HEADING 2 "Automake in the autotools process" +. +.PP +Automake's main job is to generate a Makefile.in file (this file is +maintained manually on projects using only autoconf). The main file +processed by `automake' is the Makefile.am file, which eventually +generates a Makefile. The (simplified) process is: +. +.SP 3p +.QUAD LEFT +.HY OFF +. +.LIST +.SHIFT_LIST 1m +.ITEM +`aclocal' generates the `aclocal.m4' file from `configure.ac' and +the user-defined macros in `acinclude.m4'. +.ITEM +`autoheader' generates config.h.in. +.ITEM +`autoconf' generates the `configure' script from `aclocal.m4' and `configure.ac' +.ITEM +`automake' generates Makefile.in from Makefile.am and the +`configure.ac' file. It also generates some helper scripts, on the +groff project they are located in build-aux. +.ITEM +`configure' generates `config.status' +.ITEM +`config.status' generates the Makefile and config.h. +.LIST OFF +. +.SP 3p +.JUSTIFY +.HY DEFAULT +. +.WS -2 +.RW .16 +Finally, `autoreconf' is the program that can be used to call these +various tools in the correct order. +.RW 0 +.WS DEFAULT +. +.PP +Automake defines a set of special variables that are used to +generate various build rules in the final Makefile. Note however +that if Automake's predefined rules are not enough, you still have +the possibility of adding handwritten standard `make' rules in a +Makefile.am; these rules will be copied verbatim in the Makefile.in +and then in the final Makefile. +. +.HEADING 2 "Modification of autotools files" +. +.PP +Previously, when groff used `autoconf' only and not `automake', +you had to invoke manually the autotools, depending on what you +modified. For example, to change the file `aclocal.m4', you had +to run the shell command `aclocal -I m4'; to recreate the files +`configure' and `Makefile', you had to use the command 'autoreconf +- I m4'. +.PP +Now, as groff uses `automake', you don't need to run `autoreconf'. +If you make some changes in Makefile.am or configure.ac, all the +files that need to be updated will be regenerated when you execute +`make'. +. +.HEADING 1 "Building a program" +. +.HEADING 2 "A program and its source files" +. +.PP +Generally speaking, when using `automake' you will have to write a +Makefile.am file and use the variable \*[CODE]bin_PROGRAMS\*[CODE OFF] +to declare a program that should be built, and then list the +sources of this program in a variable that starts with the name of +your program and ends with \*[CODE]_SOURCES\*[CODE OFF]\&. In the +groff project we have only 1 top-level Makefile.am that includes +several \&.am files. +.PP +Take for example the build of grolbp, in src/devices/grolbp/grolbp.am. +The file starts with: +.QUOTE ADJUST -4p +.CODE +bin_PROGRAMS += grolbp +.CODE OFF +.QUOTE OFF +This says that a program named `grolbp' is added to the list of the +programs that should be built. The variable +\*[CODE]bin_PROGRAMS\*[CODE OFF] is initialized to an empty string in +the top-level Makefile.am, which includes grolbp.am. (We will see later +why we don't write directly +\*[CODE]bin_PROGRAMS\~=\~grolbp\*[CODE OFF] in a Makefile.am in the +grolbp directory.) +.PP +Then, we list the sources of grolbp like this: +.QUOTE ADJUST -4p +.IL 1m +.HI 1m +.CODE +grolbp_SOURCES = \\ +src/devices/grolbp/lbp.cpp \\ +src/devices/grolbp/lbp.h \\ +src/devices/grolbp/charset.h +.CODE OFF +.QUOTE OFF +.ILQ +As you added `grolbp' to \*[CODE]bin_PROGRAMS\*[CODE OFF], +you need to define the sources of grolbp in the variable +\*[CODE]grolbp_SOURCES\*[CODE OFF]\&. If you write in another file +\*[CODE]bin_PROGRAMS += foo\*[CODE OFF] you will list the sources +of `foo' in \*[CODE]foo_SOURCES\*[CODE OFF]\&. +.PP +With these two statements, the resulting generated Makefile +will contain everything that is needed to build, clean, +install and uninstall the `grolbp' binary when invoking the +adequate `make' command. Also, the source files listed in +\*[CODE]grolbp_SOURCES\*[CODE OFF] will automatically be included in +the distribution tarball. That is why the headers are also listed +in \*[CODE]grolbp_SOURCES\*[CODE OFF]: it is not necessary to add +them in order to correctly build `grolbp', but this way the headers +will be distributed. +. +.SP 3p +.QUAD LEFT +.HY OFF +. +.LIST +.SHIFT_LIST 1m +.ITEM +The path to the files are relative to the top-level directory. +.ITEM +The binaries are generated in the top-level build directory. +.ITEM +The \&.o files are generated in the directory where the source files +are located, or, in the case of an out-of-source build tree, in a +directory that is the replication of the source tree directory. +For example if you built groff in a `build' directory, lbp.o +(object file from src/devices/grolbp/lbp.cpp) will be located in +build/src/devices/grolbp/lbp.o. +.LIST OFF +. +.SP 3p +.JUSTIFY +.HY DEFAULT +. +We will also see later the reasons; this is due to the non-recursive +make design. +. +.HEADING 2 "Linking against a library" +. +.PP +To list which libraries grolbp needs to link against, we just write: +.QUOTE +.IL +.HI +.CODE +grolbp_LDADD = $(LIBM) \\ +libdriver.a \\ +libgroff.a \\ +lib/libgnu.a +.CODE OFF +.QUOTE OFF +.ILQ +Again, we use the variable \*[CODE]grolbp_LDADD\*[CODE OFF] because +we added a program named `grolbp'. This will also automatically +set build dependencies between `grolbp' and the libraries it needs: +`libdriver.a' and `libgroff.a', that are convenience libraries built +within the groff project, will be compiled before grolbp. +. +.HEADING 2 "Preprocessor flags" +. +.PP +Preprocessor flags that are common to all the binaries are listed +in the variable \*[CODE]AM_CPPFLAGS\*[CODE OFF] in the top-level +Makefile.am. If a `foo' binary needs specific preprocessor +flags, use \*[CODE]foo_CPPFLAGS\*[CODE OFF], for example, in +src/devices/xditview/xditview.am, extra flags are needed to build +gxditview and are added like this: +.QUOTE +.IL +.HI +.CODE +gxditview_CPPFLAGS = $(AM_CPPFLAGS) $(X_CFLAGS) -Dlint \\ +-I$(top_builddir)/src/devices/xditview +.CODE OFF +.QUOTE OFF +.ILQ +.PP +The use of specific CPPFLAGS changes the name of the generated objects: +the \&.o object files are prefixed with the name of the program. +For example, the \&.o file corresponding to +src/devices/xditview/device.c will be +src/devices/xditview/gxditview-device.o. +. +.HEADING 2 "Cleaning" +. +.PP +You don't need to write rules to clean the programs listed in +\*[CODE]bin_PROGRAMS\*[CODE OFF], `automake' will write them for +you. However, some programs might have generated sources that +should be cleaned. In this case, you have mainly two special +variables to list extra files that should be cleaned: +. +.SP 3p +.QUAD LEFT +.HY OFF +. +.LIST +.SHIFT_LIST 1m +.ITEM +\*[CODE]MOSTLYCLEANFILES\*[CODE OFF] for files that should be +cleaned by `make mostlyclean' +.ITEM +\*[CODE]CLEANFILES\*[CODE OFF ] for files that should be cleaned by +`make clean' +.LIST OFF +. +.JUSTIFY +.HY DEFAULT +.SP 3p +. +There is also the possibility of writing custom rules. We will see +that later. +. +.HEADING 2 "Dependencies" +. +.PP +We have already seen that when linking against a convenience +library, the dependencies are already created by `automake'. +However, some dependencies still need to be manually added, for +example when a source file includes a generated header. In this +case, the easiest way is to add a plain-make dependency. For +example, src/roff/groff/groff.cpp includes defs.h, which is a +generated header. We just add in src/roff/groff/groff.am: +.QUOTE +.CODE +src/roff/groff/groff.$(OBJEXT): defs.h +.CODE OFF +.QUOTE OFF +. +.HEADING 2 "Scripts" +. +.PP +Apart from \*[CODE]bin_PROGRAMS\*[CODE OFF], there is another +similar special variable for scripts: \*[CODE]bin_SCRIPTS\*[CODE OFF]\&. +The scripts listed in this variable will automatically be +built (of course you have to provide your custom rule to build the +script), installed and uninstalled when invoking `make', `make +install' and `make uninstall'. The main difference is that unlike +the programs listed in \*[CODE]bin_PROGRAMS\*[CODE OFF], the scripts +will not be cleaned by default. They are not distributed by default +either. In the groff project, \*[CODE]bin_SCRIPTS\*[CODE OFF] are +cleaned because they are added to \*[CODE]MOSTLYCLEANFILES\*[CODE OFF] +in the top-level Makefile.am. +.PP +A simple example are the gropdf and pdfmom scripts in +src/devices/gropdf/gropdf.am: +.CODE_SIZE 84 +.QUOTE_INDENT 1 +.QUOTE +.CODE +bin_SCRIPTS += gropdf pdfmom + [...] +gropdf: $(gropdf_dir)/gropdf.pl $(SH_DEPS_SED_SCRIPT) + $(AM_V_GEN)$(RM) $@ \\ + sed -f $(SH_DEPS_SED_SCRIPT) \\ + -e "s|[@]VERSION[@]|$(VERSION)|" \\ + -e "s|[@]PERL[@]|$(PERL)|" \\ + -e "s|[@]GROFF_FONT_DIR[@]|$(fontpath)|" \\ + -e "s|[@]RT_SEP[@]|$(RT_SEP)|" $(gropdf_dir)/gropdf.pl \\ + >$@ \ + && chmod +x $@ + +pdfmom: $(gropdf_dir)/pdfmom.pl $(SH_DEPS_SED_SCRIPT) + $(AM_V_GEN)$(RM) $@ \\ + sed -f $(SH_DEPS_SED_SCRIPT) \\ + -e "s|[@]VERSION[@]|$(VERSION)|" \\ + -e "s|[@]RT_SEP[@]|$(RT_SEP)|" \\ + -e "s|[@]PERL[@]|$(PERL)|" $(gropdf_dir)/pdfmom.pl \\ + >$@ + && chmod +x $@ +.QUOTE OFF +.QUOTE_INDENT 2m +.CODE_SIZE 100 +In this example, the `@' symbol is protected by square brackets to +prevent the substitution of the variable by `automake'. +. +.HEADING 1 "Non-recursive make schema" +. +.PP +There are two possibilities for organizing the Makefile.am of a +large project, using a recursive or a non-recursive `make'. +. +.HEADING 2 "1st possibility: make recursion" +. +.PP +A top level Makefile.am includes another Makefile.am, using the +\*[CODE]SUBDIRS\*[CODE OFF] directive, and the Makefile.am of each +sub-directory lists the programs that should be built. If we had +chosen this type of organization, we would have a Makefile.am in +src/devices/grolbp and in each directory that contain sources to +build a program (tbl, eqn, troff, and so on). We would write in the +top-level Makefile.am: +.QUOTE +.IL +.HI +.CODE +SUBDIRS = src/devices/grolbp \\ +\&... (and all the dir that build a program or a script) +.CODE OFF +.QUOTE OFF +and in src/devices/grolbp, we would have a file Makefile.am that +contains: +.QUOTE +.CODE +bin_PROGRAMS = grolbp +grolbp_SOURCES = lbp.cpp lbp.h charset.h +.CODE OFF +.QUOTE OFF +.PP +Only `grolbp' is affected to the variable \*[CODE]bin_PROGRAMS\*[CODE OFF]\&. +It would be the same in, say, src/roff/troff: you would have a Makefile.am +with \*[CODE]bin_PROGRAMS = troff\*[CODE OFF]\&. We would have +one generated Makefile per Makefile.am file: in the build tree +you will have the top-level Makefile, grolbp's Makefile in +src/devices/grolbp, troff's Makefile in src/roff/troff, and so on. +When calling `make' to build everything, `make' will be recursively +called in all the directories that have a Makefile. Thus, the +paths are logically relative to the directory that contains the +Makefile.am. +.PP +This approach has the disadvantage of making dependencies harder +to resolve: each Makefile does not know the targets of the other +Makfiles. It also makes the build slower. +. +.HEADING 2 "Non-recursive make used by the Groff project" +. +.PP +The second possibility, which was chosen for the groff project, is to use +a non-recursive make schema. It is described in paragraph 7.3 of +the Automake manual ("An Alternative Approach to Subdirectories"), +based on the following paper from Peter Miller: +.PDF_WWW_LINK http://miller.emu.id.au/pmiller/books/rmch/ \ + SUFFIX . "\*[IT]Recursive Make Considered Harmful\*[PREV]" +.PP +The idea is to have a single Makefile that contains all the rules. +That is why we have only a single Makefile.am in the top-level +directory which includes all the \&.am files that define rules +to build the various programs. The inclusion is done with the +\*[CODE]include\*[CODE OFF] directive, not \*[CODE]SUBDIRS\*[CODE OFF]\&. +Using `include' is like copying the contents of the included +file into the top-level Makefile.am, and will not generate other +Makefile. +.PP +We first say in this top-level Makefile.am: +.QUOTE +.CODE +bin_PROGAMS = +.CODE OFF +.QUOTE OFF +and then all the \&.am files that define a program to be built (e.g. +src/devices/grolbp/grolbp.am, src/roff/troff/troff.am, and so on) +overload this variable, so that at the end, all the programs that +should be built are listed in this \*[CODE]bin_PROGRAMS\*[CODE OFF] +variable. This is the reason why all the paths in the various \&.am +files are relative to the top-level directory: at the end we will +have only one Makefile in the top-level directory of the build tree. +.PP +As the resulting single Makefile knows all the targets, the +dependencies are easier to manage. The build is also faster, +particularly when compiling a single file: `make' is called once only +and the file will be instantly rebuilt, while on a recursive make +system, `make' will have to be invoked in all the sub-directories. +.PP +Note also that in order to make `gnulib' work with this +non-recursive schema, the `--automake-subdir' +configuration should be selected in bootstrap.conf. +. +.HEADING 1 "Installing data" +. +.PP +Variables that end with \*[CODE]_DATA\*[CODE OFF] are special +variables used to list files that should be installed in a +particular location. The prefix of the variables should refer to +another previously defined variable that ends with a `dir' suffix. +This variable that ends with `dir' defines where the files should be +installed. +. +.HEADING 2 "A simple case" +. +.PP +For example, in font/devX100/devX100.am, we can see this: +.QUOTE +.CODE +if !WITHOUT_X11 +devX100fontdir = $(fontdir)/devX100 +devX100font_DATA = $(DEVX100FONTS) +endif +.SP +EXTRA_DIST += $(DEVX100FONTS) +.CODE OFF +.QUOTE OFF +.WS -4 +\*[CODE]DEVX100FONTS\*[CODE OFF] is just a list of font files, +defined at the beginning of devX100.am. \*[CODE]fontdir\*[CODE OFF] +is where all the font directories are installed, it is defined +in the top-level Makefile.am. The conditional +\*[CODE]if\~!WITHOUT_X11\*[CODE OFF] +is used to prevent the installation of +these files if X11 is not available. +.WS DEFAULT +.PP +We first define where we wants to install the devX100 fonts with: +.QUOTE +.CODE +devX100fontdir = $(fontdir)/devX100 +.CODE OFF +.QUOTE OFF +Because we declared a variable ending with `dir', we are allowed +to define \*[CODE]devX100font_DATA\*[CODE OFF] (you remove the +`dir' suffix and add \*[CODE]_DATA\*[CODE OFF]). Wildcards are not +supported in the special variables that end with +\*[CODE]_DATA\*[CODE OFF]\&. +.PP +With these two lines, `make install' will install the files +listed in \*[CODE]DEVX100FONTS\*[CODE OFF] and `make uninstall' +will uninstall them. \*[CODE]devX100fontdir\*[CODE OFF] will be +automatically created if missing during the installation +process, but not removed during the uninstall. The complete +\*[CODE]fontdir\*[CODE OFF] is removed by a custom uninstall rule +(uninstall_groffdirs in Makefile.am). +.PP +Because the files listed in \*[CODE]devX100font_DATA\*[CODE OFF] +are not distributed by default, we explicitly added them to the +\*[CODE]EXTRA_DIST\*[CODE OFF] variable, which lists all the files +that should be distributed and that are not taken into account by +the default automake rules. +.QUOTE +.CODE + EXTRA_DIST += $(DEVX100FONTS) +.CODE OFF +.QUOTE OFF +Another possibility would have been to add a `dist' prefix to the +\*[CODE]devX100font_DATA\*[CODE OFF] variable, in this case the use +of \*[CODE]EXTRA_DIST\*[CODE OFF] is useless (except of course if +\*[CODE]WITHOUT_X11\*[CODE OFF] is true, in this case we don't +install the files but we still have to distribute them): +.QUOTE +.CODE +if !WITHOUT_X11 +devX100fontdir = $(fontdir)/devX100 +dist_devX100font_DATA = $(DEVX100FONTS) +else +EXTRA_DIST += $(DEVX100FONTS) +endif +.CODE OFF +.QUOTE OFF +. +.HEADING 2 "Dealing with generated files" +. +.PP +In the previous example, all the font files that must be installed +were already present in the source tree. But in some cases, +you need to generate the files you intend to install. In this +case, the files should be installed but not distributed. A +simple way to deal with this is to add a `nodist' prefix to your +\*[CODE]xxx_DATA\*[CODE OFF] variable. +.PP +For example in font/devps/devps.am, we have a list of +font files already present in the source tree, defined +by \*[CODE]DEVPSFONTFILES\*[CODE OFF], and another list +of font files that are generated, listed in the variable +\*[CODE]DEVPSFONTFILES_GENERATED\*[CODE OFF]\&. They should all +by installed in a `devps' directory under the fontdir. Thus +the following three lines, where we use the `dist' and `nodist' +prefixes: +.QUOTE +.CODE +devpsfontdir = $(fontdir)/devps +dist_devpsfont_DATA = $(DEVPSFONTFILES) +nodist_devpsfont_DATA = $(DEVPSFONTFILES_GENERATED) +.CODE OFF +.QUOTE OFF +The generated files are not cleaned by default, thus we add: +.QUOTE +.CODE +MOSTLYCLEANFILES += $(DEVPSFONTFILES_GENERATED) +.CODE OFF +.QUOTE OFF +. +.HEADING 1 "Extending Automake's rules" +. +.HEADING 2 "Local clean rules" +. +.PP +In most of the cases, the files that need to be cleaned are +automatically determined by `automake', or were added to the +\*[CODE]MOSTCLEANFILES\*[CODE OFF] or \*[CODE]CLEANFILES\*[CODE OFF] +variables. However, you might need to define a specific rule +to clean some files that were not added to any list. Automake +defines a set of targets to extend the clean targets with your +own rules: clean-local, mostlyclean-local, distclean-local or +maintainerclean-local. An example of such extension exists in +font/devpdf/devpdf.am: because some fonts are not explicitly listed +in a \*[CODE]xxx_DATA\*[CODE OFF] variable but generated by a custom +rule, we define an extra rule to extend the `mostlyclean' target: +.CODE_SIZE 92 +.QUOTE +.CODE +mostlyclean-local: mostlyclean_devpdf_extra +mostlyclean_devpdf_extra: + @echo Cleaning font/devpdf + rm -rf $(top_builddir)/font/devpdf/enc \\ + $(top_builddir)/font/devpdf/map; + if test -d $(top_builddir)/font/devpdf; then \\ + for f in $(GROFF_FONT_FILES); do \\ + rm -f $(top_builddir)/font/devpdf/$$f; \\ + done; \\ + fi +.CODE OFF +.QUOTE OFF +. +.NO_FLEX OFF \" Prevent upcoming NEWPAGE from disabling flex-spacing. +.HEADING 2 "Local install/uninstall rules and hooks" +. +.PP +Similarly to the clean rules, there are extensions to install and +uninstall rules. They come with two flavous, local rules and hooks. +. +.SP 3p +.QUAD LEFT +.HY OFF +. +.LIST +.SHIFT_LIST 1m +.ITEM +There are 2 rules to extend install commands: `install-exec-local' +for binaries and `install-data-local' for data. +.ITEM +There is 1 uninstall local rule: `uninstall-local'. +.LIST OFF +. +.SP 3p +.JUSTIFY +.HY DEFAULT +. +There are no guarantees on the order of execution of these local +rules. An example of local rule is the installation of GXditview.ad +and GXditview-color.ad files in src/devices/xditview/xditview.am: if +theses files are already installed, the old files are first saved. +Also, the final file that is installed is stripped from its \&.ad +suffix. Thus the usage of a custom rule rather than the definition +of a \*[CODE]xxx_DATA\*[CODE OFF] variable: +.FLEX +.QUOTE +.CODE +# Custom installation of GXditview.ad and GXditview-color.ad +install-data-local: install_xditview +uninstall-local: uninstall_xditview +.SP +[...] +install_xditview: $(xditview_srcdir)/GXditview.ad + -test -d $(DESTDIR)$(appdefdir) \\ + || $(mkinstalldirs) $(DESTDIR)$(appdefdir) + if test -f $(DESTDIR)$(appdefdir)/GXditview; then \\ + mv $(DESTDIR)$(appdefdir)/GXditview \\ + $(DESTDIR)$(appdefdir)/GXditview.old; \\ + fi + [...] + $(INSTALL_DATA) $(xditview_srcdir)/GXditview.ad \\ + $(DESTDIR)$(appdefdir)/GXditview +.CODE OFF +.QUOTE OFF +.PP +Hooks, on the other hand, are guaranteed to be executed after all the +standard targets have been executed. +.BR +.SP 3p +.QUAD LEFT +.HY OFF +. +.LIST +.SHIFT_LIST 1m +.SP 3p +.ITEM +There are 2 install hooks: `install-exec-hook' and +`install-data-hook'. +.ITEM +There is 1 uninstall hook: `unintall-hook' +.LIST OFF +. +.SP 3p +.JUSTIFY +.HY DEFAULT +. +.PP +An example of hook is the `uninstall_groffdirs' rule in the +top-level Makefile.am. This hook is used to remove all the +directories specific to groff introduced by the installation +process. Obviously it could not be a local extension of `uninstall' +because the order of execution is not guaranteed. +.QUOTE +.CODE +# directories specific to groff +uninstall-hook: uninstall_groffdirs +uninstall_groffdirs: + if test -d $(DESTDIR)$(datasubdir); then \\ + rm -rf $(DESTDIR)$(fontdir); \\ + rm -rf $(DESTDIR)$(oldfontdir); \\ + rmdir $(DESTDIR)$(datasubdir); \\ + fi + [...] +.CODE OFF +.QUOTE OFF +.TOC +.\" Local Variables: +.\" mode: nroff +.\" End: +.\" vim: filetype=groff: diff --git a/doc/doc.am b/doc/doc.am new file mode 100644 index 0000000..cddc519 --- /dev/null +++ b/doc/doc.am @@ -0,0 +1,711 @@ +# Copyright (C) 2002-2022 Free Software Foundation, Inc. +# Original Makefile.sub written by Werner Lemberg . +# Adapted to Automake by Bertrand Garrigues +# (bertrand.garrigues@laposte.net). +# +# This file is part of groff. +# +# groff is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free +# Software Foundation, either version 3 of the License, or (at your +# option) any later version. +# +# groff is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + +doc_srcdir = $(abs_top_srcdir)/doc +doc_builddir = $(abs_top_builddir)/doc + +# Some document sources are parameterized in configuration options like +# the groff version number and the command prefix. Use this in target +# rules to prepare formattable versions of them from .in files. +DOC_SED = $(SED) \ + -e "s;[@]VERSION[@];$(VERSION);" \ + -e "s;[@]g[@];$(g);g;" + +# Use this in target rules to run the build tree's groff. +# +# It includes flags to locate its tmac and device/font description +# directories and to produce verbose diagnostics in the event of syntax +# or formatting problems. +DOC_GROFF = \ + GROFF_COMMAND_PREFIX= \ + GROFF_BIN_PATH="$(GROFF_BIN_PATH)" \ + $(GROFFBIN) -M $(doc_srcdir) $(MFLAG) $(FFLAG) -ww -b + +# This image file is used by several documents in the groff source tree. +DOC_GNU_EPS = doc/gnu.eps + +# Other doc, installed in $(docdir) +# Files located in the source tree +DOCFILES_INST = \ + doc/me-revisions \ + doc/ms.ms \ + doc/pic.ms +DOCFILES_NOINST = \ + doc/meintro.me.in \ + doc/meintro_fr.me.in \ + doc/meref.me.in +# Files that undergo a transformation prior to groff processing +GENERATEDDOCFILES = \ + doc/meintro.me \ + doc/meintro_fr.me \ + doc/meref.me +# Files generated in the build tree +if USE_GROHTML +PROCESSEDDOCFILES_HTML = \ + doc/pic.html +endif +if USE_GROPDF +PROCESSEDDOCFILES_PDF = \ + doc/automake.pdf \ + doc/groff-man-pages.pdf +endif +PROCESSEDDOCFILES_PS = \ + doc/meref.ps \ + doc/meintro.ps \ + doc/meintro_fr.ps \ + doc/ms.ps \ + doc/pic.ps +PROCESSEDDOCFILES_TXT = \ + doc/groff-man-pages.utf8.txt +PROCESSEDDOCFILES = \ + $(PROCESSEDDOCFILES_HTML) \ + $(PROCESSEDDOCFILES_PS) \ + $(PROCESSEDDOCFILES_PDF) \ + $(PROCESSEDDOCFILES_TXT) + +# Declare minimal dependencies for documents by output driver. +PROCESSEDFILES_DEPS_HTML = pre-grohtml groff troff post-grohtml \ + font/devhtml/stamp font/devps/stamp +PROCESSEDFILES_DEPS_PS = groff troff grops font/devps/stamp +PROCESSEDFILES_DEPS_PDF = groff troff gropdf font/devpdf/stamp +PROCESSEDFILES_DEPS_TXT = groff troff grotty font/devutf8/stamp + +if USE_GROHTML +$(PROCESSEDDOCFILES_HTML): $(PROCESSEDFILES_DEPS_HTML) +endif +$(PROCESSEDDOCFILES_PS): $(PROCESSEDFILES_DEPS_PS) +if USE_GROPDF +$(PROCESSEDDOCFILES_PDF): $(PROCESSEDFILES_DEPS_PDF) +endif +$(PROCESSEDDOCFILES_TXT): $(PROCESSEDFILES_DEPS_TXT) + +otherdocdir = $(docdir) +dist_otherdoc_DATA = $(DOCFILES_INST) +nodist_otherdoc_DATA = $(PROCESSEDDOCFILES) $(GENERATEDDOCFILES) +MOSTLYCLEANFILES += $(GENERATEDDOCFILES) $(PROCESSEDDOCFILES) +EXTRA_DIST += $(DOCFILES_NOINST) + +# pdf doc, written in mom and therefore using contrib/mom/mom.am +# definitions +EXTRA_DIST += doc/automake.mom +if USE_GROPDF +docpdfdocdir = $(pdfdocdir) +nodist_docpdfdoc_DATA = doc/automake.pdf +endif +doc/automake.pdf: doc/automake.mom pdfmom contrib/mom/om.tmac + +# GNU PIC html documentation, installed in $(htmldocdir) +# Other pic*.html files are installed by the local rule +if USE_GROHTML +htmlpicdir = $(htmldocdir) +htmlpic_DATA = $(PROCESSEDDOCFILES_HTML) +HTMLDOCFILESALL = pic*.html +HTMLDOCIMAGEFILES = pic* +endif + +# Examples files, installed in $(exampledir) + +# source tree files +EXAMPLEFILES = \ + doc/webpage.ms \ + doc/groff.css \ + doc/grnexmpl.g \ + doc/grnexmpl.me + +# Generated in the build tree +if USE_GROHTML +PROCESSEDEXAMPLEFILES_HTML = doc/webpage.html +else +PROCESSEDEXAMPLEFILES_HTML = +endif +PROCESSEDEXAMPLEFILES_PS = \ + doc/webpage.ps \ + doc/grnexmpl.ps +PROCESSEDEXAMPLEFILES = \ + $(PROCESSEDEXAMPLEFILES_HTML) \ + $(PROCESSEDEXAMPLEFILES_PS) + +$(PROCESSEDEXAMPLEFILES_HTML): $(PROCESSEDFILES_DEPS_HTML) +$(PROCESSEDEXAMPLEFILES_PS): $(PROCESSEDFILES_DEPS_PS) + +docexamplesdir = $(exampledir) +dist_docexamples_DATA = $(EXAMPLEFILES) +nodist_docexamples_DATA = $(PROCESSEDEXAMPLEFILES) +MOSTLYCLEANFILES += $(PROCESSEDEXAMPLEFILES) + +if USE_GROHTML +# webpage.html is generated; webpage*.html files are installed by the +# local rule. +HTMLEXAMPLEFILESALL = webpage*.html +HTMLEXAMPLEIMAGEFILES = webpage* +htmlexamplesdir = $(exampledir) +endif + +# Locate image subdirectory for HTML documents relative to an +# installation directory such as `htmldocdir` or `exampledir`. Do _not_ +# use for locating files within the source or build trees. +imagedir = img + +EXTRA_DIST += \ + doc/txi-en.tex + +# Introduce variables to house the groff man pages. We break the list +# of page sources into multiple chunks because we have to load Swedish +# localization before formatting groff_mmse.7 and then reload English +# localization afterward. This also serves as a test of groff locale +# switching; being lazy and shunting groff_mmse.7 off to the end of the +# document would not achieve this goal (and not loading Swedish +# localization at all to format it would be gauche). +GROFF_MAN_PAGES1 = \ + src/utils/addftinfo/addftinfo.1 \ + src/utils/afmtodit/afmtodit.1 \ + contrib/chem/chem.1 \ + src/preproc/eqn/eqn.1 \ + contrib/eqn2graph/eqn2graph.1 \ + contrib/gdiffmk/gdiffmk.1 \ + contrib/glilypond/glilypond.1 \ + contrib/gperl/gperl.1 \ + contrib/gpinyin/gpinyin.1 \ + contrib/grap2graph/grap2graph.1 \ + src/preproc/grn/grn.1 \ + src/devices/grodvi/grodvi.1 \ + src/roff/groff/groff.1 \ + src/utils/grog/grog.1 \ + src/devices/grohtml/grohtml.1 \ + src/devices/grolbp/grolbp.1 \ + src/devices/grolj4/grolj4.1 \ + src/devices/gropdf/gropdf.1 \ + src/devices/grops/grops.1 \ + src/devices/grotty/grotty.1 \ + $(GXDITVIEW_MAN1) \ + src/utils/hpftodit/hpftodit.1 \ + src/utils/indxbib/indxbib.1 \ + src/utils/lkbib/lkbib.1 \ + src/utils/lookbib/lookbib.1 \ + contrib/mm/mmroff.1 \ + src/preproc/eqn/neqn.1 \ + src/roff/nroff/nroff.1 \ + src/devices/gropdf/pdfmom.1 \ + contrib/pdfmark/pdfroff.1 \ + src/utils/pfbtops/pfbtops.1 \ + src/preproc/pic/pic.1 \ + contrib/pic2graph/pic2graph.1 \ + src/preproc/preconv/preconv.1 \ + src/preproc/refer/refer.1 \ + src/preproc/soelim/soelim.1 \ + src/preproc/tbl/tbl.1 \ + src/utils/tfmtodit/tfmtodit.1 \ + src/roff/troff/troff.1 \ + $(XTOTROFF_MAN1) \ + man/groff_font.5 \ + man/groff_out.5 \ + man/groff_tmac.5 \ + man/groff.7 \ + man/groff_char.7 \ + man/groff_diff.7 \ + contrib/hdtbl/groff_hdtbl.7 \ + tmac/groff_man.7 \ + tmac/groff_man_style.7 \ + tmac/groff_mdoc.7 \ + tmac/groff_me.7 \ + contrib/mm/groff_mm.7 + +GROFF_MAN_PAGES2 = \ + contrib/mm/groff_mmse.7 + +GROFF_MAN_PAGES3 = \ + contrib/mom/groff_mom.7 \ + tmac/groff_ms.7 \ + contrib/rfc1345/groff_rfc1345.7 \ + tmac/groff_trace.7 \ + tmac/groff_www.7 \ + man/roff.7 + +GROFF_MAN_PAGES_ALL = $(GROFF_MAN_PAGES1) $(GROFF_MAN_PAGES2) \ + $(GROFF_MAN_PAGES3) + +# This is a convenience target for (re-)generating all the man pages. +man-all: $(GROFF_MAN_PAGES_ALL) + +# ...and for cleaning them. +man-clean: + $(RM) $(GROFF_MAN_PAGES_ALL) + +# Many pages use tbl, a few use eqn, and soelim(1) uses pic. We also +# need groff's FreeEuro font so we can embed it. +# +# We embed the fonts (-P-e) to (1) honor the current PDF standard, (2) +# ensure consistent rendering of the document, and (3) exercise this +# feature of gropdf. +doc/groff-man-pages.pdf: $(GROFF_MAN_PAGES_ALL) eqn pic tbl \ + $(TMAC_PACKAGE_MAN) $(TMAC_PACKAGE_MDOC) font/devps/freeeuro.pfa + $(GROFF_V)$(DOC_GROFF) -pet -mandoc -dHF=HB -rC1 \ + -rCHECKSTYLE=3 -Tpdf -P-e \ + $(GROFF_MAN_PAGES1) \ + $(tmac_srcdir)/sv.tmac $(GROFF_MAN_PAGES2) \ + $(tmac_srcdir)/en.tmac $(GROFF_MAN_PAGES3) > $@ + +doc/groff-man-pages.utf8.txt: $(GROFF_MAN_PAGES_ALL) eqn pic tbl \ + $(TMAC_PACKAGE_MAN) $(TMAC_PACKAGE_MDOC) + $(GROFF_V)$(DOC_GROFF) -pet -Tutf8 -mandoc \ + -rCHECKSTYLE=3 $(GROFF_MAN_PAGES1) \ + $(tmac_srcdir)/sv.tmac $(GROFF_MAN_PAGES2) \ + $(tmac_srcdir)/en.tmac $(GROFF_MAN_PAGES3) > $@ + +doc/grnexmpl.ps: $(doc_srcdir)/grnexmpl.me $(doc_srcdir)/grnexmpl.g \ + grn eqn + $(GROFF_V)$(MKDIR_P) `dirname $@` \ + && $(DOC_GROFF) -Tps -ge -me $(doc_srcdir)/grnexmpl.me >$@ + +# Generating *.me from *.me.in is, surprisingly, a challenge. +# 1. A pattern rule ("%.me: %.me.in") is not portable to NetBSD or +# OpenBSD make. +# 2. A single-suffix rule works in an isolated Makefile, but _only_ +# with the .SUFFIXES special target, not with the +# (Automake-specific) SUFFIXES macro. +# .SUFFIXES: .in +# .in: +# $(DOC_SED) $< >$@ +# (One can validly complain that this approach is too general.) +# 3. GNU Automake insists that we use the SUFFIXES macro and not the +# special target. +# error: use variable 'SUFFIXES', not target '.SUFFIXES' +# 4. What about a target rule? We'd have to explicitly write the first +# dependency name in the rule commands because NetBSD make (and +# reportedly OpenBSD) refuses to honor the $< variable in target +# rules. +# +# So what is left? A double-suffix rule--but you have to use it in a +# special way that is explicitly not countenanced by POSIX. +# +# "The application shall ensure that the target portion is a valid +# target name (see Target Rules) of the form .s2 or .s1.s2 (where .s1 +# and .s2 are suffixes that have been given as prerequisites of the +# .SUFFIXES special target and s1 and s2 do not contain any or +# characters.) If there is only one in the target, +# it is a single-suffix inference rule. Targets with two periods are +# double-suffix inference rules. Inference rules can have only one +# target before the ." +# (POSIX Issue 8, make(1), "Inference Rules") +# +# A double-suffix rule won't work in an obvious way because its +# semantics are that the suffix is replaced, not removed. You have to +# add both suffixes to the .SUFFIXES special target, in order with the +# dependency first. +# .SUFFIXES: .me.in .me +# .me.in.me: +# $(DOC_SED) $< >$@ +# Thanks to Automake, we must say +# SUFFIXES += .me.in .me +# for reason 3 above. The GNU Automake manual does not explicitly state +# that it preserves the ordering of the suffixes, but for now it does. +# +# It appears to be dumb luck that this works; the rigamarole by itself +# justifies to me the worth of GNU Make's pattern rules (which require +# neither '.SUFFIXES' nor 'SUFFIXES') and establishing semantics for $< +# in target rules. But I won't hold my breath waiting on other make(1) +# implementors to agree. -- GBR +.PRECIOUS: $(GENERATEDDOCFILES) +SUFFIXES += .me.in .me +.me.in.me: + $(GROFF_V)$(MKDIR_P) `dirname $@` \ + && $(DOC_SED) $< >$@ + +.me.ps: + $(GROFF_V)$(MKDIR_P) `dirname $@` \ + && $(DOC_GROFF) -Tps -me $< >$@ + +# Use '-K utf8', not '-k', in case 'configure' didn't find uchardet. +# The French translation uses tbl; its English counterpart does not. +doc/meintro_fr.ps: doc/meintro_fr.me preconv + $(GROFF_V)$(MKDIR_P) `dirname $@` \ + && $(DOC_GROFF) -K utf8 -t -Tps -me -mfr $< >$@ + +doc/ms.ps: $(doc_srcdir)/ms.ms eqn tbl + $(GROFF_V)$(MKDIR_P) `dirname $@` \ + && $(DOC_GROFF) -et -Tps -ms $(doc_srcdir)/ms.ms >$@ + +doc/pic.ps: $(doc_srcdir)/pic.ms eqn pic tbl + $(GROFF_V)$(MKDIR_P) `dirname $@` \ + && $(DOC_GROFF) -pet -Tps -ms $(doc_srcdir)/pic.ms >$@ + +doc/webpage.ps: $(DOC_GNU_EPS) tmac/www.tmac tbl +doc/webpage.ps: $(doc_srcdir)/webpage.ms + $(GROFF_V)$(MKDIR_P) `dirname $@` \ + && $(DOC_GROFF) -I $(doc_srcdir) -I $(doc_builddir) -t -Tps \ + -ms -mwww $(doc_srcdir)/webpage.ms >$@ + +# We have no "generic" ms documents. +#.ms.ps: +# $(GROFF_V)$(MKDIR_P) `dirname $@` \ +# && $(DOC_GROFF) -Tps -ms $< >$@ + +doc/pic.html: eqn pic tbl +doc/pic.html: tmac/www.tmac +doc/pic.html: $(doc_srcdir)/pic.ms + $(GROFF_V)$(MKDIR_P) $(doc_builddir) \ + && cd $(doc_builddir) \ + && $(DOC_GROFF) -pet -P-Ipic -P-Dimg -P-jpic -Thtml -ms \ + $(doc_srcdir)/pic.ms > pic.html + +doc/webpage.html: tbl +doc/webpage.html: tmac/www.tmac +doc/webpage.html: $(DOC_GNU_EPS) +doc/webpage.html: $(doc_srcdir)/groff.css +doc/webpage.html: $(doc_srcdir)/webpage.ms + $(GROFF_V)$(MKDIR_P) $(doc_builddir) \ + && cd $(doc_builddir) \ + && $(DOC_GROFF) -t -I $(doc_srcdir) -P-jwebpage -P-nrb \ + -P-Iwebpage -P-Dimg -Thtml -ms $(doc_srcdir)/webpage.ms \ + > webpage.html + +# We remove groff.css only from an out-of-source build tree. +mostlyclean-local: mostlyclean_doc +mostlyclean_doc: +if USE_GROHTML + if test -d $(doc_builddir); then \ + cd $(doc_builddir) \ + && for f in $(HTMLDOCFILESALL); do \ + $(RM) $$f; \ + done; \ + fi + if test -d $(doc_builddir)/img; then \ + cd $(doc_builddir)/img \ + && for f in $(HTMLDOCIMAGEFILES); do \ + $(RM) $$f; \ + done; \ + rmdir $(doc_builddir)/img || :; \ + fi +endif + if test $(top_builddir) != $(top_srcdir); then \ + $(RM) $(top_builddir)/doc/groff.css; \ + fi +if USE_GROHTML + if test -d $(doc_builddir); then \ + cd $(doc_builddir) \ + && for f in $(HTMLEXAMPLEFILESALL); do \ + $(RM) $$f; \ + done; \ + fi + if test -d $(doc_builddir)/img; then \ + cd $(doc_builddir)/img \ + && for f in $(HTMLEXAMPLEIMAGEFILES); do \ + $(RM) $$f; \ + done; \ + rmdir $(doc_builddir)/img || :; \ + fi +endif + +install-data-hook: install_doc_htmldoc +install_doc_htmldoc: +if USE_GROHTML + cd $(doc_builddir) \ + && for f in `ls $(HTMLDOCFILESALL)`; do \ + $(RM) $(DESTDIR)$(htmldocdir)/$$f; \ + $(INSTALL_DATA) $$f $(DESTDIR)$(htmldocdir)/$$f; \ + done + -test -d $(DESTDIR)$(htmldocdir)/$(imagedir) \ + || $(mkinstalldirs) $(DESTDIR)$(htmldocdir)/$(imagedir) + $(RM) $(DESTDIR)$(htmldocdir)/$(imagedir)/$(HTMLDOCIMAGEFILES) + $(INSTALL_DATA) $(doc_builddir)/img/$(HTMLDOCIMAGEFILES) \ + $(DESTDIR)$(htmldocdir)/$(imagedir) +endif + +install-data-hook: install_doc_gnu_eps install_doc_examples + +install_doc_gnu_eps: $(DOC_GNU_EPS) + for d in $(doc_builddir) $(doc_srcdir); do \ + if test -f "$$d/gnu.eps"; then \ + $(RM) $(DESTDIR)$(exampledir)/gnu.eps; \ + $(INSTALL_DATA) \ + $$d/gnu.eps $(DESTDIR)$(exampledir)/gnu.eps; \ + break; \ + fi; \ + done + +install_doc_examples: $(DOC_GNU_EPS) +if USE_GROHTML + cd $(doc_builddir) \ + && for f in `ls $(HTMLEXAMPLEFILESALL)`; do \ + $(RM) $(DESTDIR)$(exampledir)/$$f; \ + $(INSTALL_DATA) $$f $(DESTDIR)$(exampledir)/$$f; \ + done + -test -d $(DESTDIR)$(exampledir)/$(imagedir) \ + || $(mkinstalldirs) $(DESTDIR)$(exampledir)/$(imagedir) + $(RM) \ + $(DESTDIR)$(exampledir)/$(imagedir)/$(HTMLEXAMPLEIMAGEFILES) + $(INSTALL_DATA) $(doc_builddir)/img/$(HTMLEXAMPLEIMAGEFILES) \ + $(DESTDIR)$(exampledir)/$(imagedir) +endif + +uninstall-hook: \ + uninstall_doc_examples uninstall_doc_htmldoc +uninstall_doc_examples: + $(RM) $(DESTDIR)$(exampledir)/gnu.eps +if USE_GROHTML + -test -d $(DESTDIR)$(docexamplesdir) \ + && cd $(DESTDIR)$(docexamplesdir) \ + && for f in $(HTMLEXAMPLEFILESALL); do \ + $(RM) $$f; \ + done + -test -d $(DESTDIR)$(docexamplesdir)/$(imagedir) \ + && cd $(DESTDIR)$(docexamplesdir)/$(imagedir) \ + && for f in $(HTMLEXAMPLEIMAGEFILES); do \ + $(RM) $$f; \ + done + -rmdir $(DESTDIR)$(docexamplesdir)/$(imagedir) + -rmdir $(DESTDIR)$(docexamplesdir) +endif + +uninstall_doc_htmldoc: +if USE_GROHTML + -test -d $(DESTDIR)$(htmldocdir) \ + && cd $(DESTDIR)$(htmldocdir) \ + && for f in $(HTMLDOCFILESALL); do \ + $(RM) $$f; \ + done + -test -d $(DESTDIR)$(htmldocdir)/$(imagedir) \ + && cd $(DESTDIR)$(htmldocdir)/$(imagedir) \ + && for f in $(HTMLDOCIMAGEFILES); do \ + $(RM) $$f; \ + done + -rmdir $(DESTDIR)$(htmldocdir)/$(imagedir) + -rmdir $(DESTDIR)$(htmldocdir) +endif + +# groff Texinfo manual +# +# We produce all possible formats by by default and ship them in the +# distribution archive ('make dist') so that people don't need to have +# 'makeinfo' or TeX available. +# +# The GNU info, plain text, and HTML formats require only 'makeinfo'. +# +# DVI and PDF require a working TeX installation. We can't use +# Automake's facilities for PDF production because its 'dist' target +# attempts to generate 'groff.pdf' by invoking 'texi2dvi' without the +# '-E' option (use 'makeinfo' to expand macros), which is needed to +# build this file. 'texi2dvi' honors the 'MAKEINFO' environment +# variable. +# +# Were the foregoing not true, we would simply say this: +#info_TEXINFOS = doc/groff.texi +#doc_groff_TEXINFOS = doc/fdl.texi + +if USE_TEX +GROFF_DVI = doc/groff.dvi +GROFF_PDF = doc/groff.pdf +endif + +all: doc/groff.info doc/groff.txt doc/groff.html $(GROFF_DVI) \ + $(GROFF_PDF) + +# Distribute the manual in source form as well. +EXTRA_DIST += doc/groff.texi doc/fdl.texi + +EXTRA_DIST += doc/groff.info +MAINTAINERCLEANFILES += doc/groff.info +doc/groff.info: $(doc_srcdir)/groff.texi + $(AM_V_at)$(MKDIR_P) $(doc_builddir) + $(AM_V_GEN)LANG=C \ + LC_ALL=C \ + $(MAKEINFO) -o doc/groff.info --enable-encoding \ + -I $(doc_srcdir) $(doc_srcdir)/groff.texi + +# Distribute the Info files. +dist-hook: dist-info-bits +dist-info-bits: + chmod u+w $(distdir)/doc + for d in $(doc_builddir) $(doc_srcdir); do \ + if [ -f "$$d"/groff.info ]; then \ + cp -f "$$d"/groff.info-* $(distdir)/doc; \ + break; \ + fi; \ + done + +EXTRA_DIST += doc/groff.txt +MAINTAINERCLEANFILES += doc/groff.txt +.texi.txt: + $(AM_V_at)$(MKDIR_P) $(doc_builddir) + $(AM_V_GEN)LANG=C \ + LC_ALL=C \ + $(MAKEINFO) --enable-encoding -I $(doc_srcdir) --plaintext \ + -o $@ $< + +# Generate HTML, both split into several files, and as a single file. +# 'html' and its installation counterpart 'install-html' are standard +# Automake targets. +EXTRA_DIST += doc/groff.html doc/groff.html.node +MAINTAINERCLEANFILES += doc/groff.html doc/groff.html.node +.texi.html: + $(AM_V_at)$(MKDIR_P) $(doc_builddir)/ + $(AM_V_GEN)LANG=C \ + LC_ALL=C \ + $(MAKEINFO) --html -I $(doc_srcdir) \ + -o doc/`basename $@`.node $< + $(AM_V_at)LANG=C \ + LC_ALL=C \ + $(MAKEINFO) --html -I $(doc_srcdir) --no-split \ + -o $@ $< + +EXTRA_DIST += doc/groff.dvi doc/groff.pdf + +# Define pattern rules to make our Texinfo manual in DVI and PDF +# formats. 'pdf' and 'dvi' and their installation counterparts +# 'install-pdf' and 'install-dvi' are standard Automake targets. +.texi.dvi: +if HAVE_TEXI2DVI +if USE_TEX + $(AM_V_at)$(MKDIR_P) $(doc_builddir) + $(AM_V_GEN)LANG=C \ + LC_ALL=C \ + TEXINPUTS="$(top_srcdir)/build-aux:$(TEXINPUTS)" \ + MAKEINFO='$(MAKEINFO) -I $(doc_srcdir)' \ + FORCE_SOURCE_DATE=1 \ + $(PROG_TEXI2DVI) -e --batch --build-dir=doc/`basename $@`.t2d \ + -o $@ $< +else + @echo "program 'tex' is missing; cannot generate $@" >&2; \ + exit 1 +endif # USE_TEX +else + @echo "program 'texi2dvi' is missing or too old;" \ + "cannot generate $@" >&2; \ + exit 1 +endif # HAVE_TEXI2DVI + +.texi.pdf: +if HAVE_TEXI2DVI +if USE_TEX + $(AM_V_at)$(MKDIR_P) $(doc_builddir) + $(AM_V_GEN)LANG=C \ + LC_ALL=C \ + TEXINPUTS="$(top_srcdir)/build-aux:$(TEXINPUTS)" \ + MAKEINFO='$(MAKEINFO) -I $(doc_srcdir)' \ + $(PROG_TEXI2DVI) -e --batch --pdf \ + --build-dir=doc/`basename $@`.t2p -o $@ $< +else + @echo "program 'tex' is missing; cannot generate $@" >&2; \ + exit 1 +endif # USE_TEX +else + @echo "program 'texi2dvi' is missing or too old;" \ + "cannot generate $@" >&2; \ + exit 1 +endif # HAVE_TEXI2DVI + +install-doc: install-dvi install-html install-pdf + +maintainer-clean-local: + $(RM) $(doc_builddir)/groff.info* + $(RM) $(doc_builddir)/groff.pdf + $(RM) $(doc_builddir)/groff.dvi + $(RM) $(doc_builddir)/groff.txt + $(RM) -r $(doc_builddir)/groff.html.* + +install-data-local: install-txt +install-txt: + -test -d $(DESTDIR)$(docdir) \ + || $(mkinstalldirs) $(DESTDIR)$(docdir) + cp $(top_srcdir)/doc/groff.txt $(DESTDIR)$(docdir) + +install-data-local: install_infodoc +install_infodoc: doc/groff.info + -test -d $(DESTDIR)$(infodir) \ + || $(mkinstalldirs) $(DESTDIR)$(infodir) + $(RM) $(DESTDIR)/doc/groff.info* + for d in $(doc_builddir) $(doc_srcdir); do \ + if [ -f "$$d"/groff.info ]; then \ + cp "$$d"/groff.info* $(DESTDIR)$(infodir); \ + $(INSTALL_INFO) --info-file="$$d"/groff.info \ + --info-dir=$(DESTDIR)$(infodir); \ + break; \ + fi; \ + done +install-pdf-local: doc/groff.pdf + -test -d $(DESTDIR)$(pdfdocdir) \ + || $(mkinstalldirs) $(DESTDIR)$(pdfdocdir) + cp $(top_srcdir)/doc/groff.pdf $(DESTDIR)$(pdfdocdir) +install-html-local: doc/groff.html + -test -d $(DESTDIR)$(htmldocdir)/groff.html.mono \ + || $(mkinstalldirs) $(DESTDIR)$(htmldocdir)/groff.html.mono + cp -r $(top_srcdir)/doc/groff.html \ + $(DESTDIR)$(htmldocdir)/groff.html.mono + cp -r $(top_srcdir)/doc/groff.html.node \ + $(DESTDIR)$(htmldocdir) + +uninstall-local: uninstall_infodoc uninstall-pdf uninstall-html \ + uninstall-txt +uninstall_doc: uninstall-local +uninstall-doc: uninstall-local +uninstall_infodoc: + -$(INSTALL_INFO) --remove --info-dir=$(DESTDIR)$(infodir) \ + $(DESTDIR)$(infodir)/groff.info + -for f in `ls $(DESTDIR)$(infodir)/groff.info*`; do \ + $(RM) $$f; \ + done +uninstall-pdf: + $(RM) $(DESTDIR)$(pdfdocdir)/groff.pdf + -rmdir $(DESTDIR)$(pdfdocdir) +uninstall-html: + $(RM) $(DESTDIR)$(htmldocdir)/groff.html.mono/* + $(RM) $(DESTDIR)$(htmldocdir)/groff.html.node/* +uninstall-txt: + $(RM) $(DESTDIR)$(docdir)/groff.txt + +# An image of a gnu in enscapsulated PostScript is generated during the +# build process if necessary. Our configure script assumes pnmdepth is +# available if xpmtoppm is (see macro "GROFF_PROG_XPMTOPPM"). +EXTRA_DIST += $(DOC_GNU_EPS) doc/gnu.xpm +$(DOC_GNU_EPS): doc/gnu.xpm + $(AM_V_GEN)if test "$(XPMTOPPM)" != found; then \ + echo "program 'xpmtoppm' is missing; can't generate $@" >&2; \ + exit 1; \ + fi; \ + if test "$(pnmtops)" != found; then \ + echo "program 'pnmtops' is missing; can't generate $@" >&2; \ + exit 1; \ + fi; \ + if ! echo "$(pnmtops_nosetpage)" | grep -q nosetpage; then \ + echo "program 'pnmtops' can't handle -nosetpage option;" \ + "can't generate $@" >&2; \ + exit 1; \ + fi; \ + xpmtoppm $(top_srcdir)/doc/gnu.xpm | pnmdepth 15 \ + | $(pnmtops_nosetpage) -noturn -rle >$@ + +# Provide a copy of the image in the distribution archive to accommodate +# systems without a tool to generate it from an X pixmap. +dist-hook: dist-gnueps +dist-gnueps: + chmod u+w $(distdir)/doc + for d in $(doc_builddir) $(doc_srcdir); do \ + if [ -f "$$d"/$(DOC_GNU_EPS) ]; then \ + cp -f "$$d"/$(DOC_GNU_EPS) $(distdir)/doc; \ + break; \ + fi; \ + done + + +# Local Variables: +# fill-column: 72 +# mode: makefile-automake +# End: +# vim: set autoindent filetype=automake textwidth=72: diff --git a/doc/fdl.texi b/doc/fdl.texi new file mode 100644 index 0000000..46f6b81 --- /dev/null +++ b/doc/fdl.texi @@ -0,0 +1,505 @@ +@c The GNU Free Documentation License. +@center Version 1.3, 3 November 2008 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2000-2018 Free Software Foundation, Inc. +@uref{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, La@TeX{} input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG@. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or PDF produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The ``publisher'' means any person or entity that distributes copies +of the Document to the public. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +@item +RELICENSING + +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the +site means any set of copyrightable works thus published on the MMC +site. + +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +``Incorporate'' means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is ``eligible for relicensing'' if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + 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, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.''@: line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: diff --git a/doc/gnu.eps b/doc/gnu.eps new file mode 100644 index 0000000..6a836c7 --- /dev/null +++ b/doc/gnu.eps @@ -0,0 +1,784 @@ +%!PS-Adobe-3.0 EPSF-3.0 +%%LanguageLevel: 2 +%%Creator: pnmtops +%%Title: noname.ps +%%Pages: 1 +%%BoundingBox: 203 311 408 481 +%%EndComments +%%BeginSetup +/rlestr1 1 string def +/readrlestring { + /rlestr exch def + currentfile rlestr1 readhexstring pop + 0 get + dup 127 le { + currentfile rlestr 0 + 4 3 roll + 1 add getinterval + readhexstring pop + length + } { + 257 exch sub dup + currentfile rlestr1 readhexstring pop + 0 get + exch 0 exch 1 exch 1 sub { + rlestr exch 2 index put + } for + pop + } ifelse +} bind def +/readstring { + dup length 0 { + 3 copy exch + 1 index sub + getinterval + readrlestring + add + 2 copy le { exit } if + } loop + pop pop +} bind def +/rpicstr 107 string def +/gpicstr 107 string def +/bpicstr 107 string def +%%EndSetup +%%Page: 1 1 +gsave +203.76 311.04 translate +204.48 169.92 scale +213 177 4 +[ 213 0 0 -177 0 177 ] +{ rpicstr readstring } +{ gpicstr readstring } +{ bpicstr readstring } +true 3 +colorimage +97ff00f097ff00f097ff00f097ff00f097ff00f097ff00f0ecff04eddcaabddeb1ff00f0ecff04ed +dcaabddeb1ff00f0ecff04eddcaabddeb1ff00f0eeff0ad988777478864555678adfb5ff00f0eeff +0ad988777478864555678adfb5ff00f0eeff0ad988777478864555678adfb5ff00f0f0ff0dfdbba9 +4afcb867b544777675447cb6ff00f0f0ff0dfdbba94afcb867b544777675447cb6ff00f0f0ff0dfd +bba94afcb867b544777675447cb6ff00f0f1ff10faab6985449d5d649543484465675558bdd3ff01 +ecdfe8ff00f0f1ff10faab6985449d5d649543484465675558bdd3ff01ecdfe8ff00f0f1ff10faab +6985449d5d649543484465675558bdd3ff01ecdfe8ff00f0f2ff12fb9de89476454897d54a443974 +43575554339fd7ff06d978778998889ceaff00f0f2ff12fb9de89476454897d54a44397443575554 +339fd7ff06d978778998889ceaff00f0f2ff12fb9de89476454897d54a44397443575554339fd7ff +06d978778998889ceaff00f0f3ff14fc9cfff834455554669b487434a5444755555346cfdaff0afc +869cfdcfa9fedaa988dfecff00f0f3ff14fc9cfff834455554669b487434a5444755555346cfdaff +0afc869cfdcfa9fedaa988dfecff00f0f3ff14fc9cfff834455554669b487434a5444755555346cf +daff0afc869cfdcfa9fedaa988dfecff00f0f3ff159bffd5ae84534554454c74b444474444944566 +5549effdff00fee2ff0ce8977adb8874764564444aee99ecff00f0f3ff159bffd5ae84534554454c +74b4444744449445665549effdff00fee2ff0ce8977adb8874764564444aee99ecff00f0f3ff159b +ffd5ae84534554454c74b4444744449445665549effdff00fee2ff0ce8977adb8874764564444aee +99ecff00f0f5ff18fee8defd9975ca4535454445c47844455444554456444558bffeff0176afe4ff +05e8448baa5665fe44054535797efc8bedff00f0f5ff18fee8defd9975ca4535454445c478444554 +44554456444558bffeff0176afe4ff05e8448baa5665fe44054535797efc8bedff00f0f5ff18fee8 +defd9975ca4535454445c47844455444554456444558bffeff0176afe4ff05e8448baa5665fe4405 +4535797efc8bedff00f0f5ff07e7cef97cd76758a4fe540356754b44fe540b46455463855caaacdd +a7bdafedff01fdbefbff07fd77a86754454445fe4405896446effc9eeeff00f0f5ff07e7cef97cd7 +6758a4fe540356754b44fe540b46455463855caaacdda7bdafedff01fdbefbff07fd77a867544544 +45fe4405896446effc9eeeff00f0f5ff07e7cef97cd76758a4fe540356754b44fe540b4645546385 +5caaacdda7bdafedff01fdbefbff07fd77a86754454445fe4405896446effc9eeeff00f0f6ff11fe +8e758a849ec65488444467c86467945646fe440954555757efca78bffaefedff02d675affeff13fe +ed976666844443444343444455677898affbaeefff00f0f6ff11fe8e758a849ec65488444467c864 +67945646fe440954555757efca78bffaefedff02d675affeff13feed976666844443444343444455 +677898affbaeefff00f0f6ff11fe8e758a849ec65488444467c86467945646fe440954555757efca +78bffaefedff02d675affeff13feed976666844443444343444455677898affbaeefff00f0f6ff1d +c79889555655afc64664457efd75b594485445455445494674eefddeefdaecff039efb6466fd4412 +466558444334563454434555434459cfffe9eff0ff00f0f6ff1dc79889555655afc64664457efd75 +b594485445455445494674eefddeefdaecff039efb6466fd44124665584443345634544345554344 +59cfffe9eff0ff00f0f6ff1dc79889555655afc64664457efd75b594485445455445494674eefdde +efdaecff039efb6466fd4412466558444334563454434555434459cfffe9eff0ff00f0f7ff1ef9ac +796686455447eea64589dffffffddc669557656856684494cecba66c8eecff1aa8fefecb985677b6 +5554844434345346433456457899998effffadf0ff00f0f7ff1ef9ac796686455447eea64589dfff +fffddc669557656856684494cecba66c8eecff1aa8fefecb985677b6555484443434534643345645 +7899998effffadf0ff00f0f7ff1ef9ac796686455447eea64589dffffffddc669557656856684494 +cecba66c8eecff1aa8fefecb985677b65554844434345346433456457899998effffadf0ff00f0f7 +ff1dc7ffeffb557555465bfe77ccfffecccbba568c9dfe8aefbed8dbfeeffd99ebff1bf57deef855 +4454555556534333453453345434644454444579fffbdff1ff00f0f7ff1dc7ffeffb557555465bfe +77ccfffecccbba568c9dfe8aefbed8dbfeeffd99ebff1bf57deef855445455555653433345345334 +5434644454444579fffbdff1ff00f0f7ff1dc7ffeffb557555465bfe77ccfffecccbba568c9dfe8a +efbed8dbfeeffd99ebff1bf57deef8554454555556534333453453345434644454444579fffbdff1 +ff00f0f8ff1efe9ffdedffe7445465959ffbefe967abbbcdcb97778999aaacceefffeb89dfeaff10 +94679d9964454555569a65664345334443fb44034568ffbef1ff00f0f8ff1efe9ffdedffe7445465 +959ffbefe967abbbcdcb97778999aaacceefffeb89dfeaff1094679d9964454555569a6566434533 +4443fb44034568ffbef1ff00f0f8ff1efe9ffdedffe7445465959ffbefe967abbbcdcb97778999aa +acceefffeb89dfeaff1094679d9964454555569a65664345334443fb44034568ffbef1ff00f0f8ff +0ef9ffc5457bff944545bd78ffe97aeffbff07edddccbccccccedee8ff1bfe96434689d556686887 +75874765675444443333344455789cfffaeff2ff00f0f8ff0ef9ffc5457bff944545bd78ffe97aef +fbff07edddccbccccccedee8ff1bfe96434689d55668688775874765675444443333344455789cff +faeff2ff00f0f8ff0ef9ffc5457bff944545bd78ffe97aeffbff07edddccbccccccedee8ff1bfe96 +434689d55668688775874765675444443333344455789cfffaeff2ff00f0f8ff0c9ddea6544469e8 +56567efceb9dd6ff05fda754445bdefdff04c65dfe5444fb33043446effebff2ff00f0f8ff0c9dde +a6544469e856567efceb9dd6ff05fda754445bdefdff04c65dfe5444fb33043446effebff2ff00f0 +f8ff0c9ddea6544469e856567efceb9dd6ff05fda754445bdefdff04c65dfe5444fb33043446effe +bff2ff00f0f9ff0cf8bc7559bb853459679aa9fe9dcbff03fea68ed6fd3307344456765467dfaff2 +ff00f0f9ff0cf8bc7559bb853459679aa9fe9dcbff03fea68ed6fd3307344456765467dfaff2ff00 +f0f9ff0cf8bc7559bb853459679aa9fe9dcbff03fea68ed6fd3307344456765467dfaff2ff00f0fa +ff0dfd74469cb646bdb63459eeffd8efc9ff0dc7cd33334444588754334457dfccf2ff00f0faff0d +fd74469cb646bdb63459eeffd8efc9ff0dc7cd33334444588754334457dfccf2ff00f0faff0dfd74 +469cb646bdb63459eeffd8efc9ff0dc7cd33334444588754334457dfccf2ff00f0faff0cf8964444 +5885457dc436cefb8ec7ff028ab445fd3305345676654debf2ff00f0faff0cf89644445885457dc4 +36cefb8ec7ff028ab445fd3305345676654debf2ff00f0faff0cf89644445885457dc436cefb8ec7 +ff028ab445fd3305345676654debf2ff00f0faff0bc8ffeb7444455444895befb9c6ff05fb8c9543 +3334fe4403577769faf2ff00f0faff0bc8ffeb7444455444895befb9c6ff05fb8c95433334fe4403 +577769faf2ff00f0faff0bc8ffeb7444455444895befb9c6ff05fb8c95433334fe4403577769faf2 +ff00f0fbff0cfe7cbbcacdb6444455666ffb9fc5ff02b8fc43fd330444455568caf2ff00f0fbff0c +fe7cbbcacdb6444455666ffb9fc5ff02b8fc43fd330444455568caf2ff00f0fbff0cfe7cbbcacdb6 +444455666ffb9fc5ff02b8fc43fd330444455568caf2ff00f0fbff0be7e555444569a7444558dfd8 +c4ff0cfa7fb53334433333457abbebeff3ff00f0fbff0be7e555444569a7444558dfd8c4ff0cfa7f +b53334433333457abbebeff3ff00f0fbff0be7e555444569a7444558dfd8c4ff0cfa7fb533344333 +33457abbebeff3ff00f0fbff0b9bfc9cea7544568855da8b8eedff05edbbaaaabcefddff0197e6fe +330634578865569dcff3ff00f0fbff0b9bfc9cea7544568855da8b8eedff05edbbaaaabcefddff01 +97e6fe330634578865569dcff3ff00f0fbff0b9bfc9cea7544568855da8b8eedff05edbbaaaabcef +ddff0197e6fe330634578865569dcff3ff00f0fcff0cfe7ffffeefffd9445776eff7dfefff09eb86 +7789998778778adff7ff02cbcdefecff0bfaa5333433433469dfffffbff3ff00f0fcff0cfe7ffffe +efffd9445776eff7dfefff09eb867789998778778adff7ff02cbcdefecff0bfaa5333433433469df +ffffbff3ff00f0fcff0cfe7ffffeefffd9445776eff7dfefff09eb867789998778778adff7ff02cb +cdefecff0bfaa5333433433469dfffffbff3ff00f0fcff0bf9dfffcbaaabceeb556cffabefff0be7 +69cedbb9988aa9abba88cffaff05fea8998889adecff0a77344555455444467cffaff3ff00f0fcff +0bf9dfffcbaaabceeb556cffabefff0be769cedbb9988aa9abba88cffaff05fea8998889adecff0a +77344555455444467cffaff3ff00f0fcff0bf9dfffcbaaabceeb556cffabefff0be769cedbb9988a +a9abba88cffaff05fea8998889adecff0a77344555455444467cffaff3ff00f0fcff0be8ff944433 +44446afb9efc8ff0ff0dfc69a899abdefeecba8668aa78cffcff07fb9aba988abdfcbdedff0ac874 +55544433344458ffbff3ff00f0fcff0be8ff94443344446afb9efc8ff0ff0dfc69a899abdefeecba +8668aa78cffcff07fb9aba988abdfcbdedff0ac87455544433344458ffbff3ff00f0fcff0be8ff94 +443344446afb9efc8ff0ff0dfc69a899abdefeecba8668aa78cffcff07fb9aba988abdfcbdedff0a +c87455544433344458ffbff3ff00f0fcff0a9dc856789a987544dfffe7f0ff03fd747adffaff04ec +877667dffeff09e978879bcedba98aecbfeeff02f7da53fe3304344456efbff3ff00f0fcff0a9dc8 +56789a987544dfffe7f0ff03fd747adffaff04ec877667dffeff09e978879bcedba98aecbfeeff02 +f7da53fe3304344456efbff3ff00f0fcff0a9dc856789a987544dfffe7f0ff03fd747adffaff04ec +877667dffeff09e978879bcedba98aecbfeeff02f7da53fe3304344456efbff3ff00f0fcff0a8f99 +8887765567977bffadf0ff01a58efeff04fdcfefffcefeff0feb8549ffffd9968ceffb5becfffc89 +efeeff0af9c85333333443344679cef3ff00f0fcff0a8f998887765567977bffadf0ff01a58efeff +04fdcfefffcefeff0feb8549ffffd9968ceffb5becfffc89efeeff0af9c85333333443344679cef3 +ff00f0fcff0a8f998887765567977bffadf0ff01a58efeff04fdcfefffcefeff0feb8549ffffd996 +8ceffb5becfffc89efeeff0af9c85333333443344679cef3ff00f0fdff01faadfe4406568aa86576 +df9ff1ff1dfa8efffffeffff9c885de67cffec9bfd848ddab98effffe754547ffffe89eeff0afd9f +645aa6434696445ecef3ff00f0fdff01faadfe4406568aa86576df9ff1ff1dfa8efffffeffff9c88 +5de67cffec9bfd848ddab98effffe754547ffffe89eeff0afd9f645aa6434696445ecef3ff00f0fd +ff01faadfe4406568aa86576df9ff1ff1dfa8efffffeffff9c885de67cffec9bfd848ddab98effff +e754547ffffe89eeff0afd9f645aa6434696445ecef3ff00f0fdff0bf666544565654458dec9bf9f +f1ff009bfeff1af9c8d99aa9485967ee6766cf9c65be88befdca8d4447349aeffd8ceeff097d4433 +47984348684eddf3ff00f0fdff0bf666544565654458dec9bf9ff1ff009bfeff1af9c8d99aa94859 +67ee6766cf9c65be88befdca8d4447349aeffd8ceeff097d443347984348684eddf3ff00f0fdff0b +f666544565654458dec9bf9ff1ff009bfeff1af9c8d99aa9485967ee6766cf9c65be88befdca8d44 +47349aeffd8ceeff097d443347984348684eddf3ff00f0fdff0bb888aaa8877655554ceffdbff2ff +20e8cfffffc9b9aaab69b74b69586865565ba6d786b7559c5d644945a3465da9ea8eefff09786443 +3434685345bfbcf3ff00f0fdff0bb888aaa8877655554ceffdbff2ff20e8cfffffc9b9aaab69b74b +69586865565ba6d786b7559c5d644945a3465da9ea8eefff097864433434685345bfbcf3ff00f0fd +ff0bb888aaa8877655554ceffdbff2ff20e8cfffffc9b9aaab69b74b69586865565ba6d786b7559c +5d644945a3465da9ea8eefff097864433434685345bfbcf3ff00f0fdff0b6efddb9865554445569f +faeff2ff008efeff17887b8a8c57c668874758754764655a869e644566d548a394fe33025bd7dff0 +ff099a44333344447944bfbaf3ff00f0fdff0b6efddb9865554445569ffaeff2ff008efeff17887b +8a8c57c668874758754764655a869e644566d548a394fe33025bd7dff0ff099a44333344447944bf +baf3ff00f0fdff0b6efddb9865554445569ffaeff2ff008efeff17887b8a8c57c668874758754764 +655a869e644566d548a394fe33025bd7dff0ff099a44333344447944bfbaf3ff00f0feff0bfe7ffc +544444555556666df8f2ff22f8cfbea86ea55d697e56d575a546458546554355a64ba454439b34c4 +54334333345a7bf0ff099d544555433445b65dbaf3ff00f0feff0bfe7ffc544444555556666df8f2 +ff22f8cfbea86ea55d697e56d575a546458546554355a64ba454439b34c454334333345a7bf0ff09 +9d544555433445b65dbaf3ff00f0feff0bfe7ffc544444555556666df8f2ff22f8cfbea86ea55d69 +7e56d575a546458546554355a64ba454439b34c454334333345a7bf0ff099d544555433445b65dba +f3ff00f0feff02fbae95fc44034547eee9f2ff239cdd9bc65bd55d677f56e574c454459645544345 +6855d555654d7386453344533334b99ff1ff09ab4444345543454885a9f3ff00f0feff02fbae95fc +44034547eee9f2ff239cdd9bc65bd55d677f56e574c4544596455443456855d555654d7386453344 +533334b99ff1ff09ab4444345543454885a9f3ff00f0feff02fbae95fc44034547eee9f2ff239cdd +9bc65bd55d677f56e574c4544596455443456855d555654d7386453344533334b99ff1ff09ab4444 +345543454885a9f3ff00f0feff0bf8d9444578b9bcba75356e9cf3ff24f9aff768f549e55a857f55 +d463b4444595476454455655ab584844a3784643637443335bb8f1ff09baa443444345544448e9f3 +ff00f0feff0bf8d9444578b9bcba75356e9cf3ff24f9aff768f549e55a857f55d463b44445954764 +54455655ab584844a3784643637443335bb8f1ff09baa443444345544448e9f3ff00f0feff0bf8d9 +444578b9bcba75356e9cf3ff24f9aff768f549e55a857f55d463b4444595476454455655ab584844 +a3784643637443335bb8f1ff09baa443444345544448e9f3ff00f0feff0bf7fb59bba8754444458d +ef8ff3ff25bce9fa56f648f659956f55d474944444a65784563455945b6594b4546c354363854333 +349b9ff2ff09aba433345533344346e9f3ff00f0feff0bf7fb59bba8754444458def8ff3ff25bce9 +fa56f648f659956f55d474944444a65784563455945b6594b4546c354363854333349b9ff2ff09ab +a433345533344346e9f3ff00f0feff0bf7fb59bba8754444458def8ff3ff25bce9fa56f648f65995 +6f55d474944444a65784563455945b6594b4546c354363854333349b9ff2ff09aba4333455333443 +46e9f3ff00f0feff0bf7ffb854346788787569ce9ff4ff21fe8ff77655f645f756a46e55a4747445 +44b566a4754554a446846479864a45435375fe4301499cf2ff098d7643333568634446daf3ff00f0 +feff0bf7ffb854346788787569ce9ff4ff21fe8ff77655f645f756a46e55a474744544b566a47545 +54a446846479864a45435375fe4301499cf2ff098d7643333568634446daf3ff00f0feff0bf7ffb8 +54346788787569ce9ff4ff21fe8ff77655f645f756a46e55a474744544b566a4754554a446846479 +864a45435375fe4301499cf2ff098d7643333568634446daf3ff00f0feff0bf8ff84589876555676 +6acd9ff4ff21e7ee99b445e754e945945f54c584654544b577c46454548566458a5d5c3864446545 +fe43024486eff3ff0a7f8ac7333334774446faeff4ff00f0feff0bf8ff845898765556766acd9ff4 +ff21e7ee99b445e754e945945f54c584654544b577c46454548566458a5d5c3864446545fe430244 +86eff3ff0a7f8ac7333334774446faeff4ff00f0feff0bf8ff845898765556766acd9ff4ff21e7ee +99b445e754e945945f54c584654544b577c46454548566458a5d5c3864446545fe43024486eff3ff +0a7f8ac7333334774446faeff4ff00f0feff0bf8fe576544455666567ace9ff4ff278dbb6a9544d8 +54da45a46f64d584554644c576c4858554655788fe8b84478445464444534344467df4ff0bfe8e55 +44333334557554cbdff4ff00f0feff0bf8fe576544455666567ace9ff4ff278dbb6a9544d854da45 +a46f64d584554644c576c4858554655788fe8b84478445464444534344467df4ff0bfe8e55443333 +34557554cbdff4ff00f0feff0bf8fe576544455666567ace9ff4ff278dbb6a9544d854da45a46f64 +d584554644c576c4858554655788fe8b84478445464444534344467df4ff0bfe8e55443333345575 +54cbdff4ff00f0feff0bfafc57555666655654448d8ff5ff29f8cff6489735c854bc55c56e54d584 +454844c578d485a6755433a47cf96445b4454735446444344456dff5ff02faae57fd3304355854eb +dff4ff00f0feff0bfafc57555666655654448d8ff5ff29f8cff6489735c854bc55c56e54d5844548 +44c578d485a6755433a47cf96445b4454735446444344456dff5ff02faae57fd3304355854ebdff4 +ff00f0feff0bfafc57555666655654448d8ff5ff29f8cff6489735c854bc55c56e54d584454844c5 +78d485a6755433a47cf96445b4454735446444344456dff5ff02faae57fd3304355854ebdff4ff00 +f0feff0bfdf9a44578adb985445bff8ff5ff299afff6488a34c954ad54d66e44d494444655b679d4 +a5c59666c9c445bfb343b54555364465443444456ef5ff03f8efd543fd330355a4cbeff4ff00f0fe +ff0bfdf9a44578adb985445bff8ff5ff299afff6488a34c954ad54d66e44d494444655b679d4a5c5 +9666c9c445bfb343b54555364465443444456ef5ff03f8efd543fd330355a4cbeff4ff00f0feff0b +fdf9a44578adb985445bff8ff5ff299afff6488a34c954ad54d66e44d494444655b679d4a5c59666 +c9c445bfb343b54555364465443444456ef5ff03f8efd543fd330355a4cbeff4ff00f0fdff0af67b +dfea6546988655cf8ff6ff2afaadff55487c34c9549d44c76c44b4a5445546975bc4a5d4a55dfdc3 +334543437735553444564434443446f5ff04f7ffa43453fe3303347cebeff4ff00f0fdff0af67bdf +ea6546988655cf8ff6ff2afaadff55487c34c9549d44c76c44b4a5445546975bc4a5d4a55dfdc333 +4543437735553444564434443446f5ff04f7ffa43453fe3303347cebeff4ff00f0fdff0af67bdfea +6546988655cf8ff6ff2afaadff55487c34c9549d44c76c44b4a5445546975bc4a5d4a55dfdc33345 +43437735553444564434443446f5ff04f7ffa43453fe3303347cebeff4ff00f0feff0bfcf9fb8545 +6875543345cf8ff6ff2ba8fb9d44486e34a7549c45d66a4594a4444446685ca47694844ae5e53465 +554368345434445545454433446ef6ff0bf7fd533346334333345dfbeff4ff00f0feff0bfcf9fb85 +456875543345cf8ff6ff2ba8fb9d44486e34a7549c45d66a4594a4444446685ca47694844ae5e534 +65554368345434445545454433446ef6ff0bf7fd533346334333345dfbeff4ff00f0feff0bfcf9fb +85456875543345cf8ff6ff2ba8fb9d44486e34a7549c45d66a4594a4444446685ca47694844ae5e5 +3465554368345434445545454433446ef6ff0bf7fd533346334333345dfbeff4ff00f0feff0bfbfe +a558754444697657ff8ff7ff2dfa9ffe5e44466f45a7558b45e5763694b44544574d6c9576556347 +e4db747ca544683444344554454454353446eff7ff0ad6543433346434433489fbf3ff00f0feff0b +fbfea558754444697657ff8ff7ff2dfa9ffe5e44466f45a7558b45e5763694b44544574d6c957655 +6347e4db747ca544683444344554454454353446eff7ff0ad6543433346434433489fbf3ff00f0fe +ff0bfbfea558754444697657ff8ff7ff2dfa9ffe5e44466f45a7558b45e5763694b44544574d6c95 +76556347e4db747ca544683444344554454454353446eff7ff0ad6543433346434433489fbf3ff00 +f0feff0bfaee887544459b85448cfd9cf7ff2d9affff5b54565e5486547847d4644866844535457a +4959fe9a6544d5affb4486866834443444644544643744468ef7ff0a958b433333364334347ffaf3 +ff00f0feff0bfaee887544459b85448cfd9cf7ff2d9affff5b54565e5486547847d4644866844535 +457a4959fe9a6544d5affb4486866834443444644544643744468ef7ff0a958b433333364334347f +faf3ff00f0feff0bfaee887544459b85448cfd9cf7ff2d9affff5b54565e5486547847d464486684 +4535457a4959fe9a6544d5affb4486866834443444644544643744468ef7ff0a958b433333364334 +347ffaf3ff00f0feff0bfadc985459da534784578ad8f8ff2ff8bffbbf7844566f54855455488444 +464853543646696fedcdc84a46555effa543545b444443447446445547645ad7acf8ff0274d543fe +3304543343affbf3ff00f0feff0bfadc985459da534784578ad8f8ff2ff8bffbbf7844566f548554 +55488444464853543646696fedcdc84a46555effa543545b444443447446445547645ad7acf8ff02 +74d543fe3304543343affbf3ff00f0feff0bfadc985459da534784578ad8f8ff2ff8bffbbf784456 +6f54855455488444464853543646696fedcdc84a46555effa543545b444443447446445547645ad7 +acf8ff0274d543fe3304543343affbf3ff00f0feff0bfb9ba56ce9534775444598f7f9ff30fe7cff +fc5f9654556f655455445846a7577a556577bf777855547a7b683836acee63455c54454444645743 +65448457ed9af9ff02fb8663fd33043433436ffaf3ff00f0feff0bfb9ba56ce9534775444598f7f9 +ff30fe7cfffc5f9654556f655455445846a7577a556577bf777855547a7b683836acee63455c5445 +444464574365448457ed9af9ff02fb8663fd33043433436ffaf3ff00f0feff0bfb9ba56ce9534775 +444598f7f9ff30fe7cfffc5f9654556f655455445846a7577a556577bf777855547a7b683836acee +63455c5445444464574365448457ed9af9ff02fb8663fd33043433436ffaf3ff00f0feff0cfe8eda +e9444454465445bdeabffaff31e7dffece5eb555466f555474afd99d84aaa954578887445aedc4bf +8a7a76633455335b7b8487446447a944644454448ff99ffaff0be7e834334334333343343afbf3ff +00f0feff0cfe8edae9444454465445bdeabffaff31e7dffece5eb555466f555474afd99d84aaa954 +578887445aedc4bf8a7a76633455335b7b8487446447a944644454448ff99ffaff0be7e834334334 +333343343afbf3ff00f0feff0cfe8edae9444454465445bdeabffaff31e7dffece5eb555466f5554 +74afd99d84aaa954578887445aedc4bf8a7a76633455335b7b8487446447a944644454448ff99ffa +ff0be7e834334334333343343afbf3ff00f0fdff0b7eec56b6434654445566ce9ffbff32fe7dffff +7c7ba5565566487884963466556778887666789beffff65d9358c585455954ad8c73445534556644 +444334544cfe69faff0b7bd44334333343333334dfbef3ff00f0fdff0b7eec56b6434654445566ce +9ffbff32fe7dffff7c7ba5565566487884963466556778887666789beffff65d9358c585455954ad +8c73445534556644444334544cfe69faff0b7bd44334333343333334dfbef3ff00f0fdff0b7eec56 +b6434654445566ce9ffbff32fe7dffff7c7ba5565566487884963466556778887666789beffff65d +9358c585455954ad8c73445534556644444334544cfe69faff0b7bd44334333343333334dfbef3ff +00f0fdff0b7c94774445544454445bef8cfbff0ee8dfffffa887b46644886ec7458aeffaff00eefe +ff19fe48ec535948437958f9566ab87dbefecaa967675574578de69ffcff02f87b63fa330234ef9f +f3ff00f0fdff0b7c94774445544454445bef8cfbff0ee8dfffffa887b46644886ec7458aeffaff00 +eefeff19fe48ec535948437958f9566ab87dbefecaa967675574578de69ffcff02f87b63fa330234 +ef9ff3ff00f0fdff0b7c94774445544454445bef8cfbff0ee8dfffffa887b46644886ec7458aeffa +ff00eefeff19fe48ec535948437958f9566ab87dbefecaa967675574578de69ffcff02f87b63fa33 +0234ef9ff3ff00f0fdff02a97bb6fe4406585446449ff8bffdff0dfe7effffaec7b6c46545bd7579 +cff3ff0dc57dc6335364543a58efffffb79ffeff11fdcb86557455cf97cffddeffea5564943334fe +330434334afdaff3ff00f0fdff02a97bb6fe4406585446449ff8bffdff0dfe7effffaec7b6c46545 +bd7579cff3ff0dc57dc6335364543a58efffffb79ffeff11fdcb86557455cf97cffddeffea556494 +3334fe330434334afdaff3ff00f0fdff02a97bb6fe4406585446449ff8bffdff0dfe7effffaec7b6 +c46545bd7579cff3ff0dc57dc6335364543a58efffffb79ffeff11fdcb86557455cf97cffddeffea +5564943334fe330434334afdaff3ff00f0fdff0cc9ec64444448754475345fff89fdff0bc8efffea +6bc6b484959866aef1ff08fe745885443334549ffdff01b6effdff10fdb685554bfc654456b847e7 +e633433343fe3303436ff9eff3ff00f0fdff0cc9ec64444448754475345fff89fdff0bc8efffea6b +c6b484959866aef1ff08fe745885443334549ffdff01b6effdff10fdb685554bfc654456b847e7e6 +33433343fe3303436ff9eff3ff00f0fdff0cc9ec64444448754475345fff89fdff0bc8efffea6bc6 +b484959866aef1ff08fe745885443334549ffdff01b6effdff10fdb685554bfc654456b847e7e633 +433343fe3303436ff9eff3ff00f0fdff1be7a644654595644853464cfff88dffffd99fffffc969e5 +9595746aeff8ff00eff9ff0dea454589333684dffffdeffffc6ffbff0ea555635cfec8668aeff764 +54233334fd33014bf9f2ff00f0fdff1be7a644654595644853464cfff88dffffd99fffffc969e595 +95746aeff8ff00eff9ff0dea454589333684dffffdeffffc6ffbff0ea555635cfec8668aeff76454 +233334fd33014bf9f2ff00f0fdff1be7a644654595644853464cfff88dffffd99fffffc969e59595 +746aeff8ff00eff9ff0dea454589333684dffffdeffffc6ffbff0ea555635cfec8668aeff7645423 +3334fd33014bf9f2ff00f0fdff10f7d6585468574476447445efffb988889dfeff058957e564459e +f9ff03fea9568ff9ff0dfeedb845339d75bfffc57fffffb7fbff0cfee644338ebdfb99eac5333553 +fc33023467ccf2ff00f0fdff10f7d6585468574476447445efffb988889dfeff058957e564459ef9 +ff03fea9568ff9ff0dfeedb845339d75bfffc57fffffb7fbff0cfee644338ebdfb99eac5333553fc +33023467ccf2ff00f0fdff10f7d6585468574476447445efffb988889dfeff058957e564459ef9ff +03fea9568ff9ff0dfeedb845339d75bfffc57fffffb7fbff0cfee644338ebdfb99eac5333553fc33 +023467ccf2ff00f0fdff0cfab7a54674655764477544b9cffdff07fdecda5d56e437dffaff05feca +aada35effbff10eeefffeedeb436e7487ff9a87efffff9affbff07cd55433444854344fe33084333 +43333334447a9ff2ff00f0fdff0cfab7a54674655764477544b9cffdff07fdecda5d56e437dffaff +05fecaaada35effbff10eeefffeedeb436e7487ff9a87efffff9affbff07cd55433444854344fe33 +08433343333334447a9ff2ff00f0fdff0cfab7a54674655764477544b9cffdff07fdecda5d56e437 +dffaff05fecaaada35effbff10eeefffeedeb436e7487ff9a87efffff9affbff07cd554334448543 +44fe3308433343333334447a9ff2ff00f0fdff0cfc9e94664655764458473455cefdff06f99b875d +75838ff9ff04c446655339fbff11fe7445effffef955b3346ec8646effffef6dfbff02db9443fd33 +0034f8330248fe9ff2ff00f0fdff0cfc9e94664655764458473455cefdff06f99b875d75838ff9ff +04c446655339fbff11fe7445effffef955b3346ec8646effffef6dfbff02db9443fd330034f83302 +48fe9ff2ff00f0fdff0cfc9e94664655764458473455cefdff06f99b875d75838ff9ff04c4466553 +39fbff11fe7445effffef955b3346ec8646effffef6dfbff02db9443fd330034f8330248fe9ff2ff +00f0fcff157f9764556664457464345577fddfffffea4a475d8434f9ff05fa444343336ffaff10d8 +44aeffefffd553338f9433afffffcfb7fbff03fbd54334fd330b4334433333343333443dfadff2ff +00f0fcff157f9764556664457464345577fddfffffea4a475d8434f9ff05fa444343336ffaff10d8 +44aeffefffd553338f9433afffffcfb7fbff03fbd54334fd330b4334433333343333443dfadff2ff +00f0fcff157f9764556664457464345577fddfffffea4a475d8434f9ff05fa444343336ffaff10d8 +44aeffefffd553338f9433afffffcfb7fbff03fbd54334fd330b4334433333343333443dfadff2ff +00f0fcff158deb457866437655733543459b67ffffa947584b8357f9ff05e433344336effaff10fe +a46cffeffc644358de6434dffffebff6fbff02fe9944f633044233343ceaf1ff00f0fcff158deb45 +7866437655733543459b67ffffa947584b8357f9ff05e433344336effaff10fea46cffeffc644358 +de6434dffffebff6fbff02fe9944f633044233343ceaf1ff00f0fcff158deb457866437655733543 +459b67ffffa947584b8357f9ff05e433344336effaff10fea46cffeffc644358de6434dffffebff6 +fbff02fe9944f633044233343ceaf1ff00f0fcff15bbfb669694455548434634554865faedb64559 +4a639ef9ff04934334338ffcff14d7558dfffaaacffffb4368adfe6338dfffffcff7effbff01c844 +fd33ff34fd330043fe33015e9ef1ff00f0fcff15bbfb669694455548434634554865faedb645594a +639ef9ff04934334338ffcff14d7558dfffaaacffffb4368adfe6338dfffffcff7effbff01c844fd +33ff34fd330043fe33015e9ef1ff00f0fcff15bbfb669694455548434634554865faedb645594a63 +9ef9ff04934334338ffcff14d7558dfffaaacffffb4368adfe6338dfffffcff7effbff01c844fd33 +ff34fd330043fe33015e9ef1ff00f0fcff14e9fb5d6b54465455444534544685f77e7645674545f9 +ff04fd4335337cfcff15b5335646fffffc8bbffea8aeffed733aabaadedff8effbff01f854fb3300 +43fc330334447bbff1ff00f0fcff14e9fb5d6b54465455444534544685f77e7645674545f9ff04fd +4335337cfcff15b5335646fffffc8bbffea8aeffed733aabaadedff8effbff01f854fb330043fc33 +0334447bbff1ff00f0fcff14e9fb5d6b54465455444534544685f77e7645674545f9ff04fd433533 +7cfcff15b5335646fffffc8bbffea8aeffed733aabaadedff8effbff01f854fb330043fc33033444 +7bbff1ff00f0fcff14f8c5d896547544644444344555a5f75c6654664489f9ff04f6335438bffdff +15f946aeff74efffffd58ffffefffffa94368dfc8ccff7faff01fb44f533024475a9f0ff00f0fcff +14f8c5d896547544644444344555a5f75c6654664489f9ff04f6335438bffdff15f946aeff74efff +ffd58ffffefffffa94368dfc8ccff7faff01fb44f533024475a9f0ff00f0fcff14f8c5d896547544 +644444344555a5f75c6654664489f9ff04f6335438bffdff15f946aeff74efffffd58ffffefffffa +94368dfc8ccff7faff01fb44f533024475a9f0ff00f0fcff14fa6de875657456445454443654b6f5 +6a6754543bdff9ff04b4367469bffeff0afc65cfffff849fffffb69ffdff07f883357cfeebffe6fa +ff02fd6543fe330334443334fd330253adccf0ff00f0fcff14fa6de875657456445454443654b6f5 +6a6754543bdff9ff04b4367469bffeff0afc65cfffff849fffffb69ffdff07f883357cfeebffe6fa +ff02fd6543fe330334443334fd330253adccf0ff00f0fcff14fa6de875657456445454443654b6f5 +6a6754543bdff9ff04b4367469bffeff0afc65cfffff849fffffb69ffdff07f883357cfeebffe6fa +ff02fd6543fe330334443334fd330253adccf0ff00f0fcff13fe8ffa75685655446463444555a5e5 +6a7845535ff9ff04fc537fdaf5fdff01a38ffeff05d44efffffaaefdff03f98334bffeff00b7faff +03fb643343fe3302443334fe330343566e9ff0ff00f0fcff13fe8ffa75685655446463444555a5e5 +6a7845535ff9ff04fc537fdaf5fdff01a38ffeff05d44efffffaaefdff03f98334bffeff00b7faff +03fb643343fe3302443334fe330343566e9ff0ff00f0fcff13fe8ffa75685655446463444555a5e5 +6a7845535ff9ff04fc537fdaf5fdff01a38ffeff05d44efffffaaefdff03f98334bffeff00b7faff +03fb643343fe3302443334fe330343566e9ff0ff00f0fbff129ef75968545745544354455575b45a +765443bff9ff04c57affffc6fdff0057fdff06f93dfffffc58effeff07fa53339efeffff8bf9ff02 +843343fe330944333334333433bf78cff0ff00f0fbff129ef75968545745544354455575b45a7654 +43bff9ff04c57affffc6fdff0057fdff06f93dfffffc58effeff07fa53339efeffff8bf9ff028433 +43fe330944333334333433bf78cff0ff00f0fbff129ef75968545745544354455575b45a765443bf +f9ff04c57affffc6fdff0057fdff06f93dfffffc58effeff07fa53339efeffff8bf9ff02843343fe +330944333334333433bf78cff0ff00f0fbff06cbfb5795456848fe44074555548559675434f9ff05 +fd9bafffff6afeff0cfc5dfffcb9876639fffffe54bffeff07fc533356779bff8df9ff02fc4435fe +33ff44ff3304443646fe8aefff00f0fbff06cbfb5795456848fe44074555548559675434f9ff05fd +9bafffff6afeff0cfc5dfffcb9876639fffffe54bffeff07fc533356779bff8df9ff02fc4435fe33 +ff44ff3304443646fe8aefff00f0fbff06cbfb5795456848fe44074555548559675434f9ff05fd9b +afffff6afeff0cfc5dfffcb9876639fffffe54bffeff07fc533356779bff8df9ff02fc4435fe33ff +44ff3304443646fe8aefff00f0fbff11f8fea9945895584534444956457459664437f8ff04e8efff +fe4dfeff0cfa38fb5333433335cfffffc4bffeff01fe93fd3301597bf8ff0d743534333334443343 +535559fe8fefff00f0fbff11f8fea9945895584534444956457459664437f8ff04e8effffe4dfeff +0cfa38fb5333433335cfffffc4bffeff01fe93fd3301597bf8ff0d743534333334443343535559fe +8fefff00f0fbff11f8fea9945895584534444956457459664437f8ff04e8effffe4dfeff0cfa38fb +5333433335cfffffc4bffeff01fe93fd3301597bf8ff0d743534333334443343535559fe8fefff00 +f0fbff11fbafff8678c4644434445c5645544b66644bf8ff04eefffffa6ffeff0cfd345333343338 +94bffffff6bffdff06d4354456875449f8ff01c434fe330834444543537cbfd8efefff00f0fbff11 +fbafff8678c4644434445c5645544b66644bf8ff04eefffffa6ffeff0cfd34533334333894bfffff +f6bffdff06d4354456875449f8ff01c434fe330834444543537cbfd8efefff00f0fbff11fbafff86 +78c4644434445c5645544b66644bf8ff04eefffffa6ffeff0cfd34533334333894bffffff6bffdff +06d4354456875449f8ff01c434fe330834444543537cbfd8efefff00f0faff058efff6c89474fe44 +076b5645555b67544ef5ff01f7affeff0cfe533334333338b97ffffffeadfdff07f6464545557744 +eff9ff0cf5333433334333453356fffb6eeeff00f0faff058efff6c89474fe44076b5645555b6754 +4ef5ff01f7affeff0cfe533334333338b97ffffffeadfdff07f6464545557744eff9ff0cf5333433 +334333453356fffb6eeeff00f0faff058efff6c89474fe44076b5645555b67544ef5ff01f7affeff +0cfe533334333338b97ffffffeadfdff07f6464545557744eff9ff0cf5333433334333453356fffb +6eeeff00f0faff10e8eff8ea7544734454886544555b56648ff5ff01f4effdff075335843345338a +7dfeff0079fdff07fe469333435777cff9ff02f64445fe33064466659efa77dfeeff00f0faff10e8 +eff8ea7544734454886544555b56648ff5ff01f4effdff075335843345338a7dfeff0079fdff07fe +469333435777cff9ff02f64445fe33064466659efa77dfeeff00f0faff10e8eff8ea754473445488 +6544555b56648ff5ff01f4effdff075335843345338a7dfeff0079fdff07fe469333435777cff9ff +02f64445fe33064466659efa77dfeeff00f0faff10fd9dfceb6559533844a59554565a5554eff5ff +00e6fdff08fe45bdc43344436edefeff0067fdff07fe747334334789eff9ff0bfb4446333344458e +66b758efedff00f0faff10fd9dfceb6559533844a59554565a5554eff5ff00e6fdff08fe45bdc433 +44436edefeff0067fdff07fe747334334789eff9ff0bfb4446333344458e66b758efedff00f0faff +10fd9dfceb6559533844a59554565a5554eff5ff00e6fdff08fe45bdc43344436edefeff0067fdff +07fe747334334789eff9ff0bfb4446333344458e66b758efedff00f0f9ff0ef8efee669a43484585 +b4657649453cf4ff009afcff0b4cffd33333435daefffffe5dfdff01eec5fe330136bff8ff09fd69 +b643345874bd636bebff00f0f9ff0ef8efee669a43484585b4657649453cf4ff009afcff0b4cffd3 +3333435daefffffe5dfdff01eec5fe330136bff8ff09fd69b643345874bd636bebff00f0f9ff0ef8 +efee669a43484585b4657649453cf4ff009afcff0b4cffd33333435daefffffe5dfdff01eec5fe33 +0136bff8ff09fd69b643345874bd636bebff00f0f9ff0efe9fffa9b634a54768a5b55559549ff4ff +007efcff0b88fef5333334775ffffff8affdff07feeb43333356768ff8ff07c9fb87dcfed876adea +ff00f0f9ff0efe9fffa9b634a54768a5b55559549ff4ff007efcff0b88fef5333334775ffffff8af +fdff07feeb43333356768ff8ff07c9fb87dcfed876adeaff00f0f9ff0efe9fffa9b634a54768a5b5 +5559549ff4ff007efcff0b88fef5333334775ffffff8affdff07feeb43333356768ff8ff07c9fb87 +dcfed876adeaff00f0f8ff0ccbffbae86594775d6684547655f3ff006ffcff07e77cdc433346a56f +f7ff0583333377845ff8ff06f5668877778bdffcff03feffdfdffeff00fef6ff00f0f8ff0ccbffba +e86594775d6684547655f3ff006ffcff07e77cdc433346a56ff7ff0583333377845ff8ff06f56688 +77778bdffcff03feffdfdffeff00fef6ff00f0f8ff0ccbffbae86594775d6684547655f3ff006ffc +ff07e77cdc433346a56ff7ff0583333377845ff8ff06f5668877778bdffcff03feffdfdffeff00fe +f6ff00f0f8ff0cfdaeefffda55b4ab586554954bf4ff01fc4efdff08feeda49fd88989b59ff7ff05 +d445569c94cff8ff03fbdedeeffcff0ddeffe58bff6e6ffffebde597bdbef9ff00f0f8ff0cfdaeef +ffda55b4ab586554954bf4ff01fc4efdff08feeda49fd88989b59ff7ff05d445569c94cff8ff03fb +dedeeffcff0ddeffe58bff6e6ffffebde597bdbef9ff00f0f8ff0cfdaeefffda55b4ab586554954b +f4ff01fc4efdff08feeda49fd88989b59ff7ff05d445569c94cff8ff03fbdedeeffcff0ddeffe58b +ff6e6ffffebde597bdbef9ff00f0f7ff0bfabdfffcbb49e6bf7654854ff4ff01f95efbff05fd67aa +b75558f6ff05f945669859dff7ff008ffaff0fa4cff738fe579fcbfe76db549b6577affbff00f0f7 +ff0bfabdfffcbb49e6bf7654854ff4ff01f95efbff05fd67aab75558f6ff05f945669859dff7ff00 +8ffaff0fa4cff738fe579fcbfe76db549b6577affbff00f0f7ff0bfabdfffcbb49e6bf7654854ff4 +ff01f95efbff05fd67aab75558f6ff05f945669859dff7ff008ffaff0fa4cff738fe579fcbfe76db +549b6577affbff00f0f6ff0afcacfc94aa79fd6855578ff4ff01f59efbff05eefd989abdeff5ff03 +947757daf6ff009dfaff0ffb5dff56fd45eb48dfa55d849b46b6effbff00f0f6ff0afcacfc94aa79 +fd6855578ff4ff01f59efbff05eefd989abdeff5ff03947757daf6ff009dfaff0ffb5dff56fd45eb +48dfa55d849b46b6effbff00f0f6ff0afcacfc94aa79fd6855578ff4ff01f59efbff05eefd989abd +eff5ff03947757daf6ff009dfaff0ffb5dff56fd45eb48dfa55d849b46b6effbff00f0f5ff09feba +befecffcde8cd5dff4ff01e6aefaff03feefffeef4ff03f64dfffcf6ff00e8f9ff0dd6efd8ee5dd4 +36bff846d48c4c6efaff00f0f5ff09febabefecffcde8cd5dff4ff01e6aefaff03feefffeef4ff03 +f64dfffcf6ff00e8f9ff0dd6efd8ee5dd436bff846d48c4c6efaff00f0f5ff09febabefecffcde8c +d5dff4ff01e6aefaff03feefffeef4ff03f64dfffcf6ff00e8f9ff0dd6efd8ee5dd436bff846d48c +4c6efaff00f0f3ffffbb00cefeff00e5f3ff0198ccf8ff01efdff4ff04fd58fff97ff7ff00f8f9ff +0efa6fffffec59358876446467558aeffbff00f0f3ffffbb00cefeff00e5f3ff0198ccf8ff01efdf +f4ff04fd58fff97ff7ff00f8f9ff0efa6fffffec59358876446467558aeffbff00f0f3ffffbb00ce +feff00e5f3ff0198ccf8ff01efdff4ff04fd58fff97ff7ff00f8f9ff0efa6fffffec593588764464 +67558aeffbff00f0f1ff04ecbcceff69f3ff025cfacee9ff03a4cffb58f7ff01fbcffbff0fcaa957 +766664678889bdeff9fffffebffbff00f0f1ff04ecbcceff69f3ff025cfacee9ff03a4cffb58f7ff +01fbcffbff0fcaa957766664678889bdeff9fffffebffbff00f0f1ff04ecbcceff69f3ff025cface +e9ff03a4cffb58f7ff01fbcffbff0fcaa957766664678889bdeff9fffffebffbff00f0efff02fdc9 +4ef4ff03fd3efbcde9ff04f77ffe46dff7ff009ffbff047bcc89bceffbff00fafeff00bffbff00f0 +efff02fdc94ef4ff03fd3efbcde9ff04f77ffe46dff7ff009ffbff047bcc89bceffbff00fafeff00 +bffbff00f0efff02fdc94ef4ff03fd3efbcde9ff04f77ffe46dff7ff009ffbff047bcc89bceffbff +00fafeff00bffbff00f0eeff01f96ff4ff03f73cfedde9ff04fb4dffa78ef7ff00dafbff028fffcf +f9ff04fafffffebffbff00f0eeff01f96ff4ff03f73cfedde9ff04fb4dffa78ef7ff00dafbff028f +ffcff9ff04fafffffebffbff00f0eeff01f96ff4ff03f73cfedde9ff04fb4dffa78ef7ff00dafbff +028fffcff9ff04fafffffebffbff00f0eeff01f4cff4ff03d54efffee8ff0498fff5d7eef8ff01f9 +effcff029ffeaffdff08eddbba9997ab79adbffbff00f0eeff01f4cff4ff03d54efffee8ff0498ff +f5d7eef8ff01f9effcff029ffeaffdff08eddbba9997ab79adbffbff00f0eeff01f4cff4ff03d54e +fffee8ff0498fff5d7eef8ff01f9effcff029ffeaffdff08eddbba9997ab79adbffbff00f0eeff00 +c6f3ff027956dfe7ff04e5eff78e7df8ff01fe9ffdff10fd787658a987765445785796a8dd55a9cf +fbff00f0eeff00c6f3ff027956dfe7ff04e5eff78e7df8ff01fe9ffdff10fd787658a98776544578 +5796a8dd55a9cffbff00f0eeff00c6f3ff027956dfe7ff04e5eff78e7df8ff01fe9ffdff10fd7876 +58a987765445785796a8dd55a9cffbff00f0eeff007af4ff02fc5fb7e6ff05f56ff95fe9cff8ff00 +dbfdff0ffe9a7684bbb968d74bff78f9fedf97dffaff00f0eeff007af4ff02fc5fb7e6ff05f56ff9 +5fe9cff8ff00dbfdff0ffe9a7684bbb968d74bff78f9fedf97dffaff00f0eeff007af4ff02fc5fb7 +e6ff05f56ff95fe9cff8ff00dbfdff0ffe9a7684bbb968d74bff78f9fedf97dffaff00f0efff01fe +4ef4ff02f78f95f1ff00edf7ff06fd5dfa4effaaeff9ff01fbdffcff0d9bd5fffe6af94aff77f9ff +efe7dffaff00f0efff01fe4ef4ff02f78f95f1ff00edf7ff06fd5dfa4effaaeff9ff01fbdffcff0d +9bd5fffe6af94aff77f9ffefe7dffaff00f0efff01fe4ef4ff02f78f95f1ff00edf7ff06fd5dfa4e +ffaaeff9ff01fbdffcff0d9bd5fffe6af94aff77f9ffefe7dffaff00f0efff01fb6ff4ff03c4efb6 +8ef4ff05feeeb4aeffecf9ff0688fc4afffe89eff9ff00aefcff0d8bb5ffff6afa49ff77f9fffff7 +dffaff00f0efff01fb6ff4ff03c4efb68ef4ff05feeeb4aeffecf9ff0688fc4afffe89eff9ff00ae +fcff0d8bb5ffff6afa49ff77f9fffff7dffaff00f0efff01fb6ff4ff03c4efb68ef4ff05feeeb4ae +ffecf9ff0688fc4afffe89eff9ff00aefcff0d8bb5ffff6afa49ff77f9fffff7dffaff00f0efff01 +f7aff5ff05fe59ffd85eeff5ff0596678959ddddf9ff07e6bd59fffffd99aefaff01f98efdff0d6b +c5ffff5afa48ff86f8ffeff7dffaff00f0efff01f7aff5ff05fe59ffd85eeff5ff0596678959dddd +f9ff07e6bd59fffffd99aefaff01f98efdff0d6bc5ffff5afa48ff86f8ffeff7dffaff00f0efff01 +f7aff5ff05fe59ffd85eeff5ff0596678959ddddf9ff07e6bd59fffffd99aefaff01f98efdff0d6b +c5ffff5afa48ff86f8ffeff7dffaff00f0efff01f4eff5ff05f77ffffc668ff2ff05c8667878888b +fcff02fb6c59fdff02d98beffbff01e8effeff0d7ad6fffe5afb49ff75f8fffff7dffaff00f0efff +01f4eff5ff05f77ffffc668ff2ff05c8667878888bfcff02fb6c59fdff02d98beffbff01e8effeff +0d7ad6fffe5afb49ff75f8fffff7dffaff00f0efff01f4eff5ff05f77ffffc668ff2ff05c8667878 +888bfcff02fb6c59fdff02d98beffbff01e8effeff0d7ad6fffe5afb49ff75f8fffff7dffaff00f0 +efff00c5f4ff05a6efffff754df3ff05ecbcccddeeeffaff01685afcff03fb78adeffeff02ebaaef +feff0d7bd6ffff4bfb4aff75f8fffff7dffaff00f0efff00c5f4ff05a6efffff754df3ff05ecbccc +ddeeeffaff01685afcff03fb78adeffeff02ebaaeffeff0d7bd6ffff4bfb4aff75f8fffff7dffaff +00f0efff00c5f4ff05a6efffff754df3ff05ecbcccddeeeffaff01685afcff03fb78adeffeff02eb +aaeffeff0d7bd6ffff4bfb4aff75f8fffff7dffaff00f0efff0089f5ff01e76ffeff01fb6bf5ff06 +fd66787765458df9ff01a46cfaff05c988999989befcff0d7bc7ffff5afc59ff76f8fffff6dffaff +00f0efff0089f5ff01e76ffeff01fb6bf5ff06fd66787765458df9ff01a46cfaff05c988999989be +fcff0d7bc7ffff5afc59ff76f8fffff6dffaff00f0efff0089f5ff01e76ffeff01fb6bf5ff06fd66 +787765458df9ff01a46cfaff05c988999989befcff0d7bc7ffff5afc59ff76f8fffff6dffaff00f0 +efff005ef6ff02fe55dffdff00abf5ff01f5affeff03feb858effbff01d54eefff0d8bc7fffe4afc +5aff77f8fffff6effaff00f0efff005ef6ff02fe55dffdff00abf5ff01f5affeff03feb858effbff +01d54eefff0d8bc7fffe4afc5aff77f8fffff6effaff00f0efff005ef6ff02fe55dffdff00abf5ff +01f5affeff03feb858effbff01d54eefff0d8bc7fffe4afc5aff77f8fffff6effaff00f0f0ff01fb +5ff6ff01c44dfcff00eff5ff0098fbff01d74bfbff02fc4beff0ff0d7bb7fffe4afd4aff87f8ffff +f6effaff00f0f0ff01fb5ff6ff01c44dfcff00eff5ff0098fbff01d74bfbff02fc4beff0ff0d7bb7 +fffe4afd4aff87f8fffff6effaff00f0f0ff01fb5ff6ff01c44dfcff00eff5ff0098fbff01d74bfb +ff02fc4beff0ff0d7bb7fffe4afd4aff87f8fffff6effaff00f0f0ff01f6bff7ff02fd44cff0ff01 +fc4dfaff01b58efbff0474dfedc88af3ff0d7bb7fffe49fe4bff78f7fffff6effaff00f0f0ff01f6 +bff7ff02fd44cff0ff01fc4dfaff01b58efbff0474dfedc88af3ff0d7bb7fffe49fe4bff78f7ffff +f6effaff00f0f0ff01f6bff7ff02fd44cff0ff01fc4dfaff01b58efbff0474dfedc88af3ff0d7bb7 +fffe49fe4bff78f7fffff6effaff00f0f0ff00b5f6ff01b55cefff04f6cfb6448efcff01a5affcff +0596544557776df4ff0d7bb7fffe49fe4cff78f8fffff6effaff00f0f0ff00b5f6ff01b55cefff04 +f6cfb6448efcff01a5affcff0596544557776df4ff0d7bb7fffe49fe4cff78f8fffff6effaff00f0 +f0ff00b5f6ff01b55cefff04f6cfb6448efcff01a5affcff0596544557776df4ff0d7bb7fffe49fe +4cff78f8fffff6effaff00f0f1ff01fe5cf8ff03fea658efefff05e6f8357755dffdff02fd66bffc +ff00fefeff01d5eff5ff0d7ba8fffe49fe4cff88f7fffff6effaff00f0f1ff01fe5cf8ff03fea658 +efefff05e6f8357755dffdff02fd66bffcff00fefeff01d5eff5ff0d7ba8fffe49fe4cff88f7ffff +f6effaff00f0f1ff01fe5cf8ff03fea658efefff05e6f8357755dffdff02fd66bffcff00fefeff01 +d5eff5ff0d7ba8fffe49fe4cff88f7fffff6effaff00f0f1ff01f59ff9ff03eb7457afeeff05a8a3 +7ffffceffcff02fa57dff9ff01fa8ff5ff0d7bb8fffd4afe4dff89f7fffff6effaff00f0f1ff01f5 +9ff9ff03eb7457afeeff05a8a37ffffceffcff02fa57dff9ff01fa8ff5ff0d7bb8fffd4afe4dff89 +f7fffff6effaff00f0f1ff01f59ff9ff03eb7457afeeff05a8a37ffffceffcff02fa57dff9ff01fa +8ff5ff0d7bb8fffd4afe4dff89f7fffff6effaff00f0f1ff0086fbff05eca876678ccdedff027d53 +bff8ff01e75bf8ff005ff5ff0c7cb8fffd4afe4cffacf8fffff6f9ff00f0f1ff0086fbff05eca876 +678ccdedff027d53bff8ff01e75bf8ff005ff5ff0c7cb8fffd4afe4cffacf8fffff6f9ff00f0f1ff +0086fbff05eca876678ccdedff027d53bff8ff01e75bf8ff005ff5ff0c7cb8fffd4afe4cffacf8ff +fff6f9ff00f0f2ff01fa4efdff08fb75468beffe9db9efeeff026d84eff7ff0185aff9ff006df5ff +0c6cb8fffc4bfb4dff8cf7fffff5f9ff00f0f2ff01fa4efdff08fb75468beffe9db9efeeff026d84 +eff7ff0185aff9ff006df5ff0c6cb8fffc4bfb4dff8cf7fffff5f9ff00f0f2ff01fa4efdff08fb75 +468beffe9db9efeeff026d84eff7ff0185aff9ff006df5ff0c6cb8fffc4bfb4dff8cf7fffff5f9ff +00f0f2ff01a4dffeff03f95799bffeff02fa8abfeeff076dc5ffffc74579effcff00faf8ff008bf5 +ff0c6ca9fffc4bfb4cff8cf7fffff5f9ff00f0f2ff01a4dffeff03f95799bffeff02fa8abfeeff07 +6dc5ffffc74579effcff00faf8ff008bf5ff0c6ca9fffc4bfb4cff8cf7fffff5f9ff00f0f2ff01a4 +dffeff03f95799bffeff02fa8abfeeff076dc5ffffc74579effcff00faf8ff008bf5ff0c6ca9fffc +4bfb4cff8cf7fffff5f9ff00f0f3ff01fa4cfdff0284efe9fdff02fe87bfeeff07befdffff75dca6 +5ef2ff00a9f5ff0c6da9fffc4bfb4cff8bf7fffff5f9ff00f0f3ff01fa4cfdff0284efe9fdff02fe +87bfeeff07befdffff75dca65ef2ff00a9f5ff0c6da9fffc4bfb4cff8bf7fffff5f9ff00f0f3ff01 +fa4cfdff0284efe9fdff02fe87bfeeff07befdffff75dca65ef2ff00a9f5ff0c6da9fffc4bfb4cff +8bf7fffff5f9ff00f0f3ff0173bffeff03fd4bff9dfcff01c4efeeff07dcfffffe43643567f2ff00 +a9f5ff0c6c99fffb4bfb4cff8cf7fffff5f9ff00f0f3ff0173bffeff03fd4bff9dfcff01c4efeeff +07dcfffffe43643567f2ff00a9f5ff0c6c99fffb4bfb4cff8cf7fffff5f9ff00f0f3ff0173bffeff +03fd4bff9dfcff01c4efeeff07dcfffffe43643567f2ff00a9f5ff0c6c99fffb4bfb4cff8cf7ffff +f5f9ff00f0f4ff01f939fdff03f66fff7ffcff00f6f2ff00cefaff06fe433333569adff5ff01db7c +f5ff0c5d99fffb4aa539ff7cf7fffff5f9ff00f0f4ff01f939fdff03f66fff7ffcff00f6f2ff00ce +faff06fe433333569adff5ff01db7cf5ff0c5d99fffb4aa539ff7cf7fffff5f9ff00f0f4ff01f939 +fdff03f66fff7ffcff00f6f2ff00cefaff06fe433333569adff5ff01db7cf5ff0c5d99fffb4aa539 +ff7cf7fffff5f9ff00f0f4ff01f57ffdff03b4bfff7ffcff01f7bff4ff01edeffaff06fe6333333b +546ef6ff02fe875ff5ff0c6da9fffb479dc6bf6cf7fffff5f9ff00f0f4ff01f57ffdff03b4bfff7f +fcff01f7bff4ff01edeffaff06fe6333333b546ef6ff02fe875ff5ff0c6da9fffb479dc6bf6cf7ff +fff5f9ff00f0f4ff01f57ffdff03b4bfff7ffcff01f7bff4ff01edeffaff06fe6333333b546ef6ff +02fe875ff5ff0c6da9fffb479dc6bf6cf7fffff5f9ff00f0f4ff09f4effea69ec849fffe8ffcff01 +f85ff6ff02fe866df8ff05e633334d553af6ff02f7577ff5ff0c5db8fffb46ffec5e6cf7fffff5f9 +ff00f0f4ff09f4effea69ec849fffe8ffcff01f85ff6ff02fe866df8ff05e633334d553af6ff02f7 +577ff5ff0c5db8fffb46ffec5e6cf7fffff5f9ff00f0f4ff09f4effea69ec849fffe8ffcff01f85f +f6ff02fe866df8ff05e633334d553af6ff02f7577ff5ff0c5db8fffb46ffec5e6cf7fffff5f9ff00 +f0f4ff09f77863577347dffffb9ffcff01f95bf6ff01d6aef6ff04b8aeff5b46f6ff0283447ff5ff +0c6ec8fffb4afff9344497ffffe5f9ff00f0f4ff09f77863577347dffffb9ffcff01f95bf6ff01d6 +aef6ff04b8aeff5b46f6ff0283447ff5ff0c6ec8fffb4afff9344497ffffe5f9ff00f0f4ff09f778 +63577347dffffb9ffcff01f95bf6ff01d6aef6ff04b8aeff5b46f6ff0283447ff5ff0c6ec8fffb4a +fff9344497ffffe5f9ff00f0f4ff09fe99abfffedffffffabffcff01f8c9f6ff005df2ff026cb3ef +f8ff03f84334cff5ff0c5eb9fffb38ffe46745a7fffeb6f9ff00f0f4ff09fe99abfffedffffffabf +fcff01f8c9f6ff005df2ff026cb3eff8ff03f84334cff5ff0c5eb9fffb38ffe46745a7fffeb6f9ff +00f0f4ff09fe99abfffedffffffabffcff01f8c9f6ff005df2ff026cb3eff8ff03f84334cff5ff0c +5eb9fffb38ffe46745a7fffeb6f9ff00f0ecff01f9dffcfffff8f2ff01baeff7ff025ce4aff9ff03 +fe743337f4ff0c5eb8fffa45ffe5ff6cf7eadda6f9ff00f0ecff01f9dffcfffff8f2ff01baeff7ff +025ce4aff9ff03fe743337f4ff0c5eb8fffa45ffe5ff6cf7eadda6f9ff00f0ecff01f9dffcfffff8 +f2ff01baeff7ff025ce4aff9ff03fe743337f4ff0c5eb8fffa45ffe5ff6cf7eadda6f9ff00f0ecff +01f8dffcfffff8f3ff05c5464afffffefbff03fe6ff57ffaff04feb643345ef4ff0c4eb8fff944cf +88ff5bf7a37ba6f9ff00f0ecff01f8dffcfffff8f3ff05c5464afffffefbff03fe6ff57ffaff04fe +b643345ef4ff0c4eb8fff944cf88ff5bf7a37ba6f9ff00f0ecff01f8dffcfffff8f3ff05c5464aff +fffefbff03fe6ff57ffaff04feb643345ef4ff0c4eb8fff944cf88ff5bf7a37ba6f9ff00f0ecff01 +f9cffcff01f9e7f3ff05aedfe5bffdeff9ff01f99ffbff05eed7433346bff4ff0c4db9fff846df59 +ff6bf7a35ca7f9ff00f0ecff01f9cffcff01f9e7f3ff05aedfe5bffdeff9ff01f99ffbff05eed743 +3346bff4ff0c4db9fff846df59ff6bf7a35ca7f9ff00f0ecff01f9cffcff01f9e7f3ff05aedfe5bf +fdeff9ff01f99ffbff05eed7433346bff4ff0c4db9fff846df59ff6bf7a35ca7f9ff00f0ecff01f9 +cffcff02fac8dff2ff02fc4df8f0ff04fc64333378f3ff0c4ca9fff639ee84af5bf7834b97f9ff00 +f0ecff01f9cffcff02fac8dff2ff02fc4df8f0ff04fc64333378f3ff0c4ca9fff639ee84af5bf783 +4b97f9ff00f0ecff01f9cffcff02fac8dff2ff02fc4df8f0ff04fc64333378f3ff0c4ca9fff639ee +84af5bf7834b97f9ff00f0ecff01fabffbff01a85ef1ff0179e8f1ff05fe853333356ef3ff0c4da5 +585445759a5a5bf7c69b97f9ff00f0ecff01fabffbff01a85ef1ff0179e8f1ff05fe853333356ef3 +ff0c4da5585445759a5a5bf7c69b97f9ff00f0ecff01fabffbff01a85ef1ff0179e8f1ff05fe8533 +33356ef3ff0c4da5585445759a5a5bf7c69b97f9ff00f0ecff01fb9ffaff0097f1ff01d6aaf1ff05 +e743433346dff3ff0c4da85eedba8654444bf7edfb97f9ff00f0ecff01fb9ffaff0097f1ff01d6aa +f1ff05e743433346dff3ff0c4da85eedba8654444bf7edfb97f9ff00f0ecff01fb9ffaff0097f1ff +01d6aaf1ff05e743433346dff3ff0c4da85eedba8654444bf7edfb97f9ff00f0ecff01fd8ffaff01 +e6cff2ff01f96af2ff05fe743433346ef2ff0c5d8668aceffffffe5bf7effc97f9ff00f0ecff01fd +8ffaff01e6cff2ff01f96af2ff05fe743433346ef2ff0c5d8668aceffffffe5bf7effc97f9ff00f0 +ecff01fd8ffaff01e6cff2ff01f96af2ff05fe743433346ef2ff0c5d8668aceffffffe5bf7effc97 +f9ff00f0ecff01fe7ffaff01f89ff2ff01fe58f4ff07feede744443346dff2ff0c7d746456555666 +685bf7fffd98f9ff00f0ecff01fe7ffaff01f89ff2ff01fe58f4ff07feede744443346dff2ff0c7d +746456555666685bf7fffd98f9ff00f0ecff01fe7ffaff01f89ff2ff01fe58f4ff07feede7444433 +46dff2ff0c7d746456555666685bf7fffd98f9ff00f0ebff007ffaff01eb8ff1ff00b5f2ff05c889 +755459eff2ff0c6c8555bfffffec585bf7fffda8f9ff00f0ebff007ffaff01eb8ff1ff00b5f2ff05 +c889755459eff2ff0c6c8555bfffffec585bf7fffda8f9ff00f0ebff007ffaff01eb8ff1ff00b5f2 +ff05c889755459eff2ff0c6c8555bfffffec585bf7fffda8f9ff00f0ebff007ffaff01bd8ff1ff01 +f6cff3ff09eeffedbafd8efffeeedff7ff04fe696597fefeff05d55bf6fffea9f9ff00f0ebff007f +faff01bd8ff1ff01f6cff3ff09eeffedbafd8efffeeedff7ff04fe696597fefeff05d55bf6fffea9 +f9ff00f0ebff007ffaff01bd8ff1ff01f6cff3ff09eeffedbafd8efffeeedff7ff04fe696597fefe +ff05d55bf6fffea9f9ff00f0ebff007efaff01db9cf1ff01fb8feeff06fb67656764666dfaff0efd +84434658abceeeecb64af6fffea8f9ff00f0ebff007efaff01db9cf1ff01fb8feeff06fb67656764 +666dfaff0efd84434658abceeeecb64af6fffea8f9ff00f0ebff007efaff01db9cf1ff01fb8feeff +06fb67656764666dfaff0efd84434658abceeeecb64af6fffea8f9ff00f0ebff009bfaff01f9c8f0 +ff007eedff05ccfffebefe7afaff0ef86aa98999a8764444364af6fffea9f9ff00f0ebff009bfaff +01f9c8f0ff007eedff05ccfffebefe7afaff0ef86aa98999a8764444364af6fffea9f9ff00f0ebff +009bfaff01f9c8f0ff007eedff05ccfffebefe7afaff0ef86aa98999a8764444364af6fffea9f9ff +00f0ebff00bafaff02fe95acf1ff00d8edff06fbdf97cceee6effbff0eb86544665567594666444a +e6fffd9af9ff00f0ebff00bafaff02fe95acf1ff00d8edff06fbdf97cceee6effbff0eb865446655 +67594666444ae6fffd9af9ff00f0ebff00bafaff02fe95acf1ff00d8edff06fbdf97cceee6effbff +0eb86544665567594666444ae6fffd9af9ff00f0ebff00d8f9ff03fbcb88eff3ff01fd8feeff06fe +9eb4386efc7ffbff0efeb764957acb5756544649d5fffd8af9ff00f0ebff00d8f9ff03fbcb88eff3 +ff01fd8feeff06fe9eb4386efc7ffbff0efeb764957acb5756544649d5fffd8af9ff00f0ebff00d8 +f9ff03fbcb88eff3ff01fd8feeff06fe9eb4386efc7ffbff0efeb764957acb5756544649d5fffd8a +f9ff00f0ebff00f7f9ff04fcbffd88eff3ff00c9eeff06fd7ed5439eff8af9ff0ce5f7aefe6ecdbd +dc58d6fffc8af9ff00f0ebff00f7f9ff04fcbffd88eff3ff00c9eeff06fd7ed5439eff8af9ff0ce5 +f7aefe6ecdbddc58d6fffc8af9ff00f0ebff00f7f9ff04fcbffd88eff3ff00c9eeff06fd7ed5439e +ff8af9ff0ce5f7aefe6ecdbddc58d6fffc8af9ff00f0ebff00f7f8ff03baacfd7cf3ff01fc9ff2ff +0aeffebaa638e8547fffd5dffaff0ce5f6adec58deebba57e6fffb8af9ff00f0ebff00f7f8ff03ba +acfd7cf3ff01fc9ff2ff0aeffebaa638e8547fffd5dffaff0ce5f6adec58deebba57e6fffb8af9ff +00f0ebff00f7f8ff03baacfd7cf3ff01fc9ff2ff0aeffebaa638e8547fffd5dffaff0ce5f6adec58 +deebba57e6fffb8af9ff00f0ebff01facff8ff03eb9cf7dff3ff0186cff7ff0ec96655556798674a +54ba555cfffc6dfbff10feb5b76554445569a738f6fffa88ccccdffcff00f0ebff01facff8ff03eb +9cf7dff3ff0186cff7ff0ec96655556798674a54ba555cfffc6dfbff10feb5b76554445569a738f6 +fffa88ccccdffcff00f0ebff01facff8ff03eb9cf7dff3ff0186cff7ff0ec96655556798674a54ba +555cfffc6dfbff10feb5b76554445569a738f6fffa88ccccdffcff00f0ebff01fd9ff7ff02fab86a +f3ff1be749effecbceefffeed996543344444333334bdeb36a454779bec68efcff00b6fc440b5444 +564ae6fffd855554456dfdff00f0ebff01fd9ff7ff02fab86af3ff1be749effecbceefffeed99654 +3344444333334bdeb36a454779bec68efcff00b6fc440b5444564ae6fffd855554456dfdff00f0eb +ff01fd9ff7ff02fab86af3ff1be749effecbceefffeed996543344444333334bdeb36a454779bec6 +8efcff00b6fc440b5444564ae6fffd855554456dfdff00f0eaff006ff7ff02fe99e7f2ff08a45553 +3469cdcdb643fa3322349ffff73435469766774688898899996444455555455555454af6ffff8645 +4444489afeff00f0eaff006ff7ff02fe99e7f2ff08a455533469cdcdb643fa3322349ffff7343546 +9766774688898899996444455555455555454af6ffff86454444489afeff00f0eaff006ff7ff02fe +99e7f2ff08a455533469cdcdb643fa3322349ffff734354697667746888988999964444555554555 +55454af6ffff86454444489afeff00f0eaff008df7ff02f9e8f8f2ff06fc445bdcdb9754fc331034 +44334438fffffd455844678bdfdacebafeab00a8fb990f98775cf5efff78bbcbaaaab77ffffff0ea +ff008df7ff02f9e8f8f2ff06fc445bdcdb9754fc33103444334438fffffd455844678bdfdacebafe +ab00a8fb990f98775cf5efff78bbcbaaaab77ffffff0eaff008df7ff02f9e8f8f2ff06fc445bdcdb +9754fc33103444334438fffffd455844678bdfdacebafeab00a8fb990f98775cf5efff78bbcbaaaa +b77ffffff0eaff00d8f7ff02f8d9acf1ff04e534444343fd33134433456655437ffffffe466857ec +a37be8788767fe8815778799998aaabbba5bc5efff7899866658869ffffff0eaff00d8f7ff02f8d9 +acf1ff04e534444343fd33134433456655437ffffffe466857eca37be8788767fe8815778799998a +aabbba5bc5efff7899866658869ffffff0eaff00d8f7ff02f8d9acf1ff04e534444343fd33134433 +456655437ffffffe466857eca37be8788767fe8815778799998aaabbba5bc5efff7899866658869f +fffff0eaff00f7f7ff02f98e8ef1ff0ffc74333334688887abcbaaefefded9affeff22488666fed3 +47c49ddcbbaabbba75a469c85cccdccb7db5cffe7cfff8bd6ff9cffffff0eaff00f7f7ff02f98e8e +f1ff0ffc74333334688887abcbaaefefded9affeff22488666fed347c49ddcbbaabbba75a469c85c +ccdccb7db5cffe7cfff8bd6ff9cffffff0eaff00f7f7ff02f98e8ef1ff0ffc74333334688887abcb +aaefefded9affeff22488666fed347c49ddcbbaabbba75a469c85cccdccb7db5cffe7cfff8bd6ff9 +cffffff0eaff00f7f7ff02f78f8fefff03edcdddeff9ff01fd8ffeff0757b585dfe447c4bffcff04 +86e49efa7ffeff0d8ee5cffd7dfff8ce6ff9dffffff0eaff00f7f7ff02f78f8fefff03edcdddeff9 +ff01fd8ffeff0757b585dfe447c4bffcff0486e49efa7ffeff0d8ee5cffd7dfff8ce6ff9dffffff0 +eaff00f7f7ff02f78f8fefff03edcdddeff9ff01fd8ffeff0757b585dfe447c4bffcff0486e49efa +7ffeff0d8ee5cffd7dfff8ce6ff9dffffff0eaff01f8dff8ff02f78cafedff00fcf8ff0cfe7fffff +fe58c6949fe559b4dffcff04a7f48fe99ffeff0d8ff5dffe6dfff9ce6ff9dffffff0eaff01f8dff8 +ff02f78cafedff00fcf8ff0cfe7ffffffe58c6949fe559b4dffcff04a7f48fe99ffeff0d8ff5dffe +6dfff9ce6ff9dffffff0eaff01f8dff8ff02f78cafedff00fcf8ff0cfe7ffffffe58c6949fe559b4 +dffcff04a7f48fe99ffeff0d8ff5dffe6dfff9ce6ff9dffffff0eaff01fbaff8ff02f96cafe3ff0b +fb8ffffffe58d8955ff65cb6fbff1596e58ff88ffffffd7ee5dfff6dfff8cd7ff9effffff0eaff01 +fbaff8ff02f96cafe3ff0bfb8ffffffe58d8955ff65cb6fbff1596e58ff88ffffffd7ee5dfff6dff +f8cd7ff9effffff0eaff01fbaff8ff02f96cafe3ff0bfb8ffffffe58d8955ff65cb6fbff1596e58f +f88ffffffd7ee5dfff6dfff8cd7ff9effffff0e9ff007ff7ff01798fe3ff0bf6dffffffd58e7765e +f66e97fbff1596f57ff98ffffffd7ff5efff6dfff8dd8ff8effffff0e9ff007ff7ff01798fe3ff0b +f6dffffffd58e7765ef66e97fbff1596f57ff98ffffffd7ff5efff6dfff8dd8ff8effffff0e9ff00 +7ff7ff01798fe3ff0bf6dffffffd58e7765ef66e97fbff1596f57ff98ffffffd7ff5efff6dfff8dd +8ff8effffff0e9ff00baf7ff01f66ce3ff00c6feff07fd69e6685be66f88fbff1196f59ff99fffff +fe8fe6ffff5efff8ec9ff7feff00f0e9ff00baf7ff01f66ce3ff00c6feff07fd69e6685be66f88fb +ff1196f59ff99ffffffe8fe6ffff5efff8ec9ff7feff00f0e9ff00baf7ff01f66ce3ff00c6feff07 +fd69e6685be66f88fbff1196f59ff99ffffffe8fe6ffff5efff8ec9ff7feff00f0e9ff00f7f7ff03 +fe87fffde6ff01fe7dfeff07fc5af67938d67f6afbff04a5d59ff89ffeff099fe7ffff5efff8fbaf +f7feff00f0e9ff00f7f7ff03fe87fffde6ff01fe7dfeff07fc5af67938d67f6afbff04a5d59ff89f +feff099fe7ffff5efff8fbaff7feff00f0e9ff00f7f7ff03fe87fffde6ff01fe7dfeff07fc5af679 +38d67f6afbff04a5d59ff89ffeff099fe7ffff5efff8fbaff7feff00f0e9ff01f9cff7ff02fbbff7 +e7ff02fd88effeff07fb5ce67935d78e5efbff0495c49ff89ffeff099fe7ffff5efff8fabff6feff +00f0e9ff01f9cff7ff02fbbff7e7ff02fd88effeff07fb5ce67935d78e5efbff0495c49ff89ffeff +099fe7ffff5efff8fabff6feff00f0e9ff01f9cff7ff02fbbff7e7ff02fd88effeff07fb5ce67935 +d78e5efbff0495c49ff89ffeff099fe7ffff5efff8fabff6feff00f0e9ff01fd8ff6ff01aee8eaff +fffe02b88aeffdff07fb4ec8a944b7ad5ffbff0496c49ff7affeff099fe7ffff5ffff8f9dff7feff +00f0e9ff01fd8ff6ff01aee8eafffffe02b88aeffdff07fb4ec8a944b7ad5ffbff0496c49ff7affe +ff099fe7ffff5ffff8f9dff7feff00f0e9ff01fd8ff6ff01aee8eafffffe02b88aeffdff07fb4ec8 +a944b7ad5ffbff0496c49ff7affeff099fe7ffff5ffff8f9dff7feff00f0e8ff007ef6ff03fac9ff +dff1ff07db967665555788cffbff07fb4eb8d67587c97ffbff0486d49fe7affeff099fe7ffff6fff +f8f8efe6feff00f0e8ff007ef6ff03fac9ffdff1ff07db967665555788cffbff07fb4eb8d67587c9 +7ffbff0486d49fe7affeff099fe7ffff6ffff8f8efe6feff00f0e8ff007ef6ff03fac9ffdff1ff07 +db967665555788cffbff07fb4eb8d67587c97ffbff0486d49fe7affeff099fe7ffff6ffff8f8efe6 +feff00f0e8ff00b8f6ff03fac9ffdff2ff06b643333343334ef9ff07f95faae6a566d79ffbff1186 +d49fe6affffffe8fe8ffff6ffff8f8ffd5feff00f0e8ff00b8f6ff03fac9ffdff2ff06b643333343 +334ef9ff07f95faae6a566d79ffbff1186d49fe6affffffe8fe8ffff6ffff8f8ffd5feff00f0e8ff +00b8f6ff03fac9ffdff2ff06b643333343334ef9ff07f95faae6a566d79ffbff1186d49fe6afffff +fe8fe8ffff6ffff8f8ffd5feff00f0e8ff01f9bff7ff03cbb9fe8ff4ff01fe94fb33007ff9ff07f8 +6f8af7d655d5dffbff1186d4aff5affffffe7fe8ffff7ffff7f7ffb5feff00f0e8ff01f9bff7ff03 +cbb9fe8ff4ff01fe94fb33007ff9ff07f86f8af7d655d5dffbff1186d4aff5affffffe7fe8ffff7f +fff7f7ffb5feff00f0e8ff01f9bff7ff03cbb9fe8ff4ff01fe94fb33007ff9ff07f86f8af7d655d5 +dffbff1186d4aff5affffffe7fe8ffff7ffff7f7ffb5feff00f0e7ff007ef7ff03adc9fadff4ff08 +b544333334333434dff9ff06f76f7bf97656e5faff0496e3bff4cffeff099fe8ffff7fffe8f7ffc8 +feff00f0e7ff007ef7ff03adc9fadff4ff08b544333334333434dff9ff06f76f7bf97656e5faff04 +96e3bff4cffeff099fe8ffff7fffe8f7ffc8feff00f0e7ff007ef7ff03adc9fadff4ff08b5443333 +34333434dff9ff06f76f7bf97656e5faff0496e3bff4cffeff099fe8ffff7fffe8f7ffc8feff00f0 +e7ff00d9f7ff03cae7f8fef4ff0083fc33014339f8ff06f68f6dfc5947c5faff11a5e3cff4aaa978 +998fd8fffc49ffe8f7ffcbfeff00f0e7ff00d9f7ff03cae7f8fef4ff0083fc33014339f8ff06f68f +6dfc5947c5faff11a5e3cff4aaa978998fd8fffc49ffe8f7ffcbfeff00f0e7ff00d9f7ff03cae7f8 +fef4ff0083fc33014339f8ff06f68f6dfc5947c5faff11a5e3cff4aaa978998fd8fffc49ffe8f7ff +cbfeff00f0e7ff01facff8ff02f7e8c7f3ff079c665655469de63af8ff1ff59f6ffe4b48c4666777 +6678776656d4cff49bbba9978fc7fffe546db8f7ffcafeff00f0e7ff01facff8ff02f7e8c7f3ff07 +9c665655469de63af8ff1ff59f6ffe4b48c46667776678776656d4cff49bbba9978fc7fffe546db8 +f7ffcafeff00f0e7ff01facff8ff02f7e8c7f3ff079c665655469de63af8ff1ff59f6ffe4b48c466 +67776678776656d4cff49bbba9978fc7fffe546db8f7ffcafeff00f0e6ff008ef8ff04fe8977fffc +f4ff07c58e7ad9cfe864cff9ff1fe59f6ffe7769c6eeeedddeddeeffc5e4cfd4dffffffb9fd7ffff +ac6478e8ffcafeff00f0e6ff008ef8ff04fe8977fffcf4ff07c58e7ad9cfe864cff9ff1fe59f6ffe +7769c6eeeedddeddeeffc5e4cfd4dffffffb9fd7ffffac6478e8ffcafeff00f0e6ff008ef8ff04fe +8977fffcf4ff07c58e7ad9cfe864cff9ff1fe59f6ffe7769c6eeeedddeddeeffc5e4cfd4dffffffb +9fd7ffffac6478e8ffcafeff00f0e6ff01e7eff8ff0afa45dffcfffdbefdfffaeffbff07f7cd6ffc +bffbf86ff9ff07b69e6fffd46bd49efbff11c6f3cfe4effffffccfe9fffe9ffc67d9ffbbfeff00f0 +e6ff01e7eff8ff0afa45dffcfffdbefdfffaeffbff07f7cd6ffcbffbf86ff9ff07b69e6fffd46bd4 +9efbff11c6f3cfe4effffffccfe9fffe9ffc67d9ffbbfeff00f0e6ff01e7eff8ff0afa45dffcfffd +befdfffaeffbff07f7cd6ffcbffbf86ff9ff07b69e6fffd46bd49efbff11c6f3cfe4effffffccfe9 +fffe9ffc67d9ffbbfeff00f0e6ff01fe7cf8ff09fe74affcfcfe8cefffb6faff07fa9a8efe9ffffd +4df9ff08b6cd7ffff55da877dffcff11b6d4dfd4effffffddff9fffe9fffa9caffadfeff00f0e6ff +01fe7cf8ff09fe74affcfcfe8cefffb6faff07fa9a8efe9ffffd4df9ff08b6cd7ffff55da877dffc +ff11b6d4dfd4effffffddff9fffe9fffa9caffadfeff00f0e6ff01fe7cf8ff09fe74affcfcfe8cef +ffb6faff07fa9a8efe9ffffd4df9ff08b6cd7ffff55da877dffcff11b6d4dfd4effffffddff9fffe +9fffa9caffadfeff00f0e5ff01f9bff9ff02fe946ffefb03cebfff5cfaff07fe8e8afe9fcdff76f9 +ff0985e99ffff85e5adc69effdff03d6435554feff0afebff8fffe8fff8aabefaffeff00f0e5ff01 +f9bff9ff02fe946ffefb03cebfff5cfaff07fe8e8afe9fcdff76f9ff0985e99ffff85e5adc69effd +ff03d6435554feff0afebff8fffe8fff8aabefaffeff00f0e5ff01f9bff9ff02fe946ffefb03cebf +ff5cfaff07fe8e8afe9fcdff76f9ff0985e99ffff85e5adc69effdff03d6435554feff0afebff8ff +fe8fff8aabefaffeff00f0e4ff00a9f8ff08f94dfbfce8df9ffbaaf9ff06df8a9bbfd8ffb7f9ff09 +d565cffff86d658ee749fcff02ecbacefeff0afe8fe5fffe9fff6656896cfeff00f0e4ff00a9f8ff +08f94dfbfce8df9ffbaaf9ff06df8a9bbfd8ffb7f9ff09d565cffff86d658ee749fcff02ecbacefe +ff0afe8fe5fffe9fff6656896cfeff00f0e4ff00a9f8ff08f94dfbfce8df9ffbaaf9ff06df8a9bbf +d8ffb7f9ff09d565cffff86d658ee749fcff02ecbacefeff0afe8fe5fffe9fff6656896cfeff00f0 +e4ff01fc7df9ff08fd46ebfdd9cb8ef8ccf9ff06fedf97fff7ff98f8ff09faefffe89e6e859fd75b +f6ff0d56a8fffebfffcdfedd648dfffff0e4ff01fc7df9ff08fd46ebfdd9cb8ef8ccf9ff06fedf97 +fff7ff98f8ff09faefffe89e6e859fd75bf6ff0d56a8fffebfffcdfedd648dfffff0e4ff01fc7df9 +ff08fd46ebfdd9cb8ef8ccf9ff06fedf97fff7ff98f8ff09faefffe89e6e859fd75bf6ff0d56a8ff +febfffcdfedd648dfffff0e3ff01e8cff9ff0797c8febc69caf8fbf7ff04a6ffe7ff6cf5ff1fc5ae +7ffc54bfe767777665555567988899aa86455557aaaaababbbb969fffff0e3ff01e8cff9ff0797c8 +febc69caf8fbf7ff04a6ffe7ff6cf5ff1fc5ae7ffc54bfe767777665555567988899aa86455557aa +aaababbbb969fffff0e3ff01e8cff9ff0797c8febc69caf8fbf7ff04a6ffe7ff6cf5ff1fc5ae7ffc +54bfe767777665555567988899aa86455557aaaaababbbb969fffff0e2ff008ef9ff07f999aeae56 +e8f8fbf8ff05fd89bfbafb8ff5ff16a5ac9fffd536ce4cedeeeecb99aa9cddccbbbbaa99a98afeaa +05a98989fffff0e2ff008ef9ff07f999aeae56e8f8fbf8ff05fd89bfbafb8ff5ff16a5ac9fffd536 +ce4cedeeeecb99aa9cddccbbbbaa99a98afeaa05a98989fffff0e2ff008ef9ff07f999aeae56e8f8 +fbf8ff05fd89bfbafb8ff5ff16a5ac9fffd536ce4cedeeeecb99aa9cddccbbbbaa99a98afeaa05a9 +8989fffff0e2ff00edf8ff0796eaaf859ba7fcdff9ff05ebfcbf7ef6eff5ff079478affffe95344e +edff03d8fffff0e2ff00edf8ff0796eaaf859ba7fcdff9ff05ebfcbf7ef6eff5ff079478affffe95 +344eedff03d8fffff0e2ff00edf8ff0796eaaf859ba7fcdff9ff05ebfcbf7ef6eff5ff079478afff +fe95344eedff03d8fffff0d8ff07fdbb9fd85da6bfaff8ff03e9ec8f7cf4ff02fc75bffeff03d538 +99abfecc12bbabbabaaabcdeedcb98888999a9987afffff0d8ff07fdbb9fd85da6bfaff8ff03e9ec +8f7cf4ff02fc75bffeff03d53899abfecc12bbabbabaaabcdeedcb98888999a9987afffff0d8ff07 +fdbb9fd85da6bfaff8ff03e9ec8f7cf4ff02fc75bffeff03d53899abfecc12bbabbabaaabcdeedcb +98888999a9987afffff0d7ff06aad9ff96e86edcf8ff039dd7e8cff3ff00fefdff10fed787666556 +677788888999987667789bfecc01cdeefeff00f0d7ff06aad9ff96e86edcf8ff039dd7e8cff3ff00 +fefdff10fed787666556677788888999987667789bfecc01cdeefeff00f0d7ff06aad9ff96e86edc +f8ff039dd7e8cff3ff00fefdff10fed787666556677788888999987667789bfecc01cdeefeff00f0 +d8ff07fddbfd98e67e77faf9ff03f9cd7ebdd4ff00f0d8ff07fddbfd98e67e77faf9ff03f9cd7ebd +d4ff00f0d8ff07fddbfd98e67e77faf9ff03f9cd7ebdd4ff00f0d8ff08fbaffffecd8ba9adbffbff +04fe9bc7ebbfd4ff00f0d8ff08fbaffffecd8ba9adbffbff04fe9bc7ebbfd4ff00f0d8ff08fbafff +fecd8ba9adbffbff04fe9bc7ebbfd4ff00f0d8ff08bcdfffffefb7e88fbefcff04edcbee7eacd3ff +00f0d8ff08bcdfffffefb7e88fbefcff04edcbee7eacd3ff00f0d8ff08bcdfffffefb7e88fbefcff +04edcbee7eacd3ff00f0d9ff09feb9fffffeecd7e98ffafdff09f857dfe7e9efffeca99ed7ff00f0 +d9ff09feb9fffffeecd7e98ffafdff09f857dfe7e9efffeca99ed7ff00f0d9ff09feb9fffffeecd7 +e98ffafdff09f857dfe7e9efffeca99ed7ff00f0d9ff01faf8feff05c9e8e89efe9ffeff0ae76cff +8d8cfd98adfbb8ced8ff00f0d9ff01faf8feff05c9e8e89efe9ffeff0ae76cff8d8cfd98adfbb8ce +d8ff00f0d9ff01faf8feff05c9e8e89efe9ffeff0ae76cff8d8cfd98adfbb8ced8ff00f0d9ff0af9 +f8ffffdbe7ca9caeff8ffeff0b8a6ff9c8ce875effeeff8bdfd9ff00f0d9ff0af9f8ffffdbe7ca9c +aeff8ffeff0b8a6ff9c8ce875effeeff8bdfd9ff00f0d9ff0af9f8ffffdbe7ca9caeff8ffeff0b8a +6ff9c8ce875effeeff8bdfd9ff00f0d9fffff908ffeacf9e9e7eadfbbffeff0b6a7fc99cf7c746ca +47bfe8bfd9ff00f0d9fffff908ffeacf9e9e7eadfbbffeff0b6a7fc99cf7c746ca47bfe8bfd9ff00 +f0d9fffff908ffeacf9e9e7eadfbbffeff0b6a7fc99cf7c746ca47bfe8bfd9ff00f0d9ff09faebfd +bfeadf8e8f9ef9fdff0b6a8f89afe77444b8498ff7bfd9ff00f0d9ff09faebfdbfeadf8e8f9ef9fd +ff0b6a8f89afe77444b8498ff7bfd9ff00f0d9ff09faebfdbfeadf8e8f9ef9fdff0b6a8f89afe774 +44b8498ff7bfd9ff00f0d9ff09fdddfbfb9eff8b9f8fdbfdff0b5c8e68ff95433386447865afd9ff +00f0d9ff09fdddfbfb9eff8b9f8fdbfdff0b5c8e68ff95433386447865afd9ff00f0d9ff09fdddfb +fb9eff8b9f8fdbfdff0b5c8e68ff95433386447865afd9ff00f0d7ff17ce9effff9c8f9fbdfffffe +ff6f7b5eff643343453543688fd9ff00f0d7ff17ce9effff9c8f9fbdfffffeff6f7b5eff64334345 +3543688fd9ff00f0d7ff17ce9effff9c8f9fbdfffffeff6f7b5eff643343453543688fd9ff00f0d7 +ff17e9efffffab6cdb9efffffdff6f8b4fff64434437443345bfd9ff00f0d7ff17e9efffffab6cdb +9efffffdff6f8b4fff64434437443345bfd9ff00f0d7ff17e9efffffab6cdb9efffffdff6f8b4fff +64434437443345bfd9ff00f0d7ff00dbfeff12e89afabdfffffddf8bca7bff83436434433466d8ff +00f0d7ff00dbfeff12e89afabdfffffddf8bca7bff83436434433466d8ff00f0d7ff00dbfeff12e8 +9afabdfffffddf8bca7bff83436434433466d8ff00f0d7ff00befeff12f9b6cbeafeffffafb5fef9 +bfc359d834433598d8ff00f0d7ff00befeff12f9b6cbeafeffffafb5fef9bfc359d834433598d8ff +00f0d7ff00befeff12f9b6cbeafeffffafb5fef9bfc359d834433598d8ff00f0d2ff119c8ffbffef +ff8ee58fff99e548784433455ed8ff00f0d2ff119c8ffbffefff8ee58fff99e548784433455ed8ff +00f0d2ff119c8ffbffefff8ee58fff99e548784433455ed8ff00f0d2ff01fccffdff06b9fa8afffb +7743fe3301548ed8ff00f0d2ff01fccffdff06b9fa8afffb7743fe3301548ed8ff00f0d2ff01fccf +fdff06b9fa8afffb7743fe3301548ed8ff00f0d2ff00fafcff0cfa68858efffc87433333356549d9 +ff00f0d2ff00fafcff0cfa68858efffc87433333356549d9ff00f0d2ff00fafcff0cfa68858efffc +87433333356549d9ff00f0d2ff00ebfbff0cb99a769effffdca7568effe69adaff00f0d2ff00ebfb +ff0cb99a769effffdca7568effe69adaff00f0d2ff00ebfbff0cb99a769effffdca7568effe69ada +ff00f0d2ff00cffaff03feffc7effdff03efffb68adaff00f0d2ff00cffaff03feffc7effdff03ef +ffb68adaff00f0d2ff00cffaff03feffc7effdff03efffb68adaff00f0c8ff01fedffcff02fe645a +daff00f0c8ff01fedffcff02fe645adaff00f0c8ff01fedffcff02fe645adaff00f097ff00f097ff +00f097ff00f097ff00f097ff00f097ff00f097ff00f097ff00f097ff00f0 +currentdict /inputf undef +currentdict /picstr undef +currentdict /rpicstr undef +currentdict /gpicstr undef +currentdict /bpicstr undef +grestore +showpage +%%Trailer diff --git a/doc/gnu.xpm b/doc/gnu.xpm new file mode 100644 index 0000000..bc54934 --- /dev/null +++ b/doc/gnu.xpm @@ -0,0 +1,198 @@ +/* XPM */ +static char *noname[] = { +/* width height ncolors chars_per_pixel */ +"213 177 14 1", +/* colors */ +"` c #FFF", +"a c #DDD", +"b c #BBB", +"c c #999", +"d c #777", +"e c #555", +"f c #333", +"g c #EEE", +"h c #CCC", +"i c #AAA", +"j c #888", +"k c #666", +"l c #444", +"m c #222", +/* pixels */ +"`````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````", +"`````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````", +"``````````````````````````````````````````gaahiibaag`````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````", +"``````````````````````````````````````acjjdddldjjkleeekdjia``````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````", +"```````````````````````````````````abbicli`hbjkdbelldddkdelldh```````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````", +"`````````````````````````````````iibkcjellcaeaklcelfljllkekdeeejba````````````````````````````````````````````````````````````````````````````````````````````gha````````````````````````````````````````````````````", +"```````````````````````````````bcagjcldkleljcdaelillfcdllfedeeelffc`````````````````````````````````````````````````````````````````````````````````````acdjddjccjjjch```````````````````````````````````````````````", +"`````````````````````````````hch```jflleeeelkkcbljdlfliellldeeeeeflkh````````````````````````````````````````````````````````````````````````````````hjkch`ah`ic`gaiicjja````````````````````````````````````````````", +"````````````````````````````cb``aeigjlefleellelhdlblllldllllcllekkeelcg``````````g``````````````````````````````````````````````````````````````gjcddiabjjdldkleklllliggcc```````````````````````````````````````````", +"`````````````````````````ggjag`accdehilefelelllehldjllleellleellekllleejb```````dki```````````````````````````````````````````````````````````gjlljbiiekkelllllllefedcdg`hjb`````````````````````````````````````````", +"````````````````````````gdhg`cdhadkdejilelelelekdelbllelelellkleelkfjeehiiihaaidbai``````````````````````````````````````````abg`````````````addijkdellelllelllllljckllkg``hcg```````````````````````````````````````", +"```````````````````````gjgdejijlcghkeljjllllkdhjklkdcleklklllllleleeededg`hidjb``ig`````````````````````````````````````````akdei````````ggacdkkkkjllllflllflflllleekddjcji``big`````````````````````````````````````", +"``````````````````````hdcjjceeekeei`hklkklledg`adebeclljelleleellelclkdlgg`aagg`ai``````````````````````````````````````````cg`bklkklllllllllkkeejlllfflekflellfleeelfllech```gcg````````````````````````````````````", +"`````````````````````cihdckkjkleelldggiklejca``````aahkkceedkekjekkjllclhghbikkhjg``````````````````````````````````````````ij`g`ghbcjekddbkeeeljlllflfleflklfflekledjccccjg````ia```````````````````````````````````", +"````````````````````hd``g``beedeeelkeb`gddhh```ghhhbbiekjhca`gjig`bgajab`gg``acc`````````````````````````````````````````````edagg`jeelleleeeeekeflfffleflefflelflklllelllledc```ba``````````````````````````````````", +"```````````````````gc``aga``gdllelkecec``bg`gckdibbbhahbcdddjccciiihhgg```gbjca```````````````````````````````````````````````clkdcaccklleleeeekcikekklflefflllflllllllllllllekj``bg`````````````````````````````````", +"```````````````````c``heledb``cllelebadj``gcdig`````````````gaaahhbhhhhhhgag```````````````````````````````````````````````````gcklflkjcaeekkjkjjddejdldkekdelllllfffffllleedjch```ig````````````````````````````````", +"``````````````````caagikelllkcgjekekdg`hgbca```````````````````````````````````````````````````````````````````````````````````````aidelllebag````````hkea`gelllfffffffffffffllkg``gb````````````````````````````````", +"`````````````````jbhdeecbbjefleckdciic`gca`````````````````````````````````````````````````````````````````````````````````````````````````````````````gikjgakffffffffflllekdkelkda`i````````````````````````````````", +"```````````````adllkchbklkbabkflecgg``ajg`````````````````````````````````````````````````````````````````````````````````````````````````````````````````hdhaffffllllejjdelfflleda`hh```````````````````````````````", +"```````````````jckllllejjeledahlfkhg`bjg````````````````````````````````````````````````````````````````````````````````````````````````````````````````````jiblleffffffffflekdkkelagb```````````````````````````````", +"``````````````hj``gbdlllleellljcebg`bc```````````````````````````````````````````````````````````````````````````````````````````````````````````````````````bjhcelffffllllllledddkc`i```````````````````````````````", +"`````````````gdhbbhihabklllleekkk``bc`````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````bj`hlfffffffffllleeekjhi```````````````````````````````", +"````````````gdgeeelllekcidllleeja`aj```````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````id`befffllfffffledibbgbg``````````````````````````````", +"````````````cb`hchgidellekjjeeaijbjg````````````````````````````````````````gabbiiiibhg`````````````````````````````````````````````````````````````````````````cdgkfffffffledjjkeekcah``````````````````````````````", +"```````````gd````gg```aclleddkg``da`````````````````````````````````````gbjkddjcccjddjddjia`````````````````````hbhag````````````````````````````````````````````iieffflfflfflkca`````b``````````````````````````````", +"```````````ca```hbiiibhggbeekh``ib````````````````````````````````````gdkchgabbccjjiicibbijjh````````````````gijccjjjcia``````````````````````````````````````````ddflleeeleellllkdh``i``````````````````````````````", +"``````````gj``clllffllllki`bcg`hj````````````````````````````````````hkcijccibag`gghbijkkjiidjh````````````bcibicjjiba`hba````````````````````````````````````````hjdleeelllffflllej``b``````````````````````````````", +"``````````cahjekdjcicjdella```gd```````````````````````````````````adldia```````````````ghjddkkda```````gcdjjdcbhgabicjighb````````````````````````````````````````daiefffffffflllekg`b``````````````````````````````", +"``````````j`ccjjjddkeekdcddb``ia``````````````````````````````````iejg```````ah`g```hg``````gbjelc````acckjhg``bebgh```hjcg````````````````````````````````````````chjeffffffllffllkdchg`````````````````````````````", +"`````````iiallllllekjiijkedka`c``````````````````````````````````ijg`````g````chjjeagkdh``ghcb`ajljaaibcjg````gdeleld````gjc```````````````````````````````````````ac`kleiiklflkcklleghg`````````````````````````````", +"`````````kkkellekekellejaghcb`c`````````````````````````````````cb```````chjacciicljeckdggkdkkh`chkebgjjbg`ahijallldflcig``ajh``````````````````````````````````````dallffldcjlfljkjlgaa`````````````````````````````", +"````````bjjjiiijjddkeeeelhg``ab```````````````````````````````gjh`````hcbciiibkcbdlbkcejkjkeekebikadjkbdeecheakllcleiflkeaicgijg````````````````````````````````````djkllfflflkjefleb`bh`````````````````````````````", +"````````kg`aabcjkeeellleekc``ig```````````````````````````````jg``````jjdbjijhedhkkjjdldejdeldklkeeijkcgkllekkaeljifclffffffebada```````````````````````````````````cillfffflllldcllb`bi`````````````````````````````", +"```````gd``hellllleeeeekkkka`j```````````````````````````````jh`bgijkgieeakcdgekaedeielklejelkeelfeeiklbilellfcbflhlelfflffffleidb``````````````````````````````````caelleeelffllebkeabi`````````````````````````````", +"```````bigcellllllllllleldgggc``````````````````````````````chaacbhkebaeeakdd`ekgedlhlelleckleellflekjeeaeeekeladfjkleffllefffflbcc`````````````````````````````````ibllllfleelfleljjeic`````````````````````````````", +"```````jacllledjbcbhbidefekgch`````````````````````````````ci``dkj`elcgeeijed`eealkfblllleceldklelleekeeibejljllifdjlklfkfdllfffebbj````````````````````````````````biillflllfleelllljgc`````````````````````````````", +"```````d`becbbijdelllllejag`j`````````````````````````````bhgc`iek`klj`keccek`eealdlclllllikedjlekfleeclebkeclblelkhfelfkfjelfffflcbc```````````````````````````````ibilfffleefffllflkgc`````````````````````````````", +"```````d``bjelflkdjjdjdekchgc````````````````````````````gj``ddkee`kle`dekilkgeeildldllellbekkildeleelillkjlkldcjklilelfefdelflflflcch``````````````````````````````jadklffffekjkflllkai`````````````````````````````", +"```````j``jlejcjdkeeekdkkihac```````````````````````````gdggccbllegdelgclecle`elhejlkelellbeddhlkleleljekklejieaehfjklllkelelflflflljkg`````````````````````````````d`jihdffffflddlllk`ig````````````````````````````", +"```````j`gedkellleekkkekdihgc```````````````````````````jabbkicellajelaileilk`klaejleelkllhedkhljejeelkeedjj`gjbjlldjllelklllleflflllkda```````````````````````````gjgeellfffffleedeelhba````````````````````````````", +"```````i`hedeeekkkkeekellljaj``````````````````````````jh``kljcdfehjelbheehekgelaejlleljllhedjaljeikdeelffildh`cklleblleldfellklllfllleka``````````````````````````iigedfffffffffeejelgba````````````````````````````", +"```````a`cilledjiabcjelleb``j`````````````````````````ci```kljjiflhceliaelakkgllalcllllkeebkdcalieheckkkhchlleb`bflfbeleeefkllkellfllllekg`````````````````````````jg`aelfffffffffeeilhbg````````````````````````````", +"`````````kdba`gikelkcjjkeeh`j````````````````````````iia``eeljdhflhcelcallhdkhllblielleelkcdebhliealieea`ahffflelflfddfeeeflllekllflllfllk`````````````````````````d``ilfleffffffffldhgbg````````````````````````````", +"```````h`c`bjelekjdeelffleh`j```````````````````````ij`bcallljkgflidelchleakkileclillllllkkjehildkcljlligegeflkeeelfkjflelfllleelelellffllkg```````````````````````d`aeffflkfflfffflea`bg````````````````````````````", +"```````b`gieejdellllkcdked``j``````````````````````ic``geglllkk`leideejblegedkfkclbllelledlakhcedkeekfldglabdldhiellkjflllflleellellelfefllkg`````````````````````akelflffflklfllffljc`b`````````````````````````````", +"```````iggjjdelllecbjelljh`ach````````````````````ci````ebelekegeljkeldjldalklljkkjllefeledilcec`gcikellaei``blljkjkkjflllflllkllellklfdlllkjg````````````````````cejblffffffklfflfld``i`````````````````````````````", +"```````iahcjelecaiefldjledjiaj```````````````````jb``bb`djllekk`eljeeleeljjllllkljefelfklkkck`gahahjlilkeeeg``ielfeleblllllflldllklleeldkleiadih``````````````````dlaelfffffffelfflfi``b`````````````````````````````", +"```````bcbiekhgceflddelllecj`d`````````````````gdh```he`ckeleek`keeleellejlkideddieekeddb`dddjeeeldidbkjfjfkihggkfleehellellllkledlfkelljledgaci`````````````````bjkkfffffffffflfflfk``i`````````````````````````````", +"```````gjgaigcllllellkellebagib```````````````gda``ghgegbeeelkk`eeeldli`accajliiiceledjjjdlleigahlb`jididkkffleeffebdbjljdllklldicllklllelllj``cc```````````````gdgjflfflfflfffflfflfi`b`````````````````````````````", +"````````dgghekbklflkellleekkhgc``````````````gda````dhdbieekeekkljdjjlckflkkeekddjjjdkkkdjcbg````keacfejhejeleeceliajhdflleefleekklllllfflellh`gkc``````````````dballfflfffflffffffla`bg`````````````````````````````", +"````````dhclddllleelllelllebg`jh````````````gja`````ijjdblkklljjkghdlejig```````````````gg```````gljghefecljlfdcej`cekkibjdabg`ghiickdkdeedledjagkc````````````jdbkfffffffffffffffflg`c``````````````````````````````", +"````````icdbbkllllllejellkllc``jb``````````gdg````ighdbkhlkelebadedch`````````````````````````````hedahkffefklelfiejg`````bdc````````ahbjkeedleeh`cdh``aag``gieeklclffflffffffflffli`ai``````````````````````````````", +"````````hcghklllllljdelldefle```jc````````hjg```gikbhkbljlcecjkkig`````````````````````````````````gdlejjellffflelc`````````bkg``````````abkjeeelb`hkellekbjldgdgkfflffflffffffflfk``cg``````````````````````````````", +"````````gdikllkeleceklljeflklh```jja````acc`````hckcgececedlkig```````````````````g`````````````````gilelejcfffkjla````ag````hk`````````````ieeekfeh`ghjkkjig``dklelmfffflfffffffflb`c```````````````````````````````", +"`````````dakejelkjedlldklldlleg```bcjjjjca``````jcedgekllecg`````````````````gicekj``````````````````ggabjleffcadeb```hed`````bd`````````````ggkllffjgba`bccgihefffeefffffffffffflkdhh```````````````````````````````", +"`````````ibdielkdlkeedkllddellbch``````````aghaieaekglfda````````````````ghiiiaifeg`````````````ggg```ggagblfkgdljd``cijdg`````ci`````````````haeelffllljelfllfffffflffflffffffllldic````````````````````````````````", +"`````````hcgclkklkeedkllejldfleehg`````````ccbjdeadejfj`````````````````hllkkeeffc`````````````gdlleg````g`ceebfflkghjklkg````g`ka````````````abcllfffffffffflfffffffffffffffffflj`gc````````````````````````````````", +"``````````d`cdkleekkklledlklfleedd`aa`````gilildeajlfl`````````````````illlflfffk```````````````ajllig``g```aeefffj`clffi`````h`bd`````````````baelfflfffffffflffllfffffflffffllfa`ia````````````````````````````````", +"``````````jagbledjkklfdkeedffelflecbkd````icldejlbjfed````````````````glfffllffkg````````````````gilkh``g``hkllfejagklfla````gb``k`````````````gccllfffffffffffffffffffffflmffflfhgi`````````````````````````````````", +"``````````bb`bkkckclleeeljlflkfleeljke`igabkleeclikfcg````````````````cflfflffj```````````adeeja```iiih````blfkjia`gkffja`````h``dg`````````````hjllffffffffflflfffffffflfffffffegcg`````````````````````````````````", +"``````````gc`beakbellkeleellleflellkje`ddgdklekdlele`````````````````alffeffdh``````````beffeklk`````hjbb``gijig``gadffiibiiaga``jg``````````````jelfffffffffffflffffffffffffllldbb``````````````````````````````````", +"```````````jheajckeldellklllllflleeeie`dehkkelkklljc`````````````````kffelfjb``````````clkig``dlg`````aej````g`````iclfkja`hjhh``d```````````````bllfffffffffffffffffffffffflldeic```````````````````````````````````", +"```````````ikagjdekedlekllelelllfkelbk`ekikdelelfba`````````````````blfkdlkcb````````hkeh`````jlc`````bkc``````````jjffedh`ggb``gk```````````````akelfffffffflllffflffffffffefiahh```````````````````````````````````", +"```````````gj``idekjekeellklkfllleeeiegekidjleefe``````````````````hefd`ai`e````````ifj```````allg`````iig`````````cjfflb```````bd```````````````bklfflfffffffllffflfffffflfekkgc````````````````````````````````````", +"````````````cg`deckjeledleellfelleeedebleidkellfb`````````````````hedi````hk````````ed`````````cfa`````hejg````````iefffcg`g````jb````````````````jlfflfffffffllffffflffflffb`djh````````````````````````````````````", +"````````````hb`bedcelekjljllllllleeeeljeeckdelfl`````````````````acbi`````ki```````hea```hbcjdkkfc`````gelb````````hefffekddcb``ja`````````````````hllfeffffffllllffffllfklk`gji`````````````````````````````````````", +"`````````````j`gicclejceejlefllllcekledleckkllfd``````````````````gjg````gla```````ifj`beffflffffeh`````hlb````````gcfffffffffecdb``````````````````dlfeflffffflllfflfefeeec`gj``````````````````````````````````````", +"`````````````bi```jkdjhlklllflllehekleellbkkkllb``````````````````gg`````ik````````aflefffflfffjclb``````kb`````````alfellekjdellc``````````````````hlflfffffffllllelfefdhb`ajg``````````````````````````````````````", +"``````````````jg```khjcldlllllllkbekleeeebkdellg`````````````````````````di````````gefffflfffffjbcd``````gia`````````klkleleeeddllg``````````````````effflfffflfffleffek```bkg```````````````````````````````````````", +"``````````````gjg``jgidelldflleljjkelleeebekklj``````````````````````````lg`````````effejlffleffjida``````dc`````````glkcffflfedddh``````````````````kllleffffffllkkkecg`idda````````````````````````````````````````", +"```````````````aca`hgbkeeceffjllieceelekeieeelg`````````````````````````gk`````````glebahlfflllfkgag``````kd`````````gdldfflffldjcg``````````````````blllkfffflllejgkkbdejg``````````````````````````````````````````", +"`````````````````jg`ggkkcilfljlejeblkedklclefh``````````````````````````ci``````````lh``affffflfeaig`````gea````````gghefffffffkb````````````````````akcbklfflejdlbakfkb`````````````````````````````````````````````", +"`````````````````gc```icbkflieldkjiebeeeecelc```````````````````````````dg``````````jj`g`efffffldde``````ji``````````ggblfffffekdkj```````````````````hc`bjdah`gajdkia```````````````````````````````````````````````", +"``````````````````hb``bigjkeclddeakkjleldkee````````````````````````````k```````````gddhahlffflkiek`````````````````````jfffffddjle````````````````````ekkjjddddjba````````````g``a`a````````g```````````````````````", +"```````````````````aigg```aieeblibejkeelcelb```````````````````````````hlg`````````ggailc`ajjcjcbec`````````````````````alleekchclh````````````````````bagagg```````````ag``gejb``kgk````gbagecdbabg`````````````````", +"`````````````````````iba```hbblcgkb`dkeljel````````````````````````````ceg`````````````akdiibdeeej```````````````````````clekkcjeca`````````````````````j```````````````ilh``dfj`gedc`hb`gdkabelcbkeddi``````````````", +"```````````````````````hih`hcliidc`akjeeedj````````````````````````````ecg````````````gg`acjcibag`````````````````````````clddedai``````````````````````ca```````````````bea``ek`alegblja`ieeajlcblkbkg``````````````", +"`````````````````````````gbibg`gh``hagjhaea```````````````````````````gkig```````````````gg```gg```````````````````````````kla```h``````````````````````gj````````````````akg`ajggeaalfkb``jlkaljhlhkg```````````````", +"````````````````````````````bbbbhg``````ge````````````````````````````cjhh``````````````````g`a````````````````````````````aej```cd``````````````````````j`````````````````ik`````ghecfejjdkllklkdeejig``````````````", +"````````````````````````````````ghbhhg``kc````````````````````````````eh`ihg````````````````````````````````````````````````ilh``bej`````````````````````bh`````````````hiiceddkkkklkdjjjcbag``c`````gb``````````````", +"`````````````````````````````````````ahclg```````````````````````````afg`bha`````````````````````````````````````````````````dd``glka`````````````````````c`````````````dbhhjcbhg``````````````i``````b``````````````", +"```````````````````````````````````````ck````````````````````````````dfh`gaa`````````````````````````````````````````````````bla``idjg````````````````````ai````````````j```h``````````````````i`````gb``````````````", +"```````````````````````````````````````lh```````````````````````````aelg```g``````````````````````````````````````````````````cj```eadgg```````````````````cg```````````c``gi`````````gaabbicccdibdciab``````````````", +"``````````````````````````````````````hk````````````````````````````dceka`````````````````````````````````````````````````````geg``djgda```````````````````gc``````````adjdkejicjddkelledjedckijaaeeich``````````````", +"``````````````````````````````````````di```````````````````````````he`bd```````````````````````````````````````````````````````ek``ce`gch```````````````````ab`````````gcidkjlbbbckjadlb``dj`c`ga`cda````````````````", +"`````````````````````````````````````glg```````````````````````````dj`ce````````````````````````````````ga`````````````````````aea`ilg``iig``````````````````ba```````````cbae```gki`cli``dd`c``g`gda````````````````", +"`````````````````````````````````````bk```````````````````````````hlg`bkjg```````````````````````````gggblig``gh````````````````jj`hli```gjcg`````````````````ig``````````jbbe````ki`ilc``dd`c`````da````````````````", +"`````````````````````````````````````di``````````````````````````gec``ajegg`````````````````````````ckkdjcecaaaa````````````````gkbaec`````accig```````````````cjg````````kbhe````ei`ilj``jk`j``g``da````````````````", +"`````````````````````````````````````lg``````````````````````````dd````hkkj```````````````````````````````hjkkdjdjjjjb```````````bkhec````````acjbg`````````````gjg```````diak```gei`blc``de`j`````da````````````````", +"````````````````````````````````````he``````````````````````````ikg`````dela````````````````````````````ghbhhhaaggg```````````````kjei```````````bdjiag```````gbiig```````dbak````lb`bli``de`j`````da````````````````", +"````````````````````````````````````jc````````````````````````gdk````````bkb`````````````````````````akkdjddkeleja````````````````ilkh``````````````hcjjccccjcbg``````````dbhd````ei`hec``dk`j`````ka````````````````", +"````````````````````````````````````eg```````````````````````geea`````````ib`````````````````````````ei````````gbjejg`````````````aelg````````````````````````````````````jbhd```gli`hei``dd`j`````kg````````````````", +"```````````````````````````````````be```````````````````````hlla``````````g`````````````````````````cj````````````adlb`````````````hlbg```````````````````````````````````dbbd```gli`ali``jd`j`````kg````````````````", +"```````````````````````````````````kb``````````````````````allh````````````````````````````````````hla``````````````bejg````````````dla`gahjji````````````````````````````dbbd```glc`glb``dj`d`````kg````````````````", +"``````````````````````````````````be``````````````````````beeh`````````````````````````````````````kh`bklljg``````````iei```````````ckelleedddka``````````````````````````dbbd```glc`glh``dj`j`````kg````````````````", +"`````````````````````````````````geh```````````````````gikejg`````````````````````````````````````gk`jfeddeea``````````akkb````````````g``````aeg`````````````````````````dbij```glc`glh``jj`d`````kg````````````````", +"`````````````````````````````````ec`````````````````gbdledi```````````````````````````````````````ijifd````hg````````````ieda``````````````````ij`````````````````````````dbbj```ali`gla``jc`d`````kg````````````````", +"````````````````````````````````jk````````````ghijdkkdjhha````````````````````````````````````````daefb```````````````````gdeb``````````````````e`````````````````````````dhbj```ali`glh``ih`j`````k`````````````````", +"```````````````````````````````ilg`````````bdelkjbg``gcabcg```````````````````````````````````````kajlg`````````````````````jei`````````````````ka````````````````````````khbj```hlb`bla``jh`d`````e`````````````````", +"``````````````````````````````ila````````cedccb````````ijib```````````````````````````````````````kahe````hdledcg````````````i``````````````````jb````````````````````````khic```hlb`blh``jh`d`````e`````````````````", +"`````````````````````````````ilh````````jlg`gc`````````gjdb```````````````````````````````````````bg`a````deahikeg``````````````````````````````ic````````````````````````kaic```hlb`blh``jb`d`````e`````````````````", +"````````````````````````````dfb````````alb``ca``````````hlg```````````````````````````````````````ah`````glfklfekd``````````````````````````````ic````````````````````````khcc```blb`blh``jh`d`````e`````````````````", +"```````````````````````````cfc`````````kk```d````````````k``````````````````````````````hg```````````````glfffffekcia`````````````````````````abdh````````````````````````eacc```bliiefc``dh`d`````e`````````````````", +"```````````````````````````ed`````````blb```d````````````db```````````````````````````gag````````````````gkffffffbelkg```````````````````````gjde`````````````````````````kaic```bldcahkb`kh`d`````e`````````````````", +"```````````````````````````lg``gikcghjlc```gj````````````je````````````````````````gjkka``````````````````gkfffflaeefi```````````````````````dedd`````````````````````````eabj```blk``ghegkh`d`````e`````````````````", +"```````````````````````````ddjkfeddflda````bc````````````ceb``````````````````````akig``````````````````````bjig``eblk``````````````````````jflld`````````````````````````kghj```bli```cflllcd````ge`````````````````", +"```````````````````````````gccib```ga``````ib````````````jhc``````````````````````ea``````````````````````````````khbfg````````````````````jlfflh`````````````````````````egbc```bfj``glkdleid```gbk`````````````````", +"```````````````````````````````````````````ca````````````j`j``````````````````````````````big`````````````````````ehgli``````````````````gdlfffd``````````````````````````egbj```ile``ge``kh`dgiaaik`````````````````", +"```````````````````````````````````````````ja````````````j`j````````````````````````````helkli`````g`````````````gk``ed````````````````gbklffleg``````````````````````````lgbj```cllh`jj``eb`difdbik`````````````````", +"```````````````````````````````````````````ch````````````cgd````````````````````````````iga`geb``ag``````````````````cc`````````````ggadlffflkb```````````````````````````labc```jlka`ec``kb`difehid`````````````````", +"```````````````````````````````````````````ch````````````ihja````````````````````````````````hla`j```````````````````````````````````hklffffdj````````````````````````````lhic```kfcggjli`eb`djflbcd`````````````````", +"```````````````````````````````````````````ib`````````````ijeg````````````````````````````````dcgj`````````````````````````````````gjefffffekg````````````````````````````laieejelledecieieb`dhkcbcd`````````````````", +"```````````````````````````````````````````bc```````````````cd````````````````````````````````akii````````````````````````````````gdlflffflka`````````````````````````````laijeggabijkellllb`dga`bcd`````````````````", +"```````````````````````````````````````````aj```````````````gkh````````````````````````````````cki```````````````````````````````gdlflffflkg``````````````````````````````eajkkjihg``````geb`dg``hcd`````````````````", +"```````````````````````````````````````````gd````````````````jc````````````````````````````````gej```````````````````````````ggagdllllfflka```````````````````````````````dadlklekeeekkkkjeb`d```acj`````````````````", +"````````````````````````````````````````````d```````````````gbj`````````````````````````````````be``````````````````````````````hjjcdeelecg```````````````````````````````khjeeeb`````ghejeb`d```aij`````````````````", +"````````````````````````````````````````````d```````````````baj``````````````````````````````````kh`````````````````````````````gg``gabi`ajg```ggga``````````````````````gkckecd`g``````aeeb`k```gic`````````````````", +"````````````````````````````````````````````dg``````````````abch`````````````````````````````````bj````````````````````````````````````````bkdkekdklkkka```````````````ajllflkejibhgggghbkli`k```gij`````````````````", +"````````````````````````````````````````````cb```````````````chj``````````````````````````````````dg````````````````````````````````````````hh```gbg`gdi```````````````jkiicjcccijdkllllfkli`k```gic`````````````````", +"````````````````````````````````````````````bi```````````````gceih````````````````````````````````aj`````````````````````````````````````````ba`cdhhgggkg`````````````bjkellkkeekdeclkkkllligk```aci`````````````````", +"````````````````````````````````````````````aj`````````````````bhbjjg``````````````````````````````aj````````````````````````````````````````gcgblfjkg`hd``````````````gbdklcedihbedekellklcae```aji`````````````````", +"`````````````````````````````````````````````d`````````````````hb``ajjg`````````````````````````````hc```````````````````````````````````````adgaelfcg``ji````````````````ge`dig`gkghabaahejak```hji`````````````````", +"`````````````````````````````````````````````d``````````````````biih`adh`````````````````````````````hc```````````````````````````````g``gbiikfjgjeld```aea```````````````ge`kiaghejaggbbiedgk```bji`````````````````", +"`````````````````````````````````````````````ih```````````````````gbch`da`````````````````````````````jkh`````````````````````hckkeeeekdcjkdlielbieeeh```hka`````````````gbebdkeellleekcidfj`k```ijjhhhha````````````", +"`````````````````````````````````````````````ac``````````````````````ibjki````````````````````````````gdlcg``ghbhgg```ggacckelfflllllffffflbagbfkilelddcbghkjg``````````bkllllllllllelllekligk```ajeeeelleka`````````", +"``````````````````````````````````````````````k``````````````````````gccgd``````````````````````````````ileeefflkchahabklfffffffffffffffflc````dflfelkcdkkddlkjjjcjjccccklllleeeeeleeeeeleli`k````jklellllljci```````", +"``````````````````````````````````````````````ja`````````````````````cgj`j```````````````````````````````hllebahabcdelffffffffffflllffllfj`````aleejllkdjba`aihgbiibibibijcccccccccccccjddeh`eg```djbbhbiiiibdd``````", +"``````````````````````````````````````````````aj`````````````````````jacih````````````````````````````````gefllllflfffffffffllfflekkeelfd``````glkkjedghifdbgjdjjdkdjjjjjjddjdccccjiiibbbiebheg```djccjkkkejjkc``````", +"```````````````````````````````````````````````d`````````````````````cjgjg`````````````````````````````````hdlffffflkjjjjdibhbiig`g`agaci```````ljjkkk`gafldhlcaahbbiibbbideilkchjehhhahhbdabeh``gdh```jbak``ch``````", +"```````````````````````````````````````````````d`````````````````````dj`j`````````````````````````````````````gahaaag``````````````````aj```````edbejea`glldhlb```````````jkglcg`id```````jggeh``ada```jhgk``ca``````", +"```````````````````````````````````````````````ja````````````````````djhi``````````````````````````````````````````h```````````````````gd``````gejhkclc`geecbla```````````id`lj`gcc```````j``ea``gka```chgk``ca``````", +"```````````````````````````````````````````````bi````````````````````ckhi``````````````````````````````````````````````````````````````bj``````gejajcee``kehbk````````````ckgej``jj``````adggea```ka```jhad``cg``````", +"````````````````````````````````````````````````d`````````````````````dcj``````````````````````````````````````````````````````````````ka``````aejgddkeg`kkgcd````````````ck`ed``cj``````ad``eg```ka```jaaj``jg``````", +"````````````````````````````````````````````````bi`````````````````````kkh````````````````````````````````````````````````````````````hk```````akcgkkjebgkk`jj````````````ck`ec``cc``````gj`gk````eg```jghc``d```````", +"`````````````````````````````````````````````````d`````````````````````gjd```a```````````````````````````````````````````````````````gda```````hei`kdcfjakd`ki````````````ieaec``jc```````c`gd````eg```j`bi``d```````", +"`````````````````````````````````````````````````ch``````````````````````bb``d`````````````````````````````````````````````````````ajjg````````behgkdcfeadjgeg````````````cehlc``jc```````c`gd````eg```j`ib``k```````", +"`````````````````````````````````````````````````aj```````````````````````iggj```````````````````````````````````````````````g`gbjjig``````````blghjicllbdiae`````````````ckhlc``di```````c`gd````e````j`ca``d```````", +"``````````````````````````````````````````````````dg```````````````````````ihc``a`````````````````````````````````abckdkkeeeedjjh``````````````blgbjakdejdhcd`````````````jkalc`gdi```````c`gd````k````j`jg`gk```````", +"``````````````````````````````````````````````````bj```````````````````````ihc``a```````````````````````````````bklffffflffflg`````````````````ce`iigkiekkadc`````````````jkalc`gki``````gj`gj````k````j`j``ae```````", +"```````````````````````````````````````````````````cb`````````````````````hbbc`gj````````````````````````````gclffffffffffffd``````````````````jk`ji`dakeeaea`````````````jkali``ei``````gd`gj````d````d`d``be```````", +"````````````````````````````````````````````````````dg````````````````````iahc`ia```````````````````````````bellffffflffflfla``````````````````dk`db`cdkekge``````````````ckgfb``lh```````c`gj````d```gj`d``hj```````", +"````````````````````````````````````````````````````ac````````````````````higd`j`g``````````````````````````jffffffffffflffc```````````````````kj`ka`hecldhe``````````````iegfh``liiicdjccj`aj```hlc``gj`d``hb```````", +"`````````````````````````````````````````````````````ih````````````````````dgjhd````````````````````````````chkkekeelkcagkfi```````````````````ec`k``glbljhlkkkdddkkdjddkkekalh``lcbbbiccdj`hd```gelkabj`d``hi```````", +"``````````````````````````````````````````````````````jg```````````````````gjcdd```h``````````````````````````hejgdiach`gjklh`````````````````gec`k``gddkchkggggaaagaagg``heglh`ala``````bc`ad````ihkldjgj``hi```````", +"``````````````````````````````````````````````````````gdg````````````````````ilea``h```abg`a```ig``````````````dhak``hb``b`jk`````````````````bkcgk```alkbalcg````````````hk`fh`glg``````hh`gc```gc``hkdac``bb```````", +"```````````````````````````````````````````````````````gdh```````````````````gdli``h`h`gjhg```bk```````````````icijg`gc````ala````````````````bkhad````eeaijdda```````````bkala`alg``````aa``c```gc```ichi``ia```````", +"`````````````````````````````````````````````````````````cb``````````````````gclk``b`b`bhgb```eh```````````````gjgji`gc`ha``dk````````````````jegcc````jegeiahkcg`````````aklfeeel```````gb``j```gj```jiibg`i````````", +"``````````````````````````````````````````````````````````ic```````````````````cla`b`hgja`c``bii````````````````a`jicbb`aj``bd````````````````aekeh````jkakejggdlc``````````ghbihg```````gj`ge```gc```kkekjckh```````", +"```````````````````````````````````````````````````````````hda`````````````````alkgb`aachbjg`jhh`````````````````ga`cd```d``cj```````````````````ig```gjcgkgjec`adeb``````````````````````ekij```gb```ha`gaaklja`````", +"````````````````````````````````````````````````````````````gjh`````````````````cdhj`gbhkchi`j`b````````````````````ik``gd``kh````````````````````````heigd``helb`gdkddddkkeeeeekdcjjjcciijkleeeediiiiibibbbbckc`````", +"``````````````````````````````````````````````````````````````jg`````````````````cccigigekgj`j`b```````````````````ajcb`bi`bj`````````````````````````ieihc```aefkhglhgagggghbcciichaahhbbbbiiccicjiiiiiiiicjcjc`````", +"``````````````````````````````````````````````````````````````ga``````````````````ckgii`jecbid`ha`````````````````gb`hb`dg`kg`````````````````````````cldji````gcefllg````````````````````````````````````````aj`````", +"```````````````````````````````````````````````````````````````````````````````````abbc`ajeaikb`i```````````````````gcghj`dh```````````````````````````hdeb```````aefjccibhhhhhhbbibbibiiibhaggahbcjjjjccciccjdi`````", +"````````````````````````````````````````````````````````````````````````````````````iiac``ckgjkgah``````````````````caadgjh``````````````````````````````g`````````gadjdkkkeekkdddjjjjjccccjdkkddjcbhhhhhhhagg```````", +"```````````````````````````````````````````````````````````````````````````````````aab`acjgkdgdd`i`````````````````chadgba```````````````````````````````````````````````````````````````````````````````````````````", +"```````````````````````````````````````````````````````````````````````````````````bi````ghajbiciab``````````````gcbhdgbb````````````````````````````````````````````````````````````````````````````````````````````", +"``````````````````````````````````````````````````````````````````````````````````bha`````g`bdgjj`bg``````````gahbggdgih`````````````````````````````````````````````````````````````````````````````````````````````", +"`````````````````````````````````````````````````````````````````````````````````gbc`````gghadgcj``i`````````jeda`gdgcg```ghiccg`````````````````````````````````````````````````````````````````````````````````````", +"`````````````````````````````````````````````````````````````````````````````````i`j``````hcgjgjcg`gc```````gdkh``jajh`acjia`bbjhg```````````````````````````````````````````````````````````````````````````````````", +"`````````````````````````````````````````````````````````````````````````````````c`j````abgdhichig``j```````jik``chjhgjdeg``gg``jba``````````````````````````````````````````````````````````````````````````````````", +"`````````````````````````````````````````````````````````````````````````````````c`c``gih`cgcgdgia`bb```````kid`hcch`dhdlkhildb`gjb``````````````````````````````````````````````````````````````````````````````````", +"`````````````````````````````````````````````````````````````````````````````````igb`ab`gia`jgj`cg`c````````kij`jci`gddlllbjlcj``db``````````````````````````````````````````````````````````````````````````````````", +"`````````````````````````````````````````````````````````````````````````````````aaa`b`bcg``jbc`j`ab````````ehjgkj``celfffjklldjkei``````````````````````````````````````````````````````````````````````````````````", +"````````````````````````````````````````````````````````````````````````````````````hgcg````chj`c`ba`````g``k`dbeg``klfflflefelfkjj``````````````````````````````````````````````````````````````````````````````````", +"````````````````````````````````````````````````````````````````````````````````````gcg`````ibkhabcg`````a``k`jbl```kllfllfdllffleb``````````````````````````````````````````````````````````````````````````````````", +"````````````````````````````````````````````````````````````````````````````````````ab``````gjci`iba`````aa`jbhidb``jflfklfllfflkk```````````````````````````````````````````````````````````````````````````````````", +"````````````````````````````````````````````````````````````````````````````````````bg```````cbkhbgi`g````i`be`g`cb`hfecajfllffecj```````````````````````````````````````````````````````````````````````````````````", +"``````````````````````````````````````````````````````````````````````````````````````````````chj``b``g```jggej```ccgeljdjllffleeg```````````````````````````````````````````````````````````````````````````````````", +"```````````````````````````````````````````````````````````````````````````````````````````````hh`````````bc`iji```bddlfffffffeljg```````````````````````````````````````````````````````````````````````````````````", +"```````````````````````````````````````````````````````````````````````````````````````````````i```````````ikjjejg```hjdlffffffekelc`````````````````````````````````````````````````````````````````````````````````", +"``````````````````````````````````````````````````````````````````````````````````````````````gb````````````bccidkcg````ahidekjg``gkci```````````````````````````````````````````````````````````````````````````````", +"``````````````````````````````````````````````````````````````````````````````````````````````h````````````````g``hdg`````````g```bkji```````````````````````````````````````````````````````````````````````````````", +"```````````````````````````````````````````````````````````````````````````````````````````````````````````````````ga````````````gklei```````````````````````````````````````````````````````````````````````````````", +"`````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````", +"`````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````", +"`````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````" +}; diff --git a/doc/grnexmpl.g b/doc/grnexmpl.g new file mode 100644 index 0000000..ba1a1b8 --- /dev/null +++ b/doc/grnexmpl.g @@ -0,0 +1,3250 @@ +sungremlinfile +0 320.00 240.00 +ARC +320.00 240.00 +320.00 416.00 +320.00 416.00 +320.00 64.00 +496.00 240.00 +144.00 240.00 +* +4 0 +0 +CURVE BSPLINE +764.00 288.00 +776.00 304.00 +764.00 320.00 +* +3 0 +0 +CURVE BSPLINE +768.00 288.00 +780.00 304.00 +768.00 320.00 +* +3 0 +0 +CURVE BSPLINE +768.00 320.00 +788.00 320.00 +800.00 304.00 +* +3 0 +0 +CURVE BSPLINE +768.00 288.00 +788.00 288.00 +800.00 304.00 +* +3 0 +0 +ARC +192.00 268.00 +192.00 267.00 +192.00 269.00 +192.00 267.00 +193.00 268.00 +191.00 268.00 +* +3 0 +0 +ARC +192.00 212.00 +192.00 211.00 +192.00 213.00 +192.00 211.00 +193.00 212.00 +191.00 212.00 +* +3 0 +0 +CENTRIGHT +476.00 32.00 +430.00 28.00 +453.00 28.00 +476.00 28.00 +* +1 1 +10 $DP sub 2$ +CENTRIGHT +476.00 224.00 +430.00 220.00 +453.00 220.00 +476.00 220.00 +* +1 1 +10 $DP sub 2$ +CENTRIGHT +476.00 256.00 +430.00 252.00 +453.00 252.00 +476.00 252.00 +* +1 1 +10 $DP sub 2$ +CENTRIGHT +476.00 448.00 +430.00 444.00 +453.00 444.00 +476.00 444.00 +* +1 1 +10 $DP sub 2$ +VECTOR +604.00 344.00 +612.00 344.00 +612.00 364.00 +620.00 364.00 +* +6 0 +0 +ARC +416.00 320.00 +416.00 319.00 +416.00 321.00 +416.00 319.00 +417.00 320.00 +415.00 320.00 +* +3 0 +0 +CENTLEFT +596.00 336.00 +596.00 332.00 +604.00 332.00 +613.00 332.00 +* +1 1 +3 $-$ +CENTLEFT +596.00 368.00 +596.00 364.00 +604.00 364.00 +612.00 364.00 +* +1 1 +3 $+$ +POLYGON +592.00 320.00 +592.00 384.00 +656.00 352.00 +592.00 320.00 +* +3 1 +0 +ARC +392.00 390.00 +392.00 392.00 +392.00 392.00 +392.00 388.00 +390.00 390.00 +394.00 390.00 +* +3 0 +0 +VECTOR +396.00 388.00 +384.00 384.00 +* +3 0 +0 +ARC +392.00 378.00 +392.00 380.00 +392.00 380.00 +392.00 376.00 +390.00 378.00 +394.00 378.00 +* +3 0 +0 +ARC +312.00 326.00 +312.00 328.00 +312.00 328.00 +312.00 324.00 +314.00 326.00 +310.00 326.00 +* +3 0 +0 +CENTRIGHT +276.00 352.00 +243.00 348.00 +259.00 348.00 +276.00 348.00 +* +1 1 +7 $vv B2$ +POLYGON +280.00 356.00 +280.00 348.00 +284.00 348.00 +288.00 352.00 +284.00 356.00 +* +3 21 +0 +VECTOR +308.00 324.00 +320.00 320.00 +* +3 0 +0 +ARC +312.00 314.00 +312.00 316.00 +312.00 316.00 +312.00 312.00 +314.00 314.00 +310.00 314.00 +* +3 0 +0 +CENTLEFT +292.00 212.00 +292.00 208.00 +300.00 208.00 +308.00 208.00 +* +1 1 +3 $+$ +CENTLEFT +292.00 268.00 +292.00 264.00 +300.00 264.00 +309.00 264.00 +* +1 1 +3 $-$ +POLYGON +288.00 192.00 +288.00 288.00 +384.00 240.00 +288.00 192.00 +* +3 1 +0 +ARC +256.00 268.00 +256.00 267.00 +256.00 269.00 +256.00 267.00 +257.00 268.00 +255.00 268.00 +* +3 0 +0 +VECTOR +328.00 268.00 +416.00 268.00 +416.00 320.00 +356.00 320.00 +* +6 0 +0 +VECTOR +356.00 328.00 +356.00 312.00 +* +3 0 +0 +VECTOR +352.00 328.00 +352.00 312.00 +* +6 0 +0 +VECTOR +320.00 320.00 +352.00 320.00 +* +6 0 +0 +VECTOR +312.00 312.00 +256.00 312.00 +256.00 268.00 +288.00 268.00 +* +6 0 +0 +VECTOR +224.00 276.00 +224.00 260.00 +* +3 0 +0 +VECTOR +228.00 276.00 +228.00 260.00 +* +6 0 +0 +VECTOR +228.00 268.00 +256.00 268.00 +* +6 0 +0 +VECTOR +224.00 268.00 +192.00 268.00 +192.00 384.00 +316.00 384.00 +* +6 0 +0 +VECTOR +320.00 392.00 +320.00 376.00 +* +3 0 +0 +VECTOR +316.00 392.00 +316.00 376.00 +* +6 0 +0 +VECTOR +312.00 328.00 +312.00 352.00 +288.00 352.00 +* +6 0 +0 +VECTOR +392.00 392.00 +416.00 392.00 +416.00 320.00 +* +6 0 +0 +VECTOR +320.00 384.00 +384.00 384.00 +* +6 0 +0 +VECTOR +192.00 256.00 +192.00 268.00 +160.00 268.00 +* +6 0 +0 +ARC +160.00 266.00 +160.00 268.00 +160.00 268.00 +160.00 264.00 +158.00 266.00 +162.00 266.00 +* +3 0 +0 +VECTOR +164.00 256.00 +152.00 260.00 +* +3 0 +0 +ARC +160.00 254.00 +160.00 256.00 +160.00 256.00 +160.00 252.00 +158.00 254.00 +162.00 254.00 +* +3 0 +0 +ARC +194.00 256.00 +196.00 256.00 +196.00 256.00 +192.00 256.00 +194.00 254.00 +194.00 258.00 +* +3 0 +0 +VECTOR +204.00 260.00 +200.00 248.00 +* +3 0 +0 +VECTOR +200.00 248.00 +200.00 232.00 +* +6 0 +0 +VECTOR +152.00 260.00 +128.00 260.00 +* +6 0 +0 +ARC +96.00 266.00 +96.00 268.00 +96.00 268.00 +96.00 264.00 +98.00 266.00 +94.00 266.00 +* +3 0 +0 +VECTOR +92.00 256.00 +104.00 260.00 +* +3 0 +0 +ARC +96.00 254.00 +96.00 256.00 +96.00 256.00 +96.00 252.00 +98.00 254.00 +94.00 254.00 +* +3 0 +0 +VECTOR +124.00 268.00 +124.00 252.00 +* +3 0 +0 +VECTOR +128.00 268.00 +128.00 252.00 +* +6 0 +0 +VECTOR +104.00 260.00 +124.00 260.00 +* +6 0 +0 +VECTOR +96.00 268.00 +96.00 320.00 +40.00 320.00 +* +6 0 +0 +ARC +28.00 338.00 +28.00 340.00 +28.00 340.00 +28.00 336.00 +30.00 338.00 +26.00 338.00 +* +3 0 +0 +VECTOR +24.00 336.00 +40.00 320.00 +* +3 0 +0 +ARC +28.00 302.00 +28.00 304.00 +28.00 304.00 +28.00 300.00 +30.00 302.00 +26.00 302.00 +* +3 0 +0 +ARC +14.00 320.00 +12.00 320.00 +12.00 320.00 +16.00 320.00 +14.00 322.00 +14.00 318.00 +* +3 0 +0 +VECTOR +96.00 252.00 +76.00 252.00 +* +6 0 +0 +ARC +68.00 258.00 +68.00 260.00 +68.00 260.00 +68.00 256.00 +70.00 258.00 +66.00 258.00 +* +3 0 +0 +VECTOR +64.00 248.00 +76.00 252.00 +* +3 0 +0 +ARC +68.00 246.00 +68.00 248.00 +68.00 248.00 +68.00 244.00 +70.00 246.00 +66.00 246.00 +* +3 0 +0 +VECTOR +352.00 384.00 +352.00 416.00 +512.00 416.00 +* +6 0 +0 +VECTOR +512.00 424.00 +512.00 408.00 +* +3 0 +0 +VECTOR +516.00 424.00 +516.00 408.00 +* +6 0 +0 +VECTOR +516.00 416.00 +564.00 416.00 +564.00 368.00 +592.00 368.00 +* +6 0 +0 +VECTOR +564.00 416.00 +564.00 448.00 +516.00 448.00 +* +6 0 +0 +ARC +480.00 454.00 +480.00 456.00 +480.00 456.00 +480.00 452.00 +482.00 454.00 +478.00 454.00 +* +3 0 +0 +VECTOR +476.00 444.00 +488.00 448.00 +* +3 0 +0 +ARC +480.00 442.00 +480.00 444.00 +480.00 444.00 +480.00 440.00 +482.00 442.00 +478.00 442.00 +* +3 0 +0 +VECTOR +512.00 456.00 +512.00 440.00 +* +3 0 +0 +VECTOR +516.00 456.00 +516.00 440.00 +* +6 0 +0 +VECTOR +488.00 448.00 +512.00 448.00 +* +6 0 +0 +VECTOR +480.00 440.00 +480.00 416.00 +* +6 0 +0 +ARC +352.00 384.00 +352.00 383.00 +352.00 385.00 +352.00 383.00 +353.00 384.00 +351.00 384.00 +* +3 0 +0 +ARC +480.00 416.00 +480.00 415.00 +480.00 417.00 +480.00 415.00 +481.00 416.00 +479.00 416.00 +* +3 0 +0 +ARC +564.00 416.00 +564.00 415.00 +564.00 417.00 +564.00 415.00 +565.00 416.00 +563.00 416.00 +* +3 0 +0 +VECTOR +480.00 456.00 +480.00 472.00 +* +6 0 +0 +BOTCENT +480.00 488.00 +452.00 488.00 +480.00 488.00 +509.00 488.00 +* +1 1 +12 $- ^ vv REF$ +POLYGON +484.00 480.00 +476.00 480.00 +476.00 476.00 +480.00 472.00 +484.00 476.00 +* +3 21 +0 +ARC +550.00 396.00 +548.00 396.00 +548.00 396.00 +552.00 396.00 +550.00 394.00 +550.00 398.00 +* +3 0 +0 +VECTOR +540.00 400.00 +544.00 388.00 +* +3 0 +0 +VECTOR +544.00 388.00 +544.00 316.00 +* +6 0 +0 +VECTOR +552.00 396.00 +552.00 416.00 +* +6 0 +0 +ARC +552.00 416.00 +552.00 415.00 +552.00 417.00 +552.00 415.00 +553.00 416.00 +551.00 416.00 +* +3 0 +0 +CENTRIGHT +516.00 352.00 +483.00 348.00 +499.00 348.00 +516.00 348.00 +* +1 1 +7 $vv B1$ +POLYGON +520.00 356.00 +520.00 348.00 +524.00 348.00 +528.00 352.00 +524.00 356.00 +* +3 21 +0 +VECTOR +512.00 280.00 +512.00 296.00 +* +3 0 +0 +VECTOR +516.00 280.00 +516.00 296.00 +* +6 0 +0 +VECTOR +564.00 288.00 +564.00 256.00 +516.00 256.00 +* +6 0 +0 +ARC +480.00 250.00 +480.00 248.00 +480.00 248.00 +480.00 252.00 +482.00 250.00 +478.00 250.00 +* +3 0 +0 +VECTOR +476.00 260.00 +488.00 256.00 +* +3 0 +0 +ARC +480.00 262.00 +480.00 260.00 +480.00 260.00 +480.00 264.00 +482.00 262.00 +478.00 262.00 +* +3 0 +0 +VECTOR +512.00 248.00 +512.00 264.00 +* +3 0 +0 +VECTOR +516.00 248.00 +516.00 264.00 +* +6 0 +0 +VECTOR +488.00 256.00 +512.00 256.00 +* +6 0 +0 +VECTOR +480.00 264.00 +480.00 288.00 +* +6 0 +0 +ARC +480.00 288.00 +480.00 289.00 +480.00 287.00 +480.00 289.00 +481.00 288.00 +479.00 288.00 +* +3 0 +0 +ARC +564.00 288.00 +564.00 289.00 +564.00 287.00 +564.00 289.00 +565.00 288.00 +563.00 288.00 +* +3 0 +0 +VECTOR +480.00 248.00 +480.00 232.00 +* +6 0 +0 +ARC +550.00 308.00 +548.00 308.00 +548.00 308.00 +552.00 308.00 +550.00 310.00 +550.00 306.00 +* +3 0 +0 +VECTOR +540.00 304.00 +544.00 316.00 +* +3 0 +0 +VECTOR +552.00 308.00 +552.00 288.00 +* +6 0 +0 +ARC +552.00 288.00 +552.00 289.00 +552.00 287.00 +552.00 289.00 +553.00 288.00 +551.00 288.00 +* +3 0 +0 +VECTOR +528.00 352.00 +544.00 352.00 +* +6 0 +0 +ARC +544.00 352.00 +544.00 351.00 +544.00 353.00 +544.00 351.00 +545.00 352.00 +543.00 352.00 +* +3 0 +0 +VECTOR +516.00 288.00 +564.00 288.00 +564.00 336.00 +592.00 336.00 +* +6 0 +0 +VECTOR +512.00 288.00 +448.00 288.00 +448.00 64.00 +* +6 0 +0 +VECTOR +352.00 416.00 +352.00 448.00 +* +6 0 +0 +ARC +352.00 416.00 +352.00 415.00 +352.00 417.00 +352.00 415.00 +353.00 416.00 +351.00 416.00 +* +3 0 +0 +BOTCENT +352.00 460.00 +343.00 460.00 +352.00 460.00 +361.00 460.00 +* +1 1 +3 $A$ +POLYGON +356.00 448.00 +348.00 448.00 +348.00 452.00 +352.00 456.00 +356.00 452.00 +* +3 21 +0 +BOTCENT +320.00 396.00 +307.00 396.00 +320.00 396.00 +333.00 396.00 +* +1 1 +6 $cc F$ +BOTRIGHT +348.00 328.00 +321.00 328.00 +334.00 328.00 +348.00 328.00 +* +1 1 +6 $cc O$ +BOTCENT +228.00 280.00 +215.00 280.00 +228.00 280.00 +242.00 280.00 +* +1 1 +6 $cc C$ +BOTCENT +128.00 272.00 +116.00 272.00 +128.00 272.00 +141.00 272.00 +* +1 1 +6 $cc S$ +CENTLEFT +204.00 256.00 +204.00 252.00 +227.00 252.00 +250.00 252.00 +* +1 1 +10 $DP sub 2$ +BOTCENT +68.00 264.00 +56.00 264.00 +68.00 264.00 +80.00 264.00 +* +1 1 +4 $PN$ +TOPRIGHT +388.00 380.00 +342.00 371.00 +365.00 371.00 +388.00 371.00 +* +1 1 +10 $DP sub 2$ +TOPCENT +392.00 348.00 +372.00 339.00 +392.00 339.00 +412.00 339.00 +* +1 1 +6 $AGND$ +POLYGON +396.00 352.00 +388.00 352.00 +388.00 356.00 +392.00 360.00 +396.00 356.00 +* +3 21 +0 +VECTOR +392.00 360.00 +392.00 376.00 +* +6 0 +0 +TOPRIGHT +540.00 396.00 +494.00 387.00 +517.00 387.00 +540.00 387.00 +* +1 1 +10 $DP sub 1$ +CENTRIGHT +508.00 440.00 +476.00 436.00 +492.00 436.00 +508.00 436.00 +* +1 1 +7 $cc D1$ +CENTRIGHT +508.00 408.00 +476.00 404.00 +492.00 404.00 +508.00 404.00 +* +1 1 +7 $cc D2$ +BOTRIGHT +508.00 268.00 +476.00 268.00 +492.00 268.00 +508.00 268.00 +* +1 1 +7 $cc D1$ +BOTRIGHT +508.00 300.00 +476.00 300.00 +492.00 300.00 +508.00 300.00 +* +1 1 +7 $cc D2$ +VECTOR +672.00 392.00 +672.00 344.00 +720.00 344.00 +720.00 392.00 +672.00 392.00 +* +3 0 +0 +ARC +696.00 396.00 +696.00 392.00 +696.00 400.00 +696.00 392.00 +700.00 396.00 +692.00 396.00 +* +3 0 +0 +TOPCENT +696.00 392.00 +688.00 383.00 +696.00 383.00 +705.00 383.00 +* +1 1 +3 $R$ +ARC +668.00 368.00 +668.00 364.00 +668.00 372.00 +668.00 364.00 +672.00 368.00 +664.00 368.00 +* +3 0 +0 +CENTLEFT +676.00 368.00 +676.00 364.00 +688.00 364.00 +700.00 364.00 +* +1 1 +4 $CK$ +ARC +724.00 368.00 +724.00 364.00 +724.00 372.00 +724.00 364.00 +720.00 368.00 +728.00 368.00 +* +3 0 +0 +CENTRIGHT +720.00 368.00 +688.00 364.00 +704.00 364.00 +720.00 364.00 +* +1 1 +7 $O bar$ +CENTLEFT +676.00 352.00 +676.00 348.00 +684.00 348.00 +693.00 348.00 +* +1 1 +3 $D$ +CENTRIGHT +720.00 352.00 +703.00 348.00 +711.00 348.00 +720.00 348.00 +* +1 1 +3 $O$ +VECTOR +656.00 352.00 +672.00 352.00 +* +6 0 +0 +VECTOR +720.00 352.00 +736.00 352.00 +736.00 176.00 +768.00 176.00 +* +6 0 +0 +VECTOR +728.00 368.00 +800.00 368.00 +* +6 0 +0 +BOTRIGHT +804.00 376.00 +762.00 376.00 +783.00 376.00 +804.00 376.00 +* +1 1 +6 $DOWN$ +POLYGON +800.00 372.00 +800.00 364.00 +804.00 364.00 +808.00 368.00 +804.00 372.00 +* +3 21 +0 +VECTOR +516.00 192.00 +564.00 192.00 +564.00 144.00 +592.00 144.00 +* +6 0 +0 +VECTOR +512.00 192.00 +432.00 192.00 +432.00 416.00 +* +6 0 +0 +VECTOR +512.00 200.00 +512.00 184.00 +* +3 0 +0 +VECTOR +516.00 200.00 +516.00 184.00 +* +6 0 +0 +VECTOR +564.00 192.00 +564.00 224.00 +516.00 224.00 +* +6 0 +0 +ARC +480.00 230.00 +480.00 232.00 +480.00 232.00 +480.00 228.00 +482.00 230.00 +478.00 230.00 +* +3 0 +0 +VECTOR +476.00 220.00 +488.00 224.00 +* +3 0 +0 +ARC +480.00 218.00 +480.00 220.00 +480.00 220.00 +480.00 216.00 +482.00 218.00 +478.00 218.00 +* +3 0 +0 +VECTOR +512.00 232.00 +512.00 216.00 +* +3 0 +0 +VECTOR +516.00 232.00 +516.00 216.00 +* +6 0 +0 +VECTOR +488.00 224.00 +512.00 224.00 +* +6 0 +0 +VECTOR +480.00 216.00 +480.00 192.00 +* +6 0 +0 +ARC +480.00 192.00 +480.00 191.00 +480.00 193.00 +480.00 191.00 +481.00 192.00 +479.00 192.00 +* +3 0 +0 +ARC +564.00 192.00 +564.00 191.00 +564.00 193.00 +564.00 191.00 +565.00 192.00 +563.00 192.00 +* +3 0 +0 +VECTOR +480.00 232.00 +480.00 248.00 +* +6 0 +0 +VECTOR +552.00 172.00 +552.00 192.00 +* +6 0 +0 +ARC +552.00 192.00 +552.00 191.00 +552.00 193.00 +552.00 191.00 +553.00 192.00 +551.00 192.00 +* +3 0 +0 +TOPRIGHT +508.00 220.00 +476.00 211.00 +492.00 211.00 +508.00 211.00 +* +1 1 +7 $cc D1$ +TOPRIGHT +508.00 188.00 +476.00 179.00 +492.00 179.00 +508.00 179.00 +* +1 1 +7 $cc D2$ +VECTOR +224.00 212.00 +192.00 212.00 +192.00 96.00 +316.00 96.00 +* +6 0 +0 +VECTOR +312.00 168.00 +256.00 168.00 +256.00 212.00 +288.00 212.00 +* +6 0 +0 +VECTOR +328.00 212.00 +416.00 212.00 +416.00 160.00 +356.00 160.00 +* +6 0 +0 +VECTOR +604.00 136.00 +612.00 136.00 +612.00 116.00 +620.00 116.00 +* +6 0 +0 +ARC +416.00 160.00 +416.00 161.00 +416.00 159.00 +416.00 161.00 +417.00 160.00 +415.00 160.00 +* +3 0 +0 +CENTLEFT +596.00 112.00 +596.00 108.00 +604.00 108.00 +613.00 108.00 +* +1 1 +3 $-$ +CENTLEFT +596.00 144.00 +596.00 140.00 +604.00 140.00 +612.00 140.00 +* +1 1 +3 $+$ +POLYGON +592.00 160.00 +592.00 96.00 +656.00 128.00 +592.00 160.00 +* +3 1 +0 +ARC +392.00 90.00 +392.00 88.00 +392.00 88.00 +392.00 92.00 +390.00 90.00 +394.00 90.00 +* +3 0 +0 +VECTOR +396.00 92.00 +384.00 96.00 +* +3 0 +0 +ARC +392.00 102.00 +392.00 100.00 +392.00 100.00 +392.00 104.00 +390.00 102.00 +394.00 102.00 +* +3 0 +0 +ARC +312.00 154.00 +312.00 152.00 +312.00 152.00 +312.00 156.00 +314.00 154.00 +310.00 154.00 +* +3 0 +0 +CENTRIGHT +276.00 128.00 +243.00 124.00 +259.00 124.00 +276.00 124.00 +* +1 1 +7 $vv B2$ +POLYGON +280.00 124.00 +280.00 132.00 +284.00 132.00 +288.00 128.00 +284.00 124.00 +* +3 21 +0 +VECTOR +308.00 156.00 +320.00 160.00 +* +3 0 +0 +ARC +312.00 166.00 +312.00 164.00 +312.00 164.00 +312.00 168.00 +314.00 166.00 +310.00 166.00 +* +3 0 +0 +VECTOR +356.00 152.00 +356.00 168.00 +* +3 0 +0 +VECTOR +352.00 152.00 +352.00 168.00 +* +6 0 +0 +VECTOR +320.00 160.00 +352.00 160.00 +* +6 0 +0 +VECTOR +320.00 88.00 +320.00 104.00 +* +3 0 +0 +VECTOR +316.00 88.00 +316.00 104.00 +* +6 0 +0 +VECTOR +312.00 152.00 +312.00 128.00 +288.00 128.00 +* +6 0 +0 +VECTOR +392.00 88.00 +416.00 88.00 +416.00 160.00 +* +6 0 +0 +VECTOR +320.00 96.00 +384.00 96.00 +* +6 0 +0 +VECTOR +352.00 96.00 +352.00 64.00 +512.00 64.00 +* +6 0 +0 +VECTOR +512.00 56.00 +512.00 72.00 +* +3 0 +0 +VECTOR +516.00 56.00 +516.00 72.00 +* +6 0 +0 +VECTOR +516.00 64.00 +564.00 64.00 +564.00 112.00 +592.00 112.00 +* +6 0 +0 +VECTOR +564.00 64.00 +564.00 32.00 +516.00 32.00 +* +6 0 +0 +ARC +480.00 26.00 +480.00 24.00 +480.00 24.00 +480.00 28.00 +482.00 26.00 +478.00 26.00 +* +3 0 +0 +VECTOR +476.00 36.00 +488.00 32.00 +* +3 0 +0 +ARC +480.00 38.00 +480.00 36.00 +480.00 36.00 +480.00 40.00 +482.00 38.00 +478.00 38.00 +* +3 0 +0 +VECTOR +512.00 24.00 +512.00 40.00 +* +3 0 +0 +VECTOR +516.00 24.00 +516.00 40.00 +* +6 0 +0 +VECTOR +488.00 32.00 +512.00 32.00 +* +6 0 +0 +VECTOR +480.00 40.00 +480.00 64.00 +* +6 0 +0 +ARC +352.00 96.00 +352.00 97.00 +352.00 95.00 +352.00 97.00 +353.00 96.00 +351.00 96.00 +* +3 0 +0 +ARC +480.00 64.00 +480.00 65.00 +480.00 63.00 +480.00 65.00 +481.00 64.00 +479.00 64.00 +* +3 0 +0 +ARC +564.00 64.00 +564.00 65.00 +564.00 63.00 +564.00 65.00 +565.00 64.00 +563.00 64.00 +* +3 0 +0 +VECTOR +480.00 24.00 +480.00 8.00 +* +6 0 +0 +TOPCENT +480.00 -4.00 +452.00 -13.00 +480.00 -13.00 +509.00 -13.00 +* +1 1 +12 $- ^ vv REF$ +POLYGON +484.00 0.00 +476.00 0.00 +476.00 4.00 +480.00 8.00 +484.00 4.00 +* +3 21 +0 +ARC +550.00 84.00 +548.00 84.00 +548.00 84.00 +552.00 84.00 +550.00 86.00 +550.00 82.00 +* +3 0 +0 +VECTOR +540.00 80.00 +544.00 92.00 +* +3 0 +0 +VECTOR +544.00 92.00 +544.00 164.00 +* +6 0 +0 +VECTOR +552.00 84.00 +552.00 64.00 +* +6 0 +0 +ARC +552.00 64.00 +552.00 65.00 +552.00 63.00 +552.00 65.00 +553.00 64.00 +551.00 64.00 +* +3 0 +0 +CENTRIGHT +516.00 128.00 +483.00 124.00 +499.00 124.00 +516.00 124.00 +* +1 1 +7 $vv B1$ +POLYGON +520.00 124.00 +520.00 132.00 +524.00 132.00 +528.00 128.00 +524.00 124.00 +* +3 21 +0 +ARC +550.00 172.00 +548.00 172.00 +548.00 172.00 +552.00 172.00 +550.00 170.00 +550.00 174.00 +* +3 0 +0 +VECTOR +540.00 176.00 +544.00 164.00 +* +3 0 +0 +VECTOR +528.00 128.00 +544.00 128.00 +* +6 0 +0 +ARC +544.00 128.00 +544.00 129.00 +544.00 127.00 +544.00 129.00 +545.00 128.00 +543.00 128.00 +* +3 0 +0 +VECTOR +352.00 64.00 +352.00 32.00 +* +6 0 +0 +ARC +352.00 64.00 +352.00 65.00 +352.00 63.00 +352.00 65.00 +353.00 64.00 +351.00 64.00 +* +3 0 +0 +CENTCENT +352.00 16.00 +344.00 12.00 +352.00 12.00 +360.00 12.00 +* +1 1 +3 $B$ +POLYGON +356.00 32.00 +348.00 32.00 +348.00 28.00 +352.00 24.00 +356.00 28.00 +* +3 21 +0 +TOPCENT +320.00 84.00 +307.00 75.00 +320.00 75.00 +333.00 75.00 +* +1 1 +6 $cc F$ +TOPRIGHT +348.00 160.00 +321.00 151.00 +334.00 151.00 +348.00 151.00 +* +1 1 +6 $cc O$ +BOTRIGHT +388.00 100.00 +342.00 100.00 +365.00 100.00 +388.00 100.00 +* +1 1 +10 $DP sub 2$ +BOTCENT +392.00 132.00 +372.00 132.00 +392.00 132.00 +412.00 132.00 +* +1 1 +6 $AGND$ +POLYGON +396.00 128.00 +388.00 128.00 +388.00 124.00 +392.00 120.00 +396.00 124.00 +* +3 21 +0 +VECTOR +392.00 120.00 +392.00 104.00 +* +6 0 +0 +BOTRIGHT +540.00 84.00 +494.00 84.00 +517.00 84.00 +540.00 84.00 +* +1 1 +10 $DP sub 1$ +BOTRIGHT +508.00 44.00 +476.00 44.00 +492.00 44.00 +508.00 44.00 +* +1 1 +7 $cc D1$ +BOTRIGHT +508.00 76.00 +476.00 76.00 +492.00 76.00 +508.00 76.00 +* +1 1 +7 $cc D2$ +VECTOR +672.00 88.00 +672.00 136.00 +720.00 136.00 +720.00 88.00 +672.00 88.00 +* +3 0 +0 +ARC +696.00 84.00 +696.00 88.00 +696.00 80.00 +696.00 88.00 +700.00 84.00 +692.00 84.00 +* +3 0 +0 +BOTCENT +696.00 88.00 +688.00 88.00 +696.00 88.00 +705.00 88.00 +* +1 1 +3 $R$ +ARC +668.00 112.00 +668.00 116.00 +668.00 108.00 +668.00 116.00 +672.00 112.00 +664.00 112.00 +* +3 0 +0 +CENTLEFT +676.00 112.00 +676.00 108.00 +688.00 108.00 +700.00 108.00 +* +1 1 +4 $CK$ +ARC +724.00 112.00 +724.00 116.00 +724.00 108.00 +724.00 116.00 +720.00 112.00 +728.00 112.00 +* +3 0 +0 +CENTRIGHT +720.00 112.00 +688.00 108.00 +704.00 108.00 +720.00 108.00 +* +1 1 +7 $O bar$ +CENTLEFT +676.00 128.00 +676.00 124.00 +684.00 124.00 +693.00 124.00 +* +1 1 +3 $D$ +CENTRIGHT +720.00 128.00 +703.00 124.00 +711.00 124.00 +720.00 124.00 +* +1 1 +3 $O$ +VECTOR +656.00 128.00 +672.00 128.00 +* +6 0 +0 +VECTOR +720.00 128.00 +800.00 128.00 +* +6 0 +0 +CENTRIGHT +804.00 120.00 +780.00 116.00 +792.00 116.00 +804.00 116.00 +* +1 1 +4 $UP$ +POLYGON +800.00 124.00 +800.00 132.00 +804.00 132.00 +808.00 128.00 +804.00 124.00 +* +3 21 +0 +ARC +256.00 212.00 +256.00 213.00 +256.00 211.00 +256.00 213.00 +257.00 212.00 +255.00 212.00 +* +3 0 +0 +VECTOR +224.00 204.00 +224.00 220.00 +* +3 0 +0 +VECTOR +228.00 204.00 +228.00 220.00 +* +6 0 +0 +VECTOR +228.00 212.00 +256.00 212.00 +* +6 0 +0 +VECTOR +192.00 224.00 +192.00 212.00 +160.00 212.00 +* +6 0 +0 +ARC +160.00 214.00 +160.00 212.00 +160.00 212.00 +160.00 216.00 +158.00 214.00 +162.00 214.00 +* +3 0 +0 +VECTOR +164.00 224.00 +152.00 220.00 +* +3 0 +0 +ARC +160.00 226.00 +160.00 224.00 +160.00 224.00 +160.00 228.00 +158.00 226.00 +162.00 226.00 +* +3 0 +0 +ARC +194.00 224.00 +196.00 224.00 +196.00 224.00 +192.00 224.00 +194.00 226.00 +194.00 222.00 +* +3 0 +0 +VECTOR +204.00 220.00 +200.00 232.00 +* +3 0 +0 +VECTOR +152.00 220.00 +128.00 220.00 +* +6 0 +0 +ARC +96.00 214.00 +96.00 212.00 +96.00 212.00 +96.00 216.00 +98.00 214.00 +94.00 214.00 +* +3 0 +0 +VECTOR +92.00 224.00 +104.00 220.00 +* +3 0 +0 +ARC +96.00 226.00 +96.00 224.00 +96.00 224.00 +96.00 228.00 +98.00 226.00 +94.00 226.00 +* +3 0 +0 +VECTOR +124.00 212.00 +124.00 228.00 +* +3 0 +0 +VECTOR +128.00 212.00 +128.00 228.00 +* +6 0 +0 +VECTOR +104.00 220.00 +124.00 220.00 +* +6 0 +0 +VECTOR +96.00 212.00 +96.00 160.00 +40.00 160.00 +* +6 0 +0 +VECTOR +96.00 228.00 +76.00 228.00 +* +6 0 +0 +ARC +68.00 222.00 +68.00 220.00 +68.00 220.00 +68.00 224.00 +70.00 222.00 +66.00 222.00 +* +3 0 +0 +VECTOR +64.00 232.00 +76.00 228.00 +* +3 0 +0 +ARC +68.00 234.00 +68.00 232.00 +68.00 232.00 +68.00 236.00 +70.00 234.00 +66.00 234.00 +* +3 0 +0 +TOPCENT +228.00 200.00 +215.00 191.00 +228.00 191.00 +242.00 191.00 +* +1 1 +6 $cc C$ +TOPCENT +128.00 208.00 +116.00 199.00 +128.00 199.00 +141.00 199.00 +* +1 1 +6 $cc S$ +CENTLEFT +204.00 224.00 +204.00 220.00 +227.00 220.00 +250.00 220.00 +* +1 1 +10 $DP sub 2$ +CENTRIGHT +154.00 240.00 +129.00 236.00 +141.00 236.00 +154.00 236.00 +* +1 1 +5 $ITS$ +CENTCENT +94.00 240.00 +84.00 236.00 +94.00 236.00 +105.00 236.00 +* +1 1 +4 $SP$ +TOPCENT +68.00 216.00 +56.00 207.00 +68.00 207.00 +80.00 207.00 +* +1 1 +4 $PN$ +ARC +432.00 416.00 +432.00 415.00 +432.00 417.00 +432.00 415.00 +433.00 416.00 +431.00 416.00 +* +3 0 +0 +ARC +448.00 64.00 +448.00 63.00 +448.00 65.00 +448.00 63.00 +449.00 64.00 +447.00 64.00 +* +3 0 +0 +VECTOR +480.00 248.00 +480.00 232.00 +* +6 0 +0 +CENTRIGHT +452.00 240.00 +396.00 236.00 +424.00 236.00 +452.00 236.00 +* +1 1 +12 $+ ^ vv REF$ +POLYGON +452.00 244.00 +452.00 236.00 +456.00 236.00 +460.00 240.00 +456.00 244.00 +* +3 21 +0 +VECTOR +460.00 240.00 +480.00 240.00 +* +6 0 +0 +ARC +480.00 240.00 +480.00 241.00 +480.00 239.00 +480.00 241.00 +481.00 240.00 +479.00 240.00 +* +3 0 +0 +VECTOR +160.00 252.00 +160.00 228.00 +* +6 0 +0 +VECTOR +160.00 240.00 +224.00 240.00 +* +6 0 +0 +ARC +160.00 240.00 +160.00 239.00 +160.00 241.00 +160.00 239.00 +161.00 240.00 +159.00 240.00 +* +3 0 +0 +ARC +200.00 240.00 +200.00 239.00 +200.00 241.00 +200.00 239.00 +201.00 240.00 +199.00 240.00 +* +3 0 +0 +CENTLEFT +236.00 240.00 +236.00 236.00 +252.00 236.00 +268.00 236.00 +* +1 1 +5 $GND$ +POLYGON +232.00 244.00 +232.00 236.00 +228.00 236.00 +224.00 240.00 +228.00 244.00 +* +3 21 +0 +TOPRIGHT +540.00 172.00 +494.00 163.00 +517.00 163.00 +540.00 163.00 +* +1 1 +10 $DP sub 1$ +BOTRIGHT +540.00 308.00 +494.00 308.00 +517.00 308.00 +540.00 308.00 +* +1 1 +10 $DP sub 1$ +VECTOR +340.00 260.00 +340.00 220.00 +300.00 240.00 +340.00 260.00 +* +3 0 +0 +VECTOR +340.00 232.00 +384.00 232.00 +384.00 224.00 +* +6 0 +0 +POLYGON +380.00 224.00 +392.00 224.00 +384.00 216.00 +376.00 224.00 +* +6 21 +0 +VECTOR +340.00 248.00 +392.00 248.00 +* +6 0 +0 +BOTLEFT +396.00 256.00 +396.00 256.00 +416.00 256.00 +437.00 256.00 +* +1 1 +8 $vv INC$ +POLYGON +400.00 252.00 +400.00 244.00 +396.00 244.00 +392.00 248.00 +396.00 252.00 +* +3 21 +0 +CENTRIGHT +336.00 248.00 +319.00 244.00 +327.00 244.00 +336.00 244.00 +* +1 1 +3 $-$ +CENTRIGHT +336.00 232.00 +320.00 228.00 +328.00 228.00 +336.00 228.00 +* +1 1 +3 $+$ +VECTOR +784.00 192.00 +768.00 192.00 +768.00 160.00 +784.00 160.00 +* +3 0 +0 +ARC +784.00 176.00 +784.00 160.00 +784.00 192.00 +* +3 180 +0 +VECTOR +784.00 256.00 +768.00 256.00 +768.00 224.00 +784.00 224.00 +* +3 0 +0 +ARC +784.00 240.00 +784.00 224.00 +784.00 256.00 +* +3 180 +0 +ARC +832.00 312.00 +832.00 296.00 +832.00 328.00 +* +3 180 +0 +VECTOR +832.00 328.00 +816.00 328.00 +816.00 296.00 +832.00 296.00 +* +3 0 +0 +VECTOR +744.00 368.00 +744.00 312.00 +772.00 312.00 +* +6 0 +0 +VECTOR +744.00 312.00 +744.00 240.00 +768.00 240.00 +* +6 0 +0 +VECTOR +728.00 112.00 +744.00 112.00 +744.00 232.00 +768.00 232.00 +* +6 0 +0 +VECTOR +800.00 304.00 +816.00 304.00 +* +6 0 +0 +VECTOR +816.00 320.00 +800.00 320.00 +800.00 332.00 +720.00 332.00 +* +6 0 +0 +CENTRIGHT +708.00 332.00 +683.00 328.00 +695.00 328.00 +708.00 328.00 +* +1 1 +5 $ITS$ +POLYGON +712.00 336.00 +712.00 328.00 +716.00 328.00 +720.00 332.00 +716.00 336.00 +* +3 21 +0 +VECTOR +760.00 332.00 +760.00 184.00 +768.00 184.00 +* +6 0 +0 +VECTOR +760.00 248.00 +768.00 248.00 +* +6 0 +0 +VECTOR +752.00 128.00 +752.00 168.00 +768.00 168.00 +* +6 0 +0 +CENTLEFT +828.00 240.00 +828.00 236.00 +843.00 236.00 +858.00 236.00 +* +1 1 +5 $ABP$ +POLYGON +816.00 244.00 +816.00 236.00 +820.00 236.00 +824.00 240.00 +820.00 244.00 +* +3 21 +0 +VECTOR +800.00 240.00 +816.00 240.00 +* +6 0 +0 +CENTLEFT +828.00 176.00 +828.00 172.00 +844.00 172.00 +860.00 172.00 +* +1 1 +5 $ABN$ +POLYGON +816.00 180.00 +816.00 172.00 +820.00 172.00 +824.00 176.00 +820.00 180.00 +* +3 21 +0 +VECTOR +800.00 176.00 +816.00 176.00 +* +6 0 +0 +VECTOR +848.00 312.00 +864.00 312.00 +* +6 0 +0 +POLYGON +864.00 316.00 +864.00 308.00 +868.00 308.00 +872.00 312.00 +868.00 316.00 +* +3 21 +0 +CENTLEFT +876.00 312.00 +876.00 308.00 +891.00 308.00 +907.00 308.00 +* +1 1 +5 $ABC$ +ARC +760.00 332.00 +760.00 331.00 +760.00 333.00 +760.00 331.00 +761.00 332.00 +759.00 332.00 +* +3 0 +0 +ARC +744.00 368.00 +744.00 367.00 +744.00 369.00 +744.00 367.00 +745.00 368.00 +743.00 368.00 +* +3 0 +0 +ARC +744.00 312.00 +744.00 311.00 +744.00 313.00 +744.00 311.00 +745.00 312.00 +743.00 312.00 +* +3 0 +0 +ARC +760.00 248.00 +760.00 247.00 +760.00 249.00 +760.00 247.00 +761.00 248.00 +759.00 248.00 +* +3 0 +0 +VECTOR +752.00 168.00 +752.00 296.00 +772.00 296.00 +* +6 0 +0 +ARC +752.00 128.00 +752.00 127.00 +752.00 129.00 +752.00 127.00 +753.00 128.00 +751.00 128.00 +* +3 0 +0 +ARC +752.00 168.00 +752.00 167.00 +752.00 169.00 +752.00 167.00 +753.00 168.00 +751.00 168.00 +* +3 0 +0 +ARC +28.00 178.00 +28.00 180.00 +28.00 180.00 +28.00 176.00 +30.00 178.00 +26.00 178.00 +* +3 0 +0 +VECTOR +24.00 176.00 +40.00 160.00 +* +3 0 +0 +ARC +28.00 142.00 +28.00 144.00 +28.00 144.00 +28.00 140.00 +30.00 142.00 +26.00 142.00 +* +3 0 +0 +ARC +14.00 160.00 +12.00 160.00 +12.00 160.00 +16.00 160.00 +14.00 162.00 +14.00 158.00 +* +3 0 +0 +VECTOR +28.00 300.00 +0.00 300.00 +0.00 180.00 +28.00 180.00 +* +6 0 +0 +VECTOR +12.00 320.00 +-16.00 320.00 +-16.00 160.00 +12.00 160.00 +* +6 0 +0 +VECTOR +28.00 140.00 +-32.00 140.00 +-32.00 340.00 +28.00 340.00 +* +6 0 +0 +CENTRIGHT +-60.00 268.00 +-116.00 264.00 +-88.00 264.00 +-60.00 264.00 +* +1 1 +12 $+ ^ vv REF$ +POLYGON +-56.00 272.00 +-56.00 264.00 +-52.00 264.00 +-48.00 268.00 +-52.00 272.00 +* +3 21 +0 +VECTOR +-48.00 268.00 +-32.00 268.00 +* +6 0 +0 +ARC +-32.00 268.00 +-32.00 267.00 +-32.00 269.00 +-32.00 267.00 +-31.00 268.00 +-33.00 268.00 +* +3 0 +0 +ARC +-16.00 240.00 +-16.00 239.00 +-16.00 241.00 +-16.00 239.00 +-15.00 240.00 +-17.00 240.00 +* +3 0 +0 +VECTOR +-48.00 240.00 +-16.00 240.00 +* +6 0 +0 +POLYGON +-56.00 244.00 +-56.00 236.00 +-52.00 236.00 +-48.00 240.00 +-52.00 244.00 +* +3 21 +0 +CENTRIGHT +-60.00 240.00 +-100.00 236.00 +-80.00 236.00 +-60.00 236.00 +* +1 1 +6 $AGND$ +CENTRIGHT +-60.00 212.00 +-117.00 208.00 +-89.00 208.00 +-60.00 208.00 +* +1 1 +12 $- ^ vv REF$ +POLYGON +-56.00 216.00 +-56.00 208.00 +-52.00 208.00 +-48.00 212.00 +-52.00 216.00 +* +3 21 +0 +VECTOR +-48.00 212.00 +0.00 212.00 +* +6 0 +0 +ARC +0.00 212.00 +0.00 211.00 +0.00 213.00 +0.00 211.00 +1.00 212.00 +-1.00 212.00 +* +3 0 +0 +BOTRIGHT +24.00 344.00 +-6.00 344.00 +9.00 344.00 +24.00 344.00 +* +1 1 +5 $ABP$ +BOTRIGHT +12.00 324.00 +-19.00 324.00 +-4.00 324.00 +12.00 324.00 +* +1 1 +5 $ABC$ +BOTRIGHT +24.00 304.00 +-8.00 304.00 +8.00 304.00 +24.00 304.00 +* +1 1 +5 $ABN$ +BOTRIGHT +24.00 184.00 +-6.00 184.00 +9.00 184.00 +24.00 184.00 +* +1 1 +5 $ABP$ +BOTRIGHT +12.00 164.00 +-19.00 164.00 +-4.00 164.00 +12.00 164.00 +* +1 1 +5 $ABC$ +BOTRIGHT +24.00 144.00 +-8.00 144.00 +8.00 144.00 +24.00 144.00 +* +1 1 +5 $ABN$ +VECTOR +68.00 260.00 +52.00 260.00 +52.00 220.00 +68.00 220.00 +* +6 0 +0 +VECTOR +68.00 244.00 +68.00 236.00 +* +6 0 +0 +VECTOR +68.00 240.00 +40.00 240.00 +* +6 0 +0 +VECTOR +52.00 260.00 +40.00 260.00 +* +6 0 +0 +CENTRIGHT +32.00 260.00 +-21.00 256.00 +5.00 256.00 +32.00 256.00 +* +1 1 +12 $+ ^ vv SIG$ +POLYGON +32.00 264.00 +32.00 256.00 +36.00 256.00 +40.00 260.00 +36.00 264.00 +* +3 21 +0 +POLYGON +32.00 244.00 +32.00 236.00 +36.00 236.00 +40.00 240.00 +36.00 244.00 +* +3 21 +0 +CENTRIGHT +32.00 240.00 +-22.00 236.00 +5.00 236.00 +32.00 236.00 +* +1 1 +12 $- ^ vv SIG$ +ARC +52.00 260.00 +52.00 259.00 +52.00 261.00 +52.00 259.00 +53.00 260.00 +51.00 260.00 +* +3 0 +0 +ARC +68.00 240.00 +68.00 239.00 +68.00 241.00 +68.00 239.00 +69.00 240.00 +67.00 240.00 +* +3 0 +0 +VECTOR +64.00 112.00 +96.00 112.00 +96.00 96.00 +* +6 0 +0 +VECTOR +88.00 96.00 +104.00 96.00 +* +3 0 +0 +VECTOR +88.00 92.00 +104.00 92.00 +* +6 0 +0 +VECTOR +96.00 92.00 +96.00 76.00 +* +6 0 +0 +ARC +90.00 68.00 +88.00 68.00 +88.00 68.00 +92.00 68.00 +90.00 70.00 +90.00 66.00 +* +3 0 +0 +VECTOR +92.00 64.00 +96.00 76.00 +* +3 0 +0 +ARC +102.00 68.00 +100.00 68.00 +100.00 68.00 +104.00 68.00 +102.00 70.00 +102.00 66.00 +* +3 0 +0 +VECTOR +128.00 92.00 +128.00 4.00 +* +6 0 +0 +VECTOR +120.00 96.00 +136.00 96.00 +* +3 0 +0 +VECTOR +120.00 92.00 +136.00 92.00 +* +6 0 +0 +BOTCENT +128.00 124.00 +119.00 124.00 +128.00 124.00 +137.00 124.00 +* +1 1 +3 $A$ +POLYGON +132.00 120.00 +124.00 120.00 +124.00 116.00 +128.00 112.00 +132.00 116.00 +* +3 21 +0 +VECTOR +128.00 112.00 +128.00 96.00 +* +6 0 +0 +VECTOR +88.00 68.00 +76.00 68.00 +76.00 28.00 +88.00 28.00 +* +6 0 +0 +VECTOR +104.00 68.00 +116.00 68.00 +116.00 28.00 +104.00 28.00 +* +6 0 +0 +BOTLEFT +100.00 100.00 +100.00 100.00 +114.00 100.00 +128.00 100.00 +* +1 1 +6 $cc Y$ +BOTLEFT +132.00 100.00 +132.00 100.00 +145.00 100.00 +158.00 100.00 +* +1 1 +6 $cc Z$ +BOTRIGHT +92.00 72.00 +46.00 72.00 +69.00 72.00 +92.00 72.00 +* +1 1 +10 $DP sub 1$ +CENTRIGHT +52.00 112.00 +8.00 108.00 +30.00 108.00 +52.00 108.00 +* +1 1 +10 $+ ^ vv O$ +POLYGON +56.00 116.00 +56.00 108.00 +60.00 108.00 +64.00 112.00 +60.00 116.00 +* +3 21 +0 +BOTCENT +384.00 300.00 +362.00 300.00 +384.00 300.00 +406.00 300.00 +* +1 1 +10 $+ ^ vv O$ +POLYGON +388.00 288.00 +380.00 288.00 +380.00 292.00 +384.00 296.00 +388.00 292.00 +* +3 21 +0 +VECTOR +384.00 288.00 +384.00 268.00 +* +6 0 +0 +ARC +384.00 268.00 +384.00 267.00 +384.00 269.00 +384.00 267.00 +385.00 268.00 +383.00 268.00 +* +3 0 +0 +TOPCENT +384.00 180.00 +362.00 171.00 +384.00 171.00 +407.00 171.00 +* +1 1 +10 $- ^ vv O$ +POLYGON +388.00 192.00 +380.00 192.00 +380.00 188.00 +384.00 184.00 +388.00 188.00 +* +3 21 +0 +VECTOR +384.00 192.00 +384.00 212.00 +* +6 0 +0 +ARC +384.00 212.00 +384.00 213.00 +384.00 211.00 +384.00 213.00 +385.00 212.00 +383.00 212.00 +* +3 0 +0 +TOPLEFT +132.00 -4.00 +132.00 -13.00 +145.00 -13.00 +158.00 -13.00 +* +1 1 +6 $cc Z$ +VECTOR +64.00 -16.00 +96.00 -16.00 +96.00 0.00 +* +6 0 +0 +VECTOR +88.00 0.00 +104.00 0.00 +* +3 0 +0 +VECTOR +88.00 4.00 +104.00 4.00 +* +6 0 +0 +VECTOR +96.00 4.00 +96.00 20.00 +* +6 0 +0 +ARC +90.00 28.00 +88.00 28.00 +88.00 28.00 +92.00 28.00 +90.00 26.00 +90.00 30.00 +* +3 0 +0 +VECTOR +92.00 32.00 +96.00 20.00 +* +3 0 +0 +ARC +102.00 28.00 +100.00 28.00 +100.00 28.00 +104.00 28.00 +102.00 26.00 +102.00 30.00 +* +3 0 +0 +VECTOR +120.00 0.00 +136.00 0.00 +* +3 0 +0 +VECTOR +120.00 4.00 +136.00 4.00 +* +6 0 +0 +TOPCENT +128.00 -28.00 +120.00 -37.00 +128.00 -37.00 +136.00 -37.00 +* +1 1 +3 $B$ +POLYGON +132.00 -24.00 +124.00 -24.00 +124.00 -20.00 +128.00 -16.00 +132.00 -20.00 +* +3 21 +0 +VECTOR +128.00 -16.00 +128.00 0.00 +* +6 0 +0 +TOPLEFT +100.00 -4.00 +100.00 -13.00 +114.00 -13.00 +128.00 -13.00 +* +1 1 +6 $cc Y$ +CENTRIGHT +92.00 24.00 +46.00 20.00 +69.00 20.00 +92.00 20.00 +* +1 1 +10 $DP sub 1$ +CENTRIGHT +52.00 -16.00 +8.00 -20.00 +30.00 -20.00 +52.00 -20.00 +* +1 1 +10 $+ ^ vv O$ +POLYGON +56.00 -20.00 +56.00 -12.00 +60.00 -12.00 +64.00 -16.00 +60.00 -20.00 +* +3 21 +0 +VECTOR +116.00 48.00 +152.00 48.00 +* +6 0 +0 +CENTLEFT +164.00 48.00 +164.00 44.00 +184.00 44.00 +205.00 44.00 +* +1 1 +8 $vv INC$ +POLYGON +152.00 44.00 +152.00 52.00 +156.00 52.00 +160.00 48.00 +156.00 44.00 +* +3 21 +0 +ARC +116.00 48.00 +116.00 49.00 +116.00 47.00 +116.00 49.00 +117.00 48.00 +115.00 48.00 +* +3 0 +0 +ARC +128.00 48.00 +128.00 49.00 +128.00 47.00 +128.00 49.00 +129.00 48.00 +127.00 48.00 +* +3 0 +0 +ARC +76.00 48.00 +76.00 49.00 +76.00 47.00 +76.00 49.00 +77.00 48.00 +75.00 48.00 +* +3 0 +0 +VECTOR +56.00 48.00 +76.00 48.00 +* +6 0 +0 +POLYGON +48.00 52.00 +48.00 44.00 +52.00 44.00 +56.00 48.00 +52.00 52.00 +* +3 21 +0 +CENTRIGHT +48.00 48.00 +15.00 44.00 +31.00 44.00 +48.00 44.00 +* +1 1 +7 $vv B1$ +-1 diff --git a/doc/grnexmpl.me b/doc/grnexmpl.me new file mode 100644 index 0000000..641d15c --- /dev/null +++ b/doc/grnexmpl.me @@ -0,0 +1,88 @@ +.nr pp 12 +.nr tp 12 +.nr sp 12 +.nr fi 0 +.ls 1 +.po 1i +.pl 11i +.EQ +gsize 12 +delim $$ +define // 'over down 10' +define sw 'phi sub' +define aa 'A sub' +define vv 'V sub' +define mm 'M sub' +define nn 'N sub' +define cc 'C sub' +define ll 'L sub' +define rr 'R sub' +define ss 'S sub' +define gg 'g sub' +define ff 'F sub' +define qq 'Q sub' +define qqq '{C prime} sub' +define pp 'P sub' +define tt 'T sub' +define zz 'Z sub' +define kk 'K sub' +define ii 'I sub' +define iis 'IC sub' +define e2 '2 sup' +define sunc '{ sin x } / x' +define vddm1V 'vv DD - 1 ^ roman V' +define vssp1V 'vv SS + 1 ^ roman V' +.EN +.pp +The following slide shows the complete schematics of the +fully-differential RIC. The operation includes a +correlated-double-sampling phase that occurs once every 256 +clock periods, also called the +.i "spreading ratio" . +This reset phase is controlled by clocks $ DP sub 1 $ and $ DP +sub 2 $ in which the integrator is initialized by totally +removing the charge from $ cc F $ and storing the low-frequency +noise of the op amp in $ cc C $. At the same time the comparison +thresholds are set. +.fl +.po -0.2i +.sp 2 +.lp +.(b +.EQ +gsize -4 +.EN +.GS +roman 1 +italics 2 +bold 3 +special 4 +narrow 1 +medium 3 +thick 5 +width 5.5 +l mg +file grnexmpl.g +.GE +.EQ +gsize +4 +.EN +.)b +.fl +.po +0.2i +.pp +The faster clocks are $ PN $, $ ITS $ and $ SP $. The sampling +capacitor $ cc S $ performs the delayed subtraction of a sample +of the input signal $ +- ^ vv SIG $ and a choice of $ - ^ vv REF +$, $ AGND $ or $ + ^ vv REF $ according to the operations +performed by the logic partially depicted operating on past +results of the comparisons. The synchronous comparators are +reset at this fast rates, thus performing one comparison for +every fast clock cycle. The dynamic common-mode feedback +arrangement operates synchronously with the reset time slot and +its configuration is equivalent to that in the differential +feedback path. +.\" Local Variables: +.\" mode: nroff +.\" End: +.\" vim: filetype=groff: diff --git a/doc/groff.css b/doc/groff.css new file mode 100644 index 0000000..ea36359 --- /dev/null +++ b/doc/groff.css @@ -0,0 +1,17 @@ + +body { + margin-top: 0%; + margin-left: 0%; + margin-right: 0%; + margin-bottom: 0%; + background-color: white; + color: black; +} + +pre { + background-color: #E0E0E0; + color: black; + border: thin; + border-style: solid; +} + diff --git a/doc/groff.dvi b/doc/groff.dvi new file mode 100644 index 0000000..9efd1f6 Binary files /dev/null and b/doc/groff.dvi differ diff --git a/doc/groff.html b/doc/groff.html new file mode 100644 index 0000000..e085b9e --- /dev/null +++ b/doc/groff.html @@ -0,0 +1,24945 @@ + + + + + + +The GNU Troff Manual + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: (dir)   [Contents][Index]

+
+

GNU troff

+ + +

This manual documents GNU troff version 1.23.0. +

+

Copyright © 1994–2023 Free Software Foundation, Inc. +

+
+

Permission is granted to copy, distribute and/or modify this document +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, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled “GNU Free +Documentation License”. +

+ + + + + +
+

Table of Contents

+ +
+ + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

1 Introduction

+ + +

GNU roff (or groff) is a programming system for +typesetting documents. It is highly flexible and has been used +extensively for over thirty years. +

+ + + + +
+
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+

1.1 Background

+ + +

M. Douglas McIlroy, formerly of AT&T Bell Laboratories and present at +the creation of the Unix operating system, offers an authoritative +historical summary. +

+
+

The prime reason for Unix was the desire of Ken [Thompson], Dennis +[Ritchie], and Joe Ossanna to have a pleasant environment for software +development. The fig leaf that got the nod from … +management was that an early use would be to develop a “stand-alone” +word-processing system for use in typing pools and secretarial offices. +Perhaps they had in mind “dedicated”, as distinct from +“stand-alone”; that’s what eventuated in various cases, most notably +in the legal/patent department and in the AT&T CEO’s office. +

+

Both those systems were targets of opportunity, not foreseen from the +start. When Unix was up and running on the PDP-11, Joe got wind of +the legal department having installed a commercial word processor. +He went to pitch Unix as an alternative and clinched a trial by +promising to make roff able to number lines by tomorrow in order +to fulfill a patent-office requirement that the commercial system did +not support. +

+

Modems were installed so legal-department secretaries could try the +Research machine. They liked it and Joe’s superb customer service. +Soon the legal department got a system of their own. Joe went on to +create nroff and troff. Document preparation became a +widespread use of Unix, but no stand-alone word-processing system was +ever undertaken. +

+ +

A history relating groff to its predecessors roff, +nroff, and troff is available in the roff(7) +man page. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+

1.2 What Is groff?

+ + + +

groff (GNU roff) is a typesetting system that reads plain +text input files that include formatting commands to produce output in +PostScript, PDF, HTML, DVI, or other formats, or for display to a +terminal. Formatting commands can be low-level typesetting primitives, +macros from a supplied package, or user-defined macros. All three +approaches can be combined. +

+

A reimplementation and extension of the typesetter from AT&T +Unix, groff is present on most POSIX systems owing to +its long association with Unix manuals (including man pages). It and +its predecessor are notable for their production of several best-selling +software engineering texts. groff is capable of producing +typographically sophisticated documents while consuming minimal system +resources. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+

1.3 groff Capabilities

+ + + +

GNU troff is a typesetting document formatter; it provides a wide +range of low-level text and page operations within the framework of a +programming language. These operations compose to generate footnotes, +tables of contents, mathematical equations, diagrams, multi-column text, +and other elements of typeset works. Here is a survey of formatter +features; all are under precise user control. +

+
    +
  • text filling, breaking, alignment to the left or right margin; centering + +
  • adjustment of inter-word space size to justify text, and of +inter-sentence space size to suit local style conventions + +
  • automatic and manual determination of hyphenation break points + +
  • pagination + +
  • selection of any font available to the output device + +
  • adjustment of type size and vertical spacing (or “leading”) + +
  • configuration of line length and indentation amounts; columnation + +
  • drawing of geometric primitives (lines, arcs, polygons, circles, +…) + +
  • setup of stroke and fill colors (where supported by the output +device) + +
  • embedding of hyperlinks, images, document metadata, and other inclusions +(where supported by the output device) +
+ + + +
+
+
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+

1.4 Macro Packages

+ + + +

Elemental typesetting functions can be be challenging to use directly +with complex documents. A macro facility specifies how certain +routine operations, such as starting paragraphs, or printing headers and +footers, should be performed in terms of those low-level instructions. +Macros can be specific to one document or collected together into a +macro package for use by many. Several macro packages available; +the most widely used are provided with groff. They are +man, mdoc, me, mm, mom, and +ms. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+

1.5 Preprocessors

+ + +

An alternative approach to complexity management, particularly when +constructing tables, setting mathematics, or drawing diagrams, lies in +preprocessing. A preprocessor employs a domian-specific language +to ease the generation of tables, equations, and so forth in terms that +are convenient for human entry. Each preprocessor reads a document and +translates the parts of it that apply to it into GNU troff input. +Command-line options to groff tell it which preprocessors to +use. +

+

groff provides preprocessors for laying out tables +(gtbl), typesetting equations (geqn), drawing +diagrams (gpic and ggrn), inserting bibliographic +references (grefer), and drawing chemical structures +(gchem). An associated program that is useful when dealing +with preprocessors is gsoelim.1 +

+

groff also supports grap, a preprocessor for drawing +graphs. A free implementation of it can be obtained separately. +

+

Unique to groff is the preconv preprocessor that enables +groff to handle documents in a variety of input encodings. +

+

Other preprocessors exist, but no free implementations +are known. An example is ideal, which draws diagrams using a +mathematical constraint language. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+

1.6 Output Devices

+ + + + +

GNU troff’s output is in a device-independent page description +language, which is then read by an output driver that translates +this language into a file format or byte stream that a piece of +(possibly emulated) hardware understands. groff features output +drivers for PostScript devices, terminal emulators (and other simple +typewriter-like machines), X11 (for previewing), TeX DVI, HP +LaserJet 4/PCL5 and Canon LBP printers (which use CaPSL), +HTML, XHTML, and PDF. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+

1.7 Installation

+ + +

Locate installation instructions in the files INSTALL, +INSTALL.extra, and INSTALL.REPO in the groff source +distribution. Being a GNU project, groff supports the familiar +‘./configure && make’ command sequence. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+

1.8 Conventions Used in This Manual

+ +

We apply the term “groff” to the language documented here, the GNU +implementation of the overall system, the project that develops that +system, and the command of that name. In the first sense, groff +is an extended dialect of the roff language, for which many +similar implementations exist. +

+

The roff language features several major categories for which +many items are predefined. Presentations of these items feature the +form in which the item is most commonly used on the left, and, aligned +to the right margin, the name of the category in brackets. +

+
+
Register: \n[example]
+

The register ‘example’ is one that that groff doesn’t +predefine. You can create it yourself, though; see Setting Registers. +

+ +

To make this document useful as a reference and not merely amiable +bedtime reading, we tend to present these syntax items in exhaustive +detail when they arise. References to topics discussed later in the +text are frequent; skip material you don’t understand yet. +

+

We use Texinfo’s “result” (⇒) and error→ notations to +present output written to the standard output and standard error +streams, respectively. Diagnostic messages from the GNU troff +formatter and other programs are examples of the latter, but the +formatter can also be directed to write user-specified messages to the +standard error stream. The notation then serves to identify the +output stream and does not necessarily mean that an error has +occurred.2 +

+
+
$ echo "Twelve o'clock and" | groff -Tascii | sed '/^$/d'
+    ⇒ Twelve o'clock and
+$ echo '.tm all is well.' | groff > /dev/null
+    error→ all is well.
+
+ +

Sometimes we use ⇒ somewhat abstractly to represent formatted +text that you will need to use a PostScript or PDF viewer program (or a +printer) to observe. While arguably an abuse of notation, we think this +preferable to requiring the reader to understand the syntax of these +page description languages. +

+

We also present diagnostic messages in an abbreviated form, often +omitting the name of the program issuing them, the input file name, and +line number or other positional information when such data do not serve +to illuminate the topic under discussion. +

+

Most examples are of roff language input that would be placed in +a text file. Occasionally, we start an example with a ‘$’ +character to indicate a shell prompt, as seen above. +

+

You are encouraged to try the examples yourself, and to alter them to +better learn groff’s behavior. Our examples frequently need to +direct the formatter to set a line length (with ‘.ll’) that will +fit within the page margins of this manual. We mention this so that you +know why it is there before we discuss the ll request +formally.3 +

+ + +
+
+
+
+

+Previous: , Up: Introduction   [Contents][Index]

+
+

1.9 Credits

+ + +

We adapted portions of this manual from existing documents. James +Clark’s man pages were an essential resource; we have updated them in +parallel with the development of this manual. We based the tutorial for +macro users on Eric Allman’s introduction to his me macro package +(which we also provide, little altered from 4.4BSD). Larry Kollar +contributed much of the material on the ms macro package. +

+ + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

2 Invoking groff

+ + + +

This chapter focuses on how to invoke the groff front end. This +front end takes care of the details of constructing the pipeline among +the preprocessors, gtroff and the postprocessor. +

+

It has become a tradition that GNU programs get the prefix ‘g’ to +distinguish them from their original counterparts provided by the host +(see Environment). Thus, for example, geqn is GNU +eqn. On operating systems like GNU/Linux or the Hurd, which +don’t contain proprietary versions of troff, and on +MS-DOS/MS-Windows, where troff and associated programs are not +available at all, this prefix is omitted since GNU troff is the +only incarnation of troff used. Exception: ‘groff’ is never +replaced by ‘roff’. +

+

In this document, we consequently say ‘gtroff’ when talking about +the GNU troff program. All other implementations of troff are called AT&T +troff, which is the common origin of almost all troff +implementations4 (with more or less compatible changes). Similarly, we say +‘gpic’, ‘geqn’, and so on. +

+ + + + +
+
+
+

+Next: , Previous: , Up: Invoking groff   [Contents][Index]

+
+

2.1 Options

+ + + + + + + + + + + + + +

groff normally runs the gtroff program and a +postprocessor appropriate for the selected device. The default device +is ‘ps’ (but it can be changed when groff is configured and +built). It can optionally preprocess with any of gpic, +geqn, gtbl, ggrn, grap, gchem, +grefer, gsoelim, or preconv. +

+

This section documents only options to the groff front end. Many +of the arguments to groff are passed on to gtroff; +therefore, those are also included. Arguments to preprocessors and +output drivers can be found in the man pages gpic(1), +geqn(1), gtbl(1), ggrn(1), +grefer(1), gchem(1), gsoelim(1), +preconv(1), grotty(1), grops(1), +gropdf(1), grohtml(1), grodvi(1), +grolj4(1), grolbp(1), and gxditview(1). +

+

The command-line format for groff is: +

+
+
groff [ -abceghijklpstvzCEGNRSUVXZ ] [ -dcs ] [ -Darg ]
+      [ -ffam ] [ -Fdir ] [ -Idir ] [ -Karg ]
+      [ -Larg ] [ -mname ] [ -Mdir ] [ -nnum ]
+      [ -olist ] [ -Parg ] [ -rcn ] [ -Tdev ]
+      [ -wname ] [ -Wname ] [ files… ]
+
+ +

The command-line format for gtroff is as follows. +

+
+
gtroff [ -abcivzCERU ] [ -dcs ] [ -ffam ] [ -Fdir ]
+       [ -mname ] [ -Mdir ] [ -nnum ] [ -olist ]
+       [ -rcn ] [ -Tname ] [ -wname ] [ -Wname ]
+       [ files… ]
+
+ +

Obviously, many of the options to groff are actually passed on to +gtroff. +

+

Options without an argument can be grouped behind a +single -. A filename of - denotes the +standard input. Whitespace is permitted between an option and its +argument. +

+

The grog command can be used to guess the correct groff +command to format a file. See its man page grog(1); type +‘man grog’ at the command line to view it. +

+

groff’s command-line options are as follows. +

+ +
+
‘-a’
+

Generate a plain text approximation of the typeset output. The +read-only register .A is set to 1. See Built-in Registers. This option produces a sort of abstract preview of the +formatted output. +

+
    +
  • Page breaks are marked by a phrase in angle brackets; for example, +‘<beginning of page>’. + +
  • Lines are broken where they would be in the formatted output. + +
  • A horizontal motion of any size is represented as one space. Adjacent +horizontal motions are not combined. Inter-sentence space nodes (those +arising from the second argument to the ss request) are not +represented. + +
  • Vertical motions are not represented. + +
  • Special characters are rendered in angle brackets; for example, the +default soft hyphen character appears as ‘<hy>’. +
+ +

The above description should not be considered a specification; the +details of -a output are subject to change. +

+
+
‘-b’
+

Write a backtrace reporting the state of gtroff’s input parser +to the standard error stream with each diagnostic message. The line +numbers given in the backtrace might not always be correct, because +gtroff’s idea of line numbers can be confused by requests that +append to +macros. +

+
+
‘-c’
+

Start with color output disabled. +

+
+
‘-C’
+

Enable AT&T troff compatibility mode; implies -c. +See Implementation Differences, for the list of incompatibilities +between groff and AT&T troff. +

+
+
‘-dctext’
+
‘-dstring=text’
+

Define roff string c or string as t or +text. c must be one character; string can be +of arbitrary length. Such string assignments happen before any macro +file is loaded, including the startup file. Due to getopt_long +limitations, c cannot be, and string cannot contain, an +equals sign, even though that is a valid character in a roff +identifier. +

+
+
‘-Denc’
+

Set fallback input encoding used by preconv to enc; +implies -k. +

+
+
‘-e’
+

Run geqn preprocessor. +

+
+
‘-E’
+

Inhibit gtroff error messages. This option does not +suppress messages sent to the standard error stream by documents or +macro packages using tm or related requests. +

+
+
‘-ffam’
+

Use fam as the default font family. See Font Families. +

+
+
‘-Fdir’
+

Search in directory dir for the selected output device’s +directory of device and font description files. See the description of +GROFF_FONT_PATH in Environment below for the default search +locations and ordering. +

+
+
‘-g’
+

Run ggrn preprocessor. +

+
+
‘-G’
+

Run grap preprocessor; implies -p. +

+
+
‘-h’
+

Display a usage message and exit. +

+
+
‘-i’
+

Read the standard input after all the named input files have been +processed. +

+
+
‘-Idir’
+

Search the directory dir for files named in several contexts; +implies -g and -s. +

+
    +
  • gsoelim replaces so requests with the contents of their +file name arguments. + +
  • gtroff searches for files named as operands in its command +line and as arguments to psbb, so, and soquiet +requests. + +
  • Output drivers may search for files; for instance, grops looks +for files named in ‘\X'ps: import …'’, ‘\X'ps: file +…'’, and ‘\X'pdf: pdfpic …'’ device control +escape sequences. +
+ +

This option may be specified more than once; the directories are +searched in the order specified. If you want to search the current +directory before others, add ‘-I .’ at the desired place. The +current working directory is otherwise searched last. -I works +similarly to, and is named for, the “include” option of Unix C +compilers. +

+

-I options are passed to gsoelim, gtroff, +and output drivers; with the flag letter changed to -M, they +are also passed to ggrn. +

+
+
‘-j’
+

Run gchem preprocessor. Implies -p. +

+
+
‘-k’
+

Run preconv preprocessor. Refer to its man page for its +behavior if neither of groff’s -K or -D +options is also specified. +

+
+
‘-Kenc’
+

Set input encoding used by preconv to enc; implies +-k. +

+
+
‘-l’
+

Send the output to a spooler for printing. The print directive +in the device description file specifies the default command to be used; +see Device and Font Description Files. +See options -L and -X. +

+
+
‘-Larg’
+

Pass arg to the print spooler program. If multiple args are +required, pass each with a separate -L option. groff +does not prefix an option dash to arg before passing it to the +spooler program. +

+
+
‘-mname’
+

Process the file name.tmac prior to any input files. +If not found, tmac.name is attempted. name +(in both arrangements) is presumed to be a macro file; see the +description of GROFF_TMAC_PATH in Environment below for the +default search locations and ordering. This option and its argument are +also passed to geqn, grap, and ggrn. +

+
+
‘-Mdir’
+

Search directory dir for macro files; see the description +of GROFF_TMAC_PATH in Environment below for the default +search locations and ordering. This option and its argument are also +passed to geqn, grap, and ggrn. +

+
+
‘-nnum’
+

Number the first page num. +

+
+
‘-N’
+

Prohibit newlines between eqn delimiters: pass -N to +geqn. +

+
+
‘-olist’
+

Output only pages in list, which is a comma-separated list of page +ranges; ‘n’ means page n, ‘m-n’ +means every page between m and n, ‘-n’ means +every page up to n, ‘n-’ means every page from +n on. gtroff stops processing and exits after +formatting the last page enumerated in list. +

+
+
‘-p’
+

Run gpic preprocessor. +

+
+
‘-Parg’
+

Pass arg to the postprocessor. If multiple args are +required, pass each with a separate -P option. groff +does not prefix an option dash to arg before passing it to the +postprocessor. +

+
+
‘-rcnumeric-expression’
+
‘-rregister=expr’
+

Set roff register c or register to the value +numeric-expression (see Numeric Expressions). +c must be one character; register can be of arbitrary +length. Such register assignments happen before any macro file is +loaded, including the startup file. Due to getopt_long +limitations, c cannot be, and register cannot contain, +an equals sign, even though that is a valid character in a roff +identifier. +

+
+
‘-R’
+

Run grefer preprocessor. No mechanism is provided for passing +arguments to grefer because most grefer options have +equivalent language elements that can be specified within the document. +

+ + +

gtroff also accepts a -R option, which is not +accessible via groff. This option prevents the loading of the +troffrc and troffrc-end files. +

+
+
‘-s’
+

Run gsoelim preprocessor. +

+
+
‘-S’
+
+ + + + + +

Operate in “safer” mode; see -U below for its opposite. For +security reasons, safer mode is enabled by default. +

+
+
‘-t’
+

Run gtbl preprocessor. +

+
+
‘-Tdev’
+

Direct gtroff to format the input for the output device +dev. groff then calls an output driver to convert +gtroff’s output to a form appropriate for dev. The +following output devices are available. +

+
+
ps
+

For PostScript printers and previewers. +

+
+
pdf
+

For PDF viewers or printers. +

+
+
dvi
+

For TeX DVI format. +

+
+
X75
+

For a 75dpi X11 previewer. +

+
+
X75-12
+

For a 75dpi X11 previewer with a 12-point base font in the +document. +

+
+
X100
+

For a 100dpi X11 previewer. +

+
+
X100-12
+

For a 100dpi X11 previewer with a 12-point base font in the +document. +

+
+
ascii
+
+ + + + +

For typewriter-like devices using the (7-bit) ASCII +(ISO 646) character set. +

+
+
latin1
+
+ + +

For typewriter-like devices that support the Latin-1 +(ISO 8859-1) character set. +

+
+
utf8
+
+ +

For typewriter-like devices that use the Unicode (ISO 10646) +character set with UTF-8 encoding. +

+
+
cp1047
+
+ + + + + + +

For typewriter-like devices that use the EBCDIC encoding IBM +code page 1047. +

+
+
lj4
+

For HP LaserJet4-compatible (or other PCL5-compatible) printers. +

+
+
lbp
+

For Canon CaPSL printers (LBP-4 and LBP-8 series laser +printers). +

+ + + +
+
html
+
xhtml
+

To produce HTML and XHTML output, respectively. +This driver consists of two parts, a preprocessor +(pre-grohtml) and a postprocessor (post-grohtml). +

+
+ + + +

The predefined GNU troff string .T contains the name of +the output device; the read-only register .T is set to 1 if +this option is used (which is always true if groff is used to +call GNU troff). See Built-in Registers. +

+

The postprocessor to be used for a device is specified by the +postpro command in the device description file. (See Device and Font Description Files.) This can be overridden with the +-X option. +

+
+
‘-U’
+
+

Operate in unsafe mode, which enables the open, +opena, pi, pso, and sy requests. These +requests are disabled by default because they allow an untrusted input +document to write to arbitrary file names and run arbitrary commands. +This option also adds the current directory to the macro package search +path; see the -m option above. -U is passed to +gpic and gtroff. +

+
+
‘-v’
+

Write version information for groff and all programs run by it +to the standard output stream; that is, the given command line is +processed in the usual way, passing -v to the formatter and any +pre- or postprocessors invoked. +

+
+
‘-V’
+

Output the pipeline that would be run by groff +(as a wrapper program) to the standard output stream, but do not execute +it. If given more than once, the pipeline is both written to the +standard error stream and run. +

+
+
‘-wcategory’
+

Enable warnings in category. Categories are listed in +Warnings. +

+
+
‘-Wcategory’
+

Inhibit warnings in category. Categories are listed in +Warnings. +

+
+
‘-X’
+

Use gxditview instead of the usual postprocessor to (pre)view +a document on an X11 display. Combining this option with +-Tps uses the font metrics of the PostScript device, whereas +the -TX75 and -TX100 options use the metrics of X11 +fonts. +

+
+
‘-z’
+

Suppress formatted output from gtroff. +

+
+
‘-Z’
+

Disable postprocessing. gtroff output will appear on the +standard output stream (unless suppressed with -z; see +gtroff Output for a description of this format. +

+
+ + + +
+
+
+
+

+Next: , Previous: , Up: Invoking groff   [Contents][Index]

+
+

2.2 Environment

+ + + +

There are also several environment variables (of the operating system, +not within gtroff) that can modify the behavior of groff. +

+
+
GROFF_BIN_PATH
+

This search path, followed by PATH, is used for commands executed +by groff. +

+
+
GROFF_COMMAND_PREFIX
+
+ +

If this is set to X, then groff runs +Xtroff instead of gtroff. This also applies +to tbl, pic, eqn, grn, +chem, refer, and soelim. It does not +apply to grops, grodvi, grotty, +pre-grohtml, post-grohtml, preconv, +grolj4, gropdf, and gxditview. +

+

The default command prefix is determined during the installation +process. If a non-GNU troff system is found, prefix ‘g’ is +used, none otherwise. +

+
+
GROFF_ENCODING
+

The value of this variable is passed to the preconv +preprocessor’s -e option to select the character encoding of +input files. This variable’s existence implies the groff option +-k. If set but empty, groff calls preconv +without an -e option. groff’s -K option +overrides GROFF_ENCODING. See the preconv(7) man page; +type ‘man preconv’ at the command line to view it. +

+
+
GROFF_FONT_PATH
+

A list of directories in which to seek the selected output device’s +directory of device and font description files. GNU troff +will search directories given as arguments to any specified -F +options before these, and a built-in list of directories after them. +See Font Directories and the troff(1) or +gtroff(1) man pages. +

+
+
GROFF_TMAC_PATH
+

A list of directories in which to seek macro files. GNU troff +will search directories given as arguments to any specified -M +options before these, and a built-in list of directories after them. +See Macro Directories and the troff(1) or +gtroff(1) man pages. +

+
+
GROFF_TMPDIR
+
+

The directory in which groff creates temporary files. If this is +not set and TMPDIR is set, temporary files are created in that +directory. Otherwise temporary files are created in a system-dependent +default directory (on Unix and GNU/Linux systems, this is usually +/tmp). grops, grefer, pre-grohtml, and +post-grohtml can create temporary files in this directory. +

+
+
GROFF_TYPESETTER
+

Sets the default output device. If empty or not set, a build-time +default (often ps) is used. The -Tdev option +overrides GROFF_TYPESETTER. +

+
+
SOURCE_DATE_EPOCH
+

A timestamp (expressed as seconds since the Unix epoch) to use as the +output creation timestamp in place of the current time. The time is +converted to human-readable form using localtime(3) when the +formatter starts up and stored in registers usable by documents and +macro packages (see Built-in Registers). +

+
+
TZ
+

The time zone to use when converting the current time (or value of +SOURCE_DATE_EPOCH) to human-readable form; see +tzset(3). +

+
+ +

MS-DOS and MS-Windows ports of groff use semicolons, rather than +colons, to separate the directories in the lists described above. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Invoking groff   [Contents][Index]

+
+

2.3 Macro Directories

+ + + + + +

A macro file must have a name in the form name.tmac or +tmac.name and be placed in a tmac directory to be +found by the -mname command-line option.5 + + + + + + + + + + +Together, these directories constitute the tmac path. Each +directory is searched in the following order until the desired macro +file is found or the list is exhausted. +

+
    +
  • Directories specified with GNU troff’s or groff’s +-M command-line option. + +
  • +Directories listed in the GROFF_TMAC_PATH environment variable. + +
  • + + + + + +The current working directory (only if in unsafe mode using the +-U command-line option). + +
  • + +The user’s home directory, HOME. + +
  • + + + +A platform-dependent directory, a site-local (platform-independent) +directory, and the main tmac directory. The locations +corresponding to your installation are listed in section “Environment” +of gtroff(1). If not otherwise configured, they are as +follows. + +
    +
    /usr/local/lib/groff/site-tmac
+/usr/local/share/groff/site-tmac
+/usr/local/share/groff/1.23.0/tmac
+
    + +

    The foregoing assumes that the version of groff is 1.23.0, and +that the installation prefix was /usr/local. It is possible to +fine-tune these locations during the source configuration process. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: Invoking groff   [Contents][Index]

+
+

2.4 Font Directories

+ + + + + +

groff enforces few restrictions on how font description files are +named. For its family/style mechanism to work (see Font Families), +the names of fonts within a family should start with the family name, +followed by the style. For example, the Times family uses ‘T’ for +the family name and ‘R’, ‘B’, ‘I’, and ‘BI’ to +indicate the styles ‘roman’, ‘bold’, ‘italic’, and ‘bold italic’, +respectively. Thus the final font names are ‘TR’, ‘TB’, +‘TI’, and ‘TBI’. +

+ + +

Font description files are kept in font directories, which +together constitute the font path. The search procedure +always appends the directory devname, where name is +the name of the output device. Assuming TeX DVI output, and +/foo/bar as a font directory, the font description files for +grodvi must be in /foo/bar/devdvi. +Each directory in the font path is searched in the following order until +the desired font description file is found or the list is exhausted. +

+
    +
  • Directories specified with GNU troff’s or groff’s +-f command-line option. All output drivers (and some +preprocessors) support this option as well, because they require +information about the glyphs to be rendered in the document. + +
  • +Directories listed in the GROFF_FONT_PATH environment variable. + +
  • + +A site-local directory and the main font description directory. +The locations corresponding to your installation are listed in section +“Environment” of gtroff(1). If not otherwise configured, +they are as follows. + +
    +
    /usr/local/share/groff/site-font
+/usr/local/share/groff/1.23.0/font
+
    + +

    The foregoing assumes that the version of groff is 1.23.0, and +that the installation prefix was /usr/local. It is possible to +fine-tune these locations during the source configuration process. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: Invoking groff   [Contents][Index]

+
+

2.5 Paper Format

+ + + + + + + + +

In groff, the page dimensions for the formatter GNU troff +and for output devices are handled separately. See Page Layout, for +vertical manipulation of the page size, and See Line Layout, for +horizontal changes. + + +The papersize macro package, normally loaded by troffrc at +startup, provides an interface for configuring page dimensions by +convenient names, like ‘letter’ or ‘a4’; see +groff_tmac(5). The default used by the formatter depends on +its build configuration, but is usually one of the foregoing, as +geographically appropriate. +

+

It is up to each macro package to respect the page dimensions configured +in this way. +

+

For each output device, the size of the output medium can be set in its +DESC file. Most output drivers also recognize a command-line +option -p to override the default dimensions and an option +-l to use landscape orientation. See DESC File Format, for +a description of the papersize keyword, which takes an argument +of the same form as -p. The output driver’s man page, such as +grops(1), may also be helpful. +

+

groff uses the command-line option -P to pass options to +postprocessors; for example, use the following for PostScript output on +A4 paper in landscape orientation. +

+
+
groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
+
+ + + +
+
+
+
+

+Previous: , Up: Invoking groff   [Contents][Index]

+
+

2.6 Invocation Examples

+ + + +

roff systems are best known for formatting man pages. Once a +man librarian program has located a man page, it may execute +a groff command much like the following. +

+
+
groff -t -man -Tutf8 /usr/share/man/man1/groff.1
+
+ +

The librarian will also pipe the output through a pager, which might not +interpret the SGR terminal escape sequences groff emits for +boldface, underlining, or italics; see the grotty(1) man page +for a discussion. +

+

To process a roff input file using the preprocessors +gtbl and gpic and the me macro package in the +way to which AT&T troff users were accustomed, one would type (or +script) a pipeline. +

+
+
gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty
+
+ +

Using groff, this pipe can be shortened to an equivalent +command. +

+
+
groff -p -t -me -T utf8 foo.me
+
+ +

An even easier way to do this is to use grog to guess the +preprocessor and macro options and execute the result by using the +command substitution feature of the shell. +

+
+
$(grog -Tutf8 foo.me)
+
+ +

Each command-line option to a postprocessor must be specified with any +required leading dashes ‘-’ +because groff passes the arguments as-is to the postprocessor; +this permits arbitrary arguments to be transmitted. For example, to +pass a title to the gxditview postprocessor, +the shell commands +

+
+
groff -X -P -title -P 'trial run' mydoc.t
+
+ +

and +

+
+
groff -X -Z mydoc.t | gxditview -title 'trial run' -
+
+ +

are equivalent. +

+ + + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

3 Tutorial for Macro Users

+ + + + + +

Most users of the roff language employ a macro package to format +their documents. Successful macro packages ease the composition +process; their users need not have mastered the full formatting +language, nor understand features like diversions, traps, and +environments. This chapter aims to familiarize you with basic concepts +and mechanisms common to many macro packages (like “displays”). If +you prefer a meticulous and comprehensive presentation, try GNU troff Reference instead. +

+ + + + +
+
+
+

+Next: , Previous: , Up: Tutorial for Macro Users   [Contents][Index]

+
+

3.1 Basics

+ + + +

Let us first survey some basic concepts necessary to use a macro package +fruitfully.6 +References are made throughout to more detailed information. +

+

GNU troff reads an input file prepared by the user and outputs a +formatted document suitable for publication or framing. The input +consists of text, or words to be printed, and embedded commands +(requests and escape sequences), which tell GNU +troff how to format the output. See Formatter Instructions. +

+

The word argument is used in this chapter to mean a word or +number that appears on the same line as a request, and which modifies +the meaning of that request. For example, the request +

+
+
.sp
+
+ +

spaces one line, but +

+
+
.sp 4
+
+ +

spaces four lines. The number 4 is an argument to the sp +request, which says to space four lines instead of one. Arguments are +separated from the request and from each other by spaces (not +tabs). See Invoking Requests. +

+

The primary function of GNU troff is to collect words from input +lines, fill output lines with those words, adjust the line to the +right-hand margin by widening spaces, and output the result. For +example, the input: +

+
+
Now is the time
+for all good men
+to come to the aid
+of their party.
+Four score and seven
+years ago, etc.
+
+ +

is read, packed onto output lines, and justified to produce: +

+
+
  ⇒ Now is the time for all good men to come to the aid of
+  ⇒ their party.  Four score and seven years ago, etc.
+
+ +

Sometimes a new output line should be started even though the current +line is not yet full—for example, at the end of a paragraph. To do +this it is possible to force a break, starting a new output +line. Some requests cause a break automatically, as do (normally) blank +input lines and input lines beginning with a space or tab. +

+

Not all input lines are text lines—words to be formatted. +Some are control lines that tell a macro package (or GNU +troff directly) how to format the text. Control lines start with +a dot (‘.’) or an apostrophe (‘'’) as the first character, and +can be followed by a macro call. +

+

The formatter also does more complex things, such as automatically +numbering pages, skipping over page boundaries, putting footnotes in the +correct place, and so forth. +

+

Here are a few hints for preparing text for input to GNU troff. +

+
    +
  • First, keep the input lines short. Short input lines are easier to +edit, and GNU troff packs words onto longer lines anyhow. + +
  • In keeping with this, it is helpful to begin a new line after every +comma or phrase, since common corrections are to add or delete sentences +or phrases. + +
  • End each sentence with two spaces—or better, start each sentence on a +new line. GNU troff recognizes characters that usually end a +sentence, and inserts inter-sentence space accordingly. + +
  • Do not hyphenate words at the end of lines—GNU troff is smart +enough to hyphenate words as needed, but is not smart enough to take +hyphens out and join a word back together. Also, words such as +“mother-in-law” should not be broken over a line, since then a space +can occur where not wanted, such as “mother- in-law”. +
+ +

We offer further advice in Input Conventions. +

+ + +

GNU troff permits alteration of the distance between lines of +text. This is termed vertical spacing and is expressed in the +same units as the type size—the point. The default is 10-point type +on 12-point spacing. To get double-spaced text you would set +the vertical spacing to 24 points. Some, but not all, macro packages +expose a macro or register to configure the vertical spacing. +

+

A number of requests allow you to change the way the output is arranged +on the page, sometimes called the layout of the output page. +Most macro packages don’t supply macros for performing these (at least +not without performing other actions besides), as they are such basic +operations. The macro packages for writing man pages, man and +mdoc, don’t encourage explicit use of these requests at all. +

+ +

The request ‘.sp N’ leaves N lines of blank +space. N can be omitted (skipping a single line) or can +be of the form Ni (for N inches) or Nc (for +N centimeters). For example, the input: +

+
+
.sp 1.5i
+My thoughts on the subject
+.sp
+
+ +

leaves one and a half inches of space, followed by the line “My +thoughts on the subject”, followed by a single blank line (more +measurement units are available; see Measurements). +

+

If you seek precision in spacing, be advised when using a macro package +that it might not honor sp requests as you expect; it can use a +formatter feature called no-space mode to prevent excess space +from accumulating. Macro packages typically offer registers to control +spacing between paragraphs, before section headings, and around displays +(discussed below); use these facilities preferentially. +See Manipulating Spacing. +

+ + +

Text lines can be centered by using the ce request. The line +after ce is centered (horizontally) on the page. To center more +than one line, use ‘.ce N’ (where N is the number +of lines to center), followed by the N lines. To center many +lines without counting them, type: +

+
+
.ce 1000
+lines to center
+.ce 0
+
+ +

The ‘.ce 0’ request tells GNU troff to center zero more +lines, in other words, stop centering. +

+ + + + +

GNU troff also offers the rj request for right-aligning +text. It works analogously to ce and is convenient for setting +epigraphs. +

+ + +

The bp request starts a new page; this necessarily implies an +ordinary (line) break. +

+ + +

All of these requests cause a break; that is, they always start a new +line. To start a new line without performing any other action, use +br. If you invoke them with the apostrophe ‘'’, the +no-break control character, the (initial) break they normally +perform is suppressed. ‘'br’ does nothing. +

+ + +
+
+
+
+

+Previous: , Up: Tutorial for Macro Users   [Contents][Index]

+
+

3.2 Common Features

+ + + +

GNU troff provides low-level operations for formatting a +document. Many routine operations are undertaken in nearly all +documents that require a series of such primitive operations to be +performed. These common tasks are grouped into macros, which +are then collected into a macro package. +

+

Macro packages come in two varieties: “major” or “full-service” +ones that manage page layout, and “minor” or “auxiliary” ones that +do not, instead fulfilling narrow, specific tasks. Find a list in the +groff_tmac(5) man page. Type ‘man groff_tmac’ at the +command line to view it. +

+

We survey several capabilities of full-service macro package below. +Each package employs its own macros to exercise them. For details, +consult its man page or, for ms, see ms. +

+ + + +
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.1 Paragraphs

+ + +

Paragraphs can be separated and indented in various ways. Some start +with a blank line and have a first-line indentation, like most of the +ones in this manual. Block paragraphs omit the indentation. +

+
+
  ⇒ Some  men  look  at constitutions with sanctimonious
+  ⇒ reverence,  and  deem  them  like  the  ark  of  the
+  ⇒ covenant, too sacred to be touched.
+
+ + + + +

We also frequently encounter tagged paragraphs, which begin +with a tag or label at the left margin and indent the remaining text. +

+
+
  ⇒ one  This  is the first paragraph.  Notice how the
+  ⇒      first line of the resulting  paragraph  lines
+  ⇒      up with the other lines in the paragraph.
+
+ +

If the tag is too wide for the indentation, the line is broken. +

+
+
  ⇒ longlabel
+  ⇒      The  label does not align with the subsequent
+  ⇒      lines, but they align with each other.
+
+ +

A variation of the tagged paragraph is the itemized or enumerated +paragraph, which might use punctuation or a digit for a tag, +respectively. These are frequently used to construct lists. +

+
+
  ⇒ o    This  list  item  starts with a bullet.  When
+  ⇒      producing output for a device using the ASCII
+  ⇒      character set, an 'o' is formatted instead.
+
+ +

Often, use of the same macro without a tag continues such a discussion. +

+
+
  ⇒ -xyz  This option is recognized but ignored.
+  ⇒
+  ⇒       It had a security hole that we don't discuss.
+
+ + +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.2 Sections and Chapters

+ +

The simplest kind of section heading is unnumbered, set in a bold or +italic style, and occupies a line by itself. Others possess +automatically numbered multi-level headings and/or different typeface +styles or sizes at different levels. More sophisticated macro packages +supply macros for designating chapters and appendices. +

+ +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.3 Headers and Footers

+ +

Headers and footers occupy the top and bottom of +each page, respectively, and contain data like the page number and the +article or chapter title. Their appearance is not affected by the +running text. Some packages allow for different titles on even- and +odd-numbered pages (for printed, bound material). +

+

Headers and footers are together called titles, and comprise +three parts: left-aligned, centered, and right-aligned. A ‘%’ +character appearing anywhere in a title is automatically replaced by the +page number. See Page Layout. +

+ +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.4 Page Layout

+ +

Most macro packages let the user specify the size of the page margins. +The top and bottom margins are typically handled differently than the +left and right margins; the latter two are derived from the +page offset, indentation, and line length. +See Line Layout. Commonly, packages support registers to tune these +values. +

+ +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.5 Displays and Keeps

+ + +

Displays are sections of text set off from the surrounding +material (typically paragraphs), often differing in indentation, and/or +spacing. Tables, block quotations, and figures are displayed. +Equations and code examples, when not much shorter than an output line, +often are. Lists may or may not be. Packages for setting man pages +support example displays but not keeps. +

+ +

A keep is a group of output lines, often a display, that is +formatted on a single page if possible; it causes a page break to happen +early so as to not interrupt the kept material. +

+ + +

Floating keeps can move, or “float”, relative to the text +around them in the input. They are useful for displays that are +captioned and referred to by name, as with “See figure 3”. +Depending on the package, a floating keep appears at the bottom of the +current page if it fits, and at the top of the next otherwise. +Alternatively, floating keeps might be deferred to the end of a section. +Using a floating keep can avoid the large vertical spaces that may +precede a tall keep of the ordinary sort when it won’t fit on the page. +

+ +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.6 Footnotes and Endnotes

+ + + +

Footnotes and endnotes are forms of delayed +formatting. They are recorded at their points of relevance in +the input, but not formatted there. Instead, a mark cues the +reader to check the “foot”, or bottom, of the current page, or in the +case of endnotes, an annotation list later in the document. Macro +packages that support these features also supply a means of +automatically numbering either type of annotation. +

+ +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.7 Table of Contents

+ + + +

A package may handle a table of contents by directing section +heading macros to save section heading text and the page number where it +occurs for use in a later entry for a table of contents. It +writes the collected entries at the end of the document, once all are +known, upon request. A row of dots (a leader) bridges the +text on the left with its location on the right. Other collections +might work in this manner, providing lists of figures or tables. +

+

A table of contents is often found at the end of a GNU troff +document because the formatter processes the document in a single pass. +The gropdf output driver supports a PDF feature that relocates +pages at the time the document is rendered; see the gropdf(1) +man page. Type ‘man gropdf’ at the command line to view it. +

+ +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.8 Indexing

+ + + +

An index is similar to a table of contents, in that entry labels and +locations must be collected, but poses a greater challenge because it +needs to be sorted before it is output. Here, processing the document +in multiple passes is inescapable, and tools like the makeindex +program are necessary. +

+ +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.9 Document Formats

+ + +

Some macro packages supply stock configurations of certain documents, +like business letters and memoranda. These often also have provision +for a cover sheet, which may be rigid in its format. With +these features, it is even more important to use the package’s macros in +preference to the formatter requests presented earlier, where possible. +

+ +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.10 Columnation

+ +

Macro packages apart from man and mdoc for man page +formatting offer a facility for setting multiple columns on the page. +

+ +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.11 Font and Size Changes

+ +

The formatter’s requests and escape sequences for setting the typeface +and size are not always intuitive, so all macro packages provide macros +to make these operations simpler. They also make it more convenient to +change typefaces in the middle of a word and can handle italic +corrections automatically. See Italic Corrections. +

+ +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.12 Predefined Text

+ +

Most macro packages supply predefined strings to set prepared text like +the date, or to perform operations like super- and subscripting. +

+ +
+
+
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.13 Preprocessor Support

+ +

All macro packages provide support for various preprocessors and may +extend their functionality by defining macros to set their contents in +displays. Examples include TS and TE for gtbl, +EQ and EN for geqn, and PS and PE +for gpic. +

+ +
+
+
+
+

+Previous: , Up: Common Features   [Contents][Index]

+
+

3.2.14 Configuration and Customization

+ +

Packages provide means of customizing many of the details of how the +package behaves. These range from setting the default type size to +changing the appearance of section headers. +

+ + + + +
+
+
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

4 Macro Packages

+ + + + +

This chapter surveys the “major” macro packages that come with +groff. One, ms, is presented in detail. +

+ + + +

Major macro packages are also sometimes described as full-service +due to the breadth of features they provide and because more than one +cannot be used by the same document; for example +

+
+
groff -m man foo.man -m ms bar.doc
+
+ +

doesn’t work. Option arguments are processed before non-option +arguments; the above (failing) sample is thus reordered to +

+
+
groff -m man -m ms foo.man bar.doc
+
+ + + + + + + +

Many auxiliary, or “minor”, macro packages are also available. They +may in general be used with any full-service macro package and handle a +variety of tasks from character encoding selection, to language +localization, to inlining of raster images. See the +groff_tmac(5) man page for a list. Type ‘man +groff_tmac’ at the command line to view it. +

+ + + + +
+
+
+

+Next: , Previous: , Up: Macro Packages   [Contents][Index]

+
+

4.1 man

+ + + + + +

The man macro package is the most widely used and probably the +most important ever developed for troff. It is easy to use, and +a vast majority of manual pages (“man pages”) are written in it. +

+

groff’s implementation is documented in the +groff_man(7) man page. Type ‘man groff_man’ at the +command line to view it. +

+ + + +
+
+
+

+Up: man   [Contents][Index]

+
+

4.1.1 Optional man extensions

+ + +

Use the file man.local for local extensions to the man +macros or for style changes. +

+ +
+

Custom headers and footers

+ + +

In groff versions 1.18.2 and later, you can specify custom +headers and footers by redefining the following macros in +man.local. +

+
+
Macro: .PT
+
+

Control the content of the headers. Normally, the header prints the +command name and section number on either side, and the optional fifth +argument to TH in the center. +

+ +
+
Macro: .BT
+
+

Control the content of the footers. Normally, the footer prints the +page number and the third and fourth arguments to TH. +

+

Use the FT register to specify the footer position. The default +is −0.5i. +

+ +
+
+

Ultrix-specific man macros

+ + + + +

The groff source distribution includes a file named +man.ultrix, containing macros compatible with the Ultrix variant +of man. Copy this file into man.local (or use the +mso request to load it) to enable the following macros. +

+
+
Macro: .CT key
+
+

Print ‘<CTRL/key>’. +

+ +
+
Macro: .CW
+
+

Print subsequent text using a “constant-width” (monospaced) typeface +(Courier roman). +

+ +
+
Macro: .Ds
+
+

Begin a non-filled display. +

+ +
+
Macro: .De
+
+

End a non-filled display started with Ds. +

+ +
+
Macro: .EX [indent]
+
+

Begin a non-filled display using a monospaced typeface (Courier roman). +Use the optional indent argument to indent the display. +

+ +
+
Macro: .EE
+
+

End a non-filled display started with EX. +

+ +
+
Macro: .G [text]
+
+

Set text in Helvetica. If no text is present on the line where +the macro is called, then the text of the next line appears in +Helvetica. +

+ +
+
Macro: .GL [text]
+
+

Set text in Helvetica oblique. If no text is present on the line +where the macro is called, then the text of the next line appears in +Helvetica Oblique. +

+ +
+
Macro: .HB [text]
+
+

Set text in Helvetica bold. If no text is present on the line +where the macro is called, then all text up to the next HB +appears in Helvetica bold. +

+ +
+
Macro: .TB [text]
+
+

Identical to HB. +

+ +
+
Macro: .MS title sect [punct]
+
+

Set a man page reference in Ultrix format. The title is in +Courier instead of italic. Optional punctuation follows the section +number without an intervening space. +

+ +
+
Macro: .NT [C] [title]
+
+

Begin a note. Print the optional title, or the word “Note”, +centered on the page. Text following the macro makes up the body of the +note, and is indented on both sides. If the first argument is C, +the body of the note is printed centered (the second argument replaces +the word “Note” if specified). +

+ +
+
Macro: .NE
+
+

End a note begun with NT. +

+ +
+
Macro: .PN path [punct]
+
+

Set the path name in a monospaced typeface (Courier roman), followed by +optional punctuation. +

+ +
+
Macro: .Pn [punct] path [punct]
+
+

If called with two arguments, identical to PN. If called with +three arguments, set the second argument in a monospaced typeface +(Courier roman), bracketed by the first and third arguments in the +current font. +

+ +
+
Macro: .R
+
+

Switch to roman font and turn off any underlining in effect. +

+ +
+
Macro: .RN
+
+

Print the string ‘<RETURN>’. +

+ +
+
Macro: .VS [4]
+
+

Start printing a change bar in the margin if the number 4 is +specified. Otherwise, this macro does nothing. +

+ +
+
Macro: .VE
+
+

End printing the change bar begun by VS. +

+ +
+
+

Simple example

+ +

The following example man.local file alters the SH macro +to add some extra vertical space before printing the heading. Headings +are printed in Helvetica bold. +

+
+
.\" Make the heading fonts Helvetica
+.ds HF HB
+.
+.\" Put more space in front of headings.
+.rn SH SH-orig
+.de SH
+.  if t .sp (u;\\n[PD]*2)
+.  SH-orig \\$*
+..
+
+ + + +
+
+
+
+
+
+

+Next: , Previous: , Up: Macro Packages   [Contents][Index]

+
+

4.2 mdoc

+ + +

groff’s implementation of the BSD doc package for man +pages is documented in the groff_mdoc(7) man page. Type +‘man groff_mdoc’ at the command line to view it. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Macro Packages   [Contents][Index]

+
+

4.3 me

+ + +

groff’s implementation of the BSD me macro package is +documented using itself. A tutorial, meintro.me, and reference, +meref.me, are available in groff’s documentation +directory. A groff_me(7) man page is also available and +identifies the installation path for these documents. Type ‘man +groff_me’ at the command line to view it. +

+

A French translation of the tutorial is available as +meintro_fr.me and installed parallel to the English version. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Macro Packages   [Contents][Index]

+
+

4.4 mm

+ + +

groff’s implementation of the AT&T memorandum macro +package is documented in the groff_mm(7) man page. Type +‘man groff_mm’ at the command line) to view it. +

+

A Swedish localization of mm is also available; see +groff_mmse(7). +

+ + +
+
+
+
+

+Next: , Previous: , Up: Macro Packages   [Contents][Index]

+
+

4.5 mom

+ + +

The main documentation files for the mom macros are in +HTML format. Additional, useful documentation is in +PDF format. See the groff(1) man page, section +“Installation Directories”, for their location. +

+
    +
  • toc.html +Entry point to the full mom manual. + +
  • macrolist.html +Hyperlinked index of macros with brief descriptions, arranged by +category. + +
  • mom-pdf.pdf +PDF features and usage. +
+ +

The mom macros are in active development between groff releases. +The most recent version, along with up-to-date documentation, is +available at http://www.schaffter.ca/mom/mom-05.html. +

+

The groff_mom(7) man page (type ‘man groff_mom’ at +the command line) contains a partial list of available macros, however +their usage is best understood by consulting the HTML +documentation. +

+ + + +
+
+
+
+

+Previous: , Up: Macro Packages   [Contents][Index]

+
+

4.6 ms

+ + +

The ms (“manuscript”) package is suitable for the preparation +of letters, memoranda, reports, and books. These groff +macros feature cover page and table of contents generation, +automatically numbered headings, several paragraph styles, a variety of +text styling options, footnotes, and multi-column page layouts. +ms supports the tbl, eqn, pic, and +refer preprocessors for inclusion of tables, mathematical +equations, diagrams, and standardized bibliographic citations. This +implementation is mostly compatible with the documented interface and +behavior of AT&T Unix Version 7 ms. Many extensions from +4.2BSD (Berkeley) +and Tenth Edition Research Unix have been recreated. +

+ + + +
+
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+

4.6.1 Introduction

+ +

The ms macros are the oldest surviving package for roff +systems.7 While the man +package was designed for brief reference documents, the ms macros +are also suitable for longer works intended for printing and possible +publication. +

+ + + +
+
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+

4.6.1.1 Basic information

+ +

ms documents are plain text files; prepare them with your +preferred text editor. If you’re in a hurry to start, know that +ms needs one of its macros called at the beginning of a document +so that it can initialize. A macro is a formatting instruction to +ms. Put a macro call on a line by itself. Use ‘.PP’ if you +want your paragraph’s first line to be indented, or ‘.LP’ if you +don’t. +

+

After that, start typing normally. It is a good practice to start each +sentence on a new line, or to put two spaces after sentence-ending +punctuation, so that the formatter knows where the sentence boundaries +are. You can separate paragraphs with further paragraphing macros, or +with blank lines, and you can indent with tabs. When you need one of +the features mentioned earlier (see ms), return to this part of the +manual. +

+

Format the document with the groff command. nroff +can be useful for previewing. +

+
+
+
$ editor radical.ms
+$ nroff -ww -z -ms radical.ms # check for errors
+$ nroff -ms radical.ms | less -R
+$ groff -T ps -ms radical.ms > radical.ps
+$ see radical.ps
+
+
+ +

Our radical.ms document might look like this. +

+
+
+
.LP
+Radical novelties are so disturbing that they tend to be
+suppressed or ignored, to the extent that even the
+possibility of their existence in general is more often
+denied than admitted.
+
+→That's what Dijkstra said, anyway.
+
+
+ +

ms exposes many aspects of document layout to user control via +groff’s registers and strings, which store numbers +and text, respectively. Measurements in groff are expressed with +a suffix called a scaling unit. +

+
+
i
+

inches +

+
+
c
+

centimeters +

+
+
p
+

points (1/72 inch) +

+
+
P
+

picas (1/6 inch) +

+
+
v
+

vees; current vertical spacing +

+
+
m
+

ems; width of an “M” in the current font +

+
+
n
+

ens; one-half em +

+
+ +

Set registers with the nr request and strings with the ds +request. Requests are like macro calls; they go on lines by +themselves and start with the control character, a dot (.). +The difference is that they directly instruct the formatter program, +rather than the macro package. We’ll discuss a few as applicable. It +is wise to specify a scaling unit when setting any register that +represents a length, size, or distance. +

+
+
+
.nr PS 10.5p \" Use 10.5-point type.
+.ds FAM P    \" Use Palatino font family.
+
+
+ +

In the foregoing, we see that \" begins a comment. This is an +example of an escape sequence, the other kind of formatting +instruction. Escape sequences can appear anywhere. They begin with the +escape character (\) and are followed by at least one more +character. ms documents +tend to use only a few of groff’s many requests and escape +sequences; see Request Index and Escape Sequence Index or +the groff(7) man page for complete lists. +

+
+
\"
+

Begin comment; ignore remainder of line. +

+
+
\n[reg]
+

Interpolate value of register reg. +

+
+
\*[str]
+

Interpolate contents of string str. +

+
+
\*s
+

abbreviation of \*[s]; the name s must be only one +character +

+
+
\[char]
+

Interpolate glyph of special character named char. +

+
+
\&
+

dummy character +

+
+
\~
+

Insert an unbreakable space that is adjustable like a normal space. +

+
+
\|
+

Move horizontally by one-sixth em (“thin space”). +

+
+ +

Prefix any words that start with a dot ‘.’ or neutral apostrophe +‘'’ with \& if they are at the beginning of an input line +(or might become that way in editing) to prevent them from being +interpreted as macro calls or requests. Suffix ‘.’, ‘?’, and +‘!’ with \& when needed to cancel end-of-sentence detection. +

+
+
+
My exposure was \&.5 to \&.6 Sv of neutrons, said Dr.\&
+Wallace after the criticality incident.
+
+
+ + +
+
+
+
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+

4.6.2 Document Structure

+ + +

The ms macro package expects a certain amount of structure: +a well-formed document contains at least one paragraphing or heading +macro call. Longer documents have a structure as follows. +

+
+
Document type
+

Calling the RP macro at the beginning of your document puts the +document description (see below) on a cover page. Otherwise, ms +places the information (if any) on the first page, followed immediately +by the body text. Some document types found in other ms +implementations are specific to AT&T or Berkeley, and are not +supported by groff ms. +

+
+
Format and layout
+

By setting registers and strings, you can configure your document’s +typeface, margins, spacing, headers and footers, and footnote +arrangement. See Document Control Settings. +

+
+
Document description
+

A document description consists of any of: a title, one or more authors’ +names and affiliated institutions, an abstract, and a date or other +identifier. See Document Description Macros. +

+
+
Body text
+

The main matter of your document follows its description (if any). +ms supports highly structured text consisting of paragraphs +interspersed with multi-level headings (chapters, sections, subsections, +and so forth) and augmented by lists, footnotes, tables, diagrams, and +similar material. See Body Text. +

+
+
Tables of contents
+

Macros enable the collection of entries for a table of contents (or +index) as the material they discuss appears in the document. You then +call a macro to emit the table of contents at the end of your document. +The table of contents must necessarily follow the rest of the text since +GNU troff is a single-pass formatter; it thus cannot determine +the page number of a division of the text until it has been set and +output. Since ms was designed for the production of hard copy, +the traditional procedure was to manually relocate the pages containing +the table of contents between the cover page and the body text. Today, +page resequencing is more often done in the digital domain. An index +works similarly, but because it typically needs to be sorted after +collection, its preparation requires separate processing. +

+
+ + +
+
+
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+

4.6.3 Document Control Settings

+ + +

ms exposes many aspects of document layout to user control via +groff requests. To use them, you must understand how to define +registers and strings. +

+
+
Request: .nr reg value
+
+

Set register reg to value. If reg doesn’t exist, GNU +troff creates it. +

+ +
+
Request: .ds name contents
+
+

Set string name to contents. +

+ +

A list of document control registers and strings follows. For any +parameter whose default is unsatisfactory, define its register or string +before calling any ms macro other than RP. +

+ +
+

Margin settings

+ +
+
Register: \n[PO]
+
+

Defines the page offset (i.e., the left margin). +

+

Effective: next page. +

+

Default: Varies by output device and paper format; 1i is used for +typesetters using U.S. letter paper, and zero for terminals. +See Paper Format. +

+ +
+
Register: \n[LL]
+
+

Defines the line length (i.e., the width of the body text). +

+

Effective: next paragraph. +

+

Default: Varies by output device and paper format; 6.5i is used +for typesetters using U.S. letter paper (see Paper Format) and +65n on terminals. +

+ +
+
Register: \n[LT]
+
+

Defines the title line length (i.e., the header and footer width). This +is usually the same as LL, but need not be. +

+

Effective: next paragraph. +

+

Default: Varies by output device and paper format; 6.5i is used +for typesetters using U.S. letter paper (see Paper Format) and +65n on terminals. +

+ +
+
Register: \n[HM]
+
+

Defines the header margin height at the top of the page. +

+

Effective: next page. +

+

Default: 1i. +

+ +
+
Register: \n[FM]
+
+

Defines the footer margin height at the bottom of the page. +

+

Effective: next page. +

+

Default: 1i. +

+ +
+
+

Titles (headers, footers)

+ +
+
String: \*[LH]
+
+

Defines the text displayed in the left header position. +

+

Effective: next header. +

+

Default: empty. +

+ +
+
String: \*[CH]
+
+

Defines the text displayed in the center header position. +

+

Effective: next header. +

+

Default: ‘-\n[%]-’. +

+ +
+
String: \*[RH]
+
+

Defines the text displayed in the right header position. +

+

Effective: next header. +

+

Default: empty. +

+ +
+
String: \*[LF]
+
+

Defines the text displayed in the left footer position. +

+

Effective: next footer. +

+

Default: empty. +

+ +
+
String: \*[CF]
+
+

Defines the text displayed in the center footer position. +

+

Effective: next footer. +

+

Default: empty. +

+ +
+
String: \*[RF]
+
+

Defines the text displayed in the right footer position. +

+

Effective: next footer. +

+

Default: empty. +

+ +
+
+

Text settings

+ +
+
Register: \n[PS]
+
+

Defines the type size of the body text. +

+

Effective: next paragraph. +

+

Default: 10p. +

+ +
+
Register: \n[VS]
+
+

Defines the vertical spacing (type size plus leading). +

+

Effective: next paragraph. +

+

Default: 12p. +

+ +
+
Register: \n[HY]
+
+

Defines the automatic hyphenation mode used with the hy request. +Setting HY to 0 is equivalent to using the nh +request. This is a Tenth Edition Research Unix extension. +

+

Effective: next paragraph. +

+

Default: 6. +

+ +
+
String: \*[FAM]
+
+

Defines the font family used to typeset the document. This is a GNU +extension. +

+

Effective: next paragraph. +

+

Default: defined by the output device; often ‘T’ (see Body Text) +

+ +
+
+

Paragraph settings

+ +
+
Register: \n[PI]
+
+

Defines the indentation amount used by the PP, IP (unless +overridden by an optional argument), XP, and RS macros. +

+

Effective: next paragraph. +

+

Default: 5n. +

+ +
+
Register: \n[PD]
+
+

Defines the space between paragraphs. +

+

Effective: next paragraph. +

+

Default: 0.3v (1v on low-resolution devices). +

+ +
+
Register: \n[QI]
+
+

Defines the indentation amount used on both sides of a paragraph set +with the QP or between the QS and QE macros. +

+

Effective: next paragraph. +

+

Default: 5n. +

+ +
+
Register: \n[PORPHANS]
+
+

Defines the minimum number of initial lines of any paragraph that must +be kept together to avoid isolated lines at the bottom of a page. If a +new paragraph is started close to the bottom of a page, and there is +insufficient space to accommodate PORPHANS lines before an +automatic page break, then a page break is forced before the start of +the paragraph. This is a GNU extension. +

+

Effective: next paragraph. +

+

Default: 1. +

+ +
+
+

Heading settings

+ +
+
Register: \n[PSINCR]
+
+

Defines an increment in type size to be applied to a heading at a +lesser depth than that specified in GROWPS. The value of +PSINCR should be specified in points with the p scaling +unit and may include a fractional component; for example, ‘.nr PSINCR 1.5p’ sets a type size increment of 1.5p. This is a GNU +extension. +

+

Effective: next heading. +

+

Default: 1p. +

+ +
+
Register: \n[GROWPS]
+
+

Defines the heading depth above which the type size increment set by +PSINCR becomes effective. For each heading depth less than the +value of GROWPS, the type size is increased by PSINCR. +Setting GROWPS to any value less than 2 disables the +incremental heading size feature. This is a GNU extension. +

+

Effective: next heading. +

+

Default: 0. +

+ +
+
Register: \n[HORPHANS]
+
+

Defines the minimum number of lines of an immediately succeeding +paragraph that should be kept together with any heading introduced by +the NH or SH macros. If a heading is placed close to the +bottom of a page, and there is insufficient space to accommodate both +the heading and at least HORPHANS lines of the following +paragraph, before an automatic page break, then the page break is forced +before the heading. This is a GNU extension. +

+

Effective: next paragraph. +

+

Default: 1. +

+ +
+
String: \*[SN-STYLE]
+
+

Defines the style used to print numbered headings. See Headings. This is a GNU extension. +

+

Effective: next heading. +

+

Default: alias of SN-DOT +

+ +
+
+

Footnote settings

+ +
+
Register: \n[FI]
+
+

Defines the footnote indentation. This is a Berkeley extension. +

+

Effective: next footnote. +

+

Default: 2n. +

+ +
+
Register: \n[FF]
+
+

Defines the format of automatically numbered footnotes, +and those for which the FS request is given a marker argument, at +the bottom of a column or page. This is a Berkeley extension. +

+
0
+

Set an automatic number8 as a +superscript (on typesetter devices) or surrounded by square brackets (on +terminals). The footnote paragraph is indented as with PP if +there is an FS argument or an automatic number, and as with +LP otherwise. This is the default. +

+
+
1
+

As 0, but set the marker as regular text and follow an +automatic number with a period. +

+
+
2
+

As 1, but without indentation (like LP). +

+
+
3
+

As 1, but set the footnote paragraph with the marker hanging +(like IP). +

+
+ +

Effective: next footnote. +

+

Default: 0. +

+ +
+
Register: \n[FPS]
+
+

Defines the footnote type size. +

+

Effective: next footnote. +

+

Default: \n[PS] - 2p. +

+ +
+
Register: \n[FVS]
+
+

Defines the footnote vertical spacing. +

+

Effective: next footnote. +

+

Default: \n[FPS] + 2p. +

+ +
+
Register: \n[FPD]
+
+

Defines the footnote paragraph spacing. This is a GNU extension. +

+

Effective: next footnote. +

+

Default: \n[PD] / 2. +

+ +
+
String: \*[FR]
+
+

Defines the ratio of the footnote line length to the current line +length. This is a GNU extension. +

+

Effective: next footnote in single-column arrangements, next page +otherwise. +

+

Default: 11/12. +

+ +
+
+

Display settings

+ +
+
Register: \n[DD]
+
+

Sets the display distance—the vertical spacing before and after a +display, a tbl table, an eqn equation, or a pic +image. This is a Berkeley extension. +

+

Effective: next display boundary. +

+

Default: 0.5v (1v on low-resolution devices). +

+ +
+
Register: \n[DI]
+
+

Sets the default amount by which to indent a display started with +DS and ID without arguments, to ‘.DS I’ without +an indentation argument, and to equations set with ‘.EQ I’. +This is a GNU extension. +

+

Effective: next indented display. +

+

Default: 0.5i. +

+ +
+
+

Other settings

+ +
+
Register: \n[MINGW]
+
+

Defines the default minimum width between columns in a multi-column +document. This is a GNU extension. +

+

Effective: next page. +

+

Default: 2n. +

+ +
+
Register: \n[TC-MARGIN]
+
+

Defines the width of the field in which page numbers are set in a table +of contents entry; the right margin thus moves inboard by this amount. +This is a GNU extension. +

+

Effective: next PX call. +

+

Default: \w'000' +

+ + + +
+
+
+
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+

4.6.4 Document Description Macros

+ + + +

Only the simplest document lacks a title.9 As its level of sophistication (or +complexity) increases, it tends to acquire a date of revision, +explicitly identified authors, sponsoring institutions for authors, and, +at the rarefied heights, an abstract of its content. Define these +data by calling the macros below in the order shown; DA or +ND can be called to set the document date (or other identifier) +at any time before (a) the abstract, if present, or (b) its information +is required in a header or footer. Use of these macros is optional, +except that TL is mandatory if any of RP, AU, +AI, or AB is called, and AE is mandatory if +AB is called. +

+
+
Macro: .RP [no-repeat-info] [no-renumber]
+
+

Use the “report” (AT&T: “released paper”) format for your +document, creating a separate cover page. The default arrangement is to +place most of the document description (title, author names and +institutions, and abstract, but not the date) at the top of the first +page. If the optional no-repeat-info argument is given, +ms produces a cover page but does not repeat any of its +information subsequently (but see the DA macro below regarding +the date). Normally, RP sets the page number following the cover +page to 1. Specifying the optional no-renumber argument +suppresses this alteration. Optional arguments can occur in any order. +no is recognized as a synonym of no-repeat-info for +AT&T compatibility. +

+ +
+
Macro: .TL
+
+

Specify the document title. ms collects text on input lines +following this call into the title until reaching AU, AB, +or a heading or paragraphing macro call. +

+ +
+
Macro: .AU
+
+

Specify an author’s name. ms collects text on input lines +following this call into the author’s name until reaching AI, +AB, another AU, or a heading or paragraphing macro call. +Call it repeatedly to specify multiple authors. +

+ +
+
Macro: .AI
+
+

Specify the preceding author’s institution. An AU call is +usefully followed by at most one AI call; if there are more, the +last AI call controls. ms collects text on input lines +following this call into the author’s institution until reaching +AU, AB, or a heading or paragraphing macro call. +

+ +
+
Macro: .DA [x …]
+
+

Typeset the current date, or any arguments x, in the center +footer, and, if RP is also called, left-aligned at the end of the +description information on the cover page. +

+ +
+
Macro: .ND [x …]
+
+

Typeset the current date, or any arguments x, if RP is also +called, left-aligned at the end of the document description on the cover +page. This is groff ms’s default. +

+ +
+
Macro: .AB [no]
+
+

Begin the abstract. ms collects text on input lines following +this call into the abstract until reaching an AE call. By +default, ms places the word “ABSTRACT” centered and in italics +above the text of the abstract. The optional argument no +suppresses this heading. +

+ +
+
Macro: .AE
+
+

End the abstract. +

+ +

An example document description, using a cover page, follows. + + +

+
+
+
.RP
+.TL
+The Inevitability of Code Bloat
+in Commercial and Free Software
+.AU
+J.\& Random Luser
+.AI
+University of West Bumblefuzz
+.AB
+This report examines the long-term growth of the code
+bases in two large,
+popular software packages;
+the free Emacs and the commercial Microsoft Word.
+While differences appear in the type or order of
+features added,
+due to the different methodologies used,
+the results are the same in the end.
+.PP
+The free software approach is shown to be superior in
+that while free software can become as bloated as
+commercial offerings,
+free software tends to have fewer serious bugs and the
+added features are more in line with user demand.
+.AE
+
+…the rest of the paper…
+
+
+ + +
+
+
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+

4.6.5 Body Text

+ + +

A variety of macros, registers, and strings can be used to structure and +style the body of your document. They organize your text into +paragraphs, headings, footnotes, and inclusions of material such as +tables and figures. +

+ + + +
+
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+

4.6.5.1 Text settings

+ + +

The FAM string, a GNU extension, sets the font family for body +text; the default is ‘T’. The PS and VS registers +set the type size and vertical spacing (distance between text +baselines), respectively. The font family and type size are ignored on +terminal devices. Setting these parameters before the first call of a +heading, paragraphing, or (non-date) document description macro also +applies them to headers, footers, and (for FAM) footnotes. +

+

Which font families are available depends on the output device; as a +convention, T selects a serif family (“Times”), H a +sans-serif family (“Helvetica”), and C a monospaced family +(“Courier”). The man page for the output driver documents its font +repertoire. Consult the groff(1) man page for lists of +available output devices and their drivers. +

+

The hyphenation mode (as used by the hy request) is set from the +HY register. Setting HY to ‘0’ is equivalent to +using the nh request. This is a Tenth Edition Research Unix +extension. +

+ +
+
+
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+

4.6.5.2 Typographical symbols

+ + +

ms provides a few strings to obtain typographical symbols not +easily entered with the keyboard. These and many others are available +as special character escape sequences—see the groff_char(7) +man page. +

+
+
String: \*[-]
+
+

Interpolate an em dash. +

+ +
+
String: \*[Q]
+
+
String: \*[U]
+
+

Interpolate typographer’s quotation marks where available, and neutral +double quotes otherwise. \*Q is the left quote and \*U +the right. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+

4.6.5.3 Paragraphs

+ + +

Paragraphing macros break, or terminate, any pending output line +so that a new paragraph can begin. Several paragraph types are +available, differing in how indentation applies to them: to left, right, +or both margins; to the first output line of the paragraph, all output +lines, or all but the first. All paragraphing macro calls cause the +insertion of vertical space in the amount stored in the PD +register, except at page or column breaks. Alternatively, a blank input +line breaks the output line and vertically spaces by one vee. +

+
+
Macro: .LP
+
+

Set a paragraph without any (additional) indentation. +

+ +
+
Macro: .PP
+
+

Set a paragraph with a first-line left indentation in the amount stored +in the PI register. +

+ +
+
Macro: .IP [marker [width]]
+
+

Set a paragraph with a left indentation. The optional marker is +not indented and is empty by default. It has several applications; +see Lists. width overrides the indentation amount +stored in the PI register; its default unit is ‘n’. Once +specified, width applies to further IP calls until +specified again or a heading or different paragraphing macro is called. +

+ +
+
Macro: .QP
+
+

Set a paragraph indented from both left and right margins by the amount +stored in the QI register. +

+ +
+
Macro: .QS
+
+
Macro: .QE
+
+

Begin (QS) and end (QE) a region where each paragraph is +indented from both margins by the amount stored in the QI +register. The text between QS and QE can be structured +further by use of other paragraphing macros. +

+ +
+
Macro: .XP
+
+

Set an “exdented” paragraph—one with a left indentation in the +amount stored in the PI register on every line except the +first (also known as a hanging indent). This is a Berkeley extension. +

+ +

The following example illustrates the use of paragraphing macros. +

+
+
+
.NH 2
+Cases used in the 2001 study
+.LP
+Two software releases were considered for this report.
+.PP
+The first is commercial software;
+the second is free.
+.IP \[bu]
+Microsoft Word for Windows,
+starting with version 1.0 through the current version
+(Word 2000).
+.IP \[bu]
+GNU Emacs,
+from its first appearance as a standalone editor through
+the current version (v20).
+See [Bloggs 2002] for details.
+.QP
+Franklin's Law applied to software:
+software expands to outgrow both RAM and disk space over
+time.
+.SH
+Bibliography
+.XP
+Bloggs, Joseph R.,
+.I "Everyone's a Critic" ,
+Underground Press, March 2002.
+A definitive work that answers all questions and
+criticisms about the quality and usability of free
+software.
+
+
+ + +
+
+
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+

4.6.5.4 Headings

+ + +

Use headings to create a sequential or hierarchical structure for your +document. The ms macros print headings in bold using +the same font family and, by default, type size as the body text. +Headings are available with and without automatic numbering. Text on +input lines following the macro call becomes the heading’s title. Call +a paragraphing macro to end the heading text and start the section’s +content. +

+
+
Macro: .NH [depth]
+
+
Macro: .NH S heading-depth-index …
+

Set an automatically numbered heading. +

+

ms produces a numbered heading the form a.b.c…, to +any depth desired, with the numbering of each depth increasing +automatically and being reset to zero when a more significant level is +increased. “1” is the most significant or coarsest division of +the document. Only non-zero values are output. If depth is +omitted, it is taken to be ‘1’. +

+

If you specify depth such that an ascending gap occurs relative to +the previous NH call—that is, you “skip a depth”, as by +‘.NH 1’ and then ‘.NH 3’—groff ms emits a +warning on the standard error stream. +

+

Alternatively, you can give NH a first argument of S, +followed by integers to number the heading depths explicitly. Further +automatic numbering, if used, resumes using the specified indices as +their predecessors. +This feature is a Berkeley extension. +

+ +

An example may be illustrative. +

+
+
+
.NH 1
+Animalia
+.NH 2
+Arthropoda
+.NH 3
+Crustacea
+.NH 2
+Chordata
+.NH S 6 6 6
+Daimonia
+.NH 1
+Plantae
+
+
+ +

The above results in numbering as follows; the vertical space that +normally precedes each heading is omitted. +

+
+
1.  Animalia
+1.1.  Arthropoda
+1.1.1.  Crustacea
+1.2.  Chordata
+6.6.6.  Daimonia
+7.  Plantae
+
+ +
+
String: \*[SN-STYLE]
+
+
String: \*[SN-DOT]
+
+
String: \*[SN-NO-DOT]
+
+
String: \*[SN]
+
+

After NH is called, the assigned number is made available in the +strings SN-DOT (as it appears in a printed heading with default +formatting, followed by a terminating period) and SN-NO-DOT (with +the terminating period omitted). These are GNU extensions. +

+

You can control the style used to print numbered headings by defining an +appropriate alias for the string SN-STYLE. By default, +SN-STYLE is aliased to SN-DOT. If you prefer to omit the +terminating period from numbers appearing in numbered headings, you may +define the alias as follows. +

+
+
.als SN-STYLE SN-NO-DOT
+
+ +

Any such change in numbering style becomes effective from the next use +of NH following redefinition of the alias for SN-STYLE. +The formatted number of the current heading is available in the +SN string (a feature first documented by Berkeley), which +facilitates its inclusion in, for example, table captions, equation +labels, and XS/XA/XE table of contents entries. +

+ +
+
Macro: .SH [depth]
+
+

Set an unnumbered heading. +

+

The optional depth argument is a GNU extension indicating the +heading depth corresponding to the depth argument of NH. +It matches the type size at which the heading is set to that of a +numbered heading at the same depth when the GROWPS and +PSINCR heading size adjustment mechanism is in effect. +

+ +

If the GROWPS register is set to a value greater than the +level argument to NH or SH, the type size of a +heading produced by these macros increases by PSINCR units over +the size specified by PS multiplied by the difference of +GROWPS and level. The value stored in PSINCR is +interpreted in groff basic units; the p scaling unit +should be employed when assigning a value specified in points. For +example, the sequence +

+
+
+
.nr PS 10
+.nr GROWPS 3
+.nr PSINCR 1.5p
+.NH 1
+Carnivora
+.NH 2
+Felinae
+.NH 3
+Felis catus
+.SH 2
+Machairodontinae
+
+
+ +

will cause “1. Carnivora” to be printed in 13-point text, followed by +“1.1. Felinae” in 11.5-point text, while “1.1.1. Felis catus” and +all more deeply nested heading levels will remain in the 10-point text +specified by the PS register. “Machairodontinae” is printed at +11.5 points, since it corresponds to heading level 2. +

+

The HORPHANS register operates in conjunction with the NH +and SH macros to inhibit the printing of isolated headings at the +bottom of a page; it specifies the minimum number of lines of an +immediately subsequent paragraph that must be kept on the same page as +the heading. If insufficient space remains on the current page to +accommodate the heading and this number of lines of paragraph text, a +page break is forced before the heading is printed. Any display macro +call or tbl, pic, or eqn region between the heading +and the subsequent paragraph suppresses this grouping. See Keeps, boxed keeps, and displays and Tables, figures, equations, and references. +

+ +
+
+
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+

4.6.5.5 Typeface and decoration

+ +

The ms macros provide a variety of ways to style text. +Attend closely to the ordering of arguments labeled pre and +post, which is not intuitive. Support for pre +arguments is a GNU extension.10 +

+
+
Macro: .B [text [post [pre]]]
+
+

Style text in bold, followed by post in the previous +font style without intervening space, and preceded by pre +similarly. Without arguments, ms styles subsequent text in bold +until the next paragraphing, heading, or no-argument typeface macro +call. +

+ +
+
Macro: .R [text [post [pre]]]
+
+

As B, but use the roman style (upright text of normal weight) +instead of bold. Argument recognition is a GNU extension. +

+ +
+
Macro: .I [text [post [pre]]]
+
+

As B, but use an italic or oblique style instead of bold. +

+ +
+
Macro: .BI [text [post [pre]]]
+
+

As B, but use a bold italic or bold oblique style instead of +upright bold. This is a Tenth Edition Research Unix extension. +

+ +
+
Macro: .CW [text [post [pre]]]
+
+

As B, but use a constant-width (monospaced) roman typeface +instead of bold. This is a Tenth Edition Research Unix extension. +

+ +
+
Macro: .BX [text]
+
+

Typeset text and draw a box around it. On terminal devices, +reverse video is used instead. If you want text to contain space, +use unbreakable space or horizontal motion escape sequences (\~, +\SP, \^, \|, \0 or \h). +

+ +
+
Macro: .UL [text [post]]
+
+

Typeset text with an underline. post, if present, is set +after text with no intervening space. +

+ +
+
Macro: .LG
+
+

Set subsequent text in larger type (two points larger than the +current size) until the next type size, paragraphing, or heading macro +call. You can specify this macro multiple times to enlarge the type +size as needed. +

+ +
+
Macro: .SM
+
+

Set subsequent text in smaller type (two points smaller than the current +size) until the next type size, paragraphing, or heading macro call. +You can specify this macro multiple times to reduce the type size as +needed. +

+ +
+
Macro: .NL
+
+

Set subsequent text at the normal type size (the amount in the PS +register). +

+ +

pre and post arguments are typically used to simplify the +attachment of punctuation to styled words. When pre is used, +a hyphenation control escape sequence \% that would ordinarily +start text must start pre instead to have the desired +effect. +

+
+
+
The CS course's students found one C language keyword
+.CW static ) \%(
+most troublesome.
+
+
+ +

The foregoing example produces output as follows. +

+
+
+
The CS course’s students found one C language keyword (static)
+most troublesome.
+
+
+ +

You can use the output line continuation escape sequence \c to +achieve the same result (see Line Continuation). It is also +portable to older ms implementations. +

+
+
+
The CS course's students found one C language keyword
+\%(\c
+.CW \%static )
+most troublesome.
+
+
+ +

groff ms also offers strings to begin and end super- and +subscripting. These are GNU extensions. +

+
+
String: \*[{]
+
+
String: \*[}]
+
+

Begin and end superscripting, respectively. +

+ +
+
String: \*[<]
+
+
String: \*[>]
+
+

Begin and end subscripting, respectively. +

+ +

Rather than calling the CW macro, in groff ms you +might prefer to change the font family to Courier by setting the +FAM string to ‘C’. You can then use all four style macros +above, returning to the default family (Times) with ‘.ds FAM T’. +Because changes to FAM take effect only at the next paragraph, +CW remains useful to “inline” a change to the font family, +similarly to the practice of this document in noting syntactical +elements of ms and groff. +

+ +
+
+
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+

4.6.5.6 Lists

+ + +

The marker argument to the IP macro can be employed to +present a variety of lists; for instance, you can use a bullet glyph +(\[bu]) for unordered lists, a number (or auto-incrementing +register) for numbered lists, or a word or phrase for glossary-style or +definition lists. If you set the paragraph indentation register +PI before calling IP, you can later reorder the items in +the list without having to ensure that a width argument remains +affixed to the first call. +

+

The following is an example of a bulleted list. + + +

+
+
+
.nr PI 2n
+A bulleted list:
+.IP \[bu]
+lawyers
+.IP \[bu]
+guns
+.IP \[bu]
+money
+
+
+ +
+
A bulleted list:
+
+• lawyers
+
+• guns
+
+• money
+
+ +

The following is an example of a numbered list. + + +

+
+
+
.nr step 0 1
+.nr PI 3n
+A numbered list:
+.IP \n+[step]
+lawyers
+.IP \n+[step]
+guns
+.IP \n+[step]
+money
+
+
+ +
+
A numbered list:
+
+1. lawyers
+
+2. guns
+
+3. money
+
+ +

Here we have employed the nr request to create a register of our +own, ‘step’. We initialized it to zero and assigned it an +auto-increment of 1. Each time we use the escape sequence +‘\n+[PI]’ (note the plus sign), the formatter applies the increment +just before interpolating the register’s value. Preparing the PI +register as well enables us to rearrange the list without the tedium of +updating macro calls. +

+

The next example illustrates a glossary-style list. + + +

+
+
+
A glossary-style list:
+.IP lawyers 0.4i
+Two or more attorneys.
+.IP guns
+Firearms,
+preferably large-caliber.
+.IP money
+Gotta pay for those
+lawyers and guns!
+
+
+ +
+
A glossary-style list:
+
+lawyers
+      Two or more attorneys.
+
+guns  Firearms, preferably large-caliber.
+
+money
+      Gotta pay for those lawyers and guns!
+
+ +

In the previous example, observe how the IP macro places the +definition on the same line as the term if it has enough space. If this +is not what you want, there are a few workarounds we will illustrate by +modifying the example. First, you can use a br request to force +a break after printing the term or label. +

+
+
+
.IP guns
+.br
+Firearms,
+
+
+ +

Second, you could apply the \p escape sequence to force a break. +The space following the escape sequence is important; if you omit it, +groff prints the first word of the paragraph text on the same +line as the term or label (if it fits) then breaks the line. +

+
+
+
.IP guns
+\p Firearms,
+
+
+ +

Finally, you may append a horizontal motion to the marker with the +\h escape sequence; using the same amount as the indentation will +ensure that the marker is too wide for groff to treat it as +“fitting” on the same line as the paragraph text. +

+
+
+
.IP guns\h'0.4i'
+Firearms,
+
+
+ +

In each case, the result is the same. +

+
+
A glossary-style list:
+
+lawyers
+      Two or more attorneys.
+
+guns
+      Firearms, preferably large-caliber.
+
+money
+      Gotta pay for those lawyers and guns!
+
+ + +
+
+
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+

4.6.5.7 Indented regions

+ +

You may need to indent a region of text while otherwise formatting it +normally. Indented regions can be nested; you can change \n[PI] +before each call to vary the amount of inset. +

+
+
Macro: .RS
+
+

Begin a region where headings, paragraphs, and displays are indented +(further) by the amount stored in the PI register. +

+ +
+
Macro: .RE
+
+

End the (next) most recent indented region. +

+ +

This feature enables you to easily line up text under hanging and +indented paragraphs. + + +For example, you may wish to structure lists hierarchically. +

+
+
+
.IP \[bu] 2
+Lawyers:
+.RS
+.IP \[bu]
+Dewey,
+.IP \[bu]
+Cheatham,
+and
+.IP \[bu]
+and Howe.
+.RE
+.IP \[bu]
+Guns
+
+
+ +
+
• Lawyers:
+
+  •  Dewey,
+
+  •  Cheatham, and
+
+  •  Howe.
+
+• Guns
+
+ + +
+
+
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+

4.6.5.8 Keeps, boxed keeps, and displays

+ + + + +

On occasion, you may want to keep several lines of text, or a +region of a document, together on a single page, preventing an automatic +page break within certain boundaries. This can cause a page break to +occur earlier than it normally would. For example, you may want to keep +two paragraphs together, or a paragraph that refers to a table, list, or +figure adjacent to the item it discusses. ms provides the +KS and KE macros for this purpose. +

+

You can alternatively specify a floating keep: if a keep cannot +fit on the current page, ms holds its contents and +allows material following the keep (in the source document) to fill the +remainder of the current page. When the page breaks, whether by +reaching the end or bp request, ms puts the floating keep +at the beginning of the next page. This is useful for placing large +graphics or tables that do not need to appear exactly where they occur +in the source document. +

+
+
Macro: .KS
+
+
Macro: .KF
+
+
Macro: .KE
+
+

KS begins a keep, KF a floating keep, and KE ends a +keep of either kind. +

+ +

As an alternative to the keep mechanism, the ne request forces a +page break if there is not at least the amount of vertical space +specified in its argument remaining on the page (see Page Control). +One application of ne is to reserve space on the page for a +figure or illustration to be included later. +

+ +

A boxed keep has a frame drawn around it. +

+
+
Macro: .B1
+
+
Macro: .B2
+
+

B1 begins a keep with a box drawn around it. B2 ends a +boxed keep. +

+ +

Boxed keep macros cause breaks; if you need to box a word or phrase +within a line, see the BX macro in Typeface and decoration. +Box lines are drawn as close as possible to the text they enclose so +that they are usable within paragraphs. If you wish to box one or more +paragraphs, you may improve the appearance by calling B1 after +the first paragraphing macro, and by adding a small amount of vertical +space before calling B2. +

+
+
+
.LP
+.B1
+.I Warning:
+Happy Fun Ball may suddenly accelerate to dangerous
+speeds.
+.sp \n[PD]/2 \" space by half the inter-paragraph distance
+.B2
+
+
+ +

If you want a boxed keep to float, you will need to enclose the +B1 and B2 calls within a pair of KF and KE +calls. +

+ +

Displays turn off filling; lines of verse or program code are +shown with their lines broken as in the source document without +requiring br requests between lines. Displays can be kept on a +single page or allowed to break across pages. The DS macro +begins a kept display of the layout specified in its first argument; +non-kept displays are begun with dedicated macros corresponding to their +layout. +

+
+
Macro: .DS L
+
+
Macro: .LD
+
+

Begin (DS: kept) left-aligned display. +

+ +
+
Macro: .DS [I [indent]]
+
+
Macro: .ID [indent]
+
+

Begin (DS: kept) display indented by indent if specified, +and by the amount of the DI register otherwise. +

+ +
+
Macro: .DS B
+
+
Macro: .BD
+
+

Begin a (DS: kept) a block display: the entire display is +left-aligned, but indented such that the longest line in the display +is centered on the page. +

+ +
+
Macro: .DS C
+
+
Macro: .CD
+
+

Begin a (DS: kept) centered display: each line in the display +is centered. +

+ +
+
Macro: .DS R
+
+
Macro: .RD
+
+

Begin a (DS: kept) right-aligned display. This is a GNU +extension. +

+ +
+
Macro: .DE
+
+

End any display. +

+ +

The distance stored in the DD register is inserted before and +after each pair of display macros; this is a Berkeley extension. In +groff ms, this distance replaces any adjacent +inter-paragraph distance or subsequent spacing prior to a section +heading. The DI register is a GNU extension; its value is an +indentation applied to displays created with ‘.DS’ and ‘.ID’ +without arguments, to ‘.DS I’ without an indentation argument, and +to indented equations set with ‘.EQ’. Changes to either register +take effect at the next display boundary. +

+ +
+
+
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+

4.6.5.9 Tables, figures, equations, and references

+ + + + + + + + + +

The ms package is often used with the tbl, pic, +eqn, and refer preprocessors. + + + + +Mark text meant for preprocessors by enclosing it in pairs of tokens +as follows, with nothing between the dot and the macro name. The +preprocessors match these tokens only at the start of an input line. +

+
+
Macro: .TS [H]
+
+
Macro: .TE
+
+

Demarcate a table to be processed by the tbl preprocessor. The +optional argument H to TS instructs ms to +repeat table rows (often column headings) at the top of each new page +the table spans, if applicable; calling the TH macro marks the +end of such rows. The GNU tbl(1) man page provides a +comprehensive reference to the preprocessor and offers examples of its +use. +

+ +
+
Macro: .PS
+
+
Macro: .PE
+
+
Macro: .PF
+
+

PS begins a picture to be processed by the gpic +preprocessor; either of PE or PF ends it, the latter with +“flyback” to the vertical position at its top. You can create +pic input manually or with a program such as xfig. +

+ +
+
Macro: .EQ [align [label]]
+
+
Macro: .EN
+
+

Demarcate an equation to be processed by the eqn preprocessor. +The equation is centered by default; align can be ‘C’, +‘L’, or ‘I’ to (explicitly) center, left-align, or indent it +by the amount stored in the DI register, respectively. If +specified, label is set right-aligned. +

+ +
+
Macro: .[
+
+
Macro: .]
+
+

Demarcate a bibliographic citation to be processed by the refer +preprocessor. The GNU refer(1) man page provides a +comprehensive reference to the preprocessor and the format of its +bibliographic database. Type ‘man refer’ at the command line to +view it. +

+ +

When refer emits collected references (as might be done on a +“Works Cited” page), it interpolates the REFERENCES string as +an unnumbered heading (SH). +

+ + +

The following is an example of how to set up a table that may print +across two or more pages. +

+
+
+
.TS H
+allbox;
+Cb | Cb .
+Part→Description
+_
+.TH
+.T&
+GH-1978→Fribulating gonkulator
+…the rest of the table follows…
+.TE
+
+
+ +

Attempting to place a multi-page table inside a keep can lead to +unpleasant results, particularly if the tbl allbox option +is used. +

+ +

Mathematics can be typeset using the language of the eqn +preprocessor. +

+
+
+
.EQ C (\*[SN-NO-DOT]a)
+p ~ = ~ q sqrt { ( 1 + ~ ( x / q sup 2 ) }
+.EN
+
+
+ +

This input formats a labelled equation. We used the SN-NO-DOT +string to base the equation label on the current heading number, giving +us more flexibility to reorganize the document. +

+

Use groff options to run preprocessors on the input: +-e for geqn, -p for gpic, +-R for grefer, and -t for gtbl. +

+ +
+
+
+
+

+Previous: , Up: Body Text   [Contents][Index]

+
+

4.6.5.10 Footnotes

+ + + + + +

A footnote is typically anchored to a place in the text with a +marker, which is a small integer, a symbol such as a dagger, or +arbitrary user-specified text. +

+
+
String: \*[*]
+
+

Place an automatic number, an automatically generated numeric +footnote marker, in the text. Each time this string is interpolated, +the number it produces increments by one. Automatic numbers start at 1. +This is a Berkeley extension. +

+ +

Enclose the footnote text in FS and FE macro calls to set +it at the nearest available “foot”, or bottom, of a text column or +page. +

+
+
Macro: .FS [marker]
+
+
Macro: .FE
+
+

Begin (FS) and end (FE) a footnote. FS calls +FS-MARK with any supplied marker argument, which is then +also placed at the beginning of the footnote text. If marker is +omitted, the next pending automatic footnote number enqueued by +interpolation of the * string is used, and if none exists, +nothing is prefixed. +

+ +

You may not desire automatically numbered footnotes in spite of their +convenience. You can indicate a footnote with a symbol or other text by +specifying its marker at the appropriate place (for example, by using +\[dg] for the dagger glyph) and as an argument to the +FS macro. Such manual marks should be repeated as arguments to +FS or as part of the footnote text to disambiguate their +correspondence. You may wish to use \*{ and \*} to +superscript the marker at the anchor point, in the footnote text, or +both. +

+

groff ms provides a hook macro, FS-MARK, for +user-determined operations to be performed when the FS macro is +called. It is passed the same arguments as FS itself. An +application of FS-MARK is anchor placement for a hyperlink +reference, so that a footnote can link back to its referential +context.11 By default, this macro has an empty definition. +FS-MARK is a GNU extension. +

+ + + + +

Footnotes can be safely used within keeps and displays, but you should +avoid using automatically numbered footnotes within floating keeps. You +can place a second \** interpolation between a \** and its +corresponding FS call as long as each FS call occurs +after the corresponding \** and occurrences of FS +are in the same order as corresponding occurrences of \**. +

+

Footnote text is formatted as paragraphs are, using analogous +parameters. The registers FI, FPD, FPS, and +FVS correspond to PI, PD, PS, and CS, +respectively; FPD, FPS, and FVS are GNU extensions. +

+

The FF register controls the formatting of automatically numbered +footnote paragraphs and those for which FS is given a marker +argument. See Document Control Settings. +

+

The default footnote line length is 11/12ths of the normal line length +for compatibility with the expectations of historical ms +documents; you may wish to set the FR string to ‘1’ to align +with contemporary typesetting practices. In the +past,12 an FL register +was used for the line length in footnotes; however, setting this +register at document initialization time had no effect on the footnote +line length in multi-column arrangements.13 +

+

FR should be used in preference to the old FL register in +contemporary documents. The footnote line length is effectively +computed as ‘column-width * \*[FR]’. If an absolute +footnote line length is required, recall that arithmetic expressions in +roff input are evaluated strictly from left to right, with no +operator precedence (parentheses are honored). +

+
+
.ds FR 0+3i \" Set footnote line length to 3 inches.
+
+ + +
+
+
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+

4.6.5.11 Language and localization

+ + + + + +

groff ms provides several strings that you can customize +for your own purposes, or redefine to adapt the macro package to +languages other than English. It is already localized for +Czech, German, French, Italian, and Swedish. Load the desired +localization macro package after ms; see the +groff_tmac(5) man page. +

+
+
+
$ groff -ms -mfr bienvenue.ms
+
+
+ +

The following strings are available. +

+
+
String: \*[REFERENCES]
+
+

Contains the string printed at the beginning of a references +(bibliography) page produced with GNU refer(1). The default +is ‘References’. +

+ +
+
String: \*[ABSTRACT]
+
+

Contains the string printed at the beginning of the abstract. The +default is ‘\f[I]ABSTRACT\f[]’; it includes font selection escape +sequences to set the word in italics. +

+ +
+
String: \*[TOC]
+
+

Contains the string printed at the beginning of the table of contents. +The default is ‘Table of Contents’. +

+ +
+
String: \*[MONTH1]
+
+
String: \*[MONTH2]
+
+
String: \*[MONTH3]
+
+
String: \*[MONTH4]
+
+
String: \*[MONTH5]
+
+
String: \*[MONTH6]
+
+
String: \*[MONTH7]
+
+
String: \*[MONTH8]
+
+
String: \*[MONTH9]
+
+
String: \*[MONTH10]
+
+
String: \*[MONTH11]
+
+
String: \*[MONTH12]
+
+

Contain the full names of the calendar months. The defaults are in +English: ‘January’, ‘February’, and so on. +

+ + +
+
+
+
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+

4.6.6 Page layout

+ + + +

ms’s default page layout arranges text in a single column with +the page number between hyphens centered in a header on each page except +the first, and produces no footers. You can customize this arrangement. +

+ + + +
+
+
+

+Next: , Previous: , Up: Page layout   [Contents][Index]

+
+

4.6.6.1 Headers and footers

+ + + + + +

There are multiple ways to produce headers and footers. One is to +define the strings LH, CH, and RH to set the left, +center, and right headers, respectively; and LF, CF, and +RF to set the left, center, and right footers. This approach +suffices for documents that do not distinguish odd- and even-numbered +pages. +

+

Another method is to call macros that set headers or footers for odd- or +even-numbered pages. Each such macro takes a delimited argument +separating the left, center, and right header or footer texts from each +other. You can replace the neutral apostrophes (') shown below +with any character not appearing in the header or footer text. These +macros are Berkeley extensions. +

+
+
Macro: .OH 'left'center'right'
+
+
Macro: .EH 'left'center'right'
+
+
Macro: .OF 'left'center'right'
+
+
Macro: .EF 'left'center'right'
+
+

The OH and EH macros define headers for odd- (recto) +and even-numbered (verso) pages, respectively; the OF and +EF macros define footers for them. +

+ +

With either method, a percent sign % in header or footer text is +replaced by the current page number. By default, ms places no +header on a page numbered “1” (regardless of its number format). +

+
+
Macro: .P1
+
+

Typeset the header even on page 1. To be effective, this macro +must be called before the header trap is sprung on any page numbered +“1”; in practice, unless your page numbering is unusual, this means +that you should call it early, before TL or any heading or +paragraphing macro. This is a Berkeley extension. +

+ +

For even greater flexibility, ms is designed to permit the +redefinition of the macros that are called when the groff traps +that ordinarily cause the headers and footers to be output are sprung. +PT (“page trap”) is called by ms when the header is to +be written, and BT (“bottom trap”) when the footer is to be. +The groff page location trap that ms sets up to format the +header also calls the (normally undefined) HD macro after +PT; you can define HD if you need additional processing +after setting the header (for example, to draw a line below it). +The HD hook is a Berkeley extension. Any such macros you +(re)define must implement any desired specialization for odd-, even-, or +first numbered pages. +

+ +
+
+
+
+

+Next: , Previous: , Up: Page layout   [Contents][Index]

+
+

4.6.6.2 Tab stops

+ +

Use the ta request to define tab stops as needed. See Tabs and Fields. +

+
+
Macro: .TA
+
+

Reset the tab stops to the ms default (every 5 ens). +Redefine this macro to create a different set of default tab stops. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Page layout   [Contents][Index]

+
+

4.6.6.3 Margins

+ + +

Control margins using the registers summarized in “Margin settings” in +Document Control Settings above. There is no setting for the +right margin; the combination of page offset \n[PO] and line +length \n[LL] determines it. +

+ +
+
+
+
+

+Next: , Previous: , Up: Page layout   [Contents][Index]

+
+

4.6.6.4 Multiple columns

+ + + +

ms can set text in as many columns as reasonably fit on the page. +The following macros force a page break if a multi-column layout is +active when they are called. The MINGW register stores the +default minimum gutter width; it is a GNU extension. When multiple +columns are in use, keeps and the HORPHANS and PORPHANS +registers work with respect to column breaks instead of page breaks. +

+
+
Macro: .1C
+
+

Arrange page text in a single column (the default). +

+ +
+
Macro: .2C
+
+

Arrange page text in two columns. +

+ +
+
Macro: .MC [column-width [gutter-width]]
+
+

Arrange page text in multiple columns. If you specify no arguments, it +is equivalent to the 2C macro. Otherwise, column-width is +the width of each column and gutter-width is the minimum distance +between columns. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Page layout   [Contents][Index]

+
+

4.6.6.5 Creating a table of contents

+ + + +

Because roff formatters process their input in a single pass, +material on page 50, for example, cannot influence what appears on +page 1—this poses a challenge for a table of contents at its +traditional location in front matter, if you wish to avoid manually +maintaining it. ms enables the collection of material to be +presented in the table of contents as it appears, saving its page number +along with it, and then emitting the collected contents on demand toward +the end of the document. The table of contents can then be resequenced +to its desired location by physically rearranging the pages of a printed +document, or as part of post-processing—with a sed(1) +script to reorder the pages in troff’s output, with +pdfjam(1), or with gropdf(1)’s +‘.pdfswitchtopage’ feature, for example. +

+

Define an entry to appear in the table of contents by bracketing its +text between calls to the XS and XE macros. A typical +application is to call them immediately after NH or SH and +repeat the heading text within them. The XA macro, used within +‘.XS’/‘.XE’ pairs, supplements an entry—for instance, when +it requires multiple output lines, whether because a heading is too long +to fit or because style dictates that page numbers not be repeated. You +may wish to indent the text thus wrapped to correspond to its heading +depth; this can be done in the entry text by prefixing it with tabs or +horizontal motion escape sequences, or by providing a second argument to +the XA macro. XS and XA automatically associate +the page number where they are called with the text following them, but +they accept arguments to override this behavior. At the end of the +document, call TC or PX to emit the table of contents; +TC resets the page number to ‘i’ (Roman numeral one), and +then calls PX. All of these macros are Berkeley extensions. +

+
+
Macro: .XS [page-number]
+
+
Macro: .XA [page-number [indentation]]
+
+
Macro: .XE
+
+

Begin, supplement, and end a table of contents entry. Each entry is +associated with page-number (otherwise the current page number); a +page-number of ‘no’ prevents a leader and page number from +being emitted for that entry. Use of XA within +XS/XE is optional; it can be repeated. If +indentation is present, a supplemental entry is indented by that +amount; ens are assumed if no unit is indicated. Text on input lines +between XS and XE is stored for later recall by PX. +

+ +
+
Macro: .PX [no]
+
+

Switch to single-column layout. Unless no is specified, center +and interpolate the TOC string in bold and two points larger than +the body text. Emit the table of contents entries. +

+ +
+
Macro: .TC [no]
+
+

Set the page number to 1, the page number format to lowercase Roman +numerals, and call PX (with a no argument, if present). +

+ +

Here’s an example of typical ms table of contents preparation. +We employ horizontal escape sequences \h to indent the entries by +sectioning depth. +

+
+
+
.NH 1
+Introduction
+.XS
+Introduction
+.XE
+…
+.NH 2
+Methodology
+.XS
+\h'2n'Methodology
+.XA
+\h'4n'Fassbinder's Approach
+\h'4n'Kahiu's Approach
+.XE
+…
+.NH 1
+Findings
+.XS
+Findings
+.XE
+…
+.TC
+
+
+ +

The remaining features in this subsubsection are GNU extensions. +groff ms obviates the need to repeat heading text after +XS calls. Call XN and XH after NH and +SH, respectively. +

+
+
Macro: .XN heading-text
+
+
Macro: .XH depth heading-text
+
+

Format heading-text and create a corresponding table of contents +entry. XN computes the indentation from the depth of the +preceding NH call; XH requires a depth argument to +do so. +

+ +

groff ms encourages customization of table of contents +entry production. +

+
+
Macro: .XN-REPLACEMENT heading-text
+
+
Macro: .XH-REPLACEMENT depth heading-text
+
+

These hook macros implement XN and XH, respectively. +They call XN-INIT and pass their heading-text arguments to +XH-UPDATE-TOC. +

+ +
+
Macro: .XN-INIT
+
+
Macro: .XH-UPDATE-TOC depth heading-text
+
+

The XN-INIT hook macro does nothing by default. +XH-UPDATE-TOC brackets heading-text with XS and +XE calls, indenting it by 2 ens per level of depth beyond +the first. +

+ +

We could therefore produce a table of contents similar to that in the +previous example with fewer macro calls. (The difference is that this +input follows the “Approach” entries with leaders and page numbers.) +

+
+
+
.NH 1
+.XN Introduction
+…
+.NH 2
+.XN Methodology
+.XH 3 "Fassbinder's Approach"
+.XH 3 "Kahiu's Approach"
+…
+.NH 1
+.XN Findings
+…
+
+
+ +

To get the section number of the numbered headings into the table of +contents entries, we might define XN-REPLACEMENT as follows. +(We obtain the heading depth from groff ms’s internal +register nh*hl.) +

+
+
+
.de XN-REPLACEMENT
+.XN-INIT
+.XH-UPDATE-TOC \\n[nh*hl] \\$@
+\&\\*[SN] \\$*
+..
+
+
+ +

You can change the style of the leader that bridges each table of +contents entry with its page number; define the TC-LEADER special +character by using the char request. A typical leader combines +the dot glyph ‘.’ with a horizontal motion escape sequence to +spread the dots. The width of the page number field is stored in the +TC-MARGIN register. +

+ +
+
+
+
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+

4.6.7 Differences from AT&T ms

+ + + +

The groff ms macros are an independent reimplementation, +using no AT&T code. Since they take advantage of the extended +features of groff, they cannot be used with AT&T +troff. groff ms supports features described above +as Berkeley and Tenth Edition Research Unix extensions, and adds several +of its own. +

+
    +
  • The internals of groff ms differ from the internals of +AT&T ms. Documents that depend upon implementation +details of AT&T ms may not format properly with +groff ms. Such details include macros whose function was +not documented in the AT&T ms +manual.14 + +
  • The error-handling policy of groff ms is to detect and +report errors, rather than to ignore them silently. + +
  • Tenth Edition Research Unix supported P1/P2 macros to bracket code +examples; groff ms does not. + +
  • groff ms does not work in GNU troff’s +AT&T compatibility mode. If loaded when that mode is enabled, +it aborts processing with a diagnostic message. + +
  • Multiple line spacing is not supported. Use a larger vertical spacing +instead. + +
  • groff ms uses the same header and footer defaults in both +nroff and troff modes as AT&T ms does in +troff mode; AT&T’s default in nroff mode is to +put the date, in U.S. traditional format (e.g., “January 1, 2021”), +in the center footer (the CF string). + +
  • Many groff ms macros, including those for paragraphs, +headings, and displays, cause a reset of paragraph rendering parameters, +and may change the indentation; they do so not by incrementing or +decrementing it, but by setting it absolutely. This can cause problems +for documents that define additional macros of their own that try to +manipulate indentation. Use the ms RS and RE +macros instead of the in request. + +
  • + +AT&T ms interpreted the values of the registers +PS and VS in points, and did not support the use of +scaling units with them. groff ms interprets values of +the registers PS, VS, FPS, and FVS equal to +or larger than 1,000 (one thousand) as decimal fractions multiplied +by 1,000.15 This threshold makes use of a +scaling unit with these parameters practical for high-resolution +devices while preserving backward compatibility. It also permits +expression of non-integral type sizes. For example, ‘groff +-rPS=10.5p’ at the shell prompt is equivalent to placing ‘.nr PS +10.5p’ at the beginning of the document. + +
  • AT&T ms’s AU macro supported arguments used with +some document types; groff ms does not. + +
  • Right-aligned displays are available. The AT&T ms +manual observes that “it is tempting to assume that ‘.DS R’ will +right adjust lines, but it doesn’t work”. In groff ms, +it does. + +
  • To make groff ms use the default page offset (which also +specifies the left margin), the PO register must stay undefined +until the first ms macro is called. + +

    This implies that ‘\n[PO]’ should not be used early in the +document, unless it is changed also: accessing an undefined register +automatically defines it. +

    +
  • groff ms supports the PN register, but it is not +necessary; you can access the page number via the usual % +register and invoke the af request to assign a different format +to it if desired.16 + +
  • The AT&T ms manual documents registers CW and +GW as setting the default column width and “intercolumn gap”, +respectively, and which applied when MC was called with fewer +than two arguments. groff ms instead treats MC +without arguments as synonymous with 2C; there is thus no +occasion for a default column width register. Further, the MINGW +register and the second argument to MC specify a minimum +space between columns, not the fixed gutter width of AT&T +ms. + +
  • The AT&T ms manual did not document the QI +register; Berkeley and groff ms do. +
+ +
+
Register: \n[GS]
+
+

The register GS is set to 1 by the groff ms +macros, but is not used by the AT&T ms package. +Documents that need to determine whether they are being formatted with +groff ms or another implementation should test this +register. +

+ + + + +
+
+
+

+Previous: , Up: Differences from AT&T ms   [Contents][Index]

+
+

4.6.7.1 Unix Version 7 ms macros not implemented by groff ms

+ +

Several macros described in the Unix Version 7 ms +documentation are unimplemented by groff ms because they +are specific to the requirements of documents produced internally by +Bell Laboratories, some of which also require a glyph for the Bell +System logo that groff does not support. These macros +implemented several document type formats +(EG, IM, MF, MR, TM, TR), were meaningful only in conjunction with the use of certain document +types +(AT, CS, CT, OK, SG), stored the postal addresses of Bell Labs sites +(HO, IH, MH, PY, WH), or lacked a stable definition over time +(UX). To compatibly render historical ms documents using these macros, +we advise your documents to invoke the rm request to remove any +such macros it uses and then define replacements with an authentically +typeset original at hand.17 For +informal purposes, a simple definition of UX should maintain the +readability of the document’s substance. +

+
+
+
.rm UX
+.ds UX Unix\"
+
+
+ + +
+
+
+
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+

4.6.8 Legacy Features

+ + + + + + + +

groff ms retains some legacy features solely to support +formatting of historical documents; contemporary ones should not use +them because they can render poorly. See the groff_char(7) +man page. +

+ +
+

AT&T accent mark strings

+ +

AT&T ms defined accent mark strings as follows. +

+
+
String: \*[']
+
+

Apply acute accent to subsequent glyph. +

+ +
+
String: \*[`]
+
+

Apply grave accent to subsequent glyph. +

+ +
+
String: \*[:]
+
+

Apply dieresis (umlaut) to subsequent glyph. +

+ +
+
String: \*[^]
+
+

Apply circumflex accent to subsequent glyph. +

+ +
+
String: \*[~]
+
+

Apply tilde accent to subsequent glyph. +

+ +
+
String: \*[C]
+
+

Apply caron to subsequent glyph. +

+ +
+
String: \*[,]
+
+

Apply cedilla to subsequent glyph. +

+ +
+
+

Berkeley accent mark and glyph strings

+ +

Berkeley ms offered an AM macro; calling it redefined the +AT&T accent mark strings (except for ‘\*C’), applied them to the +preceding glyph, and defined additional strings, some for spacing +glyphs. +

+
+
Macro: .AM
+
+

Enable alternative accent mark and glyph-producing strings. +

+ +
+
String: \*[']
+
+

Apply acute accent to preceding glyph. +

+ +
+
String: \*[`]
+
+

Apply grave accent to preceding glyph. +

+ +
+
String: \*[:]
+
+

Apply dieresis (umlaut) to preceding glyph. +

+ +
+
String: \*[^]
+
+

Apply circumflex accent to preceding glyph. +

+ +
+
String: \*[~]
+
+

Apply tilde accent to preceding glyph. +

+ +
+
String: \*[,]
+
+

Apply cedilla to preceding glyph. +

+ +
+
String: \*[/]
+
+

Apply stroke (slash) to preceding glyph. +

+ +
+
String: \*[v]
+
+

Apply caron to preceding glyph. +

+ +
+
String: \*[_]
+
+

Apply macron to preceding glyph. +

+ +
+
String: \*[.]
+
+

Apply underdot to preceding glyph. +

+ +
+
String: \*[o]
+
+

Apply ring accent to preceding glyph. +

+ +
+
String: \*[?]
+
+

Interpolate inverted question mark. +

+ +
+
String: \*[!]
+
+

Interpolate inverted exclamation mark. +

+ +
+
String: \*[8]
+
+

Interpolate small letter sharp s. +

+ +
+
String: \*[q]
+
+

Interpolate small letter o with hook accent (ogonek). +

+ +
+
String: \*[3]
+
+

Interpolate small letter yogh. +

+ +
+
String: \*[d-]
+
+

Interpolate small letter eth. +

+ +
+
String: \*[D-]
+
+

Interpolate capital letter eth. +

+ +
+
String: \*[th]
+
+

Interpolate small letter thorn. +

+ +
+
String: \*[Th]
+
+

Interpolate capital letter thorn. +

+ +
+
String: \*[ae]
+
+

Interpolate small æ ligature. +

+ +
+
String: \*[Ae]
+
+

Interpolate capital Æ ligature. +

+ +
+
String: \*[oe]
+
+

Interpolate small oe ligature. +

+ +
+
String: \*[OE]
+
+

Interpolate capital OE ligature. +

+ + +
+
+
+
+
+

+Previous: , Up: ms   [Contents][Index]

+
+

4.6.9 Naming Conventions

+ + + +

The following conventions are used for names of macros, strings, and +registers. External names available to documents that use the +groff ms macros contain only uppercase letters and digits. +

+

Internally, the macros are divided into modules. Conventions for +identifier names are as follows. +

+
    +
  • Names used only within one module are of the form +module*name. + +
  • Names used outside the module in which they are defined are of the form +module@name. + +
  • Names associated with a particular environment are of the form +environment:name; these are used only within the +par module. + +
  • name does not have a module prefix. + +
  • Constructed names used to implement arrays are of the form +array!index. +
+ +

Thus the groff ms macros reserve the following names. +

+
    +
  • Names containing the characters *, @, and :. + +
  • Names containing only uppercase letters and digits. +
+ + + +
+
+
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

5 GNU troff Reference

+ + + +

This chapter covers all of the facilities of the GNU +troff formatting engine. Users of macro packages may skip it if +not interested in details. +

+ + + + + +
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.1 Text

+ + +

AT&T troff was designed to take input as it would be +composed on a typewriter, including the teletypewriters used as early +computer terminals, and relieve the user drafting a document of concern +with details like line length, hyphenation breaking, and the achievement +of straight margins. Early in its development, the program gained the +ability to prepare output for a phototypesetter; a document could then +be prepared for output to either a teletypewriter, a phototypesetter, or +both. GNU troff continues this tradition of permitting an author +to compose a single master version of a document which can then be +rendered for a variety of output formats or devices. +

+

roff input files contain text interspersed with instructions to +control the formatter. Even in the absence of such instructions, GNU +troff still processes its input in several ways, by filling, +hyphenating, breaking, and adjusting it, and supplementing it with +inter-sentence space. +

+ + + +
+
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+

5.1.1 Filling

+ +

When GNU troff starts up, it obtains information about the device +for which it is preparing output.18 An essential property is the length of the output +line, such as “6.5 inches”. +

+ + +

GNU troff interprets plain text files employing the Unix +line-ending convention. It reads input a character at a time, +collecting words as it goes, and fits as many words together on an +output line as it can—this is known as filling. To GNU +troff, a word is any sequence of one or more characters +that aren’t spaces or newlines. The exceptions separate +words.19 To disable filling, see +Manipulating Filling and Adjustment. +

+
+
It is a truth universally acknowledged
+that a single man in possession of a
+good fortune must be in want of a wife.
+    ⇒ It is a truth universally acknowledged that a
+    ⇒ single man in possession of a good fortune must
+    ⇒ be in want of a wife.
+
+ + +
+
+
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+

5.1.2 Sentences

+ + +

A passionate debate has raged for decades among writers of the English +language over whether more space should appear between adjacent +sentences than between words within a sentence, and if so, how much, and +what other circumstances should influence this spacing.20 +GNU troff follows the example of AT&T troff; +it attempts to detect the boundaries between sentences, and supplies +additional inter-sentence space between them. +

+
+
Hello, world!
+Welcome to groff.
+    ⇒ Hello, world!  Welcome to groff.
+
+ + + + + +

GNU troff flags certain characters (normally ‘!’, ‘?’, +and ‘.’) as potentially ending a sentence. When GNU troff +encounters one of these end-of-sentence characters at the end of +an input line, or one of them is followed by two (unescaped) spaces on +the same input line, it appends an inter-word space followed by an +inter-sentence space in the output. +

+
+
R. Harper subscribes to a maxim of P. T. Barnum.
+    ⇒ R. Harper subscribes to a maxim of P. T. Barnum.
+
+ +

In the above example, inter-sentence space is not added after ‘P.’ +or ‘T.’ because the periods do not occur at the end of an input +line, nor are they followed by two or more spaces. Let’s imagine that +we’ve heard something about defamation from Mr. Harper’s attorney, +recast the sentence, and reflowed it in our text editor. +

+
+
I submit that R. Harper subscribes to a maxim of P. T.
+Barnum.
+    ⇒ I submit that R. Harper subscribes to a maxim of
+    ⇒ P. T.  Barnum.
+
+ +

“Barnum” doesn’t begin a sentence! What to do? Let us meet our first +escape sequence, a series of input characters that give +instructions to GNU troff instead of being used to construct +output device glyphs.21 An escape sequence begins with the backslash character \ +by default, an uncommon character in natural language text, and is +always followed by at least one other character, hence the term +“sequence”. +

+ +

The dummy character escape sequence \& can be used after an +end-of-sentence character to defeat end-of-sentence detection on a +per-instance basis. We can therefore rewrite our input more +defensively. +

+
+
I submit that R.\& Harper subscribes to a maxim of P.\&
+T.\& Barnum.
+    ⇒ I submit that R. Harper subscribes to a maxim of
+    ⇒ P. T. Barnum.
+
+ +

Adding text caused our input to wrap; now, we don’t need \& after +‘T.’ but we do after ‘P.’. Consistent use of the escape +sequence ensures that potential sentence boundaries are robust to +editing activities. Further advice along these lines will follow in +Input Conventions. +

+ + + + + + + + + + + + + +

Normally, the occurrence of a visible non-end-of-sentence character (as +opposed to a space or tab) immediately after an end-of-sentence +character cancels detection of the end of a sentence. For example, it +would be incorrect for GNU troff to infer the end of a sentence +after the dot in ‘3.14159’. However, several characters are +treated transparently after the occurrence of an end-of-sentence +character. That is, GNU troff does not cancel end-of-sentence +detection when it processes them. This is because such characters are +often used as footnote markers or to close quotations and +parentheticals. The default set is ‘"’, ‘'’, ‘)’, +‘]’, ‘*’, \[dg], \[dd], \[rq], and +\[cq]. The last four are examples of special characters, +escape sequences whose purpose is to obtain glyphs that are not easily +typed at the keyboard, or which have special meaning to GNU troff +(like \ itself).22 +

+
+
\[lq]The idea that the poor should have leisure has always
+been shocking to the rich.\[rq]
+(Bertrand Russell, 1935)
+    ⇒ "The idea that the poor should have
+    ⇒ leisure has always been shocking to
+    ⇒ the rich."  (Bertrand Russell, 1935)
+
+ +

The sets of characters that potentially end sentences or are transparent +to sentence endings are configurable. See the cflags request in +Using Symbols. To change the additional inter-sentence space +amount—even to remove it entirely—see Manipulating Filling and Adjustment. +

+ +
+
+
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+

5.1.3 Hyphenation

+ + +

When an output line is nearly full, it is uncommon for the next word +collected from the input to exactly fill it—typically, there is room +left over only for part of the next word. The process of splitting a +word so that it appears partially on one line (with a hyphen to indicate +to the reader that the word has been broken) with its remainder on the +next is hyphenation. Hyphenation points can be manually +specified; GNU troff also uses a hyphenation algorithm and +language-specific pattern files (based on those used in TeX) to +decide which words can be hyphenated and where. +

+

Hyphenation does not always occur even when the hyphenation rules for a +word allow it; it can be disabled, and when not disabled there are +several parameters that can prevent it in certain circumstances. +See Manipulating Hyphenation. +

+ +
+
+
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+

5.1.4 Breaking

+ + + + + +

Once an output line is full, the next word (or remainder of a hyphenated +one) is placed on a different output line; this is called a break. +In this manual and in roff discussions generally, a “break” if +not further qualified always refers to the termination of an output +line. When the formatter is filling text, it introduces breaks +automatically to keep output lines from exceeding the configured line +length. After an automatic break, GNU troff adjusts the line if +applicable (see below), and then resumes collecting and filling text on +the next output line. +

+

Sometimes, a line cannot be broken automatically. This usually does +not happen with natural language text unless the output line length has +been manipulated to be extremely short, but it can with specialized +text like program source code. We can use perl at the shell +prompt to contrive an example of failure to break the line. We also +employ the -z option to suppress normal output. +

+
+
$ perl -e 'print "#" x 80, "\n";' | nroff -z
+    error→ warning: cannot break line
+
+ +

The remedy for these cases is to tell GNU troff where the line +may be broken without hyphens. This is done with the non-printing break +point escape sequence ‘\:’; see Manipulating Hyphenation. +

+ + + + +

What if the document author wants to stop filling lines temporarily, for +instance to start a new paragraph? There are several solutions. A +blank input line not only causes a break, but by default it also outputs +a one-line vertical space (effectively a blank output line). This +behavior can be modified; see Blank Line Traps. Macro packages +may discourage or disable the blank line method of paragraphing in favor +of their own macros. +

+ + + + +

A line that begins with one or more spaces causes a break. The spaces +are output at the beginning of the next line without being +adjusted (see below); however, this behavior can be modified +(see Leading Space Traps). Again, macro packages may provide other +methods of producing indented paragraphs. Trailing spaces on text lines +are discarded.23 +

+

What if the file ends before enough words have been collected to fill an +output line? Or the output line is exactly full but not yet broken, and +there is no more input? GNU troff interprets the end of input as +a break. Certain requests also cause breaks, implicitly or explicitly. +This is discussed in Manipulating Filling and Adjustment. +

+ +
+
+
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+

5.1.5 Adjustment

+ + +

After GNU troff performs an automatic break, it may then +adjust the line, widening inter-word spaces until the text reaches +the right margin. Extra spaces between words are preserved. Leading +and trailing spaces are handled as noted above. Text can be aligned to +the left or right margin only, or centered; see Manipulating Filling and Adjustment. +

+ +
+
+
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+

5.1.6 Tabs and Leaders

+ + + + + + + + +

GNU troff translates input horizontal tab characters (“tabs”) +and Control+A characters (“leaders”) into movements to the next +tab stop. Tabs simply move to the next tab stop; leaders place enough +periods to fill the space. Tab stops are by default located every half +inch measured from the drawing position corresponding to the beginning +of the input line; see Page Geometry. Tabs and leaders do not +cause breaks and therefore do not interrupt filling. Below, we use +arrows → and bullets • to indicate input tabs and +leaders, respectively. +

+
+
1
+→ 2 → 3 • 4
+→ • 5
+⇒ 1         2       3.......4         ........5
+
+ +

Tabs and leaders lend themselves to table construction.24 The tab and leader glyphs can be +configured, and further facilities for sophisticated table composition +are available; see Tabs and Fields. There are many details to +track when using such low-level features, so most users turn to the +tbl(1) preprocessor to lay out tables. +

+ +
+
+
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+

5.1.7 Requests and Macros

+ +

We have now encountered almost all of the syntax there is in the +roff language, with an exception already noted in passing. + + + + + + +A request is an instruction to the formatter that occurs after a +control character, which is recognized at the beginning of an +input line. The regular control character is a dot (.). Its +counterpart, the no-break control character, a neutral apostrophe +('), suppresses the break that is implied by some requests. +These characters were chosen because it is uncommon for lines of text in +natural languages to begin with them. + + +If you require a formatted period or apostrophe (closing single +quotation mark) where GNU troff is expecting a control character, +prefix the dot or neutral apostrophe with the dummy character escape +sequence, ‘\&’. +

+ +

An input line beginning with a control character is called a +control line. + +Every line of input that is not a control line is a text +line.25 +

+ +

Requests often take arguments, words (separated from the request +name and each other by spaces) that specify details of the action GNU +troff is expected to perform. If a request is meaningless +without arguments, it is typically ignored. +

+

GNU troff’s requests and escape sequences comprise the control +language of the formatter. Of key importance are the requests that +define macros. Macros are invoked like requests, enabling the request +repertoire to be extended or overridden.26 +

+ + + +

A macro can be thought of as an abbreviation you can define for a +collection of control and text lines. When the macro is called by +giving its name after a control character, it is replaced with what it +stands for. The process of textual replacement is known as +interpolation.27 Interpolations are handled as soon as they are +recognized, and once performed, a roff formatter scans the +replacement for further requests, macro calls, and escape sequences. +

+

In roff systems, the de request defines a +macro.28 +

+
+
.de DATE
+2020-11-14
+..
+
+ +

The foregoing input produces no output by itself; all we have done is +store some information. Observe the pair of dots that ends the macro +definition. This is a default; you can specify your own terminator for +the macro definition as the second argument to the de request. +

+
+
.de NAME ENDNAME
+Heywood Jabuzzoff
+.ENDNAME
+
+ +

In fact, the ending marker is itself the name of a macro to be +called, or a request to be invoked, if it is defined at the time its +control line is read. +

+
+
.de END
+Big Rip
+..
+.de START END
+Big Bang
+.END
+.START
+    ⇒ Big Rip Big Bang
+
+ +

In the foregoing example, “Big Rip” printed before “Big Bang” +because its macro was called first. Consider what would happen +if we dropped END from the ‘.de START’ line and added +.. after .END. Would the order change? +

+

Let us consider a more elaborate example. +

+
+
.de DATE
+2020-10-05
+..
+.
+.de BOSS
+D.\& Kruger,
+J.\& Peterman
+..
+.
+.de NOTICE
+Approved:
+.DATE
+by
+.BOSS
+..
+.
+Insert tedious regulatory compliance paragraph here.
+
+.NOTICE
+
+Insert tedious liability disclaimer paragraph here.
+
+.NOTICE
+    ⇒ Insert tedious regulatory compliance paragraph here.
+    ⇒
+    ⇒ Approved: 2020-10-05 by D. Kruger, J. Peterman
+    ⇒
+    ⇒ Insert tedious liability disclaimer paragraph here.
+    ⇒
+    ⇒ Approved: 2020-10-05 by D. Kruger, J. Peterman
+
+ +

The above document started with a series of control lines. Three macros +were defined, with a de request declaring each macro’s name, and +the “body” of the macro starting on the next line and continuing until +a line with two dots ‘..’ marked its end. The text proper +began only after the macros were defined; this is a common pattern. +Only the NOTICE macro was called “directly” by the document; +DATE and BOSS were called only by NOTICE itself. +Escape sequences were used in BOSS, two levels of macro +interpolation deep. +

+

The advantage in typing and maintenance economy may not be obvious from +such a short example, but imagine a much longer document with dozens of +such paragraphs, each requiring a notice of managerial approval. +Consider what must happen if you are in charge of generating a new +version of such a document with a different date, for a different boss. +With well-chosen macros, you only have to change each datum in one +place. +

+

In practice, we would probably use strings (see Strings) instead of +macros for such simple interpolations; what is important here is to +glimpse the potential of macros and the power of recursive +interpolation. +

+

We could have defined DATE and BOSS in the opposite order; +perhaps less obviously, we could also have defined them after +NOTICE. “Forward references” like this are acceptable because +the body of a macro definition is not (completely) interpreted, but +stored instead (see Copy Mode). While a macro is being defined (or +appended to), requests are not interpreted and macros not interpolated, +whereas some commonly used escape sequences are interpreted. +roff systems also support recursive macro calls, as long as you +have a way to break the recursion (see Conditionals and Loops). +Maintainable roff documents tend to arrange macro definitions to +minimize forward references. +

+ +
+
+
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+

5.1.8 Macro Packages

+ + + +

Macro definitions can be collected into macro files, roff +input files designed to produce no output themselves but instead ease +the preparation of other roff documents. There is no syntactical +difference between a macro file and any other roff document; only +its purpose distinguishes it. When a macro file is installed at a +standard location and suitable for use by a general audience, it is +often termed a macro package.29 Macro packages can be +loaded by supplying the -m option to GNU troff or a +groff front end. Alternatively, a document requiring a macro +package can load it with the mso (“macro source”) request. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+

5.1.9 Input Encodings

+ +

The groff command’s -k option calls the +preconv preprocessor to perform input character encoding +conversions. Input to the GNU troff formatter itself, on the +other hand, must be in one of two encodings it can recognize. +

+
+
cp1047
+
+ + + + + + +

The code page 1047 input encoding works only on EBCDIC +platforms (and conversely, the other input encodings don’t work with +EBCDIC); the file cp1047.tmac is loaded at startup. +

+
+
latin1
+
+ + + +

ISO Latin-1, an encoding for Western European languages, is the +default input encoding on non-EBCDIC platforms; the file +latin1.tmac is loaded at startup. +

+
+ +

Any document that is encoded in ISO 646:1991 (a descendant of USAS +X3.4-1968 or “US-ASCII”), or, equivalently, uses only code points +from the “C0 Controls” and “Basic Latin” parts of the Unicode +character set is also a valid ISO Latin-1 document; the standards +are interchangeable in their first 128 code points.30 +

+

Other encodings are supported by means of macro packages. +

+
+
latin2
+
+ + + +

To use ISO Latin-2, an encoding for Central and Eastern European +languages, invoke ‘.mso latin2.tmac’ at the beginning of your +document or supply ‘-mlatin2’ as a command-line argument to +groff. +

+
+
latin5
+
+ + + +

To use ISO Latin-5, an encoding for the Turkish language, invoke +‘.mso latin5.tmac’ at the beginning of your document or +supply ‘-mlatin5’ as a command-line argument to groff. +

+
+
latin9
+
+ + + +

ISO Latin-9 succeeds Latin-1; it includes a Euro sign and better +glyph coverage for French. To use this encoding, invoke ‘.mso latin9.tmac’ at the beginning of your document or supply +‘-mlatin9’ as a command-line argument to groff. +

+
+ +

Some characters from an input encoding may not be available with a +particular output driver, or their glyphs may not have representation in +the font used. For terminal devices, fallbacks are defined, like +‘EUR’ for the Euro sign and ‘(C)’ for the copyright sign. For +typesetter devices, you may need to “mount” fonts that support glyphs +required by the document. See Font Positions. +

+ + +

Because a Euro glyph was not historically defined in PostScript fonts, +groff comes with a font called freeeuro.pfa that provides +the Euro in several styles. Standard PostScript fonts contain the +glyphs from Latin-5 and Latin-9 that Latin-1 lacks, so these +encodings are supported for the ps and pdf output +devices as groff ships, while Latin-2 is not. +

+

Unicode supports characters from all other input encodings; the +utf8 output driver for terminals therefore does as well. The +DVI output driver supports the Latin-2 and Latin-9 encodings if +the command-line option -mec is used as well. 31 +

+ +
+
+
+
+

+Previous: , Up: Text   [Contents][Index]

+
+

5.1.10 Input Conventions

+ + + +

Since GNU troff fills text automatically, it is common practice +in the roff language to avoid visual composition of text in input +files: the esthetic appeal of the formatted output is what matters. +Therefore, roff input should be arranged such that it is easy for +authors and maintainers to compose and develop the document, understand +the syntax of roff requests, macro calls, and preprocessor +languages used, and predict the behavior of the formatter. Several +traditions have accrued in service of these goals. +

+
    +
  • Follow sentence endings in the input with newlines to ease their +recognition (see Sentences). It is frequently convenient to end +text lines after colons and semicolons as well, as these typically +precede independent clauses. Consider doing so after commas; they often +occur in lists that become easy to scan when itemized by line, or +constitute supplements to the sentence that are added, deleted, or +updated to clarify it. Parenthetical and quoted phrases are also good +candidates for placement on text lines by themselves. + +
  • Set your text editor’s line length to 72 characters or +fewer.32 +This limit, combined with the previous item of advice, makes it less +common that an input line will wrap in your text editor, and thus will +help you perceive excessively long constructions in your text. Recall +that natural languages originate in speech, not writing, and that +punctuation is correlated with pauses for breathing and changes in +prosody. + +
  • Use \& after ‘!’, ‘?’, and ‘.’ if they are +followed by space, tab, or newline characters and don’t end a sentence. + +
  • In filled text lines, use \& before ‘.’ and ‘'’ if they +are preceded by space, so that reflowing the input doesn’t turn them +into control lines. + +
  • Do not use spaces to perform indentation or align columns of a table. +Leading spaces are reliable when text is not being filled. + +
  • Comment your document. It is never too soon to apply comments to +record information of use to future document maintainers (including your +future self). We thus introduce another escape sequence, \", +which causes GNU troff to ignore the remainder of the input line. + +
  • Use the empty request—a control character followed immediately by a +newline—to visually manage separation of material in input files. +Many of the groff project’s own documents use an empty request +between sentences, after macro definitions, and where a break is +expected, and two empty requests between paragraphs or other requests or +macro calls that will introduce vertical space into the document. + +

    You can combine the empty request with the comment escape sequence to +include whole-line comments in your document, and even “comment out” +sections of it. +

+ +

We conclude this section with an example sufficiently long to illustrate +most of the above suggestions in practice. For the purpose of fitting +the example between the margins of this manual with the font used for +its typeset version, we have shortened the input line length to 56 +columns. As before, an arrow → indicates a tab character. +

+
+
+
.\"   nroff this_file.roff | less
+.\"   groff -T ps this_file.roff > this_file.ps
+→The theory of relativity is intimately connected with
+the theory of space and time.
+.
+I shall therefore begin with a brief investigation of
+the origin of our ideas of space and time,
+although in doing so I know that I introduce a
+controversial subject.  \" remainder of paragraph elided
+.
+.
+
+→The experiences of an individual appear to us arranged
+in a series of events;
+in this series the single events which we remember
+appear to be ordered according to the criterion of
+\[lq]earlier\[rq] and \[lq]later\[rq], \" punct swapped
+which cannot be analysed further.
+.
+There exists,
+therefore,
+for the individual,
+an I-time,
+or subjective time.
+.
+This itself is not measurable.
+.
+I can,
+indeed,
+associate numbers with the events,
+in such a way that the greater number is associated with
+the later event than with an earlier one;
+but the nature of this association may be quite
+arbitrary.
+.
+This association I can define by means of a clock by
+comparing the order of events furnished by the clock
+with the order of a given series of events.
+.
+We understand by a clock something which provides a
+series of events which can be counted,
+and which has other properties of which we shall speak
+later.
+.\" Albert Einstein, _The Meaning of Relativity_, 1922
+
+
+ +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.2 Page Geometry

+ + + +

roff systems format text under certain assumptions about the size +of the output medium, or page. For the formatter to correctly break a +line it is filling, it must know the line length, which it derives from +the page width (see Line Layout). For it to decide whether to write +an output line to the current page or wait until the next one, it must +know the page length (see Page Layout). +

+ + + + + + +

A device’s resolution converts practical units like inches or +centimeters to basic units, a convenient length measure for the +output device or file format. The formatter and output driver use basic +units to reckon page measurements. The device description file defines +its resolution and page dimensions (see DESC File Format). +

+ +

A page is a two-dimensional structure upon which a roff +system imposes a rectangular coordinate system with its upper left +corner as the origin. Coordinate values are in basic units and increase +down and to the right. Useful ones are therefore always positive and +within numeric ranges corresponding to the page boundaries. +

+ + +

While the formatter (and, later, output driver) is processing a page, it +keeps track of its drawing position, which is the location at +which the next glyph will be written, from which the next motion will be +measured, or where a geometric object will commence rendering. + + +Notionally, glyphs are drawn from the text baseline upward and to the +right.33 The text baseline is a (usually invisible) line upon +which the glyphs of a typeface are aligned. A glyph therefore +“starts” at its bottom-left corner. If drawn at the origin, a typical +letter glyph would lie partially or wholly off the page, depending on +whether, like “g”, it features a descender below the baseline. +

+ + +

Such a situation is nearly always undesirable. It is furthermore +conventional not to write or draw at the extreme edges of the page. +Therefore the initial drawing position of a roff formatter is not +at the origin, but below and to the right of it. This rightward shift +from the left edge is known as the page +offset.34 The downward shift leaves room for a text output +line. +

+

Text is arranged on a one-dimensional lattice of text baselines from the +top to the bottom of the page. + + + +Vertical spacing is the distance between adjacent text baselines. +Typographic tradition sets this quantity to 120% of the type size. The +initial drawing position is one unit of vertical spacing below the page +top. Typographers term this unit a vee. +

+ + + + +

Vertical spacing has an impact on page-breaking decisions. Generally, +when a break occurs, the formatter moves the drawing position to the +next text baseline automatically. If the formatter were already writing +to the last line that would fit on the page, advancing by one vee would +place the next text baseline off the page. Rather than let that happen, +roff formatters instruct the output driver to eject the page, +start a new one, and again set the drawing position to one vee below the +page top; this is a page break. +

+

When the last line of input text corresponds to the last output line +that fits on the page, the break caused by the end of input will also +break the page, producing a useless blank one. Macro packages keep +users from having to confront this difficulty by setting “traps” +(see Traps); moreover, all but the simplest page layouts tend to +have headers and footers, or at least bear vertical margins larger than +one vee. +

+ + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.3 Measurements

+ + + + + + +

The formatter sometimes requires the input of numeric parameters to +specify measurements. These are specified as integers or decimal +fractions with an optional scaling unit suffixed. A scaling unit +is a letter that immediately follows the last digit of a number. Digits +after the decimal point are optional. Measurement expressions include +‘10.5p’, ‘11i’, and ‘3.c’. +

+ + + +

Measurements are scaled by the scaling unit and stored internally (with +any fractional part discarded) in basic units. + + +The device resolution can therefore be obtained by storing a value of +‘1i’ to a register. The only constraint on the basic unit is that +it is at least as small as any other unit. +

+
+
+ + + +
+
u
+

Basic unit. +

+
+
i
+
+ + +

Inch; defined as 2.54 centimeters. +

+
+
c
+
+ + +

Centimeter; a centimeter is about 0.3937 inches. +

+
+
p
+
+ + +

Point; a typesetter’s unit used for measuring type size. +There are 72 points to an inch. +

+
+
P
+
+ + +

Pica; another typesetter’s unit. There are 6 picas to an inch and +12 points to a pica. +

+
+
s
+
z
+

See Using Fractional Type Sizes, for a discussion of these units. +

+
+
f
+

GNU troff defines this unit to scale decimal fractions in the +interval [0, 1] to 16-bit unsigned integers. It multiplies a quantity +by 65,536. See Colors, for usage. +

+
+ +

The magnitudes of other scaling units depend on the text formatting +parameters in effect. These are useful when specifying measurements +that need to scale with the typeface or vertical spacing. +

+
+
m
+
+ + +

Em; an em is equal to the current type size in points. It is named thus +because it is approximately the width of the letter ‘M’. +

+
+
n
+
+ + +

En; an en is one-half em. +

+
+
v
+
+ + + + +

Vee; recall Page Geometry. +

+
+
M
+
+ +

Hundredth of an em. +

+
+ + + + +
+
+
+

+Next: , Previous: , Up: Measurements   [Contents][Index]

+
+

5.3.1 Motion Quanta

+ + + +

An output device’s basic unit u is not necessarily its smallest +addressable length; u can be smaller to avoid problems with +integer roundoff. The minimum distances that a device can work with in +the horizontal and vertical directions are termed its motion +quanta. Measurements are rounded to applicable motion quanta. +Half-quantum fractions round toward zero. +

+ + + + +
+
Register: \n[.H]
+
+
Register: \n[.V]
+
+

These read-only registers interpolate the horizontal and vertical motion +quanta, respectively, of the output device in basic units. +

+ +

For example, we might draw short baseline rules on a terminal device as +follows. See Drawing Geometric Objects. +

+
+
.tm \n[.H]
+    error→ 24
+.nf
+\l'36u' 36u
+\l'37u' 37u
+    ⇒ _ 36u
+    ⇒ __ 37u
+
+ + +
+
+
+
+

+Previous: , Up: Measurements   [Contents][Index]

+
+

5.3.2 Default Units

+ + + +

A general-purpose register (one created or updated with the nr +request; see see Registers) is implicitly dimensionless, or reckoned +in basic units if interpreted in a measurement context. But it is +convenient for many requests and escape sequences to infer a scaling +unit for an argument if none is specified. An explicit scaling unit +(not after a closing parenthesis) can override an undesirable default. +Effectively, the default unit is suffixed to the expression if a scaling +unit is not already present. GNU troff’s use of integer +arithmetic should also be kept in mind (see Numeric Expressions). +

+

The ll request interprets its argument in ems by default. +Consider several attempts to set a line length of 3.5 inches when +the type size is 10 points on a terminal device with a resolution +of 240 basic units and horizontal motion quantum of 24. Some +expressions become zero; the request clamps them to that quantum. +

+
+
.ll 3.5i      \" 3.5i (= 840u)
+.ll 7/2       \" 7u/2u -> 3u -> 3m -> 0, clamped to 24u
+.ll (7 / 2)u  \" 7u/2u -> as above
+.ll 7/2i      \" 7u/2i -> 7u/480u -> 0 -> as above
+.ll 7i/2      \" 7i/2u -> 1680u/2m -> 1680u/24u -> 35u
+.ll 7i/2u     \" 3.5i (= 840u)
+
+ + +

The safest way to specify measurements is to attach a scaling unit. To +multiply or divide by a dimensionless quantity, use ‘u’ as its +scaling unit. +

+ + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.4 Numeric Expressions

+ + + +

A numeric expression evaluates to an integer: it can be as +simple as a literal ‘0’ or it can be a complex sequence of register +and string interpolations interleaved with measurements and operators. +

+

GNU troff provides a set of mathematical and logical operators +familiar to programmers—as well as some unusual ones—but supports +only integer arithmetic.35 The internal data type +used for computing results is usually a 32-bit signed integer, which +suffices to represent magnitudes within a range of ±2 +billion.36 +

+ + + + + + + + + + + + + +

Arithmetic infix operators perform a function on the numeric expressions +to their left and right; they are + (addition), - +(subtraction), * (multiplication), / (truncating +division), and % (modulus). Truncating division rounds to +the integer nearer to zero, no matter how large the fractional portion. +Overflow and division (or modulus) by zero are errors and abort +evaluation of a numeric expression. + + + + + + + + +

+

Arithmetic unary operators operate on the numeric expression to their +right; they are - (negation) and + (assertion—for +completeness; it does nothing). The unary minus must often be used +with parentheses to avoid confusion with the decrementation operator, +discussed below. +

+

Observe the rounding behavior and effect of negative operands on the +modulus and truncating division operators. +

+
+
.nr T 199/100
+.nr U 5/2
+.nr V (-5)/2
+.nr W 5/-2
+.nr X 5%2
+.nr Y (-5)%2
+.nr Z 5%-2
+T=\n[T] U=\n[U] V=\n[V] W=\n[W] X=\n[X] Y=\n[Y] Z=\n[Z]
+    ⇒ T=1 U=2 V=-2 W=-2 X=1 Y=-1 Z=1
+
+ +

The sign of the modulus of operands of mixed signs is determined by the +sign of the first. Division and modulus operators satisfy the following +property: given a dividend a and a divisor b, a +quotient q formed by ‘(a / b)’ and a +remainder r by ‘(a % b)’, then qb + r = a. +

+ + + +

GNU troff’s scaling operator, used with parentheses as +(c;e), evaluates a numeric expression e +using c as the default scaling unit. If c is omitted, +scaling units are ignored in the evaluation of e. This +operator can save typing by avoiding the attachment of scaling units to +every operand out of caution. Your macros can select a sensible default +unit in case the user neglects to supply one. +

+
+
.\" Indent by amount given in first argument; assume ens.
+.de Indent
+.  in (n;\\$1)
+..
+
+ +

Without the scaling operator, the foregoing macro would, if called with +a unitless argument, cause indentation by the in request’s +default scaling unit (ems). The result would be twice as much +indentation as expected. +

+ + + + + + +

GNU troff also provides a pair of operators to compute the +extrema of two operands: >? (maximum) and <? (minimum). +

+
+
.nr slots 5
+.nr candidates 3
+.nr salaries (\n[slots] <? \n[candidates])
+Looks like we'll end up paying \n[salaries] salaries.
+    ⇒ Looks like we'll end up paying 3 salaries.
+
+ + + + + + + + + + + + +

Comparison operators comprise < (less than), > (greater +than), <= (less than or equal), >= (greater than or +equal), and = (equal). == is a synonym for =. +When evaluated, a comparison is replaced with ‘0’ if it is false +and ‘1’ if true. In the roff language, positive values are +true, others false. +

+ + + + + + + + +

We can operate on truth values with the logical operators & +(logical conjunction or “and”) and : (logical disjunction or +“or”). They evaluate as comparison operators do. +

+ + + + + +

A logical complementation (“not”) operator, !, works only +within if, ie, and while requests. +Furthermore, ! is recognized only at the beginning of a numeric +expression not contained by another numeric expression. In other words, +it must be the “outermost” operator. Including it elsewhere in the +expression produces a warning in the ‘number’ category +(see Warnings), and its expression evaluates false. This +unfortunate limitation maintains compatibility with AT&T +troff. Test a numeric expression for falsity by +comparing it to a false value.37 +

+
+
.nr X 1
+.nr Y 0
+.\" This does not work as expected.
+.if (\n[X])&(!\n[Y]) .nop A: X is true, Y is false
+.
+.\" Use this construct instead.
+.if (\n[X])&(\n[Y]<=0) .nop B: X is true, Y is false
+    error→ warning: expected numeric expression, got '!'
+    ⇒ B: X is true, Y is false
+
+ + + + + + +

The roff language has no operator precedence: expressions are +evaluated strictly from left to right, in contrast to schoolhouse +arithmetic. Use parentheses ( ) to impose a desired +precedence upon subexpressions. +

+
+
.nr X 3+5*4
+.nr Y (3+5)*4
+.nr Z 3+(5*4)
+X=\n[X] Y=\n[Y] Z=\n[Z]
+    ⇒ X=32 Y=32 Z=23
+
+ + + + + + + +

For many requests and escape sequences that cause motion on the page, +the unary operators + and - work differently when leading +a numeric expression. They then indicate a motion relative to the +drawing position: positive is down in vertical contexts, right in +horizontal ones. +

+ + + + + + + + + + + + + + + + +

+ and - are also treated differently by the following +requests and escape sequences: bp, in, ll, +lt, nm, nr, pl, pn, po, +ps, pvs, rt, ti, \H, \R, and +\s. Here, leading plus and minus signs serve as incrementation +and decrementation operators, respectively. To negate an expression, +subtract it from zero or include the unary minus in parentheses with its +argument. See Setting Registers, for examples. +

+ + + + + +

A leading | operator indicates a motion relative not to the +drawing position but to a boundary. For horizontal motions, the +measurement specifies a distance relative to a drawing position +corresponding to the beginning of the input line. By default, +tab stops reckon movements in this way. Most escape sequences do not; +| tells them to do so. +

+
+
Mind the \h'1.2i'gap.
+.br
+Mind the \h'|1.2i'gap.
+.br
+Mind the
+\h'|1.2i'gap.
+    ⇒ Mind the             gap.
+    ⇒ Mind the    gap.
+    ⇒ Mind the             gap.
+
+ +

One use of this feature is to define macros whose scope is limited to +the output they format. +

+
+
.\" underline word $1 with trailing punctuation $2
+.de Underline
+.  nop \\$1\l'|0\[ul]'\\$2
+..
+Typographical emphasis is best used
+.Underline sparingly .
+
+ +

In the above example, ‘|0’ specifies a negative motion from the +current position (at the end of the argument just emitted, \$1) +to the beginning of the input line. Thus, the \l escape sequence +in this case draws a line from right to left. A macro call occurs at +the beginning of an input line;38 if the | +operator were omitted, then the underline would be drawn at zero +distance from the current position, producing device-dependent, and +likely undesirable, results. On the ‘ps’ output device, it +underlines the period. +

+

For vertical motions, the | operator specifies a distance from +the first text baseline on the page or in the current +diversion,39 using the current vertical +spacing. +

+
+
A
+.br
+B \Z'C'\v'|0'D
+    ⇒ A D
+    ⇒ B C
+
+ +

In the foregoing example, we’ve used the \Z escape sequence +(see Page Motions) to restore the drawing position after formatting +‘C’, then moved vertically to the first text baseline on the page. +

+
+
Escape sequence: \B'anything'
+
+ + +

Interpolate 1 if anything is a valid numeric expression, +and 0 otherwise. The delimiter need not be a neutral apostrophe; +see Delimiters. +

+ +

You might use \B along with the if request to filter out +invalid macro or string arguments. See Conditionals and Loops. +

+
+
.\" Indent by amount given in first argument; assume ens.
+.de Indent
+.  if \B'\\$1' .in (n;\\$1)
+..
+
+ +

A register interpolated as an operand in a numeric expression must have +an Arabic format; luckily, this is the default. See Assigning Register Formats. +

+ + +

Because spaces separate arguments to requests, spaces are not allowed in +numeric expressions unless the (sub)expression containing them is +surrounded by parentheses. See Invoking Requests, and +Conditionals and Loops. +

+
+
.nf
+.nr a 1+2 + 2+1
+\na
+    error→ expected numeric expression, got a space
+    ⇒ 3
+.nr a 1+(2 + 2)+1
+\na
+    ⇒ 6
+
+ +

The nr request (see Setting Registers) expects its second and +optional third arguments to be numeric expressions; a bare + does +not qualify, so our first attempt got a warning. +

+ + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.5 Identifiers

+ + +

An identifier labels a GNU troff datum such as a register, +name (macro, string, or diversion), typeface, color, special character, +character class, environment, or stream. Valid identifiers consist of +one or more ordinary characters. + + +An ordinary character is an input character that is not the +escape character, a leader, tab, newline, or invalid as GNU troff +input. +

+ + + + +

Invalid input characters are a subset of control characters (from the +sets “C0 Controls” and “C1 Controls” as Unicode describes them). +When GNU troff encounters one in an identifier, it produces a +warning in category ‘input’ (see Warnings). They are removed +during interpretation: an identifier ‘foo’, followed by an invalid +character and then ‘bar’, is processed as ‘foobar’. +

+

On a machine using the ISO 646, 8859, or 10646 character encodings, +invalid input characters are 0x00, 0x08, 0x0B, +0x0D–0x1F, and 0x80–0x9F. On an +EBCDIC host, they are 0x00–0x01, 0x08, +0x09, 0x0B, 0x0D–0x14, +0x17–0x1F, and +0x30–0x3F.40 Some of these code points are used +by GNU troff internally, making it non-trivial to extend the +program to accept UTF-8 or other encodings that use characters from +these ranges.41 +

+

Thus, the identifiers ‘br’, ‘PP’, ‘end-list’, +‘ref*normal-print’, ‘|’, ‘@_’, and ‘!"#$%'()*+,-./’ +are all valid. Discretion should be exercised to prevent confusion. +Identifiers starting with ‘(’ or ‘[’ require care. +

+
+
.nr x 9
+.nr y 1
+.nr (x 2
+.nr [y 3
+.nr sum1 (\n(x + \n[y])
+    error→ a space character is not allowed in an escape
+    error→   sequence parameter
+A:2+3=\n[sum1]
+.nr sum2 (\n((x + \n[[y])
+B:2+3=\n[sum2]
+.nr sum3 (\n[(x] + \n([y)
+C:2+3=\n[sum3]
+    ⇒ A:2+3=1 B:2+3=5 C:2+3=5
+
+ + +

An identifier with a closing bracket (‘]’) in its name can’t be +accessed with bracket-form escape sequences that expect an identifier as +a parameter. For example, ‘\[foo]]’ accesses the glyph ‘foo’, +followed by ‘]’ in whatever the surrounding context is, whereas +‘\C'foo]'’ formats a glyph named ‘foo]’. Similarly, the +identifier ‘(’ can’t be interpolated except with bracket +forms. +

+ + + + +

If you begin a macro, string, or diversion name with either of the +characters ‘[’ or ‘]’, you foreclose use of the grefer +preprocessor, which recognizes ‘.[’ and ‘.]’ as bibliographic +reference delimiters. +

+
+
Escape sequence: \A'anything'
+
+

Interpolate 1 if anything is a valid identifier, and 0 +otherwise. The delimiter need not be a neutral apostrophe; see +Delimiters. Because invalid input characters are removed (see +above), invalid identifiers are empty or contain spaces, tabs, or +newlines. +

+

You can employ \A to validate a macro argument before using it to +construct another escape sequence or identifier. +

+
+
.\" usage: .init-coordinate-pair name val1 val2
+.\" Create a coordinate pair where name!x=val1 and
+.\" name!y=val2.
+.de init-coordinate-pair
+.  if \A'\\$1' \{\
+.    if \B'\\$2' .nr \\$1!x \\$2
+.    if \B'\\$3' .nr \\$1!y \\$3
+.  \}
+..
+.init-coordinate-pair center 5 10
+The center is at (\n[center!x], \n[center!y]).
+.init-coordinate-pair "poi→nt" trash garbage \" ignored
+.init-coordinate-pair point trash garbage \" ignored
+    ⇒ The center is at (5, 10).
+
+ +

In this example, we also validated the numeric arguments; the registers +‘point!x’ and ‘point!y’ remain undefined. See Numeric Expressions for the \B escape sequence. +

+ + + +

How GNU troff handles the interpretation of an undefined +identifier depends on the context. There is no way to invoke an +undefined request; such syntax is interpreted as a macro call instead. +If the identifier is interpreted as a string, macro, or diversion, GNU +troff emits a warning in category ‘mac’, defines it as +empty, and interpolates nothing. If the identifier is interpreted as a +register, GNU troff emits a warning in category ‘reg’, +initializes it to zero, and interpolates that value. See Warnings, +Interpolating Registers, and Strings. Attempting to use an +undefined typeface, special character, color, character class, +environment, or stream generally provokes an error diagnostic. +

+ + + + + +

Identifiers for requests, macros, strings, and diversions share one name +space; special characters and character classes another. No other +object types do. +

+
+
.de xxx
+.  nop foo
+..
+.di xxx
+bar
+.br
+.di
+.
+.xxx
+    ⇒ bar
+
+ +

The foregoing example shows that GNU troff reuses the identifier +‘xxx’, changing it from a macro to a diversion. No warning is +emitted, and the previous contents of ‘xxx’ are lost. +

+ + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.6 Formatter Instructions

+ + + +

To support documents that require more than filling, automatic line +breaking and hyphenation, adjustment, and supplemental inter-sentence +space, the roff language offers two means of embedding +instructions to the formatter. +

+ +

One is a request, which begins with a control character and takes +up the remainder of the input line. Requests often perform relatively +large-scale operations such as setting the page length, breaking the +line, or starting a new page. They also conduct internal operations +like defining macros. +

+ + +

The other is an escape sequence, which begins with the escape +character and can be embedded anywhere in the input, even in arguments +to requests and other escape sequences. Escape sequences interpolate +special characters, strings, or registers, and handle comparatively +minor formatting tasks like sub- and superscripting. +

+

Some operations, such as font selection and type size alteration, are +available via both requests and escape sequences. +

+ + + +
+
+
+

+Next: , Previous: , Up: Formatter Instructions   [Contents][Index]

+
+

5.6.1 Control Characters

+ + + + +

The mechanism of using roff’s control characters to invoke +requests and call macros was introduced in Requests and Macros. +Control characters are recognized only at the beginning of an input +line, or at the beginning of the branch of a control structure request; +see Conditionals and Loops. +

+

A few requests cause a break implicitly; use the no-break control +character to prevent the break. Break suppression is its sole +behavioral distinction. Employing the no-break control character to +invoke requests that don’t cause breaks is harmless but poor style. +See Manipulating Filling and Adjustment. +

+ + + + + +

The control ‘.’ and no-break control ‘'’ characters can each +be changed to any ordinary character42 +with the cc and c2 requests, respectively. +

+
+
Request: .cc [o]
+
+

Recognize the ordinary character o as the control character. +If o is absent or invalid, the default control character +‘.’ is selected. The identity of the control character is +associated with the environment (see Environments). +

+ +
+
Request: .c2 [o]
+
+

Recognize the ordinary character o as the no-break control +character. If o is absent or invalid, the default no-break +control character ‘'’ is selected. The identity of the no-break +control character is associated with the environment +(see Environments). +

+ +

When writing a macro, you might wish to know which control character was +used to call it. +

+
+
Register: \n[.br]
+
+

This read-only register interpolates 1 if the currently executing +macro was called using the normal control character and 0 +otherwise. If a macro is interpolated as a string, the .br +register’s value is inherited from the context of the string +interpolation. See Strings. +

+ + + + +

Use this register to reliably intercept requests that imply breaks. +

+
+
.als bp*orig bp
+.de bp
+.  ie \\n[.br] .bp*orig
+.  el          'bp*orig
+..
+
+ +

Testing the .br register outside of a macro definition makes no +sense. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Formatter Instructions   [Contents][Index]

+
+

5.6.2 Invoking Requests

+ + + +

A control character is optionally followed by tabs and/or spaces and +then an identifier naming a request or macro. The invocation of an +unrecognized request is interpreted as a macro call. Defining a macro +with the same name as a request replaces the request. Deleting a +request name with the rm request makes it unavailable. The +als request can alias requests, permitting them to be wrapped or +non-destructively replaced. See Strings. +

+ + + + + + + + +

There is no inherent limit on argument length or quantity. Most +requests take one or more arguments, and ignore any they do not expect. +A request may be separated from its arguments by tabs or spaces, but +only spaces can separate an argument from its successor. Only one +between arguments is necessary; any excess is ignored. GNU troff +does not allow tabs for argument separation.43 +

+

Generally, a space within a request argument is not relevant, not +meaningful, or is supported by bespoke provisions, as with the tl +request’s delimiters (see Page Layout). Some requests, like +ds, interpret the remainder of the control line as a single +argument. See Strings. +

+ + + + + +

Spaces and tabs immediately after a control character are ignored. +Commonly, authors structure the source of documents or macro files with +them. +

+
+
.de center
+.  if \\n[.br] \
+.    br
+.  ce \\$1
+..
+.
+.
+.de right-align
+.→if \\n[.br] \
+.→→br
+.→rj \\$1
+..
+
+ + + +

If you assign an empty blank line trap, you can separate macro +definitions (or any input lines) with blank lines. +

+
+
.de do-nothing
+..
+.blm do-nothing  \" activate blank line trap
+
+.de center
+.  if \\n[.br] \
+.    br
+.  ce \\$1
+..
+
+
+.de right-align
+.→if \\n[.br] \
+.→→br
+.→rj \\$1
+..
+
+.blm             \" deactivate blank line trap
+
+ +

See Blank Line Traps. +

+ +
+
+
+
+

+Next: , Previous: , Up: Formatter Instructions   [Contents][Index]

+
+

5.6.3 Calling Macros

+ + + + +

If a macro of the desired name does not exist when called, it is +created, assigned an empty definition, and a warning in category +‘mac’ is emitted. Calling an undefined macro does end a +macro definition naming it as its end macro (see Writing Macros). +

+ +

To embed spaces within a macro argument, enclose the argument in +neutral double quotes ". Horizontal motion escape sequences are +sometimes a better choice for arguments to be formatted as text. +

+

Consider calls to a hypothetical section heading macro ‘uh’. +

+
+
.uh The Mouse Problem
+.uh "The Mouse Problem"
+.uh The\~Mouse\~Problem
+.uh The\ Mouse\ Problem
+
+ + + +

The first line calls uh with three arguments: ‘The’, +‘Mouse’, and ‘Problem’. The remainder call the uh +macro with one argument, ‘The Mouse Problem’. The last solution, +using escaped spaces, can be found in documents prepared for +AT&T troff. It can cause surprise when text is +adjusted, because \SP inserts a fixed-width, +non-breaking space. GNU troff’s \~ escape sequence +inserts an adjustable, non-breaking space.44 +

+ + + + +

The foregoing raises the question of how to embed neutral double quotes +or backslashes in macro arguments when those characters are +desired as literals. In GNU troff, the special character escape +sequence \[rs] produces a backslash and \[dq] a neutral +double quote. +

+

In GNU troff’s AT&T compatibility mode, these +characters remain available as \(rs and \(dq, +respectively. AT&T troff did not consistently define +these special characters, +but its descendants can be made to support them. See Device and Font Description Files. +

+

If even that is not feasible, options remain. To obtain a literal +escape character in a macro argument, you can simply type it if you +change or disable the escape character first. See Using Escape Sequences. Otherwise, you must escape the escape character repeatedly +to a context-dependent extent. See Copy Mode. +

+

For the (neutral) double quote, you have recourse to an obscure +syntactical feature of AT&T troff. Because a double +quote can begin a macro argument, the formatter keeps track of whether +the current argument was started thus, and doesn’t require a space after +the double quote that ends it.45 In +the argument list to a macro, a double quote that isn’t preceded +by a space doesn’t start a macro argument. If not preceded by a +double quote that began an argument, this double quote becomes part of +the argument. Furthermore, within a quoted argument, a pair of adjacent +double quotes becomes a literal double quote. +

+
+
.de eq
+.  tm arg1:\\$1 arg2:\\$2 arg3:\\$3
+.  tm arg4:\\$4 arg5:\\$5 arg6:\\$6
+.. \" 4 backslashes on the next line
+.eq a" "b c" "de"f\\\\g" h""i "j""k"
+    error→ arg1:a" arg2:b c arg3:de
+    error→ arg4:f\g" arg5:h""i arg6:j"k
+
+ +

Apart from the complexity of the rules, this traditional solution has +the disadvantage that double quotes don’t survive repeated argument +expansion in AT&T troff or GNU troff’s +compatibility mode. This can frustrate efforts to pass such arguments +intact through multiple macro calls. +

+
+
.cp 1
+.de eq
+.  tm arg1:\\$1 arg2:\\$2 arg3:\\$3
+.  tm arg4:\\$4 arg5:\\$5 arg6:\\$6
+..
+.de xe
+.  eq \\$1 \\$2 \\$3 \\$4 \\$5 \\$6
+.. \" 8 backslashes on the next line
+.xe a" "b c" "de"f\\\\\\\\g" h""i "j""k"
+    error→ arg1:a" arg2:b arg3:c
+    error→ arg4:de arg5:f\g" arg6:h""i
+
+ + + + + +

Outside of compatibility mode, GNU troff doesn’t exhibit this +problem because it tracks the nesting depth of interpolations. +See Implementation Differences. +

+ +
+
+
+
+

+Next: , Previous: , Up: Formatter Instructions   [Contents][Index]

+
+

5.6.4 Using Escape Sequences

+ + + +

Whereas requests must occur on control lines, escape sequences can occur +intermixed with text and may appear in arguments to requests, macros, +and other escape sequences. + +An escape sequence is introduced by the escape character, a backslash +\ (but see the ec request below). The next character +selects the escape’s function. +

+

Escape sequences vary in length. Some take an argument, and of those, +some have different syntactical forms for a one-character, +two-character, or arbitrary-length argument. Others accept only +an arbitrary-length argument. In the former scheme, a one-character +argument follows the function character immediately, an opening +parenthesis ‘(’ introduces a two-character argument (no closing +parenthesis is used), and an argument of arbitrary length is enclosed in +brackets ‘[]’. In the latter scheme, the user selects a delimiter +character. A few escape sequences are idiosyncratic, and support both +of the foregoing conventions (\s), designate their own +termination sequence (\?), consume input until the next newline +(\!, \", \#), or support an additional modifier +character (\s again, and \n). As with requests, use of +some escape sequences in source documents may interact poorly with a +macro package you use; consult its documentation to learn of “safe” +sequences or alternative facilities it provides to achieve the desired +result. +

+

If an escape character is followed by a character that does not +identify a defined operation, the escape character is ignored (producing +a diagnostic of the ‘escape’ warning category, which is not enabled +by default) and the following character is processed normally. +

+
+
$ groff -Tps -ww
+.nr N 12
+.ds co white
+.ds animal elephant
+I have \fI\nN \*(co \*[animal]s,\f[]
+said \P.\&\~Pseudo Pachyderm.
+    error→ warning: escape character ignored before 'P'
+    ⇒ I have 12 white elephants, said P. Pseudo Pachyderm.
+
+ +

Escape sequence interpolation is of higher precedence than escape +sequence argument interpretation. This rule affords flexibility in +using escape sequences to construct parameters to other escape +sequences. +

+
+
.ds family C\" Courier
+.ds style I\" oblique
+Choice a typeface \f(\*[family]\*[style]wisely.
+    ⇒ Choose a typeface wisely.
+
+ +

In the above, the syntax form ‘\f(’ accepts only two characters for +an argument; the example works because the subsequent escape sequences +are interpolated before the selection escape sequence argument is +processed, and strings family and style interpolate one +character each.46 +

+

The escape character is nearly always interpreted when encountered; it +is therefore desirable to have a way to interpolate it, disable it, or +change it. +

+ + +
+
Escape sequence: \e
+
+

Interpolate the escape character. +

+ + + +

The \[rs] special character escape sequence formats a backslash +glyph. In macro and string definitions, the input sequences \\ +and \E defer interpretation of escape sequences. See Copy Mode. +

+
+
Request: .eo
+
+ + +

Disable the escape mechanism except in copy mode. Once this request is +invoked, no input character is recognized as starting an escape +sequence in interpretation mode. +

+ +
+
Request: .ec [o]
+
+ + +

Recognize the ordinary character o as the escape character. +If o is absent or invalid, the default escape character +‘\’ is selected. +

+ +

Switching escape sequence interpretation off to define a macro and back +on afterward can obviate the need to double the escape character within +the definition. See Writing Macros. This technique is not available +if your macro needs to interpolate values at the time it is +defined—but many do not. +

+
+
.\" simplified `BR` macro from the man(7) macro package
+.eo
+.de BR
+.  ds result \&
+.  while (\n[.$] >= 2) \{\
+.    as result \fB\$1\fR\$2\"
+.    shift 2
+.  \}
+.  if \n[.$] .as result \fB\$1\"
+\*[result]
+.  rm result
+.  ft R
+..
+.ec
+
+ +
+
Request: .ecs
+
+
Request: .ecr
+
+

The ecs request stores the escape character for recall with +ecr. ecr sets the escape character to ‘\’ if none +has been saved. +

+

Use these requests together to temporarily change the escape character. +

+ +

Using a different escape character, or disabling it, when calling macros +not under your control will likely cause errors, since GNU troff +has no mechanism to “intern” macros—that is, to convert a macro +definition into a form independent of its +representation.47 When a +macro is called, its contents are interpreted literally. +

+ +
+
+
+
+

+Previous: , Up: Formatter Instructions   [Contents][Index]

+
+

5.6.5 Delimiters

+ + + + + + + +

Some escape sequences that require parameters use delimiters. The +neutral apostrophe ' is a popular choice and shown in this +document. The neutral double quote " is also commonly seen. +Letters, numerals, and leaders can be used. Punctuation characters +are likely better choices, except for those defined as infix operators +in numeric expressions; see below. +

+
+
\l'1.5i\[bu]' \" draw 1.5 inches of bullet glyphs
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

The following escape sequences don’t take arguments and thus are allowed +as delimiters: +\SP, \%, \|, \^, \{, +\}, \', \`, \-, \_, \!, +\?, \), \/, \,, \&, \:, +\~, \0, \a, \c, \d, \e, +\E, \p, \r, \t, and \u. However, +using them this way is discouraged; they can make the input confusing to +read. +

+ + + + + + + +

A few escape sequences, +\A, +\b, +\o, +\w, +\X, +and \Z, accept a newline as a delimiter. Newlines that serve +as delimiters continue to be recognized as input line terminators. +

+
+
A caf\o
+e\(aa
+in Paris
+    ⇒ A café in Paris
+
+ +

Use of newlines as delimiters in escape sequences is also discouraged. +

+ + + + + + + + + + + +

Finally, the escape sequences \D, \h, \H, +\l, \L, \N, \R, \s, \S, +\v, and \x prohibit many delimiters. +

+
    +
  • + + + + +the numerals 0-9 and the decimal point . + +
  • + + + + + + + + + + + + +the (single-character) operators ‘+-/*%<>=&:()’ + +
  • + +the space and tab characters + +
  • + + + + + + + + + + + + +any escape sequences other than \%, \:, \{, +\}, \', \`, \-, \_, \!, +\/, \c, \e, and \p +
+ +

Delimiter syntax is complex and flexible primarily for historical +reasons; the foregoing restrictions need be kept in mind mainly when +using groff in AT&T compatibility mode. GNU +troff keeps track of the nesting depth of escape sequence +interpolations, so the only characters you need to avoid using as +delimiters are those that appear in the arguments you input, not any +that result from interpolation. Typically, ' works fine. +See Implementation Differences. +

+
+
$ groff -Tps
+.de Mw
+.  nr wd \w'\\$1'
+.  tm "\\$1" is \\n(wd units wide.
+..
+.Mw Wet'suwet'en
+.Mw Wet+200i
+.cp 1 \" turn on compatibility mode
+.Mw Wet'suwet'en
+.Mw Wet'
+.Mw Wet+200i
+    error→ "Wet'suwet'en" is 54740 units wide.
+    error→ "Wet'+200i" is 42610 units wide.
+    error→ "Wet'suwet'en" is 15860 units wide.
+    error→ "Wet'" is 15860 units wide.
+    error→ "Wet'+200i" is 14415860 units wide.
+
+ +

We see here that in compatibility mode, the part of the argument after +the ' delimiter escapes from its context and, if nefariously +crafted, influences the computation of the wd register’s value in +a surprising way. +

+
+
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.7 Comments

+ + +

One of the most common forms of escape sequence is the +comment.48 +

+
+
Escape sequence: \"
+
+

Start a comment. Everything up to the next newline is ignored. +

+

This may sound simple, but it can be tricky to keep the comments from +interfering with the appearance of the output. + + +If the escape sequence is to the right of some text or a request, that +portion of the line is ignored, but spaces preceding it are processed +normally by GNU troff. This affects only the ds and +as requests and their variants. +

+ + +

One possibly irritating idiosyncrasy is that tabs should not be used to +vertically align comments in the source document. Tab characters are +not treated as separators between a request name and its first argument, +nor between arguments. +

+ + +

A comment on a line by itself is treated as a blank line, because after +eliminating the comment, that is all that remains. +

+
+
Test
+\" comment
+Test
+    ⇒ Test
+    ⇒
+    ⇒ Test
+
+ +

To avoid this, it is common to combine the empty request with the +comment escape sequence as ‘.\"’, causing the input line to be +ignored. +

+ +

Another commenting scheme sometimes seen is three consecutive single +quotes (''') at the beginning of a line. This works, but GNU +troff emits a warning diagnostic (if enabled) about an undefined +macro (namely ‘''’). +

+ +
+
Escape sequence: \#
+
+

Start a comment; everything up to and including the next newline is +ignored. This groff extension was introduced to avoid the +problems described above. +

+
+
Test
+\# comment
+Test
+    ⇒ Test Test
+
+
+ +
+
Request: .ig [end]
+
+

Ignore input until, in the current conditional block (if +any),49 the macro end is called +at the start of a control line, or the control line ‘..’ is +encountered if end is not specified. ig is parsed as if it +were a macro definition, but its contents are discarded, not +stored.50 +

+
+
hand\c
+.de TX
+fasting
+..
+.ig TX
+This is part of a large block of input that has been
+temporarily(?) commented out.
+We can restore it simply by removing the .ig request and
+the call of its end macro.
+.TX
+
+
+
    ⇒ handfasting
+
+
+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.8 Registers

+ + +

In the roff language, numbers can be stored in registers. +Many built-in registers exist, supplying anything from the date to +details of formatting parameters. You can also define your own. +See Identifiers, for information on constructing a valid name for a +register. +

+ + + +
+
+
+

+Next: , Previous: , Up: Registers   [Contents][Index]

+
+

5.8.1 Setting Registers

+ + + +

Define registers and update their values with the nr request or +the \R escape sequence. +

+
+
Request: .nr ident value
+
+
Escape sequence: \R'ident value'
+
+

Set register ident to value. If ident doesn’t exist, +GNU troff creates it. In the \R escape sequence, the +delimiter need not be a neutral apostrophe; see Delimiters. It +also does not produce an input token in GNU troff. See gtroff Internals. +

+
+
.nr a (((17 + (3 * 4))) % 4)
+\n[a]
+.\R'a (((17 + (3 * 4))) % 4)'
+\n[a]
+    ⇒ 1 1
+
+ +

(Later, we will discuss additional forms of nr and \R that +can change a register’s value after it is dereferenced but before it is +interpolated. See Auto-increment.) +

+

The complete transparency of \R can cause surprising effects if +you use registers like .k, which get evaluated at the time they +are accessed. +

+
+
.ll 1.6i
+.
+aaa bbb ccc ddd eee fff ggg hhh\R':k \n[.k]'
+.tm :k == \n[:k]
+    ⇒ :k == 126950
+.
+.br
+.
+aaa bbb ccc ddd eee fff ggg hhh\h'0'\R':k \n[.k]'
+.tm :k == \n[:k]
+    ⇒ :k == 15000
+
+ +

If you process this with the PostScript device (-Tps), there will +be a line break eventually after ggg in both input lines. +However, after processing the space after ggg, the partially +collected line is not overfull yet, so GNU troff continues to +collect input until it sees the space (or in this case, the newline) +after hhh. At this point, the line is longer than the line +length, and the line gets broken. +

+

In the first input line, since the \R escape sequence leaves no +traces, the check for the overfull line hasn’t been done yet at the +point where \R gets handled, and you get a value for the +.k register that is even greater than the current line length. +

+

In the second input line, the insertion of \h'0' to cause a +zero-width motion forces GNU troff to check the line length, +which in turn causes the start of a new output line. Now .k +returns the expected value. +

+ +

nr and \R each have two additional special forms to +increment or decrement a register. +

+
+
Request: .nr ident +value
+
+
Request: .nr ident -value
+
Escape sequence: \R'ident +value'
+
+
Escape sequence: \R'ident -value'
+

Increment (decrement) register ident by value. In the +\R escape sequence, the delimiter need not be a neutral +apostrophe; see Delimiters. +

+
+
.nr a 1
+.nr a +1
+\na
+    ⇒ 2
+
+ + +

A leading minus sign in value is always interpreted as a +decrementation operator, not an algebraic sign. To assign a register a +negative value or the negated value of another register, you can +force GNU troff to interpret ‘-’ as a negation or minus, +rather than decrementation, operator: enclose it with its operand in +parentheses or subtract it from zero. +

+
+
.nr a 7
+.nr b 3
+.nr a -\nb
+\na
+    ⇒ 4
+.nr a (-\nb)
+\na
+    ⇒ -3
+.nr a 0-\nb
+\na
+    ⇒ -3
+
+ +

If a register’s prior value does not exist (the register was undefined), +an increment or decrement is applied as if to 0. +

+ +
+
Request: .rr ident
+
+ + +

Remove register ident. If ident doesn’t exist, the request +is ignored. Technically, only the name is removed; the register’s +contents are still accessible under aliases created with aln, if +any. +

+ +
+
Request: .rnn ident1 ident2
+
+ + +

Rename register ident1 to ident2. If ident1 doesn’t +exist, the request is ignored. Renaming a built-in register does not +otherwise alter its properties. +

+ +
+
Request: .aln new old
+
+ + + +

Create an alias new for an existing register old, causing +the names to refer to the same stored object. If old is +undefined, a warning in category ‘reg’ is produced and the request +is ignored. See Warnings, for information about the enablement and +suppression of warnings. +

+ + + +

To remove a register alias, invoke rr on its name. A register’s +contents do not become inaccessible until it has no more names. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Registers   [Contents][Index]

+
+

5.8.2 Interpolating Registers

+ + + +

Register contents are interpolated with the \n escape sequence. +

+
+
Escape sequence: \ni
+
+
Escape sequence: \n(id
+
Escape sequence: \n[ident]
+
+ + + +

Interpolate register with name ident (one-character +name i, two-character name id). \n is +interpreted even in copy mode (see Copy Mode). If the register is +undefined, it is created and assigned a value of ‘0’, that +value is interpolated, and a warning in category ‘reg’ is emitted. +See Warnings, for information about the enablement and suppression of +warnings. +

+
+
.nr a 5
+.nr as \na+\na
+\n(as
+    ⇒ 10
+
+ +
+
.nr a1 5
+.nr ab 6
+.ds str b
+.ds num 1
+\n[a\n[num]]
+    ⇒ 5
+\n[a\*[str]]
+    ⇒ 6
+
+
+ + +
+
+
+
+

+Next: , Previous: , Up: Registers   [Contents][Index]

+
+

5.8.3 Auto-increment

+ + + + +

Registers can also be incremented or decremented by a configured amount +at the time they are interpolated. The value of the increment is +specified with a third argument to the nr request, and a special +interpolation syntax is used to alter and then retrieve the register’s +value. Together, these features are called +auto-increment.51 +

+
+
Request: .nr ident value incr
+
+ +

Set register ident to value and its auto-incrementation +amount to to incr. The \R escape sequence doesn’t support +an incr argument. +

+ +

Auto-incrementation is not completely automatic; the \n +escape sequence in its basic form never alters the value of a register. +To apply auto-incrementation to a register, interpolate it with +‘\n±’. +

+
+
Escape sequence: \n+i
+
+
Escape sequence: \n-i
+
Escape sequence: \n+(id
+
Escape sequence: \n-(id
+
Escape sequence: \n+[ident]
+
Escape sequence: \n-[ident]
+

Increment or decrement ident (one-character +name i, two-character name id) by the register’s +auto-incrementation value and then interpolate the new register value. +If ident has no auto-incrementation value, interpolate as with +\n. +

+ +
+
.nr a 0 1
+.nr xx 0 5
+.nr foo 0 -2
+\n+a, \n+a, \n+a, \n+a, \n+a
+.br
+\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
+.br
+\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
+    ⇒ 1, 2, 3, 4, 5
+    ⇒ -5, -10, -15, -20, -25
+    ⇒ -2, -4, -6, -8, -10
+
+ + + +

To change the increment value without changing the value of a register, +assign the register’s value to itself by interpolating it, and specify +the desired increment normally. Apply an increment of ‘0’ to +disable auto-incrementation of the register. +

+ +
+
+
+
+

+Next: , Previous: , Up: Registers   [Contents][Index]

+
+

5.8.4 Assigning Register Formats

+ + + + +

A writable register’s value can be interpolated in several number +formats. By default, conventional Arabic numerals are used. +Other formats see use in sectioning and outlining schemes and +alternative page numbering arrangements. +

+
+
Request: .af reg fmt
+
+

Use number format fmt when interpolating register reg. +Valid number formats are as follows. +

+
+
0…
+

Arabic numerals 0, 1, 2, and so on. +Any decimal digit is equivalent to ‘0’; the formatter merely counts +the digits specified. Multiple Arabic numerals in fmt cause +interpolations to be zero-padded on the left if necessary to at least as +many digits as specified (interpolations never truncate a register +value). A register with format ‘00’ interpolates values 1, 2, 3 as +‘01’, ‘02’, ‘03’. The default format for all writable +registers is ‘0’. +

+
+
I
+
+

Uppercase Roman numerals: 0, I, II, III, IV, ... +

+
+
i
+

Lowercase Roman numerals: 0, i, ii, iii, iv, ... +

+
+
A
+

Uppercase letters: 0, A, B, C, …, Z, AA, AB, ... +

+
+
a
+

Lowercase letters: 0, a, b, c, …, z, aa, ab, ... +

+
+ +

Omitting fmt causes a warning in category ‘missing’. +See Warnings, for information about the enablement and suppression of +warnings. Specifying an unrecognized format is an error. +

+

Zero values are interpolated as ‘0’ in non-Arabic formats. +Negative quantities are prefixed with ‘-’ irrespective of format. +In Arabic formats, the sign supplements the field width. If reg +doesn’t exist, it is created with a zero value. +

+
+
.nr a 10
+.af a 0           \" the default format
+\na,
+.af a I
+\na,
+.af a 321
+.nr a (-\na)
+\na,
+.af a a
+\na
+    ⇒ 10, X, -010, -j
+
+ + + + + +

The representable extrema in the ‘i’ and ‘I’ formats +correspond to Arabic ±39,999. GNU troff uses ‘w’ and +‘z’ to represent 5,000 and 10,000 in Roman numerals, respectively, +following the convention of AT&T troff—currently, the +correct glyphs for Roman numerals five thousand (U+2181) and ten +thousand (U+2182) are not used. +

+ + +

Assigning the format of a read-only register is an error. Instead, copy +the read-only register’s value to, and assign the format of, a writable +register. +

+ +
+
Escape sequence: \gr
+
+
Escape sequence: \g(rg
+
Escape sequence: \g[reg]
+
+ +

Interpolate the format of the register reg (one-character +name r, two-character name rg). Zeroes represent +Arabic formats. If reg is not defined, reg is not created +and nothing is interpolated. \g is interpreted even in copy mode +(see Copy Mode). +

+ + + +

GNU troff interprets only Arabic numerals. The Roman numeral or +alphabetic formats cannot be used as operands to arithmetic operators in +expressions (see Numeric Expressions). For instance, it may be +desirable to test the page number independently of its format. +

+
+
.af % i \" front matter
+.de header-trap
+.  \" To test the page number, we need it in Arabic.
+.  ds saved-page-number-format \\g%\"
+.  af % 0
+.  nr page-number-in-decimal \\n%
+.  af % \\*[saved-page-number-format]
+.  ie \\n[page-number-in-decimal]=1 .do-first-page-stuff
+.  el \{\
+.    ie o .do-odd-numbered-page-stuff
+.    el   .do-even-numbered-page-stuff
+.  \}
+.  rm saved-page-number-format
+..
+.wh 0 header-trap
+
+ + +
+
+
+
+

+Previous: , Up: Registers   [Contents][Index]

+
+

5.8.5 Built-in Registers

+ + + +

Predefined registers whose identifiers start with a dot are read-only. +Many are Boolean-valued, interpolating a true or false value testable +with the if, ie, or while requests. Some read-only +registers are string-valued, meaning that they interpolate text. +

+ + + +

Caution: Built-in registers are subject to removal like +others; once removed, they can be recreated only as normal writable +registers and will not reflect formatter state. +

+

A register name (without the dot) is often associated with a request of +the same name. A complete listing of all built-in registers can be +found in Register Index. +

+

We present here a few built-in registers that are not described +elsewhere in this manual; they have to do with invariant properties of +GNU troff, or obtain information about the formatter’s +command-line options, processing progress, or the operating environment. +

+
+
\n[.A]
+
+ +

Approximate output is being formatted (Boolean-valued); see +groff -a option (Options). +

+
+
\n[.c]
+
+
+
\n[c.]
+
+ +

Input line number. ‘c.’ is a writable synonym, +affecting subsequent interpolations of both ‘.c’ and ‘c.’. +

+
+
\n[.F]
+
+ +

Name of input file (string-valued). +

+
+
\n[.g]
+
+ +

Always true in GNU troff (Boolean-valued). Documents can use +this to ask the formatter if it claims groff compatibility. +

+
+
\n[.P]
+

Output page selection status (Boolean-valued); see groff +-o option (Options). +

+
+
\n[.R]
+
+ +

Count of available unused registers; always 10,000 in GNU +troff.52 +

+
+
\n[.T]
+

Indicator of output device selection (Boolean-valued); see +groff -T option (Options). +

+
+
\n[.U]
+
+ + + +

Unsafe mode enablement status (Boolean-valued); see groff +-U option (Options). +

+
+
\n[.x]
+
+ +

Major version number of the running GNU troff formatter. For +example, if the version number is 1.23.0, then .x +contains ‘1’. +

+
+
\n[.y]
+
+ +

Minor version number of the running GNU troff formatter. For +example, if the version number is 1.23.0, then .y +contains ‘23’. +

+
+
\n[.Y]
+
+

Revision number of the running GNU troff formatter. For example, +if the version number is 1.23.0, then .Y contains ‘0’. +

+
+
\n[$$]
+
+ + + +

Process identifier (PID) of the GNU troff program in its +operating environment. +

+
+ +

Date- and time-related registers are set per the local time as +determined by localtime(3) when the formatter launches. This +initialization can be overridden by SOURCE_DATE_EPOCH and +TZ; see Environment. +

+
+
\n[seconds]
+
+ + +

Count of seconds elapsed in the minute (0–60).

+
+
\n[minutes]
+
+ + +

Count of minutes elapsed in the hour (0–59). +

+
+
\n[hours]
+
+ + +

Count of hours elapsed since midnight (0–23). +

+
+
\n[dw]
+
+ +

Day of the week (1–7; 1 is Sunday). +

+
+
\n[dy]
+
+ +

Day of the month (1–31). +

+
+
\n[mo]
+
+ +

Month of the year (1–12). +

+
+
\n[year]
+
+ +

Gregorian year. +

+ + +
+
\n[yr]
+

Gregorian year minus 1900. This register is incorrectly documented +in the AT&T troff manual as storing the last two digits +of the current year. That claim stopped being true in 2000. Old +troff input that looks like: +

+
+
'\" The year number is a surprise after 1999.
+This document was formatted in 19\n(yr.
+
+ +

can be corrected to: +

+
+
This document was formatted in \n[year].
+
+ +

or, for portability across many roff programs, to the following. +

+
+
.nr y4 1900+\n(yr
+This document was formatted in \n(y4.
+
+
+
+ + + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.9 Manipulating Filling and Adjustment

+ + + + + + + + + + + + + + + + + + + +

When an output line is pending (see below), a break moves the drawing +position to the beginning of the next text baseline, interrupting +filling. Various ways of causing breaks were shown in Breaking. +The br request likewise causes a break. Several other requests +imply breaks: bp, ce, cf, fi, fl, +in, nf, rj, sp, ti, and trf. +If the no-break control character is used with any of these requests, +GNU troff suppresses the break; instead the requested operation +takes effect at the next break. ‘'br’ does nothing. +

+
+
.ll 55n
+This line is normally filled and adjusted.
+.br
+A line's alignment is decided
+'ce \" Center the next input line (no break).
+when it is output.
+This line returns to normal filling and adjustment.
+    ⇒ This line is normally filled and adjusted.
+    ⇒    A line's alignment is decided when it is output.
+    ⇒ This line returns to normal filling and adjustment.
+
+ + + + + +

Output line properties like page offset, indentation, adjustment, and +even the location of its text baseline, are not determined until the +line has been broken. An output line is said to be pending if +some input has been collected but an output line corresponding to it has +not yet been written; such an output line is also termed partially +collected. If no output line is pending, it is as if a break has +already happened; additional breaks, whether explicit or implicit, have +no effect. If the vertical drawing position is negative—as it is when +the formatter starts up—a break starts a new page (even if no output +line is pending) unless an end-of-input macro is being interpreted. +See End-of-input Traps. +

+
+
Request: .br
+
+

Break the line: emit any pending output line without adjustment. +

+
+
foo bar
+.br
+baz
+'br
+qux
+    ⇒ foo bar
+    ⇒ baz qux
+
+
+ +

Sometimes you want to prevent a break within a phrase or between a +quantity and its units. +

+
+
Escape sequence: \~
+
+ + +

Insert an unbreakable space that is adjustable like an ordinary space. +It is discarded from the end of an output line if a break is forced. +

+
+
Set the output speed to\~1.
+There are 1,024\~bytes in 1\~KiB.
+J.\~F.\~Ossanna wrote the original CSTR\~#54.
+
+
+ +

By default, GNU troff fills text and adjusts it to reach the +output line length. The nf request disables filling; the +fi request reënables it. +

+
+
Request: .fi
+
+
Register: \n[.u]
+
+ + + + +

Enable filling of output lines; a pending output line is broken. The +read-only register .u is set to 1. The filling enablement +status, sometimes called fill mode, is associated with the +environment (see Environments). See Line Continuation, for +interaction with the \c escape sequence. +

+ +
+
Request: .nf
+
+ + + + + + +

Disable filling of output lines: the output line length (see Line Layout) is ignored and output lines are broken where the input lines +are. A pending output line is broken and adjustment is suppressed. The +read-only register .u is set to 0. The filling enablement +status is associated with the environment (see Environments). See +Line Continuation, for interaction with the \c escape +sequence. +

+ +
+
Request: .ad [mode]
+
+
Register: \n[.j]
+
+

Enable output line adjustment in mode, taking effect when the +pending (or next) output line is broken. Adjustment is suppressed when +filling is. mode can have one of the following values. +

+
+
b
+
n
+

Adjust “normally”: if the output line does not consume the distance +between the indentation and the configured output line length, GNU +troff stretches adjustable spaces within the line until that +length is reached. When the indentation is zero, this mode spreads the +line to both the left and right margins. This is the GNU troff +default. +

+
+
c
+

Center filled text. Contrast with the ce request, which centers +text without filling it. +

+
+
l
+

Align text to the left without adjusting it. +

+
+
r
+

Align text to the right without adjusting it. +

+
+ +

mode can also be a value previously stored in the .j +register. Using ad without an argument is the same as ‘.ad +\n[.j]’; unless filling is disabled, GNU troff resumes adjusting +lines in the same way it did before adjustment was disabled by +invocation of the na request. +

+ +

The adjustment mode and enablement status are encoded in the read-only +register .j. These parameters are associated with the +environment (see Environments). +

+

The value of .j for any adjustment mode is an implementation +detail and should not be relied upon as a programmer’s interface. Do +not write logic to interpret or perform arithmetic on it. +

+
+
.ll 48n
+.de AD
+.  br
+.  ad \\$1
+..
+.de NA
+.  br
+.  na
+..
+left
+.AD r
+.nr ad \n(.j
+right
+.AD c
+center
+.NA
+left
+.AD
+center
+.AD \n(ad
+right
+
+
+
    ⇒ left
+    ⇒                                            right
+    ⇒                      center
+    ⇒ left
+    ⇒                      center
+    ⇒                                            right
+
+
+ +
+
Request: .na
+
+

Disable output line adjustment. This produces the same output as +left-alignment, but the value of the adjustment mode register .j +is altered differently. The adjustment mode and enablement status are +associated with the environment (see Environments). +

+ +
+
Request: .brp
+
+
Escape sequence: \p
+
+

Break, adjusting the line per the current adjustment mode. \p +schedules a break with adjustment at the next word boundary. The escape +sequence is itself neither a break nor a space of any kind; it can thus +be placed in the middle of a word to cause a break at the end of that +word. +

+

Breaking with immediate adjustment can produce ugly results since GNU +troff doesn’t have a sophisticated paragraph-building algorithm, +as TeX has, for example. Instead, GNU troff fills and adjusts +a paragraph line by line. +

+
+
.ll 4.5i
+This is an uninteresting sentence.
+This is an uninteresting sentence.\p
+This is an uninteresting sentence.
+
+ +

is formatted as follows. +

+
+
This  is  an uninteresting sentence.  This is
+an          uninteresting           sentence.
+This is an uninteresting sentence.
+
+
+ + + + +

To clearly present the next couple of requests, we must introduce the +concept of “productive” input lines. A productive input line is +one that directly produces formatted output. Text lines produce +output,53 as do control +lines containing requests like tl or escape sequences like +\D. Macro calls are not directly productive, and thus not +counted, but their interpolated contents can be. Empty requests, and +requests and escape sequences that define registers or strings or alter +the formatting environment (as with changes to the size, face, height, +slant, or color of the type) are not productive. We will also preview +the output line continuation escape sequence, \c, which +“connects” two input lines that would otherwise be counted separately. +54 +

+
+
.de hello
+Hello, world!
+..
+.ce \" center output of next productive input line
+.
+.nr junk-reg 1
+.ft I
+Chorus: \c
+.ft
+.hello
+Went the day well?
+  ⇒                  Chorus: Hello, world!
+  ⇒ Went the day well?
+
+ +
+
Request: .ce [n]
+
+
Register: \n[.ce]
+
+ + + +

Break (unless the no-break control character is used), center the output +of the next n productive input lines with respect to the line +length and indentation without filling, then break again regardless of +the invoking control character. +If the argument is not positive, centering is disabled. Omitting the +argument implies an n of ‘1’. The count of lines remaining +to be centered is stored in the read-only register .ce and is +associated with the environment (see Environments). +

+ +

While the ‘.ad c’ request also centers text, it fills the text +as well. +

+
+
.de FR
+This is a small text fragment that shows the differences
+between the `.ce' and the `.ad c' requests.
+..
+.ll 4i
+.ce 1000
+.FR
+.ce 0
+
+.ad c
+.FR
+    ⇒ This is a small text fragment that shows
+    ⇒              the differences
+    ⇒ between the ‘.ce’ and the ‘.ad c’ requests.
+    ⇒
+    ⇒ This is a small text fragment that shows
+    ⇒  the differences between the ‘.ce’ and
+    ⇒         the ‘.ad c’ requests.
+
+ +

The previous example illustrates a common idiom of turning centering on +for a quantity of lines far in excess of what is required, and off again +after the text to be centered. This technique relieves humans of +counting lines for requests that take a count of input lines as an +argument. +

+ +
+
Request: .rj [n]
+
+
Register: \n[.rj]
+
+ + + +

Break (unless the no-break control character is used), align the output +of the next n productive input lines to the right margin without +filling, then break again regardless of the control character. +If the argument is not positive, right-alignment is disabled. Omitting +the argument implies an n of ‘1’. The count of lines +remaining to be right-aligned is stored in the read-only register +.rj and is associated with the environment +(see Environments). +

+
+
.ll 49n
+.rj 3
+At first I hoped that such a technically unsound
+project would collapse but I soon realized it was
+doomed to success. \[em] C. A. R. Hoare
+    ⇒  At first I hoped that such a technically unsound
+    ⇒ project would collapse but I soon realized it was
+    ⇒              doomed to success. -- C. A. R. Hoare
+
+
+ +
+
Request: .ss word-space-size [additional-sentence-space-size]
+
+
Register: \n[.ss]
+
+
Register: \n[.sss]
+
+ + + + + + + +

Set the sizes of spaces between words and +sentences55 in twelfths +of font’s space width (typically one-fourth to one-third em for Western +scripts). The default for both parameters is 12. Negative values +are erroneous. + + + +The first argument is a minimum; if an output line undergoes adjustment, +such spaces may increase in width. + + + +The optional second argument sets the amount of additional space +separating sentences on the same output line. If omitted, this amount +is set to word-space-size. The request is ignored if there are no +parameters. +

+ + +

Additional inter-sentence space is used only if the output line is not +full when the end of a sentence occurs in the input. If a sentence ends +at the end of an input line, then both an inter-word space and an +inter-sentence space are added to the output; if two spaces follow the +end of a sentence in the middle of an input line, then the second space +becomes an inter-sentence space in the output. Additional +inter-sentence space is not adjusted, but the inter-word space that +always precedes it may be. Further input spaces after the second, if +present, are adjusted as normal. +

+

The read-only registers .ss and .sss hold the minimal +inter-word space and additional inter-sentence space amounts, +respectively. These parameters are part of the environment +(see Environments), and rounded down to the nearest multiple +of 12 on terminals. +

+ + + +

The ss request can insert discardable horizontal space; that is, +space that is discarded at a break. For example, some footnote styles +collect the notes into a single paragraph with large gaps between +each note. +

+
+
.ll 48n
+1.\~J. Fict. Ch. Soc. 6 (2020), 3\[en]14.
+.ss 12 48 \" applies to next sentence ending
+Reprints no longer available through FCS.
+.ss 12 \" go back to normal
+2.\~Better known for other work.
+    ⇒ 1.  J.  Fict. Ch. Soc. 6 (2020), 3-14.  Reprints
+    ⇒ no longer available through FCS.      2.  Better
+    ⇒ known for other work.
+
+ +

If undiscardable space is required, use the \h escape +sequence. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.10 Manipulating Hyphenation

+ + + + + +

When filling, GNU troff hyphenates words as needed at +user-specified and automatically determined hyphenation points. The +machine-driven determination of hyphenation points in words requires +algorithms and data, and is susceptible to conventions and preferences. +Before tackling such automatic hyphenation, let us consider how +hyphenation points can be set explicitly. +

+ + + + +

Explicitly hyphenated words such as “mother-in-law” are eligible for +breaking after each of their hyphens. Relatively few words in a +language offer such obvious break points, however, and automatic +detection of syllabic (or phonetic) boundaries for hyphenation is not +perfect,56 particularly for +unusual words found in technical literature. We can instruct GNU +troff how to hyphenate specific words if the need arises. +

+ +
+
Request: .hw word …
+
+

Define each hyphenation exception word with each hyphen ‘-’ +in the word indicating a hyphenation point. For example, the request +

+
+
.hw in-sa-lub-rious alpha
+
+ +

marks potential hyphenation points in “insalubrious”, and prevents +“alpha” from being hyphenated at all. +

+

Besides the space character, any character whose hyphenation code is +zero can be used to separate the arguments of hw (see the +hcode request below). In addition, this request can be used more +than once. +

+ +

Hyphenation points specified with hw are not subject to the +within-word placement restrictions imposed by the hy request (see +below). +

+

Hyphenation exceptions specified with the hw request are +associated with the hyphenation language (see the hla request +below) and environment (see Environments); invoking the hw +request in the absence of a hyphenation language is an error. +

+

The request is ignored if there are no parameters. +

+ +

These are known as hyphenation exceptions in the expectation +that most users will avail themselves of automatic hyphenation; these +exceptions override any rules that would normally apply to a word +matching a hyphenation exception defined with hw. +

+

Situations also arise when only a specific occurrence of a word needs +its hyphenation altered or suppressed, or when a URL or similar string +needs to be breakable in sensible places without hyphenation. +

+
+
Escape sequence: \%
+
+
Escape sequence: \:
+
+ + + + +

To tell GNU troff how to hyphenate words as they occur in input, +use the \% escape sequence; it is the default hyphenation +character. Each instance within a word indicates to GNU troff +that the word may be hyphenated at that point, while prefixing a word +with this escape sequence prevents it from being otherwise hyphenated. +This mechanism affects only that occurrence of the word; to change the +hyphenation of a word for the remainder of input processing, use the +hw request. +

+ + + +

GNU troff regards the escape sequences \X and \Y as +starting a word; that is, the \% escape sequence in, say, +‘\X'...'\%foobar’ or ‘\Y'...'\%foobar’ no longer +prevents hyphenation of ‘foobar’ but inserts a hyphenation point +just prior to it; most likely this isn’t what you want. +See Postprocessor Access. +

+ + + + + + +

\: inserts a non-printing break point; that is, a word can break +there, but the soft hyphen glyph (see below) is not written to the +output if it does. This escape sequence is an input word boundary, so +the remainder of the word is subject to hyphenation as normal. +

+

You can combine \: and \% to control breaking of a file +name or URL, or to permit hyphenation only after certain explicit +hyphens within a word. +

+
+
The \%Lethbridge-Stewart-\:\%Sackville-Baggins divorce
+was, in retrospect, inevitable once the contents of
+\%/var/log/\:\%httpd/\:\%access_log on the family web
+server came to light, revealing visitors from Hogwarts.
+
+
+ +
+
Request: .hc [char]
+
+

Change the hyphenation character to char. This character then +works as the \% escape sequence normally does, and thus no longer +appears in the output.57 Without an +argument, hc resets the hyphenation character to \% (the +default). The hyphenation character is associated with the environment +(see Environments). +

+ +
+
Request: .shc [c]
+
+ + + + + + +

Set the soft hyphen character, inserted when a word is hyphenated +automatically or at a hyphenation character, to the ordinary or special +character c.58 If the argument is omitted, the soft +hyphen character is set to the default, \[hy]. If no glyph for +c exists in the font in use at a potential hyphenation point, then +the line is not broken there. Neither character definitions (specified +with the char and similar requests) nor translations (specified +with the tr request) are applied to c. +

+ + + +

Several requests influence automatic hyphenation. Because conventions +vary, a variety of hyphenation modes is available to the hy +request; these determine whether hyphenation will apply to a +word prior to breaking a line at the end of a page (more or less; see +below for details), and at which positions within that word +automatically determined hyphenation points are permissible. The places +within a word that are eligible for hyphenation are determined by +language-specific data and lettercase relationships. Furthermore, +hyphenation of a word might be suppressed due to a limit on +consecutive hyphenated lines (hlm), a minimum line length +threshold (hym), or because the line can instead be adjusted with +additional inter-word space (hys). +

+ +
+
Request: .hy [mode]
+
+
Register: \n[.hy]
+
+

Set automatic hyphenation mode to mode, an integer encoding +conditions for hyphenation; if omitted, ‘1’ is implied. The +hyphenation mode is available in the read-only register ‘.hy’; it +is associated with the environment (see Environments). The default +hyphenation mode depends on the localization file loaded when GNU +troff starts up; see the hpf request below. +

+

Typesetting practice generally does not avail itself of every +opportunity for hyphenation, but the details differ by language and site +mandates. The hyphenation modes of AT&T troff were +implemented with English-language publishing practices of the 1970s in +mind, not a scrupulous enumeration of conceivable parameters. GNU +troff extends those modes such that finer-grained control is +possible, favoring compatibility with older implementations over a more +intuitive arrangement. The means of hyphenation mode control is a set +of numbers that can be added up to encode the behavior +sought.59 The entries in the +following table are termed values; the sum of the desired +values is the mode. +

+
+
0
+

disables hyphenation. +

+
+
1
+

enables hyphenation except after the first and before the last character +of a word. +

+
+ +

The remaining values “imply” 1; that is, they enable hyphenation +under the same conditions as ‘.hy 1’, and then apply or lift +restrictions relative to that basis. +

+
+
2
+

disables hyphenation of the last word on a page,60 even for explicitly hyphenated words. +

+
+
4
+

disables hyphenation before the last two characters of a word. +

+
+
8
+

disables hyphenation after the first two characters of a word. +

+
+
16
+

enables hyphenation before the last character of a word. +

+
+
32
+

enables hyphenation after the first character of a word. +

+
+ +

Apart from value 2, restrictions imposed by the hyphenation mode +are not respected for words whose hyphenations have been +specified with the hyphenation character (‘\%’ by default) or the +hw request. +

+

Nonzero values in the previous table are additive. For example, +mode 12 causes GNU troff to hyphenate neither the last two +nor the first two characters of a word. Some values cannot be used +together because they contradict; for instance, values 4 and 16, +and values 8 and 32. As noted, it is superfluous to add 1 to any +non-zero even mode. +

+ + +

The automatic placement of hyphens in words is determined by +pattern files, which are derived from TeX and available for +several languages. The number of characters at the beginning of a word +after which the first hyphenation point should be inserted is determined +by the patterns themselves; it can’t be reduced further without +introducing additional, invalid hyphenation points (unfortunately, this +information is not part of a pattern file—you have to know it in +advance). The same is true for the number of characters at the end of +a word before the last hyphenation point should be inserted. For +example, you can supply the following input to ‘echo $(nroff)’. +

+
+
.ll 1
+.hy 48
+splitting
+
+ +

You will get +

+
+
s- plit- t- in- g
+
+ +

instead of the correct ‘split- ting’. English patterns as distributed +with GNU troff need two characters at the beginning and three +characters at the end; this means that value 4 of hy is +mandatory. Value 8 is possible as an additional restriction, but +values 16 and 32 should be avoided, as should mode 1. +Modes 4 and 6 are typical. +

+

A table of left and right minimum character counts for hyphenation as +needed by the patterns distributed with GNU troff follows; see +the groff_tmac(5) man page for more information on GNU +troff’s language macro files. +

+ + + + + + + + + + +
languagepattern nameleft minright min
Czechcs22
Englishen23
Frenchfr23
German traditionaldet22
German reformedden22
Italianit22
Swedishsv12
+ +

Hyphenation exceptions within pattern files (i.e., the words within a +TeX \hyphenation group) obey the hyphenation restrictions +given by hy. +

+ +
+
Request: .nh
+
+

Disable automatic hyphenation; i.e., set the hyphenation mode to 0 +(see above). The hyphenation mode of the last call to hy is not +remembered. +

+ +
+
Request: .hpf pattern-file
+
+
Request: .hpfa pattern-file
+
+
Request: .hpfcode a b [c d] …
+
+ + +

Read hyphenation patterns from pattern-file, which is sought +in the same way that macro files are with the mso request or the +-mname command-line option to groff. The +pattern-file should have the same format as (simple) TeX +pattern files. More specifically, the following scanning rules are +implemented. +

+
    +
  • A percent sign starts a comment (up to the end of the line) even if +preceded by a backslash. + +
  • “Digraphs” like \$ are not supported. + +
  • ^^xx (where each x is 0–9 or a–f) and +^^c (character c in the code point range 0–127 +decimal) are recognized; other uses of ^ cause an error. + +
  • No macro expansion is performed. + +
  • hpf checks for the expression \patterns{…} +(possibly with whitespace before or after the braces). Everything +between the braces is taken as hyphenation patterns. Consequently, +{ and } are not allowed in patterns. + +
  • Similarly, \hyphenation{…} gives a list of hyphenation +exceptions. + +
  • \endinput is recognized also. + +
  • For backward compatibility, if \patterns is missing, the whole +file is treated as a list of hyphenation patterns (except that the +% character is recognized as the start of a comment). +
+ +

The hpfa request appends a file of patterns to the current list. +

+

The hpfcode request defines mapping values for character codes in +pattern files. It is an older mechanism no longer used by GNU +troff’s own macro files; for its successor, see hcode +below. hpf or hpfa apply the mapping after reading the +patterns but before replacing or appending to the active list of +patterns. Its arguments are pairs of character codes—integers from 0 +to 255. The request maps character code a to +code b, code c to code d, and so on. +Character codes that would otherwise be invalid in GNU troff can +be used. By default, every code maps to itself except those for letters +‘A’ to ‘Z’, which map to those for ‘a’ to ‘z’. +

+ + + + + + + + + + +

The set of hyphenation patterns is associated with the language set by +the hla request (see below). The hpf request is usually +invoked by a localization file loaded by the troffrc +file.61 +

+

A second call to hpf (for the same language) replaces the +hyphenation patterns with the new ones. Invoking hpf or +hpfa causes an error if there is no hyphenation language. If no +hpf request is specified (either in the document, in a file +loaded at startup, or in a macro package), GNU troff won’t +automatically hyphenate at all. +

+ +
+
Request: .hcode c1 code1 [c2 code2] …
+
+ + +

Set the hyphenation code of character c1 to code1, that of +c2 to code2, and so on. A hyphenation code must be an +ordinary character (not a special character escape sequence) other than +a digit or a space. The request is ignored if given no arguments. +

+

For hyphenation to work, hyphenation codes must be set up. At +startup, GNU troff assigns hyphenation codes to the letters +‘a’–‘z’ (mapped to themselves), to the letters +‘A’–‘Z’ (mapped to ‘a’–‘z’), and zero to all other +characters. Normally, hyphenation patterns contain only lowercase +letters which should be applied regardless of case. In other words, +they assume that the words ‘FOO’ and ‘Foo’ should be hyphenated exactly +as ‘foo’ is. The hcode request extends this principle to letters +outside the Unicode basic Latin alphabet; without it, words containing +such letters won’t be hyphenated properly even if the corresponding +hyphenation patterns contain them. +

+

For example, the following hcode requests are necessary to assign +hyphenation codes to the letters ‘ÄäÖöÜüß’, needed for German. +

+
+
.hcode ä ä  Ä ä
+.hcode ö ö  Ö ö
+.hcode ü ü  Ü ü
+.hcode ß ß
+
+ +

Without these assignments, GNU troff treats the German word +‘Kindergärten’ (the plural form of ‘kindergarten’) as two words +‘kinderg’ and ‘rten’ because the hyphenation code of the +umlaut a is zero by default, just like a space. There is a German +hyphenation pattern that covers ‘kinder’, so GNU troff finds +the hyphenation ‘kin-der’. The other two hyphenation points +(‘kin-der-gär-ten’) are missed. +

+ +
+
Request: .hla lang
+
+
Register: \n[.hla]
+
+ + + + +

Set the hyphenation language to lang. Hyphenation exceptions +specified with the hw request and hyphenation patterns and +exceptions specified with the hpf and hpfa requests are +associated with the hyphenation language. The hla request is +usually invoked by a localization file, which is turn loaded by the +troffrc or troffrc-end file; see the hpf request +above. +

+ +

The hyphenation language is available in the read-only string-valued +register ‘.hla’; it is associated with the environment +(see Environments). +

+ +
+
Request: .hlm [n]
+
+
Register: \n[.hlm]
+
+
Register: \n[.hlc]
+
+ + + + + +

Set the maximum quantity of consecutive hyphenated lines to n. If +n is negative, there is no maximum. If omitted, n +is −1. This value is associated with the environment +(see Environments). Only lines output from a given environment +count toward the maximum associated with that environment. Hyphens +resulting from \% are counted; explicit hyphens are not. +

+ + +

The .hlm read-only register stores this maximum. The count of +immediately preceding consecutive hyphenated lines is available in the +read-only register .hlc. +

+ +
+
Request: .hym [length]
+
+
Register: \n[.hym]
+
+ + + +

Set the (right) hyphenation margin to length. If the adjustment +mode is not ‘b’ or ‘n’, the line is not hyphenated if it is +shorter than length. Without an argument, the hyphenation margin +is reset to its default value, 0. The default scaling unit is ‘m’. +The hyphenation margin is associated with the environment +(see Environments). +

+

A negative argument resets the hyphenation margin to zero, emitting a +warning in category ‘range’. +

+ +

The hyphenation margin is available in the .hym read-only +register. +

+ +
+
Request: .hys [hyphenation-space]
+
+
Register: \n[.hys]
+
+ + + +

Suppress hyphenation of the line in adjustment modes ‘b’ or +‘n’ if it can be justified by adding no more than +hyphenation-space extra space to each inter-word space. Without +an argument, the hyphenation space adjustment threshold is set to its +default value, 0. The default scaling unit is ‘m’. The +hyphenation space adjustment threshold is associated with the +environment (see Environments). +

+

A negative argument resets the hyphenation space adjustment threshold to +zero, emitting a warning in category ‘range’. +

+ +

The hyphenation space adjustment threshold is available in the +.hys read-only register. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.11 Manipulating Spacing

+ + + +

A break causes the formatter to update the vertical drawing position at +which the new text baseline is aligned. You can alter this location. +

+
+
Request: .sp [distance]
+
+

Break and move the next text baseline down by distance, or until +springing a page location trap.62 +If invoked with the no-break control character, sp moves the +pending output line’s text baseline by distance. A negative +distance will not reduce the position of the text baseline below +zero. Inside a diversion, any distance argument is ignored. The +default scaling unit is ‘v’. If distance is not specified, +‘1v’ is assumed. +

+
+
.pl 5v \" Set page length to 5 vees.
+.de xx
+\-\-\-
+.  br
+..
+.wh 0 xx \" Set a trap at the top of the page.
+foo on page \n%
+.sp 2v
+bar on page \n%
+.sp 50v \" This will cause a page break.
+baz on page \n%
+.pl \n(nlu \" Truncate page to current position.
+    ⇒ ---
+    ⇒ foo on page 1
+    ⇒
+    ⇒
+    ⇒ bar on page 1
+    ⇒ ---
+    ⇒ baz on page 2
+
+ +

You might use the following macros to set the baseline of the next +output text at a given distance from the top or the bottom of the page. +We subtract one line height (\n[.v]) because the | +operator moves to one vee below the page top (recall Numeric Expressions). +

+
+
.de y-from-top-down
+.  sp |\\$1-\\n[.v]u
+..
+.
+.de y-from-bot-up
+.  sp |\\n[.p]u-\\$1-\\n[.v]u
+..
+
+ +

A call to ‘.y-from-bot-up 10c’ means that the next text baseline +will be 10 cm from the bottom edge of the paper. +

+ +
+
Request: .ls [count]
+
+
Register: \n[.L]
+
+ +

Set the line spacing; add count−1 blank lines after each +line of text. With no argument, GNU troff uses the previous +value before the last ls call. The default is 1. +

+ + +

The read-only register .L contains the current line spacing; it +is associated with the environment (see Environments). +

+ +

The ls request is a coarse mechanism. See Changing the Type Size, for the requests vs and pvs as alternatives to +ls. +

+
+
Escape sequence: \x'spacing'
+
+
Register: \n[.a]
+
+

Sometimes, an output line requires additional vertical spacing, for +instance to allow room for a tall construct like an inline equation with +exponents or subscripts (particularly if they are iterated). The +\x escape sequence takes a delimited measurement (like +‘\x'3p'’) to increase the vertical spacing of the pending output +line. The default scaling unit is ‘v’. If the measurement is +positive, extra vertical space is inserted below the current line; a +negative measurement adds space above. If \x is applied to the +pending output line multiple times, the maxima of the positive and +negative adjustments are separately applied. The delimiter need not be +a neutral apostrophe; see Delimiters. +

+ +

The .a read-only register contains the extra vertical spacing +after the text baseline of the most recently emitted output line. +(In other words, it is the largest positive argument to \x +encountered on that line.) This quantity is exposed via a register +because if an output line requires this “extra post-vertical line +spacing”, and the subsequent output line requires “extra pre-vertical +line spacing” (a negative argument to \x), then applying both +can lead to excessive spacing between the output lines. Text that is +piling high on line n might not require (as much) extra +pre-vertical line spacing if line n−1 carries extra +post-vertical line spacing. +

+

Use of \x can be necessary in combination with the +bracket-building escape sequence \b,63 as the following example shows. +

+
+
.nf
+This is a test of \[rs]b (1).
+This is a test of \[rs]b (2).
+This is a test of \b'xyz'\x'-1m'\x'1m' (3).
+This is a test of \[rs]b (4).
+This is a test of \[rs]b (5).
+    ⇒ This is a test of \b (1).
+    ⇒ This is a test of \b (2).
+    ⇒                   x
+    ⇒ This is a test of y (3).
+    ⇒                   z
+    ⇒ This is a test of \b (4).
+    ⇒ This is a test of \b (5).
+
+
+ +

Without \x, the backslashes on the lines marked ‘(2)’ and +‘(4)’ would be overprinted. +

+
+
Request: .ns
+
+
Request: .rs
+
+
Register: \n[.ns]
+
+ + + + + +

Enable no-space mode. Vertical spacing, whether by sp +requests or blank input lines, is disabled. The bp request to +advance to the next page is also disabled, unless it is accompanied by a +page number (see Page Control). No-space mode ends automatically +when text64 is formatted for output 65 or the rs request is invoked, which ends +no-space mode. The read-only register .ns interpolates a Boolean +value indicating the enablement of no-space mode. +

+

A paragraphing macro might ordinarily insert vertical space to separate +paragraphs. A section heading macro could invoke ns to suppress +this spacing for the first paragraph in a section. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.12 Tabs and Fields

+ + + + +

A tab character (ISO code point 9, EBCDIC +code point 5) causes a horizontal movement to the next tab stop, if +any. +

+
+
Escape sequence: \t
+
+ + + + + +

Interpolate a tab in copy mode; see Copy Mode. +

+ +
+
Request: .ta [[n1 n2 … nn ]T r1 r2 … rn]
+
+
Register: \n[.tabs]
+
+

Change tab stop positions. This request takes a series of tab +specifiers as arguments (optionally divided into two groups with the +letter ‘T’) that indicate where each tab stop is to be, overriding +any previous settings. The default scaling unit is ‘m’. Invoking +ta without an argument removes all tab stops. + + +GNU troff’s startup value is ‘T 0.5i’. +

+

Tab stops can be specified absolutely—as distances from the left +margin. The following example sets six tab stops, one every inch. +

+
+
.ta 1i 2i 3i 4i 5i 6i
+
+ +

Tab stops can also be specified using a leading ‘+’, which means +that the specified tab stop is set relative to the previous tab stop. +For example, the following is equivalent to the previous example. +

+
+
.ta 1i +1i +1i +1i +1i +1i
+
+ +

GNU troff supports an extended syntax to specify repeating tab +stops. These stops appear after a ‘T’ argument. Their values are +always taken as distances relative to the previous tab stop. This is +the idiomatic way to specify tab stops at equal intervals in +groff. The following is, yet again, the same as the previous +examples. It does more, in fact, since it defines an infinite number of +tab stops at one-inch intervals. +

+
+
.ta T 1i
+
+ +

Now we are ready to interpret the full syntax given above. The +ta request sets tabs at positions n1, n2, …, +nn, then at nn+r1, nn+r2, …, +nn+rn, then at nn+rn+r1, +nn+rn+r2, …, nn+rn+rn, and so +on. +

+

For example, ‘4c +6c T 3c 5c 2c’ is equivalent to ‘4c 10c 13c +18c 20c 23c 28c 30c …’. +

+

Text written to a tab column (i.e., between two tab stops, or between a +tab stop and an output line boundary) may be aligned to the right or +left, or centered in the column. This alignment is determined by +appending ‘R’, ‘L’, or ‘C’ to the tab specifier. The +default is ‘L’. +

+
+
.ta 1i 2iC 3iR
+
+ +

The beginning of an output line is not a tab stop; the text that begins +an output line is placed according to the configured alignment and +indentation; see Manipulating Filling and Adjustment and Line Layout. +

+

A tab stop is converted into a non-breakable horizontal movement that +cannot be adjusted. +

+
+
.ll 2i
+.ds foo a\tb\tc
+.ta T 1i
+\*[foo]
+    error→ warning: cannot break line
+    ⇒ a         b         c
+
+ +

The above creates a single output line that is a bit longer than two +inches (we use a string to show exactly where the tab stops are). +Now consider the following. +

+
+
.ll 2i
+.ds bar a\tb c\td
+.ta T 1i
+\*[bar]
+    error→ warning: cannot adjust line
+    ⇒ a         b
+    ⇒ c       d
+
+ +

GNU troff first converts the line’s tab stops into unbreakable +horizontal movements, then breaks after ‘b’. This usually isn’t +what you want. +

+

Superfluous tab characters—those that do not correspond to a tab +stop—are ignored except for the first, which delimits the characters +belonging to the last tab stop for right-alignment or centering. +

+
+
.ds Z   foo\tbar\tbaz
+.ds ZZ  foo\tbar\tbazqux
+.ds ZZZ foo\tbar\tbaz\tqux
+.ta 2i 4iR
+\*[Z]
+.br
+\*[ZZ]
+.br
+\*[ZZZ]
+.br
+    ⇒ foo                 bar              baz
+    ⇒ foo                 bar           bazqux
+    ⇒ foo                 bar              bazqux
+
+ +

The first line right-aligns “baz” within the second tab stop. The +second line right-aligns “bazqux” within it. The third line +right-aligns only “baz” because of the additional tab character, which +marks the end of the text occupying the last tab stop defined. +

+

Tab stops are associated with the environment (see Environments). +

+ + + +

The read-only register .tabs contains a string +representation of the current tab settings suitable for use as an +argument to the ta request.66 +

+
+
.ds tab-string \n[.tabs]
+\*[tab-string]
+    ⇒ T120u
+
+
+ +
+
Request: .tc [c]
+
+ + + +

Set the tab repetition character to the ordinary or special character +c; normally, no glyph is written when moving to a tab stop (and +some output devices may output space characters to achieve this motion). +A tab repetition character causes the formatter to write as many +instances of c as are necessary to occupy the interval from the +horizontal drawing position to the next tab stop. With no argument, GNU +troff reverts to the default behavior. The tab repetition +character is associated with the environment (see Environments). +Only a single character of c is recognized; any excess is ignored. +

+ +
+
Request: .linetabs n
+
+
Register: \n[.linetabs]
+
+ + + +

If n is missing or non-zero, activate line-tabs; deactivate +it otherwise (the default). Active line-tabs cause GNU troff +to compute tab distances relative to the start of the output line +instead of the input line. +

+
+
.de Tabs
+.  ds x a\t\c
+.  ds y b\t\c
+.  ds z c
+.  ta 1i 3i
+\\*x
+\\*y
+\\*z
+..
+.Tabs
+.br
+.linetabs
+.Tabs
+    ⇒ a         b         c
+    ⇒ a         b                   c
+
+ +

Line-tabs activation is associated with the environment +(see Environments). The read-only register .linetabs +interpolates 1 if line-tabs are active, and 0 otherwise. +

+ + + + +
+
+
+

+Next: , Previous: , Up: Tabs and Fields   [Contents][Index]

+
+

5.12.1 Leaders

+ + +

Sometimes it is desirable to fill a tab stop with a given glyph, +but also use tab stops normally on the same output line. An example is +a table of contents entry that uses dots to bridge the entry name with +its page number, which is itself aligned between tab stops. The +roff language provides leaders for this +purpose.67 +

+ +

A leader character (ISO and EBCDIC code +point 1, also known as SOH or “start of heading”), +behaves similarly to a tab character: it moves to the next tab stop. +The difference is that for this movement, the default fill character is +a period ‘.’. +

+
+
Escape sequence: \a
+
+ + + + + +

Interpolate a leader in copy mode; see Copy Mode. +

+ +
+
Request: .lc [c]
+
+ + + +

Set the leader repetition character to the ordinary or special character +c. Recall Tabs and Leaders: when encountering a leader +character in the input, the formatter writes as many dots ‘.’ as +are necessary until +reaching the next tab stop; this is the leader definition +character. Omitting c unsets the leader +character. With no argument, GNU troff treats leaders the same +as tabs. The leader repetition character is associated with the +environment (see Environments). Only a single c is +recognized; any excess is ignored. +

+ + + +

A table of contents, for example, may define tab stops after a section +number, a title, and a gap to be filled with leader dots. The page +number follows the leader, after a right-aligned final tab stop wide +enough to house the largest page number occurring in the document. +

+
+
.ds entry1 19.\tThe Prophet\a\t98
+.ds entry2 20.\tAll Astir\a\t101
+.ta .5i 4.5i +.5iR
+.nf
+\*[entry1]
+\*[entry2]
+    ⇒ 19.  The Prophet.............................   98
+    ⇒ 20.  All Astir...............................  101
+
+ + +
+
+
+
+

+Previous: , Up: Tabs and Fields   [Contents][Index]

+
+

5.12.2 Fields

+ + + + + + + + +

Fields are a more general way of laying out tabular data. A field +is defined as the data between a pair of delimiting characters. +It contains substrings that are separated by padding characters. +The width of a field is the distance on the input line from the +position where the field starts to the next tab stop. A padding +character inserts an adjustable space similar to TeX’s \hss +command (thus it can even be negative) to make the sum of all substring +lengths plus the adjustable space equal to the field width. If more +than one padding character is inserted, the available space is evenly +distributed among them. +

+
+
Request: .fc [delim-char [padding-char]]
+
+

Define a delimiting and a padding character for fields. If the latter +is missing, the padding character defaults to a space character. If +there is no argument at all, the field mechanism is disabled (which is +the default). In contrast to, e.g., the tab repetition character, +delimiting and padding characters are not associated with the +environment (see Environments). +

+
+
.fc # ^
+.ta T 3i
+#foo^bar^smurf#
+.br
+#foo^^bar^smurf#
+    ⇒ foo         bar          smurf
+    ⇒ foo            bar       smurf
+
+
+ + + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.13 Character Translations

+ + + +

A translation is a mapping of an input character to an output +glyph. The mapping occurs at output time, i.e., the input character +gets assigned the metric information of the mapped output character +right before input tokens are converted to nodes (see gtroff Internals, for more on this process). +

+
+
Request: .tr abcd…
+
+
Request: .trin abcd…
+
+

Translate character a to glyph b, character c to +glyph d, and so on. If there is an odd number of characters +in the argument, the last one is translated to a fixed-width space (the +same one obtained by the \SP escape sequence). +

+

The trin request is identical to tr, but when you unformat +a diversion with asciify it ignores the translation. +See Diversions, for details about the asciify request. +

+

Some notes: +

+
    +
  • + + + + + + + + + + + + +Special characters (\(xx, \[xxx], +\C'xxx', \', \`, \-, \_), +glyphs defined with the char request, and numbered glyphs +(\N'xxx') can be translated also. + +
  • +The \e escape can be translated also. + +
  • + +Characters can be mapped onto the \% and \~ escape +sequences (but \% and \~ can’t be mapped onto another +glyph). + +
  • + + + + + + + + + +The following characters can’t be translated: space (with one exception, +see below), backspace, newline, leader (and \a), tab (and +\t). + +
  • +Translations are not considered for finding the soft hyphen character +set with the shc request. + +
  • +The pair ‘c\&’ (an arbitrary character c followed +by the dummy character) maps this character to “nothing”. + +
    +
    .tr a\&
+foo bar
+    ⇒ foo br
+
    + +

    Even the space character can be mapped to the dummy character. +

    +
    +
    .tr aa \&
+foo bar
+    ⇒ foobar
+
    + +

    As shown in the example, the space character can’t be the first +character/glyph pair as an argument of tr. Additionally, it is +not possible to map the space character to any other glyph; requests +like ‘.tr aa x’ undo ‘.tr aa \&’ instead. +

    +

    If justification is active, lines are justified in spite of the ‘empty’ +space character (but there is no minimal distance, i.e., the space +character, between words). +

    +
  • After an output glyph has been constructed (this happens at the moment +immediately before the glyph is appended to an output glyph list, either +by direct output, in a macro, diversion, or string), it is no longer +affected by tr. + +
  • Translating character to glyphs where one of them or both are undefined +is possible also; tr does not check whether the elements of its +argument exist. + +

    See gtroff Internals. +

    +
  • Without an argument, the tr request is ignored. +
+
+ +
+
Request: .trnt abcd…
+
+ +

trnt is the same as the tr request except that the +translations do not apply to text that is transparently throughput into +a diversion with \!. See Diversions. +

+

For example, +

+
+
.tr ab
+.di x
+\!.tm a
+.di
+.x
+
+ +

prints ‘b’ to the standard error stream; if trnt is used +instead of tr it prints ‘a’. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.14 troff and nroff Modes

+ + + + + +

Historically, nroff and troff were two separate programs; +the former for terminal output, the latter for typesetters. GNU +troff merges both functions into one executable68 that sends its output to a +device driver (grotty for terminal devices, grops for +PostScript, and so on) which interprets this intermediate output format. +When discussing AT&T troff, it makes sense to talk +about nroff mode and troff mode since the +differences are hard-coded. GNU troff takes information from +device and font description files without handling requests specially if +a terminal output device is used, so such a strong distinction is +unnecessary. +

+

Usually, a macro package can be used with all output devices. +Nevertheless, it is sometimes necessary to make a distinction between +terminal and non-terminal devices: GNU troff provides two +built-in conditions ‘n’ and ‘t’ for the if, ie, +and while requests to decide whether GNU troff shall +behave like nroff or like troff. +

+
+
Request: .troff
+
+ + +

Make the ‘t’ built-in condition true (and the ‘n’ built-in +condition false) for if, ie, and while conditional +requests. This is the default if GNU troff (not +groff) is started with the -R switch to avoid loading of +the startup files troffrc and troffrc-end. Without +-R, GNU troff stays in troff mode if the output +device is not a terminal (e.g., ‘ps’). +

+ +
+
Request: .nroff
+
+ +

Make the ‘n’ built-in condition true (and the ‘t’ built-in +condition false) for if, ie, and while conditional +requests. This is the default if GNU troff uses a terminal +output device; the code for switching to nroff mode is in the +file tty.tmac, which is loaded by the startup file +troffrc. +

+ +

See Conditionals and Loops, for more details on built-in conditions. +

+ + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.15 Line Layout

+ + + + + +

The following drawing shows the dimensions that gtroff uses for +placing a line of output onto the page. They are labeled with the +request that manipulates each dimension. +

+
+
     -->| in |<--
+        |<-----------ll------------>|
+   +----+----+----------------------+----+
+   |    :    :                      :    |
+   +----+----+----------------------+----+
+-->| po |<--
+   |<--------paper width---------------->|
+
+ +

These dimensions are: +

+
+
po
+
+ + + +

Page offset—this is the leftmost position of text on the final +output, defining the left margin. +

+
+
in
+
+ +

Indentation—this is the distance from the left margin where +text is printed. +

+
+
ll
+
+ +

Line length—this is the distance from the left margin to right +margin. +

+
+ + + +

The right margin is not explicitly configured; the combination of page +offset and line length provides the information necessary to derive it. +

+

A simple demonstration: +

+
+
.ll 3i
+This is text without indentation.
+The line length has been set to 3\~inches.
+.in +.5i
+.ll -.5i
+Now the left and right margins are both increased.
+.in
+.ll
+Calling .in and .ll without parameters restores
+the previous values.
+
+ +
+
    ⇒ This  is text without indenta-
+    ⇒ tion.   The  line  length  has
+    ⇒ been set to 3 inches.
+    ⇒      Now   the  left  and
+    ⇒      right  margins   are
+    ⇒      both increased.
+    ⇒ Calling  .in  and  .ll without
+    ⇒ parameters restores the previ-
+    ⇒ ous values.
+
+ +
+
Request: .po [offset]
+
+
Request: .po +offset
+
Request: .po -offset
+
Register: \n[.o]
+
+ +

Set page offset to offset (or increment or decrement its current +value by offset). If invoked without an argument, the page offset +is restored to the value before the previous po request. +This request does not cause a break; the page offset in effect when an +output line is broken prevails (see Manipulating Filling and Adjustment). The initial value is 1i and the default scaling +unit is ‘m’. On terminal devices, the page offset is set to zero +by a driver-specific macro file, tty.tmac. The current page +offset can be found in the read-only register ‘.o’. + + +This request is incorrectly documented in the AT&T +troff manual as using a default scaling unit of ‘v’. +

+
+
.po 3i
+\n[.o]
+    ⇒ 720
+.po -1i
+\n[.o]
+    ⇒ 480
+.po
+\n[.o]
+    ⇒ 720
+
+
+ +
+
Request: .in [indent]
+
+
Request: .in +indent
+
Request: .in -indent
+
Register: \n[.i]
+
+

Set indentation to indent (or increment or decrement the current +value by indent). This request causes a break. Initially, there +is no indentation. +

+

If in is called without an argument, the indentation is reset to +the previous value before the last call to in. The default +scaling unit is ‘m’. +

+

If a negative indentation value is specified (which is not allowed), +gtroff emits a warning in category ‘range’ and sets the +indentation to zero. +

+

The effect of in is delayed until a partially collected line (if +it exists) is output. A temporary indentation value is reset to zero +also. +

+

The current indentation (as set by in) can be found in the +read-only register ‘.i’. The indentation is associated with the +environment (see Environments). +

+ +
+
Request: .ti offset
+
+
Request: .ti +offset
+
Request: .ti -offset
+
Register: \n[.in]
+
+

Temporarily indent the next output line by offset. If an +increment or decrement value is specified, adjust the temporary +indentation relative to the value set by the in request. +

+

This request causes a break; its value is associated with the +environment (see Environments). The default scaling unit is +‘m’. A call of ti without an argument is ignored. +

+

If the total indentation value is negative (which is not allowed), +gtroff emits a warning in category ‘range’ and sets the +temporary indentation to zero. ‘Total indentation’ is either +offset if specified as an absolute value, or the temporary plus +normal indentation, if offset is given as a relative value. +

+

The effect of ti is delayed until a partially collected line (if +it exists) is output. +

+

The read-only register .in is the indentation that applies to the +current output line. +

+

The difference between .i and .in is that the latter takes +into account whether a partially collected line still uses the old +indentation value or a temporary indentation value is active. +

+ +
+
Request: .ll [length]
+
+
Request: .ll +length
+
Request: .ll -length
+
Register: \n[.l]
+
+
Register: \n[.ll]
+
+

Set the line length to length (or increment or decrement the +current value by length). Initially, the line length is set to +6.5i. The effect of ll is delayed until a partially +collected line (if it exists) is output. The default scaling unit is +‘m’. +

+

If ll is called without an argument, the line length is reset to +the previous value before the last call to ll. If a negative +line length is specified (which is not allowed), gtroff emits a +warning in category ‘range’ and sets the line length to zero. The +line length is associated with the environment (see Environments). +

+ +

The current line length (as set by ll) can be found in the +read-only register ‘.l’. The read-only register .ll is the +line length that applies to the current output line. +

+

Similar to .i and .in, the difference between .l +and .ll is that the latter takes into account whether a partially +collected line still uses the old line length value. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.16 Line Continuation

+ + + +

When filling is enabled, input and output line breaks generally do not +correspond. The roff language therefore distinguishes input and +output line continuation. +

+
+
Escape sequence: \RET
+
+ + + + +

\RET (a backslash immediately followed by a newline) +suppresses the effects of that newline in the input. The next input +line thus retains the classification of its predecessor as a control or +text line. \RET is useful for managing line lengths in the +input during document maintenance; you can break an input line in the +middle of a request invocation, macro call, or escape sequence. Input +line continuation is invisible to the formatter, with two exceptions: +the | operator recognizes the new input line +(see Numeric Expressions), and the input line counter register +.c is incremented. +

+
+
.ll 50n
+.de I
+.  ft I
+.  nop \\$*
+.  ft
+..
+Our film class watched
+.I The Effect of Gamma Rays on Man-in-the-Moon
+Marigolds. \" whoops, the input line wrapped
+.br
+.I My own opus begins on line \n[.c] \
+and ends on line \n[.c].
+
+
+
    ⇒ Our film class watched The Effect of Gamma Rays on
+    ⇒ Man-in-the-Moon Marigolds.
+    ⇒ My own opus begins on line 11 and ends on line 12.
+
+
+ +
+
Escape sequence: \c
+
+
Register: \n[.int]
+
+ + + + + + +

\c continues an output line. Nothing after it on the input line +is formatted. In contrast to \RET, a line after \c +remains a new input line, so a control character is recognized at its +beginning. The visual results depend on whether filling is enabled; see +Manipulating Filling and Adjustment. +

+
    +
  • + + +If filling is enabled, a word interrupted with \c is continued +with the text on the next input text line, without an intervening space. + +
    +
    This is a te\c
+st.
+    ⇒ This is a test.
+
    + +
  • + + +If filling is disabled, the next input text line after \c is +handled as a continuation of the same input text line. + +
    +
    .nf
+This is a \c
+test.
+    ⇒ This is a test.
+
    +
+ +

An intervening control line that causes a break overrides \c, +flushing out the pending output line in the usual way. +

+ + +

The .int register contains a positive value if the last output +line was continued with \c; this datum is associated with the +environment (see Environments).69 +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.17 Page Layout

+ + + +

The formatter permits configuration of the page length and page number. +

+
+
Request: .pl [length]
+
+
Request: .pl +length
+
Request: .pl -length
+
Register: \n[.p]
+
+ + + + +

Change (increase or decrease) the page length per the numeric expression +length. The default scaling unit is ‘v’. A negative +length is valid, but an uncommon application: it prevents page +location traps from being sprung,70 and each +output line is placed on a new page. If length is invalid, GNU +troff emits a warning in category ‘number’. If length +is absent or invalid, ‘11i’ is assumed. +

+ +

The read-only register ‘.p’ interpolates the current page length. +

+ +
+
Request: .pn num
+
+
Request: .pn +num
+
Request: .pn -num
+
Register: \n[.pn]
+
+ + + +

Change (increase or decrease) the page number of the next page +per the numeric expression num. If num is invalid, GNU +troff emits a warning in category ‘number’ and ignores the +request. Without an argument, pn is ignored. +

+ + +

The read-only register .pn interpolates num if set by +pn on the current page, or the current page number plus 1. +

+ + + + +

The formatter offers special support for typesetting headers and +footers, collectively termed titles. Titles have an independent +line length, and their placement on the page is not restricted. +

+
+
Request: .tl 'left'center'right'
+
+ + + + +

Format an output line as a title consisting of left, center, +and right, each aligned accordingly. The delimiter need not be a +neutral apostrophe: tl accepts the same delimiters as most escape +sequences; see Delimiters. If not used as the delimiter, any +page number character character is replaced with the current page +number; the default is ‘%’; see the the pc request below. +Without an argument, tl is ignored. tl writes the title +line immediately, ignoring any partially collected line. +

+

It is not an error to omit delimiters after the first. For example, +‘.tl /Thesis’ is interpreted as ‘.tl /Thesis///’: it +sets a title line comprising only the left-aligned word ‘Thesis’. +

+ +
+
Request: .lt [length]
+
+
Request: .lt +length
+
Request: .lt -length
+
Register: \n[.lt]
+
+ + +

Change (increase or decrease) the line length used by titles per the +numeric expression length. The default scaling unit is ‘m’. +If length is negative, GNU emits a warning in category +‘range’ and treats length as ‘0’. If length is +invalid, GNU troff emits a warning in category ‘number’ and +ignores the request. The formatter’s default title length is +‘6.5i’. With no argument, the title length is restored to the +previous value. The title length is is associated with the environment +(see Environments). +

+ +

The read-only register ‘.lt’ interpolates the title line length. +

+ +
+
Request: .pc [char]
+
+ + + +

Set the page number character to char. With no argument, the page +number character is disabled. pc does not affect the +register %. +

+ +

The following example exercises title features. +

+
+
.lt 50n
+This is my partially collected
+.tl 'Isomers 2023'%'Dextrose Edition'
+line.
+    ⇒ Isomers 2023             1        Dextrose Edition
+    ⇒ This is my partially collected line.
+
+ +

We most often see titles used in page header and footer traps. +See Traps. +

+ +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.18 Page Control

+ + + + + + + +

Discretionary page breaks can prevent the unwanted separation of +content. A new page number takes effect during page ejection; see +The Implicit Page Trap. +

+
+
Request: .bp [page-number]
+
+
Request: .bp +page-number
+
Request: .bp -page-number
+
Register: \n[%]
+
+ + +

Break the page and change (increase or decrease) the next page number +per the numeric expression page-number. If page-number is +invalid, GNU troff emits a warning in category ‘number’ and +ignores the argument. This request causes a break. A page break +advances the vertical drawing position to the bottom of the page, +springing traps. See Page Location Traps. + + + +bp has effect only if invoked within the top-level +diversion.71 + + +This request is incorrectly documented in the AT&T +troff manual as having a default scaling unit of ‘v’. +

+ + +

The register % interpolates the current page number. +

+
+
.de BP
+'  bp \" schedule page break once current line is output
+..
+
+
+ +
+
Request: .ne [space]
+
+ + + +

Force a page break if insufficient vertical space is available (assert +“needed” space). ne tests the distance to the next page +location trap; see Page Location Traps, and breaks the page if +that amount is less than space. The default scaling unit is +‘v’. If space is invalid, GNU troff emits a warning +in category ‘number’ and ignores the argument. If space is +not specified, ‘1v’ is assumed. +

+ +

We can require space for at least the first two output lines of a +paragraph, preventing its first line from being widowed at the +page bottom. +

+
+
.ne 2v
+Considering how common illness is,
+how tremendous the spiritual change that it brings,
+how astonishing,
+when the lights of health go down,
+the undiscovered countries that are then disclosed,
+what wastes and deserts of the soul a slight attack
+of influenza brings to view,
+
+ +

This method is reliable only if no output line is pending when ne +is invoked. When macro packages are used, this is often not the case: +their paragraphing macros perform the break. You may need to experiment +with placing the ne after the paragraphing macro, or br +and ne before it. +

+ + +

ne is also useful to force grouping of section headings with +their subsequent paragraphs, or tables with their captions and/or +explanations. Macro packages often use ne with diversions to +implement keeps and displays; see Diversions. They may also offer +parameters for widow and orphan management. +

+ +
+
Request: .sv [space]
+
+
Request: .os
+
+ +

Require vertical space as ne does, but also save it for +later output by the os request. If space is available +before the next page location trap, it is output immediately. Both +requests ignore a partially collected line, taking effect at the next +break. + + +sv and os ignore no-space mode (recall Manipulating Spacing). While the sv request allows negative values for +space, os ignores them. The default scaling unit is +‘v’. If space is not specified, ‘1v’ is assumed. +

+ +
+
Register: \n[nl]
+
+ + + +

nl interpolates or sets the vertical drawing position. When the +formatter starts, the first page transition hasn’t happened yet, and +nl is negative. If a header trap has been planted on the page +(typically at vertical position 0), you can assign a negative +value to nl to spring it if that page has already started +(see Page Location Traps). +

+
+
.de HD
+.  sp
+.  tl ''Goldbach Solution''
+.  sp
+..
+.
+First page.
+.bp
+.wh 0 HD \" plant header trap at top of page
+.nr nl (-1)
+Second page.
+    ⇒ First page.
+    ⇒
+    ⇒ (blank lines elided)
+    ⇒
+    ⇒                         Goldbach Solution
+    ⇒
+    ⇒ (blank lines elided)
+    ⇒
+    ⇒ Second page.
+
+ +

Without resetting nl to a negative value, the trap just planted +would be active beginning with the next page, not the current +one. +

+

See Diversions, for a comparison of nl with the .h and +.d registers. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.19 Using Fonts

+ + + + + + + + + + + + + +

In digital typography, a font is a collection of characters in a +specific typeface that a device can render as glyphs at a desired +size.72 A roff formatter can change typefaces at any +point in the text. The basic faces are a set of styles combining +upright and slanted shapes with normal and heavy stroke weights: +‘R’, ‘I’, ‘B’, and ‘BI’—these stand for +roman, italic, bold, and +bold-italic. For linguistic text, GNU troff groups +typefaces into families containing each of these +styles.73 A text font is thus often a family +combined with a style, but it need not be: consider the ps and +pdf devices’ ZCMI (Zapf Chancery Medium italic)—often, +no other style of Zapf Chancery Medium is provided. On typesetting +devices, at least one special font is available, comprising +unstyled glyphs for mathematical operators and other purposes. +

+ + + + + + + + +

Like AT&T troff, GNU troff does not itself load +or manipulate a digital font file;74 instead it +works with a font description file that characterizes it, +including its glyph repertoire and the metrics (dimensions) of +each glyph.75 This +information permits the formatter to accurately place glyphs with +respect to each other. Before using a font description, the formatter +associates it with a mounting position, a place in an ordered list +of available typefaces. + + + +So that a document need not be strongly coupled to a specific font +family, in GNU troff an output device can associate a style in +the abstract sense with a mounting position. Thus the default family +can be combined with a style dynamically, producing a resolved font +name. +

+

Fonts often have trademarked names, and even Free Software fonts can +require renaming upon modification. groff maintains a +convention that a device’s serif font family is given the name ‘T’ +(“Times”), its sans-serif family ‘H’ (“Helvetica”), and its +monospaced family ‘C’ (“Courier”). Historical inertia has driven +groff’s font identifiers to short uppercase abbreviations of font +names, as with ‘TR’, ‘TI’, ‘TB’, ‘TBI’, and a +special font ‘S’. +

+

The default family used with abstract styles can be changed at any time; +initially, it is ‘T’. Typically, abstract styles are arranged in +the first four mounting positions in the order shown above. The default +mounting position, and therefore style, is always ‘1’ (‘R’). +By issuing appropriate formatter instructions, you can override these +defaults before your document writes its first glyph. +

+ + + + + +

Terminal output devices cannot change font families and lack special +fonts. They support style changes by overstriking, or by altering +ISO 6429/ECMA-48 graphic renditions (character cell +attributes). +

+ + + +
+
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+

5.19.1 Selecting Fonts

+ + +

We use font to refer to any of several means of identifying a +font: by mounting position (‘3’), by abstract style (‘B’), or +by its identifier (‘TB’). +

+
+
Request: .ft [font]
+
+
Escape sequence: \ff
+
+
Escape sequence: \f(fn
+
Escape sequence: \f[font]
+
Register: \n[.fn]
+
+ + + + + + + + + + + +

The ft request selects the typeface font. If the argument +is absent or ‘P’, it selects the previously chosen font. If +font is a non-negative integer, it is interpreted as mounting +position; the font mounted there is selected. If that position refers +to an abstract style, it is combined with the default family (see +fam and \F below) to make a resolved font name. If the +mounting position is not a style and no font is mounted there, GNU +troff emits a warning in category ‘font’ and ignores the +request. +

+

If font matches a style name, it is combined with the current +family to make a resolved font name. Otherwise, font is assumed +to already be a resolved font name. +

+ + + +

The resolved font name is subject to translation (see request ftr +below). Next, the (possibly translated) font name’s mounting position +is looked up; if not mounted, font is sought on the file system as +a font description file and, if located, automatically mounted at the +next available position (see register .fp below). If the font +was mounted using an identifier different from its font description file +name (see request fp below), that file name is then looked up. +If a font description file for the resolved font name is not found, GNU +troff emits a warning in category ‘font’ and ignores the +request. +

+

The \f escape sequence is similar, using one-character name (or +mounting position) f, two-character name fn, or a name +font of arbitrary length. + + +‘\f[]’ selects the previous font. The syntax form ‘\fP’ is +supported for backward compatibility, and ‘\f[P]’ for consistency. +

+
+
eggs, bacon,
+.ft I
+spam,
+.ft
+and sausage.
+.br
+eggs, bacon, \fIspam,\fP and sausage.
+    ⇒ eggs, bacon, spam, and sausage
+    ⇒ eggs, bacon, spam, and sausage
+
+ +

The current and previously selected fonts are properties of the +environment (see Environments). +

+

The read-only string-valued register .fn contains the resolved +font name of the selected font. +

+

\f doesn’t produce an input token in GNU troff; it thus +can be used in requests that expect a single-character argument. We can +assign a font to a margin character as follows (see Miscellaneous). +

+
+
.mc \f[I]x\f[]
+
+
+ +
+
Request: .ftr f [g]
+
+ + + + + + + + + + + + + + +

Translate font f to font g. Whenever a font +named f is referred to in a \f escape sequence, in the +F and S conditional operators, or in the ft, +ul, bd, cs, tkf, special, +fspecial, fp, or sty requests, font g is +used. If g is missing or equal to f the translation is +undone. +

+

Font translations cannot be chained. +

+
+
.ftr XXX TR
+.ftr XXX YYY
+.ft XXX
+    error→ warning: can't find font 'XXX'
+
+
+ +
+
Request: .fzoom f [zoom]
+
+
Register: \n[.zoom]
+
+ + + + + + + + +

Set magnification of font f to factor zoom, which must +be a non-negative integer multiple of 1/1000th. This request is useful +to adjust the optical size of a font in relation to the others. In the +example below, font CR is magnified by 10% (the zoom factor is +thus 1.1). +

+
+
.fam P
+.fzoom CR 1100
+.ps 12
+Palatino and \f[CR]Courier\f[]
+
+ +

A missing or zero value of zoom is the same as a value of 1000, +which means no magnification. f must be a resolved font +name, not an abstract style. +

+

The magnification of a font is completely transparent to GNU +troff; a change of the zoom factor doesn’t cause any effect +except that the dimensions of glyphs, (word) spaces, kerns, etc., of the +affected font are adjusted accordingly. +

+

The zoom factor of the current font is available in the read-only +register ‘.zoom’, in multiples of 1/1000th. It returns zero if +there is no magnification. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+

5.19.2 Font Families

+ + + + + +

To accommodate the wide variety of fonts available, GNU troff +distinguishes font families and font styles. A resolved +font name is the catenation of a font family and a style. Selecting an +abstract style causes GNU troff to combine it with the default +font family. +

+

You can thus compose a document using abstract styles exclusively for +its body or running text, selecting a specific family only for titles or +examples, for instance, and change the default family on the command +line (recall Options). +

+

Fonts for the devices ps, pdf, dvi, lj4, +lbp, and the X11 devices support this mechanism. By default, +GNU troff uses the Times family with the four styles ‘R’, +‘I’, ‘B’, and ‘BI’. +

+
+
Request: .fam [family]
+
+
Register: \n[.fam]
+
+
Escape sequence: \Ff
+
+
Escape sequence: \F(fm
+
Escape sequence: \F[family]
+
+ +

Set the default font family, used in combination with abstract styles to +construct a resolved font name, to family (one-character +name f, two-character name fm). If no argument is +given, GNU troff selects the previous font family; if there none, +is it falls back to the device’s default76 or its own (‘T’). +

+

The \F escape sequence works similarly. In disanalogy to +\f, ‘\FP’ makes ‘P’ the default family. Use +‘\F[]’ to select the previous default family. The default font +family is available in the read-only string-valued register .fam; +it is associated with the environment (see Environments). +

+
+
spam,     \" startup defaults are T (Times) R (roman)
+.fam H    \" make Helvetica the default family
+spam,     \" family H + style R = HR
+.ft B     \" family H + style B = HB
+spam,
+.ft CR    \" Courier roman (default family not changed)
+spam,
+.ft       \" back to Helvetica bold
+spam,
+.fam T    \" make Times the default family
+spam,     \" family T + style B = TB
+.ft AR    \" font AR (not a style)
+baked beans,
+.ft R     \" family T + style R = TR
+and spam.
+
+ +

\F doesn’t produce an input token in GNU troff. As a +consequence, it can be used in requests like mc (which expects +a single character as an argument) to change the font family on the fly. +

+
+
.mc \F[P]x\F[]
+
+
+ +
+
Request: .sty n style
+
+
Register: \n[.sty]
+
+ + + + + + + + + +

Associate an abstract style style with mounting +position n, which must be a non-negative integer. If the +requests cs, bd, tkf, uf, or fspecial +are applied to an abstract style, they are instead applied to the member +of the current family corresponding to that style. +

+ + +

The default family can be set with the -f option (see Options). The styles command in the DESC file controls +which font positions (if any) are initially associated with abstract +styles rather than fonts. +

+

Caution: The style argument is not validated. +Errors may occur later, when the formatter attempts to construct a +resolved font name, or format a character for output. +

+
+
.nr BarPos \n[.fp]
+.sty \n[.fp] Bar
+.fam Foo
+.ft \n[BarPos]
+.tm .f=\n[.f]
+A
+    error→ error: no font family named 'Foo' exists
+    error→ .f=41
+    error→ error: cannot format glyph: no current font
+
+ +

When an abstract style has been selected, the read-only string-valued +register ‘.sty’ interpolates its name; this datum is associated +with the environment (see Environments). Otherwise, ‘.sty’ +interpolates nothing. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+

5.19.3 Font Positions

+ + + +

To support typeface indirection through abstract styles, and for +compatibility with AT&T troff, the formatter maintains +a list of font positions at which fonts required by a document are +mounted. An output device’s description file DESC +typically configures a set of pre-mounted fonts; see Device and Font Description Files. A font need not be explicitly mounted before +it is selected; GNU troff will search GROFF_FONT_PATH for +it by name and mount it at the first free mounting position on demand. +

+
+
Request: .fp pos id [font-description-file-name]
+
+
Register: \n[.f]
+
+
Register: \n[.fp]
+
+ + +

Mount a font under the name id at mounting position pos, a +non-negative integer. When the formatter starts up, it reads the output +device’s description to mount an initial set of faces, and selects font +position 1. Position 0 is unused by default. Unless the +font-description-file-name argument is given, id should be +the name of a font description file stored in a directory corresponding +to the selected output device. GNU troff does not traverse +directories to locate the font description file. +

+ + +

The optional third argument enables font names to be aliased, which can +be necessary in compatibility mode since AT&T troff syntax +affords no means of identifying fonts with names longer than two +characters, like ‘TBI’ or ‘ZCMI’, in a font selection escape +sequence. See Compatibility Mode. You can also alias fonts on +mounting for convenience or abstraction. (See below regarding the +.fp register.) +

+
+
.fp \n[.fp] SC ZCMI
+Send a \f(SChand-written\fP thank-you note.
+.fp \n[.fp] Emph TI
+.fp \n[.fp] Strong TB
+Are \f[Emph]these names\f[] \f[Strong]comfortable\f[]?
+
+ +

‘DESC’, ‘P’, and non-negative integers are not usable as font +identifiers. +

+ +

The position of the currently selected font (or abstract style) is +available in the read-only register ‘.f’. It is associated with +the environment (see Environments). +

+

You can copy the value of .f to another register to save it for +later use. +

+
+
.nr saved-font \n[.f]
+… text involving many font changes …
+.ft \n[saved-font]
+
+ + +

The index of the next (non-zero) free font position is available in the +read-only register ‘.fp’. + +Fonts not listed in the DESC file are automatically mounted at +position ‘\n[.fp]’ when selected with the ft request or +\f escape sequence. When mounting a font at a position +explicitly with the fp request, this same practice should be +followed, although GNU troff does not enforce this strictly. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+

5.19.4 Using Symbols

+ + + + + + + + +

A glyph is a graphical representation of a character. While +a character is an abstraction of semantic information, a glyph is +something that can be seen on screen or paper. A character has many +possible representation forms (for example, the character ‘A’ can be +written in an upright or slanted typeface, producing distinct +glyphs). Sometimes, a sequence of characters map to a single glyph: +this is a ligature—the most common is ‘fi’. +

+

Space characters never become glyphs in GNU troff. If not +discarded (as when trailing on text lines), they are represented by +horizontal motions in the output. +

+ + + + + + +

A symbol is simply a named glyph. Within gtroff, all glyph +names of a particular font are defined in its font file. If the user +requests a glyph not available in this font, gtroff looks up an +ordered list of special fonts. By default, the PostScript output +device supports the two special fonts ‘SS’ (slanted symbols) and +‘S’ (symbols) (the former is looked up before the latter). Other +output devices use different names for special fonts. Fonts mounted +with the fonts keyword in the DESC file are globally +available. To install additional special fonts locally (i.e., for a +particular font), use the fspecial request. +

+

Here are the exact rules how gtroff searches a given symbol: +

+
    +
  • If the symbol has been defined with the char request, use it. +This hides a symbol with the same name in the current font. + +
  • Check the current font. + +
  • If the symbol has been defined with the fchar request, use it. + +
  • Check whether the current font has a font-specific list of special +fonts; test all fonts in the order of appearance in the last +fspecial call if appropriate. + +
  • If the symbol has been defined with the fschar request for the +current font, use it. + +
  • Check all fonts in the order of appearance in the last special +call. + +
  • If the symbol has been defined with the schar request, use it. + +
  • As a last resort, consult all fonts loaded up to now for special fonts +and check them, starting with the lowest font number. This can +sometimes lead to surprising results since the fonts line in +the DESC file often contains empty positions, which are filled +later on. For example, consider the following: + +
    +
    fonts 3 0 0 FOO
+
    + +

    This mounts font foo at font position 3. We assume that +FOO is a special font, containing glyph foo, and that no +font has been loaded yet. The line +

    +
    +
    .fspecial BAR BAZ
+
    + +

    makes font BAZ special only if font BAR is active. We +further assume that BAZ is really a special font, i.e., the font +description file contains the special keyword, and that it also +contains glyph foo with a special shape fitting to font +BAR. After executing fspecial, font BAR is loaded +at font position 1, and BAZ at position 2. +

    +

    We now switch to a new font XXX, trying to access glyph +foo that is assumed to be missing. There are neither +font-specific special fonts for XXX nor any other fonts made +special with the special request, so gtroff starts the +search for special fonts in the list of already mounted fonts, with +increasing font positions. Consequently, it finds BAZ before +FOO even for XXX, which is not the intended behaviour. +

+ +

See Device and Font Description Files, and Special Fonts, for +more details. +

+ + + + + +

The groff_char(7) man page houses a complete list of +predefined special character names, but the availability of any as a +glyph is device- and font-dependent. For example, say +

+
+
man -Tdvi groff_char > groff_char.dvi
+
+ +

to obtain those available with the DVI device and default font +configuration.77 If you want to use an additional macro package to change +the fonts used, groff (or gtroff) must be run directly. +

+
+
groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
+
+ + + + + + +

Special character names not listed in groff_char(7) are +derived algorithmically, using a simplified version of the Adobe Glyph +List (AGL) algorithm, which is described in +https://github.com/adobe-type-tools/agl-aglfn. The (frozen) +set of names that can’t be derived algorithmically is called the +groff glyph list (GGL). +

+
    +
  • A glyph for Unicode character U+XXXX[X[X]], which is +not a composite character is named +uXXXX[X[X]]. X must be an +uppercase hexadecimal digit. Examples: u1234, u008E, +u12DB8. The largest Unicode value is 0x10FFFF. There must be at +least four X digits; if necessary, add leading zeroes (after the +‘u’). No zero padding is allowed for character codes greater than +0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF +represented with character codes from the surrogate area U+D800-U+DFFF) +are not allowed either. + +
  • A glyph representing more than a single input character is named + +
    +
    ‘u’ component1 ‘_’ component2 ‘_’ component3 …
+
    + +

    Example: u0045_0302_0301. +

    +

    For simplicity, all Unicode characters that are composites must be +maximally decomposed to NFD;78 for example, +u00CA_0301 is not a valid glyph name since U+00CA (LATIN +CAPITAL LETTER E WITH CIRCUMFLEX) can be further decomposed into U+0045 +(LATIN CAPITAL LETTER E) and U+0302 (COMBINING CIRCUMFLEX +ACCENT). u0045_0302_0301 is thus the glyph name for U+1EBE, +LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND ACUTE. +

    +
  • groff maintains a table to decompose all algorithmically derived glyph +names that are composites itself. For example, u0100 (LATIN +LETTER A WITH MACRON) is automatically decomposed into +u0041_0304. Additionally, a glyph name of the GGL is preferred +to an algorithmically derived glyph name; groff also +automatically does the mapping. Example: The glyph u0045_0302 is +mapped to ^E. + +
  • glyph names of the GGL can’t be used in composite glyph names; for +example, ^E_u0301 is invalid. +
+ +
+
Escape sequence: \(nm
+
+
Escape sequence: \[name]
+
Escape sequence: \[base-glyph combining-component …]
+
+ +

Typeset a special character name (two-character name nm) or +a composite glyph consisting of base-glyph overlaid with one or +more combining-components. For example, ‘\[A ho]’ is a +capital letter “A” with a “hook accent” (ogonek). +

+

There is no special syntax for one-character names—the analogous form +‘\n’ would collide with other escape sequences. However, the +four escape sequences \', \-, \_, and \`, +are translated on input to the special character escape sequences +\[aa], \[-], \[ul], and \[ga], respectively. +

+

A special character name of length one is not the same thing as an +ordinary character: that is, the character a is not the same as +\[a]. +

+

If name is undefined, a warning in category ‘char’ is +produced and the escape is ignored. See Warnings, for information +about the enablement and suppression of warnings. +

+

GNU troff resolves \[…] with more than a single +component as follows: +

+
    +
  • Any component that is found in the GGL is converted to the +uXXXX form. + +
  • Any component uXXXX that is found in the list of +decomposable glyphs is decomposed. + +
  • The resulting elements are then concatenated with ‘_’ in between, +dropping the leading ‘u’ in all elements but the first. +
+ +

No check for the existence of any component (similar to tr +request) is done. +

+

Examples: +

+
+
\[A ho]
+

‘A’ maps to u0041, ‘ho’ maps to u02DB, thus the +final glyph name would be u0041_02DB. This is not the expected +result: the ogonek glyph ‘ho’ is a spacing ogonek, but for a +proper composite a non-spacing ogonek (U+0328) is necessary. Looking +into the file composite.tmac, one can find ‘.composite ho u0328’, which changes the mapping of ‘ho’ while a composite glyph +name is constructed, causing the final glyph name to be +u0041_0328. +

+
+
\[^E u0301]
+
\[^E aa]
+
\[E a^ aa]
+
\[E ^ ']
+

‘^E’ maps to u0045_0302, thus the final glyph name is +u0045_0302_0301 in all forms (assuming proper calls of the +composite request). +

+
+ +

It is not possible to define glyphs with names like ‘A ho’ +within a groff font file. This is not really a limitation; +instead, you have to define u0041_0328. +

+ +
+
Escape sequence: \C'xxx'
+
+ + +

Typeset the glyph of the special character xxx. Normally, it is +more convenient to use \[xxx], but \C has some +advantages: it is compatible with AT&T device-independent +troff (and therefore available in compatibility +mode79) and can interpolate special +characters with ‘]’ in their names. The delimiter need not be +a neutral apostrophe; see Delimiters. +

+ +
+
Request: .composite id1 id2
+
+ +

Map special character name id1 to id2 if id1 is used +in \[...] with more than one component. See above for examples. +This is a strict rewriting of the special character name; no check is +performed for the existence of a glyph for either. A set of default +mappings for many accents can be found in the file +composite.tmac, loaded by the default troffrc at startup. +

+ +
+
Escape sequence: \N'n'
+
+ + + + +

Typeset the glyph with code n in the current font +(n is not the input character code). The number +n can be any non-negative decimal integer. Most devices only +have glyphs with codes between 0 and 255; the Unicode output device +uses codes in the range 0–65535. If the current font does not contain +a glyph with that code, special fonts are not searched. The +\N escape sequence can be conveniently used in conjunction with +the char request: +

+
+
.char \[phone] \f[ZD]\N'37'
+
+ + + + +

The code of each glyph is given in the fourth column in the font +description file after the charset command. It is possible to +include unnamed glyphs in the font description file by using a name of +‘---’; the \N escape sequence is the only way to use these. +

+

No kerning is applied to glyphs accessed with \N. The delimiter +need not be a neutral apostrophe; see Delimiters. +

+ +

A few escape sequences are also special characters. +

+
+
Escape sequence: \'
+
+

An escaped neutral apostrophe is a synonym for \[aa] (acute +accent). +

+ +
+
Escape sequence: \`
+
+

An escaped grave accent is a synonym for \[ga] (grave accent). +

+ +
+
Escape sequence: \-
+
+

An escaped hyphen-minus is a synonym for \[-] (minus sign). +

+ +
+
Escape sequence: \_
+
+

An escaped underscore (“low line”) is a synonym for \[ul] +(underrule). On typesetting devices, the underrule is font-invariant +and drawn lower than the underscore ‘_’. +

+ +
+
Request: .cflags n c1 c2 …
+
+ + + + +

Assign properties encoded by the number n to characters c1, +c2, and so on. +

+

Input characters, including special characters introduced by an escape, +have certain properties associated with them.80 +These properties can be modified with this request. The first argument +is the sum of the desired flags and the remaining arguments are the +characters to be assigned those properties. Spaces between the cn +arguments are optional. Any argument cn can be a character class +defined with the class request rather than an individual +character. See Character Classes. +

+

The non-negative integer n is the sum of any of the following. +Some combinations are nonsensical, such as ‘33’ (1 + 32). +

+
+
1
+
+

Recognize the character as ending a sentence if followed by a newline +or two spaces. Initially, characters ‘.?!’ have this property. +

+
+
2
+
+

Enable breaks before the character. A line is not broken at a character +with this property unless the characters on each side both have non-zero +hyphenation codes. This exception can be overridden by adding 64. +Initially, no characters have this property. +

+
+
4
+
+ +

Enable breaks after the character. A line is not broken at a character +with this property unless the characters on each side both have non-zero +hyphenation codes. This exception can be overridden by adding 64. +Initially, characters ‘\-\[hy]\[em]’ have this property. +

+
+
8
+
+ + + + + +

Mark the glyph associated with this character as overlapping other +instances of itself horizontally. Initially, characters +‘\[ul]\[rn]\[ru]\[radicalex]\[sqrtex]’ have this property. +

+
+
16
+

Mark the glyph associated with this character as overlapping other +instances of itself vertically. Initially, the character ‘\[br]’ +has this property. +

+
+
32
+
+ + + + + + + + + +

Mark the character as transparent for the purpose of end-of-sentence +recognition. In other words, an end-of-sentence character followed by +any number of characters with this property is treated as the end of a +sentence if followed by a newline or two spaces. This is the same as +having a zero space factor in TeX. Initially, characters +‘"')]*\[dg]\[dd]\[rq]\[cq]’ have this property. +

+
+
64
+

Ignore hyphenation codes of the surrounding characters. Use this in +combination with values 2 and 4 (initially, no characters have this +property). +

+

For example, if you need an automatic break point after the en-dash in +numeric ranges like “3000–5000”, insert +

+
+
.cflags 68 \[en]
+
+ +

into your document. However, this practice can lead to bad layout if +done thoughtlessly; in most situations, a better solution instead of +changing the cflags value is to insert \: right after the +hyphen at the places that really need a break point. +

+
+ +

The remaining values were implemented for East Asian language support; +those who use alphabetic scripts exclusively can disregard them. +

+
+
128
+

Prohibit a line break before the character, but allow a line break after +the character. This works only in combination with flags 256 and 512 +and has no effect otherwise. Initially, no characters have this +property. +

+
+
256
+

Prohibit a line break after the character, but allow a line break before +the character. This works only in combination with flags 128 and 512 +and has no effect otherwise. Initially, no characters have this +property. +

+
+
512
+

Allow line break before or after the character. This works only in +combination with flags 128 and 256 and has no effect otherwise. +Initially, no characters have this property. +

+
+ +

In contrast to values 2 and 4, the values 128, 256, and 512 work +pairwise. If, for example, the left character has value 512, and the +right character 128, no break will be automatically inserted between +them. If we use value 6 instead for the left character, a break +after the character can’t be suppressed since the neighboring character +on the right doesn’t get examined. +

+ +
+
Request: .char c [contents]
+
+
Request: .fchar c [contents]
+
+
Request: .fschar f c [contents]
+
+
Request: .schar c [contents]
+
+ + + + + + + + + + + + + + + + + + + + + +

Define a new character or glyph c to be contents, which +can be empty. More precisely, char defines a groff object +(or redefines an existing one) that is accessed with the +name c on input, and produces contents on output. +Every time glyph c needs to be printed, contents is +processed in a temporary environment and the result is wrapped up into a +single object. Compatibility mode is turned off and the escape +character is set to \ while contents is processed. +Any emboldening, constant spacing, or track kerning is applied to this +object rather than to individual glyphs in contents. +

+

An object defined by these requests can be used just like a normal glyph +provided by the output device. In particular, other characters can be +translated to it with the tr or trin requests; it can be +made the leader character with the lc request; repeated patterns +can be drawn with it using the \l and \L escape sequences; +and words containing c can be hyphenated correctly if the +hcode request is used to give the object a hyphenation code. +

+

There is a special anti-recursion feature: use of the object within its +own definition is handled like a normal character (not +defined with char). +

+

The tr and trin requests take precedence if char +accesses the same symbol. +

+
+
.tr XY
+X
+    ⇒ Y
+.char X Z
+X
+    ⇒ Y
+.tr XX
+X
+    ⇒ Z
+
+ +

The fchar request defines a fallback glyph: gtroff only +checks for glyphs defined with fchar if it cannot find the glyph +in the current font. gtroff carries out this test before +checking special fonts. +

+

fschar defines a fallback glyph for font f: +gtroff checks for glyphs defined with fschar after the +list of fonts declared as font-specific special fonts with the +fspecial request, but before the list of fonts declared as global +special fonts with the special request. +

+

Finally, the schar request defines a global fallback glyph: +gtroff checks for glyphs defined with schar after the list +of fonts declared as global special fonts with the special +request, but before the already mounted special fonts. +

+

See Character Classes. +

+ +
+
Request: .rchar c …
+
+
Request: .rfschar f c …
+
+ + + +

Remove definition of each ordinary or special character c, +undoing the effect of a char, fchar, or schar +request. Those supplied by font description files cannot be removed. +Spaces and tabs may separate c arguments. +

+

The request rfschar removes glyph definitions defined with +fschar for font f. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+

5.19.5 Character Classes

+ + + +

Classes are particularly useful for East Asian languages such as +Chinese, Japanese, and Korean, where the number of needed characters is +much larger than in European languages, and where large sets of +characters share the same properties. +

+
+
Request: .class name c1 c2 …
+
+ + + +

Define a character class (or simply “class”) name comprising +the characters c1, c2, and so on. +

+

A class thus defined can then be referred to in lieu of listing all the +characters within it. Currently, only the cflags request can +handle references to character classes. +

+

In the request’s simplest form, each cn is a character (or special +character). +

+
+
.class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq]
+
+ +

Since class and glyph names share the same name space, it is recommended +to start and end the class name with [ and ], +respectively, to avoid collisions with existing character names defined +by GNU troff or the user (with char and related requests). +This practice applies the presence of ] in the class name to +prevent the use of the special character escape form +\[…], thus you must use the \C escape to access +a class with such a name. +

+ + +

You can also use a character range notation consisting of a +start character followed by ‘-’ and then an end character. +Internally, GNU troff converts these two symbol names to +Unicode code points (according to the groff glyph list [GGL]), +which then give the start and end value of the range. If that fails, +the class definition is skipped. +

+

Furthermore, classes can be nested. +

+
+
.class [prepunct] , : ; > }
+.class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
+
+ +

The class ‘[prepunctx]’ thus contains the contents of the class +[prepunct] as defined above (the set ‘, : ; > }’), and +characters in the range between U+2013 and U+2016. +

+

If you want to include ‘-’ in a class, it must be the first +character value in the argument list, otherwise it gets misinterpreted +as part of the range syntax. +

+

It is not possible to use class names as end points of range +definitions. +

+

A typical use of the class request is to control line-breaking +and hyphenation rules as defined by the cflags request. For +example, to inhibit line breaks before the characters belonging to the +prepunctx class defined in the previous example, you can write +the following. +

+
+
.cflags 2 \C'[prepunctx]'
+
+ +

See the cflags request in Using Symbols, for more details. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+

5.19.6 Special Fonts

+ + + +

Special fonts are those that gtroff searches when it cannot find +the requested glyph in the current font. The Symbol font is usually a +special font. +

+

gtroff provides the following two requests to add more special +fonts. See Using Symbols, for a detailed description of the glyph +searching mechanism in gtroff. +

+

Usually, only non-TTY devices have special fonts. +

+
+
Request: .special [s1 s2 …]
+
+
Request: .fspecial f [s1 s2 …]
+
+ + +

Use the special request to define special fonts. Initially, this +list is empty. +

+

Use the fspecial request to designate special fonts only when +font f is active. Initially, this list is empty. +

+

Previous calls to special or fspecial are overwritten; +without arguments, the particular list of special fonts is set to empty. +Special fonts are searched in the order they appear as arguments. +

+

All fonts that appear in a call to special or fspecial +are loaded. +

+

See Using Symbols, for the exact search order of glyphs. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+

5.19.7 Artificial Fonts

+ + + +

There are a number of requests and escape sequences for artificially +creating fonts. These are largely vestiges of the days when output +devices did not have a wide variety of fonts, and when nroff and +troff were separate programs. Most of them are no longer +necessary in GNU troff. Nevertheless, they are supported. +

+
+
Escape sequence: \H'height'
+
+
Escape sequence: \H'+height'
+
Escape sequence: \H'-height'
+
Register: \n[.height]
+
+ + + +

Change (increment, decrement) the height of the current font, but not +the width. If height is zero, restore the original height. +Default scaling unit is ‘z’. +

+

The read-only register .height contains the font height as set by +\H. +

+

Currently, only the -Tps and -Tpdf devices support +this feature. +

+

\H doesn’t produce an input token in GNU troff. As a +consequence, it can be used in requests like mc (which expects +a single character as an argument) to change the font on the fly: +

+
+
.mc \H'+5z'x\H'0'
+
+ +

In compatibility mode, gtroff behaves differently: If an +increment or decrement is used, it is always taken relative to the +current type size and not relative to the previously selected font +height. Thus, +

+
+
.cp 1
+\H'+5'test \H'+5'test
+
+ +

prints the word ‘test’ twice with the same font height (five points +larger than the current font size). +

+ +
+
Escape sequence: \S'slant'
+
+
Register: \n[.slant]
+
+ + + +

Slant the current font by slant degrees. Positive values slant to +the right. Only integer values are possible. +

+

The read-only register .slant contains the font slant as set by +\S. +

+

Currently, only the -Tps and -Tpdf devices support +this feature. +

+

\S doesn’t produce an input token in GNU troff. As a +consequence, it can be used in requests like mc (which expects +a single character as an argument) to change the font on the fly: +

+
+
.mc \S'20'x\S'0'
+
+ + + +

This escape is incorrectly documented in the AT&T +troff manual; the slant is always set to an absolute value. +

+ +
+
Request: .ul [lines]
+
+ +

The ul request normally underlines subsequent lines if a TTY +output device is used. Otherwise, the lines are printed in italics +(only the term ‘underlined’ is used in the following). The single +argument is the quantity of input lines to be underlined; with no +argument, the next line is underlined. If lines is zero or +negative, stop the effects of ul (if it was active). Requests +and empty lines do not count for computing the number of underlined +input lines, even if they produce some output like tl. Lines +inserted by macros (e.g., invoked by a trap) do count. +

+

At the beginning of ul, the current font is stored and the +underline font is activated. Within the span of a ul request, it +is possible to change fonts, but after the last line affected by +ul the saved font is restored. +

+

This number of lines still to be underlined is associated with the +environment (see Environments). The underline font can be changed +with the uf request. +

+ + +

The ul request does not underline spaces. +

+ +
+
Request: .cu [lines]
+
+ + +

The cu request is similar to ul but underlines spaces as +well (if a TTY output device is used). +

+ +
+
Request: .uf font
+
+ + +

Set the underline font (globally) used by ul and cu. By +default, this is the font at position 2. font can be either +a non-negative font position or the name of a font. +

+ +
+
Request: .bd font [offset]
+
+
Request: .bd font1 font2 [offset]
+
Register: \n[.b]
+
+ + +

Embolden font by overstriking its glyphs offset by offset +units minus one. +

+

Two syntax forms are available. +

+
    +
  • Imitate a bold font unconditionally. The first argument specifies the +font to embolden, and the second is the number of basic units, minus +one, by which the two glyphs are offset. If the second argument is +missing, emboldening is turned off. + +

    font can be either a non-negative font position or the name of a +font. +

    +

    offset is available in the .b read-only register if a +special font is active; in the bd request, its default unit is +‘u’. +

    +
  • + + + +Imitate a bold form conditionally. Embolden font1 by offset +only if font font2 is the current font. This request can be +issued repeatedly to set up different emboldening values for different +current fonts. If the second argument is missing, emboldening is turned +off for this particular current font. + +

    This affects special fonts only (either set up with the special +command in font files or with the fspecial request). +

+
+ +
+
Request: .cs font [width [em-size]]
+
+ + + + +

Switch to and from constant glyph space mode. If activated, the +width of every glyph is width/36 ems. The em size is given +absolutely by em-size; if this argument is missing, the em value +is taken from the current font size (as set with the ps request) +when the font is effectively in use. Without second and third argument, +constant glyph space mode is deactivated. +

+

Default scaling unit for em-size is ‘z’; width is an +integer. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+

5.19.8 Ligatures and Kerning

+ + + +

Ligatures are groups of characters that are run together, i.e, producing +a single glyph. For example, the letters ‘f’ and ‘i’ can form a +ligature ‘fi’ as in the word ‘file’. This produces a cleaner look +(albeit subtle) to the printed output. Usually, ligatures are not +available in fonts for TTY output devices. +

+

Most PostScript fonts support the fi and fl ligatures. The C/A/T +typesetter that was the target of AT&T troff also +supported ‘ff’, ‘ffi’, and ‘ffl’ ligatures. Advanced typesetters or +‘expert’ fonts may include ligatures for ‘ft’ and ‘ct’, although GNU +troff does not support these (yet). +

+

Only the current font is checked for ligatures and kerns; neither +special fonts nor special charcters defined with the char request +(and its siblings) are taken into account. +

+
+
Request: .lg [flag]
+
+
Register: \n[.lg]
+
+ + + +

Switch the ligature mechanism on or off; if the parameter is non-zero or +missing, ligatures are enabled, otherwise disabled. Default is on. The +current ligature mode can be found in the read-only register .lg +(set to 1 or 2 if ligatures are enabled, 0 otherwise). +

+

Setting the ligature mode to 2 enables the two-character ligatures +(fi, fl, and ff) and disables the three-character ligatures (ffi and +ffl). +

+ +

Pairwise kerning is another subtle typesetting mechanism that +modifies the distance between a glyph pair to improve readability. In +most cases (but not always) the distance is decreased. +Typewriter-like fonts and fonts for terminals where all glyphs have the +same width don’t use kerning. +

+
+
Request: .kern [flag]
+
+
Register: \n[.kern]
+
+ + + +

Switch kerning on or off. If the parameter is non-zero or missing, +enable pairwise kerning, otherwise disable it. The read-only register +.kern is set to 1 if pairwise kerning is enabled, +0 otherwise. +

+ + +

If the font description file contains pairwise kerning information, +glyphs from that font are kerned. Kerning between two glyphs can be +inhibited by placing \& between them: ‘V\&A’. +

+

See Font Description File Format. +

+ + + +

Track kerning expands or reduces the space between glyphs. This +can be handy, for example, if you need to squeeze a long word onto a +single line or spread some text to fill a narrow column. It must be +used with great care since it is usually considered bad typography if +the reader notices the effect. +

+
+
Request: .tkf f s1 n1 s2 n2
+
+ + +

Enable track kerning for font f. If the current font +is f the width of every glyph is increased by an amount +between n1 and n2 (n1, n2 can be negative); if +the current type size is less than or equal to s1 the width is +increased by n1; if it is greater than or equal to s2 the +width is increased by n2; if the type size is greater than or +equal to s1 and less than or equal to s2 the increase in +width is a linear function of the type size. +

+

The default scaling unit is ‘z’ for s1 and s2, ‘p’ +for n1 and n2. +

+

The track kerning amount is added even to the rightmost glyph in a line; +for large values it is thus recommended to increase the line length by +the same amount to compensate. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+

5.19.9 Italic Corrections

+ +

When typesetting adjacent glyphs from typefaces of different slants, the +space between them may require adjustment. +

+
+
Escape sequence: \/
+
+ + + + + +

Apply an italic correction: modify the spacing of the preceding +glyph so that the distance between it and the following glyph is correct +if the latter is of upright shape. For example, if an +italic ‘f’ is followed immediately by a roman right +parenthesis, then in many fonts the top right portion of +the ‘f’ overlaps the top left of the right parenthesis, which +is ugly. Use this escape sequence whenever an oblique glyph is +immediately followed by an upright glyph without any intervening space. +

+ +
+
Escape sequence: \,
+
+ + + + + +

Apply a left italic correction: modify the spacing of the +following glyph so that the distance between it and the preceding +glyph is correct if the latter is of upright shape. For example, +if a roman left parenthesis is immediately followed by an +italic ‘f’, then in many fonts the bottom left portion of +the ‘f’ overlaps the bottom of the left parenthesis, which is +ugly. Use this escape sequence whenever an upright glyph is followed +immediately by an oblique glyph without any intervening space. +

+ +
+
+
+
+

+Previous: , Up: Using Fonts   [Contents][Index]

+
+

5.19.10 Dummy Characters

+ +

As discussed in Requests and Macros, the first character on an +input line is treated specially. Further, formatting a glyph has many +consequences on formatter state (see Environments). Occasionally, +we want to escape this context or embrace some of those consequences +without actually rendering a glyph to the output. +

+
+
Escape sequence: \&
+
+ + +

Interpolate a dummy character, which is constitutive of output but +invisible.81 Its presence alters the interpretation context of a +subsequent input character, and enjoys several applications. +

+
    +
  • Prevent insertion of extra space after an end-of-sentence character. + +
    +
    Test.
+Test.
+    ⇒ Test.  Test.
+Test.\&
+Test.
+    ⇒ Test. Test.
+
    + +
  • Prevent recognition of a control character. + +
    +
    .Test
+    error→ warning: macro 'Test' not defined
+\&.Test
+    ⇒ .Test
+
    + +
  • Prevent kerning between two glyphs. + + +
  • Translate a character to “nothing”. + +
    +
    .tr JIjiK\&k\&UVuv
+Post universitum, alea jacta est, OK?
+    ⇒ Post vniversitvm, alea iacta est, O?
+
    +
+ +

The dummy character escape sequence sees use in macro definitions as a +means of ensuring that arguments are treated as text even if they begin +with spaces or control characters. +

+
+
.de HD \" typeset a simple bold heading
+.  sp
+.  ft B
+\&\\$1 \" exercise: remove the \&
+.  ft
+.  sp
+..
+.HD .\|.\|.\|surprised?
+
+
+ +

One way to think about the dummy character is to imagine placing the +symbol ‘&’ in the input at a certain location; if doing so has all +the side effects on formatting that you desire except for sticking an +ugly ampersand in the midst of your text, the dummy character is what +you want in its place. +

+
+
Escape sequence: \)
+
+ + + +

Interpolate a transparent dummy character—one that is +transparent to end-of-sentence detection. It behaves as \&, +except that \& is treated as letters and numerals normally are +after ‘.’, ‘?’ and ‘!’; \& cancels end-of-sentence +detection, and \) does not. +

+
+
.de Suffix-&
+.  nop \&\\$1
+..
+.
+.de Suffix-)
+.  nop \)\\$1
+..
+.
+Here's a sentence.\c
+.Suffix-& '
+Another one.\c
+.Suffix-) '
+And a third.
+    ⇒ Here's a sentence.' Another one.'  And a third.
+
+
+ + + + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.20 Manipulating Type Size and Vertical Spacing

+ + + + + + + + +

These concepts were introduced in Page Geometry. The height of a +font’s tallest glyph is one em, which is equal to the type size in +points.82 A vertical spacing of less than 120% of +the type size can make a document hard to read. Larger proportions can +be useful to spread the text for annotations or proofreader’s marks. By +default, GNU troff uses 10 point type on 12 point +spacing. + +Typographers call the difference between type size and vertical spacing +leading.83 +

+ + + +
+
+
+

+Next: , Previous: , Up: Manipulating Type Size and Vertical Spacing   [Contents][Index]

+
+

5.20.1 Changing the Type Size

+ +
+
Request: .ps [size]
+
+
Request: .ps +size
+
Request: .ps -size
+
Escape sequence: \ssize
+
+
Register: \n[.s]
+
+ + + +

Use the ps request or the \s escape sequence to change +(increase, decrease) the type size (in scaled points). Specify +size as either an absolute type size, or as a relative change from +the current size. ps with no argument restores the previous +size. The ps request’s default scaling unit is ‘z’. The +requested size is rounded to the nearest valid size (with ties rounding +down) within the limits supported by the device. If the requested size +is non-positive, it is treated as 1u. +

+ + + +

Type size alteration is incorrectly documented in the AT&T +troff manual, which claims “if [the requested size] is invalid, +the next larger valid size will result, with a maximum of +36”.84 +

+ + +

The read-only string-valued register .s interpolates the type +size in points as a decimal fraction; it is associated with the +environment (see Environments). To obtain the type size in scaled +points, interpolate the .ps register instead (see Using Fractional Type Sizes). +

+

The \s escape sequence supports a variety of syntax forms. +

+
+
\sn
+

Set the type size to n points. n must be a single +digit. If n is 0, restore the previous size. +

+
+
\s+n
+
\s-n
+

Increase or decrease the type size by n points. +n must be exactly one digit. +

+
+
\s(nn
+

Set the type size to nn points. nn must be exactly two +digits. +

+
+
\s+(nn
+
\s-(nn
+
\s(+nn
+
\s(-nn
+

Alter the type size in points by the two-digit value nn. +

+
+ +

See Using Fractional Type Sizes, for further syntactical forms of the +\s escape sequence that additionally accept decimal fractions. +

+
+
snap, snap,
+.ps +2
+grin, grin,
+.ps +2
+wink, wink, \s+2nudge, nudge,\s+8 say no more!
+.ps 10
+
+
+ +

The \s escape sequence affects the environment immediately and +doesn’t produce an input token. Consequently, it can be used in +requests like mc, which expects a single character as an +argument, to change the type size on the fly. +

+
+
.mc \s[20]x\s[0]
+
+ +
+
Request: .sizes s1 s2 … sn [0]
+
+

The DESC file specifies which type sizes are allowed by the +output device; see DESC File Format. Use the sizes request +to change this set of permissible sizes. Arguments are in scaled +points; see Using Fractional Type Sizes. Each can be a single +type size (such as ‘12000’), or a range of sizes (such as +‘4000-72000’). You can optionally end the list with a ‘0’. +

+ +
+
+
+
+

+Next: , Previous: , Up: Manipulating Type Size and Vertical Spacing   [Contents][Index]

+
+

5.20.2 Changing the Vertical Spacing

+ +
+
Request: .vs [space]
+
+
Request: .vs +space
+
Request: .vs -space
+
Register: \n[.v]
+
+ + + +

Set the vertical spacing to, or alter it by, space. The default +scaling unit is ‘p’. If vs is called without an argument, +the vertical spacing is reset to the previous value before the last call +to vs. + +GNU troff emits a warning in category ‘range’ if space +is negative; the vertical spacing is then set to the smallest possible +positive value, the vertical motion quantum (as found in the .V +register). +

+

‘.vs 0’ isn’t saved in a diversion since it doesn’t result in +a vertical motion. You must explicitly issue this request before +interpolating the diversion. +

+

The read-only register .v contains the vertical spacing; it is +associated with the environment (see Environments). +

+ + +

When a break occurs, GNU troff performs the following procedure. +

+
    +
  • + +Move the drawing position vertically by the extra pre-vertical line +space, the minimum of all negative \x escape sequence arguments +in the pending output line. + +
  • Move the drawing position vertically by the vertical line spacing. + +
  • Write out the pending output line. + +
  • + +Move the drawing position vertically by the extra post-vertical line +space, the maximum of all positive \x escape sequence arguments +in the line that has just been output. + +
  • + +Move the drawing position vertically by the post-vertical line +spacing (see below). +
+ + +

Prefer vs or pvs over ls to produce double-spaced +documents. vs and pvs have finer granularity than +ls; moreover, some preprocessors assume single spacing. +See Manipulating Spacing, regarding the \x escape sequence and +the ls request. +

+
+
Request: .pvs [space]
+
+
Request: .pvs +space
+
Request: .pvs -space
+
Register: \n[.pvs]
+
+ + + +

Set the post-vertical spacing to, or alter it by, space. The +default scaling unit is ‘p’. If pvs is called without an +argument, the post-vertical spacing is reset to the previous value +before the last call to pvs. GNU troff emits a warning in +category ‘range’ if space is negative; the post-vertical +spacing is then set to zero. +

+

The read-only register .pvs contains the post-vertical spacing; +it is associated with the environment (see Environments). +

+ + +
+
+
+
+

+Previous: , Up: Manipulating Type Size and Vertical Spacing   [Contents][Index]

+
+

5.20.3 Using Fractional Type Sizes

+ + + + + + +

AT&T troff interpreted all type size measurements in points. +Combined with integer arithmetic, this design choice made it impossible +to support, for instance, ten and a half-point type. In GNU +troff, an output device can select a scaling factor that +subdivides a point into “scaled points”. A type size expressed in +scaled points can thus represent a non-integral type size. +

+ + + + + + + + + + + +

A scaled point is equal to 1/sizescale points, where +sizescale is specified in the device description file DESC, +and defaults to 1.85 Requests and escape sequences in GNU troff interpret +arguments that represent a type size in scaled points, which the +formatter multiplies by sizescale and converts to an integer. +Arguments treated in this way comprise those to the escape sequences +\H and \s, to the request ps, the third argument to +the cs request, and the second and fourth arguments to the +tkf request. Scaled points may be specified explicitly with the +z scaling unit. +

+

For example, if sizescale is 1000, then a scaled point is one +thousandth of a point. The request ‘.ps 10.5’ is synonymous with +‘.ps 10.5z’ and sets the type size to 10,500 scaled points, or +10.5 points. Consequently, in GNU troff, the register +.s can interpolate a non-integral type size. +

+
+
Register: \n[.ps]
+
+

This read-only register interpolates the type size in scaled points; it +is associated with the environment (see Environments). +

+ +

It makes no sense to use the ‘z’ scaling unit in a numeric +expression whose default scaling unit is neither ‘u’ nor ‘z’, +so GNU troff disallows this. Similarly, it is nonsensical to use +a scaling unit other than ‘z’ or ‘u’ in a numeric expression +whose default scaling unit is ‘z’, and so GNU troff +disallows this as well. +

+

Another GNU troff scaling unit, ‘s’, multiplies by the +number of basic units in a scaled point. Thus, ‘\n[.ps]s’ is equal +to ‘1m’ by definition. Do not confuse the ‘s’ and ‘z’ +scaling units. +

+
+
Register: \n[.psr]
+
+
Register: \n[.sr]
+
+ + + + + + +

Output devices may be limited in the type sizes they can employ. The +.s and .ps registers represent the type size selected by +the output driver as it understands a device’s capability. The last +requested type size is interpolated in scaled points by the +read-only register .psr and in points as a decimal fraction by +the read-only string-valued register .sr. Both are associated +with the environment (see Environments). +

+

For example, if a type size of 10.95 points is requested, and the +nearest size permitted by a sizes request (or by the sizes +or sizescale directives in the device’s DESC file) is 11 +points, the output driver uses the latter value. +

+ +

The \s escape sequence offers the following syntax forms that +work with fractional type sizes and accept scaling units. You may of +course give them integral arguments. The delimited forms need not use +the neutral apostrophe; see Delimiters. +

+
+
\s[n]
+
\s'n'
+

Set the type size to n scaled points; n is a +numeric expression with a default scaling unit of ‘z’. +

+
+
\s[+n]
+
\s[-n]
+
\s+[n]
+
\s-[n]
+
\s'+n'
+
\s'-n'
+
\s+'n'
+
\s-'n'
+

Increase or decrease the type size by n scaled points; +n is a numeric expression (which may start with a minus sign) +with a default scaling unit of ‘z’. +

+
+ + + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.21 Colors

+ + + + + + +

GNU troff supports color output with a variety of color spaces +and up to 16 bits per channel. Some devices, particularly terminals, +may be more limited. When color support is enabled, two colors are +current at any given time: the stroke color, with which glyphs, +rules (lines), and geometric objects like circles and polygons are +drawn, and the fill color, which can be used to paint the interior +of a closed geometric figure. +

+
+
Request: .color [n]
+
+
Register: \n[.color]
+
+

If n is missing or non-zero, enable the output of color-related +device-independent output commands (this is the default); otherwise, +disable them. This request sets a global flag; it does not produce an +input token (see gtroff Internals). +

+

The read-only register .color is 1 if colors are enabled, +0 otherwise. +

+

Color can also be disabled with the -c command-line option. +

+ +
+
Request: .defcolor ident scheme color-component …
+
+

Define a color named ident. scheme selects a color space +and determines the quantity of required color-components; it must +be one of ‘rgb’ (three components), ‘cmy’ (three), ‘cmyk’ +(four), or ‘gray’ (one). ‘grey’ is accepted as a synonym of +‘gray’. The color components can be encoded as a single +hexadecimal value starting with ‘#’ or ‘##’. The former +indicates that each component is in the range 0–255 (0–FF), the latter +the range 0–65,535 (0–FFFF). +

+
+
.defcolor half gray #7f
+.defcolor pink rgb #FFC0CB
+.defcolor magenta rgb  ##ffff0000ffff
+
+ + + + +

Alternatively, each color component can be specified as a decimal +fraction in the range 0–1, interpreted using a default scaling +unit of f, which multiplies its value by 65,536 (but +clamps it at 65,535). +

+
+
.defcolor gray50 rgb 0.5 0.5 0.5
+.defcolor darkgreen rgb 0.1f 0.5f 0.2f
+
+
+ + + +

Each output device has a color named ‘default’, which cannot be +redefined. A device’s default stroke and fill colors are not +necessarily the same. For the dvi, html, pdf, +ps, and xhtml output devices, GNU troff +automatically loads a macro file defining many color names at startup. +By the same mechanism, the devices supported by grotty recognize +the eight standard ISO 6429/EMCA-48 color names.86 +

+
+
Request: .gcolor [color]
+
+
Escape sequence: \mc
+
+
Escape sequence: \m(co
+
Escape sequence: \m[color]
+
Register: \n[.m]
+
+

Set the stroke color to color. +

+
+
.gcolor red
+The next words
+.gcolor
+\m[red]are in red\m[]
+and these words are in the previous color.
+
+ +

The escape sequence \m[] restores the previous stroke color, as +does a gcolor request without an argument. +

+ + + +

The name of the current stroke color is available in the read-only +string-valued register ‘.m’; it is associated with the environment +(see Environments). It interpolates nothing when the stroke color +is the default. +

+

\m doesn’t produce an input token in GNU troff +(see gtroff Internals). It therefore can be used in requests like +mc (which expects a single character as an argument) to change +the color on the fly: +

+
+
.mc \m[red]x\m[]
+
+
+ +
+
Request: .fcolor [color]
+
+
Escape sequence: \Mc
+
+
Escape sequence: \M(co
+
Escape sequence: \M[color]
+
Register: \n[.M]
+
+

Set the fill color for objects drawn with \D'…' escape +sequences. The escape sequence \M[] restores the previous fill +color, as does an fcolor request without an argument. +

+ + + + + + +

The name of the current fill color is available in the read-only +string-valued register ‘.M’; it is associated with the environment +(see Environments). It interpolates nothing when the fill color +is the default. \M doesn’t produce an input token in GNU +troff. +

+

Create an ellipse with a red interior as follows. +

+
+
\M[red]\h'0.5i'\D'E 2i 1i'\M[]
+
+
+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.22 Strings

+ + +

GNU troff supports strings primarily for user convenience. +Conventionally, if one would define a macro only to interpolate a small +amount of text, without invoking requests or calling any other macros, +one defines a string instead. Only one string is predefined by the +language. +

+
+
String: \*[.T]
+
+ + +

Contains the name of the output device (for example, ‘utf8’ or +‘pdf’). +

+ +

The ds request creates a string with a specified name and +contents and the \* escape sequence dereferences its name, +interpolating its contents. If the string named by the \* escape +sequence does not exist, it is defined as empty, nothing is +interpolated, and a warning in category ‘mac’ is emitted. +See Warnings, for information about the enablement and suppression of +warnings. +

+
+
Request: .ds name [contents]
+
+
Request: .ds1 name [contents]
+
+
Escape sequence: \*n
+
+
Escape sequence: \*(nm
+
Escape sequence: \*[name [arg1 arg2 …]]
+
+ + + + + +

Define a string called name with contents contents. If +name already exists as an alias, the target of the alias is +redefined; see als and rm below. If ds is called +with only one argument, name is defined as an empty string. +Otherwise, GNU troff stores contents in copy +mode.87 +

+

The \* escape sequence interpolates a previously defined string +variable name (one-character name n, two-character name +nm). The bracketed interpolation form accepts arguments that are +handled as macro arguments are; recall Calling Macros. In +contrast to macro calls, however, if a closing bracket ‘]’ occurs +in a string argument, that argument must be enclosed in double quotes. +\* is interpreted even in copy mode. When defining strings, +argument interpolations must be escaped if they are to reference +parameters from the calling context; See Parameters. +

+
+
.ds cite (\\$1, \\$2)
+Gray codes are explored in \*[cite Morgan 1998].
+    ⇒ Gray codes are explored in (Morgan, 1998).
+
+ + + + + +

Caution: Unlike other requests, the second argument to the +ds request consumes the remainder of the input line, including +trailing spaces. This means that comments on a line with such a request +can introduce unwanted space into a string when they are set off from +the material they annotate, as is conventional. +

+
+
.ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O \" water
+
+ +

Instead, place the comment on another line or put the comment escape +sequence immediately adjacent to the last character of the string. +

+
+
.ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O\" water
+
+ +

Ending string definitions (and appendments) with a comment, even an +empty one, prevents unwanted space from creeping into them during source +document maintenance. +

+
+
.ds author Alice Pleasance Liddell\"
+.ds empty \" might be appended to later with .as
+
+ + + + + + + +

An initial neutral double quote " in contents is stripped +to allow embedding of leading spaces. Any other " is interpreted +literally, but it is wise to use the special character escape sequence +\[dq] instead if the string might be interpolated as part of a +macro argument; see Calling Macros. +

+
+
.ds salutation "         Yours in a white wine sauce,\"
+.ds c-var-defn "  char mydate[]=\[dq]2020-07-29\[dq];\"
+
+ + + + + +

Strings are not limited to a single input line of text. +\RET works just as it does elsewhere. The resulting string +is stored without the newlines. Care is therefore required when +interpolating strings while filling is disabled. +

+
+
.ds foo This string contains \
+text on multiple lines \
+of input.
+
+ +

It is not possible to embed a newline in a string that will be +interpreted as such when the string is interpolated. To achieve that +effect, use \* to interpolate a macro instead; see Punning Names. +

+

Because strings are similar to macros, they too can be defined so as to +suppress AT&T troff compatibility mode when used; see +Writing Macros and Compatibility Mode. The ds1 +request defines a string such that compatibility mode is off when the +string is later interpolated. To be more precise, a compatibility +save input token is inserted at the beginning of the string, and a +compatibility restore input token at the end. +

+
+
.nr xxx 12345
+.ds aa The value of xxx is \\n[xxx].
+.ds1 bb The value of xxx is \\n[xxx].
+.
+.cp 1
+.
+\*(aa
+    error→ warning: register '[' not defined
+    ⇒ The value of xxx is 0xxx].
+\*(bb
+    ⇒ The value of xxx is 12345.
+
+
+ +
+
Request: .as name [contents]
+
+
Request: .as1 name [contents]
+
+ + +

The as request is similar to ds but appends contents +to the string stored as name instead of redefining it. If +name doesn’t exist yet, it is created. If as is called +with only one argument, no operation is performed (beyond dereferencing +the string). +

+
+
.as salutation " with shallots, onions and garlic,\"
+
+ +

The as1 request is similar to as, but compatibility mode +is switched off when the appended portion of the string is later +interpolated. To be more precise, a compatibility save input +token is inserted at the beginning of the appended string, and a +compatibility restore input token at the end. +

+ +

Several requests exist to perform rudimentary string operations. +Strings can be queried (length) and modified (chop, +substring, stringup, stringdown), and their names +can be manipulated through renaming, removal, and aliasing (rn, +rm, als). +

+
+
Request: .length reg anything
+
+ + + + + +

Compute the number of characters of anything and store the count +in the register reg. If reg doesn’t exist, it is created. +anything is read in copy mode. +

+
+
.ds xxx abcd\h'3i'efgh
+.length yyy \*[xxx]
+\n[yyy]
+    ⇒ 14
+
+
+ +
+
Request: .chop object
+
+

Remove the last character from the macro, string, or diversion named +object. This is useful for removing the newline from the end of a +diversion that is to be interpolated as a string. This request can be +used repeatedly on the same object; see gtroff Internals, +for details on nodes inserted additionally by GNU troff. +

+ +
+
Request: .substring str start [end]
+
+ +

Replace the string named str with its substring bounded by the +indices start and end, inclusively. The first character in +the string has index 0. If end is omitted, it is implicitly +set to the largest valid value (the string length minus one). Negative +indices count backward from the end of the string: the last character +has index −1, the character before the last has +index −2, and so on. +

+
+
.ds xxx abcdefgh
+.substring xxx 1 -4
+\*[xxx]
+    ⇒ bcde
+.substring xxx 2
+\*[xxx]
+    ⇒ de
+
+
+ +
+
Request: .stringdown str
+
+
Request: .stringup str
+
+ + + + + +

Alter the string named str by replacing each of its bytes with its +lowercase (stringdown) or uppercase (stringup) version (if +one exists). Special characters in the string will often transform in +the expected way due to the regular naming convention for accented +characters. When they do not, use substrings and/or catenation. +

+
+
.ds resume R\['e]sum\['e]
+\*[resume]
+.stringdown resume
+\*[resume]
+.stringup resume
+\*[resume]
+    ⇒ Résumé résumé RÉSUMÉ
+
+
+ +

(In practice, we would end the ds request with a comment escape +\" to prevent space from creeping into the definition during +source document maintenance.) +

+
+
Request: .rn old new
+
+ + + + + + + + +

Rename the request, macro, diversion, or string old to new. +

+ +
+
Request: .rm name
+
+ + + + + + + + +

Remove the request, macro, diversion, or string name. GNU +troff treats subsequent invocations as if the name had never +been defined. +

+ +
+
Request: .als new old
+
+ + + + + + + + + +

Create an alias new for the existing request, string, macro, or +diversion object named old, causing the names to refer to the same +stored object. If old is undefined, a warning in category +‘mac’ is produced, and the request is ignored. See Warnings, +for information about the enablement and suppression of warnings. +

+

To understand how the als request works, consider two different +storage pools: one for objects (macros, strings, etc.), and another +for names. As soon as an object is defined, GNU troff adds it to +the object pool, adds its name to the name pool, and creates a link +between them. When als creates an alias, it adds a new name to +the name pool that gets linked to the same object as the old name. +

+

Now consider this example. +

+
+
.de foo
+..
+.
+.als bar foo
+.
+.de bar
+.  foo
+..
+.
+.bar
+    error→ input stack limit exceeded (probable infinite
+    error→ loop)
+
+ +

In the above, bar remains an alias—another name +for—the object referred to by foo, which the second de +request replaces. Alternatively, imagine that the de request +dereferences its argument before replacing it. Either way, the +result of calling bar is a recursive loop that finally leads to +an error. See Writing Macros. +

+ + + + + + + + + +

To remove an alias, call rm on its name. The object itself is +not destroyed until it has no more names. +

+

When a request, macro, string, or diversion is aliased, redefinitions +and appendments “write through” alias names. To replace an alias with +a separately defined object, you must use the rm request on its +name first. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.23 Conditionals and Loops

+ + + +

groff has if and while control structures like +other languages. However, the syntax for grouping multiple input lines +in the branches or bodies of these structures is unusual. +

+ + + +
+
+
+

+Next: , Previous: , Up: Conditionals and Loops   [Contents][Index]

+
+

5.23.1 Operators in Conditionals

+ + + + + + +

In if, ie, and while requests, in addition to the +numeric expressions described in Numeric Expressions, several +Boolean operators are available; the members of this expanded class are +termed conditional expressions. +

+
+
c glyph
+

True if glyph is available, where glyph is an ordinary +character, a special character ‘\(xx’ or ‘\[xxx]’, +‘\N'xxx'’, or has been defined by any of the char, +fchar, fschar, or schar requests. +

+
+
d name
+

True if a string, macro, diversion, or request called name exists. +

+
+
e
+

True if the current page is even-numbered. +

+
+
F font
+

True if font exists. font is handled as if it were opened +with the ft request (that is, font translation and styles are +applied), without actually mounting it. +

+
+
m color
+

True if color is defined. +

+
+
n
+
+ +

True if the document is being processed in nroff mode. +See troff and nroff Modes. +

+
+
o
+

True if the current page is odd-numbered. +

+
+
r register
+

True if register exists. +

+
+
S style
+

True if style is available for the current font family. Font +translation is applied. +

+
+
t
+

True if the document is being processed in troff mode. +See troff and nroff Modes. +

+ +
+
v
+

Always false. This condition is recognized only for compatibility with +certain other troff implementations.88 +

+
+ +

If the first argument to an if, ie, or while +request begins with a non-alphanumeric character apart from ! +(see below); it performs an output comparison test. +89 +

+ +
+
'xxx'yyy'
+

True if formatting the comparands xxx and yyy produces the +same output commands. The delimiter need not be a neutral apostrophe: +the output comparison operator accepts the same delimiters as most +escape sequences; see Delimiters. This output comparison +operator formats xxx and yyy in separate environments; +after the comparison, the resulting data are discarded. +

+
+
.ie "|"\fR|\fP" true
+.el false
+    ⇒ true
+
+ +

The resulting glyph properties, including font family, style, size, and +slant, must match, but not necessarily the requests and/or escape +sequences used to obtain them. In the previous example, ‘|’ and +‘\fR|\fP’ result in ‘|’ glyphs in the same typefaces at the +same positions, so the comparands are equal. If ‘.ft I’ had +been added before the ‘.ie’, they would differ: the first ‘|’ +would produce an italic ‘|’, not a roman one. Motions must match +in orientation and magnitude to within the applicable horizontal and +vertical motion quanta of the device, after rounding. ‘.if +"\u\d"\v'0'"’ is false even though both comparands result in zero net +motion, because motions are not interpreted or optimized but sent as-is +to the output.90 On the other hand, ‘.if "\d"\v'0.5m'"’ is true, because +\d is defined as a downward motion of one-half em.91 +

+ + +

Surround the comparands with \? to avoid formatting them; this +causes them to be compared character by character, as with string +comparisons in other programming languages. +

+
+
.ie "\?|\?"\?\fR|\fP\?" true
+.el false
+    ⇒ false
+
+ + + + +

Since comparands protected with \? are read in copy mode +(see Copy Mode), they need not even be valid groff syntax. +The escape character is still lexically recognized, however, and +consumes the next character. +

+
+
.ds a \[
+.ds b \[
+.if '\?\*a\?'\?\*b\?' a and b equivalent
+.if '\?\\?'\?\\?' backslashes equivalent
+    ⇒ a and b equivalent
+
+
+
+ +

The above operators can’t be combined with most others, but a leading +‘!’, not followed immediately by spaces or tabs, complements an +expression. +

+
+
.nr x 1
+.ie !r x register x is not defined
+.el      register x is defined
+    ⇒ register x is defined
+
+ +

Spaces and tabs are optional immediately after the ‘c’, ‘d’, +‘F’, ‘m’, ‘r’, and ‘S’ operators, but right after +‘!’, they end the predicate and the conditional evaluates +true.92 +

+
+
.nr x 1
+.ie ! r x register x is not defined
+.el       register x is defined
+    ⇒ r x register x is not defined
+
+ +

The unexpected ‘r x’ in the output is a clue that our conditional +was not interpreted as we planned, but matters may not always be so +obvious. +

+ +
+
+
+
+

+Next: , Previous: , Up: Conditionals and Loops   [Contents][Index]

+
+

5.23.2 if-then

+ + +
+
Request: .if cond-expr anything
+
+

Evaluate the conditional expression cond-expr, and if it evaluates +true (or to a positive value), interpret the remainder of the line +anything as if it were an input line. Recall from Invoking Requests that any quantity of spaces between arguments to requests +serves only to separate them; leading spaces in anything are thus +not seen. anything effectively cannot be omitted; if +cond-expr is true and anything is empty, the newline at the +end of the control line is interpreted as a blank input line (and +therefore a blank text line). +

+
+
super\c
+tanker
+.nr force-word-break 1
+super\c
+.if ((\n[force-word-break] = 1) & \n[.int])
+tanker
+    ⇒ supertanker super tanker
+
+
+ +
+
Request: .nop anything
+
+

Interpret anything as if it were an input line. This is similar +to ‘.if 1’. nop is not really “no operation”; its +argument is processed—unconditionally. It can be used to cause +text lines to share indentation with surrounding control lines. +

+
+
.als real-MAC MAC
+.de wrapped-MAC
+.  tm MAC: called with arguments \\$@
+.  nop \\*[real-MAC]\\
+..
+.als MAC wrapped-MAC
+\# Later...
+.als MAC real-MAC
+
+ +

In the above, we’ve used aliasing, nop, and the interpolation of +a macro as a string to interpose a wrapper around the macro ‘MAC’ +(perhaps to debug it). +

+ + +
+
+
+
+

+Next: , Previous: , Up: Conditionals and Loops   [Contents][Index]

+
+

5.23.3 if-else

+ + +
+
Request: .ie cond-expr anything
+
+
Request: .el anything
+
+

Use the ie and el requests to write an if-then-else. The +first request is the “if” part and the latter is the “else” part. +Unusually among programming languages, any number of non-conditional +requests may be interposed between the ie branch and the +el branch. +

+
+
.nr a 0
+.ie \na a is non-zero.
+.nr a +1
+.el a was not positive but is now \na.
+    ⇒ a was not positive but is now 1.
+
+ +

Another way in which el is an ordinary request is that it does +not lexically “bind” more tightly to its ie counterpart than it +does to any other request. This fact can surprise C programmers. +

+
+
.nr a 1
+.nr z 0
+.ie \nz \
+.  ie \na a is true
+.  el     a is false
+.el z is false
+    error→ warning: unbalanced 'el' request
+    ⇒ a is false
+
+ +

To conveniently nest conditionals, keep reading. +

+
+ + +
+
+
+
+

+Next: , Previous: , Up: Conditionals and Loops   [Contents][Index]

+
+

5.23.4 Conditional Blocks

+ + + +

It is frequently desirable for a control structure to govern more than +one request, macro call, text line, or a combination of the foregoing. +The opening and closing brace escape sequences \{ and \} +define such groups. These conditional blocks can furthermore be +nested. +

+
+
Escape sequence: \{
+
+
Escape sequence: \}
+
+ + + + + + + + + + + + + +

\{ begins a conditional block; it must appear (after optional +spaces and tabs) immediately subsequent to the conditional expression of +an if, ie, or while +request,93 or as the argument to an el +request. +

+

\} ends a condition block and should appear on a line with other +occurrences of itself as necessary to match \{ sequences. It +can be preceded by a control character, spaces, and tabs. Input after +any quantity of \} sequences on the same line is processed only +if all of the preceding conditions to which they correspond are true. +Furthermore, a \} closing the body of a while request +must be the last such escape sequence on an input line. +

+

Brace escape sequences outside of control structures have no meaning and +produce no output. +

+

Caution: Input lines using \{ often end with +\RET, especially in macros that consist primarily of control +lines. Forgetting to use \RET on an input line after \{ +is a common source of error. +

+ +

We might write the following in a page header macro. If we delete +\RET, the header will carry an unwanted extra empty line (except +on page 1). +

+
+
.if (\\n[%] != 1) \{\
+.  ie ((\\n[%] % 2) = 0) .tl \\*[even-numbered-page-title]
+.  el                    .tl \\*[odd-numbered-page-title]
+.\}
+
+ +

Let us take a closer look at how conditional blocks nest. +

+
+
A
+.if 0 \{ B
+C
+D
+\}E
+F
+    ⇒ A F
+
+ +
+
N
+.if 1 \{ O
+.  if 0 \{ P
+Q
+R\} S\} T
+U
+    ⇒ N O U
+
+ +

The above behavior may challenge the intuition; it was implemented to +retain compatibility with AT&T troff. For clarity, it +is idiomatic to end input lines with \{ (followed by +\RET if appropriate), and to precede \} on an input +line with nothing more than a control character, spaces, tabs, and other +instances of itself. +

+

We can use ie, el, and conditional blocks to simulate the +multi-way “switch” or “case” control structures of other languages. +The following example is adapted from the groff man +package. Indentation is used to clarify the logic. +

+
+
.\" Simulate switch/case in roff.
+.      ie '\\$2'1' .ds title General Commands\"
+.el \{.ie '\\$2'2' .ds title System Calls\"
+.el \{.ie '\\$2'3' .ds title Library Functions\"
+.el \{.ie '\\$2'4' .ds title Kernel Interfaces\"
+.el \{.ie '\\$2'5' .ds title File Formats\"
+.el \{.ie '\\$2'6' .ds title Games\"
+.el \{.ie '\\$2'7' .ds title Miscellaneous Information\"
+.el \{.ie '\\$2'8' .ds title System Management\"
+.el \{.ie '\\$2'9' .ds title Kernel Development\"
+.el                .ds title \" empty
+.\}\}\}\}\}\}\}\}
+
+ + +
+
+
+
+

+Previous: , Up: Conditionals and Loops   [Contents][Index]

+
+

5.23.5 while

+ + +

groff provides a looping construct: the while request. +Its syntax matches the if request. +

+ +
+
Request: .while cond-expr anything
+
+

Evaluate the conditional expression cond-expr, and repeatedly +execute anything unless and until cond-expr evaluates false. +anything, which is often a conditional block, is referred to as +the while request’s body. +

+
+
.nr a 0 1
+.while (\na < 9) \{\
+\n+a,
+.\}
+\n+a
+    ⇒ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
+
+ + +

GNU troff treats the body of a while request similarly to +that of a de request (albeit one not read in copy +mode94), but stores it under an internal name +and deletes it when the loop finishes. The operation of a macro +containing a while request can slow significantly if the +while body is large. Each time the macro is executed, the +while body is parsed and stored again. +

+
+
.de xxx
+.  nr num 10
+.  while (\\n[num] > 0) \{\
+.    \" many lines of code
+.    nr num -1
+.  \}
+..
+
+ + + +

An often better solution—and one that is more portable, since +AT&T troff lacked the while request—is to +instead write a recursive macro. It will be parsed only +once.95 +

+
+
.de yyy
+.  if (\\n[num] > 0) \{\
+.    \" many lines of code
+.    nr num -1
+.    yyy
+.  \}
+..
+.
+.de xxx
+.  nr num 10
+.  yyy
+..
+
+ +

To prevent infinite loops, the default number of available recursion +levels is 1,000 or somewhat less.96 You can +disable this protective measure, or raise the limit, by setting the +slimit register. See Debugging. +

+

As noted above, if a while body begins with a conditional block, +its closing brace must end an input line. +

+
+
.if 1 \{\
+.  nr a 0 1
+.  while (\n[a] < 10) \{\
+.    nop \n+[a]
+.\}\}
+    error→ unbalanced brace escape sequences
+
+
+ +
+
Request: .break
+
+ + + +

Exit a while loop. Do not confuse this request with a +typographical break or the br request. +

+ +
+
Request: .continue
+
+

Skip the remainder of a while loop’s body, immediately starting +the next iteration. +

+ + + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.24 Writing Macros

+ + + +

A macro is a stored collection of text and control lines that can +be interpolated multiple times. Use macros to define common operations. +Macros are called in the same way that requests are invoked. While +requests exist for the purpose of creating macros, simply calling an +undefined macro, or interpolating it as a string, will cause it to be +defined as empty. See Identifiers. +

+
+
Request: .de name [end]
+
+

Define a macro name, replacing the definition of any existing +request, macro, string, or diversion called name. If +name already exists as an alias, the target of the alias is +redefined; recall Strings. GNU troff enters copy +mode,97 storing subsequent input lines as the +macro definition. If the optional second argument is not specified, the +definition ends with the control line ‘..’ (two dots). +Alternatively, end identifies a macro whose call syntax at the +start of a control line ends the definition of name; end is +then called normally. A macro definition must end in the same +conditional block (if any) in which it began (see Conditional Blocks). Spaces or tabs are permitted after the control character in +the line containing this ending token (either ‘.’ or +‘end’), but a tab immediately after the token prevents its +recognition as the end of a macro definition. The macro end can +be called with arguments.98 +

+

Here is a small example macro called ‘P’ that causes a break and +inserts some vertical space. It could be used to separate paragraphs. +

+
+
.de P
+.  br
+.  sp .8v
+..
+
+ +

We can define one macro within another. Attempting to nest ‘..’ +naïvely will end the outer definition because the inner definition +isn’t interpreted as such until the outer macro is later interpolated. +We can use an end macro instead. Each level of nesting should use a +unique end macro. +

+

An end macro need not be defined until it is called. This fact enables +a nested macro definition to begin inside one macro and end inside +another. Consider the following example.99 +

+
+
.de m1
+.  de m2 m3
+you
+..
+.de m3
+Hello,
+Joe.
+..
+.de m4
+do
+..
+.m1
+know?
+.  m3
+What
+.m4
+.m2
+    ⇒ Hello, Joe.  What do you know?
+
+ +

A nested macro definition can be terminated with ‘..’ and +nested macros can reuse end macros, but these control lines must +be escaped multiple times for each level of nesting. The necessity of +this escaping and the utility of nested macro definitions will become +clearer when we employ macro parameters and consider the behavior of +copy mode in detail. +

+ +

de defines a macro that inherits the compatibility mode +enablement status of its context (see Implementation Differences). +Often it is desirable to make a macro that uses groff features +callable from contexts where compatibility mode is on; for instance, +when writing extensions to a historical macro package. To achieve this, +compatibility mode needs to be switched off while such a macro is +interpreted—without disturbing that state when it is finished. +

+
+
Request: .de1 name [end]
+
+

The de1 request defines a macro to be interpreted with +compatibility mode disabled. When name is called, compatibility +mode enablement status is saved; it is restored when the call completes. +Observe the extra backlash before the interpolation of register +‘xxx’; we’ll explore this subject in Copy Mode. +

+
+
.nr xxx 12345
+.de aa
+The value of xxx is \\n[xxx].
+.  br
+..
+.de1 bb
+The value of xxx is \\n[xxx].
+..
+.cp 1
+.aa
+    error→ warning: register '[' not defined
+    ⇒ The value of xxx is 0xxx].
+.bb
+    ⇒ The value of xxx is 12345.
+
+
+ +
+
Request: .dei name [end]
+
+
Request: .dei1 name [end]
+
+

The dei request defines a macro with its name and end +macro indirected through strings. That is, it interpolates strings +named name and end before performing the definition. +

+

The following examples are equivalent. +

+
+
.ds xx aa
+.ds yy bb
+.dei xx yy
+
+ +
+
.de aa bb
+
+ +

The dei1 request bears the same relationship to dei as +de1 does to de; it temporarily turns compatibility mode +off when name is called. +

+ +
+
Request: .am name [end]
+
+
Request: .am1 name [end]
+
+
Request: .ami name [end]
+
+
Request: .ami1 name [end]
+
+ + +

am appends subsequent input lines to macro name, extending +its definition, and otherwise working as de does. +

+

To make the previously defined ‘P’ macro set indented instead of +block paragraphs, add the necessary code to the existing macro. +

+
+
.am P
+.ti +5n
+..
+
+ +

The other requests are analogous to their ‘de’ counterparts. The +am1 request turns off compatibility mode during interpretation of +the appendment. The ami request appends indirectly, meaning that +strings name and end are interpolated with the resulting +names used before appending. The ami1 request is similar to +ami, disabling compatibility mode during interpretation of the +appended lines. +

+ + +

Using trace.tmac, you can trace calls to de, +de1, am, and am1. You can also use the +backtrace request at any point desired to troubleshoot tricky +spots (see Debugging). +

+

See Strings, for the als, rm, and rn requests to +create an alias of, remove, and rename a macro, respectively. +

+ +

Macro identifiers share their name space with requests, strings, and +diversions; see Identifiers. The am, as, da, +de, di, and ds requests (together with their +variants) create a new object only if the name of the macro, diversion, +or string is currently undefined or if it is defined as a request; +normally, they modify the value of an existing object. See the +description of the als request, for pitfalls when redefining a +macro that is aliased. +

+
+
Request: .return [anything]
+
+

Exit a macro, immediately returning to the caller. If called with an +argument anything, exit twice—the current macro and the macro +one level higher. This is used to define a wrapper macro for +return in trace.tmac. +

+ + + + +
+
+
+

+Next: , Previous: , Up: Writing Macros   [Contents][Index]

+
+

5.24.1 Parameters

+ + +

Macro calls and string interpolations optionally accept a list of +arguments; recall Calling Macros. At the time such an +interpolation takes place, these parameters can be examined using +a register and a variety of escape sequences starting with ‘\$’. +All such escape sequences are interpreted even in copy mode, a fact we +shall motivate and explain below (see Copy Mode). +

+
+
Register: \n[.$]
+
+ +

The count of parameters available to a macro or string is kept in this +read-only register. The shift request can change its value. +

+ +

Any individual parameter can be accessed by its position in the list of +arguments to the macro call, numbered from left to right starting at 1, +with one of the following escape sequences. +

+
+
Escape sequence: \$n
+
+
Escape sequence: \$(nn
+
Escape sequence: \$[nnn]
+

Interpolate the nth, nnth, or nnnth parameter. The +first form expects only a single digit (1≤n≤9)), the +second two digits (01≤nn≤99)), and the third any +positive integer nnn. Macros and strings accept an unlimited +number of parameters. +

+ +
+
Request: .shift [n]
+
+

Shift the parameters n places (1 by default). This is a +“left shift”: what was parameter i becomes parameter +i-n. The parameters formerly in positions 1 +to n are no longer available. Shifting by a non-positive +amount performs no operation. The register .$ is adjusted +accordingly. +

+ + + + + +

In practice, parameter interpolations are usually seen prefixed with an +extra escape character. This is because the \$ family of escape +sequences is interpreted even in copy mode.100 +

+
+
Escape sequence: \$*
+
+
Escape sequence: \$@
+
+
Escape sequence: \$^
+
+

In some cases it is convenient to interpolate all of the parameters at +once (to pass them to a request, for instance). The \$* escape +concatenates the parameters, separating them with spaces. \$@ +is similar, concatenating the parameters, surrounding each with double +quotes and separating them with spaces. If not in compatibility mode, +the interpolation depth of double quotes is preserved (see Calling Macros). \$^ interpolates all parameters as if they were +arguments to the ds request. +

+
+
.de foo
+. tm $1='\\$1'
+. tm $2='\\$2'
+. tm $*='\\$*'
+. tm $@='\\$@'
+. tm $^='\\$^'
+..
+.foo " This is a "test"
+    error→ $1=' This is a '
+    error→ $2='test"'
+    error→ $*=' This is a  test"'
+    error→ $@='" This is a " "test""'
+    error→ $^='" This is a "test"'
+
+ +

\$* is useful when writing a macro that doesn’t need to +distinguish its arguments, or even to not interpret them; examples +include macros that produce diagnostic messages by wrapping the +tm or ab requests. Use \$@ when writing a macro +that may need to shift its parameters and/or wrap a macro or request +that finds the count significant. If in doubt, prefer \$@ to +\$*. An application of \$^ is seen in trace.tmac, +which redefines some requests and macros for debugging purposes. +

+ +
+
Escape sequence: \$0
+
+ + +

Interpolate the name by which the macro being interpreted was called. +The als request can cause a macro to have more than one name. +Applying string interpolation to a macro does not change this name. +

+
+
.de foo
+.  tm \\$0
+..
+.als bar foo
+.
+.de aaa
+.  foo
+..
+.de bbb
+.  bar
+..
+.de ccc
+\\*[foo]\\
+..
+.de ddd
+\\*[bar]\\
+..
+.
+.aaa
+    error→ foo
+.bbb
+    error→ bar
+.ccc
+    error→ ccc
+.ddd
+    error→ ddd
+
+
+ + +
+
+
+
+

+Previous: , Up: Writing Macros   [Contents][Index]

+
+

5.24.2 Copy Mode

+ + + + + + + + + +

When GNU troff processes certain requests, most importantly those +which define or append to a macro or string, it does so in copy +mode: it copies the characters of the definition into a dedicated +storage region, interpolating the escape sequences \n, \g, +\$, \*, \V, and \? normally; interpreting +\RET immediately; discarding comments \" and +\#; interpolating the current leader, escape, or tab character +with \a, \e, and \t, respectively; and storing all +other escape sequences in an encoded form. +

+ + +

The complement of copy mode—a roff formatter’s behavior when +not defining or appending to a macro, string, or diversion—where all +macros are interpolated, requests invoked, and valid escape sequences +processed immediately upon recognition, can be termed +interpretation mode. +

+
+
Escape sequence: \\
+
+

The escape character, \ by default, can escape itself. This +enables you to control whether a given \n, \g, \$, +\*, \V, or \? escape sequence is interpreted at the +time the macro containing it is defined, or later when the macro is +called.101 +

+
+
.nr x 20
+.de y
+.nr x 10
+\&\nx
+\&\\nx
+..
+.y
+    ⇒ 20 10
+
+ +

You can think of \\ as a “delayed” backslash; it is the escape +character followed by a backslash from which the escape character has +removed its special meaning. Consequently, ‘\\’ is not an escape +sequence in the usual sense. In any escape sequence ‘\X’ +that GNU troff does not recognize, the escape character is +ignored and X is output. An unrecognized escape sequence causes +a warning in category ‘escape’, with two exceptions—‘\\’ is +the first. +

+ + +
+
Escape sequence: \.
+
+

\. escapes the control character. It is similar to \\ in +that it isn’t a true escape sequence. It is used to permit nested macro +definitions to end without a named macro call to conclude them. Without +a syntax for escaping the control character, this would not be possible. +

+
+
.de m1
+foo
+.
+.  de m2
+bar
+\\..
+.
+..
+.m1
+.m2
+    ⇒ foo bar
+
+ +

The first backslash is consumed while the macro is read, and the second +is interpreted when macro m1 is called. +

+ +

roff documents should not use the \\ or \. +character sequences outside of copy mode; they serve only to obfuscate +the input. Use \e to represent the escape character, +\[rs] to obtain a backslash glyph, and \& before ‘.’ +and ‘'’ where GNU troff expects them as control characters +if you mean to use them literally (recall Requests and Macros). +

+

Macro definitions can be nested to arbitrary depth. The mechanics of +parsing the escape character have significant consequences for this +practice. +

+
+
.de M1
+\\$1
+.  de M2
+\\\\$1
+.    de M3
+\\\\\\\\$1
+\\\\..
+.    M3 hand.
+\\..
+.  M2 of
+..
+This understeer is getting
+.M1 out
+    ⇒ This understeer is getting out of hand.
+
+ +

Each escape character is interpreted twice—once in copy mode, when the +macro is defined, and once in interpretation mode, when the macro is +called. As seen above, this fact leads to exponential growth in the +quantity of escape characters required to delay interpolation of +\n, \g, \$, \*, \V, and \? at +each nesting level, which can be daunting. GNU troff offers a +solution. +

+
+
Escape sequence: \E
+
+

\E represents an escape character that is not interpreted in copy +mode. You can use it to ease the writing of nested macro definitions. +

+
+
.de M1
+.  nop \E$1
+.  de M2
+.    nop \E$1
+.    de M3
+.      nop \E$1
+\\\\..
+.    M3 better.
+\\..
+.  M2 bit
+..
+This vehicle handles
+.M1 a
+    ⇒ This vehicle handles a bit better.
+
+ +

Observe that because \. is not a true escape sequence, we can’t +use \E to keep ‘..’ from ending a macro definition +prematurely. If the multiplicity of backslashes complicates +maintenance, use end macros. +

+

\E is also convenient to define strings containing escape +sequences that need to work when used in copy mode (for example, as +macro arguments), or which will be interpolated at varying macro nesting +depths. We might define strings to begin and end superscripting +as follows.102 +

+
+
.ds { \v'-.9m\s'\En[.s]*7u/10u'+.7m'
+.ds } \v'-.7m\s0+.9m'
+
+ +

When the ec request is used to redefine the escape character, +\E also makes it easier to distinguish the semantics of an escape +character from the other meaning(s) its character might have. Consider +the use of an unusual escape character, ‘-’. +

+
+
.nr a 1
+.ec -
+.de xx
+--na
+..
+.xx
+    ⇒ -na
+
+ +

This result may surprise you; some people expect ‘1’ to be output +since register ‘a’ has clearly been defined with that value. What +has happened? The robotic replacement of ‘\’ with ‘-’ has led +us astray. You might recognize the sequence ‘--’ more readily with +the default escape character as ‘\-’, the special character escape +sequence for the minus sign glyph. +

+
+
.nr a 1
+.ec -
+.de xx
+-Ena
+..
+.xx
+    ⇒ 1
+
+
+ + + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.25 Page Motions

+ + + +

See Manipulating Spacing, for a discussion of the most commonly used +request for vertical motion, sp, which spaces downward by one +vee. +

+
+
Request: .mk [reg]
+
+
Request: .rt [dist]
+
+ + + + + + + + +

You can mark a location on a page for subsequent return. +mk takes an argument, a register name in which to store the +current page location. If given no argument, it stores the location in +an internal register. This location can be used later by the rt +or the sp requests (or the \v escape). +

+

The rt request returns upward to the location marked with +the last mk request. If used with an argument, it returns to a +vertical position dist from the top of the page (no previous +call to mk is necessary in this case). The default scaling +unit is ‘v’. +

+

If a page break occurs between a mk request and its matching +rt request, the rt request is silently ignored. +

+

A simple implementation of a macro to set text in two columns follows. +

+
+
.nr column-length 1.5i
+.nr column-gap 4m
+.nr bottom-margin 1m
+.
+.de 2c
+.  br
+.  mk
+.  ll \\n[column-length]u
+.  wh -\\n[bottom-margin]u 2c-trap
+.  nr right-side 0
+..
+.
+.de 2c-trap
+.  ie \\n[right-side] \{\
+.    nr right-side 0
+.    po -(\\n[column-length]u + \\n[column-gap]u)
+.    \" remove trap
+.    wh -\\n[bottom-margin]u
+.  \}
+.  el \{\
+.    \" switch to right side
+.    nr right-side 1
+.    po +(\\n[column-length]u + \\n[column-gap]u)
+.    rt
+.  \}
+..
+
+ +

Now let us apply our two-column macro. +

+
+
.pl 1.5i
+.ll 4i
+This is a small test that shows how the
+rt request works in combination with mk.
+
+.2c
+Starting here, text is typeset in two columns.
+Note that this implementation isn't robust
+and thus not suited for a real two-column
+macro.
+    ⇒ This is a small test that shows how the
+    ⇒ rt request works in combination with mk.
+    ⇒
+    ⇒ Starting  here,    isn't    robust
+    ⇒ text is typeset    and   thus  not
+    ⇒ in two columns.    suited  for   a
+    ⇒ Note that  this    real two-column
+    ⇒ implementation     macro.
+
+
+ +

Several escape sequences enable fine control of movement about the page. +

+
+
Escape sequence: \v'expr'
+
+ + +

Vertically move the drawing position. expr indicates the +magnitude of motion: positive is downward and and negative upward. The +default scaling unit is ‘v’. The motion is relative to the current +drawing position unless expr begins with the boundary-relative +motion operator ‘|’. See Numeric Expressions. +

+

Text processing continues at the new drawing position; usually, vertical +motions should be in balanced pairs to avoid a confusing page layout. +

+

\v will not spring a vertical position trap. This can be useful; +for example, consider a page bottom trap macro that prints a marker in +the margin to indicate continuation of a footnote. See Traps. +

+ +

A few escape sequences that produce vertical motion are unusual. They +are thought to originate early in AT&T nroff history to achieve +super- and subscripting by half-line motions on line printers and +teletypewriters before the phototypesetter made more precise positioning +available. They are reckoned in ems—not vees—to maintain continuity +with their original purpose of moving relative to the size of the type +rather than the distance between text baselines (vees).103 +

+
+
Escape sequence: \r
+
+
Escape sequence: \u
+
+
Escape sequence: \d
+
+

Move upward 1m, upward .5m, and +downward .5m, respectively. +

+ +

Let us see these escape sequences in use. +

+
+
Obtain 100 cm\u3\d of \ka\d\092\h'|\nau'\r233\dU.
+
+ +

In the foregoing we have paired \u and \d to typeset a +superscript, and later a full em negative (“reverse”) motion to place +a superscript above a subscript. A numeral-width horizontal motion +escape sequence aligns the proton and nucleon numbers, while \k +marks a horizontal position to which \h returns so that we could +stack them. (We shall discuss these horizontal motion escape sequences +presently.) In serious applications, we often want to alter the type +size of the -scripts and to fine-tune the vertical motions, as the +groff ms package does with its super- and subscripting +string definitions. +

+
+
Escape sequence: \h'expr'
+
+ + + + + +

Horizontally move the drawing position. expr indicates the +magnitude of motion: positive is rightward and negative leftward. The +default scaling unit is ‘m’. The motion is relative to the current +drawing position unless expr begins with the boundary-relative +motion operator ‘|’. See Numeric Expressions. +

+ +

The following string definition sets the TeX +logo.104 +

+
+
.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\"
+
+ +

There are a number of special-case escape sequences for horizontal +motion. +

+
+
Escape sequence: \SP
+
+ + + + +

Move right one word space. (The input is a backslash followed by a +space.) This escape sequence can be thought of as a non-adjustable, +unbreakable space. Usually you want \~ instead; see +Manipulating Filling and Adjustment. +

+ + + +
+
Escape sequence: \|
+
+

Move one-sixth em to the right on typesetting output devices. If +a glyph named ‘\|’ is defined in the current font, its width is +used instead, even on terminal output devices. +

+ + + +
+
Escape sequence: \^
+
+

Move one-twelfth em to the right on typesetting output devices. +If a glyph named ‘\^’ is defined in the current font, its width is +used instead, even on terminal output devices. +

+ +
+
Escape sequence: \0
+
+ + + + +

Move right by the width of a numeral in the current font. +

+ +

Horizontal motions are not discarded at the end of an output line as +word spaces are. See Breaking. +

+
+
Escape sequence: \w'anything'
+
+
Register: \n[st]
+
+
Register: \n[sb]
+
+
Register: \n[rst]
+
+
Register: \n[rsb]
+
+
Register: \n[ct]
+
+
Register: \n[ssc]
+
+
Register: \n[skw]
+
+ +

Interpolate the width of anything in basic units. This escape +sequence allows several properties of formatted output to be measured +without writing it out. +

+
+
The length of the string 'abc' is \w'abc'u.
+    ⇒ The length of the string 'abc' is 72u.
+
+ + + +

anything is processed in a dummy environment: this means that +font and type size changes, for example, may occur within it without +affecting subsequent output. +

+

After each use, \w sets several registers. +

+ + + +
+
st
+
sb
+

The maximum vertical displacements of the text baseline above and below, +respectively. The sign convention is opposite that of relative vertical +motions; that is, depth below the (original) baseline is negative. +These registers are incorrectly documented in the AT&T +troff manual as “the highest and lowest extent of [the argument +to \w] relative to the baseline”. +

+
+
rst
+
rsb
+

Like st and sb, but taking account of the heights and +depths of glyphs. In other words, these registers store the highest and +lowest vertical positions attained by anything, doing what +AT&T troff documented st and sb as doing. +

+
+
ct
+

Characterizes the geometry of glyphs occurring in anything. +

+
+
0
+

only short glyphs, no descenders or tall glyphs +

+
+
1
+

at least one descender +

+
+
2
+

at least one tall glyph +

+
+
3
+

at least one each of a descender and a tall glyph +

+
+ +
+
ssc
+

The amount of horizontal space (possibly negative) that should be added +to the last glyph before a subscript. +

+
+
skw
+

How far to right of the center of the last glyph in the \w +argument, the center of an accent from a roman font should be placed +over that glyph. +

+
+
+ +
+
Escape sequence: \kp
+
+
Escape sequence: \k(ps
+
Escape sequence: \k[position]
+
+ + + + +

Store the current horizontal position in the input line in a +register with the name position (one-character name p, +two-character name ps). Use this, for example, to return to the +beginning of a string for highlighting or other decoration. +

+ +
+
Register: \n[hp]
+
+ + + + +

The current horizontal position at the input line. +

+ +
+
Register: \n[.k]
+
+ + + + +

A read-only register containing the current horizontal output position +(relative to the current indentation). +

+ +
+
Escape sequence: \o'abc…'
+
+ + +

Overstrike the glyphs of characters a, b, c, …; +the glyphs are centered, written, and the drawing position advanced by +the widest of the glyphs. +

+ +
+
Escape sequence: \zc
+
+ + +

Format the character c with zero width; that is, without advancing +the drawing position. Use \z to overstrike glyphs aligned to +their left edges, in contrast to \o’s centering. +

+ +
+
Escape sequence: \Z'anything'
+
+ + +

Save the drawing position, format anything, then restore it. Tabs +and leaders in the argument are ignored with an error diagnostic. +

+

We might implement a strike-through macro thus. +

+
+
.de ST
+.nr width \w'\\$1'
+\Z@\v'-.25m'\l'\\n[width]u'@\\$1
+..
+.
+This is
+.ST "a test"
+an actual emergency!
+
+
+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.26 Drawing Geometric Objects

+ + + +

A few of the formatter’s escape sequences draw lines and other geometric +objects. Combined with each other and with page motion commands +(see Page Motions), a wide variety of figures is possible. For +complex drawings, these operations can be cumbersome; the preprocessors +gpic or ggrn are typically used instead. +

+

The \l and \L escape sequences draw horizontal and +vertical sequences of glyphs, respectively. Even the simplest of +output devices supports them. +

+
+
Escape sequence: \l'l'
+
+
Escape sequence: \l'lc'
+
+ + +

Draw a horizontal line of length l from the drawing position. +Rightward motion is positive. Afterward, the drawing position is at the +right end of the line. The default scaling unit is ‘m’. +

+ + + + +

The optional second parameter c is a character with which to +draw the line. The default is the baseline rule special character, +\[ru]. +

+ + +

If c is a valid scaling unit, put \& after l to +disambiguate the input. +

+
+
.de textbox
+\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
+..
+
+ +

The foregoing outputs a box rule (a vertical line), the text +argument(s), and another box rule. We employ the boundary-relative +motion operator ‘|’. Finally, the line-drawing escape sequences +draw a radical extender (a form of overline) and an underline from the +drawing position to the position coresponding to beginning of the +input line. The drawing position returns to just after the +right-hand box rule because the lengths of the drawn lines are negative, +as noted above. +

+ +
+
Escape sequence: \L'l'
+
+
Escape sequence: \L'lc'
+
+ + + + + + +

Draw a vertical line of length l from the drawing position. +Downward motion is positive. The default scaling unit is ‘v’. The +default character is the box rule, \[br]. As with vertical +motion escape sequences, text processing continues where the line ends. +\L is otherwise similar to \l. +

+
+
$ nroff <<EOF
+This is a \L'3v'test.
+EOF
+    ⇒ This is a
+    ⇒           |
+    ⇒           |
+    ⇒           |test.
+
+ +

When writing text, the drawing position is at the text baseline; recall +Page Geometry. +

+ +

The \D escape sequence provides drawing commands that +direct the output device to render geometrical objects rather than +glyphs. Specific devices may support only a subset, or may feature +additional ones; consult the man page for the output driver in use. +Terminal devices in particular implement almost none. See Graphics Commands. +

+

Rendering starts at the drawing position; when finished, the drawing +position is left at the rightmost point of the object, even for closed +figures, except where noted. GNU troff draws stroked (outlined) +objects with the stroke color, and shades filled ones with the fill +color. See Colors. Coordinates h and v are horizontal +and vertical motions relative to the drawing position or previous point +in the command. The default scaling unit for horizontal measurements +(and diameters of circles) is ‘m’; for vertical ones, ‘v’. +

+

Circles, ellipses, and polygons can be drawn filled or stroked. These +are independent properties; if you want a filled, stroked figure, you +must draw the same figure twice using each drawing command. A filled +figure is always smaller than an outlined one because the former is +drawn only within its defined area, whereas strokes have a line +thickness (set with ‘\D't'’). +

+
+
\h'1i'\v'1i'\
+\# increase line thickness
+\Z'\D't 5p''\
+\# draw stroked (unfilled) polygon
+\Z'\D'p 3 3 -6 0''\
+\# draw filled (solid) polygon
+\Z'\D'P 3 3 -6 0''
+
+ +
+
Escape sequence: \D'command argument …'
+
+

Drawing command escape sequence parameters begin with an ordinary +character, command, selecting the type of object to be drawn, +followed by arguments whose meaning is determined by +command. +

+
+
\D'~ h1 v1 … hn vn'
+
+

Draw a B-spline to each point in sequence, leaving the drawing position +at (hn, vn). +

+
+
\D'a hc vc h v'
+
+

Draw a circular arc centered at (hc, vc) counterclockwise +from the drawing position to a point (h, v) relative to the +center. 105 +

+
+
\D'c d'
+
+ + + + +

Draw a circle of diameter d with its leftmost point at the drawing +position. +

+
+
\D'C d'
+
+ + + + +

As ‘\D'C …'’, but the circle is filled. +

+
+
\D'e h v'
+
+ + + + +

Draw an ellipse of width h and height v with its leftmost +point at the drawing position. +

+
+
\D'E x y'
+
+ + + + +

As ‘\D'e …'’, but the ellipse is filled. +

+
+
\D'l dx dy'
+
+

Draw line from the drawing position to (h, v). +

+

The following is a macro for drawing a box around a text argument; for +simplicity, the box margin is a fixed at 0.2m. +

+
+
.de TEXTBOX
+.  nr @wd \w'\\$1'
+\h'.2m'\
+\h'-.2m'\v'(.2m - \\n[rsb]u)'\
+\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
+\D'l (\\n[@wd]u + .4m) 0'\
+\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
+\D'l -(\\n[@wd]u + .4m) 0'\
+\h'.2m'\v'-(.2m - \\n[rsb]u)'\
+\\$1\
+\h'.2m'
+..
+
+ +

The argument is measured with the \w escape sequence. Its width +is stored in register @wd. \w also sets the registers +rst and rsb; these contain its maximum vertical extents of +the argument. Then, four lines are drawn to form a box, offset by the +box margin. +

+
+
\D'p h1 v1 … hn vn'
+
+ + + + +

Draw polygon with vertices at drawing position and each point in +sequence. GNU troff closes the polygon by drawing a line from +(hn, vn) back to the initial drawing position. +Afterward, the drawing position is left at (hn, vn). +

+
+
\D'P dx1 dy1 dx2 dy2 …'
+
+ + + + +

As ‘\D'P …'’, but the polygon is filled. +

+

The following macro is like the ‘\D'l'’ example, but shades the +box. We draw the box before writing the text because colors in GNU +troff have no transparency; in othe opposite order, the filled +polygon would occlude the text. +

+
+
.de TEXTBOX
+.  nr @wd \w'\\$1'
+\h'.2m'\
+\h'-.2m'\v'(.2m - \\n[rsb]u)'\
+\M[lightcyan]\
+\D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
+     (\\n[@wd]u + .4m) 0 \
+     0 (\\n[rst]u - \\n[rsb]u + .4m) \
+     -(\\n[@wd]u + .4m) 0'\
+\h'.2m'\v'-(.2m - \\n[rsb]u)'\
+\M[]\
+\\$1\
+\h'.2m'
+..
+
+ +
+
\D't n'
+
+

Set the stroke thickness of geometric objects to n basic units. A +zero n selects the minimal supported thickness. A negative +n selects a thickness proportional to the type size; this is the +default. +

+
+
+ +

In a hazy penumbra between text rendering and drawing commands we locate +the bracket-building escape sequence, \b. It can assemble +apparently large glyphs by vertically stacking ordinary ones. +

+
+
Escape sequence: \b'contents'
+
+ + + +

Pile and center a sequence of glyphs vertically on the output line. +Piling stacks glyphs corresponding to each character in +contents, read from left to right, and placed from top to bottom. +GNU troff separates the glyphs vertically by 1m, and the +pile itself is centered 0.5m above the text baseline. The +horizontal drawing position is then advanced by the width of the widest +glyph in the pile. +

+ + +

This rather inflexible positioning algorithm doesn’t work with the +dvi output device since its bracket pieces vary in height. +Instead, use the geqn preprocessor. +

+

Manipulating Spacing describes how to adjust the vertical spacing +of the output line with the \x escape sequence. +

+

The application of \b that lends its name is construction of +brackets, braces, and parentheses when typesetting mathematics. We +might construct a large opening (left) brace as follows. +

+
+
\b'\[lt]\[bv]\[lk]\[bv]\[lb]'
+
+ +

See groff_char(7) for a list of special character +identifiers. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.27 Deferring Output

+ + + + + +

A few roff language elements are generally not used in simple +documents, but arise as page layouts become more sophisticated and +demanding. Environments collect formatting parameters like line +length and typeface. A diversion stores formatted output for +later use. A trap is a condition on the input or output, tested +automatically by the formatter, that is associated with a macro, causing +it to be called when that condition is fulfilled. +

+

Footnote support often exercises all three of the foregoing features. A +simple implementation might work as follows. A pair of macros is +defined: one starts a footnote and the other ends it. The author calls +the first macro where a footnote marker is desired. The macro +establishes a diversion so that the footnote text is collected at the +place in the body text where its corresponding marker appears. An +environment is created for the footnote so that it is set at a smaller +typeface. The footnote text is formatted in the diversion using that +environment, but it does not yet appear in the output. The document +author calls the footnote end macro, which returns to the previous +environment and ends the diversion. Later, after much more body text in +the document, a trap, set a small distance above the page bottom, is +sprung. The macro called by the trap draws a line across the page and +emits the stored diversion. Thus, the footnote is rendered. +

+

Diversions and traps make the text formatting process non-linear. Let +us imagine a set of text lines or paragraphs labelled ‘A’, +‘B’, and so on. If we set up a trap that produces text ‘T’ +(as a page footer, say), and we also use a diversion to store the +formatted text ‘D’, then a document with input text in the order +‘A B C D E F’ might render as ‘A B C E T F’. The diversion +‘D’ will never be output if we do not call for it. +

+

Environments of themselves are not a source of non-linearity in document +formatting: environment switches have immediate effect. One could +always write a macro to change as many formatting parameters as desired +with a single convenient call. But because diversions can be nested and +macros called by traps that are sprung by other trap-called macros, they +may be called upon in varying contexts. For example, consider a page +header that is always to be set in Helvetica. A document that uses +Times for most of its body text, but Courier for displayed code +examples, poses a challenge if a page break occurs in the middle of a +code display; if the header trap assumes that the “previous font” is +always Times, the rest of the example will be formatted in the wrong +typeface. One could carefully save all formatting parameters upon +entering the trap and restore them upon leaving it, but this is verbose, +error-prone, and not future-proof as the groff language develops. +Environments save us considerable effort. +

+ +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.28 Traps

+ + +

Traps are locations in the output or conditions on the input that, +when reached or fulfilled, call a specified macro. These traps can +occur at a given location on the page, at a given location in the +current diversion (together, these are known as vertical +position traps), at a blank line, at a line with leading space +characters, after a quantity of input lines, or at the end of input. +Macros called by traps are passed no arguments. + + +Setting a trap is also called planting one. + + +It is said that a trap is sprung if its condition is fulfilled. +

+ + + +
+
+
+

+Next: , Previous: , Up: Traps   [Contents][Index]

+
+

5.28.1 Vertical Position Traps

+ + + +

A vertical position trap calls a macro when the formatter’s +vertical drawing position reaches or passes, in the downward direction, +a certain location on the output page or in a diversion. Its +applications include setting page headers and footers, body text in +multiple columns, and footnotes. +

+
+
Request: .vpt [flag]
+
+
Register: \n[.vpt]
+
+ + + +

Enable vertical position traps if flag is non-zero or absent; +disable them otherwise. Vertical position traps are those set by the +wh request or by dt within a diversion. The parameter +that controls whether vertical position traps are enabled is global. +Initially, vertical position traps are enabled. The current value is +stored in the .vpt read-only register. +

+ + + + +

A page can’t be ejected if vpt is set to zero; see The Implicit Page Trap. +

+ + + + +
+
+
+

+Next: , Previous: , Up: Vertical Position Traps   [Contents][Index]

+
+

5.28.1.1 Page Location Traps

+ + + +

A page location trap is a vertical position trap that applies to +the page; that is, to undiverted output. Many can be present; manage +them with the wh and ch requests. +

+
+
Request: .wh dist [name]
+
+

Plant macro name as page location trap at dist. The default +scaling unit is ‘v’. Non-negative values for dist set the +trap relative to the top of the page; negative values set the trap +relative to the bottom of the page. It is not possible to plant a trap +less than one basic unit from the page bottom: a dist of -0 +is interpreted as 0, the top of the page.106 An existing visible trap (see below) at +dist is removed; this is wh’s sole function if name +is missing. +

+

A trap is sprung only if it is visible, meaning that its location +is reachable on the page107 and it +is not hidden by another trap at the same location already planted +there. +

+ + + + + + + + +

A macro package might set headers and footers as follows; this example +configures vertical margins of one inch to the body text, and one +half-inch to the titles. Observe the use of the no-break control +character with sp request to position our text baselines, +and the page number character ‘%’ used with the tl request. +

+
+
.\" hdfo.roff
+.de hd                  \" page header
+'  sp .5i
+'  tl '\\*(Ti''\\*(Da'  \" title and date strings
+'  sp .5i
+..
+.de fo                  \" page footer
+'  sp .5i
+.  tl ''%''
+.  bp
+..
+.wh 0   hd             \" trap at top of the page
+.wh -1i fo             \" trap 1 inch from bottom
+
+ +

To use these traps, copy the above (or load it from a file with the +so or mso requests), then set up the strings it uses. +

+
+
.so hdfo.roff
+.ds Ti Final Report\"
+.ds Da 21 May 2023\"
+.ti
+On 5 August of last year,
+this committee tasked me with the investigation of the
+CFIT (controlled flight into terrain) incident of
+.\" ...and so on...
+
+ +

A trap above the top or at or below the bottom of the page can be made +visible by either moving it into the page area or increasing the page +length so that the trap is on the page. Negative trap values always use +the current page length; they are not converted to an absolute +vertical position. + + +We can use the ptr request to dump our page location traps to the +standard error stream (see Debugging). Their positions are reported +in basic units; an nroff device example follows. +

+
+
.pl 5i
+.wh -1i xx
+.ptr
+    error→ xx      -240
+.pl 100i
+.ptr
+    error→ xx      -240
+
+ +

It is possible to have more than one trap at the same location (although +only one at a time can be visible); to achieve this, the traps must be +defined at different locations, then moved to the same place with the +ch request. In the following example, the many empty lines +caused by the bp request are not shown in the output. +

+
+
.de a
+.  nop a
+..
+.de b
+.  nop b
+..
+.de c
+.  nop c
+..
+.
+.wh 1i a
+.wh 2i b
+.wh 3i c
+.bp
+    ⇒ a b c
+
+
+
.ch b 1i
+.ch c 1i
+.bp
+    ⇒ a
+
+
+
.ch a 0.5i
+.bp
+    ⇒ a b
+
+
+ +
+
Register: \n[.t]
+
+ + +

The read-only register .t holds the distance to the next vertical +position trap. If there are no traps between the current position and +the bottom of the page, it contains the distance to the page bottom. +Within a diversion, in the absence of a diversion trap, this distance is +the largest representable integer in basic units—effectively infinite. +

+ +
+
Request: .ch name [dist]
+
+ + +

Change the location of a trap by moving macro name to new location +dist, or by unplanting it altogether if dist is absent. The +default scaling unit is ‘v’. Parameters to ch are specified +in the opposite order from wh. If name is the earliest +planted macro of multiple traps at the same location, (re)moving it from +that location exposes the macro next least recently planted at the same +place.108 +

+

Changing a trap’s location is useful for building up footnotes in a +diversion to allow more space at the bottom of the page for them. +

+ +
+ +

The same macro can be installed simultaneously at multiple locations; +however, only the earliest-planted instance—that has not yet been +deleted with wh—will be moved by ch. The following +example (using an nroff device) illustrates this behavior. Blank +lines have been elided from the output. +

+
+
.de T
+Trap sprung at \\n(nlu.
+.br
+..
+.wh 1i T
+.wh 2i T
+foo
+.sp 11i
+.bp
+.ch T 4i
+bar
+.sp 11i
+.bp
+.ch T 5i
+baz
+.sp 11i
+.bp
+.wh 5i
+.ch T 6i
+qux
+.sp 11i
+
+
+
    ⇒ foo
+    ⇒ Trap sprung at 240u.
+    ⇒ Trap sprung at 480u.
+    ⇒ bar
+    ⇒ Trap sprung at 480u.
+    ⇒ Trap sprung at 960u.
+    ⇒ baz
+    ⇒ Trap sprung at 480u.
+    ⇒ Trap sprung at 1200u.
+    ⇒ qux
+    ⇒ Trap sprung at 1440u.
+
+ +
+
Register: \n[.ne]
+
+

The read-only register .ne contains the amount of space that was +needed in the last ne request that caused a trap to be sprung; +it is useful in conjunction with the .trunc register. See Page Control. Since the .ne register is set only by traps, it +doesn’t make sense to interpolate it outside of macros called by traps. +

+ +
+
Register: \n[.trunc]
+
+ + +

A read-only register containing the amount of vertical space truncated +from an sp request by the most recently sprung vertical +position trap, or, if the trap was sprung by an ne request, +minus the amount of vertical motion produced by the ne +request. In other words, at the point a trap is sprung, it +represents the difference of what the vertical position would have +been but for the trap, and what the vertical position actually is. +Since the .trunc register is set only by traps, it doesn’t make +sense to interpolate it outside of macros called by traps. +

+ +
+
Register: \n[.pe]
+
+ + + +

This Boolean-valued, read-only register interpolates 1 while a page +is being ejected, and 0 otherwise. +

+

In the following example, we plant the same trap at the top and the +bottom of the page. We also make the trap report its name and the +vertical drawing position. +

+
+
.de T
+.tm \\$0: page \\n%, nl=\\n[nl] .pe=\\n[.pe]
+..
+.ll 46n
+.wh 0 T
+.wh -1v T
+Those who can make you believe absurdities can make you
+commit atrocities. \[em] Voltaire
+    error→ T: page 1, nl=0 .pe=0
+    error→ T: page 1, nl=2600 .pe=1
+    ⇒ Those who can make you believe absurdities can
+    ⇒ make you commit atrocities. -- Voltaire
+
+
+ + + +

When designing macros, keep in mind that diversions and traps do +normally interact. For example, if a trap calls a header macro (while +outputting a diversion) that tries to change the font on the current +page, the effect is not visible before the diversion has completely been +printed (except for input protected with \! or \?) since +the data in the diversion is already formatted. In most cases, this is +not the expected behaviour. +

+ +
+
+
+
+

+Next: , Previous: , Up: Vertical Position Traps   [Contents][Index]

+
+

5.28.1.2 The Implicit Page Trap

+ + + + + + + +

If, after starting GNU troff without loading a macro package, you +use the ptr request to dump a list of the active traps to the +standard error stream,109 nothing is reported. +Yet the .t register will report a steadily decreasing value with +every output line your document produces, and once the value of +.t gets to within .V of zero, you will notice that +something trap-like happens—the page is ejected, a new one begins, and +the value of .t becomes large once more. +

+

This implicit page trap always exists in the top-level +diversion;110 it works like a trap in some +ways but not others. Its purpose is to eject the current page and start +the next one. It has no name, so it cannot be moved or deleted with +wh or ch requests. You cannot hide it by placing another +trap at its location, and can move it only by redefining the page length +with pl. Its operation is suppressed when vertical page traps +are disabled with GNU troff’s vpt request. +

+ +
+
+
+
+

+Next: , Previous: , Up: Vertical Position Traps   [Contents][Index]

+
+

5.28.1.3 Diversion Traps

+ + + +

A diversion is not formatted in the context of a page, so it lacks page +location traps; instead it can have a diversion trap. There can +exist at most one such vertical position trap per diversion. +

+
+
Request: .dt [dist name]
+
+ + + + +

Set a trap within a diversion at location dist, which is +interpreted relative to diversion rather than page boundaries. If invoked with +fewer than two arguments, any diversion trap in the current diversion is +removed. The register .t works within diversions. It is an +error to invoke dt in the top-level diversion. +See Diversions. +

+ + +
+
+
+
+
+

+Next: , Previous: , Up: Traps   [Contents][Index]

+
+

5.28.2 Input Line Traps

+ + + +
+
Request: .it [n name]
+
+
Request: .itc [n name]
+
+ + + + + + +

Set an input line trap, calling macro name after processing the +next n productive input lines (recall Manipulating Filling and Adjustment). Any existing input line trap in the +environment is replaced. Without arguments, it and itc +clear any input line trap that has not yet sprung. +

+

Consider a macro ‘.ST s n’ which sets the next +n input lines in the font style s. +

+
+
.de ST \" Use style $1 for next $2 text lines.
+.  it \\$2 ES
+.  ft \\$1
+..
+.de ES \" end ST
+.  ft R
+..
+.ST I 1
+oblique
+face
+.ST I 1
+oblique\c
+face
+    ⇒ oblique face obliqueface  (second “face” upright)
+
+ + + + + +

Unlike the ce and rj requests, it counts lines +interrupted with the \c escape sequence separately (see Line Continuation); itc does not. To see the difference, let’s +change the previous example to use itc instead. +

+
+
…
+.  itc \\$2 ES
+…
+    ⇒ oblique face obliqueface  (second “face” oblique)
+
+ +

You can think of the ce and rj requests as implicitly +creating an input line trap with itc that schedules a break when +the trap is sprung. +

+
+
.de BR
+.  br
+.  internal: disable centering-without-filling
+..
+.
+.de ce
+.  if \\n[.br] .br
+.  itc \\$1 BR
+.  internal: enable centering-without-filling
+..
+
+ +

Let us consider in more detail the sorts of input lines that are or are +not “productive”. +

+
+
.de Trap
+TRAP SPRUNG
+..
+.de Mac
+.if r a \l'5n'
+..
+.it 2 Trap
+.
+foo
+.Mac
+bar
+baz
+.it 1 Trap
+.sp \" moves, but does not write or draw
+qux
+.itc 1 Trap
+\h'5n'\c \" moves, but does not write or draw
+jat
+
+ +

When ‘Trap’ gets called depends on whether the ‘a’ register is +defined; the control line with the if request may or may not +produce written output. We also see that the spacing request sp, +while certainly affecting the output, does not spring the input line +trap. Similarly, the horizontal motion escape sequence \h also +affected the output, but was not “written”. Observe that we had to +follow it with \c and use itc to prevent the newline at +the end of the text line from causing a word break, which, like an +ordinary space character, counts as written output. +

+
+
$ groff -Tascii input-trap-example.groff
+    ⇒ foo bar TRAP SPRUNG baz
+    ⇒
+    ⇒ qux TRAP SPRUNG      jat TRAP SPRUNG
+$ groff -Tascii -ra1 input-trap-example.groff
+    ⇒ foo _____ TRAP SPRUNG bar baz
+    ⇒
+    ⇒ qux TRAP SPRUNG      jat TRAP SPRUNG
+
+
+ +

Input line traps are associated with the environment +(see Environments); switching to another environment suspends the +current input line trap, and going back resumes it, restoring the count +of qualifying lines enumerated in that environment. +

+ +
+
+
+
+

+Next: , Previous: , Up: Traps   [Contents][Index]

+
+

5.28.3 Blank Line Traps

+ + + +
+
Request: .blm [name]
+
+ +

Set a blank line trap, calling the macro name when GNU +troff encounters a blank line in an input file, instead of the +usual behavior (see Breaking). A line consisting only of spaces is +also treated as blank and subject to this trap. If no argument is +supplied, the default blank line behavior is (re-)established. +

+ + +
+
+
+
+

+Next: , Previous: , Up: Traps   [Contents][Index]

+
+

5.28.4 Leading Space Traps

+ + + +
+
Request: .lsm [name]
+
+
Register: \n[lsn]
+
+
Register: \n[lss]
+
+ +

Set a leading space trap, calling the macro name when GNU +troff encounters leading spaces in an input line; the implicit +line break that normally happens in this case is suppressed. If no +argument is supplied, the default leading space behavior is +(re-)established (see Breaking). +

+

The count of leading spaces on an input line is stored in register +lsn, and the amount of corresponding horizontal motion in +register lss, irrespective of whether a leading space trap is +set. When it is, the leading spaces are removed from the input line, +and no motion is produced before calling name. +

+
+ + +
+
+
+
+

+Previous: , Up: Traps   [Contents][Index]

+
+

5.28.5 End-of-input Traps

+ + + +
+
Request: .em [name]
+
+ + + + + +

Set a trap at the end of input, calling macro name after the last +line of the last input file has been processed. If no argument is +given, any existing end-of-input trap is removed. +

+

For example, if the document had to have a section at the bottom of the +last page for someone to approve it, the em request could be +used. +

+
+
.de approval
+\c
+.  ne 3v
+.  sp (\\n[.t]u - 3v)
+.  in +4i
+.  lc _
+.  br
+Approved:\t\a
+.  sp
+Date:\t\t\a
+..
+.
+.em approval
+
+ +

The \c in the above example needs explanation. For historical +reasons (compatibility with AT&T troff), the +end-of-input macro exits as soon as it causes a page break if no +partially collected line remains.111 +

+ + + + +

Let us assume that there is no \c in the above approval +macro, that the page is full, and last output line has been broken with, +say, a br request. Because there is no more room, a ne +request at this point causes a page ejection, which in turn makes +troff exit immediately as just described. In most situations, +this is not desired; people generally want to format the input after +ne. +

+

To force processing of the whole end-of-input macro independently of +this behavior, it is thus advisable to (invisibly) ensure the existence +of a partially collected line (\c) whenever there is a chance +that a page break can happen. In the above example, invoking the +ne request ensures that there is room for the subsequent +formatted output on the same page, so we need insert \c only +once. +

+

The next example shows how to append three lines, then start a new page +unconditionally. Since ‘.ne 1’ doesn’t give the desired +effect—there is always one line available or we are already at the +beginning of the next page—we temporarily increase the page length by +one line so that we can use ‘.ne 2’. +

+
+
.de EM
+.pl +1v
+\c
+.ne 2
+line one
+.br
+\c
+.ne 2
+line two
+.br
+\c
+.ne 2
+line three
+.br
+.pl -1v
+\c
+'bp
+..
+.em EM
+
+ +

This specific feature affects only the first potential page break caused +by the end-of-input macro; further page breaks emitted by the macro are +handled normally. +

+

Another possible use of the em request is to make GNU +troff emit a single large page instead of multiple pages. For +example, one may want to produce a long plain text file for reading +in a terminal or emulator without page footers and headers interrupting +the body of the document. One approach is to set the page length at the +beginning of the document to a very large value to hold all the +text,112 and +automatically adjust it to the exact height of the document after the +text has been output. +

+
+
.de adjust-page-length
+.  br
+.  pl \\n[nl]u \" \n[nl]: current vertical position
+..
+.
+.de single-page-mode
+.  pl 99999
+.  em adjust-page-length
+..
+.
+.\" Activate the above code if configured.
+.if \n[do-continuous-rendering] \
+.  single-page-mode
+
+ +

Since only one end-of-input trap exists and another macro package may +already use it, care must be taken not to break the mechanism. A simple +solution would be to append the above macro to the macro package’s +end-of-input macro using the am request. +

+ + + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.29 Diversions

+ + +

In roff systems it is possible to format text as if for output, +but instead of writing it immediately, one can divert the +formatted text into a named storage area. It is retrieved later by +specifying its name after a control character. The same name space is +used for such diversions as for strings and macros; see +Identifiers. Such text is sometimes said to be “stored in a +macro”, but this coinage obscures the important distinction between +macros and strings on one hand and diversions on the other; the former +store unformatted input text, and the latter capture +formatted output. Diversions also do not interpret arguments. +Applications of diversions include “keeps” (preventing a page break +from occurring at an inconvenient place by forcing a set of output lines +to be set as a group), footnotes, tables of contents, and indices. + + +For orthogonality it is said that GNU troff is in the +top-level diversion if no diversion is active (that is, formatted +output is being “diverted” immediately to the output device). +

+

Dereferencing an undefined diversion will create an empty one of that +name and cause a warning in category ‘mac’ to be emitted. +See Warnings, for information about the enablement and suppression of +warnings. A diversion does not exist for the purpose of testing with +the d conditional operator until its initial definition ends +(see Operators in Conditionals). The following requests are used to +create and alter diversions. +

+
+
Request: .di [name]
+
+
Request: .da [name]
+
+ + + + + + +

Start collecting formatted output in a diversion called name. The +da request appends to a diversion called name, creating it +if necessary. If name already exists as an alias, the target of +the alias is replaced or appended to; recall Strings. The pending +output line is diverted as well. Switching to another environment (with +the ev request) before invoking di or da avoids +including any pending output line in the diversion; see +Environments. +

+

Invoking di or da without an argument stops diverting +output to the diversion named by the most recent corresponding request. +If di or da is called without an argument when there is no +current diversion, a warning in category ‘di’ is produced. +See Warnings, for information about the enablement and suppression +of warnings. +

+
+
Before the diversion.
+.di yyy
+In the diversion.
+.br
+.di
+After the diversion.
+.br
+    ⇒ After the diversion.
+.yyy
+    ⇒ Before the diversion.  In the diversion.
+
+
+ + +

GNU troff supports box requests to exclude a partially +collected line from a diversion, as this is often desirable. +

+
+
Request: .box [name]
+
+
Request: .boxa [name]
+
+

Divert (or append) output to name, similarly to the di and +da requests, respectively. Any pending output line is not +included in the diversion. Without an argument, stop diverting output; +any pending output line inside the diversion is discarded. +

+
+
Before the box.
+.box xxx
+In the box.
+.br
+Hidden treasure.
+.box
+After the box.
+.br
+    ⇒ Before the box.  After the box.
+.xxx
+    ⇒ In the box.
+
+
+ +

Apart from pending output line inclusion and the request names that +populate them, boxes are handled exactly as diversions are. All of the +following groff language elements can be used with them +interchangeably. +

+
+
Register: \n[.z]
+
+
Register: \n[.d]
+
+ + + + + + + +

Diversions may be nested. The read-only string-valued register +.z contains the name of the current diversion. The read-only +register .d contains the current vertical place in the diversion. +If the input text is not being diverted, .d reports the same +location as the register nl. +

+ +
+
Register: \n[.h]
+
+ + + + +

The read-only register .h stores the high-water mark on the +current page or in the current diversion. It corresponds to the text +baseline of the lowest line on the page.113 +

+
+
.tm .h==\n[.h], nl==\n[nl]
+    ⇒ .h==0, nl==-1
+This is a test.
+.br
+.sp 2
+.tm .h==\n[.h], nl==\n[nl]
+    ⇒ .h==40, nl==120
+
+ + + +

As implied by the example, vertical motion does not produce text +baselines and thus does not increase the value interpolated by +‘\n[.h]’. +

+ +
+
Register: \n[dn]
+
+
Register: \n[dl]
+
+ + + + +

After completing a diversion, the writable registers dn and +dl contain its vertical and horizontal sizes. Only the lines +just processed are counted: for the computation of dn and +dl, the requests da and boxa are handled as if +di and box had been used, respectively—lines that have +been already stored in the diversion (box) are not taken into account. +

+
+
.\" Center text both horizontally and vertically.
+.\" Macro .(c starts centering mode; .)c terminates it.
+.
+.\" Disable the escape character with .eo so that we
+.\" don't have to double backslashes on the "\n"s.
+.eo
+.de (c
+.  br
+.  ev (c
+.  evc 0
+.  in 0
+.  nf
+.  di @c
+..
+
+
+
.de )c
+.  br
+.  ev
+.  di
+.  nr @s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
+.  sp \n[@s]u
+.  ce 1000
+.  @c
+.  ce 0
+.  sp \n[@s]u
+.  br
+.  fi
+.  rr @s
+.  rm @c
+..
+.ec
+
+
+ +
+
Escape sequence: \!anything
+
+
Escape sequence: \?anything\?
+
+ + +

Transparently embed anything into the current diversion, +preventing requests, macro calls, and escape sequences from being +interpreted when read into a diversion. This is useful for preventing +them from taking effect until the diverted text is actually output. The +\! escape sequence transparently embeds input up to and including +the end of the line. The \? escape sequence transparently embeds +input until its own next occurrence. +

+ + + + + + +

anything may not contain newlines; use \! by itself to +embed newlines in a diversion. The escape sequence \? is also +recognized in copy mode and turned into a single internal code; it is +this code that terminates anything. Thus the following example +prints 4. +

+
+
.nr x 1
+.nf
+.di d
+\?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
+.di
+.nr x 2
+.di e
+.d
+.di
+.nr x 3
+.di f
+.e
+.di
+.nr x 4
+.f
+
+ +

Both escape sequences read the data in copy mode. +

+ + + +

If \! is used in the top-level diversion, its argument is +directly embedded into GNU troff’s intermediate output. This can +be used, for example, to control a postprocessor that processes the data +before it is sent to an output driver. +

+ + + +

The \? escape used in the top-level diversion produces no output +at all; its argument is simply ignored. +

+ + + + + + +
+
Request: .output contents
+
+

Emit contents directly to GNU troff’s intermediate output +(subject to copy mode interpretation); this is similar to \! used +at the top level. An initial neutral double quote in contents is +stripped to allow embedding of leading spaces. +

+

This request can’t be used before the first page has started—if you +get an error, simply insert .br before the output request. +

+

Use with caution! It is normally only needed for mark-up used by a +postprocessor that does something with the output before sending it to +the output device, filtering out contents again. +

+ +
+
Request: .asciify div
+
+ + + +

Unformat the diversion div in a way such that Unicode basic +Latin (ASCII) characters, characters translated with the +trin request, space characters, and some escape sequences, that +were formatted and diverted into div are treated like ordinary +input characters when div is reread. Doing so can be useful in +conjunction with the writem request. asciify can be also +used for gross hacks; for example, the following sets +register n to 1. +

+
+
.tr @.
+.di x
+@nr n 1
+.br
+.di
+.tr @@
+.asciify x
+.x
+
+ +

asciify cannot return all items in a diversion to their source +equivalent: nodes such as those produced by the \N escape +sequence will remain nodes, so the result cannot be guaranteed to be a +pure string. See Copy Mode. Glyph parameters such as the type face +and size are not preserved; use unformat to achieve that. +

+ +
+
Request: .unformat div
+
+

Like asciify, unformat the diversion div. However, +unformat handles only tabs and spaces between words, the latter +usually arising from spaces or newlines in the input. Tabs are treated +as input tokens, and spaces become adjustable again. The vertical sizes +of lines are not preserved, but glyph information (font, type size, +space width, and so on) is retained. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.30 Punning Names

+ + +

Macros, strings, and diversions share a name space; recall +Identifiers. Internally, the same mechanism is used to store +them. You can thus call a macro with string interpolation syntax and +vice versa. +

+
+
.de subject
+Typesetting
+..
+.de predicate
+rewards attention to detail
+..
+\*[subject] \*[predicate].
+Truly.
+    ⇒ Typesetting
+    ⇒  rewards attention to detail Truly.
+
+ +

What went wrong? Strings don’t contain newlines, but macros do. String +interpolation placed a newline at the end of ‘\*[subject]’, and the +next thing on the input was a space. Then when ‘\*[predicate]’ was +interpolated, it was followed by the empty request ‘.’ on a line by +itself. If we want to use macros as strings, we must take interpolation +behavior into account. +

+
+
.de subject
+Typesetting\\
+..
+.de predicate
+rewards attention to detail\\
+..
+\*[subject] \*[predicate].
+Truly.
+    ⇒ Typesetting rewards attention to detail.  Truly.
+
+ +

By ending each text line of the macros with an escaped +\RET, we get the desired effect (see Line Continuation).114 +What would have happened if we had used only one backslash at a time +instead? +

+

Interpolating a string does not hide existing macro arguments. We can +also place the escaped newline outside the string interpolation instead +of within the string definition. Thus, in a macro, a more efficient way +of doing +

+
+
.xx \\$@
+
+ +

is +

+
+
\\*[xx]\\
+
+ +

The latter calling syntax doesn’t change the value of \$0, which +is then inherited from the calling macro (see Parameters). +

+

Diversions can be also called with string syntax. It is sometimes +convenient to copy one-line diversions to a string. +

+
+
.di xx
+the
+.ft I
+interpolation system
+.ft
+.br
+.di
+.ds yy This is a test of \*(xx\c
+\*(yy.
+    ⇒ This is a test of the interpolation system.
+
+ +

As the previous example shows, it is possible to store formatted output +in strings. The \c escape sequence prevents the subsequent +newline from being interpreted as a break (again, +see Line Continuation). +

+

Copying multi-output line diversions produces unexpected results. +

+
+
.di xxx
+a funny
+.br
+test
+.br
+.di
+.ds yyy This is \*[xxx]\c
+\*[yyy].
+    ⇒ test This is a funny.
+
+ +

Usually, it is not predictable whether a diversion contains one or more +output lines, so this mechanism should be avoided. With AT&T +troff, this was the only solution to strip off a final newline +from a diversion. Another disadvantage is that the spaces in the copied +string are already formatted, preventing their adjustment. This can +cause ugly results. +

+ + + + + + + +

A clean solution to this problem is available in GNU troff, using +the requests chop to remove the final newline of a diversion, and +unformat to make the horizontal spaces adjustable again. +

+
+
.box xxx
+a funny
+.br
+test
+.br
+.box
+.chop xxx
+.unformat xxx
+This is \*[xxx].
+    ⇒ This is a funny test.
+
+ +

See gtroff Internals. +

+ +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.31 Environments

+ + +

As discussed in Deferring Output, environments store most of the +parameters that determine the appearance of text. A default environment +named ‘0’ exists when GNU troff starts up; it is modified by +formatting-related requests and escape sequences. +

+ +

You can create new environments and switch among them. Only one is +current at any given time. Active environments are managed using a +stack, a data structure supporting “push” and “pop” +operations. The current environment is at the top of the stack. +The same environment name can be pushed onto the stack multiple times, +possibly interleaved with others. Popping the environment stack does +not destroy the current environment; it remains accessible by name and +can be made current again by pushing it at any time. Environments +cannot be renamed or deleted, and can only be modified when current. To +inspect the environment stack, use the pev request; see +Debugging. +

+

Environments store the following information. +

+
    +
  • a partially collected line, if any + +
  • data about the most recently output glyph and line (registers +.cdp, .cht, .csk, .n, .w) + +
  • typeface parameters (size, family, style, height and slant, inter-word +and inter-sentence space sizes) + +
  • page parameters (line length, title length, vertical spacing, line +spacing, indentation, line numbering, centering, right-alignment, +underlining, hyphenation parameters) + +
  • filling enablement; adjustment enablement and mode + +
  • tab stops; tab, leader, escape, control, no-break control, hyphenation, +and margin characters + +
  • input line traps + +
  • stroke and fill colors +
+ +
+
Request: .ev [ident]
+
+
Register: \n[.ev]
+
+ + + +

Enter the environment ident, which is created if it does not +already exist, using the same parameters as for the default environment +used at startup. With no argument, GNU troff switches to the +previous environment. +

+

Invoking ev with an argument puts environment ident onto +the top of the environment stack. (If it isn’t already present in the +stack, this is a proper push.) Without an argument, ev pops the +environment stack, making the previous environment current. It is an +error to pop the environment stack with no previous environment +available. The read-only string-valued register .ev contains the +name of the current environment—the one at the top of the stack. +

+
+
.ev footnote-env
+.fam N
+.ps 6
+.vs 8
+.ll -.5i
+.ev
+
+…
+
+.ev footnote-env
+\[dg] Observe the smaller text and vertical spacing.
+.ev
+
+ +

We can familiarize ourselves with stack behavior by wrapping the +ev request with a macro that reports the contents of the +.ev register to the standard error stream. +

+
+
.de EV
+.  ev \\$1
+.  tm environment is now \\n[.ev]
+..
+.
+.EV foo
+.EV bar
+.EV
+.EV baz
+.EV
+.EV
+.EV
+
+ +
+
    error→ environment is now foo
+    error→ environment is now bar
+    error→ environment is now foo
+    error→ environment is now baz
+    error→ environment is now foo
+    error→ environment is now 0
+    error→ error: environment stack underflow
+    error→ environment is now 0
+
+ +
+ +
+
Request: .evc environment
+
+ + +

Copy the contents of environment to the current environment. +

+

The following environment data are not copied. +

+
    +
  • a partially collected line, if present; + +
  • the interruption status of the previous input line (due to use of the +\c escape sequence); + +
  • the count of remaining lines to center, to right-justify, or to +underline (with or without underlined spaces)—these are set to zero; + +
  • the activation status of temporary indentation; + +
  • input line traps and their associated data; + +
  • the activation status of line numbering (which can be reactivated with +‘.nm +0’); and + +
  • the count of consecutive hyphenated lines (set to zero). +
+
+ +
+
Register: \n[.w]
+
+
Register: \n[.cht]
+
+
Register: \n[.cdp]
+
+
Register: \n[.csk]
+
+ + + + + + + +

The \n[.w] register contains the width of the last glyph +formatted in the environment. +

+

The \n[.cht] register contains the height of the last glyph +formatted in the environment. +

+

The \n[.cdp] register contains the depth of the last glyph +formatted in the environment. It is positive for glyphs extending below +the baseline. +

+

The \n[.csk] register contains the skew (how far to the +right of the glyph’s center that GNU troff should place an +accent) of the last glyph formatted in the environment. +

+ +
+
Register: \n[.n]
+
+ + + + +

The \n[.n] register contains the length of the previous output +line emitted in the environment. +

+ + + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.32 Suppressing Output

+ +
+
Escape sequence: \O[num]
+
+ + +

Suppress GNU troff output of glyphs and geometric objects. The +sequences \O2, \O3, \O4, and \O5 are +intended for internal use by grohtml. +

+
+
‘\O0’
+

Disable the emission of glyphs and geometric objects to the output +driver, provided that this sequence occurs at the outermost suppression +level (see \O3 and \04 below). Horizontal motions +corresponding to non-overstruck glyph widths still occur. +

+
+
‘\O1’
+

Enable the emission of glyphs and geometric objects to the output +driver, provided that this sequence occurs at the outermost suppression +level. +

+
+ + + + + +

\O0 and \O1 also reset the four registers opminx, +opminy, opmaxx, and opmaxy to −1. These +four registers mark the top left and bottom right hand corners of a box +encompassing all written or drawn output. +

+
+
‘\O2’
+

At the outermost suppression level, enable emission of glyphs and +geometric objects, and write to the standard error stream the page +number and values of the four aforementioned registers encompassing +glyphs written since the last interpolation of a \O sequence, as +well as the page offset, line length, image file name (if any), +horizontal and vertical device motion quanta, and input file name. +Numeric values are in basic units. +

+
+
‘\O3’
+

Begin a nested suppression level. grohtml uses this mechanism +to create images of output preprocessed with gpic, +geqn, and gtbl. At startup, GNU troff is at +the outermost suppression level. pre-grohtml generates these +sequences when processing the document, using GNU troff with +the ps output device, Ghostscript, and the PNM tools to produce +images in PNG format. They start a new page if the device is not +html or xhtml, to reduce the number of images crossing a +page boundary. +

+
+
‘\O4’
+

End a nested suppression level. +

+
+ +
+
‘\O[5Pfile]’
+

At the outermost suppression level, write the name file to the +standard error stream at position P, which must be one of +l, r, c, or i, corresponding to left, +right, centered, and inline alignments within the document, +respectively. file is a name associated with the production of +the next image. +

+
+
+ +
+
Register: \n[.O]
+
+ + + +

Output suppression nesting level applied by \O3 and \O4 +escape sequences. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.33 I/O

+ + + + + +

gtroff has several requests for including files: +

+
+
Request: .so file
+
+
Request: .soquiet file
+
+ + +

Replace the so request’s control line with the contents of the +file named by the argument, “sourcing” it. file is sought in +the directories specified by -I command-line option. If +file does not exist, a warning in category ‘file’ is produced +and the request has no further effect. See Warnings, for +information about the enablement and suppression of warnings. +

+

so can be useful for large documents; e.g., allowing each chapter +of a book to be kept in a separate file. However, files interpolated +with so are not preprocessed; to overcome this limitation, see +the gsoelim(1) man page. +

+

Since GNU troff replaces the entire control line with the +contents of a file, it matters whether file is terminated with a +newline or not. Assume that file xxx contains only the word +‘foo’ without a trailing newline. +

+
+
$ printf 'foo' > xxx
+
+The situation is
+.so xxx
+bar.
+    ⇒ The situation is foobar.
+
+ +

soquiet works the same way, except that no warning diagnostic is +issued if file does not exist. +

+ +
+
Request: .pso command
+
+

Read the standard output from the specified command and include +it in place of the pso request. +

+ + + + +

It is an error to use this request in safer mode, which is the +default. Invoke GNU troff or a front end with the -U +option to enable unsafe mode. +

+

The comment regarding a final newline for the so request is valid +for pso also. +

+ +
+
Request: .mso file
+
+
Request: .msoquiet file
+
+

Identical to the so and soquiet requests, respectively, +except that gtroff searches for the specified file in the +same directories as macro files for the -m command-line option. +If the file name to be included has the form name.tmac and +it isn’t found, these requests try to include tmac.name and +vice versa. +

+ +
+
Request: .trf file
+
+
Request: .cf file
+
+ + + + + + + + +

Transparently output the contents of file. Each line is output as +if it were preceded by \!; however, the lines are not +subject to copy mode interpretation. If the file does not end with a +newline, trf adds one. Both requests cause a break. +

+

When used in a diversion, these requests embed a node (see gtroff Internals) in it that, when reread, causes the contents of file +to be transparently copied to the output. In AT&T +troff, the contents of file are immediately copied to the +output regardless of whether there is a current diversion; this +behaviour is so anomalous that it must be considered a bug. +

+ + + +

While cf copies the contents of file completely +unprocessed, trf disallows characters such as NUL that are not +valid gtroff input characters (see Identifiers). +

+

For cf, within a diversion, “completely unprocessed” means that +each line of a file to be inserted is handled as if it were preceded by +\!\\!. +

+

To define a macro x containing the contents of +file f, use +

+
+
.ev 1
+.di x
+.trf f
+.di
+.ev
+
+ +

The calls to ev prevent the partially collected output line +from becoming part of the diversion (see Diversions). +

+ +
+
Request: .nx [file]
+
+ + + +

Force gtroff to continue processing of the file specified as an +argument. If no argument is given, immediately jump to the end of file. +

+ +
+
Request: .rd [prompt [arg1 arg2 …]]
+
+ + + +

Read from standard input, and include what is read as though it were +part of the input file. Text is read until a blank line is encountered. +

+

If standard input is a TTY input device (keyboard), write prompt +to standard error, followed by a colon (or send BEL for a beep if no +argument is given). +

+

Arguments after prompt are available for the input. For example, +the line +

+
+
.rd data foo bar
+
+ +

with the input ‘This is \$2.’ prints +

+
+
This is bar.
+
+
+ + + +

Using the nx and rd requests, it is easy to set up form +letters. The form letter template is constructed like this, putting the +following lines into a file called repeat.let: +

+
+
.ce
+\*(td
+.sp 2
+.nf
+.rd
+.sp
+.rd
+.fi
+Body of letter.
+.bp
+.nx repeat.let
+
+ + +

When this is run, a file containing the following lines should be +redirected in. Requests included in this file are executed as though +they were part of the form letter. The last block of input is the +ex request, which tells GNU troff to stop processing. If +this were not there, troff would not know when to stop. +

+
+
Trent A. Fisher
+708 NW 19th Av., #202
+Portland, OR  97209
+
+Dear Trent,
+
+Len Adollar
+4315 Sierra Vista
+San Diego, CA  92103
+
+Dear Mr. Adollar,
+
+.ex
+
+ +
+
Request: .pi pipe
+
+

Pipe the output of gtroff to the shell command(s) specified by +pipe. This request must occur before gtroff has a chance +to print anything. +

+ + + + +

It is an error to use this request in safer mode, which is the +default. Invoke GNU troff or a front end with the -U +option to enable unsafe mode. +

+

Multiple calls to pi are allowed, acting as a chain. For +example, +

+
+
.pi foo
+.pi bar
+...
+
+ +

is the same as ‘.pi foo | bar’. +

+ + +

The intermediate output format of GNU troff is piped to the +specified commands. Consequently, calling groff without the +-Z option normally causes a fatal error. +

+ + + +
+
Request: .sy cmds
+
+
Register: \n[systat]
+
+

Execute the shell command(s) specified by cmds. The output is not +saved anywhere, so it is up to the user to do so. +

+ + + + +

It is an error to use this request in safer mode; this is the default. +Give GNU troff or a front end program the -U option to +enable unsafe mode. +

+

The following code fragment introduces the current time into a document. +

+ +
+
.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
+             (localtime(time))[2,1,0]' > /tmp/x\n[$$]
+.so /tmp/x\n[$$]
+.sy rm /tmp/x\n[$$]
+\nH:\nM:\nS
+
+ +

This works by having the Perl script (run by sy) write +nr requests that set the registers H, M, and +S to a temporary file. The roff document then reads the +temporary file using the so request. +

+ + +

The registers seconds, minutes, and hours, +initialized at startup of GNU troff, should satisfy most +requirements. Use the af request to format their values for +output. +

+
+
.af hours 00
+.af minutes 00
+.af seconds 00
+\n[hours]:\n[minutes]:\n[seconds]
+    ⇒ 02:17:54
+
+ + +

The writable register systat contains the return value of the +system() function executed by the last sy request. +

+ +
+
Request: .open stream file
+
+
Request: .opena stream file
+
+ + + + +

Open the specified file for writing and associates the specified +stream with it. +

+

The opena request is like open, but if the file exists, +append to it instead of truncating it. +

+ + + + +

It is an error to use these requests in safer mode; this is the default. +Give GNU troff or a front end program the -U option to +enable unsafe mode. +

+ +
+
Request: .write stream data
+
+
Request: .writec stream data
+
+ + + + + + + + +

Write to the file associated with the specified stream. The +stream must previously have been the subject of an open request. The +remainder of the line is interpreted as the ds request reads its +second argument: an initial neutral double quote in contents is +stripped to allow embedding of leading spaces, and it is read in copy +mode. +

+

The writec request is like write, but only write +appends a newline to the data. +

+ +
+
Request: .writem stream xx
+
+ +

Write the contents of the macro or string xx to the file +associated with the specified stream. +

+ + + +

xx is read in copy mode, i.e., already formatted elements are +ignored. Consequently, diversions must be unformatted with the +asciify request before calling writem. Usually, this +means a loss of information. +

+ +
+
Request: .close stream
+
+ + +

Close the specified stream; the stream is no longer an acceptable +argument to the write request. +

+

Here a simple macro to write an index entry. +

+
+
.open idx test.idx
+.
+.de IX
+.  write idx \\n[%] \\$*
+..
+.
+.IX test entry
+.
+.close idx
+
+
+ +
+
Escape sequence: \Ve
+
+
Escape sequence: \V(ev
+
Escape sequence: \V[env]
+
+ + +

Interpolate the contents of the specified environment variable env +(one-character name e, two-character name ev) as +returned by the function getenv(3). \V is interpreted +even in copy mode (see Copy Mode). +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.34 Postprocessor Access

+ + + +

Two escape sequences and two requests enable documents to pass +information directly to a postprocessor. These are useful for +exercising device-specific capabilities that the groff language +does not abstract or generalize; examples include the embedding of +hyperlinks and image files. Device-specific functions are documented in +each output driver’s man page, such as gropdf(1), +grops(1), or grotty(1). +

+
+
Request: .device xxx …
+
+
Escape sequence: \X'xxx …'
+
+

Embed all xxx arguments into GNU troff output as parameters +to a device control command ‘x X’. The meaning and +interpretation of such parameters is determined by the output driver or +other postprocessor. +

+ + + +

The device request processes its arguments in copy mode +(see Copy Mode). An initial neutral double quote in contents +is stripped to allow embedding of leading spaces. + + + + +By contrast, within \X arguments, the escape sequences \&, +\), \%, and \: are ignored; \SP and +\~ are converted to single space characters; and \\ has +its escape character stripped. So that the basic Latin subset of the +Unicode character set115 can be reliably encoded in device control +commands, seven special character escape sequences (‘\-’, +‘\[aq]’, ‘\[dq]’, ‘\[ga]’, ‘\[ha]’, ‘\[rs]’, +and ‘\[ti]’,) are mapped to basic Latin characters; see the +groff_char(7) man page. For this transformation, character +translations and special character definitions are +ignored.116 The use of any +other escape sequence in \X parameters is normally an error. +

+ + + +

If the use_charnames_in_special directive appears in the output +device’s DESC file, the use of special character escape sequences +is not an error; they are simply output verbatim (with the +exception of the seven mapped to Unicode basic Latin characters, +discussed above). use_charnames_in_special is currently employed +only by grohtml. +

+ +
+
Request: .devicem name
+
+
Escape sequence: \Yn
+
+
Escape sequence: \Y(nm
+
Escape sequence: \Y[name]
+

This is approximately equivalent to ‘\X'\*[name]'’ +(one-character name n, two-character name nm). +However, the contents of the string or macro name are not +interpreted; also it is permitted for name to have been defined as +a macro and thus contain newlines (it is not permitted for the argument +to \X to contain newlines). The inclusion of newlines requires +an extension to the AT&T troff output format, and +confuses drivers that do not know about this extension (see Device Control Commands). +

+ +
+
Request: .tag name
+
+
Request: .taga name
+
+

Reserved for internal use. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.35 Miscellaneous

+ +

We document here GNU troff features that fit poorly elsewhere. +

+
+
Request: .nm [start [increment [space [indentation]]]]
+
+
Register: \n[ln]
+
+
Register: \n[.nm]
+
+ + + +

Begin (or, with no arguments, cease) numbering output lines. +start assigns the number of the next output line. Only +line numbers divisible by increment are marked (default: +‘1’). space configures the horizontal spacing between the +number and the text (default: ‘1’). Any given indentation is +applied to the numbers (default: ‘0’). The third and fourth +arguments are reckoned in numeral widths (\0). start must +be non-negative and increment positive. +

+

The formatter aligns the number to the right in a width of three numeral +spaces plus indentation, then catenates space and the output +line. The line length is not reduced. Depending on the value of +the page offset,117 numbers wider than +the allocated space protrude into the left margin, or shift the output +line to the right. +

+

Line numbering parameters corresponding to missing arguments are not +altered. After numbering is disabled, ‘.nm +0’ resumes it using +the previously active parameters. +

+

The parameters of nm are associated with the environment +(see Environments). +

+ + +

While numbering is enabled, the output line number register ln is +updated as each line is output, even if no line number is formatted with +it because it is being skipped (it is not a multiple of increment) +or because numbering is suppressed (see the nn request below). +

+

The .nm register tracks the enablement status of numbering. +Temporary suspension of numbering with the nn request does +not alter its value. +

+
+
.po 5n
+.ll 44n
+Programming,
+when stripped of all its circumstantial irrelevancies,
+.nm 999 1 1 -4
+boils down to no more and no less than
+.nm +0 3
+very effective thinking so as to avoid unmastered
+.nn 2
+complexity,
+to very vigorous separation of your many
+different concerns.
+.br
+\(em Edsger Dijkstra
+.sp
+.nm 1 1 1
+This guy's arrogance takes your breath away.
+.br
+\(em John Backus
+    ⇒      Programming,  when  stripped of all its cir-
+    ⇒  999 cumstantial irrelevancies, boils down to  no
+    ⇒      more  and no less than very effective think-
+    ⇒      ing so as to avoid unmastered complexity, to
+    ⇒      very vigorous separation of your  many  dif-
+    ⇒      ferent concerns.
+    ⇒ 1002 -- Edsger Dijkstra
+    ⇒
+    ⇒    1 This guy’s arrogance takes your breath away.
+    ⇒    2 -- John Backus
+
+
+ +
+
Request: .nn [skip]
+
+
Register: \n[.nn]
+
+

Suppress numbering of the next skip output lines that would +otherwise be numbered. The default is 1. nn can be invoked +when line numbering is not active; suppression of numbering will take +effect for skip lines once nm enables it. +

+

The .nn register stores the count of output lines still to have +their numbering suppressed. +

+

This count is associated with the environment (see Environments). +

+ +

To test whether the current output line will be numbered, you must check +both the .nm and .nn registers. +

+
+
  .de is-numbered
+  .  nop This line
+  .  ie (\\n[.nm] & (1-\\n[.nn])) IS
+  .  el                           ISN'T
+  .  nop numbered.
+  .  br
+  ..
+  Test line numbering.
+  .is-numbered
+  .nm 1
+  .nn 1
+  .is-numbered
+  .is-numbered
+  .nm
+  .is-numbered
+    ⇒ Test line numbering.  This line ISN’T numbered.
+    ⇒ This line ISN’T numbered.
+    ⇒   1 This line IS numbered.
+    ⇒ This line ISN’T numbered.
+
+ +
+
Request: .mc [margin-character [distance]
+
+ + +

Begin (or, with no arguments, cease) writing a margin-character to +the right of each output line. The distance argument separates +margin-character from the right margin. If absent, the most +recent value is used; the default is 10 points. If an output line +exceeds the line length, the margin character is appended to it. + +No margin character is written on lines produced by the tl +request. +

+

The margin character is a property of the output line; the margin +character last configured when the line is output controls. If the +margin character is disabled before an output line breaks, none is +output (but see below). +

+

The margin character is associated with the environment +(see Environments). +

+
+
.ll 5i
+.nf
+.mc \[br]
+This paragraph is marked with a margin character.
+.sp
+As seen above, vertical space isn't thus marked.
+\&
+An output line that is present, but empty, is.
+    ⇒ This paragraph is marked with a margin character.  |
+    ⇒
+    ⇒ As seen above, vertical space isn’t thus marked.   |
+    ⇒                                                    |
+    ⇒ An output line that is present, but empty, is.     |
+
+
+ +

For compatibility with AT&T troff, a call to mc +to set the margin character can’t be undone immediately; at least one +line gets a margin character. +

+
+
.ll 10n
+.nf
+.mc |
+.mc *
+.mc
+foo
+bar
+    ⇒ foo        *
+    ⇒ bar
+
+ + + + + +

The margin character mechanism is commonly used to annotate changes in +documents. The groff distribution ships a program, +gdiffmk, to assist with this task.118 +

+
+
Request: .psbb file
+
+
Register: \n[llx]
+
+
Register: \n[lly]
+
+
Register: \n[urx]
+
+
Register: \n[ury]
+
+ + +

Retrieve the bounding box of the PostScript image found in file, +which must conform to Adobe’s Document Structuring Conventions +(DSC), locate a %%BoundingBox comment, and store the (upper-, +lower-, -left, -right) values into the registers llx, +lly, urx, and ury. If an error occurs (for +example, if no %%BoundingBox comment is present), the formatter +sets these registers to 0. +

+

The search path for file can be controlled with the -I +command-line option. +

+ + + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.36 gtroff Internals

+ + + + + +

gtroff processes input in three steps. One or more input +characters are converted to an input token.119 Then, one or more input tokens are converted to +an output node. Finally, output nodes are converted to the +intermediate output language understood by all output devices. +

+

Actually, before step one happens, gtroff converts certain escape +sequences into reserved input characters (not accessible by the user); +such reserved characters are used for other internal processing also – +this is the very reason why not all characters are valid input. +See Identifiers, for more on this topic. +

+

For example, the input string ‘fi\[:u]’ is converted into a +character token ‘f’, a character token ‘i’, and a special +token ‘:u’ (representing u umlaut). Later on, the character +tokens ‘f’ and ‘i’ are merged to a single output node +representing the ligature glyph ‘fi’ (provided the current font has +a glyph for this ligature); the same happens with ‘:u’. All output +glyph nodes are ‘processed’, which means that they are invariably +associated with a given font, font size, advance width, etc. During the +formatting process, gtroff itself adds various nodes to control +the data flow. +

+

Macros, diversions, and strings collect elements in two chained lists: a +list of input tokens that have been passed unprocessed, and a list of +output nodes. Consider the following diversion. +

+
+
.di xxx
+a
+\!b
+c
+.br
+.di
+
+ +

It contains these elements. +

+ + + + + + + + + + + + +
node listtoken listelement number
line start node—1
glyph node a—2
word space node—3
—b4
—\n5
glyph node c—6
vertical size node—7
vertical size node—8
—\n9
+ + +

Elements 1, 7, and 8 are inserted by gtroff; the latter two +(which are always present) specify the vertical extent of the last line, +possibly modified by \x. The br request finishes the +pending output line, inserting a newline input token, which is +subsequently converted to a space when the diversion is reread. Note +that the word space node has a fixed width that isn’t adjustable +anymore. To convert horizontal space nodes back to input tokens, use +the unformat request. +

+

Macros only contain elements in the token list (and the node list is +empty); diversions and strings can contain elements in both lists. +

+

The chop request simply reduces the number of elements in a +macro, string, or diversion by one. Exceptions are compatibility +save and compatibility ignore input tokens, which are ignored. +The substring request also ignores those input tokens. +

+

Some requests like tr or cflags work on glyph identifiers +only; this means that the associated glyph can be changed without +destroying this association. This can be very helpful for substituting +glyphs. In the following example, we assume that glyph ‘foo’ isn’t +available by default, so we provide a substitution using the +fchar request and map it to input character ‘x’. +

+
+
.fchar \[foo] foo
+.tr x \[foo]
+
+ +

Now let us assume that we install an additional special font ‘bar’ +that has glyph ‘foo’. +

+
+
.special bar
+.rchar \[foo]
+
+ +

Since glyphs defined with fchar are searched before glyphs in +special fonts, we must call rchar to remove the definition of the +fallback glyph. Anyway, the translation is still active; ‘x’ now +maps to the real glyph ‘foo’. +

+ + + + + + +

Macro and request arguments preserve compatibility mode enablement. +

+
+
.cp 1     \" switch to compatibility mode
+.de xx
+\\$1
+..
+.cp 0     \" switch compatibility mode off
+.xx caf\['e]
+    ⇒ café
+
+ +

Since compatibility mode is enabled while de is invoked, the +macro xx enables compatibility mode when it is called. Argument +$1 can still be handled properly because it inherits the +compatibility mode enablement status that was active at the point where +xx was called. +

+

After interpolation of the parameters, the compatibility save and +restore tokens are removed. +

+ + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.37 Debugging

+ + +

Standard troff voodoo, just put a power of two backslashes in +front of it until it works and if you still have problems add a \c. +— Ron Natalie +

+

GNU troff is not the easiest language to debug, in part thanks to +its design features of recursive interpolation and the use of +multi-stage pipeline processing in the surrounding system. Nevertheless +there exist several features useful for troubleshooting. +

+

Preprocessors use the lf request to preserve the identity of the +line numbers and names of input files. GNU troff emits a variety +of error diagnostics and supports several categories of warning; the +output of these can be selectively suppressed. A trace of the +formatter’s input processing stack can be emitted when errors or +warnings occur by means of GNU troff’s -b option, or +produced on demand with the backtrace request. The tm +and related requests can be used to emit customized diagnostic messages +or for instrumentation while troubleshooting. The ex and +ab requests cause early termination with successful and error +exit codes respectively, to halt further processing when continuing +would be fruitless. Examine the state of the formatter with requests +that write lists of defined names (macros, strings, and diversions), +environments, registers, and page location traps to the standard error +stream. +

+
+
Request: .lf line [file]
+
+ + + + + + +

Set the input line number (and, optionally, the file name) GNU +troff shall use for error and warning messages. line is +the input line number of the next line. Without an argument, the +request is ignored. +

+

lf’s primary purpose is to aid the debugging of documents that +undergo preprocessing. Programs like tbl that transform input +in their own languages into roff requests use it so that any +diagnostic messages emitted by troff correspond to the source +document. +

+ +
+
Request: .tm message
+
+
Request: .tm1 message
+
+
Request: .tmc message
+
+ + +

Send message, which consumes the remainder of the input line and +cannot contain special characters, to the standard error stream, +followed by a newline. Leading spaces in message are ignored. +

+

tm1 is similar, but recognizes and strips a leading neutral +double quote from message to allow the embedding of leading +spaces. +

+

tmc works as tm1, but does not append a newline. +

+ +
+
Request: .ab [message]
+
+ +

Write any message to the standard error stream (like tm) +and then abort GNU troff; that is, stop processing and terminate +with a failure status. +

+ +
+
Request: .ex
+
+ + +

Exit GNU troff; that is, stop processing and terminate with a +successful status. To stop processing only the current file, use the +nx request; see I/O. +

+ +

When doing something involved, it is useful to leave the debugging +statements in the code and have them turned on by a command-line flag. +

+
+
.if \n[DB] .tm debugging output
+
+ +

To activate such statements, use the -r option to set the +register. +

+
+
groff -rDB=1 file
+
+ +

If it is known in advance that there are many errors and no useful +output, GNU troff can be forced to suppress formatted output with +the -z option. +

+
+
Request: .pev
+
+ + +

Report the state of the current environment followed by that of all +other environments to the standard error stream. +

+ +
+
Request: .pm
+
+ + +

Report, to the standard error stream, the names of all defined macros, +strings, and diversions with their sizes in bytes. +

+ +
+
Request: .pnr
+
+ + +

Report the names and contents of all currently defined registers to the +standard error stream. +

+ +
+
Request: .ptr
+
+ + + + +

Report the names and positions of all page location traps to the +standard error stream. Empty slots in the list, where a trap has been +planted but subsequently (re)moved, are printed as well. +

+ +
+
Request: .fl
+
+ + + + +

Instruct gtroff to flush its output immediately. The intent is +for interactive use, but this behaviour is currently not implemented in +gtroff. Contrary to Unix troff, TTY output is sent to a +device driver also (grotty), making it non-trivial to communicate +interactively. +

+

This request causes a line break. +

+ +
+
Request: .backtrace
+
+ + +

Write the state of the input stack to the standard error stream. +

+

Consider the following in a file test. +

+
+
.de xxx
+.  backtrace
+..
+.de yyy
+.  xxx
+..
+.
+.yyy
+    error→ troff: backtrace: 'test':2: macro 'xxx'
+    error→ troff: backtrace: 'test':5: macro 'yyy'
+    error→ troff: backtrace: file 'test':8
+
+ +

The -b option of GNU troff causes a backtrace to be +generated on each error or warning. Some warnings have to be enabled; +See Warnings. +

+ +
+
Register: \n[slimit]
+
+ +

If greater than 0, sets the maximum quantity of objects on GNU +troff’s internal input stack. If less than or equal to 0, +there is no limit: recursion can continue until program memory is +exhausted. The default is 1,000. +

+ +
+
Request: .warnscale su
+
+

Set the scaling unit used in certain warnings to su, which can take the values ‘u’, ‘i’, ‘c’, +‘p’, and ‘P’. The default is ‘i’. +

+ +
+
Request: .spreadwarn [limit]
+
+

Emit a break warning if the additional space inserted for each +space between words in an output line adjusted to both margins with +‘.ad b’ is larger than or equal to limit. A negative +value is treated as zero; an absent argument toggles the warning on and +off without changing limit. The default scaling unit is ‘m’. +At startup, spreadwarn is inactive and limit is 3m. +

+

For example, +

+
+
.spreadwarn 0.2m
+
+ +

causes a warning if break warnings are not suppressed and +gtroff must add 0.2m or more for each inter-word space in a +line. See Warnings. +

+ + +

GNU troff has command-line options for reporting warnings +(-w) and backtraces (-b) when a warning or an error +occurs. +

+
+
Request: .warn [n]
+
+
Register: \n[.warn]
+
+ +

Select the categories, or “types”, of reported warnings. +n is the sum of the numeric codes associated with each +warning category that is to be enabled; all other categories are +disabled. The categories and their associated codes are listed in +Warnings. For example, ‘.warn 0’ disables all warnings, and +‘.warn 1’ disables all warnings except those about missing glyphs. +If no argument is given, all warning categories are enabled. +

+

The read-only register .warn contains the sum of the numeric +codes of enabled warning categories. +

+ + + + +
+
+
+

+Previous: , Up: Debugging   [Contents][Index]

+
+

5.37.1 Warnings

+ + +

Warning diagnostics emitted by GNU troff are divided into named, +numbered categories. The name associated with each warning category is +used by the -w and -W options. Each category is also +assigned a power of two; the sum of enabled category values is used by +the warn request and the .warn register. +

+

Warnings of each category are produced under the following +circumstances. +

+ + +
+
‘char’
+
‘1’
+

No mounted font defines a glyph for the requested character. This +category is enabled by default. +

+
+
‘number’
+
‘2’
+

An invalid numeric expression was encountered. This category is enabled +by default. +See Numeric Expressions. +

+
+
‘break’
+
‘4’
+
+

A filled output line could not be broken such that its length was less +than the output line length ‘\n[.l]’. This category is enabled by +default. +

+
+
‘delim’
+
‘8’
+

The closing delimiter in an escape sequence was missing or mismatched. +

+
+
‘el’
+
‘16’
+
+

The el request was encountered with no prior corresponding +ie request. See if-else. +

+
+
‘scale’
+
‘32’
+

A scaling unit inappropriate to its context was used in a numeric +expression. +

+
+
‘range’
+
‘64’
+

A numeric expression was out of range for its context. +

+
+
‘syntax’
+
‘128’
+

A self-contradictory hyphenation mode was requested; an empty or +incomplete numeric expression was encountered; an operand to a numeric +operator was missing; an attempt was made to define a recursive, empty, +or nonsensical character class; or a groff extension conditional +expression operator was used while in compatibility mode. +

+
+
‘di’
+
‘256’
+
+ + +

A di, da, box, or boxa request was invoked +without an argument when there was no current diversion. +

+
+
‘mac’
+
‘512’
+
+ + + + + + +

An undefined string, macro, or diversion was used. When such an object +is dereferenced, an empty one of that name is automatically created. +So, unless it is later deleted, at most one warning is given for each. +

+

This warning is also emitted upon an attempt to move an unplanted trap +macro (see Page Location Traps). In such cases, the unplanted macro +is not dereferenced, so it is not created if it does not exist. +

+
+
‘reg’
+
‘1024’
+
+ +

An undefined register was used. When an undefined register is +dereferenced, it is automatically defined with a value of 0. So, +unless it is later deleted, at most one warning is given for each. +

+
+
‘tab’
+
‘2048’
+

A tab character was encountered where a number was expected, or appeared +in an unquoted macro argument. +

+
+
‘right-brace’
+
‘4096’
+

A right brace escape sequence \} was encountered where a number +was expected. +

+
+
‘missing’
+
‘8192’
+

A request was invoked with a mandatory argument absent. +

+
+
‘input’
+
‘16384’
+

An invalid character occurred on the input stream. +

+
+
‘escape’
+
‘32768’
+

An unsupported escape sequence was encountered. +

+
+
‘space’
+
‘65536’
+

A space was missing between a request or macro and its argument. This +warning is produced when an undefined name longer than two characters is +encountered and the first two characters of the name constitute a +defined name. No request is invoked, no macro called, and an empty +macro is not defined. This category is enabled by default. It never +occurs in compatibility mode. +

+
+
‘font’
+
‘131072’
+

A non-existent font was selected, or the selection was ignored because a +font selection escape sequence was used after the output line +continuation escape sequence on an input line. This category is enabled +by default. +

+
+
‘ig’
+
‘262144’
+

An invalid escape sequence occurred in input ignored using the ig +request. This warning category diagnoses a condition that is an error +when it occurs in non-ignored input. +

+
+
‘color’
+
‘524288’
+

An undefined color was selected, an attempt was made to define a color +using an unrecognized color space, an invalid component in a color +definition was encountered, or an attempt was made to redefine a default +color. +

+
+
‘file’
+
‘1048576’
+

An attempt was made to load a file that does not exist. This category +is enabled by default. +

+
+ +

Two warning names group other warning categories for convenience. +

+
+
‘all’
+

All warning categories except ‘di’, ‘mac’ and ‘reg’. +This shorthand is intended to produce all warnings that are useful with +macro packages written for AT&T troff and its +descendants, which have less fastidious diagnostics than GNU +troff. +

+
+
‘w’
+

All warning categories. Authors of documents and macro packages +targeting groff are encouraged to use this setting. +

+
+ + +
+
+
+
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+

5.38 Implementation Differences

+ + + + +

GNU troff has a number of features that cause incompatibilities +with documents written for other versions of troff. Some GNU +extensions to troff have become supported by other +implementations. +

+ + + +
+
+
+

+Next: , Previous: , Up: Implementation Differences   [Contents][Index]

+
+

5.38.1 Safer Mode

+ + + + + +

The formatter operates in “safer” mode by default; to mitigate risks +from untrusted input documents, the pi and sy requests are +disabled. GNU troff’s -U option enables “unsafe +mode”, restoring their function and enabling additional groff +extension requests, open, opena, and pso. +See I/O. +

+ +
+
+
+
+

+Next: , Previous: , Up: Implementation Differences   [Contents][Index]

+
+

5.38.2 Compatibility Mode

+ + + + + + + +

Long identifier names may be GNU troff’s most obvious innovation. +AT&T troff interprets ‘.dsabcd’ as defining a +string ‘ab’ with contents ‘cd’. Normally, GNU troff +interprets this as a call of a macro named dsabcd. +AT&T troff also interprets ‘\*[’ and ‘\n[’ as +an interpolation of a string or register, respectively, named ‘[’. +In GNU troff, however, the ‘[’ is normally interpreted as +delimiting a long name. In compatibility mode, GNU troff +interprets names in the traditional way; they thus can be two characters +long at most. +

+
+
Request: .cp [n]
+
+
Register: \n[.C]
+
+

If n is missing or non-zero, turn on compatibility mode; +otherwise, turn it off. +

+

The read-only register .C is 1 if compatibility mode is on, +0 otherwise. +

+

Compatibility mode can be also turned on with the -C +command-line option. +

+ +
+
Request: .do name
+
+
Register: \n[.cp]
+
+

The do request interprets the string, request, diversion, or +macro name (along with any further arguments) with compatibility +mode disabled. Compatibility mode is restored (only if it was active) +when the expansion of name is interpreted; that is, the +restored compatibility state applies to the contents of the macro, +string, or diversion name as well as data read from files or pipes +if name is any of the so, soquiet, mso, +msoquiet, or pso requests. +

+

The following example illustrates several aspects of do behavior. +

+
+
.de mac1
+FOO
+..
+.de1 mac2
+groff
+.mac1
+..
+.de mac3
+compatibility
+.mac1
+..
+.de ma
+\\$1
+..
+.cp 1
+.do mac1
+.do mac2 \" mac2, defined with .de1, calls "mac1"
+.do mac3 \" mac3 calls "ma" with argument "c1"
+.do mac3 \[ti] \" groff syntax accepted in .do arguments
+    ⇒ FOO groff FOO compatibility c1 ~
+
+ +

The read-only register .cp, meaningful only when dereferenced +from a do request, is 1 if compatibility mode was on when +the do request was encountered, and 0 if it was not. This +register is specialized and may require a statement of rationale. +

+

When writing macro packages or documents that use GNU troff +features and which may be mixed with other packages or documents that do +not—common scenarios include serial processing of man pages or use of +the so or mso requests—you may desire correct operation +regardless of compatibility mode enablement in the surrounding context. +It may occur to you to save the existing value of ‘\n(.C’ into a +register, say, ‘_C’, at the beginning of your file, turn +compatibility mode off with ‘.cp 0’, then restore it from that +register at the end with ‘.cp \n(_C’. At the same time, a modular +design of a document or macro package may lead you to multiple layers of +inclusion. You cannot use the same register name everywhere lest you +“clobber” the value from a preceding or enclosing context. The +two-character register name space of AT&T troff is +confining and mnemonically challenging; you may wish to use the more +capacious name space of GNU troff. However, attempting ‘.nr +_my_saved_C \n(.C’ will not work in compatibility mode; the register +name is too long. “This is exactly what do is for,” you think, +‘.do nr _my_saved_C \n(.C’. The foregoing will always save zero to +your register, because do turns compatibility mode off +while it interprets its argument list. +

+

To robustly save compatibility mode before switching it off, use +

+
+
.do nr _my_saved_C \n[.cp]
+.cp 0
+
+ +

at the beginning of your file, followed by +

+
+
.cp \n[_my_saved_C]
+.do rr _my_saved_C
+
+ +

at the end. As in the C language, we all have to share one big +name space, so choose a register name that is unlikely to collide with +other uses. +

+ + + + +

Normally, GNU troff preserves the interpolation depth in +delimited arguments, but not in compatibility mode. +

+
+
.ds xx '
+\w'abc\*(xxdef'
+    ⇒ 168 (normal mode on a terminal device)
+    ⇒ 72def' (compatibility mode on a terminal device)
+
+ + + + + +

Furthermore, the escape sequences \f, \H, \m, +\M, \R, \s, and \S are transparent for the +purpose of recognizing a control character at the beginning of a line +only in compatibility mode. For example, this code produces bold output +in both cases, but the text differs. +

+
+
.de xx
+Hello!
+..
+\fB.xx\fP
+    ⇒ .xx (normal mode)
+    ⇒ Hello! (compatibility mode)
+
+ + +

Normally, the syntax form \sn accepts only a single +character (a digit) for n, consistently with other forms that +originated in AT&T troff, like \*, \$, +\f, \g, \k, \n, and \z. In +compatibility mode only, a non-zero n must be in the range +4–39. Legacy documents relying upon this quirk of parsing120 should be migrated to another +\s form. +

+ +
+
+
+
+

+Previous: , Up: Implementation Differences   [Contents][Index]

+
+

5.38.3 Other Differences

+ +

groff request names unrecognized by other troff +implementations will likely be ignored by them; escape sequences that +are groff extensions are liable to be interpreted as if the +escape character were not present. + +For example, the adjustable, non-breaking escape sequence \~ +is also supported by Heirloom Doctools troff 050915 (September +2005), mandoc 1.9.5 (2009-09-21), neatroff (commit +1c6ab0f6e, 2016-09-13), and Plan 9 from User Space troff +(commit 93f8143600, 2022-08-12), but not by Solaris or Documenter’s +Workbench troffs. +See Manipulating Filling and Adjustment. +

+ + + + + + + + + + + + + + +

GNU troff does not allow the use of the escape sequences +\|, \^, \&, \{, \}, +\SP, \', \`, \-, \_, \!, +\%, and \c in identifiers; AT&T troff +does. The \A escape sequence (see Identifiers) may be +helpful in avoiding use of these escape sequences in names. +

+ + +

When adjusting to both margins, AT&T troff at first +adjusts spaces starting from the right; GNU troff begins from +the left. Both implementations adjust spaces from opposite ends on +alternating output lines in this adjustment mode to prevent “rivers” +in the text. +

+ +

GNU troff does not always hyphenate words as AT&T +troff does. The AT&T implementation uses a set of +hard-coded rules specific to English, while GNU troff uses +language-specific hyphenation pattern files derived from TeX. +Furthermore, in old versions of troff there was a limited amount +of space to store hyphenation exceptions (arguments to the hw +request); GNU troff has no such restriction. +

+ +

GNU troff predefines a string .T containing the argument +given to the -T command-line option, namely the current output +device (for example, ‘pdf’ or ‘utf8’). The existence of this +string is a common feature of post-CSTR #54 +troffs121 but valid values are specific +to each implementation. +

+ + + +

AT&T troff ignored attempts to remove read-only +registers; GNU troff honors such requests. See Built-in Registers. +

+ +

The (read-only) register .T interpolates 1 if GNU +troff is called with the -T command-line option, and +0 otherwise. This behavior differs from AT&T troff, which +interpolated 1 only if nroff was the formatter and was +called with -T. +

+ +

AT&T troff and other implementations handle the +lf request differently. For them, its line argument +changes the line number of the current line. +

+ +

AT&T troff had only environments named ‘0’, +‘1’, and ‘2’. In GNU troff, any number of environments +may exist, using any valid identifiers for their names +(see Identifiers.) +

+ + + + + + +

Fractional type sizes cause one noteworthy incompatibility. In +AT&T troff the ps request ignores scaling units +and thus ‘.ps 10u’ sets the type size to 10 points, whereas in +GNU troff it sets the type size to 10 scaled points. +See Using Fractional Type Sizes. +

+ +

The ab request differs from AT&T troff: +GNU troff writes no message to the standard error stream if no +arguments are given, and it exits with a failure status instead of a +successful one. +

+ +

The bp request differs from AT&T troff: +GNU troff does not accept a scaling unit on the argument, a page +number; the former (somewhat uselessly) does. +

+ +

The pm request differs from AT&T troff: +GNU troff reports the sizes of macros, strings, and diversions in +bytes and ignores an argument to report only the sum of the sizes. +

+ +

Unlike AT&T troff, GNU troff does not ignore the +ss request if the output is a terminal device; instead, the +values of minimal inter-word and additional inter-sentence space are +each rounded down to the nearest multiple of 12. +

+ + + + + + + + +

In GNU troff there is a fundamental difference between +(unformatted) characters and (formatted) glyphs. Everything that +affects how a glyph is output is stored with the glyph node; once a +glyph node has been constructed, it is unaffected by any subsequent +requests that are executed, including bd, cs, tkf, +tr, or fp requests. Normally, glyphs are constructed from +characters immediately before the glyph is added to an output line. +Macros, diversions, and strings are all, in fact, the same type of +object; they contain a sequence of intermixed character and glyph nodes. +Special characters transform from one to the other: before being added +to the output, they behave as characters; afterward, they are glyphs. A +glyph node does not behave like a character node when it is processed by +a macro: it does not inherit any of the special properties that the +character from which it was constructed might have had. For example, +the input +

+
+
.di x
+\\\\
+.br
+.di
+.x
+
+ +

produces ‘\\’ in GNU troff. Each pair of backslashes +becomes one backslash glyph; the resulting backslashes are thus +not interpreted as escape characters when they are reread as the +diversion is output. AT&T troff would interpret +them as escape characters when rereading them and end up printing one +‘\’. +

+ + + + + + + +

One correct way to obtain a printable backslash in most documents is to +use the \e escape sequence; this always prints a single instance +of the current escape character,122 regardless of whether or not it is used in a diversion; it +also works in both GNU troff and AT&T troff. +

+

The other correct way, appropriate in contexts independent of the +backslash’s common use as a troff escape character—perhaps in +discussion of character sets or other programming languages—is +the character escape \(rs or \[rs], for “reverse +solidus”, from its name in the ECMA-6 (ISO/IEC 646) +standard.123 +

+

To store an escape sequence in a diversion that is interpreted when the +diversion is reread, either use the traditional \! transparent +output facility, or, if this is unsuitable, the new \? escape +sequence. See Diversions and gtroff Internals. +

+

In the somewhat pathological case where a diversion exists containing a +partially collected line and a partially collected line at the top-level +diversion has never existed, AT&T troff will output the +partially collected line at the end of input; GNU troff will not. +

+ + + + +
+
+
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

6 File Formats

+ + + +

All files read and written by gtroff are text files. The +following two sections describe their format. +

+ + + + + +
+
+
+

+Next: , Previous: , Up: File Formats   [Contents][Index]

+
+

6.1 gtroff Output

+ + + +

This section describes the groff intermediate output format +produced by GNU troff. +

+

As groff is a wrapper program around GNU troff and +automatically calls an output driver (or “postprocessor”), this output +does not show up normally. This is why it is called +intermediate. groff provides the option -Z to +inhibit postprocessing such that the produced intermediate output is +sent to standard output just as it is when calling GNU troff +directly. +

+ + + + +

Here, the term troff output describes what is output by +GNU troff, while intermediate output refers to the language +that is accepted by the parser that prepares this output for the output +drivers. This parser handles whitespace more flexibly than +AT&T’s implementation and implements obsolete elements for +compatibility; otherwise, both formats are the same.124 +

+

The main purpose of the intermediate output concept is to facilitate the +development of postprocessors by providing a common programming +interface for all devices. It has a language of its own that is +completely different from the gtroff language. While the +gtroff language is a high-level programming language for text +processing, the intermediate output language is a kind of low-level +assembler language by specifying all positions on the page for writing +and drawing. +

+

The intermediate output produced by gtroff is fairly readable, +while output from AT&T troff is rather hard to +understand because of strange habits that are still supported, but not +used any longer by gtroff. +

+ + + +
+
+
+

+Next: , Previous: , Up: gtroff Output   [Contents][Index]

+
+

6.1.1 Language Concepts

+ +

The fundamental operation of the GNU troff formatter is the +translation of the groff input language into a device-independent +form primarily concerned with what has to be written or drawn at +specific positions on the output device. This language is simple and +imperative. In the following discussion, the term command always +refers to this intermediate output language, and never to the +groff language intended for direct use by document authors. +Intermediate output commands comprise several categories: glyph output; +font, color, and text size selection; motion of the printing position; +page advancement; drawing of geometric objects; and device control +commands, a catch-all for operations not easily classified as any of the +foregoing, such as directives to start and stop output, identify the +intended output device, or place URL hyperlinks in supported output +formats. +

+ + +
+
+
+

+Next: , Previous: , Up: Language Concepts   [Contents][Index]

+
+

6.1.1.1 Separation

+ +

AT&T troff output has strange requirements regarding +whitespace. The gtroff output parser, however, is more tolerant, +making whitespace maximally optional. Such characters, i.e., the tab, +space, and newline, always have a syntactical meaning. They are never +printable because spacing within the output is always done by +positioning commands. +

+

Any sequence of space or tab characters is treated as a single +syntactical space. It separates commands and arguments, but is +only required when there would occur a clashing between the command code +and the arguments without the space. Most often, this happens when +variable-length command names, arguments, argument lists, or command +clusters meet. Commands and arguments with a known, fixed length need +not be separated by syntactical space. +

+

A line break is a syntactical element, too. Every command argument can +be followed by whitespace, a comment, or a newline character. Thus a +syntactical line break is defined to consist of optional +syntactical space that is optionally followed by a comment, and a +newline character. +

+

The normal commands, those for positioning and text, consist of a single +letter taking a fixed number of arguments. For historical reasons, the +parser allows stacking of such commands on the same line, but +fortunately, in gtroff’s intermediate output, every command with +at least one argument is followed by a line break, thus providing +excellent readability. +

+

The other commands—those for drawing and device controlling—have a +more complicated structure; some recognize long command names, and some +take a variable number of arguments. So all ‘D’ and ‘x’ +commands were designed to request a syntactical line break after their +last argument. Only one command, ‘x X’, has an argument that +can span several input lines; all other commands must have all of +their arguments on the same line as the command, i.e., the arguments may +not be split by a line break. +

+

Empty lines (these are lines containing only space and/or a comment), +can occur everywhere. They are just ignored. +

+
+
+
+
+

+Next: , Previous: , Up: Language Concepts   [Contents][Index]

+
+

6.1.1.2 Argument Units

+ +

Some commands take integer arguments that are assumed to represent +values in a measurement unit, but the letter for the corresponding +scaling unit is not written with the output command arguments. Most +commands assume the scaling unit ‘u’, the basic unit of the device, +some use ‘z’, the scaled point unit of the device, while others, +such as the color commands, expect plain integers. +

+

Single characters can have the eighth bit set, as can the names of +fonts and special characters. The names of characters and fonts can be +of arbitrary length. A character that is to be printed is always in +the current font. +

+

A string argument is always terminated by the next whitespace character +(space, tab, or newline); an embedded ‘#’ character is regarded as +part of the argument, not as the beginning of a comment command. An +integer argument is already terminated by the next non-digit character, +which then is regarded as the first character of the next argument or +command. +

+
+
+
+
+

+Previous: , Up: Language Concepts   [Contents][Index]

+
+

6.1.1.3 Document Parts

+ +

A correct intermediate output document consists of two parts, the +prologue and the body. +

+

The task of the prologue is to set the general device parameters using +three exactly specified commands. gtroff’s prologue is +guaranteed to consist of the following three lines (in that order): +

+
+
x T device
+x res n h v
+x init
+
+ +

with the arguments set as outlined in Device Control Commands. +The parser for the intermediate output format is able to interpret +additional whitespace and comments as well even in the prologue. +

+

The body is the main section for processing the document data. +Syntactically, it is a sequence of any commands different from the ones +used in the prologue. Processing is terminated as soon as the first +‘x stop’ command is encountered; the last line of any +gtroff intermediate output always contains such a command. +

+

Semantically, the body is page oriented. A new page is started by a +‘p’ command. Positioning, writing, and drawing commands are always +done within the current page, so they cannot occur before the first +‘p’ command. Absolute positioning (by the ‘H’ and ‘V’ +commands) is done relative to the current page; all other positioning is +done relative to the current location within this page. +

+ +
+
+
+
+
+

+Next: , Previous: , Up: gtroff Output   [Contents][Index]

+
+

6.1.2 Command Reference

+ +

This section describes all intermediate output commands, both from +AT&T troff as well as the gtroff extensions. +

+ + +
+
+
+

+Next: , Previous: , Up: Command Reference   [Contents][Index]

+
+

6.1.2.1 Comment Command

+ +
+
#anything‹end of line›
+

A comment. Ignore any characters from the ‘#’ character up to the +next newline character. +

+

This command is the only possibility for commenting in the intermediate +output. Each comment can be preceded by arbitrary syntactical space; +every command can be terminated by a comment. +

+
+ +
+
+
+
+

+Next: , Previous: , Up: Command Reference   [Contents][Index]

+
+

6.1.2.2 Simple Commands

+ +

The commands in this subsection have a command code consisting of a +single character, taking a fixed number of arguments. Most of them are +commands for positioning and text writing. These commands are tolerant +of whitespace. Optionally, syntactical space can be inserted before, +after, and between the command letter and its arguments. All of these +commands are stackable; i.e., they can be preceded by other simple +commands or followed by arbitrary other commands on the same line. A +separating syntactical space is necessary only when two integer +arguments would clash or if the preceding argument ends with a string +argument. +

+
+
C id‹whitespace›
+

Typeset the glyph of the special character id. Trailing +syntactical space is necessary to allow special character names of +arbitrary length. The drawing position is not advanced. +

+
+
c g
+

Typeset the glyph of the ordinary character c. The drawing +position is not advanced. +

+
+
f n
+

Select the font mounted at position n. n cannot +be negative. +

+
+
H n
+

Horizontally move the drawing position to n basic units from +the left edge of the page. n cannot be negative. +

+
+
h n
+

Move the drawing position right n basic units. AT&T +troff allowed negative n; GNU troff does not produce +such values, but groff’s output driver library handles them. +

+
+
m color-scheme [component …]
+

Select the stroke color using the components in the color space +scheme. Each component is an integer between 0 and 65535. +The quantity of components and their meanings vary with each +scheme. This command is a groff extension. +

+
+
mc cyan magenta yellow
+

Use the CMY color scheme with components cyan, magenta, and yellow. +

+
+
md
+

Use the default color (no components; black in most cases). +

+
+
mg gray
+

Use a grayscale color scheme with a component ranging between 0 (black) +and 65535 (white). +

+
+
mk cyan magenta yellow black
+

Use the CMYK color scheme with components cyan, magenta, yellow, and +black. +

+
+
mr red green blue
+

Use the RGB color scheme with components red, green, and blue. +

+
+ +
+
N n
+

Typeset the glyph with index n in the current font. +n is normally a non-negative integer. The drawing position +is not advanced. The html and xhtml devices use this +command with negative n to produce unbreakable space; the +absolute value of n is taken and interpreted in basic units. +

+
+
n b a
+

Indicate a break. No action is performed; the command is present to +make the output more easily parsed. The integers b +and a describe the vertical space amounts before and after +the break, respectively. GNU troff issues this command but +groff’s output driver library ignores it. See v and +V below. +

+
+
p n
+

Begin a new page, setting its number to n. Each page is +independent, even from those using the same number. The vertical +drawing position is set to 0. All positioning, writing, and +drawing commands are interpreted in the context of a page, so a +p command must precede them. +

+
+
s n
+

Set type size to n scaled points (unit z in GNU +troff. +AT&T troff used unscaled points p instead; +see Output Language Compatibility. +

+
+
t xyz‹whitespace›
+
t xyz dummy-arg‹whitespace›
+

Typeset a word xyz; that is, set a sequence of ordinary glyphs +named x, y, z, …, terminated by a space +character or a line break; an optional second integer argument is +ignored (this allows the formatter to generate an even number of +arguments). Each glyph is set at the current drawing position, and the position is +then advanced horizontally by the glyph’s width. A glyph’s width is +read from its metrics in the font description file, scaled to the +current type size, and rounded to a multiple of the horizontal motion +quantum. Use the C command to emplace glyphs of special +characters. The t command is a groff extension and +is output only for devices whose DESC file contains the +tcommand directive; see DESC File Format. +

+
+
u n xyz‹whitespace›
+

Typeset word xyz with track kerning. As t, but after +placing each glyph, the drawing position is further advanced +horizontally by n basic units (u). The +u command is a groff extension and is output only for +devices whose DESC file contains the tcommand directive; +see DESC File Format. +

+
+
V n
+

Vertically move the drawing position to n basic units from +the top edge of the page. n cannot be negative. +

+
+
v n
+

Move the drawing position down n basic units. AT&T +troff allowed negative n; GNU troff does not produce +such values, but groff’s output driver library handles them. +

+
+
w
+

Indicate an inter-word space. No action is performed; the command is +present to make the output more easily parsed. Only adjustable, +breakable inter-word spaces are thus described; those resulting from +\~ or horizontal motion escape sequences are not. GNU +troff issues this command but groff’s output driver +library ignores it. See h and H above. +

+
+ +
+
+
+
+

+Next: , Previous: , Up: Command Reference   [Contents][Index]

+
+

6.1.2.3 Graphics Commands

+ +

Each graphics or drawing command in the intermediate output starts with +the letter ‘D’, followed by one or two characters that specify a +subcommand; this is followed by a fixed or variable number of integer +arguments that are separated by a single space character. A ‘D’ +command may not be followed by another command on the same line (apart +from a comment), so each ‘D’ command is terminated by a syntactical +line break. +

+

gtroff output follows the classical spacing rules (no space +between command and subcommand, all arguments are preceded by a single +space character), but the parser allows optional space between the +command letters and makes the space before the first argument optional. +As usual, each space can be any sequence of tab and space characters. +

+

Some graphics commands can take a variable number of arguments. In this +case, they are integers representing a size measured in basic units +‘u’. The arguments called h1, h2, …, hn +stand for horizontal distances where positive means right, negative +left. The arguments called v1, v2, …, vn stand +for vertical distances where positive means down, negative up. All +these distances are offsets relative to the current location. +

+

Each graphics command directly corresponds to a similar gtroff +\D escape sequence. See Drawing Geometric Objects. +

+

Unknown ‘D’ commands are assumed to be device-specific. Its +arguments are parsed as strings; the whole information is then sent to +the postprocessor. +

+

In the following command reference, the syntax element ‹line +break› means a syntactical line break as defined above. +

+
+
D~ h1 v1 h2 v2 … hn vn‹line break›
+

Draw B-spline from current position to offset (h1,v1), then +to offset (h2,v2), if given, etc., up to +(hn,vn). This command takes a variable number of argument +pairs; the current position is moved to the terminal point of the drawn +curve. +

+
+
Da h1 v1 h2 v2‹line break›
+

Draw arc from current position to +(h1,v1)+(h2,v2) with center at +(h1,v1); then move the current position to the final point +of the arc. +

+
+
DC d‹line break›
+
DC d dummy-arg‹line break›
+

Draw a solid circle using the current fill color with +diameter d (integer in basic units ‘u’) with leftmost +point at the current position; then move the current position to the +rightmost point of the circle. An optional second integer argument is +ignored (this allows the formatter to generate an even number of +arguments). This command is a gtroff extension. +

+
+
Dc d‹line break›
+

Draw circle line with diameter d (integer in basic units +‘u’) with leftmost point at the current position; then move the +current position to the rightmost point of the circle. +

+
+
DE h v‹line break›
+

Draw a solid ellipse in the current fill color with a horizontal +diameter of h and a vertical diameter of v (both +integers in basic units ‘u’) with the leftmost point at the current +position; then move to the rightmost point of the ellipse. This command +is a gtroff extension. +

+
+
De h v‹line break›
+

Draw an outlined ellipse with a horizontal diameter of h and +a vertical diameter of v (both integers in basic units +‘u’) with the leftmost point at current position; then move to the +rightmost point of the ellipse. +

+
+
DF color-scheme [component …]‹line break›
+

Set fill color for solid drawing objects using different color schemes; +the analogous command for setting the color of text, line graphics, and +the outline of graphic objects is ‘m’. The color components are +specified as integer arguments between 0 and 65535. The number of color +components and their meaning vary for the different color schemes. +These commands are generated by gtroff’s escape sequences +‘\D'F …'’ and \M (with no other corresponding +graphics commands). No position changing. This command is a +gtroff extension. +

+
+
DFc cyan magenta yellow‹line break›
+

Set fill color for solid drawing objects using the CMY color scheme, +having the 3 color components cyan, magenta, and +yellow. +

+
+
DFd‹line break›
+

Set fill color for solid drawing objects to the default fill color value +(black in most cases). No component arguments. +

+
+
DFg gray‹line break›
+

Set fill color for solid drawing objects to the shade of gray given by +the argument, an integer between 0 (black) and 65535 (white). +

+
+
DFk cyan magenta yellow black‹line break›
+

Set fill color for solid drawing objects using the CMYK color scheme, +having the 4 color components cyan, magenta, +yellow, and black. +

+
+
DFr red green blue‹line break›
+

Set fill color for solid drawing objects using the RGB color scheme, +having the 3 color components red, green, and +blue. +

+
+ +
+
Df n‹line break›
+

The argument n must be an integer in the range -32767 +to 32767. +

+
+
0 ≤ n ≤ 1000
+

Set the color for filling solid drawing objects to a shade of gray, +where 0 corresponds to solid white, 1000 (the default) to solid black, +and values in between to intermediate shades of gray; this is obsoleted +by command ‘DFg’. +

+
+
n < 0 or n > 1000
+

Set the filling color to the color that is currently being used for the +text and the outline, see command ‘m’. For example, the command +sequence +

+
+
mg 0 0 65535
+Df -1
+
+ +

sets all colors to blue. +

+
+ +

No position changing. This command is a gtroff extension. +

+
+
Dl h v‹line break›
+

Draw line from current position to offset (h,v) (integers in +basic units ‘u’); then set current position to the end of the drawn +line. +

+
+
Dp h1 v1 h2 v2 … hn vn‹line break›
+

Draw a polygon line from current position to offset (h1,v1), +from there to offset (h2,v2), etc., up to offset +(hn,vn), and from there back to the starting position. For +historical reasons, the position is changed by adding the sum of all +arguments with odd index to the actual horizontal position and the even +ones to the vertical position. Although this doesn’t make sense it is +kept for compatibility. +This command is a gtroff extension. +

+
+
DP h1 v1 h2 v2 … hn vn‹line break›
+

Draw a solid polygon in the current fill color rather than an outlined +polygon, using the same arguments and positioning as the corresponding +‘Dp’ command. +This command is a gtroff extension. +

+
+
Dt n‹line break›
+

Set the current line thickness to n (an integer in basic +units ‘u’) if n>0; if n=0 select the +smallest available line thickness; if n<0 set the line +thickness proportional to the type size (this is the default before the +first ‘Dt’ command was specified). For historical reasons, the +horizontal position is changed by adding the argument to the actual +horizontal position, while the vertical position is not changed. +Although this doesn’t make sense it is kept for compatibility. +This command is a gtroff extension. +

+
+ +
+
+
+
+

+Next: , Previous: , Up: Command Reference   [Contents][Index]

+
+

6.1.2.4 Device Control Commands

+ +

Each device control command starts with the letter ‘x’, followed by +a space character (optional or arbitrary space or tab in gtroff) +and a subcommand letter or word; each argument (if any) must be preceded +by a syntactical space. All ‘x’ commands are terminated by a +syntactical line break; no device control command can be followed by +another command on the same line (except a comment). +

+

The subcommand is basically a single letter, but to increase +readability, it can be written as a word, i.e., an arbitrary sequence of +characters terminated by the next tab, space, or newline character. All +characters of the subcommand word but the first are simply ignored. For +example, gtroff outputs the initialization command ‘x i’ +as ‘x init’ and the resolution command ‘x r’ as +‘x res’. +

+

In the following, the syntax element ‹line break› means a +syntactical line break (see Separation). +

+
+
xF name‹line break›
+

The ‘F’ stands for Filename. +

+

Use name as the intended name for the current file in error +reports. This is useful for remembering the original file name when +gtroff uses an internal piping mechanism. The input file is not +changed by this command. This command is a gtroff extension. +

+
+
xf n s‹line break›
+

The ‘f’ stands for font. +

+

Mount font position n (a non-negative integer) with font +named s (a text word). See Font Positions. +

+
+
xH n‹line break›
+

The ‘H’ stands for Height. +

+

Set glyph height to n (a positive integer in scaled points +‘z’). AT&T troff uses the unit points (‘p’) +instead. See Output Language Compatibility. +

+
+
xi‹line break›
+

The ‘i’ stands for init. +

+

Initialize device. This is the third command of the prologue. +

+
+
xp‹line break›
+

The ‘p’ stands for pause. +

+

Parsed but ignored. The AT&T troff manual documents +this command as +

+
+
pause device, can be restarted
+
+ +

but GNU troff output drivers do nothing with this command. +

+
+
xr n h v‹line break›
+

The ‘r’ stands for resolution. +

+

Resolution is n, while h is the minimal horizontal +motion, and v the minimal vertical motion possible with this +device; all arguments are positive integers in basic units ‘u’ per +inch. This is the second command of the prologue. +

+
+
xS n‹line break›
+

The ‘S’ stands for Slant. +

+

Set slant to n (an integer in basic units ‘u’). +

+
+
xs‹line break›
+

The ‘s’ stands for stop. +

+

Terminates the processing of the current file; issued as the last +command of any intermediate troff output. +

+
+
xt‹line break›
+

The ‘t’ stands for trailer. +

+

Generate trailer information, if any. In GNU troff, this is +ignored. +

+
+
xT xxx‹line break›
+

The ‘T’ stands for Typesetter. +

+

Set the name of the output driver to xxx, a sequence of +non-whitespace characters terminated by whitespace. The possible names +correspond to those of groff’s -T option. This is the +first command of the prologue. +

+
+
xu n‹line break›
+

The ‘u’ stands for underline. +

+

Configure underlining of spaces. If n is 1, start +underlining of spaces; if n is 0, stop underlining of spaces. +This is needed for the cu request in nroff mode and is +ignored otherwise. This command is a gtroff extension. +

+
+
xX anything‹line break›
+

The ‘x’ stands for X-escape. +

+

Send string anything uninterpreted to the device. If the line +following this command starts with a ‘+’ character this line is +interpreted as a continuation line in the following sense. The ‘+’ +is ignored, but a newline character is sent instead to the device, the +rest of the line is sent uninterpreted. The same applies to all +following lines until the first character of a line is not a ‘+’ +character. This command is generated by the gtroff escape +sequence \X. The line-continuing feature is a gtroff +extension. +

+
+ +
+
+
+
+

+Previous: , Up: Command Reference   [Contents][Index]

+
+

6.1.2.5 Obsolete Command

+

In AT&T troff output, the writing of a single glyph is +mostly done by a very strange command that combines a horizontal move +and a single character giving the glyph name. It doesn’t have a command +code, but is represented by a 3-character argument consisting of exactly +2 digits and a character. +

+
+
ddg
+

Move right dd (exactly two decimal digits) basic units ‘u’, +then print glyph g (represented as a single character). +

+

In GNU troff, arbitrary syntactical space around and within this +command is allowed. Only when a preceding command on the same line ends +with an argument of variable length is a separating space obligatory. +In AT&T troff, large clusters of these and other +commands are used, mostly without spaces; this made such output almost +unreadable. +

+
+ +

For modern high-resolution devices, this command does not make sense +because the width of the glyphs can become much larger than two decimal +digits. In gtroff, this is only used for the devices X75, +X75-12, X100, and X100-12. For other devices, the +commands ‘t’ and ‘u’ provide a better functionality. +

+ +
+
+
+
+
+

+Next: , Previous: , Up: gtroff Output   [Contents][Index]

+
+

6.1.3 Intermediate Output Examples

+ +

This section presents the intermediate output generated from the same +input for three different devices. The input is the sentence ‘hell +world’ fed into gtroff on the command line. +

+
+
High-resolution device ps
+
+

This is the standard output of gtroff if no -T option is +given. +

+
+
shell> echo "hell world" | groff -Z -T ps
+
+x T ps
+x res 72000 1 1
+x init
+
p1
+x font 5 TR
+f5
+s10000
+V12000
+H72000
+thell
+wh2500
+tw
+H96620
+torld
+n12000 0
+
x trailer
+V792000
+x stop
+
+ +

This output can be fed into grops to get its representation as a +PostScript file. +

+
+
Low-resolution device latin1
+
+

This is similar to the high-resolution device except that the +positioning is done at a minor scale. Some comments (lines starting +with ‘#’) were added for clarification; they were not generated by +the formatter. +

+
+
shell> echo "hell world" | groff -Z -T latin1
+
+# prologue
+x T latin1
+x res 240 24 40
+x init
+
# begin a new page
+p1
+# font setup
+x font 1 R
+f1
+s10
+# initial positioning on the page
+V40
+H0
+# write text 'hell'
+thell
+# inform about space, and issue a horizontal jump
+wh24
+# write text 'world'
+tworld
+# announce line break, but do nothing because...
+n40 0
+
# ...the end of the document has been reached
+x trailer
+V2640
+x stop
+
+ +

This output can be fed into grotty to get a formatted text +document. +

+
+
AT&T troff output
+

Since a computer monitor has a much lower resolution than modern +printers, the intermediate output for X11 devices can use the +jump-and-write command with its 2-digit displacements. +

+
+
shell> echo "hell world" | groff -Z -T X100
+
+x T X100
+x res 100 1 1
+x init
+
p1
+x font 5 TR
+f5
+s10
+V16
+H100
+# write text with jump-and-write commands
+ch07e07l03lw06w11o07r05l03dh7
+n16 0
+
x trailer
+V1100
+x stop
+
+ +

This output can be fed into xditview or gxditview for +displaying in X. +

+

Due to the obsolete jump-and-write command, the text clusters in the +AT&T troff output are almost unreadable. +

+
+ + +
+
+
+
+

+Previous: , Up: gtroff Output   [Contents][Index]

+
+

6.1.4 Output Language Compatibility

+ +

The intermediate output language of AT&T troff was +first documented in A Typesetter-independent TROFF, by Brian +Kernighan, and by 1992 the AT&T troff manual was +updated to incorprate a description of it. +

+

The GNU troff intermediate output format is compatible with this +specification except for the following features. +

+
    +
  • The classical quasi-device independence is not yet implemented. + +
  • The old hardware was very different from what we use today. So the +groff devices are also fundamentally different from the ones +in AT&T troff. For example, the AT&T +PostScript device is called post and has a resolution of only 720 +units per inch, suitable for printers 20 years ago, while groff’s +ps device has a resolution of 72000 units per inch. Maybe, by +implementing some rescaling mechanism similar to the classical +quasi-device independence, groff could emulate AT&T’s +post device. + +
  • The B-spline command ‘D~’ is correctly handled by the intermediate +output parser, but the drawing routines aren’t implemented in some of +the postprocessor programs. + +
  • The argument of the commands ‘s’ and ‘x H’ has the +implicit unit scaled point ‘z’ in gtroff, while +AT&T troff has point (‘p’). This isn’t an +incompatibility but a compatible extension, for both units coincide for +all devices without a sizescale parameter in the DESC +file, including all postprocessors from AT&T and +groff’s text devices. The few groff devices with a +sizescale parameter either do not exist for AT&T +troff, have a different name, or seem to have a different +resolution. So conflicts are very unlikely. + +
  • The position changing after the commands ‘Dp’, ‘DP’, and +‘Dt’ is illogical, but as old versions of gtroff used this +feature it is kept for compatibility reasons. + + +
+ + + +
+
+
+
+
+

+Previous: , Up: File Formats   [Contents][Index]

+
+

6.2 Device and Font Description Files

+ + + +

The groff font and output device description formats are slight +extensions of those used by AT&T device-independent +troff. In distinction to the AT&T implementation, +groff lacks a binary format; all files are text +files.125 The device and font description files for a device name +are stored in a devname directory. The device description +file is called DESC, and, for each font supported by the device, +a font description file is called f, where +f is usually an abbreviation of a font’s name and/or style. +For example, the ps (PostScript) device has groff font +description files for Times roman (TR) and Zapf Chancery Medium +italic (ZCMI), among many others, while the utf8 device +(for terminal emulators) has only font descriptions for the roman, +italic, bold, and bold-italic styles (R, I, B, and +BI, respectively). +

+

Device and font description files are read both by the formatter, GNU +troff, and by output drivers. The programs delegate these files’ +processing to an internal library, libgroff, ensuring their +consistent interpretation. +

+ + + +
+
+
+

+Next: , Previous: , Up: Device and Font Description Files   [Contents][Index]

+
+

6.2.1 DESC File Format

+ + + + +

The DESC file contains a series of directives; each begins a +line. Their order is not important, with two exceptions: (1) the +res directive must precede any papersize directive; and +(2) the charset directive must come last (if at all). If a +directive name is repeated, later entries in the file override previous +ones (except that the paper dimensions are computed based on the +res directive last seen when papersize is encountered). +Spaces and/or tabs separate words and are ignored at line boundaries. + + + +Comments start with the ‘#’ character and extend to the end of a +line. Empty lines are ignored. +

+
+
family fam
+

The default font family is fam. +

+
+
fonts n F1 … Fn
+

Fonts F1, …, Fn are mounted at font positions +m+1, …, m+n where m is the number of +styles (see below). This directive may extend over more than one +line. A font name of 0 causes no font to be mounted at the +corresponding position. +

+
+
hor n
+
+ + + + +

The horizontal motion quantum is n basic units. All +horizontal quantities are rounded to multiples of n. +

+
+
image_generator program
+
+ +

Use program to generate PNG images from PostScript input. Under +GNU/Linux, this is usually gs, but under other systems (notably +Cygwin) it might be set to another name. The grohtml driver uses +this directive. +

+
+
paperlength n
+

The vertical dimension of the output medium is n basic units +(deprecated: use papersize instead). +

+
+
papersize format-or-dimension-pair-or-file-name …
+

The dimensions of the output medium are as according to the +argument, which is either a standard paper format, a pair of dimensions, +or the name of a plain text file containing either of the foregoing. +

+

Recognized paper formats are the ISO and DIN formats +A0–A7, B0–B7, C0–C7, +D0–D7; the U.S. paper types letter, +legal, tabloid, ledger, statement, and +executive; and the envelope formats com10, monarch, +and DL. Matching is performed without regard for lettercase. +

+

Alternatively, the argument can be a custom paper format in the format +length,width (with no spaces before or after the +comma). Both length and width must have a unit appended; +valid units are ‘i’ for inches, ‘c’ for centimeters, ‘p’ +for points, and ‘P’ for picas. Example: ‘12c,235p’. An +argument that starts with a digit is always treated as a custom paper +format. +

+

Finally, the argument can be a file name (e.g., /etc/papersize); +if the file can be opened, the first line is read and a match attempted +against each of the other forms. No comment syntax is supported. +

+

More than one argument can be specified; +each is scanned in turn and the first valid paper specification used. +

+
+
paperwidth n
+

The horizontal dimension of the output medium is n basic +units (deprecated: use papersize instead). +

+
+
pass_filenames
+

Direct GNU troff to emit the name of the source file being +processed. This is achieved with the intermediate output command +‘x F’, which grohtml interprets. +

+
+
postpro program
+

Use program as the postprocessor. +

+
+
prepro program
+

Use program as a preprocessor. The html and xhtml +output devices use this directive. +

+
+
print program
+

Use program as a spooler program for printing. If omitted, the +-l and -L options of groff are ignored. +

+
+
res n
+
+ +

The device resolution is n basic units per inch. +

+
+
sizes s1 … sn 0
+

The device has fonts at s1, …, sn scaled points (see +below). The list of sizes must be terminated by 0. Each +si can also be a range of sizes m–n. The list can +extend over more than one line. +

+
+
sizescale n
+

A typographical point is subdivided into n scaled points. +The default is 1. See Using Fractional Type Sizes. +

+
+
styles S1 … Sm
+

The first m mounting positions are associated with styles +S1, …, Sm. +

+
+
tcommand
+

The postprocessor can handle the ‘t’ and ‘u’ intermediate +output commands. +

+
+
unicode
+

The output device supports the complete Unicode repertoire. This +directive is useful only for devices that produce character entities +instead of glyphs. +

+

If unicode is present, no charset section is required in +the font description files since the Unicode handling built into +groff is used. However, if there are entries in a font +description file’s charset section, they either override the +default mappings for those particular characters or add new mappings +(normally for composite characters). +

+

The utf8, html, and xhtml output devices use this +directive. +

+
+
unitwidth n
+

Quantities in the font description files are in basic units for fonts +whose type size is n scaled points. +

+
+
unscaled_charwidths
+

Make the font handling module always return unscaled character widths. +The grohtml driver uses this directive. +

+
+
use_charnames_in_special
+

GNU troff should encode special characters inside device control +commands; see Postprocessor Access. The grohtml driver +uses this directive. +

+
+
vert n
+
+ + + + +

The vertical motion quantum is n basic units. All vertical +quantities are rounded to multiples of n. +

+
+
charset
+

This line and everything following it in the file are ignored. It is +recognized for compatibility with other troff implementations. +In GNU troff, character set repertoire is described on a +per-font basis. +

+
+ + + + +

GNU troff recognizes but ignores the directives spare1, +spare2, and biggestfont. +

+

The res, unitwidth, fonts, and sizes lines +are mandatory. Directives not listed above are ignored by GNU +troff but may be used by postprocessors to obtain further +information about the device. +

+ +
+
+
+
+

+Previous: , Up: Device and Font Description Files   [Contents][Index]

+
+

6.2.2 Font Description File Format

+ + + + + +

On typesetting output devices, each font is typically available at +multiple sizes. While paper measurements in the device description file +are in absolute units, measurements applicable to fonts must be +proportional to the type size. groff achieves this using the +precedent set by AT&T device-independent troff: one +font size is chosen as a norm, and all others are scaled linearly +relative to that basis. The “unit width” is the number of basic units +per point when the font is rendered at this nominal size. +

+

For instance, groff’s lbp device uses a unitwidth +of 800. Its Times roman font ‘TR’ has a spacewidth +of 833; this is also the width of its comma, period, centered +period, and mathematical asterisk, while its ‘M’ is 2,963 basic +units. Thus, an ‘M’ on the lbp device is 2,963 basic units +wide at a notional type size of 800 points.126 +

+

A font description file has two sections. The first is a sequence of +directives, and is parsed similarly to the DESC file described +above. Except for the directive names that begin the second section, +their ordering is immaterial. Later directives of the same name +override earlier ones, spaces and tabs are handled in the same way, + + + +and the same comment syntax is supported. Empty lines are ignored +throughout. +

+
+
name f
+

The name of the font is f. ‘DESC’ is an invalid font +name. Simple integers are valid, but their use is +discouraged.127 +

+
+
spacewidth n
+

The width of an unadjusted inter-word space is n basic units. +

+
+ +

The directives above must appear in the first section; those below are +optional. +

+
+
slant n
+

The font’s glyphs have a slant of n degrees; a positive +n slants in the direction of text flow. +

+
+
ligatures lig1 … lign [0]
+

Glyphs lig1, …, lign are ligatures; possible ligatures +are ‘ff’, ‘fi’, ‘fl’, ‘ffi’ and ‘ffl’. For +compatibility with other troff implementations, the list of +ligatures may be terminated with a 0. The list of ligatures +must not extend over more than one line. +

+
+
special
+
+

The font is special: when a glyph is requested that is not present +in the current font, it is sought in any mounted fonts that bear this +property. +

+
+ +

Other directives in this section are ignored by GNU troff, but +may be used by postprocessors to obtain further information about the +font. +

+

The second section contains one or two subsections. These can appear in +either order; the first one encountered commences the second section. +Each starts with a directive on a line by itself. A charset +subsection is mandatory unless the associated DESC file contains +the unicode directive. Another subsection, kernpairs, +is optional. +

+ +

The directive charset starts the character set +subsection.128 It precedes a series +of glyph descriptions, one per line. Each such glyph description +comprises a set of fields separated by spaces or tabs and organized as +follows. +

+
+

name metrics type code [entity-name] +[-- comment] +

+ + + + + + + + +

name identifies the glyph: +if name is a printable character c, it corresponds to +the troff ordinary character c. If name is a +multi-character sequence not beginning with \, it corresponds to +the GNU troff special character escape sequence +‘\[name]’. A name consisting of three minus signs, +‘---’, is special and indicates that the glyph is unnamed: such +glyphs can be accessed only by the \N escape sequence in +troff. A special character named ‘---’ can still be defined +using char and similar requests. The name ‘\-’ +defines the minus sign glyph. Finally, name can be the +unbreakable one-sixth and one-twelfth space escape sequences, \| +and \^ (“thin” and “hair” spaces, respectively), in which +case only the width metric described below is interpreted; a font can +thus customize the widths of these spaces. +

+

The form of the metrics field is as follows. +

+
+
width[,[height[,[depth[,[italic-correction
+  [,[left-italic-correction[,[subscript-correction]]]]]]]]]]
+
+ +

There must not be any spaces, tabs, or newlines between these +subfields (which have been split here into two lines only for +better legibility). The subfields are in basic units expressed as +decimal integers. Unspecified subfields default to 0. +Since there is no associated binary format, these values are not +required to fit into the C language data type ‘char’ as they are in +AT&T device-independent troff. +

+

The width subfield gives the width of the glyph. The height +subfield gives the height of the glyph (upward is positive); if a glyph +does not extend above the baseline, it should be given a zero height, +rather than a negative height. The depth subfield gives the depth +of the glyph, that is, the distance below the baseline to which the +glyph extends (downward is positive); if a glyph does not extend below +the baseline, it should be given a zero depth, rather than a negative +depth. Italic corrections are relevant to glyphs in italic or oblique +styles. The italic-correction is the amount of space that should +be added after an oblique glyph to be followed immediately by an upright +glyph. The left-italic-correction is the amount of space that +should be added before an oblique glyph to be preceded immediately by an +upright glyph. The subscript-correction is the amount of space +that should be added after an oblique glyph to be followed by a +subscript; it should be less than the italic correction. +

+

For fonts used with typesetting devices, the type field gives a +featural description of the glyph: it is a bit mask recording whether +the glyph is an ascender, descender, both, or neither. When a \w +escape sequence is interpolated, these values are bitwise or-ed +together for each glyph and stored in the nr register. In font +descriptions for terminal devices, all glyphs might have a type of zero, +regardless of their appearance. +

+
+
0
+

means the glyph lies entirely between the baseline and a horizontal line +at the “x-height” of the font; typical examples are ‘a’, +‘c’, and ‘x’; +

+
+
1
+

means the glyph descends below the baseline, like ‘p’; +

+
+
2
+

means the glyph ascends above the font’s x-height, like ‘A’ or +‘b’; and +

+
+
3
+

means the glyph is both an ascender and a descender—this is true of +parentheses in some fonts. +

+
+ +

The code field gives a numeric identifier that the postprocessor +uses to render the glyph. The glyph can be specified to troff +using this code by means of the \N escape sequence. code +can be any integer.129 +

+

The entity-name field defines an identifier for the glyph that the +postprocessor uses to print the GNU troff glyph name. This +field is optional; it was introduced so that the grohtml output +driver could encode its character set. For example, the glyph +‘\[Po]’ is represented by ‘&pound;’ in HTML 4.0. +For efficiency, these data are now compiled directly into +grohtml. grops uses the field to build sub-encoding +arrays for PostScript fonts containing more than 256 glyphs. Anything +on the line after the entity-name field or ‘--’ is ignored. +

+

A line in the charset section can also have the form +

+
+
name "
+
+ +

identifying name as another name for the glyph mentioned in the +preceding line. Such aliases can be chained. +

+ +

The directive kernpairs starts a list of kerning adjustments to +be made to adjacent glyph pairs from this font. It contains a sequence +of lines formatted as follows. +

+
+
g1 g2 n
+
+ +

The foregoing means that when glyph g1 is typeset immediately +before g2, the space between them should be increased +by n. Most kerning pairs should have a negative value +for n. +

+ + + + +
+
+
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

Appendix A Copying This Manual

+ +
Version 1.3, 3 November 2008 +
+ +
+
Copyright © 2000-2018 Free Software Foundation, Inc.
+http://fsf.org/
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+ +
    +
  1. PREAMBLE + +

    The purpose of this License is to make a manual, textbook, or other +functional and useful document free in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. +

    +

    This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. +

    +

    We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. +

    +
  2. APPLICABILITY AND DEFINITIONS + +

    This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The “Document”, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. +

    +

    A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. +

    +

    A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document’s overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. +

    +

    The “Invariant Sections” are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. +

    +

    The “Cover Texts” are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. +

    +

    A “Transparent” copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not “Transparent” is called “Opaque”. +

    +

    Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or PDF produced by some word processors for +output purposes only. +

    +

    The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work’s title, +preceding the beginning of the body of the text. +

    +

    The “publisher” means any person or entity that distributes copies +of the Document to the public. +

    +

    A section “Entitled XYZ” means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as “Acknowledgements”, +“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” +of such a section when you modify the Document means that it remains a +section “Entitled XYZ” according to this definition. +

    +

    The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. +

    +
  3. VERBATIM COPYING + +

    You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. +

    +

    You may also lend copies, under the same conditions stated above, and +you may publicly display copies. +

    +
  4. COPYING IN QUANTITY + +

    If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document’s license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. +

    +

    If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. +

    +

    If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. +

    +

    It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. +

    +
  5. MODIFICATIONS + +

    You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: +

    +
      +
    1. Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +
    2. List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +
    3. State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +
    4. Preserve all the copyright notices of the Document. + +
    5. Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +
    6. Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +
    7. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document’s license notice. + +
    8. Include an unaltered copy of this License. + +
    9. Preserve the section Entitled “History”, Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled “History” in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +
    10. Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the “History” section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +
    12. Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +
    13. Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + +
    14. Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + +
    15. Preserve any Warranty Disclaimers. +
    + +

    If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version’s license notice. +These titles must be distinct from any other section titles. +

    +

    You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. +

    +

    You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +

    +

    The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. +

    +
  6. COMBINING DOCUMENTS + +

    You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. +

    +

    The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. +

    +

    In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” +

    +
  7. COLLECTIONS OF DOCUMENTS + +

    You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. +

    +

    You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. +

    +
  8. AGGREGATION WITH INDEPENDENT WORKS + +

    A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an “aggregate” if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation’s users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. +

    +

    If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document’s Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. +

    +
  9. TRANSLATION + +

    Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. +

    +

    If a section in the Document is Entitled “Acknowledgements”, +“Dedications”, or “History”, the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. +

    +
  10. TERMINATION + +

    You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. +

    +

    However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. +

    +

    Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. +

    +

    Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. +

    +
  11. FUTURE REVISIONS OF THIS LICENSE + +

    The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. +

    +

    Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy’s public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. +

    +
  12. RELICENSING + +

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +“Massive Multiauthor Collaboration” (or “MMC”) contained in the +site means any set of copyrightable works thus published on the MMC +site. +

    +

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. +

    +

    “Incorporate” means to publish or republish a Document, in whole or +in part, as part of another Document. +

    +

    An MMC is “eligible for relicensing” if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. +

    +

    The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. +

    +
+ +

ADDENDUM: How to use this License for your documents

+ +

To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: +

+
+
  Copyright (C)  year  your name.
+  Permission is granted to copy, distribute and/or modify this document
+  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, no Front-Cover Texts, and no Back-Cover
+  Texts.  A copy of the license is included in the section entitled ``GNU
+  Free Documentation License''.
+
+ +

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with…Texts.” line with this: +

+
+
    with the Invariant Sections being list their titles, with
+    the Front-Cover Texts being list, and with the Back-Cover Texts
+    being list.
+
+ +

If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. +

+

If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. +

+ + + + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

Appendix B Request Index

+ +

Request names appear without a leading control character; the defaults +are . for the regular control character and ' for the +no-break control character. +

+
+
Jump to:   A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +K +   +L +   +M +   +N +   +O +   +P +   +R +   +S +   +T +   +U +   +V +   +W +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
A
ab: Debugging
ad: Manipulating Filling and Adjustment
af: Assigning Register Formats
aln: Setting Registers
als: Strings
am: Writing Macros
am1: Writing Macros
ami: Writing Macros
ami1: Writing Macros
as: Strings
as1: Strings
asciify: Diversions
B
backtrace: Debugging
bd: Artificial Fonts
blm: Blank Line Traps
box: Diversions
boxa: Diversions
bp: Page Control
br: Manipulating Filling and Adjustment
break: while
brp: Manipulating Filling and Adjustment
C
c2: Control Characters
cc: Control Characters
ce: Manipulating Filling and Adjustment
cf: I/O
cflags: Using Symbols
ch: Page Location Traps
char: Using Symbols
chop: Strings
class: Character Classes
close: I/O
color: Colors
composite: Using Symbols
continue: while
cp: Compatibility Mode
cs: Artificial Fonts
cu: Artificial Fonts
D
da: Diversions
de: Writing Macros
de1: Writing Macros
defcolor: Colors
dei: Writing Macros
dei1: Writing Macros
device: Postprocessor Access
devicem: Postprocessor Access
di: Diversions
do: Compatibility Mode
ds: ms Document Control Settings
ds: Strings
ds1: Strings
dt: Diversion Traps
E
ec: Using Escape Sequences
ecr: Using Escape Sequences
ecs: Using Escape Sequences
el: if-else
em: End-of-input Traps
eo: Using Escape Sequences
ev: Environments
evc: Environments
ex: Debugging
F
fam: Font Families
fc: Fields
fchar: Using Symbols
fcolor: Colors
fi: Manipulating Filling and Adjustment
fl: Debugging
fp: Font Positions
fschar: Using Symbols
fspecial: Special Fonts
ft: Selecting Fonts
ftr: Selecting Fonts
fzoom: Selecting Fonts
G
gcolor: Colors
H
hc: Manipulating Hyphenation
hcode: Manipulating Hyphenation
hla: Manipulating Hyphenation
hlm: Manipulating Hyphenation
hpf: Manipulating Hyphenation
hpfa: Manipulating Hyphenation
hpfcode: Manipulating Hyphenation
hw: Manipulating Hyphenation
hy: Manipulating Hyphenation
hym: Manipulating Hyphenation
hys: Manipulating Hyphenation
I
ie: if-else
if: if-then
ig: Comments
in: Line Layout
it: Input Line Traps
itc: Input Line Traps
K
kern: Ligatures and Kerning
L
lc: Leaders
length: Strings
lf: Debugging
lg: Ligatures and Kerning
linetabs: Tabs and Fields
ll: Line Layout
ls: Manipulating Spacing
lsm: Leading Space Traps
lt: Page Layout
M
mc: Miscellaneous
mk: Page Motions
mso: I/O
msoquiet: I/O
N
na: Manipulating Filling and Adjustment
ne: Page Control
nf: Manipulating Filling and Adjustment
nh: Manipulating Hyphenation
nm: Miscellaneous
nn: Miscellaneous
nop: if-then
nr: ms Document Control Settings
nr: Setting Registers
nr: Setting Registers
nr: Auto-increment
nroff: troff and nroff Modes
ns: Manipulating Spacing
nx: I/O
O
open: I/O
opena: I/O
os: Page Control
output: Diversions
P
pc: Page Layout
pev: Debugging
pi: I/O
pl: Page Layout
pm: Debugging
pn: Page Layout
pnr: Debugging
po: Line Layout
ps: Changing the Type Size
psbb: Miscellaneous
pso: I/O
ptr: Debugging
pvs: Changing the Vertical Spacing
R
rchar: Using Symbols
rd: I/O
return: Writing Macros
rfschar: Using Symbols
rj: Manipulating Filling and Adjustment
rm: Strings
rn: Strings
rnn: Setting Registers
rr: Setting Registers
rs: Manipulating Spacing
rt: Page Motions
S
schar: Using Symbols
shc: Manipulating Hyphenation
shift: Parameters
sizes: Changing the Type Size
so: I/O
soquiet: I/O
sp: Manipulating Spacing
special: Special Fonts
spreadwarn: Debugging
ss: Manipulating Filling and Adjustment
stringdown: Strings
stringup: Strings
sty: Font Families
substring: Strings
sv: Page Control
sy: I/O
T
ta: Tabs and Fields
tag: Postprocessor Access
taga: Postprocessor Access
tc: Tabs and Fields
ti: Line Layout
tkf: Ligatures and Kerning
tl: Page Layout
tm: Debugging
tm1: Debugging
tmc: Debugging
tr: Character Translations
trf: I/O
trin: Character Translations
trnt: Character Translations
troff: troff and nroff Modes
U
uf: Artificial Fonts
ul: Artificial Fonts
unformat: Diversions
V
vpt: Vertical Position Traps
vs: Changing the Vertical Spacing
W
warn: Debugging
warnscale: Debugging
wh: Page Location Traps
while: while
write: I/O
writec: I/O
writem: I/O
+
Jump to:   A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +K +   +L +   +M +   +N +   +O +   +P +   +R +   +S +   +T +   +U +   +V +   +W +   +
+
+ + + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

Appendix C Escape Sequence Index

+ +

The escape character, \ by default, is always followed by at +least one more input character, making an escape sequence. Any +input token \X with X not in the list below emits a +warning and interpolates glyph X. Note the entries for \., +which may be obscured by the leader dots, and for \RET and +\SP, which are sorted alphabetically, not by code point +order. +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
\
\: Using Escape Sequences
\: Using Symbols
\!: Diversions
\": Comments
\#: Comments
\$: Parameters
\$*: Parameters
\$0: Parameters
\$@: Parameters
\$^: Parameters
\%: Manipulating Hyphenation
\&: Dummy Characters
\': Using Symbols
\(: Using Symbols
\): Dummy Characters
\*: Strings
\,: Italic Corrections
\-: Using Symbols
\.: Copy Mode
\/: Italic Corrections
\0: Page Motions
\:: Manipulating Hyphenation
\?: Diversions
\A: Identifiers
\a: Leaders
\B: Numeric Expressions
\b: Drawing Geometric Objects
\c: Line Continuation
\C: Using Symbols
\d: Page Motions
\D: Drawing Geometric Objects
\e: Using Escape Sequences
\E: Copy Mode
\f: Selecting Fonts
\F: Font Families
\g: Assigning Register Formats
\H: Artificial Fonts
\h: Page Motions
\k: Page Motions
\l: Drawing Geometric Objects
\L: Drawing Geometric Objects
\m: Colors
\M: Colors
\n: Interpolating Registers
\n: Auto-increment
\N: Using Symbols
\newline: Line Continuation
\o: Page Motions
\O: Suppressing Output
\p: Manipulating Filling and Adjustment
\R: Setting Registers
\R: Setting Registers
\r: Page Motions
\RET: Line Continuation
\S: Artificial Fonts
\s: Changing the Type Size
\SP: Page Motions
\space: Page Motions
\t: Tabs and Fields
\u: Page Motions
\v: Page Motions
\V: I/O
\w: Page Motions
\x: Manipulating Spacing
\X: Postprocessor Access
\Y: Postprocessor Access
\z: Page Motions
\Z: Page Motions
\[: Using Symbols
\\: Copy Mode
\^: Page Motions
\_: Using Symbols
\`: Using Symbols
\{: Conditional Blocks
\{: Conditional Blocks
\|: Page Motions
\}: Conditional Blocks
\~: Manipulating Filling and Adjustment
+
+ + + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

Appendix D Operator Index

+ +
+
Jump to:   ! +   +% +   +& +   +( +   +) +   +* +   ++ +   +- +   +/ +   +: +   +; +   +< +   += +   +> +   +| +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
!
!: Numeric Expressions
%
%: Numeric Expressions
&
&: Numeric Expressions
(
(: Numeric Expressions
)
): Numeric Expressions
*
*: Numeric Expressions
+
+: Numeric Expressions
+: Numeric Expressions
+ (unary): Numeric Expressions
-
-: Numeric Expressions
-: Numeric Expressions
- (unary): Numeric Expressions
/
/: Numeric Expressions
:
:: Numeric Expressions
;
;: Numeric Expressions
<
<: Numeric Expressions
<=: Numeric Expressions
<?: Numeric Expressions
=
=: Numeric Expressions
==: Numeric Expressions
>
>: Numeric Expressions
>=: Numeric Expressions
>?: Numeric Expressions
|
|: Numeric Expressions
+
Jump to:   ! +   +% +   +& +   +( +   +) +   +* +   ++ +   +- +   +/ +   +: +   +; +   +< +   += +   +> +   +| +
+
+ + + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

Appendix E Register Index

+ +

The macro package or program a specific register belongs to is appended +in brackets. +

+

A register name x consisting of exactly one character can be +accessed as ‘\nx’. A register name xx consisting of exactly +two characters can be accessed as ‘\n(xx’. Register names +xxx of any length can be accessed as ‘\n[xxx]’. +

+
+
Jump to:   $ +   +% +   +. +   +
+C +   +D +   +F +   +G +   +H +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +Y +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
$
$$: Built-in Registers
%
%: Page Layout
%: Page Control
.
.$: Parameters
.A: Built-in Registers
.a: Manipulating Spacing
.b: Artificial Fonts
.br: Control Characters
.c: Built-in Registers
.C: Compatibility Mode
.cdp: Environments
.ce: Manipulating Filling and Adjustment
.cht: Environments
.color: Colors
.cp: Compatibility Mode
.csk: Environments
.d: Diversions
.ev: Environments
.F: Built-in Registers
.f: Font Positions
.fam: Font Families
.fn: Selecting Fonts
.fp: Font Positions
.g: Built-in Registers
.H: Motion Quanta
.h: Diversions
.height: Artificial Fonts
.hla: Manipulating Hyphenation
.hlc: Manipulating Hyphenation
.hlm: Manipulating Hyphenation
.hy: Manipulating Hyphenation
.hym: Manipulating Hyphenation
.hys: Manipulating Hyphenation
.i: Line Layout
.in: Line Layout
.int: Line Continuation
.j: Manipulating Filling and Adjustment
.k: Page Motions
.kern: Ligatures and Kerning
.L: Manipulating Spacing
.l: Line Layout
.lg: Ligatures and Kerning
.linetabs: Tabs and Fields
.ll: Line Layout
.lt: Page Layout
.m: Colors
.M: Colors
.n: Environments
.ne: Page Location Traps
.nm: Miscellaneous
.nn: Miscellaneous
.ns: Manipulating Spacing
.o: Line Layout
.O: Suppressing Output
.P: Built-in Registers
.p: Page Layout
.pe: Page Location Traps
.pn: Page Layout
.ps: Using Fractional Type Sizes
.psr: Using Fractional Type Sizes
.pvs: Changing the Vertical Spacing
.R: Built-in Registers
.rj: Manipulating Filling and Adjustment
.s: Changing the Type Size
.slant: Artificial Fonts
.sr: Using Fractional Type Sizes
.ss: Manipulating Filling and Adjustment
.sss: Manipulating Filling and Adjustment
.sty: Font Families
.T: Built-in Registers
.t: Page Location Traps
.tabs: Tabs and Fields
.trunc: Page Location Traps
.U: Built-in Registers
.u: Manipulating Filling and Adjustment
.V: Motion Quanta
.v: Changing the Vertical Spacing
.vpt: Vertical Position Traps
.w: Environments
.warn: Debugging
.x: Built-in Registers
.y: Built-in Registers
.Y: Built-in Registers
.z: Diversions
.zoom: Selecting Fonts
C
c.: Built-in Registers
ct: Page Motions
D
DD [ms]: ms Document Control Settings
DI [ms]: ms Document Control Settings
dl: Diversions
dn: Diversions
dw: Built-in Registers
dy: Built-in Registers
F
FF [ms]: ms Document Control Settings
FI [ms]: ms Document Control Settings
FM [ms]: ms Document Control Settings
FPD [ms]: ms Document Control Settings
FPS [ms]: ms Document Control Settings
FVS [ms]: ms Document Control Settings
G
GROWPS [ms]: ms Document Control Settings
GS [ms]: Differences from AT&T ms
H
HM [ms]: ms Document Control Settings
HORPHANS [ms]: ms Document Control Settings
hours: Built-in Registers
hp: Page Motions
HY [ms]: ms Document Control Settings
L
LL [ms]: ms Document Control Settings
llx: Miscellaneous
lly: Miscellaneous
ln: Miscellaneous
lsn: Leading Space Traps
lss: Leading Space Traps
LT [ms]: ms Document Control Settings
M
MINGW [ms]: ms Document Control Settings
minutes: Built-in Registers
mo: Built-in Registers
N
nl: Page Control
O
opmaxx: Suppressing Output
opmaxy: Suppressing Output
opminx: Suppressing Output
opminy: Suppressing Output
P
PD [ms]: ms Document Control Settings
PI [ms]: ms Document Control Settings
PO [ms]: ms Document Control Settings
PORPHANS [ms]: ms Document Control Settings
PS [ms]: ms Document Control Settings
PSINCR [ms]: ms Document Control Settings
Q
QI [ms]: ms Document Control Settings
R
rsb: Page Motions
rst: Page Motions
S
sb: Page Motions
seconds: Built-in Registers
skw: Page Motions
slimit: Debugging
ssc: Page Motions
st: Page Motions
systat: I/O
T
TC-MARGIN [ms]: ms Document Control Settings
U
urx: Miscellaneous
ury: Miscellaneous
V
VS [ms]: ms Document Control Settings
Y
year: Built-in Registers
yr: Built-in Registers
+
Jump to:   $ +   +% +   +. +   +
+C +   +D +   +F +   +G +   +H +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +Y +   +
+
+ + + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

Appendix F Macro Index

+ +

The macro package a specific macro belongs to is appended in brackets. +They appear without the leading control character (normally ‘.’). +

+
+
Jump to:   1 +   +2 +   +[ +   +] +   +
+A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +K +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +X +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
1
1C [ms]: ms Multiple Columns
2
2C [ms]: ms Multiple Columns
[
[ [ms]: ms Insertions
]
] [ms]: ms Insertions
A
AB [ms]: ms Document Description Macros
AE [ms]: ms Document Description Macros
AI [ms]: ms Document Description Macros
AM [ms]: ms Legacy Features
AU [ms]: ms Document Description Macros
B
B [ms]: Typeface and decoration
B1 [ms]: ms keeps and displays
B2 [ms]: ms keeps and displays
BD [ms]: ms keeps and displays
BI [ms]: Typeface and decoration
BT [man]: Optional man extensions
BX [ms]: Typeface and decoration
C
CD [ms]: ms keeps and displays
CT [man]: Optional man extensions
CW [man]: Optional man extensions
CW [ms]: Typeface and decoration
D
DA [ms]: ms Document Description Macros
De [man]: Optional man extensions
DE [ms]: ms keeps and displays
Ds [man]: Optional man extensions
DS [ms]: ms keeps and displays
DS [ms]: ms keeps and displays
DS [ms]: ms keeps and displays
DS [ms]: ms keeps and displays
DS [ms]: ms keeps and displays
E
EE [man]: Optional man extensions
EF [ms]: ms Headers and Footers
EH [ms]: ms Headers and Footers
EN [ms]: ms Insertions
EQ [ms]: ms Insertions
EX [man]: Optional man extensions
F
FE [ms]: ms Footnotes
FS [ms]: ms Footnotes
G
G [man]: Optional man extensions
GL [man]: Optional man extensions
H
HB [man]: Optional man extensions
I
I [ms]: Typeface and decoration
ID [ms]: ms keeps and displays
IP [ms]: Paragraphs in ms
K
KE [ms]: ms keeps and displays
KF [ms]: ms keeps and displays
KS [ms]: ms keeps and displays
L
LD [ms]: ms keeps and displays
LG [ms]: Typeface and decoration
LP [ms]: Paragraphs in ms
M
MC [ms]: ms Multiple Columns
MS [man]: Optional man extensions
N
ND [ms]: ms Document Description Macros
NE [man]: Optional man extensions
NH [ms]: Headings in ms
NL [ms]: Typeface and decoration
NT [man]: Optional man extensions
O
OF [ms]: ms Headers and Footers
OH [ms]: ms Headers and Footers
P
P1 [ms]: ms Headers and Footers
PE [ms]: ms Insertions
PF [ms]: ms Insertions
PN [man]: Optional man extensions
Pn [man]: Optional man extensions
PP [ms]: Paragraphs in ms
PS [ms]: ms Insertions
PT [man]: Optional man extensions
PX [ms]: ms TOC
Q
QE [ms]: Paragraphs in ms
QP [ms]: Paragraphs in ms
QS [ms]: Paragraphs in ms
R
R [man]: Optional man extensions
R [ms]: Typeface and decoration
RD [ms]: ms keeps and displays
RE [ms]: Indented regions in ms
RN [man]: Optional man extensions
RP [ms]: ms Document Description Macros
RS [ms]: Indented regions in ms
S
SH [ms]: Headings in ms
SM [ms]: Typeface and decoration
T
TA [ms]: Tab Stops in ms
TB [man]: Optional man extensions
TC [ms]: ms TOC
TE [ms]: ms Insertions
TL [ms]: ms Document Description Macros
TS [ms]: ms Insertions
U
UL [ms]: Typeface and decoration
V
VE [man]: Optional man extensions
VS [man]: Optional man extensions
X
XA [ms]: ms TOC
XE [ms]: ms TOC
XH [ms]: ms TOC
XH-REPLACEMENT [ms]: ms TOC
XH-UPDATE-TOC [ms]: ms TOC
XN [ms]: ms TOC
XN-INIT [ms]: ms TOC
XN-REPLACEMENT [ms]: ms TOC
XP [ms]: Paragraphs in ms
XS [ms]: ms TOC
+
Jump to:   1 +   +2 +   +[ +   +] +   +
+A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +K +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +X +   +
+
+ + + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

Appendix G String Index

+ +

The macro package or program a that defines or uses each string is +appended in brackets. (Only one string, .T, is defined by the +troff formatter itself.) See Strings. +

+ +
+
Jump to:   ! +   +' +   +* +   +, +   +- +   +. +   +/ +   +3 +   +8 +   +: +   +< +   +> +   +? +   +^ +   +_ +   +` +   +{ +   +} +   +~ +   +
+A +   +C +   +D +   +F +   +L +   +M +   +O +   +Q +   +R +   +S +   +T +   +U +   +V +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
!
! [ms]: ms Legacy Features
'
' [ms]: ms Legacy Features
' [ms]: ms Legacy Features
*
* [ms]: ms Footnotes
,
, [ms]: ms Legacy Features
, [ms]: ms Legacy Features
-
- [ms]: Typographical symbols in ms
.
. [ms]: ms Legacy Features
.T: Strings
.T: Strings
/
/ [ms]: ms Legacy Features
3
3 [ms]: ms Legacy Features
8
8 [ms]: ms Legacy Features
:
: [ms]: ms Legacy Features
: [ms]: ms Legacy Features
<
< [ms]: Typeface and decoration
>
> [ms]: Typeface and decoration
?
? [ms]: ms Legacy Features
^
^ [ms]: ms Legacy Features
^ [ms]: ms Legacy Features
_
_ [ms]: ms Legacy Features
`
` [ms]: ms Legacy Features
` [ms]: ms Legacy Features
{
{ [ms]: Typeface and decoration
}
} [ms]: Typeface and decoration
~
~ [ms]: ms Legacy Features
~ [ms]: ms Legacy Features
A
ABSTRACT [ms]: ms language and localization
ae [ms]: ms Legacy Features
Ae [ms]: ms Legacy Features
C
C [ms]: ms Legacy Features
CF [ms]: ms Document Control Settings
CH [ms]: ms Document Control Settings
D
d- [ms]: ms Legacy Features
D- [ms]: ms Legacy Features
F
FAM [ms]: ms Document Control Settings
FR [ms]: ms Document Control Settings
L
LF [ms]: ms Document Control Settings
LH [ms]: ms Document Control Settings
M
MONTH1 [ms]: ms language and localization
MONTH10 [ms]: ms language and localization
MONTH11 [ms]: ms language and localization
MONTH12 [ms]: ms language and localization
MONTH2 [ms]: ms language and localization
MONTH3 [ms]: ms language and localization
MONTH4 [ms]: ms language and localization
MONTH5 [ms]: ms language and localization
MONTH6 [ms]: ms language and localization
MONTH7 [ms]: ms language and localization
MONTH8 [ms]: ms language and localization
MONTH9 [ms]: ms language and localization
O
o [ms]: ms Legacy Features
oe [ms]: ms Legacy Features
OE [ms]: ms Legacy Features
Q
Q [ms]: Typographical symbols in ms
q [ms]: ms Legacy Features
R
REFERENCES [ms]: ms language and localization
RF [ms]: ms Document Control Settings
RH [ms]: ms Document Control Settings
S
SN [ms]: Headings in ms
SN-DOT [ms]: Headings in ms
SN-NO-DOT [ms]: Headings in ms
SN-STYLE [ms]: ms Document Control Settings
SN-STYLE [ms]: Headings in ms
T
th [ms]: ms Legacy Features
Th [ms]: ms Legacy Features
TOC [ms]: ms language and localization
U
U [ms]: Typographical symbols in ms
V
v [ms]: ms Legacy Features
+
Jump to:   ! +   +' +   +* +   +, +   +- +   +. +   +/ +   +3 +   +8 +   +: +   +< +   +> +   +? +   +^ +   +_ +   +` +   +{ +   +} +   +~ +   +
+A +   +C +   +D +   +F +   +L +   +M +   +O +   +Q +   +R +   +S +   +T +   +U +   +V +   +
+
+ + + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

Appendix H File Keyword Index

+ +
+
Jump to:   # +   +- +   +
+B +   +C +   +F +   +H +   +I +   +K +   +L +   +N +   +P +   +R +   +S +   +T +   +U +   +V +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
#
#: DESC File Format
#: Font Description File Format
-
---: Font Description File Format
B
biggestfont: DESC File Format
C
charset: DESC File Format
charset: Font Description File Format
F
family: Selecting Fonts
family: DESC File Format
fonts: Using Symbols
fonts: Special Fonts
fonts: DESC File Format
H
hor: DESC File Format
I
image_generator: DESC File Format
K
kernpairs: Font Description File Format
L
ligatures: Font Description File Format
N
name: Font Description File Format
P
paperlength: DESC File Format
papersize: DESC File Format
paperwidth: DESC File Format
pass_filenames: DESC File Format
postpro: DESC File Format
prepro: DESC File Format
print: DESC File Format
R
res: DESC File Format
S
sizes: DESC File Format
sizescale: DESC File Format
slant: Font Description File Format
spacewidth: Font Description File Format
spare1: DESC File Format
spare2: DESC File Format
special: Artificial Fonts
special: Font Description File Format
styles: Selecting Fonts
styles: Font Families
styles: DESC File Format
T
tcommand: DESC File Format
U
unicode: DESC File Format
unitwidth: DESC File Format
unscaled_charwidths: DESC File Format
use_charnames_in_special: Postprocessor Access
use_charnames_in_special: DESC File Format
V
vert: DESC File Format
+
Jump to:   # +   +- +   +
+B +   +C +   +F +   +H +   +I +   +K +   +L +   +N +   +P +   +R +   +S +   +T +   +U +   +V +   +
+
+ + + + +
+
+
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+

Appendix I Program and File Index

+ +
+
Jump to:   A +   +C +   +D +   +E +   +F +   +G +   +I +   +J +   +L +   +M +   +N +   +P +   +R +   +S +   +T +   +V +   +Z +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
A
an.tmac: man
C
changebar: Miscellaneous
composite.tmac: Using Symbols
cp1047.tmac: Input Encodings
cs.tmac: Manipulating Hyphenation
D
de.tmac: Manipulating Hyphenation
DESC: Selecting Fonts
DESC: Font Families
DESC: Using Symbols
DESC: Using Symbols
DESC: Special Fonts
diffmk: Miscellaneous
E
ec.tmac: Input Encodings
en.tmac: Manipulating Hyphenation
eqn: ms Insertions
F
fr.tmac: Manipulating Hyphenation
freeeuro.pfa: Input Encodings
G
gchem: Groff Options
gdiffmk: Miscellaneous
geqn: Groff Options
ggrn: Groff Options
gpic: Groff Options
grap: Groff Options
grefer: Groff Options
groff: Groff Options
gsoelim: Groff Options
gtbl: Groff Options
gtroff: Groff Options
I
it.tmac: Manipulating Hyphenation
J
ja.tmac: Manipulating Hyphenation
L
latin1.tmac: Input Encodings
latin2.tmac: Input Encodings
latin5.tmac: Input Encodings
latin9.tmac: Input Encodings
M
makeindex: Indexing
man.local: Optional man extensions
man.tmac: man
man.ultrix: Optional man extensions
N
nrchbar: Miscellaneous
P
papersize.tmac: Paper Format
perl: I/O
pic: ms Insertions
post-grohtml: Groff Options
pre-grohtml: Groff Options
preconv: Groff Options
R
refer: ms Insertions
S
soelim: Debugging
sv.tmac: Manipulating Hyphenation
T
tbl: ms Insertions
trace.tmac: Writing Macros
troffrc: Groff Options
troffrc: Paper Format
troffrc: Manipulating Hyphenation
troffrc: Manipulating Hyphenation
troffrc: troff and nroff Modes
troffrc-end: Groff Options
troffrc-end: Manipulating Hyphenation
troffrc-end: troff and nroff Modes
tty.tmac: troff and nroff Modes
tty.tmac: Line Layout
V
vtroff: Operators in Conditionals
Z
zh.tmac: Manipulating Hyphenation
+
Jump to:   A +   +C +   +D +   +E +   +F +   +G +   +I +   +J +   +L +   +M +   +N +   +P +   +R +   +S +   +T +   +V +   +Z +   +
+
+ + + + +
+
+
+
+

+Previous: , Up: GNU troff   [Contents][Index]

+
+

Appendix J Concept Index

+ +
+
Jump to:   " +   +% +   +& +   +' +   +( +   +) +   +* +   ++ +   +- +   +. +   +/ +   +8 +   +: +   +< +   += +   +> +   +[ +   +\ +   +] +   +| +   +
+A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +J +   +K +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +W +   +Y +   +Z +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
"
", as delimiter: Delimiters
", at end of sentence: Sentences
", at end of sentence: Using Symbols
", embedding in a macro argument: Calling Macros
%
%, as delimiter: Delimiters
&
&, as delimiter: Delimiters
'
', as a comment: Comments
', as delimiter: Delimiters
', at end of sentence: Sentences
', at end of sentence: Using Symbols
(
(, as delimiter: Delimiters
)
), as delimiter: Delimiters
), at end of sentence: Sentences
), at end of sentence: Using Symbols
*
*, as delimiter: Delimiters
*, at end of sentence: Sentences
*, at end of sentence: Using Symbols
+
+, and page motion: Numeric Expressions
+, as delimiter: Delimiters
-
-, and page motion: Numeric Expressions
-, as delimiter: Delimiters
.
., as delimiter: Delimiters
.h register, difference from nl: Diversions
.ps register, in comparison with .psr: Using Fractional Type Sizes
.s register, in comparison with .sr: Using Fractional Type Sizes
.S register, Plan 9 alias for .tabs: Tabs and Fields
.t register, and diversions: Diversion Traps
.tabs register, Plan 9 alias (.S): Tabs and Fields
.V register, and vs: Changing the Vertical Spacing
/
/, as delimiter: Delimiters
8
8-bit input: Font Description File Format
:
:, as delimiter: Delimiters
<
<, as delimiter: Delimiters
=
=, as delimiter: Delimiters
>
>, as delimiter: Delimiters
[
[, macro names starting with, and refer: Identifiers
\
\!, and copy mode: Diversions
\!, and output request: Diversions
\!, and trnt: Character Translations
\!, as delimiter: Delimiters
\!, as delimiter: Delimiters
\!, in top-level diversion: Diversions
\!, incompatibilities with AT&T troff: Other Differences
\!, incompatibilities with AT&T troff: Other Differences
\$, when reading text for a macro: Copy Mode
\%, and translations: Character Translations
\%, as delimiter: Delimiters
\%, as delimiter: Delimiters
\%, following \X or \Y: Manipulating Hyphenation
\%, in \X: Postprocessor Access
\%, incompatibilities with AT&T troff: Other Differences
\&, and glyph definitions: Using Symbols
\&, and translations: Character Translations
\&, as delimiter: Delimiters
\&, at end of sentence: Sentences
\&, in \X: Postprocessor Access
\&, incompatibilities with AT&T troff: Other Differences
\', and translations: Character Translations
\', as delimiter: Delimiters
\', as delimiter: Delimiters
\', incompatibilities with AT&T troff: Other Differences
\(, and translations: Character Translations
\), as delimiter: Delimiters
\), in \X: Postprocessor Access
\*, and warnings: Warnings
\*, incompatibilities with AT&T troff: Compatibility Mode
\*, when reading text for a macro: Copy Mode
\, disabling (eo): Using Escape Sequences
\, embedding in a macro argument: Calling Macros
\,, as delimiter: Delimiters
\- glyph, and cflags: Using Symbols
\-, and translations: Character Translations
\-, as delimiter: Delimiters
\-, as delimiter: Delimiters
\-, incompatibilities with AT&T troff: Other Differences
\/, as delimiter: Delimiters
\/, as delimiter: Delimiters
\0, as delimiter: Delimiters
\:, as delimiter: Delimiters
\:, as delimiter: Delimiters
\:, in \X: Postprocessor Access
\?, and copy mode: Operators in Conditionals
\?, and copy mode: Diversions
\?, as delimiter: Delimiters
\?, in top-level diversion: Diversions
\?, incompatibilities with AT&T troff: Other Differences
\a, and copy mode: Leaders
\a, and translations: Character Translations
\a, as delimiter: Delimiters
\A, delimiters allowed by: Delimiters
\A, incompatibilities with AT&T troff: Other Differences
\b, delimiters allowed by: Delimiters
\b, limitations of: Drawing Geometric Objects
\C, and translations: Character Translations
\c, as delimiter: Delimiters
\c, as delimiter: Delimiters
\c, incompatibilities with AT&T troff: Other Differences
\c, when filling disabled: Line Continuation
\c, when filling enabled: Line Continuation
\d, as delimiter: Delimiters
\D, delimiters allowed by: Delimiters
\e, and glyph definitions: Using Symbols
\e, and translations: Character Translations
\e, as delimiter: Delimiters
\E, as delimiter: Delimiters
\e, as delimiter: Delimiters
\e, incompatibilities with AT&T troff: Other Differences
\F, and changing fonts: Selecting Fonts
\f, and font translations: Selecting Fonts
\f, incompatibilities with AT&T troff: Compatibility Mode
\h, delimiters allowed by: Delimiters
\H, delimiters allowed by: Delimiters
\H, incompatibilities with AT&T troff: Compatibility Mode
\H, using + and - with: Numeric Expressions
\H, with fractional type sizes: Using Fractional Type Sizes
\l, and glyph definitions: Using Symbols
\L, and glyph definitions: Using Symbols
\l, delimiters allowed by: Delimiters
\L, delimiters allowed by: Delimiters
\N, and translations: Character Translations
\n, and warnings: Warnings
\N, delimiters allowed by: Delimiters
\n, incompatibilities with AT&T troff: Compatibility Mode
\n, when reading text for a macro: Copy Mode
\o, delimiters allowed by: Delimiters
\p, as delimiter: Delimiters
\p, as delimiter: Delimiters
\R, after \c: Line Continuation
\R, and warnings: Warnings
\r, as delimiter: Delimiters
\R, delimiters allowed by: Delimiters
\R, difference from nr: Auto-increment
\R, using + and - with: Numeric Expressions
\RET, when reading text for a macro: Copy Mode
\s, delimiters allowed by: Delimiters
\S, delimiters allowed by: Delimiters
\s, incompatibilities with AT&T troff: Compatibility Mode
\S, incompatibilities with AT&T troff: Compatibility Mode
\s, incompatibilities with AT&T troff: Compatibility Mode
\s, using + and - with: Numeric Expressions
\s, with fractional type sizes: Using Fractional Type Sizes
\SP, as delimiter: Delimiters
\SP, difference from \~: Calling Macros
\SP, incompatibilities with AT&T troff: Other Differences
\t, and copy mode: Tabs and Fields
\t, and translations: Character Translations
\t, and warnings: Warnings
\t, as delimiter: Delimiters
\u, as delimiter: Delimiters
\V, and copy mode: I/O
\v, delimiters allowed by: Delimiters
\v, internal representation: Gtroff Internals
\w, delimiters allowed by: Delimiters
\X, and special characters: Postprocessor Access
\X, delimiters allowed by: Delimiters
\x, delimiters allowed by: Delimiters
\X, followed by \%: Manipulating Hyphenation
\Y, followed by \%: Manipulating Hyphenation
\Z, delimiters allowed by: Delimiters
\[, and translations: Character Translations
\\, when reading text for a macro: Copy Mode
\^, as delimiter: Delimiters
\^, incompatibilities with AT&T troff: Other Differences
\_, and translations: Character Translations
\_, as delimiter: Delimiters
\_, as delimiter: Delimiters
\_, incompatibilities with AT&T troff: Other Differences
\`, and translations: Character Translations
\`, as delimiter: Delimiters
\`, as delimiter: Delimiters
\`, incompatibilities with AT&T troff: Other Differences
\{, as delimiter: Delimiters
\{, as delimiter: Delimiters
\{, incompatibilities with AT&T troff: Other Differences
\|, as delimiter: Delimiters
\|, incompatibilities with AT&T troff: Other Differences
\}, and warnings: Warnings
\}, as delimiter: Delimiters
\}, as delimiter: Delimiters
\}, incompatibilities with AT&T troff: Other Differences
\~, and translations: Character Translations
\~, as delimiter: Delimiters
\~, difference from \SP: Calling Macros
\~, incompatibilities with AT&T troff: Other Differences
]
], as part of an identifier: Identifiers
], at end of sentence: Sentences
], at end of sentence: Using Symbols
], macro names starting with, and refer: Identifiers
|
|, and page motion: Numeric Expressions
A
ab request, incompatibilities with AT&T troff: Other Differences
aborting (ab): Debugging
absolute (sic) position operator (|): Numeric Expressions
abstract font style: Using Fonts
abstract font style, setting up (sty): Font Families
accent marks [ms]: ms Legacy Features
access to postprocessor: Postprocessor Access
accessing unnamed glyphs with \N: Font Description File Format
activating kerning (kern): Ligatures and Kerning
activating ligatures (lg): Ligatures and Kerning
activating track kerning (tkf): Ligatures and Kerning
ad request, and hyphenation margin: Manipulating Hyphenation
ad request, and hyphenation space: Manipulating Hyphenation
addition: Numeric Expressions
additional inter-sentence space: Manipulating Filling and Adjustment
adjustment and filling, manipulating: Manipulating Filling and Adjustment
adjustment mode register (.j): Manipulating Filling and Adjustment
adjustment to both margins, difference from AT&T troff: Other Differences
Adobe Glyph List (AGL): Using Symbols
alias, diversion, creating (als): Strings
alias, diversion, removing (rm): Strings
alias, macro, creating (als): Strings
alias, macro, removing (rm): Strings
alias, register, creating (aln): Setting Registers
alias, register, removing (rr): Setting Registers
alias, string, creating (als): Strings
alias, string, removing (rm): Strings
aliasing fonts with third argument to fp request: Font Positions
als request, and \$0: Parameters
am, am1, ami requests, and warnings: Warnings
appending to a diversion (da, boxa): Diversions
appending to a file (opena): I/O
appending to a macro (am): Writing Macros
appending to a string (as): Strings
approximation output register (.A): Built-in Registers
arc, drawing (‘\D'a …'’): Drawing Geometric Objects
argument: Requests and Macros
arguments to macros: Calling Macros
arguments to macros, and tabs: Invoking Requests
arguments to requests: Invoking Requests
arguments to requests, and tabs: Invoking Requests
arguments, and compatibility mode: Gtroff Internals
arguments, to escape sequences, delimiting: Delimiters
arguments, to strings: Strings
arithmetic operators: Numeric Expressions
artificial fonts: Artificial Fonts
as, as1 requests, and comments: Comments
as, as1 requests, and warnings: Warnings
ASCII output encoding: Groff Options
asciify request, and writem: I/O
assertion (arithmetic operator): Numeric Expressions
assign number format to register (af): Assigning Register Formats
assignments, indirect: Interpolating Registers
assignments, nested: Interpolating Registers
AT&T ms, macro package differences: Differences from AT&T ms
attributes, character cell: Using Fonts
auto-incrementation of a register: Auto-increment
automatic font mounting: Selecting Fonts
automatic hyphenation: Manipulating Hyphenation
automatic hyphenation parameters: Manipulating Hyphenation
auxiliary macro package: Major Macro Packages
available glyphs, list of (groff_char(7) man page): Using Symbols
B
background: Background
background color name register (.M): Colors
backslash glyph, formatting (\[rs]): Using Escape Sequences
backslash, embedding in a macro argument: Calling Macros
backslash, printing (\\, \e, \E, \[rs]): Other Differences
backspace character, and translations: Character Translations
backtrace of input stack (backtrace): Debugging
baseline rule special character(\[ru]): Drawing Geometric Objects
baseline, text: Page Geometry
baseline, text: Manipulating Type Size and Vertical Spacing
basic scaling unit (u): Measurements
basic units: Page Geometry
basic units, conversion to: Measurements
basics of macro package usage: Basics
bd request, and font styles: Font Families
bd request, and font translations: Selecting Fonts
bd request, incompatibilities with AT&T troff: Other Differences
beginning diversion (di, box): Diversions
beginning of conditional block (\{): Conditional Blocks
blank line: Breaking
blank line macro (blm): Breaking
blank line macro (blm): Invoking Requests
blank line macro (blm): Blank Line Traps
blank line trap (blm): Invoking Requests
blank line traps: Blank Line Traps
blank lines, disabling: Manipulating Spacing
block, conditional, beginning (\{): Conditional Blocks
block, conditional, end (\}): Conditional Blocks
blocks, conditional: Conditional Blocks
body, of a while request: while
boldface, imitating (bd): Artificial Fonts
bottom margin: Page Location Traps
boundary-relative motion operator (|): Numeric Expressions
bounding box: Miscellaneous
box (diversion operation): Diversions
box request, and warnings: Warnings
box rule glyph (\[br]): Drawing Geometric Objects
box, boxa requests, and warnings: Warnings
boxa request, and dn (dl): Diversions
boxa request, and warnings: Warnings
boxes [ms]: ms keeps and displays
bp request, and top-level diversion: Page Control
bp request, and traps (.pe): Page Location Traps
bp request, causing implicit break: Manipulating Filling and Adjustment
bp request, incompatibilities with AT&T troff: Other Differences
bp request, using + and - with: Numeric Expressions
br glyph, and cflags: Using Symbols
brace escape sequence, closing (\}): Conditional Blocks
brace escape sequence, opening (\}): Conditional Blocks
brace escape sequences (\{, \}): Conditional Blocks
break: Breaking
break: Manipulating Filling and Adjustment
break (introduction): Basics
break request, in a while loop: while
break, page: Page Geometry
break, page: Page Control
break, page: The Implicit Page Trap
break, page (introduction): Basics
break, page, final: End-of-input Traps
break, page, prevented by vpt: Vertical Position Traps
breaking file names (\:): Manipulating Hyphenation
breaking URLs (\:): Manipulating Hyphenation
breaking without hyphens (\:): Manipulating Hyphenation
built-in register, removing: Built-in Registers
built-in registers: Built-in Registers
bulleted list, example markup [ms]: Lists in ms
C
c scaling unit: Measurements
calling a macro: Requests and Macros
calling macros: Calling Macros
capabilities of groff: groff Capabilities
case-transforming a string (stringdown, stringup): Strings
categories, warning: Warnings
CCSID 1047 output encoding (EBCDIC): Groff Options
ce request, causing implicit break: Manipulating Filling and Adjustment
ce request, difference from ‘.ad c’: Manipulating Filling and Adjustment
cell, character, attributes: Using Fonts
centered text (filled): Manipulating Filling and Adjustment
centered text (unfilled): Manipulating Filling and Adjustment
centering lines (ce): Manipulating Filling and Adjustment
centering lines (introduction): Basics
centimeter scaling unit (c): Measurements
cf request, and copy mode: I/O
cf request, causing implicit break: Manipulating Filling and Adjustment
changing control characters: Control Characters
changing font family (fam, \F): Font Families
changing fonts (ft, \f): Selecting Fonts
changing format, and read-only registers: Assigning Register Formats
changing the font height (\H): Artificial Fonts
changing the font slant (\S): Artificial Fonts
changing the page number character (pc): Page Layout
changing trap location (ch): Page Location Traps
changing type sizes (ps, \s): Changing the Type Size
changing vertical line spacing (vs): Changing the Vertical Spacing
char request, and soft hyphen character: Manipulating Hyphenation
char request, and translations: Character Translations
char request, used with \N: Using Symbols
character: Using Symbols
character cell attributes: Using Fonts
character class (class): Character Classes
character classes: Character Classes
character properties (cflags): Using Symbols
character translations: Character Translations
character, backspace, and translations: Character Translations
character, control (.): Requests and Macros
character, control, changing (cc): Control Characters
character, defining (char): Using Symbols
character, defining fallback (fchar, fschar, schar): Using Symbols
character, distinguished from glyph: Using Symbols
character, dummy (\&): Dummy Characters
character, dummy (\&), as control character suppressor: Requests and Macros
character, dummy (\&), effect on kerning: Ligatures and Kerning
character, dummy (\&), effect on \l escape sequence: Drawing Geometric Objects
character, escape, changing (ec): Using Escape Sequences
character, escape, while defining glyph: Using Symbols
character, field delimiting (fc): Fields
character, field padding (fc): Fields
character, horizontal tab: Tabs and Leaders
character, hyphenation (\%): Manipulating Hyphenation
character, leader: Tabs and Leaders
character, leader repetition (lc): Leaders
character, leader, and translations: Character Translations
character, leader, non-interpreted (\a): Leaders
character, named (\C): Using Symbols
character, newline, and translations: Character Translations
character, no-break control ('): Requests and Macros
character, no-break control, changing (c2): Control Characters
character, ordinary: Identifiers
character, soft hyphen, setting (shc): Manipulating Hyphenation
character, special: Character Translations
character, tab repetition (tc): Tabs and Fields
character, tab, and translations: Character Translations
character, tab, non-interpreted (\t): Tabs and Fields
character, transparent: Using Symbols
character, transparent dummy (\)): Dummy Characters
characters, end-of-sentence: Using Symbols
characters, end-of-sentence transparent: Sentences
characters, hyphenation: Using Symbols
characters, input, and output glyphs, compatibility with AT&T troff: Other Differences
characters, invalid for trf request: I/O
characters, invalid input: Identifiers
characters, overlapping: Using Symbols
characters, special: Sentences
characters, special, list of (groff_char(7) man page): Using Symbols
characters, unnamed, accessing with \N: Font Description File Format
circle, filled, drawing (‘\D'C …'’): Drawing Geometric Objects
circle, outlined, drawing (‘\D'c …'’): Drawing Geometric Objects
circle, solid, drawing (‘\D'C …'’): Drawing Geometric Objects
circle, stroked, drawing (‘\D'c …'’): Drawing Geometric Objects
class of characters (class): Character Classes
classes, character: Character Classes
clearing input line trap (it, itc): Input Line Traps
closing brace escape sequence (\}): Conditional Blocks
closing file (close): I/O
code page 1047 output encoding: Groff Options
code page 1047, input encoding: Input Encodings
code, hyphenation (hcode): Manipulating Hyphenation
color name, background, register (.M): Colors
color name, fill, register (.M): Colors
color name, stroke, register (.m): Colors
color, default: Colors
color, fill: Colors
color, stroke: Colors
colors: Colors
command prefix: Environment
command-line options: Groff Options
comments: Comments
comments in device description files: DESC File Format
comments in font description files: Font Description File Format
comments, lining up with tabs: Comments
comments, with ds: Strings
common features: Common Features
common name space of macros, diversions, and strings: Identifiers
comparison of strings: Operators in Conditionals
comparison operators: Numeric Expressions
compatibility mode: Warnings
compatibility mode: Compatibility Mode
compatibility mode, and parameters: Gtroff Internals
complementation, logical: Numeric Expressions
composite glyph names: Using Symbols
conditional block, beginning (\{): Conditional Blocks
conditional block, end (\}): Conditional Blocks
conditional blocks: Conditional Blocks
conditional expressions: Operators in Conditionals
conditional output for terminal (TTY): Operators in Conditionals
conditional page break (ne): Page Control
conditionals and loops: Conditionals and Loops
configuring control characters: Control Characters
configuring the page length (pl): Page Layout
consecutive hyphenated lines (hlm): Manipulating Hyphenation
constant glyph space mode (cs): Artificial Fonts
contents, table of: Table of Contents
contents, table of: Leaders
continuation, input line (\RET): Line Continuation
continuation, output line (\c): Line Continuation
continue request, in a while loop: while
continued output line register (.int): Line Continuation
continuous underlining (cu): Artificial Fonts
control character (.): Requests and Macros
control character, changing (cc): Control Characters
control character, no-break ('): Requests and Macros
control character, no-break, changing (c2): Control Characters
control characters: Control Characters
control line: Requests and Macros
control, line: Line Continuation
control, page: Page Control
conventions for input: Input Conventions
conversion to basic units: Measurements
copy mode: Copy Mode
copy mode: Copy Mode
copy mode, and cf request: I/O
copy mode, and device request: Postprocessor Access
copy mode, and length request: Strings
copy mode, and macro parameters: Parameters
copy mode, and output request: Diversions
copy mode, and trf request: I/O
copy mode, and write request: I/O
copy mode, and writec request: I/O
copy mode, and writem request: I/O
copy mode, and \!: Diversions
copy mode, and \?: Operators in Conditionals
copy mode, and \?: Diversions
copy mode, and \a: Leaders
copy mode, and \t: Tabs and Fields
copy mode, and \V: I/O
copying environment (evc): Environments
correction between oblique and upright glyph (\/, \,): Italic Corrections
correction between upright and oblique glyph (\/, \,): Italic Corrections
correction, italic (\/): Italic Corrections
correction, left italic (\,): Italic Corrections
cover page in [ms], example markup: ms Document Description Macros
cp request, and glyph definitions: Using Symbols
cq glyph, at end of sentence: Sentences
cq glyph, at end of sentence: Using Symbols
creating alias for register (aln): Setting Registers
creating alias, for diversion (als): Strings
creating alias, for macro (als): Strings
creating alias, for string (als): Strings
creating new characters (char): Using Symbols
credits: Credits
cs request, and font styles: Font Families
cs request, and font translations: Selecting Fonts
cs request, incompatibilities with AT&T troff: Other Differences
cs request, with fractional type sizes: Using Fractional Type Sizes
CSTR #54 errata: Built-in Registers
CSTR #54 errata: Line Layout
CSTR #54 errata: Page Control
CSTR #54 errata: Artificial Fonts
CSTR #54 errata: Changing the Type Size
CSTR #54 errata: Page Motions
CSTR #54 erratum, bp request: Page Control
CSTR #54 erratum, po request: Line Layout
CSTR #54 erratum, ps request: Changing the Type Size
CSTR #54 erratum, sb register: Page Motions
CSTR #54 erratum, st register: Page Motions
CSTR #54 erratum, yr register: Built-in Registers
CSTR #54 erratum, \S escape: Artificial Fonts
CSTR #54 erratum, \s escape sequence: Changing the Type Size
current directory: Macro Directories
current input file name register (.F): Built-in Registers
current page number (%): Page Control
current time, hours (hours): Built-in Registers
current time, minutes (minutes): Built-in Registers
current time, seconds (seconds): Built-in Registers
D
da request, and dn (dl): Diversions
da request, and warnings: Warnings
da request, and warnings: Warnings
date, day of the month register (dy): Built-in Registers
date, day of the week register (dw): Built-in Registers
date, month of the year register (mo): Built-in Registers
date, year register (year, yr): Built-in Registers
day of the month register (dy): Built-in Registers
day of the week register (dw): Built-in Registers
dd glyph, at end of sentence: Sentences
dd glyph, at end of sentence: Using Symbols
de request, and while: while
de, de1, dei requests, and warnings: Warnings
debugging: Debugging
debugging page location traps: Page Location Traps
decimal point, as delimiter: Delimiters
decrementation, automatic, of a register: Auto-increment
default color: Colors
default tab stops: Tabs and Fields
default units: Default Units
deferred output: Deferring Output
defining character (char): Using Symbols
defining character class (class): Character Classes
defining fallback character (fchar, fschar, schar): Using Symbols
defining glyph (char): Using Symbols
defining symbol (char): Using Symbols
delimited arguments, incompatibilities with AT&T troff: Compatibility Mode
delimiters, for escape sequence arguments: Delimiters
delimiting character, for fields (fc): Fields
delimiting escape sequence arguments: Delimiters
depth, interpolation: Calling Macros
depth, of last glyph (.cdp): Environments
DESC file format: DESC File Format
DESC file, and font mounting: Font Positions
DESC file, and use_charnames_in_special keyword: Postprocessor Access
description file, font: Using Fonts
device description files, comments: DESC File Format
device request, and copy mode: Postprocessor Access
device resolution: Page Geometry
device resolution: DESC File Format
device resolution, obtaining in the formatter: Measurements
devices for output: Output Device Intro
dg glyph, at end of sentence: Sentences
dg glyph, at end of sentence: Using Symbols
di request, and warnings: Warnings
di request, and warnings: Warnings
differences in implementation: Implementation Differences
digit-width space (\0): Page Motions
digits, as delimiters: Delimiters
dimensions, line: Line Layout
directories for fonts: Font Directories
directories for macros: Macro Directories
directory, current: Macro Directories
directory, for tmac files: Macro Directories
directory, home: Macro Directories
directory, platform-specific: Macro Directories
directory, site-local: Macro Directories
directory, site-local: Font Directories
disabling hyphenation (\%): Manipulating Hyphenation
disabling \ (eo): Using Escape Sequences
discardable horizontal space: Manipulating Filling and Adjustment
displays: Displays and Keeps
displays [ms]: ms keeps and displays
displays, and footnotes [ms]: ms Footnotes
distance to next vertical position trap register (.t): Page Location Traps
diversion: Deferring Output
diversion name register (.z): Diversions
diversion trap, setting (dt): Diversion Traps
diversion traps: Diversion Traps
diversion, appending to (da, boxa): Diversions
diversion, beginning (di, box): Diversions
diversion, creating alias for (als): Strings
diversion, ending (di, box): Diversions
diversion, nested: Diversions
diversion, removing (rm): Strings
diversion, removing alias for (rm): Strings
diversion, renaming (rn): Strings
diversion, stripping final newline: Punning Names
diversion, top-level: Diversions
diversion, top-level, and bp: Page Control
diversion, top-level, and \!: Diversions
diversion, top-level, and \?: Diversions
diversion, unformatting (asciify): Diversions
diversion, vertical position in, register (.d): Diversions
diversions: Diversions
diversions: Punning Names
diversions, and traps: Page Location Traps
diversions, shared name space with macros and strings: Identifiers
division, truncating: Numeric Expressions
dl register, and da (boxa): Diversions
dn register, and da (boxa): Diversions
document description macros, [ms]: ms Document Description Macros
document formats: Document Formats
documents, multi-file: Debugging
documents, structuring the source of: Invoking Requests
dot, as delimiter: Delimiters
double quote, embedding in a macro argument: Calling Macros
double quotes, trailing, in strings: Strings
double-spacing (ls): Manipulating Spacing
double-spacing (vs, pvs): Changing the Vertical Spacing
down-casing a string (stringdown): Strings
drawing a filled circle (‘\D'C …'’): Drawing Geometric Objects
drawing a filled ellipse (‘\D'E …'’): Drawing Geometric Objects
drawing a filled polygon (‘\D'P …'’): Drawing Geometric Objects
drawing a line (‘\D'l …'’): Drawing Geometric Objects
drawing a solid circle (‘\D'C …'’): Drawing Geometric Objects
drawing a solid ellipse (‘\D'E …'’): Drawing Geometric Objects
drawing a solid polygon (‘\D'P …'’): Drawing Geometric Objects
drawing a spline (‘\D'~ …'’): Drawing Geometric Objects
drawing a stroked circle (‘\D'c …'’): Drawing Geometric Objects
drawing a stroked ellipse (‘\D'e …'’): Drawing Geometric Objects
drawing a stroked polygon (‘\D'p …'’): Drawing Geometric Objects
drawing an arc (‘\D'a …'’): Drawing Geometric Objects
drawing an outlined circle (‘\D'c …'’): Drawing Geometric Objects
drawing an outlined ellipse (‘\D'e …'’): Drawing Geometric Objects
drawing an outlined polygon (‘\D'p …'’): Drawing Geometric Objects
drawing horizontal lines (\l): Drawing Geometric Objects
drawing position: Page Geometry
drawing position, vertical (nl): Page Control
drawing requests: Drawing Geometric Objects
drawing vertical lines (\L): Drawing Geometric Objects
ds request, and comments: Strings
ds request, and double quotes: Strings
ds request, and leading spaces: Strings
ds, ds1 requests, and comments: Comments
ds, ds1 requests, and warnings: Warnings
dummy character (\&): Dummy Characters
dummy character (\&), as control character suppressor: Requests and Macros
dummy character (\&), effect on kerning: Ligatures and Kerning
dummy character (\&), effect on \l escape sequence: Drawing Geometric Objects
dummy character, transparent (\)): Dummy Characters
dummy environment, used by \w escape sequence: Page Motions
dumping environments (pev): Debugging
dumping page location traps (ptr): Debugging
dumping registers (pnr): Debugging
dumping symbol table (pm): Debugging
E
EBCDIC output encoding: Groff Options
EBCDIC, input encoding: Input Encodings
ejection, page: Page Geometry
ejection, page: Page Control
ejection, page: The Implicit Page Trap
ejection, page, of final page: End-of-input Traps
ejection, page, prevented by vpt: Vertical Position Traps
el request, and warnings: Warnings
ellipse, filled, drawing (‘\D'E …'’): Drawing Geometric Objects
ellipse, outlined, drawing (‘\D'e …'’): Drawing Geometric Objects
ellipse, solid, drawing (‘\D'E …'’): Drawing Geometric Objects
ellipse, stroked, drawing (‘\D'e …'’): Drawing Geometric Objects
em glyph, and cflags: Using Symbols
em scaling unit (m): Measurements
embolding of special fonts: Artificial Fonts
empty line: Breaking
en scaling unit (n): Measurements
enabling vertical position traps (vpt): Vertical Position Traps
encoding, input, code page 1047: Input Encodings
encoding, input, EBCDIC: Input Encodings
encoding, input, Latin-1 (ISO 8859-1): Input Encodings
encoding, input, Latin-2 (ISO 8859-2): Input Encodings
encoding, input, Latin-5 (ISO 8859-9): Input Encodings
encoding, input, Latin-9 (ISO 8859-15): Input Encodings
encoding, output, ASCII: Groff Options
encoding, output, code page 1047: Groff Options
encoding, output, EBCDIC: Groff Options
encoding, output, ISO 646: Groff Options
encoding, output, Latin-1 (ISO 8859-1): Groff Options
encoding, output, UTF-8: Groff Options
end of conditional block (\}): Conditional Blocks
end-of-input macro (em): End-of-input Traps
end-of-input trap, setting (em): End-of-input Traps
end-of-input traps: End-of-input Traps
end-of-sentence characters: Sentences
end-of-sentence characters: Using Symbols
end-of-sentence transparent characters: Sentences
ending diversion (di, box): Diversions
endnotes: Footnotes and Endnotes
environment: Deferring Output
environment availability and naming, incompatibilities with: Other Differences
environment number/name register (.ev): Environments
environment variables: Environment
environment, copying (evc): Environments
environment, dimensions of last glyph (.w, .cht, .cdp, .csk): Environments
environment, dummy, used by \w escape sequence: Page Motions
environment, previous line length (.n): Environments
environment, switching (ev): Environments
environments: Environments
environments, dumping (pev): Debugging
equality operator: Numeric Expressions
equation example [ms]: ms Insertions
equations [ms]: ms Insertions
escape character, changing (ec): Using Escape Sequences
escape character, formatting (\e): Using Escape Sequences
escape character, while defining glyph: Using Symbols
escape sequence: Formatter Instructions
escape sequence argument delimiters: Delimiters
escape sequences: Using Escape Sequences
escape sequences, brace (\{, \}): Conditional Blocks
escaping newline characters, in strings: Strings
ex request, use in debugging: Debugging
ex request, used with nx and rd: I/O
example markup, bulleted list [ms]: Lists in ms
example markup, cover page in [ms]: ms Document Description Macros
example markup, glossary-style list [ms]: Lists in ms
example markup, numbered list [ms]: Lists in ms
examples of invocation: Invocation Examples
exiting (ex): Debugging
expansion of strings (\*): Strings
explicit hyphen (\%): Manipulating Hyphenation
explicit hyphenation: Manipulating Hyphenation
expression, limitation of logical not in: Numeric Expressions
expression, order of evaluation: Numeric Expressions
expressions, and register format: Assigning Register Formats
expressions, and space characters: Numeric Expressions
expressions, conditional: Operators in Conditionals
expressions, numeric: Numeric Expressions
extra post-vertical line space (\x): Changing the Vertical Spacing
extra post-vertical line space register (.a): Manipulating Spacing
extra pre-vertical line space (\x): Changing the Vertical Spacing
extra spaces between words: Adjustment
extreme values representable with Roman numerals: Assigning Register Formats
extremum operators (>?, <?): Numeric Expressions
F
f scaling unit: Colors
factor, zoom, of a font (fzoom): Selecting Fonts
fallback character, defining (fchar, fschar, schar): Using Symbols
fallback glyph, removing definition (rchar, rfschar): Using Symbols
fam request, and changing fonts: Selecting Fonts
families, font: Font Families
family, font: Using Fonts
features, common: Common Features
fi request, causing implicit break: Manipulating Filling and Adjustment
field delimiting character (fc): Fields
field padding character (fc): Fields
fields: Fields
fields, and tabs: Tabs and Fields
figure space (\0): Page Motions
figures [ms]: ms Insertions
file formats: File Formats
file names, breaking (\:): Manipulating Hyphenation
file, appending to (opena): I/O
file, closing (close): I/O
file, font description: Using Fonts
file, inclusion (so): I/O
file, macro, search path: Macro Directories
file, opening (open): I/O
file, processing next (nx): I/O
file, writing to (write, writec): I/O
files, font: Device and Font Description Files
fill color: Colors
fill color name register (.M): Colors
fill mode (fi), enabling: Manipulating Filling and Adjustment
fill mode, and \c: Line Continuation
fill mode, disabling: Manipulating Filling and Adjustment
filled circle, drawing (‘\D'C …'’): Drawing Geometric Objects
filled ellipse, drawing (‘\D'E …'’): Drawing Geometric Objects
filled polygon, drawing (‘\D'P …'’): Drawing Geometric Objects
filling: Filling
filling and adjustment, manipulating: Manipulating Filling and Adjustment
filling of output, disabling (nf): Manipulating Filling and Adjustment
filling of output, enabling (fi): Manipulating Filling and Adjustment
filling, and break warnings: Warnings
filling, and inter-sentence space: Manipulating Filling and Adjustment
final newline, stripping in diversions: Punning Names
fl request, causing implicit break: Manipulating Filling and Adjustment
floating keep: Displays and Keeps
flush output (fl): Debugging
font: Using Fonts
font aliasing with third argument to fp request: Font Positions
font description file: Using Fonts
font description file format: DESC File Format
font description file, format: Font Description File Format
font description files, comments: Font Description File Format
font directories: Font Directories
font families: Font Families
font family: Using Fonts
font family, changing (fam, \F): Font Families
font file, format: Font Description File Format
font files: Device and Font Description Files
font for underlining (uf): Artificial Fonts
font height, changing (\H): Artificial Fonts
font metrics: Using Fonts
font mounting, automatic: Selecting Fonts
font path: Font Directories
font position register (.f): Font Positions
font positions: Font Positions
font slant, changing (\S): Artificial Fonts
font style: Using Fonts
font style, abstract: Using Fonts
font style, abstract, setting up (sty): Font Families
font styles: Font Families
font translation (ftr): Selecting Fonts
font, magnification (fzoom): Selecting Fonts
font, mounting (fp): Font Positions
font, optical size: Selecting Fonts
font, previous, selecting (\f[], \fP): Selecting Fonts
font, previous, slecting (ft): Selecting Fonts
font, selection: Selecting Fonts
font, special: Using Fonts
font, text: Using Fonts
font, unstyled: Using Fonts
font, zoom factor (fzoom): Selecting Fonts
fonts, artificial: Artificial Fonts
fonts, changing (ft, \f): Selecting Fonts
fonts, searching: Font Directories
fonts, special: Special Fonts
footers: Page Layout
footers: Page Location Traps
footers [ms]: ms Headers and Footers
footnote marker [ms]: ms Footnotes
footnotes: Footnotes and Endnotes
footnotes [ms]: ms Footnotes
footnotes, and displays [ms]: ms Footnotes
footnotes, and keeps [ms]: ms Footnotes
form letters: I/O
format of font description file: DESC File Format
format of font description files: Font Description File Format
format of font files: Font Description File Format
format of register (\g): Assigning Register Formats
format, paper: Paper Format
formats, file: File Formats
formatter instructions: Formatter Instructions
formatting a backslash glyph (\[rs]): Using Escape Sequences
formatting a title line (tl): Page Layout
formatting the escape character (\e): Using Escape Sequences
formatting the time: I/O
fp request, and font translations: Selecting Fonts
fp request, incompatibilities with AT&T troff: Other Differences
fractional point sizes: Using Fractional Type Sizes
fractional point sizes: Other Differences
fractional type sizes: Using Fractional Type Sizes
fractional type sizes: Other Differences
fractional type sizes in ms macros: Differences from AT&T ms
French spacing: Sentences
fspecial request, and font styles: Font Families
fspecial request, and font translations: Selecting Fonts
fspecial request, and glyph search order: Using Symbols
fspecial request, and imitating bold: Artificial Fonts
ft request, and font translations: Selecting Fonts
full-service macro package: Major Macro Packages
G
geometry, page: Page Geometry
GGL (groff glyph list): Using Symbols
GGL (groff glyph list): Character Classes
glossary-style list, example markup [ms]: Lists in ms
glyph: Using Symbols
glyph for line drawing: Drawing Geometric Objects
glyph names, composite: Using Symbols
glyph pile (\b): Drawing Geometric Objects
glyph properties (cflags): Using Symbols
glyph, box rule (\[br]): Drawing Geometric Objects
glyph, constant space: Artificial Fonts
glyph, defining (char): Using Symbols
glyph, distinguished from character: Using Symbols
glyph, for line drawing: Drawing Geometric Objects
glyph, for margins (mc): Miscellaneous
glyph, last, dimensions (.w, .cht, .cdp, .csk): Environments
glyph, leader repetition (lc): Leaders
glyph, numbered (\N): Character Translations
glyph, numbered (\N): Using Symbols
glyph, removing definition (rchar, rfschar): Using Symbols
glyph, soft hyphen (hy): Manipulating Hyphenation
glyph, tab repetition (tc): Tabs and Fields
glyph, underscore (\[ru]): Drawing Geometric Objects
glyphs, available, list of (groff_char(7) man page): Using Symbols
glyphs, output, and input characters, compatibility with AT&T troff: Other Differences
glyphs, overstriking (\o): Page Motions
glyphs, unnamed: Using Symbols
glyphs, unnamed, accessing with \N: Font Description File Format
GNU troff, identification register (.g): Built-in Registers
GNU troff, PID register ($$): Built-in Registers
GNU troff, process ID register ($$): Built-in Registers
GNU-specific register (.g): Built-in Registers
graphic renditions: Using Fonts
greater than (or equal to) operator: Numeric Expressions
groff capabilities: groff Capabilities
groff glyph list (GGL): Using Symbols
groff glyph list (GGL): Character Classes
groff invocation: Invoking groff
groff, and pi request: I/O
groff—what is it?: What Is groff?
GROFF_BIN_PATH, environment variable: Environment
GROFF_COMMAND_PREFIX, environment variable: Environment
GROFF_ENCODING, environment variable: Environment
GROFF_FONT_PATH, environment variable: Environment
GROFF_FONT_PATH, environment variable: Font Directories
GROFF_TMAC_PATH, environment variable: Environment
GROFF_TMAC_PATH, environment variable: Macro Directories
GROFF_TMPDIR, environment variable: Environment
GROFF_TYPESETTER, environment variable: Environment
grohtml, the program: Groff Options
gtroff, interactive use: Debugging
gtroff, output: gtroff Output
gtroff, reference: GNU troff Reference
H
hair space (\^): Page Motions
hcode request, and glyph definitions: Using Symbols
headers: Page Layout
headers: Page Location Traps
headers [ms]: ms Headers and Footers
height, font, changing (\H): Artificial Fonts
height, of last glyph (.cht): Environments
high-water mark register (.h): Diversions
home directory: Macro Directories
horizontal discardable space: Manipulating Filling and Adjustment
horizontal input line position register (hp): Page Motions
horizontal input line position, saving (\k): Page Motions
horizontal line, drawing (\l): Drawing Geometric Objects
horizontal motion (\h): Page Motions
horizontal motion quantum: DESC File Format
horizontal motion quantum register (.H): Motion Quanta
horizontal output line position register (.k): Page Motions
horizontal resolution: DESC File Format
horizontal resolution register (.H): Motion Quanta
horizontal space (\h): Page Motions
horizontal space, unformatting: Punning Names
horizontal tab character: Tabs and Leaders
hours, current time (hours): Built-in Registers
hpf request, and hyphenation language: Manipulating Hyphenation
hw request, and hy restrictions: Manipulating Hyphenation
hw request, and hyphenation language: Manipulating Hyphenation
hy glyph, and cflags: Using Symbols
hyphen, explicit (\%): Manipulating Hyphenation
hyphenated lines, consecutive (hlm): Manipulating Hyphenation
hyphenating characters: Using Symbols
hyphenation: Hyphenation
hyphenation character (\%): Manipulating Hyphenation
hyphenation code (hcode): Manipulating Hyphenation
hyphenation consecutive line count register (.hlc): Manipulating Hyphenation
hyphenation consecutive line limit register (.hlm): Manipulating Hyphenation
hyphenation exceptions: Manipulating Hyphenation
hyphenation language register (.hla): Manipulating Hyphenation
hyphenation margin (hym): Manipulating Hyphenation
hyphenation margin register (.hym): Manipulating Hyphenation
hyphenation mode register (.hy): Manipulating Hyphenation
hyphenation parameters, automatic: Manipulating Hyphenation
hyphenation pattern files: Manipulating Hyphenation
hyphenation patterns (hpf): Manipulating Hyphenation
hyphenation space (hys): Manipulating Hyphenation
hyphenation space adjustment threshold: Manipulating Hyphenation
hyphenation space adjustment threshold register (.hys): Manipulating Hyphenation
hyphenation, automatic: Manipulating Hyphenation
hyphenation, disabling (\%): Manipulating Hyphenation
hyphenation, explicit: Manipulating Hyphenation
hyphenation, incompatibilities with AT&T troff: Other Differences
hyphenation, manipulating: Manipulating Hyphenation
hyphenation, manual: Manipulating Hyphenation
I
i scaling unit: Measurements
i/o: I/O
IBM code page 1047 input encoding: Input Encodings
IBM code page 1047 output encoding: Groff Options
identifiers: Identifiers
identifiers, undefined: Identifiers
ie request, and font translations: Selecting Fonts
ie request, and warnings: Warnings
ie request, operators to use with: Operators in Conditionals
if request, and font translations: Selecting Fonts
if request, and the ‘!’ operator: Numeric Expressions
if request, operators to use with: Operators in Conditionals
if-else: if-else
if-then: if-then
imitating boldface (bd): Artificial Fonts
implementation differences: Implementation Differences
implicit line break: Breaking
implicit trap: The Implicit Page Trap
in request, causing implicit break: Manipulating Filling and Adjustment
in request, using + and - with: Numeric Expressions
inch scaling unit (i): Measurements
including a file (so): I/O
incompatibilities with AT&T troff: Implementation Differences
increment value without changing the register: Auto-increment
incrementation, automatic, of a register: Auto-increment
indentation (in): Line Layout
indentation, of roff source code: Invoking Requests
index, in macro package: Indexing
indicator, scaling: Measurements
indirect assignments: Interpolating Registers
input and output requests: I/O
input characters and output glyphs, compatibility with AT&T troff: Other Differences
input characters, invalid: Identifiers
input conventions: Input Conventions
input encoding, code page 1047: Input Encodings
input encoding, EBCDIC: Input Encodings
input encoding, Latin-1 (ISO 8859-1): Input Encodings
input encoding, Latin-2 (ISO 8859-2): Input Encodings
input encoding, Latin-5 (ISO 8859-9): Input Encodings
input encoding, Latin-9 (ISO 8859-15): Input Encodings
input file name, current, register (.F): Built-in Registers
input level: Calling Macros
input level in delimited arguments: Compatibility Mode
input line continuation (\RET): Line Continuation
input line number register (.c, c.): Built-in Registers
input line number, setting (lf): Debugging
input line position, horizontal, saving (\k): Page Motions
input line trap, clearing (it, itc): Input Line Traps
input line trap, setting (it, itc): Input Line Traps
input line traps: Input Line Traps
input line traps and interrupted lines (itc): Input Line Traps
input line, horizontal position, register (hp): Page Motions
input line, productive: Manipulating Filling and Adjustment
input stack, backtrace (backtrace): Debugging
input stack, setting limit: Debugging
input token: Gtroff Internals
input, 8-bit: Font Description File Format
input, standard, reading from (rd): I/O
inserting horizontal space (\h): Page Motions
installation: Installation
instructing the formatter: Formatter Instructions
inter-sentence space size register (.sss): Manipulating Filling and Adjustment
inter-sentence space, additional: Manipulating Filling and Adjustment
inter-word spacing, minimal: Manipulating Filling and Adjustment
interactive use of gtroff: Debugging
intercepting requests: Control Characters
intermediate output: gtroff Output
interpolating registers (\n): Interpolating Registers
interpolation: Requests and Macros
interpolation depth: Calling Macros
interpolation depth in delimited arguments: Compatibility Mode
interpolation of strings (\*): Strings
interpretation mode: Copy Mode
interrupted line: Line Continuation
interrupted line register (.int): Line Continuation
interrupted lines and input line traps (itc): Input Line Traps
introduction: Introduction
invalid characters for trf request: I/O
invalid input characters: Identifiers
invocation examples: Invocation Examples
invoking groff: Invoking groff
invoking requests: Invoking Requests
ISO 646 output encoding: Groff Options
ISO 8859-1 (Latin-1) output encoding: Groff Options
ISO 8859-1 (Latin-1), input encoding: Input Encodings
ISO 8859-15 (Latin-9), input encoding: Input Encodings
ISO 8859-2 (Latin-2), input encoding: Input Encodings
ISO 8859-9 (Latin-5), input encoding: Input Encodings
italic correction (\/): Italic Corrections
J
justifying text: Manipulating Filling and Adjustment
justifying text (rj): Manipulating Filling and Adjustment
K
keep, floating: Displays and Keeps
keeps (introduction): Displays and Keeps
keeps [ms]: ms keeps and displays
keeps, and footnotes [ms]: ms Footnotes
kerning and ligatures: Ligatures and Kerning
kerning enabled register (.kern): Ligatures and Kerning
kerning, activating (kern): Ligatures and Kerning
kerning, track: Ligatures and Kerning
L
landscape page orientation: Paper Format
language [ms]: ms language and localization
last glyph, dimensions (.w, .cht, .cdp, .csk): Environments
last-requested point size registers (.psr, .sr): Using Fractional Type Sizes
last-requested type size registers (.psr, .sr): Using Fractional Type Sizes
Latin-1 (ISO 8859-1) output encoding: Groff Options
Latin-1 (ISO 8859-1), input encoding: Input Encodings
Latin-2 (ISO 8859-2), input encoding: Input Encodings
Latin-5 (ISO 8859-9), input encoding: Input Encodings
Latin-9 (ISO 8859-15), input encoding: Input Encodings
layout, line: Line Layout
layout, page: Page Layout
lc request, and glyph definitions: Using Symbols
leader character: Tabs and Leaders
leader character: Leaders
leader character, and translations: Character Translations
leader character, non-interpreted (\a): Leaders
leader repetition character (lc): Leaders
leaders: Leaders
leading: Manipulating Type Size and Vertical Spacing
leading space macro (lsm): Breaking
leading space traps: Leading Space Traps
leading spaces: Breaking
leading spaces macro (lsm): Leading Space Traps
leading spaces with ds: Strings
left italic correction (\,): Italic Corrections
left margin (po): Line Layout
length of a string (length): Strings
length of line (ll): Line Layout
length of previous line (.n): Environments
length of the page, configuring (pl): Page Layout
length of title line, configuring (lt): Page Layout
length request, and copy mode: Strings
less than (or equal to) operator: Numeric Expressions
letters, form: I/O
level, input: Calling Macros
level, suppression nesting, register: Suppressing Output
lf request, incompatibilities with AT&T troff: Other Differences
ligature: Using Symbols
ligatures and kerning: Ligatures and Kerning
ligatures enabled register (.lg): Ligatures and Kerning
ligatures, activating (lg): Ligatures and Kerning
limitations of \b escape sequence: Drawing Geometric Objects
line break: Manipulating Filling and Adjustment
line break (introduction): Basics
line break, output: Breaking
line control: Line Continuation
line dimensions: Line Layout
line drawing glyph: Drawing Geometric Objects
line drawing glyph: Drawing Geometric Objects
line indentation (in): Line Layout
line layout: Line Layout
line length (ll): Line Layout
line length register (.l): Line Layout
line length, previous (.n): Environments
line number, input, register (.c, c.): Built-in Registers
line number, output, register (ln): Miscellaneous
line numbers, printing (nm): Miscellaneous
line space, extra post-vertical (\x): Changing the Vertical Spacing
line space, extra pre-vertical (\x): Changing the Vertical Spacing
line spacing register (.L): Manipulating Spacing
line spacing, post-vertical (pvs): Changing the Vertical Spacing
line thickness (‘\D't …'’): Drawing Geometric Objects
line, blank: Breaking
line, drawing (‘\D'l …'’): Drawing Geometric Objects
line, horizontal, drawing (\l): Drawing Geometric Objects
line, input, continuation (\RET): Line Continuation
line, input, horizontal position, register (hp): Page Motions
line, input, horizontal position, saving (\k): Page Motions
line, interrupted: Line Continuation
line, output, continuation (\c): Line Continuation
line, output, horizontal position, register (.k): Page Motions
line, productive input: Manipulating Filling and Adjustment
line, vertical, drawing (\L): Drawing Geometric Objects
line-tabs mode: Tabs and Fields
lines, blank, disabling: Manipulating Spacing
lines, centering (ce): Manipulating Filling and Adjustment
lines, centering (introduction): Basics
lines, consecutive hyphenated (hlm): Manipulating Hyphenation
lines, interrupted, and input line traps (itc): Input Line Traps
lines, right-aligning (introduction): Basics
lines, right-justifying (introduction): Basics
list of special characters (groff_char(7) man page): Using Symbols
listing page location traps (ptr): Debugging
lists: Paragraphs
ll request, using + and - with: Numeric Expressions
localization: Manipulating Hyphenation
localization [ms]: ms language and localization
locating macro files: Macro Directories
locating macro packages: Macro Directories
location, vertical, page, marking (mk): Page Motions
location, vertical, page, returning to marked (rt): Page Motions
logical “and” operator: Numeric Expressions
logical “or” operator: Numeric Expressions
logical complementation operator: Numeric Expressions
logical conjunction operator: Numeric Expressions
logical disjunction operator: Numeric Expressions
logical not, limitation in expression: Numeric Expressions
logical operators: Numeric Expressions
long names: Compatibility Mode
loops and conditionals: Conditionals and Loops
lowercasing a string (stringdown): Strings
ls request, alternative to (pvs): Changing the Vertical Spacing
lt request, using + and - with: Numeric Expressions
M
m scaling unit: Measurements
M scaling unit: Measurements
machine units: Page Geometry
macro: Requests and Macros
macro arguments: Calling Macros
macro arguments, and compatibility mode: Gtroff Internals
macro arguments, and tabs: Invoking Requests
macro directories: Macro Directories
macro file search path: Macro Directories
macro name register (\$0): Parameters
macro names, starting with [ or ], and refer: Identifiers
macro package: Macro Packages
macro package search path: Macro Directories
macro package usage, basics of: Basics
macro package, auxiliary: Major Macro Packages
macro package, full-service: Major Macro Packages
macro package, introduction: Macro Package Intro
macro package, major: Major Macro Packages
macro package, minor: Major Macro Packages
macro package, structuring the source of: Invoking Requests
macro, appending to (am): Writing Macros
macro, creating alias for (als): Strings
macro, end-of-input (em): End-of-input Traps
macro, parameters (\$): Parameters
macro, removing (rm): Strings
macro, removing alias for (rm): Strings
macro, renaming (rn): Strings
macros, recursive: while
macros, searching: Macro Directories
macros, shared name space with strings and diversions: Identifiers
macros, tutorial for users: Tutorial for Macro Users
macros, writing: Writing Macros
magnification of a font (fzoom): Selecting Fonts
major macro package: Major Macro Packages
major version number register (.x): Built-in Registers
man macros, custom headers and footers: Optional man extensions
man macros, Ultrix-specific: Optional man extensions
man pages: man
manipulating filling and adjustment: Manipulating Filling and Adjustment
manipulating hyphenation: Manipulating Hyphenation
manipulating spacing: Manipulating Spacing
manipulating type size and vertical spacing: Manipulating Type Size and Vertical Spacing
manual hyphenation: Manipulating Hyphenation
manual pages: man
margin for hyphenation (hym): Manipulating Hyphenation
margin glyph (mc): Miscellaneous
margin, bottom: Page Location Traps
margin, left (po): Line Layout
margin, right: Line Layout
margin, top: Page Location Traps
mark, high-water, register (.h): Diversions
marker, footnote [ms]: ms Footnotes
marking vertical page location (mk): Page Motions
maximum operator: Numeric Expressions
maximum value representable with Roman numerals: Assigning Register Formats
mdoc macros: mdoc
me macro package: me
measurement units: Measurements
measurements: Measurements
measurements, specifying safely: Default Units
metrics, font: Using Fonts
minimal inter-word spacing: Manipulating Filling and Adjustment
minimum operator: Numeric Expressions
minimum value representable with Roman numerals: Assigning Register Formats
minor macro package: Major Macro Packages
minor version number register (.y): Built-in Registers
minutes, current time (minutes): Built-in Registers
mm macro package: mm
mode for constant glyph space (cs): Artificial Fonts
mode, compatibility: Compatibility Mode
mode, compatibility, and parameters: Gtroff Internals
mode, copy: Copy Mode
mode, copy: Copy Mode
mode, copy, and cf request: I/O
mode, copy, and device request: Postprocessor Access
mode, copy, and length request: Strings
mode, copy, and macro parameters: Parameters
mode, copy, and output request: Diversions
mode, copy, and trf request: I/O
mode, copy, and write request: I/O
mode, copy, and writec request: I/O
mode, copy, and writem request: I/O
mode, copy, and \!: Diversions
mode, copy, and \?: Operators in Conditionals
mode, copy, and \?: Diversions
mode, copy, and \a: Leaders
mode, copy, and \t: Tabs and Fields
mode, copy, and \V: I/O
mode, fill (fi), enabling: Manipulating Filling and Adjustment
mode, fill, and break warnings: Warnings
mode, fill, and inter-sentence space: Manipulating Filling and Adjustment
mode, fill, and \c: Line Continuation
mode, fill, disabling: Manipulating Filling and Adjustment
mode, interpretation: Copy Mode
mode, line-tabs: Tabs and Fields
mode, no-fill: Manipulating Filling and Adjustment
mode, no-fill, and \c: Line Continuation
mode, no-space (ns): Manipulating Spacing
mode, nroff: troff and nroff Modes
mode, safer: Groff Options
mode, safer: Macro Directories
mode, safer: Built-in Registers
mode, safer: I/O
mode, safer: I/O
mode, safer: I/O
mode, safer: I/O
mode, safer: Safer Mode
mode, troff: troff and nroff Modes
mode, unsafe: Groff Options
mode, unsafe: Macro Directories
mode, unsafe: Built-in Registers
mode, unsafe: I/O
mode, unsafe: I/O
mode, unsafe: I/O
mode, unsafe: I/O
modifying requests: Control Characters
modulus: Numeric Expressions
mom macro package: mom
month of the year register (mo): Built-in Registers
motion operators: Numeric Expressions
motion quanta: Motion Quanta
motion quantum, horizontal: DESC File Format
motion quantum, horizontal, register (.H): Motion Quanta
motion quantum, vertical: DESC File Format
motion, horizontal (\h): Page Motions
motion, vertical (\v): Page Motions
motions, page: Page Motions
mounting a font (fp): Font Positions
mounting position: Using Fonts
mounting position: Using Fonts
mounting, font, automatic: Selecting Fonts
ms macros: ms
ms macros, accent marks: ms Legacy Features
ms macros, body text: ms Body Text
ms macros, creating table of contents: ms TOC
ms macros, displays: ms keeps and displays
ms macros, document control settings: ms Document Control Settings
ms macros, document description: ms Document Description Macros
ms macros, equations: ms Insertions
ms macros, figures: ms Insertions
ms macros, footers: ms Headers and Footers
ms macros, footnotes: ms Footnotes
ms macros, fractional type sizes in: Differences from AT&T ms
ms macros, general structure: ms Document Structure
ms macros, groff differences from AT&T: Differences from AT&T ms
ms macros, headers: ms Headers and Footers
ms macros, headings: Headings in ms
ms macros, keeps: ms keeps and displays
ms macros, language: ms language and localization
ms macros, lists: Lists in ms
ms macros, localization: ms language and localization
ms macros, margins: ms Margins
ms macros, multiple columns: ms Multiple Columns
ms macros, naming conventions: ms Naming Conventions
ms macros, nested lists: Indented regions in ms
ms macros, obtaining typographical symbols: Typographical symbols in ms
ms macros, page layout: ms Page Layout
ms macros, paragraph handling: Paragraphs in ms
ms macros, references: ms Insertions
ms macros, special characters: ms Legacy Features
ms macros, strings: ms Legacy Features
ms macros, tables: ms Insertions
ms macros, text settings: Text settings in ms
multi-file documents: Debugging
multi-line strings: Strings
multi-page table example [ms]: ms Insertions
multiple columns [ms]: ms Multiple Columns
multiplication: Numeric Expressions
N
n scaling unit: Measurements
name space, common, of macros, diversions, and strings: Identifiers
name, background color, register (.M): Colors
name, fill color, register (.M): Colors
name, stroke color, register (.m): Colors
named character (\C): Using Symbols
names, long: Compatibility Mode
naming conventions, ms macros: ms Naming Conventions
ne request, and the .trunc register: Page Location Traps
ne request, comparison with sv: Page Control
negating register values: Setting Registers
negation: Numeric Expressions
nested assignments: Interpolating Registers
nested diversions: Diversions
nested lists [ms]: Indented regions in ms
nesting level, suppression, register: Suppressing Output
new page (bp): Page Control
newline character, and translations: Character Translations
newline character, in strings, escaping: Strings
newline, as delimiter: Delimiters
newline, final, stripping in diversions: Punning Names
next file, processing (nx): I/O
next free font position register (.fp): Font Positions
next page number register (.pn): Page Layout
next page number, configuring (pn): Page Layout
nf request, causing implicit break: Manipulating Filling and Adjustment
nl register, and .d: Diversions
nl register, difference from .h: Diversions
nm request, using + and - with: Numeric Expressions
no-break control character ('): Requests and Macros
no-break control character, changing (c2): Control Characters
no-fill mode: Manipulating Filling and Adjustment
no-fill mode, and \c: Line Continuation
no-space mode (ns): Manipulating Spacing
node, output: Gtroff Internals
non-printing break point (\:): Manipulating Hyphenation
nr request, and warnings: Warnings
nr request, using + and - with: Numeric Expressions
nroff mode: troff and nroff Modes
number formats, assigning to register (af): Assigning Register Formats
number of registers register (.R): Built-in Registers
number, input line, setting (lf): Debugging
number, page, next, configuring (pn): Page Layout
numbered glyph (\N): Character Translations
numbered glyph (\N): Using Symbols
numbered list, example markup [ms]: Lists in ms
numbers, line, printing (nm): Miscellaneous
numeral-width space (\0): Page Motions
numerals, as delimiters: Delimiters
numerals, Roman: Assigning Register Formats
numeric expression, valid: Numeric Expressions
numeric expressions: Numeric Expressions
O
object creation: Writing Macros
offset, page: Page Geometry
offset, page (po): Line Layout
open request, and safer mode: Groff Options
opena request, and safer mode: Groff Options
opening brace escape sequence (\}): Conditional Blocks
opening file (open): I/O
operator, scaling: Numeric Expressions
operators, arithmetic: Numeric Expressions
operators, as delimiters: Delimiters
operators, comparison: Numeric Expressions
operators, extremum (>?, <?): Numeric Expressions
operators, logical: Numeric Expressions
operators, motion: Numeric Expressions
operators, unary arithmetic: Numeric Expressions
optical size of a font: Selecting Fonts
options: Groff Options
order of evaluation in expressions: Numeric Expressions
ordinary character: Identifiers
orientation, landscape: Paper Format
orphan: Page Control
orphan lines, preventing with ne: Page Control
os request, and no-space mode: Page Control
outlined circle, drawing (‘\D'c …'’): Drawing Geometric Objects
outlined ellipse, drawing (‘\D'e …'’): Drawing Geometric Objects
outlined polygon, drawing (‘\D'p …'’): Drawing Geometric Objects
output and input requests: I/O
output comparison operator: Operators in Conditionals
output device name string (.T): Groff Options
output device name string (.T): Strings
output device name string (.T), in other implementations: Other Differences
output device usage register (.T): Groff Options
output device usage register (.T), incompatibility with AT&T troff: Other Differences
output devices: Output Device Intro
output encoding, ASCII: Groff Options
output encoding, code page 1047: Groff Options
output encoding, EBCDIC: Groff Options
output encoding, ISO 646: Groff Options
output encoding, Latin-1 (ISO 8859-1): Groff Options
output encoding, UTF-8: Groff Options
output glyphs, and input characters, compatibility with AT&T troff: Other Differences
output line break: Breaking
output line number register (ln): Miscellaneous
output line properties: Manipulating Filling and Adjustment
output line, continuation (\c): Line Continuation
output line, horizontal position, register (.k): Page Motions
output node: Gtroff Internals
output request, and copy mode: Diversions
output request, and \!: Diversions
output, filling, disablement of (nf): Manipulating Filling and Adjustment
output, filling, enablement of (fi): Manipulating Filling and Adjustment
output, flush (fl): Debugging
output, gtroff: gtroff Output
output, intermediate: gtroff Output
output, suppressing (\O): Suppressing Output
output, transparent (cf, trf): I/O
output, transparent (\!, \?): Diversions
output, transparent, incompatibilities with AT&T troff: Other Differences
output, troff: gtroff Output
overlapping characters: Using Symbols
overstriking glyphs (\o): Page Motions
P
p scaling unit: Measurements
P scaling unit: Measurements
package, macro: Macro Packages
package, macro, auxiliary: Major Macro Packages
package, macro, full-service: Major Macro Packages
package, macro, introduction: Macro Package Intro
package, macro, major: Major Macro Packages
package, macro, minor: Major Macro Packages
package, macro, search path: Macro Directories
package, package, structuring the source of: Invoking Requests
padding character, for fields (fc): Fields
page: Page Geometry
page break: Page Geometry
page break: Page Control
page break: The Implicit Page Trap
page break (introduction): Basics
page break, conditional (ne): Page Control
page break, final: End-of-input Traps
page break, prevented by vpt: Vertical Position Traps
page control: Page Control
page ejection: Page Geometry
page ejection: Page Control
page ejection: The Implicit Page Trap
page ejection status register (.pe): Page Location Traps
page ejection, of final page: End-of-input Traps
page ejection, prevented by vpt: Vertical Position Traps
page footers: Page Location Traps
page headers: Page Location Traps
page layout: Page Layout
page layout [ms]: ms Page Layout
page length register (.p): Page Layout
page length, configuring (pl): Page Layout
page location traps: Page Location Traps
page location traps, debugging: Page Location Traps
page location, vertical, marking (mk): Page Motions
page location, vertical, returning to marked (rt): Page Motions
page motions: Page Motions
page number character (%): Page Layout
page number character, changing (pc): Page Layout
page number register (%): Page Control
page number, configuring next (pn): Page Layout
page number, next, register (.pn): Page Layout
page offset: Page Geometry
page offset (po): Line Layout
page orientation, landscape: Paper Format
page, geometry of: Page Geometry
page, new (bp): Page Control
paper format: Paper Format
paper size: Paper Format
paragraphs: Paragraphs
parameter count register (.$): Parameters
parameters: Parameters
parameters, and compatibility mode: Gtroff Internals
parameters, macro (\$): Parameters
parentheses: Numeric Expressions
partially collected line: Manipulating Filling and Adjustment
path, for font files: Font Directories
path, for tmac files: Macro Directories
pattern files, for hyphenation: Manipulating Hyphenation
patterns for hyphenation (hpf): Manipulating Hyphenation
pending output line: Manipulating Filling and Adjustment
pi request, and groff: I/O
pi request, and safer mode: Groff Options
pi request, disabled by default: Safer Mode
pica scaling unit (P): Measurements
PID of GNU troff register ($$): Built-in Registers
pile, glyph (\b): Drawing Geometric Objects
pl request, using + and - with: Numeric Expressions
plain text approximation output register (.A): Groff Options
plain text approximation output register (.A): Built-in Registers
planting a trap: Traps
platform-specific directory: Macro Directories
pm request, incompatibilities with AT&T troff: Other Differences
pn request, using + and - with: Numeric Expressions
PNG image generation from PostScript: DESC File Format
po request, using + and - with: Numeric Expressions
point scaling unit (p): Measurements
point size registers (.s, .ps): Changing the Type Size
point size registers, last-requested (.psr, .sr): Using Fractional Type Sizes
point sizes, changing (ps, \s): Changing the Type Size
point sizes, fractional: Using Fractional Type Sizes
point sizes, fractional: Other Differences
polygon, filled, drawing (‘\D'P …'’): Drawing Geometric Objects
polygon, outlined, drawing (‘\D'p …'’): Drawing Geometric Objects
polygon, solid, drawing (‘\D'P …'’): Drawing Geometric Objects
polygon, stroked, drawing (‘\D'p …'’): Drawing Geometric Objects
position of lowest text line (.h): Diversions
position, absolute (sic) operator (|): Numeric Expressions
position, drawing: Page Geometry
position, horizontal input line, saving (\k): Page Motions
position, horizontal, in input line, register (hp): Page Motions
position, horizontal, in output line, register (.k): Page Motions
position, mounting: Using Fonts
position, vertical, in diversion, register (.d): Diversions
positions, font: Font Positions
post-vertical line spacing: Changing the Vertical Spacing
post-vertical line spacing register (.pvs): Changing the Vertical Spacing
post-vertical line spacing, changing (pvs): Changing the Vertical Spacing
postprocessor access: Postprocessor Access
postprocessors: Output Device Intro
PostScript, bounding box: Miscellaneous
PostScript, PNG image generation: DESC File Format
prefix, for commands: Environment
preprocessors: Preprocessor Intro
previous font, selecting (ft): Selecting Fonts
previous font, selecting (\f[], \fP): Selecting Fonts
previous line length (.n): Environments
print current page register (.P): Groff Options
printing backslash (\\, \e, \E, \[rs]): Other Differences
printing line numbers (nm): Miscellaneous
printing to stderr (tm, tm1, tmc): Debugging
printing, zero-width (\z, \Z): Page Motions
printing, zero-width (\z, \Z): Page Motions
process ID of GNU troff register ($$): Built-in Registers
processing next file (nx): I/O
productive input line: Manipulating Filling and Adjustment
properties of characters (cflags): Using Symbols
properties of glyphs (cflags): Using Symbols
properties of output lines: Manipulating Filling and Adjustment
ps request, and constant glyph space mode: Artificial Fonts
ps request, incompatibilities with AT&T troff: Other Differences
ps request, using + and - with: Numeric Expressions
ps request, with fractional type sizes: Using Fractional Type Sizes
pso request, and safer mode: Groff Options
pvs request, using + and - with: Numeric Expressions
Q
quanta, motion: Motion Quanta
quantum, horizontal motion: DESC File Format
quantum, vertical motion: DESC File Format
R
radicalex glyph, and cflags: Using Symbols
ragged-left text: Manipulating Filling and Adjustment
ragged-right text: Manipulating Filling and Adjustment
rc request, and glyph definitions: Using Symbols
read-only register removal, incompatibility with AT&T troff: Other Differences
read-only register, changing format: Assigning Register Formats
reading from standard input (rd): I/O
recursive macros: while
refer, and macro names starting with [ or ]: Identifiers
reference, gtroff: GNU troff Reference
references [ms]: ms Insertions
register format, in expressions: Assigning Register Formats
register, assigning number format to (af): Assigning Register Formats
register, built-in, removing: Built-in Registers
register, creating alias for (aln): Setting Registers
register, format (\g): Assigning Register Formats
register, read-only, removal, incompatibility with AT&T troff: Other Differences
register, removing (rr): Setting Registers
register, removing alias for (rr): Setting Registers
register, renaming (rnn): Setting Registers
registers: Registers
registers, built-in: Built-in Registers
registers, dumping (pnr): Debugging
registers, interpolating (\n): Interpolating Registers
registers, number of, register (.R): Built-in Registers
registers, setting (nr, \R): Setting Registers
removal of read-only registers, incompatibility with AT&T troff: Other Differences
removing a built-in register: Built-in Registers
removing a register (rr): Setting Registers
removing alias for register (rr): Setting Registers
removing alias, for diversion (rm): Strings
removing alias, for macro (rm): Strings
removing alias, for string (rm): Strings
removing diversion (rm): Strings
removing glyph definition (rchar, rfschar): Using Symbols
removing macro (rm): Strings
removing request (rm): Strings
removing string (rm): Strings
renaming a register (rnn): Setting Registers
renaming diversion (rn): Strings
renaming macro (rn): Strings
renaming request (rn): Strings
renaming string (rn): Strings
renditions, graphic: Using Fonts
request: Requests and Macros
request: Formatter Instructions
request arguments: Invoking Requests
request arguments, and compatibility mode: Gtroff Internals
request arguments, and tabs: Invoking Requests
request, removing (rm): Strings
request, renaming (rn): Strings
request, undefined: Comments
requests for drawing: Drawing Geometric Objects
requests for input and output: I/O
requests, intercepting: Control Characters
requests, invoking: Invoking Requests
requests, modifying: Control Characters
resolution, device: Page Geometry
resolution, device: DESC File Format
resolution, device, obtaining in the formatter: Measurements
resolution, horizontal: DESC File Format
resolution, horizontal, register (.H): Motion Quanta
resolution, vertical: DESC File Format
returning to marked vertical page location (rt): Page Motions
revision number register (.Y): Built-in Registers
right margin: Line Layout
right-aligning lines (introduction): Basics
right-justifying (rj): Manipulating Filling and Adjustment
right-justifying lines (introduction): Basics
rivers: Other Differences
rj request, causing implicit break: Manipulating Filling and Adjustment
rn glyph, and cflags: Using Symbols
roman glyph, correction after italic glyph (\/): Italic Corrections
roman glyph, correction before italic glyph (\,): Italic Corrections
Roman numerals: Assigning Register Formats
Roman numerals, extrema (maximum and minimum): Assigning Register Formats
rq glyph, at end of sentence: Sentences
rq glyph, at end of sentence: Using Symbols
rt request, using + and - with: Numeric Expressions
ru glyph, and cflags: Using Symbols
running system commands: I/O
S
s scaling unit: Using Fractional Type Sizes
safer mode: Groff Options
safer mode: Macro Directories
safer mode: Built-in Registers
safer mode: I/O
safer mode: I/O
safer mode: I/O
safer mode: I/O
safer mode: Safer Mode
saving horizontal input line position (\k): Page Motions
scaling indicator: Measurements
scaling operator: Numeric Expressions
scaling unit c: Measurements
scaling unit f: Colors
scaling unit i: Measurements
scaling unit m: Measurements
scaling unit M: Measurements
scaling unit n: Measurements
scaling unit p: Measurements
scaling unit P: Measurements
scaling unit s: Using Fractional Type Sizes
scaling unit u: Measurements
scaling unit v: Measurements
scaling unit z: Using Fractional Type Sizes
searching fonts: Font Directories
searching macros: Macro Directories
seconds, current time (seconds): Built-in Registers
selecting the previous font (ft): Selecting Fonts
sentence space: Sentences
sentence space size register (.sss): Manipulating Filling and Adjustment
sentences: Sentences
sequence, escape: Formatter Instructions
setting diversion trap (dt): Diversion Traps
setting end-of-input trap (em): End-of-input Traps
setting input line number (lf): Debugging
setting input line trap (it, itc): Input Line Traps
setting registers (nr, \R): Setting Registers
setting the page length (pl): Page Layout
setting up an abstract font style (sty): Font Families
shc request, and translations: Character Translations
site-local directory: Macro Directories
site-local directory: Font Directories
size of sentence space register (.sss): Manipulating Filling and Adjustment
size of word space register (.ss): Manipulating Filling and Adjustment
size, optical, of a font: Selecting Fonts
size, paper: Paper Format
size, size: Manipulating Type Size and Vertical Spacing
sizes, fractional: Other Differences
sizes, fractional type: Using Fractional Type Sizes
skew, of last glyph (.csk): Environments
slant, font, changing (\S): Artificial Fonts
soft hyphen character, setting (shc): Manipulating Hyphenation
soft hyphen glyph (hy): Manipulating Hyphenation
solid circle, drawing (‘\D'C …'’): Drawing Geometric Objects
solid ellipse, drawing (‘\D'E …'’): Drawing Geometric Objects
solid polygon, drawing (‘\D'P …'’): Drawing Geometric Objects
SOURCE_DATE_EPOCH, environment variable: Environment
sp request, and no-space mode: Manipulating Spacing
sp request, causing implicit break: Manipulating Filling and Adjustment
space between sentences: Sentences
space between sentences register (.sss): Manipulating Filling and Adjustment
space between words register (.ss): Manipulating Filling and Adjustment
space character, as delimiter: Delimiters
space characters, in expressions: Numeric Expressions
space, between sentences: Manipulating Filling and Adjustment
space, between words: Manipulating Filling and Adjustment
space, discardable, horizontal: Manipulating Filling and Adjustment
space, hair (\^): Page Motions
space, horizontal (\h): Page Motions
space, horizontal, unformatting: Punning Names
space, thin (\|): Page Motions
space, unbreakable (\~): Manipulating Filling and Adjustment
space, unbreakable and unadjustable (\SP): Page Motions
space, vertical, unit (v): Measurements
space, width of a digit (numeral) (\0): Page Motions
spaces with ds: Strings
spaces, in a macro argument: Calling Macros
spaces, leading and trailing: Breaking
spacing (introduction): Basics
spacing, manipulating: Manipulating Spacing
spacing, vertical: Page Geometry
spacing, vertical: Manipulating Type Size and Vertical Spacing
spacing, vertical (introduction): Basics
special characters: Sentences
special characters: Character Translations
special characters [ms]: ms Legacy Features
special characters, list of (groff_char(7) man page): Using Symbols
special font: Using Fonts
special fonts: Using Symbols
special fonts: Special Fonts
special fonts: Font Description File Format
special fonts, emboldening: Artificial Fonts
special request, and font translations: Selecting Fonts
special request, and glyph search order: Using Symbols
spline, drawing (‘\D'~ …'’): Drawing Geometric Objects
springing a trap: Traps
sqrtex glyph, and cflags: Using Symbols
ss request, incompatibilities with AT&T troff: Other Differences
stack: Environments
stacking glyphs (\b): Drawing Geometric Objects
standard input, reading from (rd): I/O
stderr, printing to (tm, tm1, tmc): Debugging
stops, tab: Tabs and Leaders
string arguments: Strings
string comparison: Operators in Conditionals
string expansion (\*): Strings
string interpolation (\*): Strings
string, appending (as): Strings
string, creating alias for (als): Strings
string, length of (length): Strings
string, removing (rm): Strings
string, removing alias for (rm): Strings
string, renaming (rn): Strings
strings: Strings
strings [ms]: ms Legacy Features
strings, multi-line: Strings
strings, shared name space with macros and diversions: Identifiers
stripping final newline in diversions: Punning Names
stroke color: Colors
stroke color name register (.m): Colors
stroked circle, drawing (‘\D'c …'’): Drawing Geometric Objects
stroked ellipse, drawing (‘\D'e …'’): Drawing Geometric Objects
stroked polygon, drawing (‘\D'p …'’): Drawing Geometric Objects
structuring source code of documents or macro packages: Invoking Requests
sty request, and changing fonts: Selecting Fonts
sty request, and font translations: Selecting Fonts
style, font: Using Fonts
style, font, abstract: Using Fonts
style, font, abstract, setting up (sty): Font Families
styles, font: Font Families
substring (substring): Strings
subtraction: Numeric Expressions
suppressing output (\O): Suppressing Output
suppression nesting level register: Suppressing Output
sv request, and no-space mode: Page Control
switching environments (ev): Environments
sy request, and safer mode: Groff Options
sy request, disabled by default: Safer Mode
symbol: Using Symbols
symbol table, dumping (pm): Debugging
symbol, defining (char): Using Symbols
symbols, using: Using Symbols
system commands, running: I/O
system() return value register (systat): I/O
T
tab character: Tabs and Leaders
tab character encoding: Tabs and Fields
tab character, and translations: Character Translations
tab character, as delimiter: Delimiters
tab character, non-interpreted (\t): Tabs and Fields
tab repetition character (tc): Tabs and Fields
tab stop settings register (.tabs): Tabs and Fields
tab stops: Tabs and Leaders
tab stops, default: Tabs and Fields
tab, line-tabs mode: Tabs and Fields
table of contents: Table of Contents
table of contents: Leaders
table of contents, creating [ms]: ms TOC
table, multi-page, example [ms]: ms Insertions
tables [ms]: ms Insertions
tabs, and fields: Tabs and Fields
tabs, and macro arguments: Invoking Requests
tabs, and request arguments: Invoking Requests
tabs, before comments: Comments
tagged paragraphs: Paragraphs
tags, paragraph: Paragraphs
terminal, conditional output for: Operators in Conditionals
text baseline: Page Geometry
text baseline: Manipulating Type Size and Vertical Spacing
text font: Using Fonts
text line: Requests and Macros
text line, position of lowest (.h): Diversions
text, GNU troff processing: Text
text, justifying: Manipulating Filling and Adjustment
text, justifying (rj): Manipulating Filling and Adjustment
thickness of lines (‘\D't …'’): Drawing Geometric Objects
thin space (\|): Page Motions
three-part title (tl): Page Layout
ti request, causing implicit break: Manipulating Filling and Adjustment
ti request, using + and - with: Numeric Expressions
time, current, hours (hours): Built-in Registers
time, current, minutes (minutes): Built-in Registers
time, current, seconds (seconds): Built-in Registers
time, formatting: I/O
title length, configuring (lt): Page Layout
title line length register (.lt): Page Layout
title line, formatting (tl): Page Layout
titles: Page Layout
tkf request, and font styles: Font Families
tkf request, and font translations: Selecting Fonts
tkf request, with fractional type sizes: Using Fractional Type Sizes
tl request, and mc: Miscellaneous
tmac, directory: Macro Directories
tmac, path: Macro Directories
TMPDIR, environment variable: Environment
token, input: Gtroff Internals
top margin: Page Location Traps
top-level diversion: Diversions
top-level diversion, and bp: Page Control
top-level diversion, and \!: Diversions
top-level diversion, and \?: Diversions
tr request, and glyph definitions: Using Symbols
tr request, and soft hyphen character: Manipulating Hyphenation
tr request, incompatibilities with AT&T troff: Other Differences
track kerning: Ligatures and Kerning
track kerning, activating (tkf): Ligatures and Kerning
trailing double quotes in strings: Strings
trailing spaces in string definitions and appendments: Strings
trailing spaces on text lines: Breaking
translations of characters: Character Translations
transparent characters: Using Symbols
transparent dummy character (\)): Dummy Characters
transparent output (cf, trf): I/O
transparent output (\!, \?): Diversions
transparent output, incompatibilities with AT&T troff: Other Differences
trap: Deferring Output
trap, changing location (ch): Page Location Traps
trap, distance to next vertical position, register (.t): Page Location Traps
trap, diversion, setting (dt): Diversion Traps
trap, end-of-input, setting (em): End-of-input Traps
trap, implicit: The Implicit Page Trap
trap, input line, clearing (it, itc): Input Line Traps
trap, input line, setting (it, itc): Input Line Traps
trap, planting: Traps
trap, springing: Traps
traps: Traps
traps, and diversions: Page Location Traps
traps, blank line: Blank Line Traps
traps, diversion: Diversion Traps
traps, end-of-input: End-of-input Traps
traps, input line: Input Line Traps
traps, input line, and interrupted lines (itc): Input Line Traps
traps, leading space: Leading Space Traps
traps, page location: Page Location Traps
traps, page location, dumping (ptr): Debugging
traps, page location, listing (ptr): Debugging
traps, sprung by bp request (.pe): Page Location Traps
traps, vertical position: Vertical Position Traps
trf request, and copy mode: I/O
trf request, and invalid characters: I/O
trf request, causing implicit break: Manipulating Filling and Adjustment
trin request, and asciify: Diversions
troff mode: troff and nroff Modes
troff output: gtroff Output
truncated vertical space register (.trunc): Page Location Traps
truncating division: Numeric Expressions
TTY, conditional output for: Operators in Conditionals
tutorial for macro users: Tutorial for Macro Users
type size: Manipulating Type Size and Vertical Spacing
type size registers (.s, .ps): Changing the Type Size
type size registers, last-requested (.psr, .sr): Using Fractional Type Sizes
type sizes, changing (ps, \s): Changing the Type Size
type sizes, fractional: Using Fractional Type Sizes
type sizes, fractional: Other Differences
typeface: Using Fonts
TZ, environment variable: Environment
U
u scaling unit: Measurements
uf request, and font styles: Font Families
ul glyph, and cflags: Using Symbols
ul request, and font translations: Selecting Fonts
Ultrix-specific man macros: Optional man extensions
unadjustable and unbreakable space (\SP): Page Motions
unary arithmetic operators: Numeric Expressions
unbreakable and unadjustable space (\SP): Page Motions
unbreakable space (\~): Manipulating Filling and Adjustment
undefined identifiers: Identifiers
undefined request: Comments
underline font (uf): Artificial Fonts
underlining (ul): Artificial Fonts
underlining, continuous (cu): Artificial Fonts
unformatting diversions (asciify): Diversions
unformatting horizontal space: Punning Names
Unicode: Identifiers
Unicode: Using Symbols
unit, scaling, c: Measurements
unit, scaling, f: Colors
unit, scaling, i: Measurements
unit, scaling, m: Measurements
unit, scaling, M: Measurements
unit, scaling, n: Measurements
unit, scaling, p: Measurements
unit, scaling, P: Measurements
unit, scaling, s: Using Fractional Type Sizes
unit, scaling, u: Measurements
unit, scaling, v: Measurements
unit, scaling, z: Using Fractional Type Sizes
units of measurement: Measurements
units, basic: Page Geometry
units, basic, conversion to: Measurements
units, default: Default Units
units, machine: Page Geometry
unnamed glyphs: Using Symbols
unnamed glyphs, accessing with \N: Font Description File Format
unsafe mode: Groff Options
unsafe mode: Macro Directories
unsafe mode: Built-in Registers
unsafe mode: I/O
unsafe mode: I/O
unsafe mode: I/O
unsafe mode: I/O
unstyled font: Using Fonts
up-casing a string (stringup): Strings
uppercasing a string (stringup): Strings
upright glyph, correction after oblique glyph (\/): Italic Corrections
upright glyph, correction before oblique glyph (\,): Italic Corrections
URLs, breaking (\:): Manipulating Hyphenation
user’s macro tutorial: Tutorial for Macro Users
user’s tutorial for macros: Tutorial for Macro Users
using escape sequences: Using Escape Sequences
using symbols: Using Symbols
UTF-8 output encoding: Groff Options
V
v scaling unit: Measurements
valid numeric expression: Numeric Expressions
value, incrementing without changing the register: Auto-increment
variables in environment: Environment
vee: Page Geometry
vee scaling unit (v): Measurements
version number, major, register (.x): Built-in Registers
version number, minor, register (.y): Built-in Registers
vertical drawing position (nl): Page Control
vertical line drawing (\L): Drawing Geometric Objects
vertical line spacing register (.v): Changing the Vertical Spacing
vertical line spacing, changing (vs): Changing the Vertical Spacing
vertical line spacing, effective value: Changing the Vertical Spacing
vertical motion (\v): Page Motions
vertical motion quantum: DESC File Format
vertical page location, marking (mk): Page Motions
vertical page location, returning to marked (rt): Page Motions
vertical position in diversion register (.d): Diversions
vertical position trap enable register (.vpt): Vertical Position Traps
vertical position traps: Vertical Position Traps
vertical position traps, enabling (vpt): Vertical Position Traps
vertical position, drawing (nl): Page Control
vertical resolution: DESC File Format
vertical space unit (v): Measurements
vertical spacing: Page Geometry
vertical spacing: Manipulating Type Size and Vertical Spacing
vertical spacing (introduction): Basics
W
warning categories: Warnings
warning level (warn): Debugging
warnings: Debugging
warnings: Warnings
what is groff?: What Is groff?
while: while
while request, and font translations: Selecting Fonts
while request, and the ‘!’ operator: Numeric Expressions
while request, confusing with br: while
while request, operators to use with: Operators in Conditionals
widow: Page Control
widow: Page Control
width escape (\w): Page Motions
width, of last glyph (.w): Environments
word space size register (.ss): Manipulating Filling and Adjustment
word, definition of: Filling
write request, and copy mode: I/O
writec request, and copy mode: I/O
writem request, and copy mode: I/O
writing macros: Writing Macros
writing to file (write, writec): I/O
Y
year, current, register (year, yr): Built-in Registers
Z
z scaling unit: Using Fractional Type Sizes
zero-width printing (\z, \Z): Page Motions
zero-width printing (\z, \Z): Page Motions
zoom factor of a font (fzoom): Selecting Fonts
+
Jump to:   " +   +% +   +& +   +' +   +( +   +) +   +* +   ++ +   +- +   +. +   +/ +   +8 +   +: +   +< +   += +   +> +   +[ +   +\ +   +] +   +| +   +
+A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +J +   +K +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +W +   +Y +   +Z +   +
+
+ + +
+
+
+
+
+

+   [Contents][Index]

+
+

Footnotes

+ +
(1)
+

The ‘g’ prefix is +not used on all systems; see Invoking groff.

+
(2)
+

Unix and related operating systems distinguish +standard output and standard error streams because of +troff: +https://minnie.tuhs.org/pipermail/tuhs/2013-December/006113.html.

+
(3)
+

See Line Layout.

+
(4)
+

Besides groff, neatroff is an +exception.

+
(5)
+

The +mso request does not have these limitations. See I/O.

+
(6)
+

The remainder of this chapter is based on +Writing Papers with nroff using -me by Eric P. Allman, +which is distributed with groff as meintro.me.

+
(7)
+

While manual pages are older, early ones used +macros supplanted by the man package of Seventh Edition Unix +(1979). ms shipped with Sixth Edition (1975) and was documented +by Mike Lesk in a Bell Labs internal memorandum.

+
(8)
+

defined in Footnotes

+
(9)
+

Distinguish a +document title from “titles”, which are what roff systems call +headers and footers collectively.

+
(10)
+

This idiosyncrasy arose through +feature accretion; for example, the B macro in Version 6 +Unix ms (1975) accepted only one argument, the text to be set in +boldface. By Version 7 (1979) it recognized a second argument; in +1990, groff ms added a “pre” argument, placing it third +to avoid breaking support for older documents.

+
(11)
+

“Portable Document Format Publishing with GNU +Troff”, pdfmark.ms in the groff distribution, uses this +technique.

+
(12)
+

Unix Version 7 ms, its descendants, and GNU +ms prior to groff version 1.23.0

+
(13)
+

You could reset it +after each call to .1C, .2C, or .MC.

+
(14)
+

Typing Documents on the UNIX System: Using the +-ms Macros with Troff and Nroff, M. E. Lesk, Bell Laboratories, +1978

+
(15)
+

Register values are converted to and stored as +basic units. See Measurements.

+
(16)
+

If you redefine the ms PT macro +and desire special treatment of certain page numbers (like ‘1’), +you may need to handle a non-Arabic page number format, as groff +ms’s PT does; see the macro package source. groff +ms aliases the PN register to %.

+
(17)
+

The removal beforehand is necessary +because groff ms aliases these macros to a diagnostic +macro, and you want to redefine the aliased name, not its target.

+
(18)
+

See Device and Font Description Files.

+
(19)
+

Tabs and leaders also separate +words. Escape sequences can function as word characters, word +separators, or neither—the last simply have no effect on GNU +troff’s idea of whether an input character is within a word. +We’ll discuss all of these in due course.

+
(20)
+

A +well-researched jeremiad appreciated by groff contributors on +both sides of the sentence-spacing debate can be found at +https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324.

+
(21)
+

This statement oversimplifies; there are +escape sequences whose purpose is precisely to produce glyphs on the +output device, and input characters that aren’t part of escape +sequences can undergo a great deal of processing before getting to the +output.

+
(22)
+

The mnemonics for the special +characters shown here are “dagger”, “double dagger”, “right +(double) quote”, and “closing (single) quote”. See the +groff_char(7) man page.

+
(23)
+

“Text lines” are defined in Requests and Macros.

+
(24)
+

“Tab” +is short for “tabulation”, revealing the term’s origin as a spacing +mechanism for table arrangement.

+
(25)
+

The \RET escape sequence can alter how an +input line is classified; see Line Continuation.

+
(26)
+

Argument handling in +macros is more flexible but also more complex. See Calling Macros.

+
(27)
+

Some escape sequences undergo +interpolation as well.

+
(28)
+

GNU troff offers additional ones. See Writing Macros.

+
(29)
+

Macro files and packages +frequently define registers and strings as well.

+
(30)
+

The +semantics of certain punctuation code points have gotten stricter +with the successive standards, a cause of some frustration among man +page writers; see the groff_char(7) man page.

+
(31)
+

The +DVI output device defaults to using the Computer Modern (CM) fonts; +ec.tmac loads the EC fonts instead, which provide Euro +‘\[Eu]’ and per mille ‘\[%0]’ glyphs.

+
(32)
+

Emacs: fill-column: 72; Vim: textwidth=72

+
(33)
+

groff does not yet support right-to-left +scripts.

+
(34)
+

groff’s terminal output devices have page +offsets of zero.

+
(35)
+

Provision is made for interpreting and +reporting decimal fractions in certain cases.

+
(36)
+

If that’s not enough, see the groff_tmac(5) +man page for the 62bit.tmac macro package.

+
(37)
+

See Conditionals and Loops.

+
(38)
+

Control structure syntax +creates an exception to this rule, but is designed to remain useful: +recalling our example, ‘.if 1 .Underline this’ would underline only +“this”, precisely. See Conditionals and Loops.

+
(39)
+

See Diversions.

+
(40)
+

Historically, control characters like +ASCII STX, ETX, and BEL (Control+B, Control+C, and +Control+G) have been observed in roff documents, +particularly in macro packages employing them as delimiters with the +output comparison operator to try to avoid collisions with the content +of arbitrary user-supplied parameters (see Operators in Conditionals). We discourage this expedient; in GNU troff it is +unnecessary (outside of compatibility mode) because delimited arguments +are parsed at a different input level than the surrounding context. +See Implementation Differences.

+
(41)
+

Consider what happens when a C1 control +0x80–0x9F is necessary as a continuation byte in a UTF-8 +sequence.

+
(42)
+

Recall Identifiers.

+
(43)
+

In compatibility +mode, a space is not necessary after a request or macro name of two +characters’ length. Also, Plan 9 troff allows tabs to +separate arguments.

+
(44)
+

\~ is fairly +portable; see Other Differences.

+
(45)
+

Strictly, you can neglect to +close the last quoted macro argument, relying on the end of the control +line to do so. We consider this lethargic practice poor style.

+
(46)
+

The omission of spaces before the comment +escape sequences is necessary; see Strings.

+
(47)
+

TeX does have such a mechanism.

+
(48)
+

This claim may be more aspirational than descriptive.

+
(49)
+

See Conditional Blocks.

+
(50)
+

Exception: auto-incrementing registers defined outside +the ignored region will be modified if interpolated with +\n± inside it. See Auto-increment.

+
(51)
+

A negative auto-increment can be +considered an “auto-decrement”.

+
(52)
+

GNU troff dynamically allocates memory for +as many registers as required.

+
(53)
+

unless diverted; see Diversions

+
(54)
+

See Line Continuation.

+
(55)
+

Recall Filling and Sentences for the +definitions of word and sentence boundaries, respectively.

+
(56)
+

Whether a perfect algorithm for this application is +even possible is an unsolved problem in computer science: +https://tug.org/docs/liang/liang-thesis.pdf.

+
(57)
+

\% itself stops marking +hyphenation points but still produces no output glyph.

+
(58)
+

“Soft” because it appears in output +only where a hyphenation break is performed; a “hard” hyphen, as in +“long-term”, always appears.

+
(59)
+

The mode is a vector of Booleans encoded as an integer. +To a programmer, this fact is easily deduced from the exclusive use of +powers of two for the configuration parameters; they are computationally +easy to “mask off” and compare to zero. To almost everyone else, the +arrangement seems recondite and unfriendly.

+
(60)
+

Hyphenation is +prevented if the next page location trap is closer to the vertical +drawing position than the next text baseline would be. See Page Location Traps.

+
(61)
+

For more on localization, see the +groff_tmac(5) man page.

+
(62)
+

See Page Location Traps.

+
(63)
+

See Drawing Geometric Objects.

+
(64)
+

or geometric objects; see Drawing Geometric Objects

+
(65)
+

to the top-level diversion; +see Diversions

+
(66)
+

Plan 9 troff +uses the register .S for this purpose.

+
(67)
+

This is pronounced to rhyme with “feeder”, and +refers to how the glyphs “lead” the eye across the page to the +corresponding page number or other datum.

+
(68)
+

A +GNU nroff program is available for convenience; it calls GNU +troff to perform the formatting.

+
(69)
+

Historically, the \c +escape sequence has proven challenging to characterize. Some sources +say it “connects the next input text” (to the input line on which it +appears); others describe it as “interrupting” text, on the grounds +that a text line is interrupted without breaking, perhaps to inject a +request invocation or macro call.

+
(70)
+

See Traps.

+
(71)
+

See Diversions.

+
(72)
+

Terminals and some output devices have fonts that render +at only one or two sizes. As examples of the latter, take the +groff lj4 device’s Lineprinter, and lbp’s Courier +and Elite faces.

+
(73)
+

Font designers prepare families such that the styles +share esthetic properties.

+
(74)
+

Historically, the fonts +troffs dealt with were not Free Software or, as with the Graphic +Systems C/A/T, did not even exist in the digital domain.

+
(75)
+

See Font Description File Format.

+
(76)
+

See DESC File Format.

+
(77)
+

Not all versions of the man program +support the -T option; use the subsequent example for an +alternative.

+
(78)
+

This is “Normalization Form D” +as documented in Unicode Standard Annex #15 +(https://unicode.org/reports/tr15/).

+
(79)
+

See Compatibility Mode.

+
(80)
+

Output glyphs +don’t—to GNU troff, a glyph is simply a box with an index into +a font, a given height above and depth below the baseline, and a width.

+
(81)
+

Opinions of this escape sequence’s name abound. +“Zero-width space” is a popular misnomer: roff formatters do +not treat it like a space. Ossanna called it a “non-printing, +zero-width character”, but the character causes output even +though it does not “print”. If no output line is pending, the dummy +character starts one. Contrast an empty input document with one +containing only \&. The former produces no output; the latter, a +blank page.

+
(82)
+

In text fonts, the tallest glyphs are typically +parentheses. Unfortunately, in many cases the actual dimensions of the +glyphs in a font do not closely match its declared type size! For +example, in the standard PostScript font families, 10-point Times sets +better with 9-point Helvetica and 11-point Courier than if all three +were used at 10 points.

+
(83)
+

Rhyme with “sledding”; mechanical typography +used lead metal (Latin plumbum).

+
(84)
+

The claim appears to have been true of Ossanna +troff for the C/A/T device; Kernighan made device-independent +troff more flexible.

+
(85)
+

See Device and Font Description Files.

+
(86)
+

also +known vulgarly as “ANSI colors”

+
(87)
+

See Copy Mode.

+
(88)
+

This refers to +vtroff, a translator that would convert the C/A/T output from +early-vintage AT&T troff to a form suitable for +Versatec and Benson-Varian plotters.

+
(89)
+

Strictly, letters not otherwise recognized are treated +as output comparison delimiters. For portability, it is wise to avoid +using letters not in the list above; for example, Plan 9 +troff uses ‘h’ to test a mode it calls htmlroff, and +GNU troff may provide additional operators in the future.

+
(90)
+

Because formatting of the comparands takes place +in a dummy environment, vertical motions within them cannot spring +traps.

+
(91)
+

All +of this is to say that the lists of output nodes created by formatting +xxx and yyy must be identical. See gtroff Internals.

+
(92)
+

This bizarre behavior maintains compatibility with +AT&T troff.

+
(93)
+

See while.

+
(94)
+

See Copy Mode.

+
(95)
+

unless you redefine it

+
(96)
+

“somewhat less” because +things other than macro calls can be on the input stack

+
(97)
+

See Copy Mode.

+
(98)
+

While it is possible to define and +call a macro ‘.’, you can’t use it as an end macro: during a macro +definition, ‘..’ is never handled as calling ‘.’, even if +‘.de name .’ explicitly precedes it.

+
(99)
+

Its structure is +adapted from, and isomorphic to, part of a solution by Tadziu Hoffman to +the problem of reflowing text multiple times to find an optimal +configuration for it. +https://lists.gnu.org/archive/html/groff/2008-12/msg00006.html

+
(100)
+

If they were not, +parameter interpolations would be similar to command-line +parameters—fixed for the entire duration of a roff program’s +run. The advantage of interpolating \$ escape sequences even in +copy mode is that they can interpolate different contents from one call +to the next, like function parameters in a procedural language. The +additional escape character is the price of this power.

+
(101)
+

Compare this to the \def and \edef +commands in TeX.

+
(102)
+

These are lightly adapted from the groff +implementation of the ms macros.

+
(103)
+

At the +grops defaults of 10-point type on 12-point vertical spacing, the +difference between half a vee and half an em can be subtle: large +spacings like ‘.vs .5i’ make it obvious.

+
(104)
+

See Strings, for an explanation of the trailing +‘\"’.

+
(105)
+

(hc, vc) is adjusted to the point nearest +the perpendicular bisector of the arc’s chord.

+
(106)
+

See The Implicit Page Trap.

+
(107)
+

A trap planted at ‘20i’ or +‘-30i’ will not be sprung on a page of length ‘11i’.

+
(108)
+

It may help to think of each trap location as +maintaining a queue; wh operates on the head of the queue, and +ch operates on its tail. Only the trap at the head of the queue +is visible.

+
(109)
+

See Debugging.

+
(110)
+

See Diversions.

+
(111)
+

While processing an +end-of-input macro, the formatter assumes that the next page break must +be the last; it goes into “sudden death overtime”.

+
(112)
+

Another, taken by the groff man macros, is +to intercept ne requests and wrap bp ones.

+
(113)
+

Thus, the “water” +gets “higher” proceeding down the page.

+
(114)
+

The backslash is doubled. See Copy Mode.

+
(115)
+

that is, ISO 646:1991-IRV or, +popularly, “US-ASCII”

+
(116)
+

They are bypassed because these parameters are not +rendered as glyphs in the output; instead, they remain abstract +characters—in a PDF bookmark or a URL, for example.

+
(117)
+

Recall Line Layout.

+
(118)
+

Historically, +tools named nrchbar and changebar were developed for +marking changes with margin characters and could be found in archives of +the comp.sources.unix USENET group. Some proprietary +Unices also offer(ed) a diffmk program.

+
(119)
+

Except the +escape sequences \f, \F, \H, \m, \M, +\R, \s, and \S, which are processed immediately if +not in copy mode.

+
(120)
+

The +Graphic Systems C/A/T phototypesetter (the original device target for +AT&T troff) supported only a few discrete type sizes +in the range 6–36 points, so Ossanna contrived a special case in the +parser to do what the user must have meant. Kernighan warned of this in +the 1992 revision of CSTR #54 (§2.3), and more recently, McIlroy +referred to it as a “living fossil”.

+
(121)
+

DWB 3.3, Solaris, Heirloom Doctools, and +Plan 9 troff all support it.

+
(122)
+

Naturally, if you’ve changed +the escape character, you need to prefix the e with whatever it +is—and you’ll likely get something other than a backslash in the +output.

+
(123)
+

The rs special character identifier was not +defined in AT&T troff’s font description files, but is +in those of its lineal descendant, Heirloom Doctools troff, as of +the latter’s 060716 release (July 2006).

+
(124)
+

The parser +and postprocessor for intermediate output can be found in the file
+groff-source-dir/src/libs/libdriver/input.cpp.

+
(125)
+

Plan 9 troff has also abandoned the binary +format.

+
(126)
+

800-point type +is not practical for most purposes, but using it enables the quantities +in the font description files to be expressed as integers.

+
(127)
+

groff requests and escape sequences +interpret non-negative font names as mounting positions instead. +Further, a font named ‘0’ cannot be automatically mounted by the +fonts directive of a DESC file.

+
(128)
+

For typesetter devices, this directive is misnamed +since it starts a list of glyphs, not characters.

+
(129)
+

that is, any integer parsable by the C +standard library’s strtol(3) function

+
+ + + + diff --git a/doc/groff.html.node/Adjustment.html b/doc/groff.html.node/Adjustment.html new file mode 100644 index 0000000..60b01c4 --- /dev/null +++ b/doc/groff.html.node/Adjustment.html @@ -0,0 +1,57 @@ + + + + + + +Adjustment (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+
+

5.1.5 Adjustment

+ + +

After GNU troff performs an automatic break, it may then +adjust the line, widening inter-word spaces until the text reaches +the right margin. Extra spaces between words are preserved. Leading +and trailing spaces are handled as noted above. Text can be aligned to +the left or right margin only, or centered; see Manipulating Filling and Adjustment. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Argument-Units.html b/doc/groff.html.node/Argument-Units.html new file mode 100644 index 0000000..c7cbb16 --- /dev/null +++ b/doc/groff.html.node/Argument-Units.html @@ -0,0 +1,68 @@ + + + + + + +Argument Units (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Language Concepts   [Contents][Index]

+
+
+

6.1.1.2 Argument Units

+ +

Some commands take integer arguments that are assumed to represent +values in a measurement unit, but the letter for the corresponding +scaling unit is not written with the output command arguments. Most +commands assume the scaling unit ‘u’, the basic unit of the device, +some use ‘z’, the scaled point unit of the device, while others, +such as the color commands, expect plain integers. +

+

Single characters can have the eighth bit set, as can the names of +fonts and special characters. The names of characters and fonts can be +of arbitrary length. A character that is to be printed is always in +the current font. +

+

A string argument is always terminated by the next whitespace character +(space, tab, or newline); an embedded ‘#’ character is regarded as +part of the argument, not as the beginning of a comment command. An +integer argument is already terminated by the next non-digit character, +which then is regarded as the first character of the next argument or +command. +

+
+ + + + + diff --git a/doc/groff.html.node/Artificial-Fonts.html b/doc/groff.html.node/Artificial-Fonts.html new file mode 100644 index 0000000..6f9d43d --- /dev/null +++ b/doc/groff.html.node/Artificial-Fonts.html @@ -0,0 +1,252 @@ + + + + + + +Artificial Fonts (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+
+

5.19.7 Artificial Fonts

+ + + +

There are a number of requests and escape sequences for artificially +creating fonts. These are largely vestiges of the days when output +devices did not have a wide variety of fonts, and when nroff and +troff were separate programs. Most of them are no longer +necessary in GNU troff. Nevertheless, they are supported. +

+
+
Escape sequence: \H'height'
+
+
Escape sequence: \H'+height'
+
Escape sequence: \H'-height'
+
Register: \n[.height]
+
+ + + +

Change (increment, decrement) the height of the current font, but not +the width. If height is zero, restore the original height. +Default scaling unit is ‘z’. +

+

The read-only register .height contains the font height as set by +\H. +

+

Currently, only the -Tps and -Tpdf devices support +this feature. +

+

\H doesn’t produce an input token in GNU troff. As a +consequence, it can be used in requests like mc (which expects +a single character as an argument) to change the font on the fly: +

+
+
.mc \H'+5z'x\H'0'
+
+ +

In compatibility mode, gtroff behaves differently: If an +increment or decrement is used, it is always taken relative to the +current type size and not relative to the previously selected font +height. Thus, +

+
+
.cp 1
+\H'+5'test \H'+5'test
+
+ +

prints the word ‘test’ twice with the same font height (five points +larger than the current font size). +

+ +
+
Escape sequence: \S'slant'
+
+
Register: \n[.slant]
+
+ + + +

Slant the current font by slant degrees. Positive values slant to +the right. Only integer values are possible. +

+

The read-only register .slant contains the font slant as set by +\S. +

+

Currently, only the -Tps and -Tpdf devices support +this feature. +

+

\S doesn’t produce an input token in GNU troff. As a +consequence, it can be used in requests like mc (which expects +a single character as an argument) to change the font on the fly: +

+
+
.mc \S'20'x\S'0'
+
+ + + +

This escape is incorrectly documented in the AT&T +troff manual; the slant is always set to an absolute value. +

+ +
+
Request: .ul [lines]
+
+ +

The ul request normally underlines subsequent lines if a TTY +output device is used. Otherwise, the lines are printed in italics +(only the term ‘underlined’ is used in the following). The single +argument is the quantity of input lines to be underlined; with no +argument, the next line is underlined. If lines is zero or +negative, stop the effects of ul (if it was active). Requests +and empty lines do not count for computing the number of underlined +input lines, even if they produce some output like tl. Lines +inserted by macros (e.g., invoked by a trap) do count. +

+

At the beginning of ul, the current font is stored and the +underline font is activated. Within the span of a ul request, it +is possible to change fonts, but after the last line affected by +ul the saved font is restored. +

+

This number of lines still to be underlined is associated with the +environment (see Environments). The underline font can be changed +with the uf request. +

+ + +

The ul request does not underline spaces. +

+ +
+
Request: .cu [lines]
+
+ + +

The cu request is similar to ul but underlines spaces as +well (if a TTY output device is used). +

+ +
+
Request: .uf font
+
+ + +

Set the underline font (globally) used by ul and cu. By +default, this is the font at position 2. font can be either +a non-negative font position or the name of a font. +

+ +
+
Request: .bd font [offset]
+
+
Request: .bd font1 font2 [offset]
+
Register: \n[.b]
+
+ + +

Embolden font by overstriking its glyphs offset by offset +units minus one. +

+

Two syntax forms are available. +

+
    +
  • Imitate a bold font unconditionally. The first argument specifies the +font to embolden, and the second is the number of basic units, minus +one, by which the two glyphs are offset. If the second argument is +missing, emboldening is turned off. + +

    font can be either a non-negative font position or the name of a +font. +

    +

    offset is available in the .b read-only register if a +special font is active; in the bd request, its default unit is +‘u’. +

    +
  • + + + +Imitate a bold form conditionally. Embolden font1 by offset +only if font font2 is the current font. This request can be +issued repeatedly to set up different emboldening values for different +current fonts. If the second argument is missing, emboldening is turned +off for this particular current font. + +

    This affects special fonts only (either set up with the special +command in font files or with the fspecial request). +

+
+ +
+
Request: .cs font [width [em-size]]
+
+ + + + +

Switch to and from constant glyph space mode. If activated, the +width of every glyph is width/36 ems. The em size is given +absolutely by em-size; if this argument is missing, the em value +is taken from the current font size (as set with the ps request) +when the font is effectively in use. Without second and third argument, +constant glyph space mode is deactivated. +

+

Default scaling unit for em-size is ‘z’; width is an +integer. +

+ + +
+
+
+

+Next: Ligatures and Kerning, Previous: Special Fonts, Up: Using Fonts   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Assigning-Register-Formats.html b/doc/groff.html.node/Assigning-Register-Formats.html new file mode 100644 index 0000000..ff0ddfa --- /dev/null +++ b/doc/groff.html.node/Assigning-Register-Formats.html @@ -0,0 +1,188 @@ + + + + + + +Assigning Register Formats (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Registers   [Contents][Index]

+
+
+

5.8.4 Assigning Register Formats

+ + + + +

A writable register’s value can be interpolated in several number +formats. By default, conventional Arabic numerals are used. +Other formats see use in sectioning and outlining schemes and +alternative page numbering arrangements. +

+
+
Request: .af reg fmt
+
+

Use number format fmt when interpolating register reg. +Valid number formats are as follows. +

+
+
0…
+

Arabic numerals 0, 1, 2, and so on. +Any decimal digit is equivalent to ‘0’; the formatter merely counts +the digits specified. Multiple Arabic numerals in fmt cause +interpolations to be zero-padded on the left if necessary to at least as +many digits as specified (interpolations never truncate a register +value). A register with format ‘00’ interpolates values 1, 2, 3 as +‘01’, ‘02’, ‘03’. The default format for all writable +registers is ‘0’. +

+
+
I
+
+

Uppercase Roman numerals: 0, I, II, III, IV, ... +

+
+
i
+

Lowercase Roman numerals: 0, i, ii, iii, iv, ... +

+
+
A
+

Uppercase letters: 0, A, B, C, …, Z, AA, AB, ... +

+
+
a
+

Lowercase letters: 0, a, b, c, …, z, aa, ab, ... +

+
+ +

Omitting fmt causes a warning in category ‘missing’. +See Warnings, for information about the enablement and suppression of +warnings. Specifying an unrecognized format is an error. +

+

Zero values are interpolated as ‘0’ in non-Arabic formats. +Negative quantities are prefixed with ‘-’ irrespective of format. +In Arabic formats, the sign supplements the field width. If reg +doesn’t exist, it is created with a zero value. +

+
+
.nr a 10
+.af a 0           \" the default format
+\na,
+.af a I
+\na,
+.af a 321
+.nr a (-\na)
+\na,
+.af a a
+\na
+    ⇒ 10, X, -010, -j
+
+ + + + + +

The representable extrema in the ‘i’ and ‘I’ formats +correspond to Arabic ±39,999. GNU troff uses ‘w’ and +‘z’ to represent 5,000 and 10,000 in Roman numerals, respectively, +following the convention of AT&T troff—currently, the +correct glyphs for Roman numerals five thousand (U+2181) and ten +thousand (U+2182) are not used. +

+ + +

Assigning the format of a read-only register is an error. Instead, copy +the read-only register’s value to, and assign the format of, a writable +register. +

+ +
+
Escape sequence: \gr
+
+
Escape sequence: \g(rg
+
Escape sequence: \g[reg]
+
+ +

Interpolate the format of the register reg (one-character +name r, two-character name rg). Zeroes represent +Arabic formats. If reg is not defined, reg is not created +and nothing is interpolated. \g is interpreted even in copy mode +(see Copy Mode). +

+ + + +

GNU troff interprets only Arabic numerals. The Roman numeral or +alphabetic formats cannot be used as operands to arithmetic operators in +expressions (see Numeric Expressions). For instance, it may be +desirable to test the page number independently of its format. +

+
+
.af % i \" front matter
+.de header-trap
+.  \" To test the page number, we need it in Arabic.
+.  ds saved-page-number-format \\g%\"
+.  af % 0
+.  nr page-number-in-decimal \\n%
+.  af % \\*[saved-page-number-format]
+.  ie \\n[page-number-in-decimal]=1 .do-first-page-stuff
+.  el \{\
+.    ie o .do-odd-numbered-page-stuff
+.    el   .do-even-numbered-page-stuff
+.  \}
+.  rm saved-page-number-format
+..
+.wh 0 header-trap
+
+ + +
+
+
+

+Next: Built-in Registers, Previous: Auto-increment, Up: Registers   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Auto_002dincrement.html b/doc/groff.html.node/Auto_002dincrement.html new file mode 100644 index 0000000..2680f67 --- /dev/null +++ b/doc/groff.html.node/Auto_002dincrement.html @@ -0,0 +1,124 @@ + + + + + + +Auto-increment (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Registers   [Contents][Index]

+
+
+

5.8.3 Auto-increment

+ + + + +

Registers can also be incremented or decremented by a configured amount +at the time they are interpolated. The value of the increment is +specified with a third argument to the nr request, and a special +interpolation syntax is used to alter and then retrieve the register’s +value. Together, these features are called +auto-increment.51 +

+
+
Request: .nr ident value incr
+
+ +

Set register ident to value and its auto-incrementation +amount to to incr. The \R escape sequence doesn’t support +an incr argument. +

+ +

Auto-incrementation is not completely automatic; the \n +escape sequence in its basic form never alters the value of a register. +To apply auto-incrementation to a register, interpolate it with +‘\n±’. +

+
+
Escape sequence: \n+i
+
+
Escape sequence: \n-i
+
Escape sequence: \n+(id
+
Escape sequence: \n-(id
+
Escape sequence: \n+[ident]
+
Escape sequence: \n-[ident]
+

Increment or decrement ident (one-character +name i, two-character name id) by the register’s +auto-incrementation value and then interpolate the new register value. +If ident has no auto-incrementation value, interpolate as with +\n. +

+ +
+
.nr a 0 1
+.nr xx 0 5
+.nr foo 0 -2
+\n+a, \n+a, \n+a, \n+a, \n+a
+.br
+\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
+.br
+\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
+    ⇒ 1, 2, 3, 4, 5
+    ⇒ -5, -10, -15, -20, -25
+    ⇒ -2, -4, -6, -8, -10
+
+ + + +

To change the increment value without changing the value of a register, +assign the register’s value to itself by interpolating it, and specify +the desired increment normally. Apply an increment of ‘0’ to +disable auto-incrementation of the register. +

+ +
+
+
+

+Next: Assigning Register Formats, Previous: Interpolating Registers, Up: Registers   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Background.html b/doc/groff.html.node/Background.html new file mode 100644 index 0000000..1ce4224 --- /dev/null +++ b/doc/groff.html.node/Background.html @@ -0,0 +1,96 @@ + + + + + + +Background (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+
+

1.1 Background

+ + +

M. Douglas McIlroy, formerly of AT&T Bell Laboratories and present at +the creation of the Unix operating system, offers an authoritative +historical summary. +

+
+

The prime reason for Unix was the desire of Ken [Thompson], Dennis +[Ritchie], and Joe Ossanna to have a pleasant environment for software +development. The fig leaf that got the nod from … +management was that an early use would be to develop a “stand-alone” +word-processing system for use in typing pools and secretarial offices. +Perhaps they had in mind “dedicated”, as distinct from +“stand-alone”; that’s what eventuated in various cases, most notably +in the legal/patent department and in the AT&T CEO’s office. +

+

Both those systems were targets of opportunity, not foreseen from the +start. When Unix was up and running on the PDP-11, Joe got wind of +the legal department having installed a commercial word processor. +He went to pitch Unix as an alternative and clinched a trial by +promising to make roff able to number lines by tomorrow in order +to fulfill a patent-office requirement that the commercial system did +not support. +

+

Modems were installed so legal-department secretaries could try the +Research machine. They liked it and Joe’s superb customer service. +Soon the legal department got a system of their own. Joe went on to +create nroff and troff. Document preparation became a +widespread use of Unix, but no stand-alone word-processing system was +ever undertaken. +

+ +

A history relating groff to its predecessors roff, +nroff, and troff is available in the roff(7) +man page. +

+ + +
+
+
+

+Next: What Is groff?, Previous: Introduction, Up: Introduction   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Basics.html b/doc/groff.html.node/Basics.html new file mode 100644 index 0000000..95db07b --- /dev/null +++ b/doc/groff.html.node/Basics.html @@ -0,0 +1,232 @@ + + + + + + +Basics (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Tutorial for Macro Users   [Contents][Index]

+
+
+

3.1 Basics

+ + + +

Let us first survey some basic concepts necessary to use a macro package +fruitfully.6 +References are made throughout to more detailed information. +

+

GNU troff reads an input file prepared by the user and outputs a +formatted document suitable for publication or framing. The input +consists of text, or words to be printed, and embedded commands +(requests and escape sequences), which tell GNU +troff how to format the output. See Formatter Instructions. +

+

The word argument is used in this chapter to mean a word or +number that appears on the same line as a request, and which modifies +the meaning of that request. For example, the request +

+
+
.sp
+
+ +

spaces one line, but +

+
+
.sp 4
+
+ +

spaces four lines. The number 4 is an argument to the sp +request, which says to space four lines instead of one. Arguments are +separated from the request and from each other by spaces (not +tabs). See Invoking Requests. +

+

The primary function of GNU troff is to collect words from input +lines, fill output lines with those words, adjust the line to the +right-hand margin by widening spaces, and output the result. For +example, the input: +

+
+
Now is the time
+for all good men
+to come to the aid
+of their party.
+Four score and seven
+years ago, etc.
+
+ +

is read, packed onto output lines, and justified to produce: +

+
+
  ⇒ Now is the time for all good men to come to the aid of
+  ⇒ their party.  Four score and seven years ago, etc.
+
+ +

Sometimes a new output line should be started even though the current +line is not yet full—for example, at the end of a paragraph. To do +this it is possible to force a break, starting a new output +line. Some requests cause a break automatically, as do (normally) blank +input lines and input lines beginning with a space or tab. +

+

Not all input lines are text lines—words to be formatted. +Some are control lines that tell a macro package (or GNU +troff directly) how to format the text. Control lines start with +a dot (‘.’) or an apostrophe (‘'’) as the first character, and +can be followed by a macro call. +

+

The formatter also does more complex things, such as automatically +numbering pages, skipping over page boundaries, putting footnotes in the +correct place, and so forth. +

+

Here are a few hints for preparing text for input to GNU troff. +

+
    +
  • First, keep the input lines short. Short input lines are easier to +edit, and GNU troff packs words onto longer lines anyhow. + +
  • In keeping with this, it is helpful to begin a new line after every +comma or phrase, since common corrections are to add or delete sentences +or phrases. + +
  • End each sentence with two spaces—or better, start each sentence on a +new line. GNU troff recognizes characters that usually end a +sentence, and inserts inter-sentence space accordingly. + +
  • Do not hyphenate words at the end of lines—GNU troff is smart +enough to hyphenate words as needed, but is not smart enough to take +hyphens out and join a word back together. Also, words such as +“mother-in-law” should not be broken over a line, since then a space +can occur where not wanted, such as “mother- in-law”. +
+ +

We offer further advice in Input Conventions. +

+ + +

GNU troff permits alteration of the distance between lines of +text. This is termed vertical spacing and is expressed in the +same units as the type size—the point. The default is 10-point type +on 12-point spacing. To get double-spaced text you would set +the vertical spacing to 24 points. Some, but not all, macro packages +expose a macro or register to configure the vertical spacing. +

+

A number of requests allow you to change the way the output is arranged +on the page, sometimes called the layout of the output page. +Most macro packages don’t supply macros for performing these (at least +not without performing other actions besides), as they are such basic +operations. The macro packages for writing man pages, man and +mdoc, don’t encourage explicit use of these requests at all. +

+ +

The request ‘.sp N’ leaves N lines of blank +space. N can be omitted (skipping a single line) or can +be of the form Ni (for N inches) or Nc (for +N centimeters). For example, the input: +

+
+
.sp 1.5i
+My thoughts on the subject
+.sp
+
+ +

leaves one and a half inches of space, followed by the line “My +thoughts on the subject”, followed by a single blank line (more +measurement units are available; see Measurements). +

+

If you seek precision in spacing, be advised when using a macro package +that it might not honor sp requests as you expect; it can use a +formatter feature called no-space mode to prevent excess space +from accumulating. Macro packages typically offer registers to control +spacing between paragraphs, before section headings, and around displays +(discussed below); use these facilities preferentially. +See Manipulating Spacing. +

+ + +

Text lines can be centered by using the ce request. The line +after ce is centered (horizontally) on the page. To center more +than one line, use ‘.ce N’ (where N is the number +of lines to center), followed by the N lines. To center many +lines without counting them, type: +

+
+
.ce 1000
+lines to center
+.ce 0
+
+ +

The ‘.ce 0’ request tells GNU troff to center zero more +lines, in other words, stop centering. +

+ + + + +

GNU troff also offers the rj request for right-aligning +text. It works analogously to ce and is convenient for setting +epigraphs. +

+ + +

The bp request starts a new page; this necessarily implies an +ordinary (line) break. +

+ + +

All of these requests cause a break; that is, they always start a new +line. To start a new line without performing any other action, use +br. If you invoke them with the apostrophe ‘'’, the +no-break control character, the (initial) break they normally +perform is suppressed. ‘'br’ does nothing. +

+ + +
+
+
+

+Next: Common Features, Previous: Tutorial for Macro Users, Up: Tutorial for Macro Users   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Blank-Line-Traps.html b/doc/groff.html.node/Blank-Line-Traps.html new file mode 100644 index 0000000..b7b0ae4 --- /dev/null +++ b/doc/groff.html.node/Blank-Line-Traps.html @@ -0,0 +1,71 @@ + + + + + + +Blank Line Traps (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Traps   [Contents][Index]

+
+
+

5.28.3 Blank Line Traps

+ + + +
+
Request: .blm [name]
+
+ +

Set a blank line trap, calling the macro name when GNU +troff encounters a blank line in an input file, instead of the +usual behavior (see Breaking). A line consisting only of spaces is +also treated as blank and subject to this trap. If no argument is +supplied, the default blank line behavior is (re-)established. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Breaking.html b/doc/groff.html.node/Breaking.html new file mode 100644 index 0000000..a883e07 --- /dev/null +++ b/doc/groff.html.node/Breaking.html @@ -0,0 +1,119 @@ + + + + + + +Breaking (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+
+

5.1.4 Breaking

+ + + + + +

Once an output line is full, the next word (or remainder of a hyphenated +one) is placed on a different output line; this is called a break. +In this manual and in roff discussions generally, a “break” if +not further qualified always refers to the termination of an output +line. When the formatter is filling text, it introduces breaks +automatically to keep output lines from exceeding the configured line +length. After an automatic break, GNU troff adjusts the line if +applicable (see below), and then resumes collecting and filling text on +the next output line. +

+

Sometimes, a line cannot be broken automatically. This usually does +not happen with natural language text unless the output line length has +been manipulated to be extremely short, but it can with specialized +text like program source code. We can use perl at the shell +prompt to contrive an example of failure to break the line. We also +employ the -z option to suppress normal output. +

+
+
$ perl -e 'print "#" x 80, "\n";' | nroff -z
+    error→ warning: cannot break line
+
+ +

The remedy for these cases is to tell GNU troff where the line +may be broken without hyphens. This is done with the non-printing break +point escape sequence ‘\:’; see Manipulating Hyphenation. +

+ + + + +

What if the document author wants to stop filling lines temporarily, for +instance to start a new paragraph? There are several solutions. A +blank input line not only causes a break, but by default it also outputs +a one-line vertical space (effectively a blank output line). This +behavior can be modified; see Blank Line Traps. Macro packages +may discourage or disable the blank line method of paragraphing in favor +of their own macros. +

+ + + + +

A line that begins with one or more spaces causes a break. The spaces +are output at the beginning of the next line without being +adjusted (see below); however, this behavior can be modified +(see Leading Space Traps). Again, macro packages may provide other +methods of producing indented paragraphs. Trailing spaces on text lines +are discarded.23 +

+

What if the file ends before enough words have been collected to fill an +output line? Or the output line is exactly full but not yet broken, and +there is no more input? GNU troff interprets the end of input as +a break. Certain requests also cause breaks, implicitly or explicitly. +This is discussed in Manipulating Filling and Adjustment. +

+ +
+
+
+

+Next: Adjustment, Previous: Hyphenation, Up: Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Built_002din-Registers.html b/doc/groff.html.node/Built_002din-Registers.html new file mode 100644 index 0000000..a1b0530 --- /dev/null +++ b/doc/groff.html.node/Built_002din-Registers.html @@ -0,0 +1,253 @@ + + + + + + +Built-in Registers (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Registers   [Contents][Index]

+
+
+

5.8.5 Built-in Registers

+ + + +

Predefined registers whose identifiers start with a dot are read-only. +Many are Boolean-valued, interpolating a true or false value testable +with the if, ie, or while requests. Some read-only +registers are string-valued, meaning that they interpolate text. +

+ + + +

Caution: Built-in registers are subject to removal like +others; once removed, they can be recreated only as normal writable +registers and will not reflect formatter state. +

+

A register name (without the dot) is often associated with a request of +the same name. A complete listing of all built-in registers can be +found in Register Index. +

+

We present here a few built-in registers that are not described +elsewhere in this manual; they have to do with invariant properties of +GNU troff, or obtain information about the formatter’s +command-line options, processing progress, or the operating environment. +

+
+
\n[.A]
+
+ +

Approximate output is being formatted (Boolean-valued); see +groff -a option (Options). +

+
+
\n[.c]
+
+
+
\n[c.]
+
+ +

Input line number. ‘c.’ is a writable synonym, +affecting subsequent interpolations of both ‘.c’ and ‘c.’. +

+
+
\n[.F]
+
+ +

Name of input file (string-valued). +

+
+
\n[.g]
+
+ +

Always true in GNU troff (Boolean-valued). Documents can use +this to ask the formatter if it claims groff compatibility. +

+
+
\n[.P]
+

Output page selection status (Boolean-valued); see groff +-o option (Options). +

+
+
\n[.R]
+
+ +

Count of available unused registers; always 10,000 in GNU +troff.52 +

+
+
\n[.T]
+

Indicator of output device selection (Boolean-valued); see +groff -T option (Options). +

+
+
\n[.U]
+
+ + + +

Unsafe mode enablement status (Boolean-valued); see groff +-U option (Options). +

+
+
\n[.x]
+
+ +

Major version number of the running GNU troff formatter. For +example, if the version number is 1.23.0, then .x +contains ‘1’. +

+
+
\n[.y]
+
+ +

Minor version number of the running GNU troff formatter. For +example, if the version number is 1.23.0, then .y +contains ‘23’. +

+
+
\n[.Y]
+
+

Revision number of the running GNU troff formatter. For example, +if the version number is 1.23.0, then .Y contains ‘0’. +

+
+
\n[$$]
+
+ + + +

Process identifier (PID) of the GNU troff program in its +operating environment. +

+
+ +

Date- and time-related registers are set per the local time as +determined by localtime(3) when the formatter launches. This +initialization can be overridden by SOURCE_DATE_EPOCH and +TZ; see Environment. +

+
+
\n[seconds]
+
+ + +

Count of seconds elapsed in the minute (0–60).

+
+
\n[minutes]
+
+ + +

Count of minutes elapsed in the hour (0–59). +

+
+
\n[hours]
+
+ + +

Count of hours elapsed since midnight (0–23). +

+
+
\n[dw]
+
+ +

Day of the week (1–7; 1 is Sunday). +

+
+
\n[dy]
+
+ +

Day of the month (1–31). +

+
+
\n[mo]
+
+ +

Month of the year (1–12). +

+
+
\n[year]
+
+ +

Gregorian year. +

+ + +
+
\n[yr]
+

Gregorian year minus 1900. This register is incorrectly documented +in the AT&T troff manual as storing the last two digits +of the current year. That claim stopped being true in 2000. Old +troff input that looks like: +

+
+
'\" The year number is a surprise after 1999.
+This document was formatted in 19\n(yr.
+
+ +

can be corrected to: +

+
+
This document was formatted in \n[year].
+
+ +

or, for portability across many roff programs, to the following. +

+
+
.nr y4 1900+\n(yr
+This document was formatted in \n(y4.
+
+
+
+ + + +
+
+
+

+Previous: Assigning Register Formats, Up: Registers   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Calling-Macros.html b/doc/groff.html.node/Calling-Macros.html new file mode 100644 index 0000000..1e8d81a --- /dev/null +++ b/doc/groff.html.node/Calling-Macros.html @@ -0,0 +1,164 @@ + + + + + + +Calling Macros (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Formatter Instructions   [Contents][Index]

+
+
+

5.6.3 Calling Macros

+ + + + +

If a macro of the desired name does not exist when called, it is +created, assigned an empty definition, and a warning in category +‘mac’ is emitted. Calling an undefined macro does end a +macro definition naming it as its end macro (see Writing Macros). +

+ +

To embed spaces within a macro argument, enclose the argument in +neutral double quotes ". Horizontal motion escape sequences are +sometimes a better choice for arguments to be formatted as text. +

+

Consider calls to a hypothetical section heading macro ‘uh’. +

+
+
.uh The Mouse Problem
+.uh "The Mouse Problem"
+.uh The\~Mouse\~Problem
+.uh The\ Mouse\ Problem
+
+ + + +

The first line calls uh with three arguments: ‘The’, +‘Mouse’, and ‘Problem’. The remainder call the uh +macro with one argument, ‘The Mouse Problem’. The last solution, +using escaped spaces, can be found in documents prepared for +AT&T troff. It can cause surprise when text is +adjusted, because \SP inserts a fixed-width, +non-breaking space. GNU troff’s \~ escape sequence +inserts an adjustable, non-breaking space.44 +

+ + + + +

The foregoing raises the question of how to embed neutral double quotes +or backslashes in macro arguments when those characters are +desired as literals. In GNU troff, the special character escape +sequence \[rs] produces a backslash and \[dq] a neutral +double quote. +

+

In GNU troff’s AT&T compatibility mode, these +characters remain available as \(rs and \(dq, +respectively. AT&T troff did not consistently define +these special characters, +but its descendants can be made to support them. See Device and Font Description Files. +

+

If even that is not feasible, options remain. To obtain a literal +escape character in a macro argument, you can simply type it if you +change or disable the escape character first. See Using Escape Sequences. Otherwise, you must escape the escape character repeatedly +to a context-dependent extent. See Copy Mode. +

+

For the (neutral) double quote, you have recourse to an obscure +syntactical feature of AT&T troff. Because a double +quote can begin a macro argument, the formatter keeps track of whether +the current argument was started thus, and doesn’t require a space after +the double quote that ends it.45 In +the argument list to a macro, a double quote that isn’t preceded +by a space doesn’t start a macro argument. If not preceded by a +double quote that began an argument, this double quote becomes part of +the argument. Furthermore, within a quoted argument, a pair of adjacent +double quotes becomes a literal double quote. +

+
+
.de eq
+.  tm arg1:\\$1 arg2:\\$2 arg3:\\$3
+.  tm arg4:\\$4 arg5:\\$5 arg6:\\$6
+.. \" 4 backslashes on the next line
+.eq a" "b c" "de"f\\\\g" h""i "j""k"
+    error→ arg1:a" arg2:b c arg3:de
+    error→ arg4:f\g" arg5:h""i arg6:j"k
+
+ +

Apart from the complexity of the rules, this traditional solution has +the disadvantage that double quotes don’t survive repeated argument +expansion in AT&T troff or GNU troff’s +compatibility mode. This can frustrate efforts to pass such arguments +intact through multiple macro calls. +

+
+
.cp 1
+.de eq
+.  tm arg1:\\$1 arg2:\\$2 arg3:\\$3
+.  tm arg4:\\$4 arg5:\\$5 arg6:\\$6
+..
+.de xe
+.  eq \\$1 \\$2 \\$3 \\$4 \\$5 \\$6
+.. \" 8 backslashes on the next line
+.xe a" "b c" "de"f\\\\\\\\g" h""i "j""k"
+    error→ arg1:a" arg2:b arg3:c
+    error→ arg4:de arg5:f\g" arg6:h""i
+
+ + + + + +

Outside of compatibility mode, GNU troff doesn’t exhibit this +problem because it tracks the nesting depth of interpolations. +See Implementation Differences. +

+ +
+
+
+

+Next: Using Escape Sequences, Previous: Invoking Requests, Up: Formatter Instructions   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Changing-the-Type-Size.html b/doc/groff.html.node/Changing-the-Type-Size.html new file mode 100644 index 0000000..da02d8b --- /dev/null +++ b/doc/groff.html.node/Changing-the-Type-Size.html @@ -0,0 +1,159 @@ + + + + + + +Changing the Type Size (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Manipulating Type Size and Vertical Spacing   [Contents][Index]

+
+
+

5.20.1 Changing the Type Size

+ +
+
Request: .ps [size]
+
+
Request: .ps +size
+
Request: .ps -size
+
Escape sequence: \ssize
+
+
Register: \n[.s]
+
+ + + +

Use the ps request or the \s escape sequence to change +(increase, decrease) the type size (in scaled points). Specify +size as either an absolute type size, or as a relative change from +the current size. ps with no argument restores the previous +size. The ps request’s default scaling unit is ‘z’. The +requested size is rounded to the nearest valid size (with ties rounding +down) within the limits supported by the device. If the requested size +is non-positive, it is treated as 1u. +

+ + + +

Type size alteration is incorrectly documented in the AT&T +troff manual, which claims “if [the requested size] is invalid, +the next larger valid size will result, with a maximum of +36”.84 +

+ + +

The read-only string-valued register .s interpolates the type +size in points as a decimal fraction; it is associated with the +environment (see Environments). To obtain the type size in scaled +points, interpolate the .ps register instead (see Using Fractional Type Sizes). +

+

The \s escape sequence supports a variety of syntax forms. +

+
+
\sn
+

Set the type size to n points. n must be a single +digit. If n is 0, restore the previous size. +

+
+
\s+n
+
\s-n
+

Increase or decrease the type size by n points. +n must be exactly one digit. +

+
+
\s(nn
+

Set the type size to nn points. nn must be exactly two +digits. +

+
+
\s+(nn
+
\s-(nn
+
\s(+nn
+
\s(-nn
+

Alter the type size in points by the two-digit value nn. +

+
+ +

See Using Fractional Type Sizes, for further syntactical forms of the +\s escape sequence that additionally accept decimal fractions. +

+
+
snap, snap,
+.ps +2
+grin, grin,
+.ps +2
+wink, wink, \s+2nudge, nudge,\s+8 say no more!
+.ps 10
+
+
+ +

The \s escape sequence affects the environment immediately and +doesn’t produce an input token. Consequently, it can be used in +requests like mc, which expects a single character as an +argument, to change the type size on the fly. +

+
+
.mc \s[20]x\s[0]
+
+ +
+
Request: .sizes s1 s2 … sn [0]
+
+

The DESC file specifies which type sizes are allowed by the +output device; see DESC File Format. Use the sizes request +to change this set of permissible sizes. Arguments are in scaled +points; see Using Fractional Type Sizes. Each can be a single +type size (such as ‘12000’), or a range of sizes (such as +‘4000-72000’). You can optionally end the list with a ‘0’. +

+ +
+
+
+

+Next: Changing the Vertical Spacing, Previous: Manipulating Type Size and Vertical Spacing, Up: Manipulating Type Size and Vertical Spacing   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Changing-the-Vertical-Spacing.html b/doc/groff.html.node/Changing-the-Vertical-Spacing.html new file mode 100644 index 0000000..cca1634 --- /dev/null +++ b/doc/groff.html.node/Changing-the-Vertical-Spacing.html @@ -0,0 +1,146 @@ + + + + + + +Changing the Vertical Spacing (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Manipulating Type Size and Vertical Spacing   [Contents][Index]

+
+
+

5.20.2 Changing the Vertical Spacing

+ +
+
Request: .vs [space]
+
+
Request: .vs +space
+
Request: .vs -space
+
Register: \n[.v]
+
+ + + +

Set the vertical spacing to, or alter it by, space. The default +scaling unit is ‘p’. If vs is called without an argument, +the vertical spacing is reset to the previous value before the last call +to vs. + +GNU troff emits a warning in category ‘range’ if space +is negative; the vertical spacing is then set to the smallest possible +positive value, the vertical motion quantum (as found in the .V +register). +

+

‘.vs 0’ isn’t saved in a diversion since it doesn’t result in +a vertical motion. You must explicitly issue this request before +interpolating the diversion. +

+

The read-only register .v contains the vertical spacing; it is +associated with the environment (see Environments). +

+ + +

When a break occurs, GNU troff performs the following procedure. +

+
    +
  • + +Move the drawing position vertically by the extra pre-vertical line +space, the minimum of all negative \x escape sequence arguments +in the pending output line. + +
  • Move the drawing position vertically by the vertical line spacing. + +
  • Write out the pending output line. + +
  • + +Move the drawing position vertically by the extra post-vertical line +space, the maximum of all positive \x escape sequence arguments +in the line that has just been output. + +
  • + +Move the drawing position vertically by the post-vertical line +spacing (see below). +
+ + +

Prefer vs or pvs over ls to produce double-spaced +documents. vs and pvs have finer granularity than +ls; moreover, some preprocessors assume single spacing. +See Manipulating Spacing, regarding the \x escape sequence and +the ls request. +

+
+
Request: .pvs [space]
+
+
Request: .pvs +space
+
Request: .pvs -space
+
Register: \n[.pvs]
+
+ + + +

Set the post-vertical spacing to, or alter it by, space. The +default scaling unit is ‘p’. If pvs is called without an +argument, the post-vertical spacing is reset to the previous value +before the last call to pvs. GNU troff emits a warning in +category ‘range’ if space is negative; the post-vertical +spacing is then set to zero. +

+

The read-only register .pvs contains the post-vertical spacing; +it is associated with the environment (see Environments). +

+ + +
+
+
+

+Next: Using Fractional Type Sizes, Previous: Changing the Type Size, Up: Manipulating Type Size and Vertical Spacing   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Character-Classes.html b/doc/groff.html.node/Character-Classes.html new file mode 100644 index 0000000..6e315dd --- /dev/null +++ b/doc/groff.html.node/Character-Classes.html @@ -0,0 +1,140 @@ + + + + + + +Character Classes (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+
+

5.19.5 Character Classes

+ + + +

Classes are particularly useful for East Asian languages such as +Chinese, Japanese, and Korean, where the number of needed characters is +much larger than in European languages, and where large sets of +characters share the same properties. +

+
+
Request: .class name c1 c2 …
+
+ + + +

Define a character class (or simply “class”) name comprising +the characters c1, c2, and so on. +

+

A class thus defined can then be referred to in lieu of listing all the +characters within it. Currently, only the cflags request can +handle references to character classes. +

+

In the request’s simplest form, each cn is a character (or special +character). +

+
+
.class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq]
+
+ +

Since class and glyph names share the same name space, it is recommended +to start and end the class name with [ and ], +respectively, to avoid collisions with existing character names defined +by GNU troff or the user (with char and related requests). +This practice applies the presence of ] in the class name to +prevent the use of the special character escape form +\[…], thus you must use the \C escape to access +a class with such a name. +

+ + +

You can also use a character range notation consisting of a +start character followed by ‘-’ and then an end character. +Internally, GNU troff converts these two symbol names to +Unicode code points (according to the groff glyph list [GGL]), +which then give the start and end value of the range. If that fails, +the class definition is skipped. +

+

Furthermore, classes can be nested. +

+
+
.class [prepunct] , : ; > }
+.class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
+
+ +

The class ‘[prepunctx]’ thus contains the contents of the class +[prepunct] as defined above (the set ‘, : ; > }’), and +characters in the range between U+2013 and U+2016. +

+

If you want to include ‘-’ in a class, it must be the first +character value in the argument list, otherwise it gets misinterpreted +as part of the range syntax. +

+

It is not possible to use class names as end points of range +definitions. +

+

A typical use of the class request is to control line-breaking +and hyphenation rules as defined by the cflags request. For +example, to inhibit line breaks before the characters belonging to the +prepunctx class defined in the previous example, you can write +the following. +

+
+
.cflags 2 \C'[prepunctx]'
+
+ +

See the cflags request in Using Symbols, for more details. +

+ + +
+
+
+

+Next: Special Fonts, Previous: Using Symbols, Up: Using Fonts   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Character-Translations.html b/doc/groff.html.node/Character-Translations.html new file mode 100644 index 0000000..a867be8 --- /dev/null +++ b/doc/groff.html.node/Character-Translations.html @@ -0,0 +1,200 @@ + + + + + + +Character Translations (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.13 Character Translations

+ + + +

A translation is a mapping of an input character to an output +glyph. The mapping occurs at output time, i.e., the input character +gets assigned the metric information of the mapped output character +right before input tokens are converted to nodes (see gtroff Internals, for more on this process). +

+
+
Request: .tr abcd…
+
+
Request: .trin abcd…
+
+

Translate character a to glyph b, character c to +glyph d, and so on. If there is an odd number of characters +in the argument, the last one is translated to a fixed-width space (the +same one obtained by the \SP escape sequence). +

+

The trin request is identical to tr, but when you unformat +a diversion with asciify it ignores the translation. +See Diversions, for details about the asciify request. +

+

Some notes: +

+
    +
  • + + + + + + + + + + + + +Special characters (\(xx, \[xxx], +\C'xxx', \', \`, \-, \_), +glyphs defined with the char request, and numbered glyphs +(\N'xxx') can be translated also. + +
  • +The \e escape can be translated also. + +
  • + +Characters can be mapped onto the \% and \~ escape +sequences (but \% and \~ can’t be mapped onto another +glyph). + +
  • + + + + + + + + + +The following characters can’t be translated: space (with one exception, +see below), backspace, newline, leader (and \a), tab (and +\t). + +
  • +Translations are not considered for finding the soft hyphen character +set with the shc request. + +
  • +The pair ‘c\&’ (an arbitrary character c followed +by the dummy character) maps this character to “nothing”. + +
    +
    .tr a\&
+foo bar
+    ⇒ foo br
+
    + +

    Even the space character can be mapped to the dummy character. +

    +
    +
    .tr aa \&
+foo bar
+    ⇒ foobar
+
    + +

    As shown in the example, the space character can’t be the first +character/glyph pair as an argument of tr. Additionally, it is +not possible to map the space character to any other glyph; requests +like ‘.tr aa x’ undo ‘.tr aa \&’ instead. +

    +

    If justification is active, lines are justified in spite of the ‘empty’ +space character (but there is no minimal distance, i.e., the space +character, between words). +

    +
  • After an output glyph has been constructed (this happens at the moment +immediately before the glyph is appended to an output glyph list, either +by direct output, in a macro, diversion, or string), it is no longer +affected by tr. + +
  • Translating character to glyphs where one of them or both are undefined +is possible also; tr does not check whether the elements of its +argument exist. + +

    See gtroff Internals. +

    +
  • Without an argument, the tr request is ignored. +
+
+ +
+
Request: .trnt abcd…
+
+ +

trnt is the same as the tr request except that the +translations do not apply to text that is transparently throughput into +a diversion with \!. See Diversions. +

+

For example, +

+
+
.tr ab
+.di x
+\!.tm a
+.di
+.x
+
+ +

prints ‘b’ to the standard error stream; if trnt is used +instead of tr it prints ‘a’. +

+ + + +
+
+
+

+Next: troff and nroff Modes, Previous: Tabs and Fields, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Colors.html b/doc/groff.html.node/Colors.html new file mode 100644 index 0000000..8c23dcb --- /dev/null +++ b/doc/groff.html.node/Colors.html @@ -0,0 +1,208 @@ + + + + + + +Colors (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.21 Colors

+ + + + + + +

GNU troff supports color output with a variety of color spaces +and up to 16 bits per channel. Some devices, particularly terminals, +may be more limited. When color support is enabled, two colors are +current at any given time: the stroke color, with which glyphs, +rules (lines), and geometric objects like circles and polygons are +drawn, and the fill color, which can be used to paint the interior +of a closed geometric figure. +

+
+
Request: .color [n]
+
+
Register: \n[.color]
+
+

If n is missing or non-zero, enable the output of color-related +device-independent output commands (this is the default); otherwise, +disable them. This request sets a global flag; it does not produce an +input token (see gtroff Internals). +

+

The read-only register .color is 1 if colors are enabled, +0 otherwise. +

+

Color can also be disabled with the -c command-line option. +

+ +
+
Request: .defcolor ident scheme color-component …
+
+

Define a color named ident. scheme selects a color space +and determines the quantity of required color-components; it must +be one of ‘rgb’ (three components), ‘cmy’ (three), ‘cmyk’ +(four), or ‘gray’ (one). ‘grey’ is accepted as a synonym of +‘gray’. The color components can be encoded as a single +hexadecimal value starting with ‘#’ or ‘##’. The former +indicates that each component is in the range 0–255 (0–FF), the latter +the range 0–65,535 (0–FFFF). +

+
+
.defcolor half gray #7f
+.defcolor pink rgb #FFC0CB
+.defcolor magenta rgb  ##ffff0000ffff
+
+ + + + +

Alternatively, each color component can be specified as a decimal +fraction in the range 0–1, interpreted using a default scaling +unit of f, which multiplies its value by 65,536 (but +clamps it at 65,535). +

+
+
.defcolor gray50 rgb 0.5 0.5 0.5
+.defcolor darkgreen rgb 0.1f 0.5f 0.2f
+
+
+ + + +

Each output device has a color named ‘default’, which cannot be +redefined. A device’s default stroke and fill colors are not +necessarily the same. For the dvi, html, pdf, +ps, and xhtml output devices, GNU troff +automatically loads a macro file defining many color names at startup. +By the same mechanism, the devices supported by grotty recognize +the eight standard ISO 6429/EMCA-48 color names.86 +

+
+
Request: .gcolor [color]
+
+
Escape sequence: \mc
+
+
Escape sequence: \m(co
+
Escape sequence: \m[color]
+
Register: \n[.m]
+
+

Set the stroke color to color. +

+
+
.gcolor red
+The next words
+.gcolor
+\m[red]are in red\m[]
+and these words are in the previous color.
+
+ +

The escape sequence \m[] restores the previous stroke color, as +does a gcolor request without an argument. +

+ + + +

The name of the current stroke color is available in the read-only +string-valued register ‘.m’; it is associated with the environment +(see Environments). It interpolates nothing when the stroke color +is the default. +

+

\m doesn’t produce an input token in GNU troff +(see gtroff Internals). It therefore can be used in requests like +mc (which expects a single character as an argument) to change +the color on the fly: +

+
+
.mc \m[red]x\m[]
+
+
+ +
+
Request: .fcolor [color]
+
+
Escape sequence: \Mc
+
+
Escape sequence: \M(co
+
Escape sequence: \M[color]
+
Register: \n[.M]
+
+

Set the fill color for objects drawn with \D'…' escape +sequences. The escape sequence \M[] restores the previous fill +color, as does an fcolor request without an argument. +

+ + + + + + +

The name of the current fill color is available in the read-only +string-valued register ‘.M’; it is associated with the environment +(see Environments). It interpolates nothing when the fill color +is the default. \M doesn’t produce an input token in GNU +troff. +

+

Create an ellipse with a red interior as follows. +

+
+
\M[red]\h'0.5i'\D'E 2i 1i'\M[]
+
+
+ + + +
+
+
+

+Next: Strings, Previous: Manipulating Type Size and Vertical Spacing, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Columnation.html b/doc/groff.html.node/Columnation.html new file mode 100644 index 0000000..7ac057f --- /dev/null +++ b/doc/groff.html.node/Columnation.html @@ -0,0 +1,53 @@ + + + + + + +Columnation (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.10 Columnation

+ +

Macro packages apart from man and mdoc for man page +formatting offer a facility for setting multiple columns on the page. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Command-Reference.html b/doc/groff.html.node/Command-Reference.html new file mode 100644 index 0000000..bd5cd9e --- /dev/null +++ b/doc/groff.html.node/Command-Reference.html @@ -0,0 +1,60 @@ + + + + + + +Command Reference (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: gtroff Output   [Contents][Index]

+
+
+

6.1.2 Command Reference

+ +

This section describes all intermediate output commands, both from +AT&T troff as well as the gtroff extensions. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Comment-Command.html b/doc/groff.html.node/Comment-Command.html new file mode 100644 index 0000000..1ef8d94 --- /dev/null +++ b/doc/groff.html.node/Comment-Command.html @@ -0,0 +1,65 @@ + + + + + + +Comment Command (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Command Reference   [Contents][Index]

+
+
+

6.1.2.1 Comment Command

+ +
+
#anything‹end of line›
+

A comment. Ignore any characters from the ‘#’ character up to the +next newline character. +

+

This command is the only possibility for commenting in the intermediate +output. Each comment can be preceded by arbitrary syntactical space; +every command can be terminated by a comment. +

+
+ +
+ + + + + diff --git a/doc/groff.html.node/Comments.html b/doc/groff.html.node/Comments.html new file mode 100644 index 0000000..46b3523 --- /dev/null +++ b/doc/groff.html.node/Comments.html @@ -0,0 +1,157 @@ + + + + + + +Comments (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.7 Comments

+ + +

One of the most common forms of escape sequence is the +comment.48 +

+
+
Escape sequence: \"
+
+

Start a comment. Everything up to the next newline is ignored. +

+

This may sound simple, but it can be tricky to keep the comments from +interfering with the appearance of the output. + + +If the escape sequence is to the right of some text or a request, that +portion of the line is ignored, but spaces preceding it are processed +normally by GNU troff. This affects only the ds and +as requests and their variants. +

+ + +

One possibly irritating idiosyncrasy is that tabs should not be used to +vertically align comments in the source document. Tab characters are +not treated as separators between a request name and its first argument, +nor between arguments. +

+ + +

A comment on a line by itself is treated as a blank line, because after +eliminating the comment, that is all that remains. +

+
+
Test
+\" comment
+Test
+    ⇒ Test
+    ⇒
+    ⇒ Test
+
+ +

To avoid this, it is common to combine the empty request with the +comment escape sequence as ‘.\"’, causing the input line to be +ignored. +

+ +

Another commenting scheme sometimes seen is three consecutive single +quotes (''') at the beginning of a line. This works, but GNU +troff emits a warning diagnostic (if enabled) about an undefined +macro (namely ‘''’). +

+ +
+
Escape sequence: \#
+
+

Start a comment; everything up to and including the next newline is +ignored. This groff extension was introduced to avoid the +problems described above. +

+
+
Test
+\# comment
+Test
+    ⇒ Test Test
+
+
+ +
+
Request: .ig [end]
+
+

Ignore input until, in the current conditional block (if +any),49 the macro end is called +at the start of a control line, or the control line ‘..’ is +encountered if end is not specified. ig is parsed as if it +were a macro definition, but its contents are discarded, not +stored.50 +

+
+
hand\c
+.de TX
+fasting
+..
+.ig TX
+This is part of a large block of input that has been
+temporarily(?) commented out.
+We can restore it simply by removing the .ig request and
+the call of its end macro.
+.TX
+
+
+
    ⇒ handfasting
+
+
+ + + +
+
+
+

+Next: Registers, Previous: Formatter Instructions, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Common-Features.html b/doc/groff.html.node/Common-Features.html new file mode 100644 index 0000000..074015e --- /dev/null +++ b/doc/groff.html.node/Common-Features.html @@ -0,0 +1,89 @@ + + + + + + +Common Features (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Tutorial for Macro Users   [Contents][Index]

+
+
+

3.2 Common Features

+ + + +

GNU troff provides low-level operations for formatting a +document. Many routine operations are undertaken in nearly all +documents that require a series of such primitive operations to be +performed. These common tasks are grouped into macros, which +are then collected into a macro package. +

+

Macro packages come in two varieties: “major” or “full-service” +ones that manage page layout, and “minor” or “auxiliary” ones that +do not, instead fulfilling narrow, specific tasks. Find a list in the +groff_tmac(5) man page. Type ‘man groff_tmac’ at the +command line to view it. +

+

We survey several capabilities of full-service macro package below. +Each package employs its own macros to exercise them. For details, +consult its man page or, for ms, see ms. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/Compatibility-Mode.html b/doc/groff.html.node/Compatibility-Mode.html new file mode 100644 index 0000000..60c376b --- /dev/null +++ b/doc/groff.html.node/Compatibility-Mode.html @@ -0,0 +1,221 @@ + + + + + + +Compatibility Mode (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Implementation Differences   [Contents][Index]

+
+
+

5.38.2 Compatibility Mode

+ + + + + + + +

Long identifier names may be GNU troff’s most obvious innovation. +AT&T troff interprets ‘.dsabcd’ as defining a +string ‘ab’ with contents ‘cd’. Normally, GNU troff +interprets this as a call of a macro named dsabcd. +AT&T troff also interprets ‘\*[’ and ‘\n[’ as +an interpolation of a string or register, respectively, named ‘[’. +In GNU troff, however, the ‘[’ is normally interpreted as +delimiting a long name. In compatibility mode, GNU troff +interprets names in the traditional way; they thus can be two characters +long at most. +

+
+
Request: .cp [n]
+
+
Register: \n[.C]
+
+

If n is missing or non-zero, turn on compatibility mode; +otherwise, turn it off. +

+

The read-only register .C is 1 if compatibility mode is on, +0 otherwise. +

+

Compatibility mode can be also turned on with the -C +command-line option. +

+ +
+
Request: .do name
+
+
Register: \n[.cp]
+
+

The do request interprets the string, request, diversion, or +macro name (along with any further arguments) with compatibility +mode disabled. Compatibility mode is restored (only if it was active) +when the expansion of name is interpreted; that is, the +restored compatibility state applies to the contents of the macro, +string, or diversion name as well as data read from files or pipes +if name is any of the so, soquiet, mso, +msoquiet, or pso requests. +

+

The following example illustrates several aspects of do behavior. +

+
+
.de mac1
+FOO
+..
+.de1 mac2
+groff
+.mac1
+..
+.de mac3
+compatibility
+.mac1
+..
+.de ma
+\\$1
+..
+.cp 1
+.do mac1
+.do mac2 \" mac2, defined with .de1, calls "mac1"
+.do mac3 \" mac3 calls "ma" with argument "c1"
+.do mac3 \[ti] \" groff syntax accepted in .do arguments
+    ⇒ FOO groff FOO compatibility c1 ~
+
+ +

The read-only register .cp, meaningful only when dereferenced +from a do request, is 1 if compatibility mode was on when +the do request was encountered, and 0 if it was not. This +register is specialized and may require a statement of rationale. +

+

When writing macro packages or documents that use GNU troff +features and which may be mixed with other packages or documents that do +not—common scenarios include serial processing of man pages or use of +the so or mso requests—you may desire correct operation +regardless of compatibility mode enablement in the surrounding context. +It may occur to you to save the existing value of ‘\n(.C’ into a +register, say, ‘_C’, at the beginning of your file, turn +compatibility mode off with ‘.cp 0’, then restore it from that +register at the end with ‘.cp \n(_C’. At the same time, a modular +design of a document or macro package may lead you to multiple layers of +inclusion. You cannot use the same register name everywhere lest you +“clobber” the value from a preceding or enclosing context. The +two-character register name space of AT&T troff is +confining and mnemonically challenging; you may wish to use the more +capacious name space of GNU troff. However, attempting ‘.nr +_my_saved_C \n(.C’ will not work in compatibility mode; the register +name is too long. “This is exactly what do is for,” you think, +‘.do nr _my_saved_C \n(.C’. The foregoing will always save zero to +your register, because do turns compatibility mode off +while it interprets its argument list. +

+

To robustly save compatibility mode before switching it off, use +

+
+
.do nr _my_saved_C \n[.cp]
+.cp 0
+
+ +

at the beginning of your file, followed by +

+
+
.cp \n[_my_saved_C]
+.do rr _my_saved_C
+
+ +

at the end. As in the C language, we all have to share one big +name space, so choose a register name that is unlikely to collide with +other uses. +

+ + + + +

Normally, GNU troff preserves the interpolation depth in +delimited arguments, but not in compatibility mode. +

+
+
.ds xx '
+\w'abc\*(xxdef'
+    ⇒ 168 (normal mode on a terminal device)
+    ⇒ 72def' (compatibility mode on a terminal device)
+
+ + + + + +

Furthermore, the escape sequences \f, \H, \m, +\M, \R, \s, and \S are transparent for the +purpose of recognizing a control character at the beginning of a line +only in compatibility mode. For example, this code produces bold output +in both cases, but the text differs. +

+
+
.de xx
+Hello!
+..
+\fB.xx\fP
+    ⇒ .xx (normal mode)
+    ⇒ Hello! (compatibility mode)
+
+ + +

Normally, the syntax form \sn accepts only a single +character (a digit) for n, consistently with other forms that +originated in AT&T troff, like \*, \$, +\f, \g, \k, \n, and \z. In +compatibility mode only, a non-zero n must be in the range +4–39. Legacy documents relying upon this quirk of parsing120 should be migrated to another +\s form. +

+ +
+
+
+

+Next: Safer Mode, Previous: Other Differences, Up: Implementation Differences   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Concept-Index.html b/doc/groff.html.node/Concept-Index.html new file mode 100644 index 0000000..3adcfcb --- /dev/null +++ b/doc/groff.html.node/Concept-Index.html @@ -0,0 +1,2359 @@ + + + + + + +Concept Index (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: GNU troff   [Contents][Index]

+
+
+

Appendix J Concept Index

+ +
+
Jump to:   " +   +% +   +& +   +' +   +( +   +) +   +* +   ++ +   +- +   +. +   +/ +   +8 +   +: +   +< +   += +   +> +   +[ +   +\ +   +] +   +| +   +
+A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +J +   +K +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +W +   +Y +   +Z +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
"
", as delimiter: Delimiters
", at end of sentence: Sentences
", at end of sentence: Using Symbols
", embedding in a macro argument: Calling Macros
%
%, as delimiter: Delimiters
&
&, as delimiter: Delimiters
'
', as a comment: Comments
', as delimiter: Delimiters
', at end of sentence: Sentences
', at end of sentence: Using Symbols
(
(, as delimiter: Delimiters
)
), as delimiter: Delimiters
), at end of sentence: Sentences
), at end of sentence: Using Symbols
*
*, as delimiter: Delimiters
*, at end of sentence: Sentences
*, at end of sentence: Using Symbols
+
+, and page motion: Numeric Expressions
+, as delimiter: Delimiters
-
-, and page motion: Numeric Expressions
-, as delimiter: Delimiters
.
., as delimiter: Delimiters
.h register, difference from nl: Diversions
.ps register, in comparison with .psr: Using Fractional Type Sizes
.s register, in comparison with .sr: Using Fractional Type Sizes
.S register, Plan 9 alias for .tabs: Tabs and Fields
.t register, and diversions: Diversion Traps
.tabs register, Plan 9 alias (.S): Tabs and Fields
.V register, and vs: Changing the Vertical Spacing
/
/, as delimiter: Delimiters
8
8-bit input: Font Description File Format
:
:, as delimiter: Delimiters
<
<, as delimiter: Delimiters
=
=, as delimiter: Delimiters
>
>, as delimiter: Delimiters
[
[, macro names starting with, and refer: Identifiers
\
\!, and copy mode: Diversions
\!, and output request: Diversions
\!, and trnt: Character Translations
\!, as delimiter: Delimiters
\!, as delimiter: Delimiters
\!, in top-level diversion: Diversions
\!, incompatibilities with AT&T troff: Other Differences
\!, incompatibilities with AT&T troff: Other Differences
\$, when reading text for a macro: Copy Mode
\%, and translations: Character Translations
\%, as delimiter: Delimiters
\%, as delimiter: Delimiters
\%, following \X or \Y: Manipulating Hyphenation
\%, in \X: Postprocessor Access
\%, incompatibilities with AT&T troff: Other Differences
\&, and glyph definitions: Using Symbols
\&, and translations: Character Translations
\&, as delimiter: Delimiters
\&, at end of sentence: Sentences
\&, in \X: Postprocessor Access
\&, incompatibilities with AT&T troff: Other Differences
\', and translations: Character Translations
\', as delimiter: Delimiters
\', as delimiter: Delimiters
\', incompatibilities with AT&T troff: Other Differences
\(, and translations: Character Translations
\), as delimiter: Delimiters
\), in \X: Postprocessor Access
\*, and warnings: Warnings
\*, incompatibilities with AT&T troff: Compatibility Mode
\*, when reading text for a macro: Copy Mode
\, disabling (eo): Using Escape Sequences
\, embedding in a macro argument: Calling Macros
\,, as delimiter: Delimiters
\- glyph, and cflags: Using Symbols
\-, and translations: Character Translations
\-, as delimiter: Delimiters
\-, as delimiter: Delimiters
\-, incompatibilities with AT&T troff: Other Differences
\/, as delimiter: Delimiters
\/, as delimiter: Delimiters
\0, as delimiter: Delimiters
\:, as delimiter: Delimiters
\:, as delimiter: Delimiters
\:, in \X: Postprocessor Access
\?, and copy mode: Operators in Conditionals
\?, and copy mode: Diversions
\?, as delimiter: Delimiters
\?, in top-level diversion: Diversions
\?, incompatibilities with AT&T troff: Other Differences
\a, and copy mode: Leaders
\a, and translations: Character Translations
\a, as delimiter: Delimiters
\A, delimiters allowed by: Delimiters
\A, incompatibilities with AT&T troff: Other Differences
\b, delimiters allowed by: Delimiters
\b, limitations of: Drawing Geometric Objects
\C, and translations: Character Translations
\c, as delimiter: Delimiters
\c, as delimiter: Delimiters
\c, incompatibilities with AT&T troff: Other Differences
\c, when filling disabled: Line Continuation
\c, when filling enabled: Line Continuation
\d, as delimiter: Delimiters
\D, delimiters allowed by: Delimiters
\e, and glyph definitions: Using Symbols
\e, and translations: Character Translations
\e, as delimiter: Delimiters
\E, as delimiter: Delimiters
\e, as delimiter: Delimiters
\e, incompatibilities with AT&T troff: Other Differences
\F, and changing fonts: Selecting Fonts
\f, and font translations: Selecting Fonts
\f, incompatibilities with AT&T troff: Compatibility Mode
\h, delimiters allowed by: Delimiters
\H, delimiters allowed by: Delimiters
\H, incompatibilities with AT&T troff: Compatibility Mode
\H, using + and - with: Numeric Expressions
\H, with fractional type sizes: Using Fractional Type Sizes
\l, and glyph definitions: Using Symbols
\L, and glyph definitions: Using Symbols
\l, delimiters allowed by: Delimiters
\L, delimiters allowed by: Delimiters
\N, and translations: Character Translations
\n, and warnings: Warnings
\N, delimiters allowed by: Delimiters
\n, incompatibilities with AT&T troff: Compatibility Mode
\n, when reading text for a macro: Copy Mode
\o, delimiters allowed by: Delimiters
\p, as delimiter: Delimiters
\p, as delimiter: Delimiters
\R, after \c: Line Continuation
\R, and warnings: Warnings
\r, as delimiter: Delimiters
\R, delimiters allowed by: Delimiters
\R, difference from nr: Auto-increment
\R, using + and - with: Numeric Expressions
\RET, when reading text for a macro: Copy Mode
\s, delimiters allowed by: Delimiters
\S, delimiters allowed by: Delimiters
\s, incompatibilities with AT&T troff: Compatibility Mode
\S, incompatibilities with AT&T troff: Compatibility Mode
\s, incompatibilities with AT&T troff: Compatibility Mode
\s, using + and - with: Numeric Expressions
\s, with fractional type sizes: Using Fractional Type Sizes
\SP, as delimiter: Delimiters
\SP, difference from \~: Calling Macros
\SP, incompatibilities with AT&T troff: Other Differences
\t, and copy mode: Tabs and Fields
\t, and translations: Character Translations
\t, and warnings: Warnings
\t, as delimiter: Delimiters
\u, as delimiter: Delimiters
\V, and copy mode: I/O
\v, delimiters allowed by: Delimiters
\v, internal representation: Gtroff Internals
\w, delimiters allowed by: Delimiters
\X, and special characters: Postprocessor Access
\X, delimiters allowed by: Delimiters
\x, delimiters allowed by: Delimiters
\X, followed by \%: Manipulating Hyphenation
\Y, followed by \%: Manipulating Hyphenation
\Z, delimiters allowed by: Delimiters
\[, and translations: Character Translations
\\, when reading text for a macro: Copy Mode
\^, as delimiter: Delimiters
\^, incompatibilities with AT&T troff: Other Differences
\_, and translations: Character Translations
\_, as delimiter: Delimiters
\_, as delimiter: Delimiters
\_, incompatibilities with AT&T troff: Other Differences
\`, and translations: Character Translations
\`, as delimiter: Delimiters
\`, as delimiter: Delimiters
\`, incompatibilities with AT&T troff: Other Differences
\{, as delimiter: Delimiters
\{, as delimiter: Delimiters
\{, incompatibilities with AT&T troff: Other Differences
\|, as delimiter: Delimiters
\|, incompatibilities with AT&T troff: Other Differences
\}, and warnings: Warnings
\}, as delimiter: Delimiters
\}, as delimiter: Delimiters
\}, incompatibilities with AT&T troff: Other Differences
\~, and translations: Character Translations
\~, as delimiter: Delimiters
\~, difference from \SP: Calling Macros
\~, incompatibilities with AT&T troff: Other Differences
]
], as part of an identifier: Identifiers
], at end of sentence: Sentences
], at end of sentence: Using Symbols
], macro names starting with, and refer: Identifiers
|
|, and page motion: Numeric Expressions
A
ab request, incompatibilities with AT&T troff: Other Differences
aborting (ab): Debugging
absolute (sic) position operator (|): Numeric Expressions
abstract font style: Using Fonts
abstract font style, setting up (sty): Font Families
accent marks [ms]: ms Legacy Features
access to postprocessor: Postprocessor Access
accessing unnamed glyphs with \N: Font Description File Format
activating kerning (kern): Ligatures and Kerning
activating ligatures (lg): Ligatures and Kerning
activating track kerning (tkf): Ligatures and Kerning
ad request, and hyphenation margin: Manipulating Hyphenation
ad request, and hyphenation space: Manipulating Hyphenation
addition: Numeric Expressions
additional inter-sentence space: Manipulating Filling and Adjustment
adjustment and filling, manipulating: Manipulating Filling and Adjustment
adjustment mode register (.j): Manipulating Filling and Adjustment
adjustment to both margins, difference from AT&T troff: Other Differences
Adobe Glyph List (AGL): Using Symbols
alias, diversion, creating (als): Strings
alias, diversion, removing (rm): Strings
alias, macro, creating (als): Strings
alias, macro, removing (rm): Strings
alias, register, creating (aln): Setting Registers
alias, register, removing (rr): Setting Registers
alias, string, creating (als): Strings
alias, string, removing (rm): Strings
aliasing fonts with third argument to fp request: Font Positions
als request, and \$0: Parameters
am, am1, ami requests, and warnings: Warnings
appending to a diversion (da, boxa): Diversions
appending to a file (opena): I/O
appending to a macro (am): Writing Macros
appending to a string (as): Strings
approximation output register (.A): Built-in Registers
arc, drawing (‘\D'a …'’): Drawing Geometric Objects
argument: Requests and Macros
arguments to macros: Calling Macros
arguments to macros, and tabs: Invoking Requests
arguments to requests: Invoking Requests
arguments to requests, and tabs: Invoking Requests
arguments, and compatibility mode: Gtroff Internals
arguments, to escape sequences, delimiting: Delimiters
arguments, to strings: Strings
arithmetic operators: Numeric Expressions
artificial fonts: Artificial Fonts
as, as1 requests, and comments: Comments
as, as1 requests, and warnings: Warnings
ASCII output encoding: Groff Options
asciify request, and writem: I/O
assertion (arithmetic operator): Numeric Expressions
assign number format to register (af): Assigning Register Formats
assignments, indirect: Interpolating Registers
assignments, nested: Interpolating Registers
AT&T ms, macro package differences: Differences from AT&T ms
attributes, character cell: Using Fonts
auto-incrementation of a register: Auto-increment
automatic font mounting: Selecting Fonts
automatic hyphenation: Manipulating Hyphenation
automatic hyphenation parameters: Manipulating Hyphenation
auxiliary macro package: Major Macro Packages
available glyphs, list of (groff_char(7) man page): Using Symbols
B
background: Background
background color name register (.M): Colors
backslash glyph, formatting (\[rs]): Using Escape Sequences
backslash, embedding in a macro argument: Calling Macros
backslash, printing (\\, \e, \E, \[rs]): Other Differences
backspace character, and translations: Character Translations
backtrace of input stack (backtrace): Debugging
baseline rule special character(\[ru]): Drawing Geometric Objects
baseline, text: Page Geometry
baseline, text: Manipulating Type Size and Vertical Spacing
basic scaling unit (u): Measurements
basic units: Page Geometry
basic units, conversion to: Measurements
basics of macro package usage: Basics
bd request, and font styles: Font Families
bd request, and font translations: Selecting Fonts
bd request, incompatibilities with AT&T troff: Other Differences
beginning diversion (di, box): Diversions
beginning of conditional block (\{): Conditional Blocks
blank line: Breaking
blank line macro (blm): Breaking
blank line macro (blm): Invoking Requests
blank line macro (blm): Blank Line Traps
blank line trap (blm): Invoking Requests
blank line traps: Blank Line Traps
blank lines, disabling: Manipulating Spacing
block, conditional, beginning (\{): Conditional Blocks
block, conditional, end (\}): Conditional Blocks
blocks, conditional: Conditional Blocks
body, of a while request: while
boldface, imitating (bd): Artificial Fonts
bottom margin: Page Location Traps
boundary-relative motion operator (|): Numeric Expressions
bounding box: Miscellaneous
box (diversion operation): Diversions
box request, and warnings: Warnings
box rule glyph (\[br]): Drawing Geometric Objects
box, boxa requests, and warnings: Warnings
boxa request, and dn (dl): Diversions
boxa request, and warnings: Warnings
boxes [ms]: ms keeps and displays
bp request, and top-level diversion: Page Control
bp request, and traps (.pe): Page Location Traps
bp request, causing implicit break: Manipulating Filling and Adjustment
bp request, incompatibilities with AT&T troff: Other Differences
bp request, using + and - with: Numeric Expressions
br glyph, and cflags: Using Symbols
brace escape sequence, closing (\}): Conditional Blocks
brace escape sequence, opening (\}): Conditional Blocks
brace escape sequences (\{, \}): Conditional Blocks
break: Breaking
break: Manipulating Filling and Adjustment
break (introduction): Basics
break request, in a while loop: while
break, page: Page Geometry
break, page: Page Control
break, page: The Implicit Page Trap
break, page (introduction): Basics
break, page, final: End-of-input Traps
break, page, prevented by vpt: Vertical Position Traps
breaking file names (\:): Manipulating Hyphenation
breaking URLs (\:): Manipulating Hyphenation
breaking without hyphens (\:): Manipulating Hyphenation
built-in register, removing: Built-in Registers
built-in registers: Built-in Registers
bulleted list, example markup [ms]: Lists in ms
C
c scaling unit: Measurements
calling a macro: Requests and Macros
calling macros: Calling Macros
capabilities of groff: groff Capabilities
case-transforming a string (stringdown, stringup): Strings
categories, warning: Warnings
CCSID 1047 output encoding (EBCDIC): Groff Options
ce request, causing implicit break: Manipulating Filling and Adjustment
ce request, difference from ‘.ad c’: Manipulating Filling and Adjustment
cell, character, attributes: Using Fonts
centered text (filled): Manipulating Filling and Adjustment
centered text (unfilled): Manipulating Filling and Adjustment
centering lines (ce): Manipulating Filling and Adjustment
centering lines (introduction): Basics
centimeter scaling unit (c): Measurements
cf request, and copy mode: I/O
cf request, causing implicit break: Manipulating Filling and Adjustment
changing control characters: Control Characters
changing font family (fam, \F): Font Families
changing fonts (ft, \f): Selecting Fonts
changing format, and read-only registers: Assigning Register Formats
changing the font height (\H): Artificial Fonts
changing the font slant (\S): Artificial Fonts
changing the page number character (pc): Page Layout
changing trap location (ch): Page Location Traps
changing type sizes (ps, \s): Changing the Type Size
changing vertical line spacing (vs): Changing the Vertical Spacing
char request, and soft hyphen character: Manipulating Hyphenation
char request, and translations: Character Translations
char request, used with \N: Using Symbols
character: Using Symbols
character cell attributes: Using Fonts
character class (class): Character Classes
character classes: Character Classes
character properties (cflags): Using Symbols
character translations: Character Translations
character, backspace, and translations: Character Translations
character, control (.): Requests and Macros
character, control, changing (cc): Control Characters
character, defining (char): Using Symbols
character, defining fallback (fchar, fschar, schar): Using Symbols
character, distinguished from glyph: Using Symbols
character, dummy (\&): Dummy Characters
character, dummy (\&), as control character suppressor: Requests and Macros
character, dummy (\&), effect on kerning: Ligatures and Kerning
character, dummy (\&), effect on \l escape sequence: Drawing Geometric Objects
character, escape, changing (ec): Using Escape Sequences
character, escape, while defining glyph: Using Symbols
character, field delimiting (fc): Fields
character, field padding (fc): Fields
character, horizontal tab: Tabs and Leaders
character, hyphenation (\%): Manipulating Hyphenation
character, leader: Tabs and Leaders
character, leader repetition (lc): Leaders
character, leader, and translations: Character Translations
character, leader, non-interpreted (\a): Leaders
character, named (\C): Using Symbols
character, newline, and translations: Character Translations
character, no-break control ('): Requests and Macros
character, no-break control, changing (c2): Control Characters
character, ordinary: Identifiers
character, soft hyphen, setting (shc): Manipulating Hyphenation
character, special: Character Translations
character, tab repetition (tc): Tabs and Fields
character, tab, and translations: Character Translations
character, tab, non-interpreted (\t): Tabs and Fields
character, transparent: Using Symbols
character, transparent dummy (\)): Dummy Characters
characters, end-of-sentence: Using Symbols
characters, end-of-sentence transparent: Sentences
characters, hyphenation: Using Symbols
characters, input, and output glyphs, compatibility with AT&T troff: Other Differences
characters, invalid for trf request: I/O
characters, invalid input: Identifiers
characters, overlapping: Using Symbols
characters, special: Sentences
characters, special, list of (groff_char(7) man page): Using Symbols
characters, unnamed, accessing with \N: Font Description File Format
circle, filled, drawing (‘\D'C …'’): Drawing Geometric Objects
circle, outlined, drawing (‘\D'c …'’): Drawing Geometric Objects
circle, solid, drawing (‘\D'C …'’): Drawing Geometric Objects
circle, stroked, drawing (‘\D'c …'’): Drawing Geometric Objects
class of characters (class): Character Classes
classes, character: Character Classes
clearing input line trap (it, itc): Input Line Traps
closing brace escape sequence (\}): Conditional Blocks
closing file (close): I/O
code page 1047 output encoding: Groff Options
code page 1047, input encoding: Input Encodings
code, hyphenation (hcode): Manipulating Hyphenation
color name, background, register (.M): Colors
color name, fill, register (.M): Colors
color name, stroke, register (.m): Colors
color, default: Colors
color, fill: Colors
color, stroke: Colors
colors: Colors
command prefix: Environment
command-line options: Groff Options
comments: Comments
comments in device description files: DESC File Format
comments in font description files: Font Description File Format
comments, lining up with tabs: Comments
comments, with ds: Strings
common features: Common Features
common name space of macros, diversions, and strings: Identifiers
comparison of strings: Operators in Conditionals
comparison operators: Numeric Expressions
compatibility mode: Warnings
compatibility mode: Compatibility Mode
compatibility mode, and parameters: Gtroff Internals
complementation, logical: Numeric Expressions
composite glyph names: Using Symbols
conditional block, beginning (\{): Conditional Blocks
conditional block, end (\}): Conditional Blocks
conditional blocks: Conditional Blocks
conditional expressions: Operators in Conditionals
conditional output for terminal (TTY): Operators in Conditionals
conditional page break (ne): Page Control
conditionals and loops: Conditionals and Loops
configuring control characters: Control Characters
configuring the page length (pl): Page Layout
consecutive hyphenated lines (hlm): Manipulating Hyphenation
constant glyph space mode (cs): Artificial Fonts
contents, table of: Table of Contents
contents, table of: Leaders
continuation, input line (\RET): Line Continuation
continuation, output line (\c): Line Continuation
continue request, in a while loop: while
continued output line register (.int): Line Continuation
continuous underlining (cu): Artificial Fonts
control character (.): Requests and Macros
control character, changing (cc): Control Characters
control character, no-break ('): Requests and Macros
control character, no-break, changing (c2): Control Characters
control characters: Control Characters
control line: Requests and Macros
control, line: Line Continuation
control, page: Page Control
conventions for input: Input Conventions
conversion to basic units: Measurements
copy mode: Copy Mode
copy mode: Copy Mode
copy mode, and cf request: I/O
copy mode, and device request: Postprocessor Access
copy mode, and length request: Strings
copy mode, and macro parameters: Parameters
copy mode, and output request: Diversions
copy mode, and trf request: I/O
copy mode, and write request: I/O
copy mode, and writec request: I/O
copy mode, and writem request: I/O
copy mode, and \!: Diversions
copy mode, and \?: Operators in Conditionals
copy mode, and \?: Diversions
copy mode, and \a: Leaders
copy mode, and \t: Tabs and Fields
copy mode, and \V: I/O
copying environment (evc): Environments
correction between oblique and upright glyph (\/, \,): Italic Corrections
correction between upright and oblique glyph (\/, \,): Italic Corrections
correction, italic (\/): Italic Corrections
correction, left italic (\,): Italic Corrections
cover page in [ms], example markup: ms Document Description Macros
cp request, and glyph definitions: Using Symbols
cq glyph, at end of sentence: Sentences
cq glyph, at end of sentence: Using Symbols
creating alias for register (aln): Setting Registers
creating alias, for diversion (als): Strings
creating alias, for macro (als): Strings
creating alias, for string (als): Strings
creating new characters (char): Using Symbols
credits: Credits
cs request, and font styles: Font Families
cs request, and font translations: Selecting Fonts
cs request, incompatibilities with AT&T troff: Other Differences
cs request, with fractional type sizes: Using Fractional Type Sizes
CSTR #54 errata: Built-in Registers
CSTR #54 errata: Line Layout
CSTR #54 errata: Page Control
CSTR #54 errata: Artificial Fonts
CSTR #54 errata: Changing the Type Size
CSTR #54 errata: Page Motions
CSTR #54 erratum, bp request: Page Control
CSTR #54 erratum, po request: Line Layout
CSTR #54 erratum, ps request: Changing the Type Size
CSTR #54 erratum, sb register: Page Motions
CSTR #54 erratum, st register: Page Motions
CSTR #54 erratum, yr register: Built-in Registers
CSTR #54 erratum, \S escape: Artificial Fonts
CSTR #54 erratum, \s escape sequence: Changing the Type Size
current directory: Macro Directories
current input file name register (.F): Built-in Registers
current page number (%): Page Control
current time, hours (hours): Built-in Registers
current time, minutes (minutes): Built-in Registers
current time, seconds (seconds): Built-in Registers
D
da request, and dn (dl): Diversions
da request, and warnings: Warnings
da request, and warnings: Warnings
date, day of the month register (dy): Built-in Registers
date, day of the week register (dw): Built-in Registers
date, month of the year register (mo): Built-in Registers
date, year register (year, yr): Built-in Registers
day of the month register (dy): Built-in Registers
day of the week register (dw): Built-in Registers
dd glyph, at end of sentence: Sentences
dd glyph, at end of sentence: Using Symbols
de request, and while: while
de, de1, dei requests, and warnings: Warnings
debugging: Debugging
debugging page location traps: Page Location Traps
decimal point, as delimiter: Delimiters
decrementation, automatic, of a register: Auto-increment
default color: Colors
default tab stops: Tabs and Fields
default units: Default Units
deferred output: Deferring Output
defining character (char): Using Symbols
defining character class (class): Character Classes
defining fallback character (fchar, fschar, schar): Using Symbols
defining glyph (char): Using Symbols
defining symbol (char): Using Symbols
delimited arguments, incompatibilities with AT&T troff: Compatibility Mode
delimiters, for escape sequence arguments: Delimiters
delimiting character, for fields (fc): Fields
delimiting escape sequence arguments: Delimiters
depth, interpolation: Calling Macros
depth, of last glyph (.cdp): Environments
DESC file format: DESC File Format
DESC file, and font mounting: Font Positions
DESC file, and use_charnames_in_special keyword: Postprocessor Access
description file, font: Using Fonts
device description files, comments: DESC File Format
device request, and copy mode: Postprocessor Access
device resolution: Page Geometry
device resolution: DESC File Format
device resolution, obtaining in the formatter: Measurements
devices for output: Output Device Intro
dg glyph, at end of sentence: Sentences
dg glyph, at end of sentence: Using Symbols
di request, and warnings: Warnings
di request, and warnings: Warnings
differences in implementation: Implementation Differences
digit-width space (\0): Page Motions
digits, as delimiters: Delimiters
dimensions, line: Line Layout
directories for fonts: Font Directories
directories for macros: Macro Directories
directory, current: Macro Directories
directory, for tmac files: Macro Directories
directory, home: Macro Directories
directory, platform-specific: Macro Directories
directory, site-local: Macro Directories
directory, site-local: Font Directories
disabling hyphenation (\%): Manipulating Hyphenation
disabling \ (eo): Using Escape Sequences
discardable horizontal space: Manipulating Filling and Adjustment
displays: Displays and Keeps
displays [ms]: ms keeps and displays
displays, and footnotes [ms]: ms Footnotes
distance to next vertical position trap register (.t): Page Location Traps
diversion: Deferring Output
diversion name register (.z): Diversions
diversion trap, setting (dt): Diversion Traps
diversion traps: Diversion Traps
diversion, appending to (da, boxa): Diversions
diversion, beginning (di, box): Diversions
diversion, creating alias for (als): Strings
diversion, ending (di, box): Diversions
diversion, nested: Diversions
diversion, removing (rm): Strings
diversion, removing alias for (rm): Strings
diversion, renaming (rn): Strings
diversion, stripping final newline: Punning Names
diversion, top-level: Diversions
diversion, top-level, and bp: Page Control
diversion, top-level, and \!: Diversions
diversion, top-level, and \?: Diversions
diversion, unformatting (asciify): Diversions
diversion, vertical position in, register (.d): Diversions
diversions: Diversions
diversions: Punning Names
diversions, and traps: Page Location Traps
diversions, shared name space with macros and strings: Identifiers
division, truncating: Numeric Expressions
dl register, and da (boxa): Diversions
dn register, and da (boxa): Diversions
document description macros, [ms]: ms Document Description Macros
document formats: Document Formats
documents, multi-file: Debugging
documents, structuring the source of: Invoking Requests
dot, as delimiter: Delimiters
double quote, embedding in a macro argument: Calling Macros
double quotes, trailing, in strings: Strings
double-spacing (ls): Manipulating Spacing
double-spacing (vs, pvs): Changing the Vertical Spacing
down-casing a string (stringdown): Strings
drawing a filled circle (‘\D'C …'’): Drawing Geometric Objects
drawing a filled ellipse (‘\D'E …'’): Drawing Geometric Objects
drawing a filled polygon (‘\D'P …'’): Drawing Geometric Objects
drawing a line (‘\D'l …'’): Drawing Geometric Objects
drawing a solid circle (‘\D'C …'’): Drawing Geometric Objects
drawing a solid ellipse (‘\D'E …'’): Drawing Geometric Objects
drawing a solid polygon (‘\D'P …'’): Drawing Geometric Objects
drawing a spline (‘\D'~ …'’): Drawing Geometric Objects
drawing a stroked circle (‘\D'c …'’): Drawing Geometric Objects
drawing a stroked ellipse (‘\D'e …'’): Drawing Geometric Objects
drawing a stroked polygon (‘\D'p …'’): Drawing Geometric Objects
drawing an arc (‘\D'a …'’): Drawing Geometric Objects
drawing an outlined circle (‘\D'c …'’): Drawing Geometric Objects
drawing an outlined ellipse (‘\D'e …'’): Drawing Geometric Objects
drawing an outlined polygon (‘\D'p …'’): Drawing Geometric Objects
drawing horizontal lines (\l): Drawing Geometric Objects
drawing position: Page Geometry
drawing position, vertical (nl): Page Control
drawing requests: Drawing Geometric Objects
drawing vertical lines (\L): Drawing Geometric Objects
ds request, and comments: Strings
ds request, and double quotes: Strings
ds request, and leading spaces: Strings
ds, ds1 requests, and comments: Comments
ds, ds1 requests, and warnings: Warnings
dummy character (\&): Dummy Characters
dummy character (\&), as control character suppressor: Requests and Macros
dummy character (\&), effect on kerning: Ligatures and Kerning
dummy character (\&), effect on \l escape sequence: Drawing Geometric Objects
dummy character, transparent (\)): Dummy Characters
dummy environment, used by \w escape sequence: Page Motions
dumping environments (pev): Debugging
dumping page location traps (ptr): Debugging
dumping registers (pnr): Debugging
dumping symbol table (pm): Debugging
E
EBCDIC output encoding: Groff Options
EBCDIC, input encoding: Input Encodings
ejection, page: Page Geometry
ejection, page: Page Control
ejection, page: The Implicit Page Trap
ejection, page, of final page: End-of-input Traps
ejection, page, prevented by vpt: Vertical Position Traps
el request, and warnings: Warnings
ellipse, filled, drawing (‘\D'E …'’): Drawing Geometric Objects
ellipse, outlined, drawing (‘\D'e …'’): Drawing Geometric Objects
ellipse, solid, drawing (‘\D'E …'’): Drawing Geometric Objects
ellipse, stroked, drawing (‘\D'e …'’): Drawing Geometric Objects
em glyph, and cflags: Using Symbols
em scaling unit (m): Measurements
embolding of special fonts: Artificial Fonts
empty line: Breaking
en scaling unit (n): Measurements
enabling vertical position traps (vpt): Vertical Position Traps
encoding, input, code page 1047: Input Encodings
encoding, input, EBCDIC: Input Encodings
encoding, input, Latin-1 (ISO 8859-1): Input Encodings
encoding, input, Latin-2 (ISO 8859-2): Input Encodings
encoding, input, Latin-5 (ISO 8859-9): Input Encodings
encoding, input, Latin-9 (ISO 8859-15): Input Encodings
encoding, output, ASCII: Groff Options
encoding, output, code page 1047: Groff Options
encoding, output, EBCDIC: Groff Options
encoding, output, ISO 646: Groff Options
encoding, output, Latin-1 (ISO 8859-1): Groff Options
encoding, output, UTF-8: Groff Options
end of conditional block (\}): Conditional Blocks
end-of-input macro (em): End-of-input Traps
end-of-input trap, setting (em): End-of-input Traps
end-of-input traps: End-of-input Traps
end-of-sentence characters: Sentences
end-of-sentence characters: Using Symbols
end-of-sentence transparent characters: Sentences
ending diversion (di, box): Diversions
endnotes: Footnotes and Endnotes
environment: Deferring Output
environment availability and naming, incompatibilities with: Other Differences
environment number/name register (.ev): Environments
environment variables: Environment
environment, copying (evc): Environments
environment, dimensions of last glyph (.w, .cht, .cdp, .csk): Environments
environment, dummy, used by \w escape sequence: Page Motions
environment, previous line length (.n): Environments
environment, switching (ev): Environments
environments: Environments
environments, dumping (pev): Debugging
equality operator: Numeric Expressions
equation example [ms]: ms Insertions
equations [ms]: ms Insertions
escape character, changing (ec): Using Escape Sequences
escape character, formatting (\e): Using Escape Sequences
escape character, while defining glyph: Using Symbols
escape sequence: Formatter Instructions
escape sequence argument delimiters: Delimiters
escape sequences: Using Escape Sequences
escape sequences, brace (\{, \}): Conditional Blocks
escaping newline characters, in strings: Strings
ex request, use in debugging: Debugging
ex request, used with nx and rd: I/O
example markup, bulleted list [ms]: Lists in ms
example markup, cover page in [ms]: ms Document Description Macros
example markup, glossary-style list [ms]: Lists in ms
example markup, numbered list [ms]: Lists in ms
examples of invocation: Invocation Examples
exiting (ex): Debugging
expansion of strings (\*): Strings
explicit hyphen (\%): Manipulating Hyphenation
explicit hyphenation: Manipulating Hyphenation
expression, limitation of logical not in: Numeric Expressions
expression, order of evaluation: Numeric Expressions
expressions, and register format: Assigning Register Formats
expressions, and space characters: Numeric Expressions
expressions, conditional: Operators in Conditionals
expressions, numeric: Numeric Expressions
extra post-vertical line space (\x): Changing the Vertical Spacing
extra post-vertical line space register (.a): Manipulating Spacing
extra pre-vertical line space (\x): Changing the Vertical Spacing
extra spaces between words: Adjustment
extreme values representable with Roman numerals: Assigning Register Formats
extremum operators (>?, <?): Numeric Expressions
F
f scaling unit: Colors
factor, zoom, of a font (fzoom): Selecting Fonts
fallback character, defining (fchar, fschar, schar): Using Symbols
fallback glyph, removing definition (rchar, rfschar): Using Symbols
fam request, and changing fonts: Selecting Fonts
families, font: Font Families
family, font: Using Fonts
features, common: Common Features
fi request, causing implicit break: Manipulating Filling and Adjustment
field delimiting character (fc): Fields
field padding character (fc): Fields
fields: Fields
fields, and tabs: Tabs and Fields
figure space (\0): Page Motions
figures [ms]: ms Insertions
file formats: File Formats
file names, breaking (\:): Manipulating Hyphenation
file, appending to (opena): I/O
file, closing (close): I/O
file, font description: Using Fonts
file, inclusion (so): I/O
file, macro, search path: Macro Directories
file, opening (open): I/O
file, processing next (nx): I/O
file, writing to (write, writec): I/O
files, font: Device and Font Description Files
fill color: Colors
fill color name register (.M): Colors
fill mode (fi), enabling: Manipulating Filling and Adjustment
fill mode, and \c: Line Continuation
fill mode, disabling: Manipulating Filling and Adjustment
filled circle, drawing (‘\D'C …'’): Drawing Geometric Objects
filled ellipse, drawing (‘\D'E …'’): Drawing Geometric Objects
filled polygon, drawing (‘\D'P …'’): Drawing Geometric Objects
filling: Filling
filling and adjustment, manipulating: Manipulating Filling and Adjustment
filling of output, disabling (nf): Manipulating Filling and Adjustment
filling of output, enabling (fi): Manipulating Filling and Adjustment
filling, and break warnings: Warnings
filling, and inter-sentence space: Manipulating Filling and Adjustment
final newline, stripping in diversions: Punning Names
fl request, causing implicit break: Manipulating Filling and Adjustment
floating keep: Displays and Keeps
flush output (fl): Debugging
font: Using Fonts
font aliasing with third argument to fp request: Font Positions
font description file: Using Fonts
font description file format: DESC File Format
font description file, format: Font Description File Format
font description files, comments: Font Description File Format
font directories: Font Directories
font families: Font Families
font family: Using Fonts
font family, changing (fam, \F): Font Families
font file, format: Font Description File Format
font files: Device and Font Description Files
font for underlining (uf): Artificial Fonts
font height, changing (\H): Artificial Fonts
font metrics: Using Fonts
font mounting, automatic: Selecting Fonts
font path: Font Directories
font position register (.f): Font Positions
font positions: Font Positions
font slant, changing (\S): Artificial Fonts
font style: Using Fonts
font style, abstract: Using Fonts
font style, abstract, setting up (sty): Font Families
font styles: Font Families
font translation (ftr): Selecting Fonts
font, magnification (fzoom): Selecting Fonts
font, mounting (fp): Font Positions
font, optical size: Selecting Fonts
font, previous, selecting (\f[], \fP): Selecting Fonts
font, previous, slecting (ft): Selecting Fonts
font, selection: Selecting Fonts
font, special: Using Fonts
font, text: Using Fonts
font, unstyled: Using Fonts
font, zoom factor (fzoom): Selecting Fonts
fonts, artificial: Artificial Fonts
fonts, changing (ft, \f): Selecting Fonts
fonts, searching: Font Directories
fonts, special: Special Fonts
footers: Page Layout
footers: Page Location Traps
footers [ms]: ms Headers and Footers
footnote marker [ms]: ms Footnotes
footnotes: Footnotes and Endnotes
footnotes [ms]: ms Footnotes
footnotes, and displays [ms]: ms Footnotes
footnotes, and keeps [ms]: ms Footnotes
form letters: I/O
format of font description file: DESC File Format
format of font description files: Font Description File Format
format of font files: Font Description File Format
format of register (\g): Assigning Register Formats
format, paper: Paper Format
formats, file: File Formats
formatter instructions: Formatter Instructions
formatting a backslash glyph (\[rs]): Using Escape Sequences
formatting a title line (tl): Page Layout
formatting the escape character (\e): Using Escape Sequences
formatting the time: I/O
fp request, and font translations: Selecting Fonts
fp request, incompatibilities with AT&T troff: Other Differences
fractional point sizes: Using Fractional Type Sizes
fractional point sizes: Other Differences
fractional type sizes: Using Fractional Type Sizes
fractional type sizes: Other Differences
fractional type sizes in ms macros: Differences from AT&T ms
French spacing: Sentences
fspecial request, and font styles: Font Families
fspecial request, and font translations: Selecting Fonts
fspecial request, and glyph search order: Using Symbols
fspecial request, and imitating bold: Artificial Fonts
ft request, and font translations: Selecting Fonts
full-service macro package: Major Macro Packages
G
geometry, page: Page Geometry
GGL (groff glyph list): Using Symbols
GGL (groff glyph list): Character Classes
glossary-style list, example markup [ms]: Lists in ms
glyph: Using Symbols
glyph for line drawing: Drawing Geometric Objects
glyph names, composite: Using Symbols
glyph pile (\b): Drawing Geometric Objects
glyph properties (cflags): Using Symbols
glyph, box rule (\[br]): Drawing Geometric Objects
glyph, constant space: Artificial Fonts
glyph, defining (char): Using Symbols
glyph, distinguished from character: Using Symbols
glyph, for line drawing: Drawing Geometric Objects
glyph, for margins (mc): Miscellaneous
glyph, last, dimensions (.w, .cht, .cdp, .csk): Environments
glyph, leader repetition (lc): Leaders
glyph, numbered (\N): Character Translations
glyph, numbered (\N): Using Symbols
glyph, removing definition (rchar, rfschar): Using Symbols
glyph, soft hyphen (hy): Manipulating Hyphenation
glyph, tab repetition (tc): Tabs and Fields
glyph, underscore (\[ru]): Drawing Geometric Objects
glyphs, available, list of (groff_char(7) man page): Using Symbols
glyphs, output, and input characters, compatibility with AT&T troff: Other Differences
glyphs, overstriking (\o): Page Motions
glyphs, unnamed: Using Symbols
glyphs, unnamed, accessing with \N: Font Description File Format
GNU troff, identification register (.g): Built-in Registers
GNU troff, PID register ($$): Built-in Registers
GNU troff, process ID register ($$): Built-in Registers
GNU-specific register (.g): Built-in Registers
graphic renditions: Using Fonts
greater than (or equal to) operator: Numeric Expressions
groff capabilities: groff Capabilities
groff glyph list (GGL): Using Symbols
groff glyph list (GGL): Character Classes
groff invocation: Invoking groff
groff, and pi request: I/O
groff—what is it?: What Is groff?
GROFF_BIN_PATH, environment variable: Environment
GROFF_COMMAND_PREFIX, environment variable: Environment
GROFF_ENCODING, environment variable: Environment
GROFF_FONT_PATH, environment variable: Environment
GROFF_FONT_PATH, environment variable: Font Directories
GROFF_TMAC_PATH, environment variable: Environment
GROFF_TMAC_PATH, environment variable: Macro Directories
GROFF_TMPDIR, environment variable: Environment
GROFF_TYPESETTER, environment variable: Environment
grohtml, the program: Groff Options
gtroff, interactive use: Debugging
gtroff, output: gtroff Output
gtroff, reference: GNU troff Reference
H
hair space (\^): Page Motions
hcode request, and glyph definitions: Using Symbols
headers: Page Layout
headers: Page Location Traps
headers [ms]: ms Headers and Footers
height, font, changing (\H): Artificial Fonts
height, of last glyph (.cht): Environments
high-water mark register (.h): Diversions
home directory: Macro Directories
horizontal discardable space: Manipulating Filling and Adjustment
horizontal input line position register (hp): Page Motions
horizontal input line position, saving (\k): Page Motions
horizontal line, drawing (\l): Drawing Geometric Objects
horizontal motion (\h): Page Motions
horizontal motion quantum: DESC File Format
horizontal motion quantum register (.H): Motion Quanta
horizontal output line position register (.k): Page Motions
horizontal resolution: DESC File Format
horizontal resolution register (.H): Motion Quanta
horizontal space (\h): Page Motions
horizontal space, unformatting: Punning Names
horizontal tab character: Tabs and Leaders
hours, current time (hours): Built-in Registers
hpf request, and hyphenation language: Manipulating Hyphenation
hw request, and hy restrictions: Manipulating Hyphenation
hw request, and hyphenation language: Manipulating Hyphenation
hy glyph, and cflags: Using Symbols
hyphen, explicit (\%): Manipulating Hyphenation
hyphenated lines, consecutive (hlm): Manipulating Hyphenation
hyphenating characters: Using Symbols
hyphenation: Hyphenation
hyphenation character (\%): Manipulating Hyphenation
hyphenation code (hcode): Manipulating Hyphenation
hyphenation consecutive line count register (.hlc): Manipulating Hyphenation
hyphenation consecutive line limit register (.hlm): Manipulating Hyphenation
hyphenation exceptions: Manipulating Hyphenation
hyphenation language register (.hla): Manipulating Hyphenation
hyphenation margin (hym): Manipulating Hyphenation
hyphenation margin register (.hym): Manipulating Hyphenation
hyphenation mode register (.hy): Manipulating Hyphenation
hyphenation parameters, automatic: Manipulating Hyphenation
hyphenation pattern files: Manipulating Hyphenation
hyphenation patterns (hpf): Manipulating Hyphenation
hyphenation space (hys): Manipulating Hyphenation
hyphenation space adjustment threshold: Manipulating Hyphenation
hyphenation space adjustment threshold register (.hys): Manipulating Hyphenation
hyphenation, automatic: Manipulating Hyphenation
hyphenation, disabling (\%): Manipulating Hyphenation
hyphenation, explicit: Manipulating Hyphenation
hyphenation, incompatibilities with AT&T troff: Other Differences
hyphenation, manipulating: Manipulating Hyphenation
hyphenation, manual: Manipulating Hyphenation
I
i scaling unit: Measurements
i/o: I/O
IBM code page 1047 input encoding: Input Encodings
IBM code page 1047 output encoding: Groff Options
identifiers: Identifiers
identifiers, undefined: Identifiers
ie request, and font translations: Selecting Fonts
ie request, and warnings: Warnings
ie request, operators to use with: Operators in Conditionals
if request, and font translations: Selecting Fonts
if request, and the ‘!’ operator: Numeric Expressions
if request, operators to use with: Operators in Conditionals
if-else: if-else
if-then: if-then
imitating boldface (bd): Artificial Fonts
implementation differences: Implementation Differences
implicit line break: Breaking
implicit trap: The Implicit Page Trap
in request, causing implicit break: Manipulating Filling and Adjustment
in request, using + and - with: Numeric Expressions
inch scaling unit (i): Measurements
including a file (so): I/O
incompatibilities with AT&T troff: Implementation Differences
increment value without changing the register: Auto-increment
incrementation, automatic, of a register: Auto-increment
indentation (in): Line Layout
indentation, of roff source code: Invoking Requests
index, in macro package: Indexing
indicator, scaling: Measurements
indirect assignments: Interpolating Registers
input and output requests: I/O
input characters and output glyphs, compatibility with AT&T troff: Other Differences
input characters, invalid: Identifiers
input conventions: Input Conventions
input encoding, code page 1047: Input Encodings
input encoding, EBCDIC: Input Encodings
input encoding, Latin-1 (ISO 8859-1): Input Encodings
input encoding, Latin-2 (ISO 8859-2): Input Encodings
input encoding, Latin-5 (ISO 8859-9): Input Encodings
input encoding, Latin-9 (ISO 8859-15): Input Encodings
input file name, current, register (.F): Built-in Registers
input level: Calling Macros
input level in delimited arguments: Compatibility Mode
input line continuation (\RET): Line Continuation
input line number register (.c, c.): Built-in Registers
input line number, setting (lf): Debugging
input line position, horizontal, saving (\k): Page Motions
input line trap, clearing (it, itc): Input Line Traps
input line trap, setting (it, itc): Input Line Traps
input line traps: Input Line Traps
input line traps and interrupted lines (itc): Input Line Traps
input line, horizontal position, register (hp): Page Motions
input line, productive: Manipulating Filling and Adjustment
input stack, backtrace (backtrace): Debugging
input stack, setting limit: Debugging
input token: Gtroff Internals
input, 8-bit: Font Description File Format
input, standard, reading from (rd): I/O
inserting horizontal space (\h): Page Motions
installation: Installation
instructing the formatter: Formatter Instructions
inter-sentence space size register (.sss): Manipulating Filling and Adjustment
inter-sentence space, additional: Manipulating Filling and Adjustment
inter-word spacing, minimal: Manipulating Filling and Adjustment
interactive use of gtroff: Debugging
intercepting requests: Control Characters
intermediate output: gtroff Output
interpolating registers (\n): Interpolating Registers
interpolation: Requests and Macros
interpolation depth: Calling Macros
interpolation depth in delimited arguments: Compatibility Mode
interpolation of strings (\*): Strings
interpretation mode: Copy Mode
interrupted line: Line Continuation
interrupted line register (.int): Line Continuation
interrupted lines and input line traps (itc): Input Line Traps
introduction: Introduction
invalid characters for trf request: I/O
invalid input characters: Identifiers
invocation examples: Invocation Examples
invoking groff: Invoking groff
invoking requests: Invoking Requests
ISO 646 output encoding: Groff Options
ISO 8859-1 (Latin-1) output encoding: Groff Options
ISO 8859-1 (Latin-1), input encoding: Input Encodings
ISO 8859-15 (Latin-9), input encoding: Input Encodings
ISO 8859-2 (Latin-2), input encoding: Input Encodings
ISO 8859-9 (Latin-5), input encoding: Input Encodings
italic correction (\/): Italic Corrections
J
justifying text: Manipulating Filling and Adjustment
justifying text (rj): Manipulating Filling and Adjustment
K
keep, floating: Displays and Keeps
keeps (introduction): Displays and Keeps
keeps [ms]: ms keeps and displays
keeps, and footnotes [ms]: ms Footnotes
kerning and ligatures: Ligatures and Kerning
kerning enabled register (.kern): Ligatures and Kerning
kerning, activating (kern): Ligatures and Kerning
kerning, track: Ligatures and Kerning
L
landscape page orientation: Paper Format
language [ms]: ms language and localization
last glyph, dimensions (.w, .cht, .cdp, .csk): Environments
last-requested point size registers (.psr, .sr): Using Fractional Type Sizes
last-requested type size registers (.psr, .sr): Using Fractional Type Sizes
Latin-1 (ISO 8859-1) output encoding: Groff Options
Latin-1 (ISO 8859-1), input encoding: Input Encodings
Latin-2 (ISO 8859-2), input encoding: Input Encodings
Latin-5 (ISO 8859-9), input encoding: Input Encodings
Latin-9 (ISO 8859-15), input encoding: Input Encodings
layout, line: Line Layout
layout, page: Page Layout
lc request, and glyph definitions: Using Symbols
leader character: Tabs and Leaders
leader character: Leaders
leader character, and translations: Character Translations
leader character, non-interpreted (\a): Leaders
leader repetition character (lc): Leaders
leaders: Leaders
leading: Manipulating Type Size and Vertical Spacing
leading space macro (lsm): Breaking
leading space traps: Leading Space Traps
leading spaces: Breaking
leading spaces macro (lsm): Leading Space Traps
leading spaces with ds: Strings
left italic correction (\,): Italic Corrections
left margin (po): Line Layout
length of a string (length): Strings
length of line (ll): Line Layout
length of previous line (.n): Environments
length of the page, configuring (pl): Page Layout
length of title line, configuring (lt): Page Layout
length request, and copy mode: Strings
less than (or equal to) operator: Numeric Expressions
letters, form: I/O
level, input: Calling Macros
level, suppression nesting, register: Suppressing Output
lf request, incompatibilities with AT&T troff: Other Differences
ligature: Using Symbols
ligatures and kerning: Ligatures and Kerning
ligatures enabled register (.lg): Ligatures and Kerning
ligatures, activating (lg): Ligatures and Kerning
limitations of \b escape sequence: Drawing Geometric Objects
line break: Manipulating Filling and Adjustment
line break (introduction): Basics
line break, output: Breaking
line control: Line Continuation
line dimensions: Line Layout
line drawing glyph: Drawing Geometric Objects
line drawing glyph: Drawing Geometric Objects
line indentation (in): Line Layout
line layout: Line Layout
line length (ll): Line Layout
line length register (.l): Line Layout
line length, previous (.n): Environments
line number, input, register (.c, c.): Built-in Registers
line number, output, register (ln): Miscellaneous
line numbers, printing (nm): Miscellaneous
line space, extra post-vertical (\x): Changing the Vertical Spacing
line space, extra pre-vertical (\x): Changing the Vertical Spacing
line spacing register (.L): Manipulating Spacing
line spacing, post-vertical (pvs): Changing the Vertical Spacing
line thickness (‘\D't …'’): Drawing Geometric Objects
line, blank: Breaking
line, drawing (‘\D'l …'’): Drawing Geometric Objects
line, horizontal, drawing (\l): Drawing Geometric Objects
line, input, continuation (\RET): Line Continuation
line, input, horizontal position, register (hp): Page Motions
line, input, horizontal position, saving (\k): Page Motions
line, interrupted: Line Continuation
line, output, continuation (\c): Line Continuation
line, output, horizontal position, register (.k): Page Motions
line, productive input: Manipulating Filling and Adjustment
line, vertical, drawing (\L): Drawing Geometric Objects
line-tabs mode: Tabs and Fields
lines, blank, disabling: Manipulating Spacing
lines, centering (ce): Manipulating Filling and Adjustment
lines, centering (introduction): Basics
lines, consecutive hyphenated (hlm): Manipulating Hyphenation
lines, interrupted, and input line traps (itc): Input Line Traps
lines, right-aligning (introduction): Basics
lines, right-justifying (introduction): Basics
list of special characters (groff_char(7) man page): Using Symbols
listing page location traps (ptr): Debugging
lists: Paragraphs
ll request, using + and - with: Numeric Expressions
localization: Manipulating Hyphenation
localization [ms]: ms language and localization
locating macro files: Macro Directories
locating macro packages: Macro Directories
location, vertical, page, marking (mk): Page Motions
location, vertical, page, returning to marked (rt): Page Motions
logical “and” operator: Numeric Expressions
logical “or” operator: Numeric Expressions
logical complementation operator: Numeric Expressions
logical conjunction operator: Numeric Expressions
logical disjunction operator: Numeric Expressions
logical not, limitation in expression: Numeric Expressions
logical operators: Numeric Expressions
long names: Compatibility Mode
loops and conditionals: Conditionals and Loops
lowercasing a string (stringdown): Strings
ls request, alternative to (pvs): Changing the Vertical Spacing
lt request, using + and - with: Numeric Expressions
M
m scaling unit: Measurements
M scaling unit: Measurements
machine units: Page Geometry
macro: Requests and Macros
macro arguments: Calling Macros
macro arguments, and compatibility mode: Gtroff Internals
macro arguments, and tabs: Invoking Requests
macro directories: Macro Directories
macro file search path: Macro Directories
macro name register (\$0): Parameters
macro names, starting with [ or ], and refer: Identifiers
macro package: Macro Packages
macro package search path: Macro Directories
macro package usage, basics of: Basics
macro package, auxiliary: Major Macro Packages
macro package, full-service: Major Macro Packages
macro package, introduction: Macro Package Intro
macro package, major: Major Macro Packages
macro package, minor: Major Macro Packages
macro package, structuring the source of: Invoking Requests
macro, appending to (am): Writing Macros
macro, creating alias for (als): Strings
macro, end-of-input (em): End-of-input Traps
macro, parameters (\$): Parameters
macro, removing (rm): Strings
macro, removing alias for (rm): Strings
macro, renaming (rn): Strings
macros, recursive: while
macros, searching: Macro Directories
macros, shared name space with strings and diversions: Identifiers
macros, tutorial for users: Tutorial for Macro Users
macros, writing: Writing Macros
magnification of a font (fzoom): Selecting Fonts
major macro package: Major Macro Packages
major version number register (.x): Built-in Registers
man macros, custom headers and footers: Optional man extensions
man macros, Ultrix-specific: Optional man extensions
man pages: man
manipulating filling and adjustment: Manipulating Filling and Adjustment
manipulating hyphenation: Manipulating Hyphenation
manipulating spacing: Manipulating Spacing
manipulating type size and vertical spacing: Manipulating Type Size and Vertical Spacing
manual hyphenation: Manipulating Hyphenation
manual pages: man
margin for hyphenation (hym): Manipulating Hyphenation
margin glyph (mc): Miscellaneous
margin, bottom: Page Location Traps
margin, left (po): Line Layout
margin, right: Line Layout
margin, top: Page Location Traps
mark, high-water, register (.h): Diversions
marker, footnote [ms]: ms Footnotes
marking vertical page location (mk): Page Motions
maximum operator: Numeric Expressions
maximum value representable with Roman numerals: Assigning Register Formats
mdoc macros: mdoc
me macro package: me
measurement units: Measurements
measurements: Measurements
measurements, specifying safely: Default Units
metrics, font: Using Fonts
minimal inter-word spacing: Manipulating Filling and Adjustment
minimum operator: Numeric Expressions
minimum value representable with Roman numerals: Assigning Register Formats
minor macro package: Major Macro Packages
minor version number register (.y): Built-in Registers
minutes, current time (minutes): Built-in Registers
mm macro package: mm
mode for constant glyph space (cs): Artificial Fonts
mode, compatibility: Compatibility Mode
mode, compatibility, and parameters: Gtroff Internals
mode, copy: Copy Mode
mode, copy: Copy Mode
mode, copy, and cf request: I/O
mode, copy, and device request: Postprocessor Access
mode, copy, and length request: Strings
mode, copy, and macro parameters: Parameters
mode, copy, and output request: Diversions
mode, copy, and trf request: I/O
mode, copy, and write request: I/O
mode, copy, and writec request: I/O
mode, copy, and writem request: I/O
mode, copy, and \!: Diversions
mode, copy, and \?: Operators in Conditionals
mode, copy, and \?: Diversions
mode, copy, and \a: Leaders
mode, copy, and \t: Tabs and Fields
mode, copy, and \V: I/O
mode, fill (fi), enabling: Manipulating Filling and Adjustment
mode, fill, and break warnings: Warnings
mode, fill, and inter-sentence space: Manipulating Filling and Adjustment
mode, fill, and \c: Line Continuation
mode, fill, disabling: Manipulating Filling and Adjustment
mode, interpretation: Copy Mode
mode, line-tabs: Tabs and Fields
mode, no-fill: Manipulating Filling and Adjustment
mode, no-fill, and \c: Line Continuation
mode, no-space (ns): Manipulating Spacing
mode, nroff: troff and nroff Modes
mode, safer: Groff Options
mode, safer: Macro Directories
mode, safer: Built-in Registers
mode, safer: I/O
mode, safer: I/O
mode, safer: I/O
mode, safer: I/O
mode, safer: Safer Mode
mode, troff: troff and nroff Modes
mode, unsafe: Groff Options
mode, unsafe: Macro Directories
mode, unsafe: Built-in Registers
mode, unsafe: I/O
mode, unsafe: I/O
mode, unsafe: I/O
mode, unsafe: I/O
modifying requests: Control Characters
modulus: Numeric Expressions
mom macro package: mom
month of the year register (mo): Built-in Registers
motion operators: Numeric Expressions
motion quanta: Motion Quanta
motion quantum, horizontal: DESC File Format
motion quantum, horizontal, register (.H): Motion Quanta
motion quantum, vertical: DESC File Format
motion, horizontal (\h): Page Motions
motion, vertical (\v): Page Motions
motions, page: Page Motions
mounting a font (fp): Font Positions
mounting position: Using Fonts
mounting position: Using Fonts
mounting, font, automatic: Selecting Fonts
ms macros: ms
ms macros, accent marks: ms Legacy Features
ms macros, body text: ms Body Text
ms macros, creating table of contents: ms TOC
ms macros, displays: ms keeps and displays
ms macros, document control settings: ms Document Control Settings
ms macros, document description: ms Document Description Macros
ms macros, equations: ms Insertions
ms macros, figures: ms Insertions
ms macros, footers: ms Headers and Footers
ms macros, footnotes: ms Footnotes
ms macros, fractional type sizes in: Differences from AT&T ms
ms macros, general structure: ms Document Structure
ms macros, groff differences from AT&T: Differences from AT&T ms
ms macros, headers: ms Headers and Footers
ms macros, headings: Headings in ms
ms macros, keeps: ms keeps and displays
ms macros, language: ms language and localization
ms macros, lists: Lists in ms
ms macros, localization: ms language and localization
ms macros, margins: ms Margins
ms macros, multiple columns: ms Multiple Columns
ms macros, naming conventions: ms Naming Conventions
ms macros, nested lists: Indented regions in ms
ms macros, obtaining typographical symbols: Typographical symbols in ms
ms macros, page layout: ms Page Layout
ms macros, paragraph handling: Paragraphs in ms
ms macros, references: ms Insertions
ms macros, special characters: ms Legacy Features
ms macros, strings: ms Legacy Features
ms macros, tables: ms Insertions
ms macros, text settings: Text settings in ms
multi-file documents: Debugging
multi-line strings: Strings
multi-page table example [ms]: ms Insertions
multiple columns [ms]: ms Multiple Columns
multiplication: Numeric Expressions
N
n scaling unit: Measurements
name space, common, of macros, diversions, and strings: Identifiers
name, background color, register (.M): Colors
name, fill color, register (.M): Colors
name, stroke color, register (.m): Colors
named character (\C): Using Symbols
names, long: Compatibility Mode
naming conventions, ms macros: ms Naming Conventions
ne request, and the .trunc register: Page Location Traps
ne request, comparison with sv: Page Control
negating register values: Setting Registers
negation: Numeric Expressions
nested assignments: Interpolating Registers
nested diversions: Diversions
nested lists [ms]: Indented regions in ms
nesting level, suppression, register: Suppressing Output
new page (bp): Page Control
newline character, and translations: Character Translations
newline character, in strings, escaping: Strings
newline, as delimiter: Delimiters
newline, final, stripping in diversions: Punning Names
next file, processing (nx): I/O
next free font position register (.fp): Font Positions
next page number register (.pn): Page Layout
next page number, configuring (pn): Page Layout
nf request, causing implicit break: Manipulating Filling and Adjustment
nl register, and .d: Diversions
nl register, difference from .h: Diversions
nm request, using + and - with: Numeric Expressions
no-break control character ('): Requests and Macros
no-break control character, changing (c2): Control Characters
no-fill mode: Manipulating Filling and Adjustment
no-fill mode, and \c: Line Continuation
no-space mode (ns): Manipulating Spacing
node, output: Gtroff Internals
non-printing break point (\:): Manipulating Hyphenation
nr request, and warnings: Warnings
nr request, using + and - with: Numeric Expressions
nroff mode: troff and nroff Modes
number formats, assigning to register (af): Assigning Register Formats
number of registers register (.R): Built-in Registers
number, input line, setting (lf): Debugging
number, page, next, configuring (pn): Page Layout
numbered glyph (\N): Character Translations
numbered glyph (\N): Using Symbols
numbered list, example markup [ms]: Lists in ms
numbers, line, printing (nm): Miscellaneous
numeral-width space (\0): Page Motions
numerals, as delimiters: Delimiters
numerals, Roman: Assigning Register Formats
numeric expression, valid: Numeric Expressions
numeric expressions: Numeric Expressions
O
object creation: Writing Macros
offset, page: Page Geometry
offset, page (po): Line Layout
open request, and safer mode: Groff Options
opena request, and safer mode: Groff Options
opening brace escape sequence (\}): Conditional Blocks
opening file (open): I/O
operator, scaling: Numeric Expressions
operators, arithmetic: Numeric Expressions
operators, as delimiters: Delimiters
operators, comparison: Numeric Expressions
operators, extremum (>?, <?): Numeric Expressions
operators, logical: Numeric Expressions
operators, motion: Numeric Expressions
operators, unary arithmetic: Numeric Expressions
optical size of a font: Selecting Fonts
options: Groff Options
order of evaluation in expressions: Numeric Expressions
ordinary character: Identifiers
orientation, landscape: Paper Format
orphan: Page Control
orphan lines, preventing with ne: Page Control
os request, and no-space mode: Page Control
outlined circle, drawing (‘\D'c …'’): Drawing Geometric Objects
outlined ellipse, drawing (‘\D'e …'’): Drawing Geometric Objects
outlined polygon, drawing (‘\D'p …'’): Drawing Geometric Objects
output and input requests: I/O
output comparison operator: Operators in Conditionals
output device name string (.T): Groff Options
output device name string (.T): Strings
output device name string (.T), in other implementations: Other Differences
output device usage register (.T): Groff Options
output device usage register (.T), incompatibility with AT&T troff: Other Differences
output devices: Output Device Intro
output encoding, ASCII: Groff Options
output encoding, code page 1047: Groff Options
output encoding, EBCDIC: Groff Options
output encoding, ISO 646: Groff Options
output encoding, Latin-1 (ISO 8859-1): Groff Options
output encoding, UTF-8: Groff Options
output glyphs, and input characters, compatibility with AT&T troff: Other Differences
output line break: Breaking
output line number register (ln): Miscellaneous
output line properties: Manipulating Filling and Adjustment
output line, continuation (\c): Line Continuation
output line, horizontal position, register (.k): Page Motions
output node: Gtroff Internals
output request, and copy mode: Diversions
output request, and \!: Diversions
output, filling, disablement of (nf): Manipulating Filling and Adjustment
output, filling, enablement of (fi): Manipulating Filling and Adjustment
output, flush (fl): Debugging
output, gtroff: gtroff Output
output, intermediate: gtroff Output
output, suppressing (\O): Suppressing Output
output, transparent (cf, trf): I/O
output, transparent (\!, \?): Diversions
output, transparent, incompatibilities with AT&T troff: Other Differences
output, troff: gtroff Output
overlapping characters: Using Symbols
overstriking glyphs (\o): Page Motions
P
p scaling unit: Measurements
P scaling unit: Measurements
package, macro: Macro Packages
package, macro, auxiliary: Major Macro Packages
package, macro, full-service: Major Macro Packages
package, macro, introduction: Macro Package Intro
package, macro, major: Major Macro Packages
package, macro, minor: Major Macro Packages
package, macro, search path: Macro Directories
package, package, structuring the source of: Invoking Requests
padding character, for fields (fc): Fields
page: Page Geometry
page break: Page Geometry
page break: Page Control
page break: The Implicit Page Trap
page break (introduction): Basics
page break, conditional (ne): Page Control
page break, final: End-of-input Traps
page break, prevented by vpt: Vertical Position Traps
page control: Page Control
page ejection: Page Geometry
page ejection: Page Control
page ejection: The Implicit Page Trap
page ejection status register (.pe): Page Location Traps
page ejection, of final page: End-of-input Traps
page ejection, prevented by vpt: Vertical Position Traps
page footers: Page Location Traps
page headers: Page Location Traps
page layout: Page Layout
page layout [ms]: ms Page Layout
page length register (.p): Page Layout
page length, configuring (pl): Page Layout
page location traps: Page Location Traps
page location traps, debugging: Page Location Traps
page location, vertical, marking (mk): Page Motions
page location, vertical, returning to marked (rt): Page Motions
page motions: Page Motions
page number character (%): Page Layout
page number character, changing (pc): Page Layout
page number register (%): Page Control
page number, configuring next (pn): Page Layout
page number, next, register (.pn): Page Layout
page offset: Page Geometry
page offset (po): Line Layout
page orientation, landscape: Paper Format
page, geometry of: Page Geometry
page, new (bp): Page Control
paper format: Paper Format
paper size: Paper Format
paragraphs: Paragraphs
parameter count register (.$): Parameters
parameters: Parameters
parameters, and compatibility mode: Gtroff Internals
parameters, macro (\$): Parameters
parentheses: Numeric Expressions
partially collected line: Manipulating Filling and Adjustment
path, for font files: Font Directories
path, for tmac files: Macro Directories
pattern files, for hyphenation: Manipulating Hyphenation
patterns for hyphenation (hpf): Manipulating Hyphenation
pending output line: Manipulating Filling and Adjustment
pi request, and groff: I/O
pi request, and safer mode: Groff Options
pi request, disabled by default: Safer Mode
pica scaling unit (P): Measurements
PID of GNU troff register ($$): Built-in Registers
pile, glyph (\b): Drawing Geometric Objects
pl request, using + and - with: Numeric Expressions
plain text approximation output register (.A): Groff Options
plain text approximation output register (.A): Built-in Registers
planting a trap: Traps
platform-specific directory: Macro Directories
pm request, incompatibilities with AT&T troff: Other Differences
pn request, using + and - with: Numeric Expressions
PNG image generation from PostScript: DESC File Format
po request, using + and - with: Numeric Expressions
point scaling unit (p): Measurements
point size registers (.s, .ps): Changing the Type Size
point size registers, last-requested (.psr, .sr): Using Fractional Type Sizes
point sizes, changing (ps, \s): Changing the Type Size
point sizes, fractional: Using Fractional Type Sizes
point sizes, fractional: Other Differences
polygon, filled, drawing (‘\D'P …'’): Drawing Geometric Objects
polygon, outlined, drawing (‘\D'p …'’): Drawing Geometric Objects
polygon, solid, drawing (‘\D'P …'’): Drawing Geometric Objects
polygon, stroked, drawing (‘\D'p …'’): Drawing Geometric Objects
position of lowest text line (.h): Diversions
position, absolute (sic) operator (|): Numeric Expressions
position, drawing: Page Geometry
position, horizontal input line, saving (\k): Page Motions
position, horizontal, in input line, register (hp): Page Motions
position, horizontal, in output line, register (.k): Page Motions
position, mounting: Using Fonts
position, vertical, in diversion, register (.d): Diversions
positions, font: Font Positions
post-vertical line spacing: Changing the Vertical Spacing
post-vertical line spacing register (.pvs): Changing the Vertical Spacing
post-vertical line spacing, changing (pvs): Changing the Vertical Spacing
postprocessor access: Postprocessor Access
postprocessors: Output Device Intro
PostScript, bounding box: Miscellaneous
PostScript, PNG image generation: DESC File Format
prefix, for commands: Environment
preprocessors: Preprocessor Intro
previous font, selecting (ft): Selecting Fonts
previous font, selecting (\f[], \fP): Selecting Fonts
previous line length (.n): Environments
print current page register (.P): Groff Options
printing backslash (\\, \e, \E, \[rs]): Other Differences
printing line numbers (nm): Miscellaneous
printing to stderr (tm, tm1, tmc): Debugging
printing, zero-width (\z, \Z): Page Motions
printing, zero-width (\z, \Z): Page Motions
process ID of GNU troff register ($$): Built-in Registers
processing next file (nx): I/O
productive input line: Manipulating Filling and Adjustment
properties of characters (cflags): Using Symbols
properties of glyphs (cflags): Using Symbols
properties of output lines: Manipulating Filling and Adjustment
ps request, and constant glyph space mode: Artificial Fonts
ps request, incompatibilities with AT&T troff: Other Differences
ps request, using + and - with: Numeric Expressions
ps request, with fractional type sizes: Using Fractional Type Sizes
pso request, and safer mode: Groff Options
pvs request, using + and - with: Numeric Expressions
Q
quanta, motion: Motion Quanta
quantum, horizontal motion: DESC File Format
quantum, vertical motion: DESC File Format
R
radicalex glyph, and cflags: Using Symbols
ragged-left text: Manipulating Filling and Adjustment
ragged-right text: Manipulating Filling and Adjustment
rc request, and glyph definitions: Using Symbols
read-only register removal, incompatibility with AT&T troff: Other Differences
read-only register, changing format: Assigning Register Formats
reading from standard input (rd): I/O
recursive macros: while
refer, and macro names starting with [ or ]: Identifiers
reference, gtroff: GNU troff Reference
references [ms]: ms Insertions
register format, in expressions: Assigning Register Formats
register, assigning number format to (af): Assigning Register Formats
register, built-in, removing: Built-in Registers
register, creating alias for (aln): Setting Registers
register, format (\g): Assigning Register Formats
register, read-only, removal, incompatibility with AT&T troff: Other Differences
register, removing (rr): Setting Registers
register, removing alias for (rr): Setting Registers
register, renaming (rnn): Setting Registers
registers: Registers
registers, built-in: Built-in Registers
registers, dumping (pnr): Debugging
registers, interpolating (\n): Interpolating Registers
registers, number of, register (.R): Built-in Registers
registers, setting (nr, \R): Setting Registers
removal of read-only registers, incompatibility with AT&T troff: Other Differences
removing a built-in register: Built-in Registers
removing a register (rr): Setting Registers
removing alias for register (rr): Setting Registers
removing alias, for diversion (rm): Strings
removing alias, for macro (rm): Strings
removing alias, for string (rm): Strings
removing diversion (rm): Strings
removing glyph definition (rchar, rfschar): Using Symbols
removing macro (rm): Strings
removing request (rm): Strings
removing string (rm): Strings
renaming a register (rnn): Setting Registers
renaming diversion (rn): Strings
renaming macro (rn): Strings
renaming request (rn): Strings
renaming string (rn): Strings
renditions, graphic: Using Fonts
request: Requests and Macros
request: Formatter Instructions
request arguments: Invoking Requests
request arguments, and compatibility mode: Gtroff Internals
request arguments, and tabs: Invoking Requests
request, removing (rm): Strings
request, renaming (rn): Strings
request, undefined: Comments
requests for drawing: Drawing Geometric Objects
requests for input and output: I/O
requests, intercepting: Control Characters
requests, invoking: Invoking Requests
requests, modifying: Control Characters
resolution, device: Page Geometry
resolution, device: DESC File Format
resolution, device, obtaining in the formatter: Measurements
resolution, horizontal: DESC File Format
resolution, horizontal, register (.H): Motion Quanta
resolution, vertical: DESC File Format
returning to marked vertical page location (rt): Page Motions
revision number register (.Y): Built-in Registers
right margin: Line Layout
right-aligning lines (introduction): Basics
right-justifying (rj): Manipulating Filling and Adjustment
right-justifying lines (introduction): Basics
rivers: Other Differences
rj request, causing implicit break: Manipulating Filling and Adjustment
rn glyph, and cflags: Using Symbols
roman glyph, correction after italic glyph (\/): Italic Corrections
roman glyph, correction before italic glyph (\,): Italic Corrections
Roman numerals: Assigning Register Formats
Roman numerals, extrema (maximum and minimum): Assigning Register Formats
rq glyph, at end of sentence: Sentences
rq glyph, at end of sentence: Using Symbols
rt request, using + and - with: Numeric Expressions
ru glyph, and cflags: Using Symbols
running system commands: I/O
S
s scaling unit: Using Fractional Type Sizes
safer mode: Groff Options
safer mode: Macro Directories
safer mode: Built-in Registers
safer mode: I/O
safer mode: I/O
safer mode: I/O
safer mode: I/O
safer mode: Safer Mode
saving horizontal input line position (\k): Page Motions
scaling indicator: Measurements
scaling operator: Numeric Expressions
scaling unit c: Measurements
scaling unit f: Colors
scaling unit i: Measurements
scaling unit m: Measurements
scaling unit M: Measurements
scaling unit n: Measurements
scaling unit p: Measurements
scaling unit P: Measurements
scaling unit s: Using Fractional Type Sizes
scaling unit u: Measurements
scaling unit v: Measurements
scaling unit z: Using Fractional Type Sizes
searching fonts: Font Directories
searching macros: Macro Directories
seconds, current time (seconds): Built-in Registers
selecting the previous font (ft): Selecting Fonts
sentence space: Sentences
sentence space size register (.sss): Manipulating Filling and Adjustment
sentences: Sentences
sequence, escape: Formatter Instructions
setting diversion trap (dt): Diversion Traps
setting end-of-input trap (em): End-of-input Traps
setting input line number (lf): Debugging
setting input line trap (it, itc): Input Line Traps
setting registers (nr, \R): Setting Registers
setting the page length (pl): Page Layout
setting up an abstract font style (sty): Font Families
shc request, and translations: Character Translations
site-local directory: Macro Directories
site-local directory: Font Directories
size of sentence space register (.sss): Manipulating Filling and Adjustment
size of word space register (.ss): Manipulating Filling and Adjustment
size, optical, of a font: Selecting Fonts
size, paper: Paper Format
size, size: Manipulating Type Size and Vertical Spacing
sizes, fractional: Other Differences
sizes, fractional type: Using Fractional Type Sizes
skew, of last glyph (.csk): Environments
slant, font, changing (\S): Artificial Fonts
soft hyphen character, setting (shc): Manipulating Hyphenation
soft hyphen glyph (hy): Manipulating Hyphenation
solid circle, drawing (‘\D'C …'’): Drawing Geometric Objects
solid ellipse, drawing (‘\D'E …'’): Drawing Geometric Objects
solid polygon, drawing (‘\D'P …'’): Drawing Geometric Objects
SOURCE_DATE_EPOCH, environment variable: Environment
sp request, and no-space mode: Manipulating Spacing
sp request, causing implicit break: Manipulating Filling and Adjustment
space between sentences: Sentences
space between sentences register (.sss): Manipulating Filling and Adjustment
space between words register (.ss): Manipulating Filling and Adjustment
space character, as delimiter: Delimiters
space characters, in expressions: Numeric Expressions
space, between sentences: Manipulating Filling and Adjustment
space, between words: Manipulating Filling and Adjustment
space, discardable, horizontal: Manipulating Filling and Adjustment
space, hair (\^): Page Motions
space, horizontal (\h): Page Motions
space, horizontal, unformatting: Punning Names
space, thin (\|): Page Motions
space, unbreakable (\~): Manipulating Filling and Adjustment
space, unbreakable and unadjustable (\SP): Page Motions
space, vertical, unit (v): Measurements
space, width of a digit (numeral) (\0): Page Motions
spaces with ds: Strings
spaces, in a macro argument: Calling Macros
spaces, leading and trailing: Breaking
spacing (introduction): Basics
spacing, manipulating: Manipulating Spacing
spacing, vertical: Page Geometry
spacing, vertical: Manipulating Type Size and Vertical Spacing
spacing, vertical (introduction): Basics
special characters: Sentences
special characters: Character Translations
special characters [ms]: ms Legacy Features
special characters, list of (groff_char(7) man page): Using Symbols
special font: Using Fonts
special fonts: Using Symbols
special fonts: Special Fonts
special fonts: Font Description File Format
special fonts, emboldening: Artificial Fonts
special request, and font translations: Selecting Fonts
special request, and glyph search order: Using Symbols
spline, drawing (‘\D'~ …'’): Drawing Geometric Objects
springing a trap: Traps
sqrtex glyph, and cflags: Using Symbols
ss request, incompatibilities with AT&T troff: Other Differences
stack: Environments
stacking glyphs (\b): Drawing Geometric Objects
standard input, reading from (rd): I/O
stderr, printing to (tm, tm1, tmc): Debugging
stops, tab: Tabs and Leaders
string arguments: Strings
string comparison: Operators in Conditionals
string expansion (\*): Strings
string interpolation (\*): Strings
string, appending (as): Strings
string, creating alias for (als): Strings
string, length of (length): Strings
string, removing (rm): Strings
string, removing alias for (rm): Strings
string, renaming (rn): Strings
strings: Strings
strings [ms]: ms Legacy Features
strings, multi-line: Strings
strings, shared name space with macros and diversions: Identifiers
stripping final newline in diversions: Punning Names
stroke color: Colors
stroke color name register (.m): Colors
stroked circle, drawing (‘\D'c …'’): Drawing Geometric Objects
stroked ellipse, drawing (‘\D'e …'’): Drawing Geometric Objects
stroked polygon, drawing (‘\D'p …'’): Drawing Geometric Objects
structuring source code of documents or macro packages: Invoking Requests
sty request, and changing fonts: Selecting Fonts
sty request, and font translations: Selecting Fonts
style, font: Using Fonts
style, font, abstract: Using Fonts
style, font, abstract, setting up (sty): Font Families
styles, font: Font Families
substring (substring): Strings
subtraction: Numeric Expressions
suppressing output (\O): Suppressing Output
suppression nesting level register: Suppressing Output
sv request, and no-space mode: Page Control
switching environments (ev): Environments
sy request, and safer mode: Groff Options
sy request, disabled by default: Safer Mode
symbol: Using Symbols
symbol table, dumping (pm): Debugging
symbol, defining (char): Using Symbols
symbols, using: Using Symbols
system commands, running: I/O
system() return value register (systat): I/O
T
tab character: Tabs and Leaders
tab character encoding: Tabs and Fields
tab character, and translations: Character Translations
tab character, as delimiter: Delimiters
tab character, non-interpreted (\t): Tabs and Fields
tab repetition character (tc): Tabs and Fields
tab stop settings register (.tabs): Tabs and Fields
tab stops: Tabs and Leaders
tab stops, default: Tabs and Fields
tab, line-tabs mode: Tabs and Fields
table of contents: Table of Contents
table of contents: Leaders
table of contents, creating [ms]: ms TOC
table, multi-page, example [ms]: ms Insertions
tables [ms]: ms Insertions
tabs, and fields: Tabs and Fields
tabs, and macro arguments: Invoking Requests
tabs, and request arguments: Invoking Requests
tabs, before comments: Comments
tagged paragraphs: Paragraphs
tags, paragraph: Paragraphs
terminal, conditional output for: Operators in Conditionals
text baseline: Page Geometry
text baseline: Manipulating Type Size and Vertical Spacing
text font: Using Fonts
text line: Requests and Macros
text line, position of lowest (.h): Diversions
text, GNU troff processing: Text
text, justifying: Manipulating Filling and Adjustment
text, justifying (rj): Manipulating Filling and Adjustment
thickness of lines (‘\D't …'’): Drawing Geometric Objects
thin space (\|): Page Motions
three-part title (tl): Page Layout
ti request, causing implicit break: Manipulating Filling and Adjustment
ti request, using + and - with: Numeric Expressions
time, current, hours (hours): Built-in Registers
time, current, minutes (minutes): Built-in Registers
time, current, seconds (seconds): Built-in Registers
time, formatting: I/O
title length, configuring (lt): Page Layout
title line length register (.lt): Page Layout
title line, formatting (tl): Page Layout
titles: Page Layout
tkf request, and font styles: Font Families
tkf request, and font translations: Selecting Fonts
tkf request, with fractional type sizes: Using Fractional Type Sizes
tl request, and mc: Miscellaneous
tmac, directory: Macro Directories
tmac, path: Macro Directories
TMPDIR, environment variable: Environment
token, input: Gtroff Internals
top margin: Page Location Traps
top-level diversion: Diversions
top-level diversion, and bp: Page Control
top-level diversion, and \!: Diversions
top-level diversion, and \?: Diversions
tr request, and glyph definitions: Using Symbols
tr request, and soft hyphen character: Manipulating Hyphenation
tr request, incompatibilities with AT&T troff: Other Differences
track kerning: Ligatures and Kerning
track kerning, activating (tkf): Ligatures and Kerning
trailing double quotes in strings: Strings
trailing spaces in string definitions and appendments: Strings
trailing spaces on text lines: Breaking
translations of characters: Character Translations
transparent characters: Using Symbols
transparent dummy character (\)): Dummy Characters
transparent output (cf, trf): I/O
transparent output (\!, \?): Diversions
transparent output, incompatibilities with AT&T troff: Other Differences
trap: Deferring Output
trap, changing location (ch): Page Location Traps
trap, distance to next vertical position, register (.t): Page Location Traps
trap, diversion, setting (dt): Diversion Traps
trap, end-of-input, setting (em): End-of-input Traps
trap, implicit: The Implicit Page Trap
trap, input line, clearing (it, itc): Input Line Traps
trap, input line, setting (it, itc): Input Line Traps
trap, planting: Traps
trap, springing: Traps
traps: Traps
traps, and diversions: Page Location Traps
traps, blank line: Blank Line Traps
traps, diversion: Diversion Traps
traps, end-of-input: End-of-input Traps
traps, input line: Input Line Traps
traps, input line, and interrupted lines (itc): Input Line Traps
traps, leading space: Leading Space Traps
traps, page location: Page Location Traps
traps, page location, dumping (ptr): Debugging
traps, page location, listing (ptr): Debugging
traps, sprung by bp request (.pe): Page Location Traps
traps, vertical position: Vertical Position Traps
trf request, and copy mode: I/O
trf request, and invalid characters: I/O
trf request, causing implicit break: Manipulating Filling and Adjustment
trin request, and asciify: Diversions
troff mode: troff and nroff Modes
troff output: gtroff Output
truncated vertical space register (.trunc): Page Location Traps
truncating division: Numeric Expressions
TTY, conditional output for: Operators in Conditionals
tutorial for macro users: Tutorial for Macro Users
type size: Manipulating Type Size and Vertical Spacing
type size registers (.s, .ps): Changing the Type Size
type size registers, last-requested (.psr, .sr): Using Fractional Type Sizes
type sizes, changing (ps, \s): Changing the Type Size
type sizes, fractional: Using Fractional Type Sizes
type sizes, fractional: Other Differences
typeface: Using Fonts
TZ, environment variable: Environment
U
u scaling unit: Measurements
uf request, and font styles: Font Families
ul glyph, and cflags: Using Symbols
ul request, and font translations: Selecting Fonts
Ultrix-specific man macros: Optional man extensions
unadjustable and unbreakable space (\SP): Page Motions
unary arithmetic operators: Numeric Expressions
unbreakable and unadjustable space (\SP): Page Motions
unbreakable space (\~): Manipulating Filling and Adjustment
undefined identifiers: Identifiers
undefined request: Comments
underline font (uf): Artificial Fonts
underlining (ul): Artificial Fonts
underlining, continuous (cu): Artificial Fonts
unformatting diversions (asciify): Diversions
unformatting horizontal space: Punning Names
Unicode: Identifiers
Unicode: Using Symbols
unit, scaling, c: Measurements
unit, scaling, f: Colors
unit, scaling, i: Measurements
unit, scaling, m: Measurements
unit, scaling, M: Measurements
unit, scaling, n: Measurements
unit, scaling, p: Measurements
unit, scaling, P: Measurements
unit, scaling, s: Using Fractional Type Sizes
unit, scaling, u: Measurements
unit, scaling, v: Measurements
unit, scaling, z: Using Fractional Type Sizes
units of measurement: Measurements
units, basic: Page Geometry
units, basic, conversion to: Measurements
units, default: Default Units
units, machine: Page Geometry
unnamed glyphs: Using Symbols
unnamed glyphs, accessing with \N: Font Description File Format
unsafe mode: Groff Options
unsafe mode: Macro Directories
unsafe mode: Built-in Registers
unsafe mode: I/O
unsafe mode: I/O
unsafe mode: I/O
unsafe mode: I/O
unstyled font: Using Fonts
up-casing a string (stringup): Strings
uppercasing a string (stringup): Strings
upright glyph, correction after oblique glyph (\/): Italic Corrections
upright glyph, correction before oblique glyph (\,): Italic Corrections
URLs, breaking (\:): Manipulating Hyphenation
user’s macro tutorial: Tutorial for Macro Users
user’s tutorial for macros: Tutorial for Macro Users
using escape sequences: Using Escape Sequences
using symbols: Using Symbols
UTF-8 output encoding: Groff Options
V
v scaling unit: Measurements
valid numeric expression: Numeric Expressions
value, incrementing without changing the register: Auto-increment
variables in environment: Environment
vee: Page Geometry
vee scaling unit (v): Measurements
version number, major, register (.x): Built-in Registers
version number, minor, register (.y): Built-in Registers
vertical drawing position (nl): Page Control
vertical line drawing (\L): Drawing Geometric Objects
vertical line spacing register (.v): Changing the Vertical Spacing
vertical line spacing, changing (vs): Changing the Vertical Spacing
vertical line spacing, effective value: Changing the Vertical Spacing
vertical motion (\v): Page Motions
vertical motion quantum: DESC File Format
vertical page location, marking (mk): Page Motions
vertical page location, returning to marked (rt): Page Motions
vertical position in diversion register (.d): Diversions
vertical position trap enable register (.vpt): Vertical Position Traps
vertical position traps: Vertical Position Traps
vertical position traps, enabling (vpt): Vertical Position Traps
vertical position, drawing (nl): Page Control
vertical resolution: DESC File Format
vertical space unit (v): Measurements
vertical spacing: Page Geometry
vertical spacing: Manipulating Type Size and Vertical Spacing
vertical spacing (introduction): Basics
W
warning categories: Warnings
warning level (warn): Debugging
warnings: Debugging
warnings: Warnings
what is groff?: What Is groff?
while: while
while request, and font translations: Selecting Fonts
while request, and the ‘!’ operator: Numeric Expressions
while request, confusing with br: while
while request, operators to use with: Operators in Conditionals
widow: Page Control
widow: Page Control
width escape (\w): Page Motions
width, of last glyph (.w): Environments
word space size register (.ss): Manipulating Filling and Adjustment
word, definition of: Filling
write request, and copy mode: I/O
writec request, and copy mode: I/O
writem request, and copy mode: I/O
writing macros: Writing Macros
writing to file (write, writec): I/O
Y
year, current, register (year, yr): Built-in Registers
Z
z scaling unit: Using Fractional Type Sizes
zero-width printing (\z, \Z): Page Motions
zero-width printing (\z, \Z): Page Motions
zoom factor of a font (fzoom): Selecting Fonts
+
Jump to:   " +   +% +   +& +   +' +   +( +   +) +   +* +   ++ +   +- +   +. +   +/ +   +8 +   +: +   +< +   += +   +> +   +[ +   +\ +   +] +   +| +   +
+A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +J +   +K +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +W +   +Y +   +Z +   +
+
+ + +
+
+
+

+Previous: Program and File Index, Up: GNU troff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Conditional-Blocks.html b/doc/groff.html.node/Conditional-Blocks.html new file mode 100644 index 0000000..b2b789b --- /dev/null +++ b/doc/groff.html.node/Conditional-Blocks.html @@ -0,0 +1,174 @@ + + + + + + +Conditional Blocks (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Conditionals and Loops   [Contents][Index]

+
+
+

5.23.4 Conditional Blocks

+ + + +

It is frequently desirable for a control structure to govern more than +one request, macro call, text line, or a combination of the foregoing. +The opening and closing brace escape sequences \{ and \} +define such groups. These conditional blocks can furthermore be +nested. +

+
+
Escape sequence: \{
+
+
Escape sequence: \}
+
+ + + + + + + + + + + + + +

\{ begins a conditional block; it must appear (after optional +spaces and tabs) immediately subsequent to the conditional expression of +an if, ie, or while +request,93 or as the argument to an el +request. +

+

\} ends a condition block and should appear on a line with other +occurrences of itself as necessary to match \{ sequences. It +can be preceded by a control character, spaces, and tabs. Input after +any quantity of \} sequences on the same line is processed only +if all of the preceding conditions to which they correspond are true. +Furthermore, a \} closing the body of a while request +must be the last such escape sequence on an input line. +

+

Brace escape sequences outside of control structures have no meaning and +produce no output. +

+

Caution: Input lines using \{ often end with +\RET, especially in macros that consist primarily of control +lines. Forgetting to use \RET on an input line after \{ +is a common source of error. +

+ +

We might write the following in a page header macro. If we delete +\RET, the header will carry an unwanted extra empty line (except +on page 1). +

+
+
.if (\\n[%] != 1) \{\
+.  ie ((\\n[%] % 2) = 0) .tl \\*[even-numbered-page-title]
+.  el                    .tl \\*[odd-numbered-page-title]
+.\}
+
+ +

Let us take a closer look at how conditional blocks nest. +

+
+
A
+.if 0 \{ B
+C
+D
+\}E
+F
+    ⇒ A F
+
+ +
+
N
+.if 1 \{ O
+.  if 0 \{ P
+Q
+R\} S\} T
+U
+    ⇒ N O U
+
+ +

The above behavior may challenge the intuition; it was implemented to +retain compatibility with AT&T troff. For clarity, it +is idiomatic to end input lines with \{ (followed by +\RET if appropriate), and to precede \} on an input +line with nothing more than a control character, spaces, tabs, and other +instances of itself. +

+

We can use ie, el, and conditional blocks to simulate the +multi-way “switch” or “case” control structures of other languages. +The following example is adapted from the groff man +package. Indentation is used to clarify the logic. +

+
+
.\" Simulate switch/case in roff.
+.      ie '\\$2'1' .ds title General Commands\"
+.el \{.ie '\\$2'2' .ds title System Calls\"
+.el \{.ie '\\$2'3' .ds title Library Functions\"
+.el \{.ie '\\$2'4' .ds title Kernel Interfaces\"
+.el \{.ie '\\$2'5' .ds title File Formats\"
+.el \{.ie '\\$2'6' .ds title Games\"
+.el \{.ie '\\$2'7' .ds title Miscellaneous Information\"
+.el \{.ie '\\$2'8' .ds title System Management\"
+.el \{.ie '\\$2'9' .ds title Kernel Development\"
+.el                .ds title \" empty
+.\}\}\}\}\}\}\}\}
+
+ + +
+
+
+

+Next: while, Previous: Operators in Conditionals, Up: Conditionals and Loops   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Conditionals-and-Loops.html b/doc/groff.html.node/Conditionals-and-Loops.html new file mode 100644 index 0000000..b05ce5d --- /dev/null +++ b/doc/groff.html.node/Conditionals-and-Loops.html @@ -0,0 +1,64 @@ + + + + + + +Conditionals and Loops (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.23 Conditionals and Loops

+ + + +

groff has if and while control structures like +other languages. However, the syntax for grouping multiple input lines +in the branches or bodies of these structures is unusual. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/Configuration-and-Customization.html b/doc/groff.html.node/Configuration-and-Customization.html new file mode 100644 index 0000000..6f76a47 --- /dev/null +++ b/doc/groff.html.node/Configuration-and-Customization.html @@ -0,0 +1,56 @@ + + + + + + +Configuration and Customization (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.14 Configuration and Customization

+ +

Packages provide means of customizing many of the details of how the +package behaves. These range from setting the default type size to +changing the appearance of section headers. +

+ + + + +
+ + + + + diff --git a/doc/groff.html.node/Control-Characters.html b/doc/groff.html.node/Control-Characters.html new file mode 100644 index 0000000..13ebe41 --- /dev/null +++ b/doc/groff.html.node/Control-Characters.html @@ -0,0 +1,137 @@ + + + + + + +Control Characters (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Formatter Instructions   [Contents][Index]

+
+
+

5.6.1 Control Characters

+ + + + +

The mechanism of using roff’s control characters to invoke +requests and call macros was introduced in Requests and Macros. +Control characters are recognized only at the beginning of an input +line, or at the beginning of the branch of a control structure request; +see Conditionals and Loops. +

+

A few requests cause a break implicitly; use the no-break control +character to prevent the break. Break suppression is its sole +behavioral distinction. Employing the no-break control character to +invoke requests that don’t cause breaks is harmless but poor style. +See Manipulating Filling and Adjustment. +

+ + + + + +

The control ‘.’ and no-break control ‘'’ characters can each +be changed to any ordinary character42 +with the cc and c2 requests, respectively. +

+
+
Request: .cc [o]
+
+

Recognize the ordinary character o as the control character. +If o is absent or invalid, the default control character +‘.’ is selected. The identity of the control character is +associated with the environment (see Environments). +

+ +
+
Request: .c2 [o]
+
+

Recognize the ordinary character o as the no-break control +character. If o is absent or invalid, the default no-break +control character ‘'’ is selected. The identity of the no-break +control character is associated with the environment +(see Environments). +

+ +

When writing a macro, you might wish to know which control character was +used to call it. +

+
+
Register: \n[.br]
+
+

This read-only register interpolates 1 if the currently executing +macro was called using the normal control character and 0 +otherwise. If a macro is interpolated as a string, the .br +register’s value is inherited from the context of the string +interpolation. See Strings. +

+ + + + +

Use this register to reliably intercept requests that imply breaks. +

+
+
.als bp*orig bp
+.de bp
+.  ie \\n[.br] .bp*orig
+.  el          'bp*orig
+..
+
+ +

Testing the .br register outside of a macro definition makes no +sense. +

+ + +
+
+
+

+Next: Invoking Requests, Previous: Formatter Instructions, Up: Formatter Instructions   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Conventions-Used-in-This-Manual.html b/doc/groff.html.node/Conventions-Used-in-This-Manual.html new file mode 100644 index 0000000..95e85b3 --- /dev/null +++ b/doc/groff.html.node/Conventions-Used-in-This-Manual.html @@ -0,0 +1,124 @@ + + + + + + +Conventions Used in This Manual (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+
+

1.8 Conventions Used in This Manual

+ +

We apply the term “groff” to the language documented here, the GNU +implementation of the overall system, the project that develops that +system, and the command of that name. In the first sense, groff +is an extended dialect of the roff language, for which many +similar implementations exist. +

+

The roff language features several major categories for which +many items are predefined. Presentations of these items feature the +form in which the item is most commonly used on the left, and, aligned +to the right margin, the name of the category in brackets. +

+
+
Register: \n[example]
+

The register ‘example’ is one that that groff doesn’t +predefine. You can create it yourself, though; see Setting Registers. +

+ +

To make this document useful as a reference and not merely amiable +bedtime reading, we tend to present these syntax items in exhaustive +detail when they arise. References to topics discussed later in the +text are frequent; skip material you don’t understand yet. +

+

We use Texinfo’s “result” (⇒) and error→ notations to +present output written to the standard output and standard error +streams, respectively. Diagnostic messages from the GNU troff +formatter and other programs are examples of the latter, but the +formatter can also be directed to write user-specified messages to the +standard error stream. The notation then serves to identify the +output stream and does not necessarily mean that an error has +occurred.2 +

+
+
$ echo "Twelve o'clock and" | groff -Tascii | sed '/^$/d'
+    ⇒ Twelve o'clock and
+$ echo '.tm all is well.' | groff > /dev/null
+    error→ all is well.
+
+ +

Sometimes we use ⇒ somewhat abstractly to represent formatted +text that you will need to use a PostScript or PDF viewer program (or a +printer) to observe. While arguably an abuse of notation, we think this +preferable to requiring the reader to understand the syntax of these +page description languages. +

+

We also present diagnostic messages in an abbreviated form, often +omitting the name of the program issuing them, the input file name, and +line number or other positional information when such data do not serve +to illuminate the topic under discussion. +

+

Most examples are of roff language input that would be placed in +a text file. Occasionally, we start an example with a ‘$’ +character to indicate a shell prompt, as seen above. +

+

You are encouraged to try the examples yourself, and to alter them to +better learn groff’s behavior. Our examples frequently need to +direct the formatter to set a line length (with ‘.ll’) that will +fit within the page margins of this manual. We mention this so that you +know why it is there before we discuss the ll request +formally.3 +

+ + +
+
+
+

+Next: Credits, Previous: Installation, Up: Introduction   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Copy-Mode.html b/doc/groff.html.node/Copy-Mode.html new file mode 100644 index 0000000..cc7de66 --- /dev/null +++ b/doc/groff.html.node/Copy-Mode.html @@ -0,0 +1,256 @@ + + + + + + +Copy Mode (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Writing Macros   [Contents][Index]

+
+
+

5.24.2 Copy Mode

+ + + + + + + + + +

When GNU troff processes certain requests, most importantly those +which define or append to a macro or string, it does so in copy +mode: it copies the characters of the definition into a dedicated +storage region, interpolating the escape sequences \n, \g, +\$, \*, \V, and \? normally; interpreting +\RET immediately; discarding comments \" and +\#; interpolating the current leader, escape, or tab character +with \a, \e, and \t, respectively; and storing all +other escape sequences in an encoded form. +

+ + +

The complement of copy mode—a roff formatter’s behavior when +not defining or appending to a macro, string, or diversion—where all +macros are interpolated, requests invoked, and valid escape sequences +processed immediately upon recognition, can be termed +interpretation mode. +

+
+
Escape sequence: \\
+
+

The escape character, \ by default, can escape itself. This +enables you to control whether a given \n, \g, \$, +\*, \V, or \? escape sequence is interpreted at the +time the macro containing it is defined, or later when the macro is +called.101 +

+
+
.nr x 20
+.de y
+.nr x 10
+\&\nx
+\&\\nx
+..
+.y
+    ⇒ 20 10
+
+ +

You can think of \\ as a “delayed” backslash; it is the escape +character followed by a backslash from which the escape character has +removed its special meaning. Consequently, ‘\\’ is not an escape +sequence in the usual sense. In any escape sequence ‘\X’ +that GNU troff does not recognize, the escape character is +ignored and X is output. An unrecognized escape sequence causes +a warning in category ‘escape’, with two exceptions—‘\\’ is +the first. +

+ + +
+
Escape sequence: \.
+
+

\. escapes the control character. It is similar to \\ in +that it isn’t a true escape sequence. It is used to permit nested macro +definitions to end without a named macro call to conclude them. Without +a syntax for escaping the control character, this would not be possible. +

+
+
.de m1
+foo
+.
+.  de m2
+bar
+\\..
+.
+..
+.m1
+.m2
+    ⇒ foo bar
+
+ +

The first backslash is consumed while the macro is read, and the second +is interpreted when macro m1 is called. +

+ +

roff documents should not use the \\ or \. +character sequences outside of copy mode; they serve only to obfuscate +the input. Use \e to represent the escape character, +\[rs] to obtain a backslash glyph, and \& before ‘.’ +and ‘'’ where GNU troff expects them as control characters +if you mean to use them literally (recall Requests and Macros). +

+

Macro definitions can be nested to arbitrary depth. The mechanics of +parsing the escape character have significant consequences for this +practice. +

+
+
.de M1
+\\$1
+.  de M2
+\\\\$1
+.    de M3
+\\\\\\\\$1
+\\\\..
+.    M3 hand.
+\\..
+.  M2 of
+..
+This understeer is getting
+.M1 out
+    ⇒ This understeer is getting out of hand.
+
+ +

Each escape character is interpreted twice—once in copy mode, when the +macro is defined, and once in interpretation mode, when the macro is +called. As seen above, this fact leads to exponential growth in the +quantity of escape characters required to delay interpolation of +\n, \g, \$, \*, \V, and \? at +each nesting level, which can be daunting. GNU troff offers a +solution. +

+
+
Escape sequence: \E
+
+

\E represents an escape character that is not interpreted in copy +mode. You can use it to ease the writing of nested macro definitions. +

+
+
.de M1
+.  nop \E$1
+.  de M2
+.    nop \E$1
+.    de M3
+.      nop \E$1
+\\\\..
+.    M3 better.
+\\..
+.  M2 bit
+..
+This vehicle handles
+.M1 a
+    ⇒ This vehicle handles a bit better.
+
+ +

Observe that because \. is not a true escape sequence, we can’t +use \E to keep ‘..’ from ending a macro definition +prematurely. If the multiplicity of backslashes complicates +maintenance, use end macros. +

+

\E is also convenient to define strings containing escape +sequences that need to work when used in copy mode (for example, as +macro arguments), or which will be interpolated at varying macro nesting +depths. We might define strings to begin and end superscripting +as follows.102 +

+
+
.ds { \v'-.9m\s'\En[.s]*7u/10u'+.7m'
+.ds } \v'-.7m\s0+.9m'
+
+ +

When the ec request is used to redefine the escape character, +\E also makes it easier to distinguish the semantics of an escape +character from the other meaning(s) its character might have. Consider +the use of an unusual escape character, ‘-’. +

+
+
.nr a 1
+.ec -
+.de xx
+--na
+..
+.xx
+    ⇒ -na
+
+ +

This result may surprise you; some people expect ‘1’ to be output +since register ‘a’ has clearly been defined with that value. What +has happened? The robotic replacement of ‘\’ with ‘-’ has led +us astray. You might recognize the sequence ‘--’ more readily with +the default escape character as ‘\-’, the special character escape +sequence for the minus sign glyph. +

+
+
.nr a 1
+.ec -
+.de xx
+-Ena
+..
+.xx
+    ⇒ 1
+
+
+ + + +
+
+
+

+Previous: Parameters, Up: Writing Macros   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Copying-This-Manual.html b/doc/groff.html.node/Copying-This-Manual.html new file mode 100644 index 0000000..47c4c3e --- /dev/null +++ b/doc/groff.html.node/Copying-This-Manual.html @@ -0,0 +1,534 @@ + + + + + + +Copying This Manual (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

Appendix A Copying This Manual

+ +
Version 1.3, 3 November 2008 +
+ +
+
Copyright © 2000-2018 Free Software Foundation, Inc.
+http://fsf.org/
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+ +
    +
  1. PREAMBLE + +

    The purpose of this License is to make a manual, textbook, or other +functional and useful document free in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. +

    +

    This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. +

    +

    We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. +

    +
  2. APPLICABILITY AND DEFINITIONS + +

    This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The “Document”, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. +

    +

    A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. +

    +

    A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document’s overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. +

    +

    The “Invariant Sections” are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. +

    +

    The “Cover Texts” are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. +

    +

    A “Transparent” copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not “Transparent” is called “Opaque”. +

    +

    Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input +format, SGML or XML using a publicly available +DTD, and standard-conforming simple HTML, +PostScript or PDF designed for human modification. Examples +of transparent image formats include PNG, XCF and +JPG. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, SGML or +XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML, +PostScript or PDF produced by some word processors for +output purposes only. +

    +

    The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work’s title, +preceding the beginning of the body of the text. +

    +

    The “publisher” means any person or entity that distributes copies +of the Document to the public. +

    +

    A section “Entitled XYZ” means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as “Acknowledgements”, +“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” +of such a section when you modify the Document means that it remains a +section “Entitled XYZ” according to this definition. +

    +

    The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. +

    +
  3. VERBATIM COPYING + +

    You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. +

    +

    You may also lend copies, under the same conditions stated above, and +you may publicly display copies. +

    +
  4. COPYING IN QUANTITY + +

    If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document’s license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. +

    +

    If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. +

    +

    If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. +

    +

    It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. +

    +
  5. MODIFICATIONS + +

    You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: +

    +
      +
    1. Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +
    2. List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +
    3. State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +
    4. Preserve all the copyright notices of the Document. + +
    5. Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +
    6. Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +
    7. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document’s license notice. + +
    8. Include an unaltered copy of this License. + +
    9. Preserve the section Entitled “History”, Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled “History” in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +
    10. Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the “History” section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +
    12. Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +
    13. Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + +
    14. Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + +
    15. Preserve any Warranty Disclaimers. +
    + +

    If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version’s license notice. +These titles must be distinct from any other section titles. +

    +

    You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. +

    +

    You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +

    +

    The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. +

    +
  6. COMBINING DOCUMENTS + +

    You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. +

    +

    The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. +

    +

    In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” +

    +
  7. COLLECTIONS OF DOCUMENTS + +

    You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. +

    +

    You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. +

    +
  8. AGGREGATION WITH INDEPENDENT WORKS + +

    A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an “aggregate” if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation’s users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. +

    +

    If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document’s Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. +

    +
  9. TRANSLATION + +

    Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. +

    +

    If a section in the Document is Entitled “Acknowledgements”, +“Dedications”, or “History”, the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. +

    +
  10. TERMINATION + +

    You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. +

    +

    However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. +

    +

    Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. +

    +

    Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. +

    +
  11. FUTURE REVISIONS OF THIS LICENSE + +

    The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. +

    +

    Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy’s public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. +

    +
  12. RELICENSING + +

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +“Massive Multiauthor Collaboration” (or “MMC”) contained in the +site means any set of copyrightable works thus published on the MMC +site. +

    +

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. +

    +

    “Incorporate” means to publish or republish a Document, in whole or +in part, as part of another Document. +

    +

    An MMC is “eligible for relicensing” if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. +

    +

    The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. +

    +
+ +

ADDENDUM: How to use this License for your documents

+ +

To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: +

+
+
  Copyright (C)  year  your name.
+  Permission is granted to copy, distribute and/or modify this document
+  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, no Front-Cover Texts, and no Back-Cover
+  Texts.  A copy of the license is included in the section entitled ``GNU
+  Free Documentation License''.
+
+ +

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with…Texts.” line with this: +

+
+
    with the Invariant Sections being list their titles, with
+    the Front-Cover Texts being list, and with the Back-Cover Texts
+    being list.
+
+ +

If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. +

+

If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. +

+ + + + + +
+
+
+

+Next: Request Index, Previous: Font Description File Format, Up: GNU troff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Credits.html b/doc/groff.html.node/Credits.html new file mode 100644 index 0000000..4f46327 --- /dev/null +++ b/doc/groff.html.node/Credits.html @@ -0,0 +1,58 @@ + + + + + + +Credits (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Introduction   [Contents][Index]

+
+
+

1.9 Credits

+ + +

We adapted portions of this manual from existing documents. James +Clark’s man pages were an essential resource; we have updated them in +parallel with the development of this manual. We based the tutorial for +macro users on Eric Allman’s introduction to his me macro package +(which we also provide, little altered from 4.4BSD). Larry Kollar +contributed much of the material on the ms macro package. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/DESC-File-Format.html b/doc/groff.html.node/DESC-File-Format.html new file mode 100644 index 0000000..11e1b73 --- /dev/null +++ b/doc/groff.html.node/DESC-File-Format.html @@ -0,0 +1,258 @@ + + + + + + +DESC File Format (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Device and Font Description Files   [Contents][Index]

+
+
+

6.2.1 DESC File Format

+ + + + +

The DESC file contains a series of directives; each begins a +line. Their order is not important, with two exceptions: (1) the +res directive must precede any papersize directive; and +(2) the charset directive must come last (if at all). If a +directive name is repeated, later entries in the file override previous +ones (except that the paper dimensions are computed based on the +res directive last seen when papersize is encountered). +Spaces and/or tabs separate words and are ignored at line boundaries. + + + +Comments start with the ‘#’ character and extend to the end of a +line. Empty lines are ignored. +

+
+
family fam
+

The default font family is fam. +

+
+
fonts n F1 … Fn
+

Fonts F1, …, Fn are mounted at font positions +m+1, …, m+n where m is the number of +styles (see below). This directive may extend over more than one +line. A font name of 0 causes no font to be mounted at the +corresponding position. +

+
+
hor n
+
+ + + + +

The horizontal motion quantum is n basic units. All +horizontal quantities are rounded to multiples of n. +

+
+
image_generator program
+
+ +

Use program to generate PNG images from PostScript input. Under +GNU/Linux, this is usually gs, but under other systems (notably +Cygwin) it might be set to another name. The grohtml driver uses +this directive. +

+
+
paperlength n
+

The vertical dimension of the output medium is n basic units +(deprecated: use papersize instead). +

+
+
papersize format-or-dimension-pair-or-file-name …
+

The dimensions of the output medium are as according to the +argument, which is either a standard paper format, a pair of dimensions, +or the name of a plain text file containing either of the foregoing. +

+

Recognized paper formats are the ISO and DIN formats +A0–A7, B0–B7, C0–C7, +D0–D7; the U.S. paper types letter, +legal, tabloid, ledger, statement, and +executive; and the envelope formats com10, monarch, +and DL. Matching is performed without regard for lettercase. +

+

Alternatively, the argument can be a custom paper format in the format +length,width (with no spaces before or after the +comma). Both length and width must have a unit appended; +valid units are ‘i’ for inches, ‘c’ for centimeters, ‘p’ +for points, and ‘P’ for picas. Example: ‘12c,235p’. An +argument that starts with a digit is always treated as a custom paper +format. +

+

Finally, the argument can be a file name (e.g., /etc/papersize); +if the file can be opened, the first line is read and a match attempted +against each of the other forms. No comment syntax is supported. +

+

More than one argument can be specified; +each is scanned in turn and the first valid paper specification used. +

+
+
paperwidth n
+

The horizontal dimension of the output medium is n basic +units (deprecated: use papersize instead). +

+
+
pass_filenames
+

Direct GNU troff to emit the name of the source file being +processed. This is achieved with the intermediate output command +‘x F’, which grohtml interprets. +

+
+
postpro program
+

Use program as the postprocessor. +

+
+
prepro program
+

Use program as a preprocessor. The html and xhtml +output devices use this directive. +

+
+
print program
+

Use program as a spooler program for printing. If omitted, the +-l and -L options of groff are ignored. +

+
+
res n
+
+ +

The device resolution is n basic units per inch. +

+
+
sizes s1 … sn 0
+

The device has fonts at s1, …, sn scaled points (see +below). The list of sizes must be terminated by 0. Each +si can also be a range of sizes m–n. The list can +extend over more than one line. +

+
+
sizescale n
+

A typographical point is subdivided into n scaled points. +The default is 1. See Using Fractional Type Sizes. +

+
+
styles S1 … Sm
+

The first m mounting positions are associated with styles +S1, …, Sm. +

+
+
tcommand
+

The postprocessor can handle the ‘t’ and ‘u’ intermediate +output commands. +

+
+
unicode
+

The output device supports the complete Unicode repertoire. This +directive is useful only for devices that produce character entities +instead of glyphs. +

+

If unicode is present, no charset section is required in +the font description files since the Unicode handling built into +groff is used. However, if there are entries in a font +description file’s charset section, they either override the +default mappings for those particular characters or add new mappings +(normally for composite characters). +

+

The utf8, html, and xhtml output devices use this +directive. +

+
+
unitwidth n
+

Quantities in the font description files are in basic units for fonts +whose type size is n scaled points. +

+
+
unscaled_charwidths
+

Make the font handling module always return unscaled character widths. +The grohtml driver uses this directive. +

+
+
use_charnames_in_special
+

GNU troff should encode special characters inside device control +commands; see Postprocessor Access. The grohtml driver +uses this directive. +

+
+
vert n
+
+ + + + +

The vertical motion quantum is n basic units. All vertical +quantities are rounded to multiples of n. +

+
+
charset
+

This line and everything following it in the file are ignored. It is +recognized for compatibility with other troff implementations. +In GNU troff, character set repertoire is described on a +per-font basis. +

+
+ + + + +

GNU troff recognizes but ignores the directives spare1, +spare2, and biggestfont. +

+

The res, unitwidth, fonts, and sizes lines +are mandatory. Directives not listed above are ignored by GNU +troff but may be used by postprocessors to obtain further +information about the device. +

+ +
+
+
+

+Next: Font Description File Format, Previous: Device and Font Description Files, Up: Device and Font Description Files   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Debugging.html b/doc/groff.html.node/Debugging.html new file mode 100644 index 0000000..594201c --- /dev/null +++ b/doc/groff.html.node/Debugging.html @@ -0,0 +1,317 @@ + + + + + + +Debugging (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.37 Debugging

+ + +

Standard troff voodoo, just put a power of two backslashes in +front of it until it works and if you still have problems add a \c. +— Ron Natalie +

+

GNU troff is not the easiest language to debug, in part thanks to +its design features of recursive interpolation and the use of +multi-stage pipeline processing in the surrounding system. Nevertheless +there exist several features useful for troubleshooting. +

+

Preprocessors use the lf request to preserve the identity of the +line numbers and names of input files. GNU troff emits a variety +of error diagnostics and supports several categories of warning; the +output of these can be selectively suppressed. A trace of the +formatter’s input processing stack can be emitted when errors or +warnings occur by means of GNU troff’s -b option, or +produced on demand with the backtrace request. The tm +and related requests can be used to emit customized diagnostic messages +or for instrumentation while troubleshooting. The ex and +ab requests cause early termination with successful and error +exit codes respectively, to halt further processing when continuing +would be fruitless. Examine the state of the formatter with requests +that write lists of defined names (macros, strings, and diversions), +environments, registers, and page location traps to the standard error +stream. +

+
+
Request: .lf line [file]
+
+ + + + + + +

Set the input line number (and, optionally, the file name) GNU +troff shall use for error and warning messages. line is +the input line number of the next line. Without an argument, the +request is ignored. +

+

lf’s primary purpose is to aid the debugging of documents that +undergo preprocessing. Programs like tbl that transform input +in their own languages into roff requests use it so that any +diagnostic messages emitted by troff correspond to the source +document. +

+ +
+
Request: .tm message
+
+
Request: .tm1 message
+
+
Request: .tmc message
+
+ + +

Send message, which consumes the remainder of the input line and +cannot contain special characters, to the standard error stream, +followed by a newline. Leading spaces in message are ignored. +

+

tm1 is similar, but recognizes and strips a leading neutral +double quote from message to allow the embedding of leading +spaces. +

+

tmc works as tm1, but does not append a newline. +

+ +
+
Request: .ab [message]
+
+ +

Write any message to the standard error stream (like tm) +and then abort GNU troff; that is, stop processing and terminate +with a failure status. +

+ +
+
Request: .ex
+
+ + +

Exit GNU troff; that is, stop processing and terminate with a +successful status. To stop processing only the current file, use the +nx request; see I/O. +

+ +

When doing something involved, it is useful to leave the debugging +statements in the code and have them turned on by a command-line flag. +

+
+
.if \n[DB] .tm debugging output
+
+ +

To activate such statements, use the -r option to set the +register. +

+
+
groff -rDB=1 file
+
+ +

If it is known in advance that there are many errors and no useful +output, GNU troff can be forced to suppress formatted output with +the -z option. +

+
+
Request: .pev
+
+ + +

Report the state of the current environment followed by that of all +other environments to the standard error stream. +

+ +
+
Request: .pm
+
+ + +

Report, to the standard error stream, the names of all defined macros, +strings, and diversions with their sizes in bytes. +

+ +
+
Request: .pnr
+
+ + +

Report the names and contents of all currently defined registers to the +standard error stream. +

+ +
+
Request: .ptr
+
+ + + + +

Report the names and positions of all page location traps to the +standard error stream. Empty slots in the list, where a trap has been +planted but subsequently (re)moved, are printed as well. +

+ +
+
Request: .fl
+
+ + + + +

Instruct gtroff to flush its output immediately. The intent is +for interactive use, but this behaviour is currently not implemented in +gtroff. Contrary to Unix troff, TTY output is sent to a +device driver also (grotty), making it non-trivial to communicate +interactively. +

+

This request causes a line break. +

+ +
+
Request: .backtrace
+
+ + +

Write the state of the input stack to the standard error stream. +

+

Consider the following in a file test. +

+
+
.de xxx
+.  backtrace
+..
+.de yyy
+.  xxx
+..
+.
+.yyy
+    error→ troff: backtrace: 'test':2: macro 'xxx'
+    error→ troff: backtrace: 'test':5: macro 'yyy'
+    error→ troff: backtrace: file 'test':8
+
+ +

The -b option of GNU troff causes a backtrace to be +generated on each error or warning. Some warnings have to be enabled; +See Warnings. +

+ +
+
Register: \n[slimit]
+
+ +

If greater than 0, sets the maximum quantity of objects on GNU +troff’s internal input stack. If less than or equal to 0, +there is no limit: recursion can continue until program memory is +exhausted. The default is 1,000. +

+ +
+
Request: .warnscale su
+
+

Set the scaling unit used in certain warnings to su, which can take the values ‘u’, ‘i’, ‘c’, +‘p’, and ‘P’. The default is ‘i’. +

+ +
+
Request: .spreadwarn [limit]
+
+

Emit a break warning if the additional space inserted for each +space between words in an output line adjusted to both margins with +‘.ad b’ is larger than or equal to limit. A negative +value is treated as zero; an absent argument toggles the warning on and +off without changing limit. The default scaling unit is ‘m’. +At startup, spreadwarn is inactive and limit is 3m. +

+

For example, +

+
+
.spreadwarn 0.2m
+
+ +

causes a warning if break warnings are not suppressed and +gtroff must add 0.2m or more for each inter-word space in a +line. See Warnings. +

+ + +

GNU troff has command-line options for reporting warnings +(-w) and backtraces (-b) when a warning or an error +occurs. +

+
+
Request: .warn [n]
+
+
Register: \n[.warn]
+
+ +

Select the categories, or “types”, of reported warnings. +n is the sum of the numeric codes associated with each +warning category that is to be enabled; all other categories are +disabled. The categories and their associated codes are listed in +Warnings. For example, ‘.warn 0’ disables all warnings, and +‘.warn 1’ disables all warnings except those about missing glyphs. +If no argument is given, all warning categories are enabled. +

+

The read-only register .warn contains the sum of the numeric +codes of enabled warning categories. +

+ + + + +
+
+
+

+Next: Implementation Differences, Previous: gtroff Internals, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Default-Units.html b/doc/groff.html.node/Default-Units.html new file mode 100644 index 0000000..168c5cc --- /dev/null +++ b/doc/groff.html.node/Default-Units.html @@ -0,0 +1,87 @@ + + + + + + +Default Units (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Measurements   [Contents][Index]

+
+
+

5.3.2 Default Units

+ + + +

A general-purpose register (one created or updated with the nr +request; see see Registers) is implicitly dimensionless, or reckoned +in basic units if interpreted in a measurement context. But it is +convenient for many requests and escape sequences to infer a scaling +unit for an argument if none is specified. An explicit scaling unit +(not after a closing parenthesis) can override an undesirable default. +Effectively, the default unit is suffixed to the expression if a scaling +unit is not already present. GNU troff’s use of integer +arithmetic should also be kept in mind (see Numeric Expressions). +

+

The ll request interprets its argument in ems by default. +Consider several attempts to set a line length of 3.5 inches when +the type size is 10 points on a terminal device with a resolution +of 240 basic units and horizontal motion quantum of 24. Some +expressions become zero; the request clamps them to that quantum. +

+
+
.ll 3.5i      \" 3.5i (= 840u)
+.ll 7/2       \" 7u/2u -> 3u -> 3m -> 0, clamped to 24u
+.ll (7 / 2)u  \" 7u/2u -> as above
+.ll 7/2i      \" 7u/2i -> 7u/480u -> 0 -> as above
+.ll 7i/2      \" 7i/2u -> 1680u/2m -> 1680u/24u -> 35u
+.ll 7i/2u     \" 3.5i (= 840u)
+
+ + +

The safest way to specify measurements is to attach a scaling unit. To +multiply or divide by a dimensionless quantity, use ‘u’ as its +scaling unit. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Deferring-Output.html b/doc/groff.html.node/Deferring-Output.html new file mode 100644 index 0000000..81ab360 --- /dev/null +++ b/doc/groff.html.node/Deferring-Output.html @@ -0,0 +1,106 @@ + + + + + + +Deferring Output (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.27 Deferring Output

+ + + + + +

A few roff language elements are generally not used in simple +documents, but arise as page layouts become more sophisticated and +demanding. Environments collect formatting parameters like line +length and typeface. A diversion stores formatted output for +later use. A trap is a condition on the input or output, tested +automatically by the formatter, that is associated with a macro, causing +it to be called when that condition is fulfilled. +

+

Footnote support often exercises all three of the foregoing features. A +simple implementation might work as follows. A pair of macros is +defined: one starts a footnote and the other ends it. The author calls +the first macro where a footnote marker is desired. The macro +establishes a diversion so that the footnote text is collected at the +place in the body text where its corresponding marker appears. An +environment is created for the footnote so that it is set at a smaller +typeface. The footnote text is formatted in the diversion using that +environment, but it does not yet appear in the output. The document +author calls the footnote end macro, which returns to the previous +environment and ends the diversion. Later, after much more body text in +the document, a trap, set a small distance above the page bottom, is +sprung. The macro called by the trap draws a line across the page and +emits the stored diversion. Thus, the footnote is rendered. +

+

Diversions and traps make the text formatting process non-linear. Let +us imagine a set of text lines or paragraphs labelled ‘A’, +‘B’, and so on. If we set up a trap that produces text ‘T’ +(as a page footer, say), and we also use a diversion to store the +formatted text ‘D’, then a document with input text in the order +‘A B C D E F’ might render as ‘A B C E T F’. The diversion +‘D’ will never be output if we do not call for it. +

+

Environments of themselves are not a source of non-linearity in document +formatting: environment switches have immediate effect. One could +always write a macro to change as many formatting parameters as desired +with a single convenient call. But because diversions can be nested and +macros called by traps that are sprung by other trap-called macros, they +may be called upon in varying contexts. For example, consider a page +header that is always to be set in Helvetica. A document that uses +Times for most of its body text, but Courier for displayed code +examples, poses a challenge if a page break occurs in the middle of a +code display; if the header trap assumes that the “previous font” is +always Times, the rest of the example will be formatted in the wrong +typeface. One could carefully save all formatting parameters upon +entering the trap and restore them upon leaving it, but this is verbose, +error-prone, and not future-proof as the groff language develops. +Environments save us considerable effort. +

+ +
+
+
+

+Next: Traps, Previous: Drawing Geometric Objects, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Delimiters.html b/doc/groff.html.node/Delimiters.html new file mode 100644 index 0000000..fa117db --- /dev/null +++ b/doc/groff.html.node/Delimiters.html @@ -0,0 +1,233 @@ + + + + + + +Delimiters (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Formatter Instructions   [Contents][Index]

+
+
+

5.6.5 Delimiters

+ + + + + + + +

Some escape sequences that require parameters use delimiters. The +neutral apostrophe ' is a popular choice and shown in this +document. The neutral double quote " is also commonly seen. +Letters, numerals, and leaders can be used. Punctuation characters +are likely better choices, except for those defined as infix operators +in numeric expressions; see below. +

+
+
\l'1.5i\[bu]' \" draw 1.5 inches of bullet glyphs
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

The following escape sequences don’t take arguments and thus are allowed +as delimiters: +\SP, \%, \|, \^, \{, +\}, \', \`, \-, \_, \!, +\?, \), \/, \,, \&, \:, +\~, \0, \a, \c, \d, \e, +\E, \p, \r, \t, and \u. However, +using them this way is discouraged; they can make the input confusing to +read. +

+ + + + + + + +

A few escape sequences, +\A, +\b, +\o, +\w, +\X, +and \Z, accept a newline as a delimiter. Newlines that serve +as delimiters continue to be recognized as input line terminators. +

+
+
A caf\o
+e\(aa
+in Paris
+    ⇒ A café in Paris
+
+ +

Use of newlines as delimiters in escape sequences is also discouraged. +

+ + + + + + + + + + + +

Finally, the escape sequences \D, \h, \H, +\l, \L, \N, \R, \s, \S, +\v, and \x prohibit many delimiters. +

+
    +
  • + + + + +the numerals 0-9 and the decimal point . + +
  • + + + + + + + + + + + + +the (single-character) operators ‘+-/*%<>=&:()’ + +
  • + +the space and tab characters + +
  • + + + + + + + + + + + + +any escape sequences other than \%, \:, \{, +\}, \', \`, \-, \_, \!, +\/, \c, \e, and \p +
+ +

Delimiter syntax is complex and flexible primarily for historical +reasons; the foregoing restrictions need be kept in mind mainly when +using groff in AT&T compatibility mode. GNU +troff keeps track of the nesting depth of escape sequence +interpolations, so the only characters you need to avoid using as +delimiters are those that appear in the arguments you input, not any +that result from interpolation. Typically, ' works fine. +See Implementation Differences. +

+
+
$ groff -Tps
+.de Mw
+.  nr wd \w'\\$1'
+.  tm "\\$1" is \\n(wd units wide.
+..
+.Mw Wet'suwet'en
+.Mw Wet+200i
+.cp 1 \" turn on compatibility mode
+.Mw Wet'suwet'en
+.Mw Wet'
+.Mw Wet+200i
+    error→ "Wet'suwet'en" is 54740 units wide.
+    error→ "Wet'+200i" is 42610 units wide.
+    error→ "Wet'suwet'en" is 15860 units wide.
+    error→ "Wet'" is 15860 units wide.
+    error→ "Wet'+200i" is 14415860 units wide.
+
+ +

We see here that in compatibility mode, the part of the argument after +the ' delimiter escapes from its context and, if nefariously +crafted, influences the computation of the wd register’s value in +a surprising way. +

+
+
+
+

+Previous: Using Escape Sequences, Up: Formatter Instructions   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Device-Control-Commands.html b/doc/groff.html.node/Device-Control-Commands.html new file mode 100644 index 0000000..9d56288 --- /dev/null +++ b/doc/groff.html.node/Device-Control-Commands.html @@ -0,0 +1,185 @@ + + + + + + +Device Control Commands (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Command Reference   [Contents][Index]

+
+
+

6.1.2.4 Device Control Commands

+ +

Each device control command starts with the letter ‘x’, followed by +a space character (optional or arbitrary space or tab in gtroff) +and a subcommand letter or word; each argument (if any) must be preceded +by a syntactical space. All ‘x’ commands are terminated by a +syntactical line break; no device control command can be followed by +another command on the same line (except a comment). +

+

The subcommand is basically a single letter, but to increase +readability, it can be written as a word, i.e., an arbitrary sequence of +characters terminated by the next tab, space, or newline character. All +characters of the subcommand word but the first are simply ignored. For +example, gtroff outputs the initialization command ‘x i’ +as ‘x init’ and the resolution command ‘x r’ as +‘x res’. +

+

In the following, the syntax element ‹line break› means a +syntactical line break (see Separation). +

+
+
xF name‹line break›
+

The ‘F’ stands for Filename. +

+

Use name as the intended name for the current file in error +reports. This is useful for remembering the original file name when +gtroff uses an internal piping mechanism. The input file is not +changed by this command. This command is a gtroff extension. +

+
+
xf n s‹line break›
+

The ‘f’ stands for font. +

+

Mount font position n (a non-negative integer) with font +named s (a text word). See Font Positions. +

+
+
xH n‹line break›
+

The ‘H’ stands for Height. +

+

Set glyph height to n (a positive integer in scaled points +‘z’). AT&T troff uses the unit points (‘p’) +instead. See Output Language Compatibility. +

+
+
xi‹line break›
+

The ‘i’ stands for init. +

+

Initialize device. This is the third command of the prologue. +

+
+
xp‹line break›
+

The ‘p’ stands for pause. +

+

Parsed but ignored. The AT&T troff manual documents +this command as +

+
+
pause device, can be restarted
+
+ +

but GNU troff output drivers do nothing with this command. +

+
+
xr n h v‹line break›
+

The ‘r’ stands for resolution. +

+

Resolution is n, while h is the minimal horizontal +motion, and v the minimal vertical motion possible with this +device; all arguments are positive integers in basic units ‘u’ per +inch. This is the second command of the prologue. +

+
+
xS n‹line break›
+

The ‘S’ stands for Slant. +

+

Set slant to n (an integer in basic units ‘u’). +

+
+
xs‹line break›
+

The ‘s’ stands for stop. +

+

Terminates the processing of the current file; issued as the last +command of any intermediate troff output. +

+
+
xt‹line break›
+

The ‘t’ stands for trailer. +

+

Generate trailer information, if any. In GNU troff, this is +ignored. +

+
+
xT xxx‹line break›
+

The ‘T’ stands for Typesetter. +

+

Set the name of the output driver to xxx, a sequence of +non-whitespace characters terminated by whitespace. The possible names +correspond to those of groff’s -T option. This is the +first command of the prologue. +

+
+
xu n‹line break›
+

The ‘u’ stands for underline. +

+

Configure underlining of spaces. If n is 1, start +underlining of spaces; if n is 0, stop underlining of spaces. +This is needed for the cu request in nroff mode and is +ignored otherwise. This command is a gtroff extension. +

+
+
xX anything‹line break›
+

The ‘x’ stands for X-escape. +

+

Send string anything uninterpreted to the device. If the line +following this command starts with a ‘+’ character this line is +interpreted as a continuation line in the following sense. The ‘+’ +is ignored, but a newline character is sent instead to the device, the +rest of the line is sent uninterpreted. The same applies to all +following lines until the first character of a line is not a ‘+’ +character. This command is generated by the gtroff escape +sequence \X. The line-continuing feature is a gtroff +extension. +

+
+ +
+
+
+

+Next: Obsolete Command, Previous: Graphics Commands, Up: Command Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Device-and-Font-Description-Files.html b/doc/groff.html.node/Device-and-Font-Description-Files.html new file mode 100644 index 0000000..b935830 --- /dev/null +++ b/doc/groff.html.node/Device-and-Font-Description-Files.html @@ -0,0 +1,77 @@ + + + + + + +Device and Font Description Files (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: File Formats   [Contents][Index]

+
+
+

6.2 Device and Font Description Files

+ + + +

The groff font and output device description formats are slight +extensions of those used by AT&T device-independent +troff. In distinction to the AT&T implementation, +groff lacks a binary format; all files are text +files.125 The device and font description files for a device name +are stored in a devname directory. The device description +file is called DESC, and, for each font supported by the device, +a font description file is called f, where +f is usually an abbreviation of a font’s name and/or style. +For example, the ps (PostScript) device has groff font +description files for Times roman (TR) and Zapf Chancery Medium +italic (ZCMI), among many others, while the utf8 device +(for terminal emulators) has only font descriptions for the roman, +italic, bold, and bold-italic styles (R, I, B, and +BI, respectively). +

+

Device and font description files are read both by the formatter, GNU +troff, and by output drivers. The programs delegate these files’ +processing to an internal library, libgroff, ensuring their +consistent interpretation. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/Differences-from-AT_0026T-ms.html b/doc/groff.html.node/Differences-from-AT_0026T-ms.html new file mode 100644 index 0000000..6d45741 --- /dev/null +++ b/doc/groff.html.node/Differences-from-AT_0026T-ms.html @@ -0,0 +1,171 @@ + + + + + + +Differences from AT&T ms (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+
+

4.6.7 Differences from AT&T ms

+ + + +

The groff ms macros are an independent reimplementation, +using no AT&T code. Since they take advantage of the extended +features of groff, they cannot be used with AT&T +troff. groff ms supports features described above +as Berkeley and Tenth Edition Research Unix extensions, and adds several +of its own. +

+
    +
  • The internals of groff ms differ from the internals of +AT&T ms. Documents that depend upon implementation +details of AT&T ms may not format properly with +groff ms. Such details include macros whose function was +not documented in the AT&T ms +manual.14 + +
  • The error-handling policy of groff ms is to detect and +report errors, rather than to ignore them silently. + +
  • Tenth Edition Research Unix supported P1/P2 macros to bracket code +examples; groff ms does not. + +
  • groff ms does not work in GNU troff’s +AT&T compatibility mode. If loaded when that mode is enabled, +it aborts processing with a diagnostic message. + +
  • Multiple line spacing is not supported. Use a larger vertical spacing +instead. + +
  • groff ms uses the same header and footer defaults in both +nroff and troff modes as AT&T ms does in +troff mode; AT&T’s default in nroff mode is to +put the date, in U.S. traditional format (e.g., “January 1, 2021”), +in the center footer (the CF string). + +
  • Many groff ms macros, including those for paragraphs, +headings, and displays, cause a reset of paragraph rendering parameters, +and may change the indentation; they do so not by incrementing or +decrementing it, but by setting it absolutely. This can cause problems +for documents that define additional macros of their own that try to +manipulate indentation. Use the ms RS and RE +macros instead of the in request. + +
  • + +AT&T ms interpreted the values of the registers +PS and VS in points, and did not support the use of +scaling units with them. groff ms interprets values of +the registers PS, VS, FPS, and FVS equal to +or larger than 1,000 (one thousand) as decimal fractions multiplied +by 1,000.15 This threshold makes use of a +scaling unit with these parameters practical for high-resolution +devices while preserving backward compatibility. It also permits +expression of non-integral type sizes. For example, ‘groff +-rPS=10.5p’ at the shell prompt is equivalent to placing ‘.nr PS +10.5p’ at the beginning of the document. + +
  • AT&T ms’s AU macro supported arguments used with +some document types; groff ms does not. + +
  • Right-aligned displays are available. The AT&T ms +manual observes that “it is tempting to assume that ‘.DS R’ will +right adjust lines, but it doesn’t work”. In groff ms, +it does. + +
  • To make groff ms use the default page offset (which also +specifies the left margin), the PO register must stay undefined +until the first ms macro is called. + +

    This implies that ‘\n[PO]’ should not be used early in the +document, unless it is changed also: accessing an undefined register +automatically defines it. +

    +
  • groff ms supports the PN register, but it is not +necessary; you can access the page number via the usual % +register and invoke the af request to assign a different format +to it if desired.16 + +
  • The AT&T ms manual documents registers CW and +GW as setting the default column width and “intercolumn gap”, +respectively, and which applied when MC was called with fewer +than two arguments. groff ms instead treats MC +without arguments as synonymous with 2C; there is thus no +occasion for a default column width register. Further, the MINGW +register and the second argument to MC specify a minimum +space between columns, not the fixed gutter width of AT&T +ms. + +
  • The AT&T ms manual did not document the QI +register; Berkeley and groff ms do. +
+ +
+
Register: \n[GS]
+
+

The register GS is set to 1 by the groff ms +macros, but is not used by the AT&T ms package. +Documents that need to determine whether they are being formatted with +groff ms or another implementation should test this +register. +

+ + + + +
+
+
+

+Next: Naming Conventions, Previous: Page layout, Up: ms   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Displays-and-Keeps.html b/doc/groff.html.node/Displays-and-Keeps.html new file mode 100644 index 0000000..9d8f2b0 --- /dev/null +++ b/doc/groff.html.node/Displays-and-Keeps.html @@ -0,0 +1,74 @@ + + + + + + +Displays and Keeps (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.5 Displays and Keeps

+ + +

Displays are sections of text set off from the surrounding +material (typically paragraphs), often differing in indentation, and/or +spacing. Tables, block quotations, and figures are displayed. +Equations and code examples, when not much shorter than an output line, +often are. Lists may or may not be. Packages for setting man pages +support example displays but not keeps. +

+ +

A keep is a group of output lines, often a display, that is +formatted on a single page if possible; it causes a page break to happen +early so as to not interrupt the kept material. +

+ + +

Floating keeps can move, or “float”, relative to the text +around them in the input. They are useful for displays that are +captioned and referred to by name, as with “See figure 3”. +Depending on the package, a floating keep appears at the bottom of the +current page if it fits, and at the top of the next otherwise. +Alternatively, floating keeps might be deferred to the end of a section. +Using a floating keep can avoid the large vertical spaces that may +precede a tall keep of the ordinary sort when it won’t fit on the page. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Diversion-Traps.html b/doc/groff.html.node/Diversion-Traps.html new file mode 100644 index 0000000..4c924e7 --- /dev/null +++ b/doc/groff.html.node/Diversion-Traps.html @@ -0,0 +1,79 @@ + + + + + + +Diversion Traps (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Vertical Position Traps   [Contents][Index]

+
+
+

5.28.1.3 Diversion Traps

+ + + +

A diversion is not formatted in the context of a page, so it lacks page +location traps; instead it can have a diversion trap. There can +exist at most one such vertical position trap per diversion. +

+
+
Request: .dt [dist name]
+
+ + + + +

Set a trap within a diversion at location dist, which is +interpreted relative to diversion rather than page boundaries. If invoked with +fewer than two arguments, any diversion trap in the current diversion is +removed. The register .t works within diversions. It is an +error to invoke dt in the top-level diversion. +See Diversions. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Diversions.html b/doc/groff.html.node/Diversions.html new file mode 100644 index 0000000..c0dc8e9 --- /dev/null +++ b/doc/groff.html.node/Diversions.html @@ -0,0 +1,394 @@ + + + + + + +Diversions (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.29 Diversions

+ + +

In roff systems it is possible to format text as if for output, +but instead of writing it immediately, one can divert the +formatted text into a named storage area. It is retrieved later by +specifying its name after a control character. The same name space is +used for such diversions as for strings and macros; see +Identifiers. Such text is sometimes said to be “stored in a +macro”, but this coinage obscures the important distinction between +macros and strings on one hand and diversions on the other; the former +store unformatted input text, and the latter capture +formatted output. Diversions also do not interpret arguments. +Applications of diversions include “keeps” (preventing a page break +from occurring at an inconvenient place by forcing a set of output lines +to be set as a group), footnotes, tables of contents, and indices. + + +For orthogonality it is said that GNU troff is in the +top-level diversion if no diversion is active (that is, formatted +output is being “diverted” immediately to the output device). +

+

Dereferencing an undefined diversion will create an empty one of that +name and cause a warning in category ‘mac’ to be emitted. +See Warnings, for information about the enablement and suppression of +warnings. A diversion does not exist for the purpose of testing with +the d conditional operator until its initial definition ends +(see Operators in Conditionals). The following requests are used to +create and alter diversions. +

+
+
Request: .di [name]
+
+
Request: .da [name]
+
+ + + + + + +

Start collecting formatted output in a diversion called name. The +da request appends to a diversion called name, creating it +if necessary. If name already exists as an alias, the target of +the alias is replaced or appended to; recall Strings. The pending +output line is diverted as well. Switching to another environment (with +the ev request) before invoking di or da avoids +including any pending output line in the diversion; see +Environments. +

+

Invoking di or da without an argument stops diverting +output to the diversion named by the most recent corresponding request. +If di or da is called without an argument when there is no +current diversion, a warning in category ‘di’ is produced. +See Warnings, for information about the enablement and suppression +of warnings. +

+
+
Before the diversion.
+.di yyy
+In the diversion.
+.br
+.di
+After the diversion.
+.br
+    ⇒ After the diversion.
+.yyy
+    ⇒ Before the diversion.  In the diversion.
+
+
+ + +

GNU troff supports box requests to exclude a partially +collected line from a diversion, as this is often desirable. +

+
+
Request: .box [name]
+
+
Request: .boxa [name]
+
+

Divert (or append) output to name, similarly to the di and +da requests, respectively. Any pending output line is not +included in the diversion. Without an argument, stop diverting output; +any pending output line inside the diversion is discarded. +

+
+
Before the box.
+.box xxx
+In the box.
+.br
+Hidden treasure.
+.box
+After the box.
+.br
+    ⇒ Before the box.  After the box.
+.xxx
+    ⇒ In the box.
+
+
+ +

Apart from pending output line inclusion and the request names that +populate them, boxes are handled exactly as diversions are. All of the +following groff language elements can be used with them +interchangeably. +

+
+
Register: \n[.z]
+
+
Register: \n[.d]
+
+ + + + + + + +

Diversions may be nested. The read-only string-valued register +.z contains the name of the current diversion. The read-only +register .d contains the current vertical place in the diversion. +If the input text is not being diverted, .d reports the same +location as the register nl. +

+ +
+
Register: \n[.h]
+
+ + + + +

The read-only register .h stores the high-water mark on the +current page or in the current diversion. It corresponds to the text +baseline of the lowest line on the page.113 +

+
+
.tm .h==\n[.h], nl==\n[nl]
+    ⇒ .h==0, nl==-1
+This is a test.
+.br
+.sp 2
+.tm .h==\n[.h], nl==\n[nl]
+    ⇒ .h==40, nl==120
+
+ + + +

As implied by the example, vertical motion does not produce text +baselines and thus does not increase the value interpolated by +‘\n[.h]’. +

+ +
+
Register: \n[dn]
+
+
Register: \n[dl]
+
+ + + + +

After completing a diversion, the writable registers dn and +dl contain its vertical and horizontal sizes. Only the lines +just processed are counted: for the computation of dn and +dl, the requests da and boxa are handled as if +di and box had been used, respectively—lines that have +been already stored in the diversion (box) are not taken into account. +

+
+
.\" Center text both horizontally and vertically.
+.\" Macro .(c starts centering mode; .)c terminates it.
+.
+.\" Disable the escape character with .eo so that we
+.\" don't have to double backslashes on the "\n"s.
+.eo
+.de (c
+.  br
+.  ev (c
+.  evc 0
+.  in 0
+.  nf
+.  di @c
+..
+
+
+
.de )c
+.  br
+.  ev
+.  di
+.  nr @s (((\n[.t]u - \n[dn]u) / 2u) - 1v)
+.  sp \n[@s]u
+.  ce 1000
+.  @c
+.  ce 0
+.  sp \n[@s]u
+.  br
+.  fi
+.  rr @s
+.  rm @c
+..
+.ec
+
+
+ +
+
Escape sequence: \!anything
+
+
Escape sequence: \?anything\?
+
+ + +

Transparently embed anything into the current diversion, +preventing requests, macro calls, and escape sequences from being +interpreted when read into a diversion. This is useful for preventing +them from taking effect until the diverted text is actually output. The +\! escape sequence transparently embeds input up to and including +the end of the line. The \? escape sequence transparently embeds +input until its own next occurrence. +

+ + + + + + +

anything may not contain newlines; use \! by itself to +embed newlines in a diversion. The escape sequence \? is also +recognized in copy mode and turned into a single internal code; it is +this code that terminates anything. Thus the following example +prints 4. +

+
+
.nr x 1
+.nf
+.di d
+\?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
+.di
+.nr x 2
+.di e
+.d
+.di
+.nr x 3
+.di f
+.e
+.di
+.nr x 4
+.f
+
+ +

Both escape sequences read the data in copy mode. +

+ + + +

If \! is used in the top-level diversion, its argument is +directly embedded into GNU troff’s intermediate output. This can +be used, for example, to control a postprocessor that processes the data +before it is sent to an output driver. +

+ + + +

The \? escape used in the top-level diversion produces no output +at all; its argument is simply ignored. +

+ + + + + + +
+
Request: .output contents
+
+

Emit contents directly to GNU troff’s intermediate output +(subject to copy mode interpretation); this is similar to \! used +at the top level. An initial neutral double quote in contents is +stripped to allow embedding of leading spaces. +

+

This request can’t be used before the first page has started—if you +get an error, simply insert .br before the output request. +

+

Use with caution! It is normally only needed for mark-up used by a +postprocessor that does something with the output before sending it to +the output device, filtering out contents again. +

+ +
+
Request: .asciify div
+
+ + + +

Unformat the diversion div in a way such that Unicode basic +Latin (ASCII) characters, characters translated with the +trin request, space characters, and some escape sequences, that +were formatted and diverted into div are treated like ordinary +input characters when div is reread. Doing so can be useful in +conjunction with the writem request. asciify can be also +used for gross hacks; for example, the following sets +register n to 1. +

+
+
.tr @.
+.di x
+@nr n 1
+.br
+.di
+.tr @@
+.asciify x
+.x
+
+ +

asciify cannot return all items in a diversion to their source +equivalent: nodes such as those produced by the \N escape +sequence will remain nodes, so the result cannot be guaranteed to be a +pure string. See Copy Mode. Glyph parameters such as the type face +and size are not preserved; use unformat to achieve that. +

+ +
+
Request: .unformat div
+
+

Like asciify, unformat the diversion div. However, +unformat handles only tabs and spaces between words, the latter +usually arising from spaces or newlines in the input. Tabs are treated +as input tokens, and spaces become adjustable again. The vertical sizes +of lines are not preserved, but glyph information (font, type size, +space width, and so on) is retained. +

+ + + +
+
+
+

+Next: Punning Names, Previous: Traps, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Document-Formats.html b/doc/groff.html.node/Document-Formats.html new file mode 100644 index 0000000..9079d67 --- /dev/null +++ b/doc/groff.html.node/Document-Formats.html @@ -0,0 +1,57 @@ + + + + + + +Document Formats (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.9 Document Formats

+ + +

Some macro packages supply stock configurations of certain documents, +like business letters and memoranda. These often also have provision +for a cover sheet, which may be rigid in its format. With +these features, it is even more important to use the package’s macros in +preference to the formatter requests presented earlier, where possible. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Document-Parts.html b/doc/groff.html.node/Document-Parts.html new file mode 100644 index 0000000..7b83511 --- /dev/null +++ b/doc/groff.html.node/Document-Parts.html @@ -0,0 +1,84 @@ + + + + + + +Document Parts (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Language Concepts   [Contents][Index]

+
+
+

6.1.1.3 Document Parts

+ +

A correct intermediate output document consists of two parts, the +prologue and the body. +

+

The task of the prologue is to set the general device parameters using +three exactly specified commands. gtroff’s prologue is +guaranteed to consist of the following three lines (in that order): +

+
+
x T device
+x res n h v
+x init
+
+ +

with the arguments set as outlined in Device Control Commands. +The parser for the intermediate output format is able to interpret +additional whitespace and comments as well even in the prologue. +

+

The body is the main section for processing the document data. +Syntactically, it is a sequence of any commands different from the ones +used in the prologue. Processing is terminated as soon as the first +‘x stop’ command is encountered; the last line of any +gtroff intermediate output always contains such a command. +

+

Semantically, the body is page oriented. A new page is started by a +‘p’ command. Positioning, writing, and drawing commands are always +done within the current page, so they cannot occur before the first +‘p’ command. Absolute positioning (by the ‘H’ and ‘V’ +commands) is done relative to the current page; all other positioning is +done relative to the current location within this page. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Drawing-Geometric-Objects.html b/doc/groff.html.node/Drawing-Geometric-Objects.html new file mode 100644 index 0000000..fa0732f --- /dev/null +++ b/doc/groff.html.node/Drawing-Geometric-Objects.html @@ -0,0 +1,361 @@ + + + + + + +Drawing Geometric Objects (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.26 Drawing Geometric Objects

+ + + +

A few of the formatter’s escape sequences draw lines and other geometric +objects. Combined with each other and with page motion commands +(see Page Motions), a wide variety of figures is possible. For +complex drawings, these operations can be cumbersome; the preprocessors +gpic or ggrn are typically used instead. +

+

The \l and \L escape sequences draw horizontal and +vertical sequences of glyphs, respectively. Even the simplest of +output devices supports them. +

+
+
Escape sequence: \l'l'
+
+
Escape sequence: \l'lc'
+
+ + +

Draw a horizontal line of length l from the drawing position. +Rightward motion is positive. Afterward, the drawing position is at the +right end of the line. The default scaling unit is ‘m’. +

+ + + + +

The optional second parameter c is a character with which to +draw the line. The default is the baseline rule special character, +\[ru]. +

+ + +

If c is a valid scaling unit, put \& after l to +disambiguate the input. +

+
+
.de textbox
+\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]'
+..
+
+ +

The foregoing outputs a box rule (a vertical line), the text +argument(s), and another box rule. We employ the boundary-relative +motion operator ‘|’. Finally, the line-drawing escape sequences +draw a radical extender (a form of overline) and an underline from the +drawing position to the position coresponding to beginning of the +input line. The drawing position returns to just after the +right-hand box rule because the lengths of the drawn lines are negative, +as noted above. +

+ +
+
Escape sequence: \L'l'
+
+
Escape sequence: \L'lc'
+
+ + + + + + +

Draw a vertical line of length l from the drawing position. +Downward motion is positive. The default scaling unit is ‘v’. The +default character is the box rule, \[br]. As with vertical +motion escape sequences, text processing continues where the line ends. +\L is otherwise similar to \l. +

+
+
$ nroff <<EOF
+This is a \L'3v'test.
+EOF
+    ⇒ This is a
+    ⇒           |
+    ⇒           |
+    ⇒           |test.
+
+ +

When writing text, the drawing position is at the text baseline; recall +Page Geometry. +

+ +

The \D escape sequence provides drawing commands that +direct the output device to render geometrical objects rather than +glyphs. Specific devices may support only a subset, or may feature +additional ones; consult the man page for the output driver in use. +Terminal devices in particular implement almost none. See Graphics Commands. +

+

Rendering starts at the drawing position; when finished, the drawing +position is left at the rightmost point of the object, even for closed +figures, except where noted. GNU troff draws stroked (outlined) +objects with the stroke color, and shades filled ones with the fill +color. See Colors. Coordinates h and v are horizontal +and vertical motions relative to the drawing position or previous point +in the command. The default scaling unit for horizontal measurements +(and diameters of circles) is ‘m’; for vertical ones, ‘v’. +

+

Circles, ellipses, and polygons can be drawn filled or stroked. These +are independent properties; if you want a filled, stroked figure, you +must draw the same figure twice using each drawing command. A filled +figure is always smaller than an outlined one because the former is +drawn only within its defined area, whereas strokes have a line +thickness (set with ‘\D't'’). +

+
+
\h'1i'\v'1i'\
+\# increase line thickness
+\Z'\D't 5p''\
+\# draw stroked (unfilled) polygon
+\Z'\D'p 3 3 -6 0''\
+\# draw filled (solid) polygon
+\Z'\D'P 3 3 -6 0''
+
+ +
+
Escape sequence: \D'command argument …'
+
+

Drawing command escape sequence parameters begin with an ordinary +character, command, selecting the type of object to be drawn, +followed by arguments whose meaning is determined by +command. +

+
+
\D'~ h1 v1 … hn vn'
+
+

Draw a B-spline to each point in sequence, leaving the drawing position +at (hn, vn). +

+
+
\D'a hc vc h v'
+
+

Draw a circular arc centered at (hc, vc) counterclockwise +from the drawing position to a point (h, v) relative to the +center. 105 +

+
+
\D'c d'
+
+ + + + +

Draw a circle of diameter d with its leftmost point at the drawing +position. +

+
+
\D'C d'
+
+ + + + +

As ‘\D'C …'’, but the circle is filled. +

+
+
\D'e h v'
+
+ + + + +

Draw an ellipse of width h and height v with its leftmost +point at the drawing position. +

+
+
\D'E x y'
+
+ + + + +

As ‘\D'e …'’, but the ellipse is filled. +

+
+
\D'l dx dy'
+
+

Draw line from the drawing position to (h, v). +

+

The following is a macro for drawing a box around a text argument; for +simplicity, the box margin is a fixed at 0.2m. +

+
+
.de TEXTBOX
+.  nr @wd \w'\\$1'
+\h'.2m'\
+\h'-.2m'\v'(.2m - \\n[rsb]u)'\
+\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
+\D'l (\\n[@wd]u + .4m) 0'\
+\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
+\D'l -(\\n[@wd]u + .4m) 0'\
+\h'.2m'\v'-(.2m - \\n[rsb]u)'\
+\\$1\
+\h'.2m'
+..
+
+ +

The argument is measured with the \w escape sequence. Its width +is stored in register @wd. \w also sets the registers +rst and rsb; these contain its maximum vertical extents of +the argument. Then, four lines are drawn to form a box, offset by the +box margin. +

+
+
\D'p h1 v1 … hn vn'
+
+ + + + +

Draw polygon with vertices at drawing position and each point in +sequence. GNU troff closes the polygon by drawing a line from +(hn, vn) back to the initial drawing position. +Afterward, the drawing position is left at (hn, vn). +

+
+
\D'P dx1 dy1 dx2 dy2 …'
+
+ + + + +

As ‘\D'P …'’, but the polygon is filled. +

+

The following macro is like the ‘\D'l'’ example, but shades the +box. We draw the box before writing the text because colors in GNU +troff have no transparency; in othe opposite order, the filled +polygon would occlude the text. +

+
+
.de TEXTBOX
+.  nr @wd \w'\\$1'
+\h'.2m'\
+\h'-.2m'\v'(.2m - \\n[rsb]u)'\
+\M[lightcyan]\
+\D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
+     (\\n[@wd]u + .4m) 0 \
+     0 (\\n[rst]u - \\n[rsb]u + .4m) \
+     -(\\n[@wd]u + .4m) 0'\
+\h'.2m'\v'-(.2m - \\n[rsb]u)'\
+\M[]\
+\\$1\
+\h'.2m'
+..
+
+ +
+
\D't n'
+
+

Set the stroke thickness of geometric objects to n basic units. A +zero n selects the minimal supported thickness. A negative +n selects a thickness proportional to the type size; this is the +default. +

+
+
+ +

In a hazy penumbra between text rendering and drawing commands we locate +the bracket-building escape sequence, \b. It can assemble +apparently large glyphs by vertically stacking ordinary ones. +

+
+
Escape sequence: \b'contents'
+
+ + + +

Pile and center a sequence of glyphs vertically on the output line. +Piling stacks glyphs corresponding to each character in +contents, read from left to right, and placed from top to bottom. +GNU troff separates the glyphs vertically by 1m, and the +pile itself is centered 0.5m above the text baseline. The +horizontal drawing position is then advanced by the width of the widest +glyph in the pile. +

+ + +

This rather inflexible positioning algorithm doesn’t work with the +dvi output device since its bracket pieces vary in height. +Instead, use the geqn preprocessor. +

+

Manipulating Spacing describes how to adjust the vertical spacing +of the output line with the \x escape sequence. +

+

The application of \b that lends its name is construction of +brackets, braces, and parentheses when typesetting mathematics. We +might construct a large opening (left) brace as follows. +

+
+
\b'\[lt]\[bv]\[lk]\[bv]\[lb]'
+
+ +

See groff_char(7) for a list of special character +identifiers. +

+ + + +
+
+
+

+Next: Traps, Previous: Page Motions, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Dummy-Characters.html b/doc/groff.html.node/Dummy-Characters.html new file mode 100644 index 0000000..769574d --- /dev/null +++ b/doc/groff.html.node/Dummy-Characters.html @@ -0,0 +1,166 @@ + + + + + + +Dummy Characters (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Using Fonts   [Contents][Index]

+
+
+

5.19.10 Dummy Characters

+ +

As discussed in Requests and Macros, the first character on an +input line is treated specially. Further, formatting a glyph has many +consequences on formatter state (see Environments). Occasionally, +we want to escape this context or embrace some of those consequences +without actually rendering a glyph to the output. +

+
+
Escape sequence: \&
+
+ + +

Interpolate a dummy character, which is constitutive of output but +invisible.81 Its presence alters the interpretation context of a +subsequent input character, and enjoys several applications. +

+
    +
  • Prevent insertion of extra space after an end-of-sentence character. + +
    +
    Test.
+Test.
+    ⇒ Test.  Test.
+Test.\&
+Test.
+    ⇒ Test. Test.
+
    + +
  • Prevent recognition of a control character. + +
    +
    .Test
+    error→ warning: macro 'Test' not defined
+\&.Test
+    ⇒ .Test
+
    + +
  • Prevent kerning between two glyphs. + + +
  • Translate a character to “nothing”. + +
    +
    .tr JIjiK\&k\&UVuv
+Post universitum, alea jacta est, OK?
+    ⇒ Post vniversitvm, alea iacta est, O?
+
    +
+ +

The dummy character escape sequence sees use in macro definitions as a +means of ensuring that arguments are treated as text even if they begin +with spaces or control characters. +

+
+
.de HD \" typeset a simple bold heading
+.  sp
+.  ft B
+\&\\$1 \" exercise: remove the \&
+.  ft
+.  sp
+..
+.HD .\|.\|.\|surprised?
+
+
+ +

One way to think about the dummy character is to imagine placing the +symbol ‘&’ in the input at a certain location; if doing so has all +the side effects on formatting that you desire except for sticking an +ugly ampersand in the midst of your text, the dummy character is what +you want in its place. +

+
+
Escape sequence: \)
+
+ + + +

Interpolate a transparent dummy character—one that is +transparent to end-of-sentence detection. It behaves as \&, +except that \& is treated as letters and numerals normally are +after ‘.’, ‘?’ and ‘!’; \& cancels end-of-sentence +detection, and \) does not. +

+
+
.de Suffix-&
+.  nop \&\\$1
+..
+.
+.de Suffix-)
+.  nop \)\\$1
+..
+.
+Here's a sentence.\c
+.Suffix-& '
+Another one.\c
+.Suffix-) '
+And a third.
+    ⇒ Here's a sentence.' Another one.'  And a third.
+
+
+ + + + +
+
+
+

+Previous: Italic Corrections, Up: Using Fonts   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/End_002dof_002dinput-Traps.html b/doc/groff.html.node/End_002dof_002dinput-Traps.html new file mode 100644 index 0000000..4dad1f2 --- /dev/null +++ b/doc/groff.html.node/End_002dof_002dinput-Traps.html @@ -0,0 +1,187 @@ + + + + + + +End-of-input Traps (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Traps   [Contents][Index]

+
+
+

5.28.5 End-of-input Traps

+ + + +
+
Request: .em [name]
+
+ + + + + +

Set a trap at the end of input, calling macro name after the last +line of the last input file has been processed. If no argument is +given, any existing end-of-input trap is removed. +

+

For example, if the document had to have a section at the bottom of the +last page for someone to approve it, the em request could be +used. +

+
+
.de approval
+\c
+.  ne 3v
+.  sp (\\n[.t]u - 3v)
+.  in +4i
+.  lc _
+.  br
+Approved:\t\a
+.  sp
+Date:\t\t\a
+..
+.
+.em approval
+
+ +

The \c in the above example needs explanation. For historical +reasons (compatibility with AT&T troff), the +end-of-input macro exits as soon as it causes a page break if no +partially collected line remains.111 +

+ + + + +

Let us assume that there is no \c in the above approval +macro, that the page is full, and last output line has been broken with, +say, a br request. Because there is no more room, a ne +request at this point causes a page ejection, which in turn makes +troff exit immediately as just described. In most situations, +this is not desired; people generally want to format the input after +ne. +

+

To force processing of the whole end-of-input macro independently of +this behavior, it is thus advisable to (invisibly) ensure the existence +of a partially collected line (\c) whenever there is a chance +that a page break can happen. In the above example, invoking the +ne request ensures that there is room for the subsequent +formatted output on the same page, so we need insert \c only +once. +

+

The next example shows how to append three lines, then start a new page +unconditionally. Since ‘.ne 1’ doesn’t give the desired +effect—there is always one line available or we are already at the +beginning of the next page—we temporarily increase the page length by +one line so that we can use ‘.ne 2’. +

+
+
.de EM
+.pl +1v
+\c
+.ne 2
+line one
+.br
+\c
+.ne 2
+line two
+.br
+\c
+.ne 2
+line three
+.br
+.pl -1v
+\c
+'bp
+..
+.em EM
+
+ +

This specific feature affects only the first potential page break caused +by the end-of-input macro; further page breaks emitted by the macro are +handled normally. +

+

Another possible use of the em request is to make GNU +troff emit a single large page instead of multiple pages. For +example, one may want to produce a long plain text file for reading +in a terminal or emulator without page footers and headers interrupting +the body of the document. One approach is to set the page length at the +beginning of the document to a very large value to hold all the +text,112 and +automatically adjust it to the exact height of the document after the +text has been output. +

+
+
.de adjust-page-length
+.  br
+.  pl \\n[nl]u \" \n[nl]: current vertical position
+..
+.
+.de single-page-mode
+.  pl 99999
+.  em adjust-page-length
+..
+.
+.\" Activate the above code if configured.
+.if \n[do-continuous-rendering] \
+.  single-page-mode
+
+ +

Since only one end-of-input trap exists and another macro package may +already use it, care must be taken not to break the mechanism. A simple +solution would be to append the above macro to the macro package’s +end-of-input macro using the am request. +

+ + + +
+
+
+

+Previous: Leading Space Traps, Up: Traps   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Environment.html b/doc/groff.html.node/Environment.html new file mode 100644 index 0000000..cd92fd5 --- /dev/null +++ b/doc/groff.html.node/Environment.html @@ -0,0 +1,151 @@ + + + + + + +Environment (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Invoking groff   [Contents][Index]

+
+
+

2.2 Environment

+ + + +

There are also several environment variables (of the operating system, +not within gtroff) that can modify the behavior of groff. +

+
+
GROFF_BIN_PATH
+

This search path, followed by PATH, is used for commands executed +by groff. +

+
+
GROFF_COMMAND_PREFIX
+
+ +

If this is set to X, then groff runs +Xtroff instead of gtroff. This also applies +to tbl, pic, eqn, grn, +chem, refer, and soelim. It does not +apply to grops, grodvi, grotty, +pre-grohtml, post-grohtml, preconv, +grolj4, gropdf, and gxditview. +

+

The default command prefix is determined during the installation +process. If a non-GNU troff system is found, prefix ‘g’ is +used, none otherwise. +

+
+
GROFF_ENCODING
+

The value of this variable is passed to the preconv +preprocessor’s -e option to select the character encoding of +input files. This variable’s existence implies the groff option +-k. If set but empty, groff calls preconv +without an -e option. groff’s -K option +overrides GROFF_ENCODING. See the preconv(7) man page; +type ‘man preconv’ at the command line to view it. +

+
+
GROFF_FONT_PATH
+

A list of directories in which to seek the selected output device’s +directory of device and font description files. GNU troff +will search directories given as arguments to any specified -F +options before these, and a built-in list of directories after them. +See Font Directories and the troff(1) or +gtroff(1) man pages. +

+
+
GROFF_TMAC_PATH
+

A list of directories in which to seek macro files. GNU troff +will search directories given as arguments to any specified -M +options before these, and a built-in list of directories after them. +See Macro Directories and the troff(1) or +gtroff(1) man pages. +

+
+
GROFF_TMPDIR
+
+

The directory in which groff creates temporary files. If this is +not set and TMPDIR is set, temporary files are created in that +directory. Otherwise temporary files are created in a system-dependent +default directory (on Unix and GNU/Linux systems, this is usually +/tmp). grops, grefer, pre-grohtml, and +post-grohtml can create temporary files in this directory. +

+
+
GROFF_TYPESETTER
+

Sets the default output device. If empty or not set, a build-time +default (often ps) is used. The -Tdev option +overrides GROFF_TYPESETTER. +

+
+
SOURCE_DATE_EPOCH
+

A timestamp (expressed as seconds since the Unix epoch) to use as the +output creation timestamp in place of the current time. The time is +converted to human-readable form using localtime(3) when the +formatter starts up and stored in registers usable by documents and +macro packages (see Built-in Registers). +

+
+
TZ
+

The time zone to use when converting the current time (or value of +SOURCE_DATE_EPOCH) to human-readable form; see +tzset(3). +

+
+ +

MS-DOS and MS-Windows ports of groff use semicolons, rather than +colons, to separate the directories in the lists described above. +

+ + +
+
+
+

+Next: Macro Directories, Previous: Options, Up: Invoking groff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Environments.html b/doc/groff.html.node/Environments.html new file mode 100644 index 0000000..489ee62 --- /dev/null +++ b/doc/groff.html.node/Environments.html @@ -0,0 +1,250 @@ + + + + + + +Environments (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.31 Environments

+ + +

As discussed in Deferring Output, environments store most of the +parameters that determine the appearance of text. A default environment +named ‘0’ exists when GNU troff starts up; it is modified by +formatting-related requests and escape sequences. +

+ +

You can create new environments and switch among them. Only one is +current at any given time. Active environments are managed using a +stack, a data structure supporting “push” and “pop” +operations. The current environment is at the top of the stack. +The same environment name can be pushed onto the stack multiple times, +possibly interleaved with others. Popping the environment stack does +not destroy the current environment; it remains accessible by name and +can be made current again by pushing it at any time. Environments +cannot be renamed or deleted, and can only be modified when current. To +inspect the environment stack, use the pev request; see +Debugging. +

+

Environments store the following information. +

+
    +
  • a partially collected line, if any + +
  • data about the most recently output glyph and line (registers +.cdp, .cht, .csk, .n, .w) + +
  • typeface parameters (size, family, style, height and slant, inter-word +and inter-sentence space sizes) + +
  • page parameters (line length, title length, vertical spacing, line +spacing, indentation, line numbering, centering, right-alignment, +underlining, hyphenation parameters) + +
  • filling enablement; adjustment enablement and mode + +
  • tab stops; tab, leader, escape, control, no-break control, hyphenation, +and margin characters + +
  • input line traps + +
  • stroke and fill colors +
+ +
+
Request: .ev [ident]
+
+
Register: \n[.ev]
+
+ + + +

Enter the environment ident, which is created if it does not +already exist, using the same parameters as for the default environment +used at startup. With no argument, GNU troff switches to the +previous environment. +

+

Invoking ev with an argument puts environment ident onto +the top of the environment stack. (If it isn’t already present in the +stack, this is a proper push.) Without an argument, ev pops the +environment stack, making the previous environment current. It is an +error to pop the environment stack with no previous environment +available. The read-only string-valued register .ev contains the +name of the current environment—the one at the top of the stack. +

+
+
.ev footnote-env
+.fam N
+.ps 6
+.vs 8
+.ll -.5i
+.ev
+
+…
+
+.ev footnote-env
+\[dg] Observe the smaller text and vertical spacing.
+.ev
+
+ +

We can familiarize ourselves with stack behavior by wrapping the +ev request with a macro that reports the contents of the +.ev register to the standard error stream. +

+
+
.de EV
+.  ev \\$1
+.  tm environment is now \\n[.ev]
+..
+.
+.EV foo
+.EV bar
+.EV
+.EV baz
+.EV
+.EV
+.EV
+
+ +
+
    error→ environment is now foo
+    error→ environment is now bar
+    error→ environment is now foo
+    error→ environment is now baz
+    error→ environment is now foo
+    error→ environment is now 0
+    error→ error: environment stack underflow
+    error→ environment is now 0
+
+ +
+ +
+
Request: .evc environment
+
+ + +

Copy the contents of environment to the current environment. +

+

The following environment data are not copied. +

+
    +
  • a partially collected line, if present; + +
  • the interruption status of the previous input line (due to use of the +\c escape sequence); + +
  • the count of remaining lines to center, to right-justify, or to +underline (with or without underlined spaces)—these are set to zero; + +
  • the activation status of temporary indentation; + +
  • input line traps and their associated data; + +
  • the activation status of line numbering (which can be reactivated with +‘.nm +0’); and + +
  • the count of consecutive hyphenated lines (set to zero). +
+
+ +
+
Register: \n[.w]
+
+
Register: \n[.cht]
+
+
Register: \n[.cdp]
+
+
Register: \n[.csk]
+
+ + + + + + + +

The \n[.w] register contains the width of the last glyph +formatted in the environment. +

+

The \n[.cht] register contains the height of the last glyph +formatted in the environment. +

+

The \n[.cdp] register contains the depth of the last glyph +formatted in the environment. It is positive for glyphs extending below +the baseline. +

+

The \n[.csk] register contains the skew (how far to the +right of the glyph’s center that GNU troff should place an +accent) of the last glyph formatted in the environment. +

+ +
+
Register: \n[.n]
+
+ + + + +

The \n[.n] register contains the length of the previous output +line emitted in the environment. +

+ + + + +
+
+
+

+Next: Suppressing Output, Previous: Diversions, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Escape-Sequence-Index.html b/doc/groff.html.node/Escape-Sequence-Index.html new file mode 100644 index 0000000..19e5a61 --- /dev/null +++ b/doc/groff.html.node/Escape-Sequence-Index.html @@ -0,0 +1,162 @@ + + + + + + +Escape Sequence Index (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

Appendix C Escape Sequence Index

+ +

The escape character, \ by default, is always followed by at +least one more input character, making an escape sequence. Any +input token \X with X not in the list below emits a +warning and interpolates glyph X. Note the entries for \., +which may be obscured by the leader dots, and for \RET and +\SP, which are sorted alphabetically, not by code point +order. +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
\
\: Using Escape Sequences
\: Using Symbols
\!: Diversions
\": Comments
\#: Comments
\$: Parameters
\$*: Parameters
\$0: Parameters
\$@: Parameters
\$^: Parameters
\%: Manipulating Hyphenation
\&: Dummy Characters
\': Using Symbols
\(: Using Symbols
\): Dummy Characters
\*: Strings
\,: Italic Corrections
\-: Using Symbols
\.: Copy Mode
\/: Italic Corrections
\0: Page Motions
\:: Manipulating Hyphenation
\?: Diversions
\A: Identifiers
\a: Leaders
\B: Numeric Expressions
\b: Drawing Geometric Objects
\c: Line Continuation
\C: Using Symbols
\d: Page Motions
\D: Drawing Geometric Objects
\e: Using Escape Sequences
\E: Copy Mode
\f: Selecting Fonts
\F: Font Families
\g: Assigning Register Formats
\H: Artificial Fonts
\h: Page Motions
\k: Page Motions
\l: Drawing Geometric Objects
\L: Drawing Geometric Objects
\m: Colors
\M: Colors
\n: Interpolating Registers
\n: Auto-increment
\N: Using Symbols
\newline: Line Continuation
\o: Page Motions
\O: Suppressing Output
\p: Manipulating Filling and Adjustment
\R: Setting Registers
\R: Setting Registers
\r: Page Motions
\RET: Line Continuation
\S: Artificial Fonts
\s: Changing the Type Size
\SP: Page Motions
\space: Page Motions
\t: Tabs and Fields
\u: Page Motions
\v: Page Motions
\V: I/O
\w: Page Motions
\x: Manipulating Spacing
\X: Postprocessor Access
\Y: Postprocessor Access
\z: Page Motions
\Z: Page Motions
\[: Using Symbols
\\: Copy Mode
\^: Page Motions
\_: Using Symbols
\`: Using Symbols
\{: Conditional Blocks
\{: Conditional Blocks
\|: Page Motions
\}: Conditional Blocks
\~: Manipulating Filling and Adjustment
+
+ + + + +
+
+
+

+Next: Operator Index, Previous: Request Index, Up: GNU troff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Fields.html b/doc/groff.html.node/Fields.html new file mode 100644 index 0000000..6e1754a --- /dev/null +++ b/doc/groff.html.node/Fields.html @@ -0,0 +1,98 @@ + + + + + + +Fields (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Tabs and Fields   [Contents][Index]

+
+
+

5.12.2 Fields

+ + + + + + + + +

Fields are a more general way of laying out tabular data. A field +is defined as the data between a pair of delimiting characters. +It contains substrings that are separated by padding characters. +The width of a field is the distance on the input line from the +position where the field starts to the next tab stop. A padding +character inserts an adjustable space similar to TeX’s \hss +command (thus it can even be negative) to make the sum of all substring +lengths plus the adjustable space equal to the field width. If more +than one padding character is inserted, the available space is evenly +distributed among them. +

+
+
Request: .fc [delim-char [padding-char]]
+
+

Define a delimiting and a padding character for fields. If the latter +is missing, the padding character defaults to a space character. If +there is no argument at all, the field mechanism is disabled (which is +the default). In contrast to, e.g., the tab repetition character, +delimiting and padding characters are not associated with the +environment (see Environments). +

+
+
.fc # ^
+.ta T 3i
+#foo^bar^smurf#
+.br
+#foo^^bar^smurf#
+    ⇒ foo         bar          smurf
+    ⇒ foo            bar       smurf
+
+
+ + + +
+ + + + + diff --git a/doc/groff.html.node/File-Formats.html b/doc/groff.html.node/File-Formats.html new file mode 100644 index 0000000..c5d4d54 --- /dev/null +++ b/doc/groff.html.node/File-Formats.html @@ -0,0 +1,62 @@ + + + + + + +File Formats (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

6 File Formats

+ + + +

All files read and written by gtroff are text files. The +following two sections describe their format. +

+ + + + + +
+ + + + + diff --git a/doc/groff.html.node/File-Keyword-Index.html b/doc/groff.html.node/File-Keyword-Index.html new file mode 100644 index 0000000..348d292 --- /dev/null +++ b/doc/groff.html.node/File-Keyword-Index.html @@ -0,0 +1,215 @@ + + + + + + +File Keyword Index (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

Appendix H File Keyword Index

+ +
+
Jump to:   # +   +- +   +
+B +   +C +   +F +   +H +   +I +   +K +   +L +   +N +   +P +   +R +   +S +   +T +   +U +   +V +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
#
#: DESC File Format
#: Font Description File Format
-
---: Font Description File Format
B
biggestfont: DESC File Format
C
charset: DESC File Format
charset: Font Description File Format
F
family: Selecting Fonts
family: DESC File Format
fonts: Using Symbols
fonts: Special Fonts
fonts: DESC File Format
H
hor: DESC File Format
I
image_generator: DESC File Format
K
kernpairs: Font Description File Format
L
ligatures: Font Description File Format
N
name: Font Description File Format
P
paperlength: DESC File Format
papersize: DESC File Format
paperwidth: DESC File Format
pass_filenames: DESC File Format
postpro: DESC File Format
prepro: DESC File Format
print: DESC File Format
R
res: DESC File Format
S
sizes: DESC File Format
sizescale: DESC File Format
slant: Font Description File Format
spacewidth: Font Description File Format
spare1: DESC File Format
spare2: DESC File Format
special: Artificial Fonts
special: Font Description File Format
styles: Selecting Fonts
styles: Font Families
styles: DESC File Format
T
tcommand: DESC File Format
U
unicode: DESC File Format
unitwidth: DESC File Format
unscaled_charwidths: DESC File Format
use_charnames_in_special: Postprocessor Access
use_charnames_in_special: DESC File Format
V
vert: DESC File Format
+
Jump to:   # +   +- +   +
+B +   +C +   +F +   +H +   +I +   +K +   +L +   +N +   +P +   +R +   +S +   +T +   +U +   +V +   +
+
+ + + + +
+
+
+

+Next: Program and File Index, Previous: String Index, Up: GNU troff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Filling.html b/doc/groff.html.node/Filling.html new file mode 100644 index 0000000..f6db6f3 --- /dev/null +++ b/doc/groff.html.node/Filling.html @@ -0,0 +1,79 @@ + + + + + + +Filling (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+
+

5.1.1 Filling

+ +

When GNU troff starts up, it obtains information about the device +for which it is preparing output.18 An essential property is the length of the output +line, such as “6.5 inches”. +

+ + +

GNU troff interprets plain text files employing the Unix +line-ending convention. It reads input a character at a time, +collecting words as it goes, and fits as many words together on an +output line as it can—this is known as filling. To GNU +troff, a word is any sequence of one or more characters +that aren’t spaces or newlines. The exceptions separate +words.19 To disable filling, see +Manipulating Filling and Adjustment. +

+
+
It is a truth universally acknowledged
+that a single man in possession of a
+good fortune must be in want of a wife.
+    ⇒ It is a truth universally acknowledged that a
+    ⇒ single man in possession of a good fortune must
+    ⇒ be in want of a wife.
+
+ + +
+ + + + + diff --git a/doc/groff.html.node/Font-Description-File-Format.html b/doc/groff.html.node/Font-Description-File-Format.html new file mode 100644 index 0000000..a44cf20 --- /dev/null +++ b/doc/groff.html.node/Font-Description-File-Format.html @@ -0,0 +1,280 @@ + + + + + + +Font Description File Format (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Device and Font Description Files   [Contents][Index]

+
+
+

6.2.2 Font Description File Format

+ + + + + +

On typesetting output devices, each font is typically available at +multiple sizes. While paper measurements in the device description file +are in absolute units, measurements applicable to fonts must be +proportional to the type size. groff achieves this using the +precedent set by AT&T device-independent troff: one +font size is chosen as a norm, and all others are scaled linearly +relative to that basis. The “unit width” is the number of basic units +per point when the font is rendered at this nominal size. +

+

For instance, groff’s lbp device uses a unitwidth +of 800. Its Times roman font ‘TR’ has a spacewidth +of 833; this is also the width of its comma, period, centered +period, and mathematical asterisk, while its ‘M’ is 2,963 basic +units. Thus, an ‘M’ on the lbp device is 2,963 basic units +wide at a notional type size of 800 points.126 +

+

A font description file has two sections. The first is a sequence of +directives, and is parsed similarly to the DESC file described +above. Except for the directive names that begin the second section, +their ordering is immaterial. Later directives of the same name +override earlier ones, spaces and tabs are handled in the same way, + + + +and the same comment syntax is supported. Empty lines are ignored +throughout. +

+
+
name f
+

The name of the font is f. ‘DESC’ is an invalid font +name. Simple integers are valid, but their use is +discouraged.127 +

+
+
spacewidth n
+

The width of an unadjusted inter-word space is n basic units. +

+
+ +

The directives above must appear in the first section; those below are +optional. +

+
+
slant n
+

The font’s glyphs have a slant of n degrees; a positive +n slants in the direction of text flow. +

+
+
ligatures lig1 … lign [0]
+

Glyphs lig1, …, lign are ligatures; possible ligatures +are ‘ff’, ‘fi’, ‘fl’, ‘ffi’ and ‘ffl’. For +compatibility with other troff implementations, the list of +ligatures may be terminated with a 0. The list of ligatures +must not extend over more than one line. +

+
+
special
+
+

The font is special: when a glyph is requested that is not present +in the current font, it is sought in any mounted fonts that bear this +property. +

+
+ +

Other directives in this section are ignored by GNU troff, but +may be used by postprocessors to obtain further information about the +font. +

+

The second section contains one or two subsections. These can appear in +either order; the first one encountered commences the second section. +Each starts with a directive on a line by itself. A charset +subsection is mandatory unless the associated DESC file contains +the unicode directive. Another subsection, kernpairs, +is optional. +

+ +

The directive charset starts the character set +subsection.128 It precedes a series +of glyph descriptions, one per line. Each such glyph description +comprises a set of fields separated by spaces or tabs and organized as +follows. +

+
+

name metrics type code [entity-name] +[-- comment] +

+ + + + + + + + +

name identifies the glyph: +if name is a printable character c, it corresponds to +the troff ordinary character c. If name is a +multi-character sequence not beginning with \, it corresponds to +the GNU troff special character escape sequence +‘\[name]’. A name consisting of three minus signs, +‘---’, is special and indicates that the glyph is unnamed: such +glyphs can be accessed only by the \N escape sequence in +troff. A special character named ‘---’ can still be defined +using char and similar requests. The name ‘\-’ +defines the minus sign glyph. Finally, name can be the +unbreakable one-sixth and one-twelfth space escape sequences, \| +and \^ (“thin” and “hair” spaces, respectively), in which +case only the width metric described below is interpreted; a font can +thus customize the widths of these spaces. +

+

The form of the metrics field is as follows. +

+
+
width[,[height[,[depth[,[italic-correction
+  [,[left-italic-correction[,[subscript-correction]]]]]]]]]]
+
+ +

There must not be any spaces, tabs, or newlines between these +subfields (which have been split here into two lines only for +better legibility). The subfields are in basic units expressed as +decimal integers. Unspecified subfields default to 0. +Since there is no associated binary format, these values are not +required to fit into the C language data type ‘char’ as they are in +AT&T device-independent troff. +

+

The width subfield gives the width of the glyph. The height +subfield gives the height of the glyph (upward is positive); if a glyph +does not extend above the baseline, it should be given a zero height, +rather than a negative height. The depth subfield gives the depth +of the glyph, that is, the distance below the baseline to which the +glyph extends (downward is positive); if a glyph does not extend below +the baseline, it should be given a zero depth, rather than a negative +depth. Italic corrections are relevant to glyphs in italic or oblique +styles. The italic-correction is the amount of space that should +be added after an oblique glyph to be followed immediately by an upright +glyph. The left-italic-correction is the amount of space that +should be added before an oblique glyph to be preceded immediately by an +upright glyph. The subscript-correction is the amount of space +that should be added after an oblique glyph to be followed by a +subscript; it should be less than the italic correction. +

+

For fonts used with typesetting devices, the type field gives a +featural description of the glyph: it is a bit mask recording whether +the glyph is an ascender, descender, both, or neither. When a \w +escape sequence is interpolated, these values are bitwise or-ed +together for each glyph and stored in the nr register. In font +descriptions for terminal devices, all glyphs might have a type of zero, +regardless of their appearance. +

+
+
0
+

means the glyph lies entirely between the baseline and a horizontal line +at the “x-height” of the font; typical examples are ‘a’, +‘c’, and ‘x’; +

+
+
1
+

means the glyph descends below the baseline, like ‘p’; +

+
+
2
+

means the glyph ascends above the font’s x-height, like ‘A’ or +‘b’; and +

+
+
3
+

means the glyph is both an ascender and a descender—this is true of +parentheses in some fonts. +

+
+ +

The code field gives a numeric identifier that the postprocessor +uses to render the glyph. The glyph can be specified to troff +using this code by means of the \N escape sequence. code +can be any integer.129 +

+

The entity-name field defines an identifier for the glyph that the +postprocessor uses to print the GNU troff glyph name. This +field is optional; it was introduced so that the grohtml output +driver could encode its character set. For example, the glyph +‘\[Po]’ is represented by ‘&pound;’ in HTML 4.0. +For efficiency, these data are now compiled directly into +grohtml. grops uses the field to build sub-encoding +arrays for PostScript fonts containing more than 256 glyphs. Anything +on the line after the entity-name field or ‘--’ is ignored. +

+

A line in the charset section can also have the form +

+
+
name "
+
+ +

identifying name as another name for the glyph mentioned in the +preceding line. Such aliases can be chained. +

+ +

The directive kernpairs starts a list of kerning adjustments to +be made to adjacent glyph pairs from this font. It contains a sequence +of lines formatted as follows. +

+
+
g1 g2 n
+
+ +

The foregoing means that when glyph g1 is typeset immediately +before g2, the space between them should be increased +by n. Most kerning pairs should have a negative value +for n. +

+ + + + +
+
+
+

+Previous: DESC File Format, Up: Device and Font Description Files   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Font-Directories.html b/doc/groff.html.node/Font-Directories.html new file mode 100644 index 0000000..89cb39d --- /dev/null +++ b/doc/groff.html.node/Font-Directories.html @@ -0,0 +1,113 @@ + + + + + + +Font Directories (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Invoking groff   [Contents][Index]

+
+
+

2.4 Font Directories

+ + + + + +

groff enforces few restrictions on how font description files are +named. For its family/style mechanism to work (see Font Families), +the names of fonts within a family should start with the family name, +followed by the style. For example, the Times family uses ‘T’ for +the family name and ‘R’, ‘B’, ‘I’, and ‘BI’ to +indicate the styles ‘roman’, ‘bold’, ‘italic’, and ‘bold italic’, +respectively. Thus the final font names are ‘TR’, ‘TB’, +‘TI’, and ‘TBI’. +

+ + +

Font description files are kept in font directories, which +together constitute the font path. The search procedure +always appends the directory devname, where name is +the name of the output device. Assuming TeX DVI output, and +/foo/bar as a font directory, the font description files for +grodvi must be in /foo/bar/devdvi. +Each directory in the font path is searched in the following order until +the desired font description file is found or the list is exhausted. +

+
    +
  • Directories specified with GNU troff’s or groff’s +-f command-line option. All output drivers (and some +preprocessors) support this option as well, because they require +information about the glyphs to be rendered in the document. + +
  • +Directories listed in the GROFF_FONT_PATH environment variable. + +
  • + +A site-local directory and the main font description directory. +The locations corresponding to your installation are listed in section +“Environment” of gtroff(1). If not otherwise configured, +they are as follows. + +
    +
    /usr/local/share/groff/site-font
+/usr/local/share/groff/1.23.0/font
+
    + +

    The foregoing assumes that the version of groff is 1.23.0, and +that the installation prefix was /usr/local. It is possible to +fine-tune these locations during the source configuration process. +

+ + + +
+
+
+

+Next: Paper Format, Previous: Macro Directories, Up: Invoking groff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Font-Families.html b/doc/groff.html.node/Font-Families.html new file mode 100644 index 0000000..f631c1a --- /dev/null +++ b/doc/groff.html.node/Font-Families.html @@ -0,0 +1,182 @@ + + + + + + +Font Families (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+
+

5.19.2 Font Families

+ + + + + +

To accommodate the wide variety of fonts available, GNU troff +distinguishes font families and font styles. A resolved +font name is the catenation of a font family and a style. Selecting an +abstract style causes GNU troff to combine it with the default +font family. +

+

You can thus compose a document using abstract styles exclusively for +its body or running text, selecting a specific family only for titles or +examples, for instance, and change the default family on the command +line (recall Options). +

+

Fonts for the devices ps, pdf, dvi, lj4, +lbp, and the X11 devices support this mechanism. By default, +GNU troff uses the Times family with the four styles ‘R’, +‘I’, ‘B’, and ‘BI’. +

+
+
Request: .fam [family]
+
+
Register: \n[.fam]
+
+
Escape sequence: \Ff
+
+
Escape sequence: \F(fm
+
Escape sequence: \F[family]
+
+ +

Set the default font family, used in combination with abstract styles to +construct a resolved font name, to family (one-character +name f, two-character name fm). If no argument is +given, GNU troff selects the previous font family; if there none, +is it falls back to the device’s default76 or its own (‘T’). +

+

The \F escape sequence works similarly. In disanalogy to +\f, ‘\FP’ makes ‘P’ the default family. Use +‘\F[]’ to select the previous default family. The default font +family is available in the read-only string-valued register .fam; +it is associated with the environment (see Environments). +

+
+
spam,     \" startup defaults are T (Times) R (roman)
+.fam H    \" make Helvetica the default family
+spam,     \" family H + style R = HR
+.ft B     \" family H + style B = HB
+spam,
+.ft CR    \" Courier roman (default family not changed)
+spam,
+.ft       \" back to Helvetica bold
+spam,
+.fam T    \" make Times the default family
+spam,     \" family T + style B = TB
+.ft AR    \" font AR (not a style)
+baked beans,
+.ft R     \" family T + style R = TR
+and spam.
+
+ +

\F doesn’t produce an input token in GNU troff. As a +consequence, it can be used in requests like mc (which expects +a single character as an argument) to change the font family on the fly. +

+
+
.mc \F[P]x\F[]
+
+
+ +
+
Request: .sty n style
+
+
Register: \n[.sty]
+
+ + + + + + + + + +

Associate an abstract style style with mounting +position n, which must be a non-negative integer. If the +requests cs, bd, tkf, uf, or fspecial +are applied to an abstract style, they are instead applied to the member +of the current family corresponding to that style. +

+ + +

The default family can be set with the -f option (see Options). The styles command in the DESC file controls +which font positions (if any) are initially associated with abstract +styles rather than fonts. +

+

Caution: The style argument is not validated. +Errors may occur later, when the formatter attempts to construct a +resolved font name, or format a character for output. +

+
+
.nr BarPos \n[.fp]
+.sty \n[.fp] Bar
+.fam Foo
+.ft \n[BarPos]
+.tm .f=\n[.f]
+A
+    error→ error: no font family named 'Foo' exists
+    error→ .f=41
+    error→ error: cannot format glyph: no current font
+
+ +

When an abstract style has been selected, the read-only string-valued +register ‘.sty’ interpolates its name; this datum is associated +with the environment (see Environments). Otherwise, ‘.sty’ +interpolates nothing. +

+ + +
+
+
+

+Next: Font Positions, Previous: Selecting Fonts, Up: Using Fonts   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Font-Positions.html b/doc/groff.html.node/Font-Positions.html new file mode 100644 index 0000000..387b4bb --- /dev/null +++ b/doc/groff.html.node/Font-Positions.html @@ -0,0 +1,138 @@ + + + + + + +Font Positions (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+
+

5.19.3 Font Positions

+ + + +

To support typeface indirection through abstract styles, and for +compatibility with AT&T troff, the formatter maintains +a list of font positions at which fonts required by a document are +mounted. An output device’s description file DESC +typically configures a set of pre-mounted fonts; see Device and Font Description Files. A font need not be explicitly mounted before +it is selected; GNU troff will search GROFF_FONT_PATH for +it by name and mount it at the first free mounting position on demand. +

+
+
Request: .fp pos id [font-description-file-name]
+
+
Register: \n[.f]
+
+
Register: \n[.fp]
+
+ + +

Mount a font under the name id at mounting position pos, a +non-negative integer. When the formatter starts up, it reads the output +device’s description to mount an initial set of faces, and selects font +position 1. Position 0 is unused by default. Unless the +font-description-file-name argument is given, id should be +the name of a font description file stored in a directory corresponding +to the selected output device. GNU troff does not traverse +directories to locate the font description file. +

+ + +

The optional third argument enables font names to be aliased, which can +be necessary in compatibility mode since AT&T troff syntax +affords no means of identifying fonts with names longer than two +characters, like ‘TBI’ or ‘ZCMI’, in a font selection escape +sequence. See Compatibility Mode. You can also alias fonts on +mounting for convenience or abstraction. (See below regarding the +.fp register.) +

+
+
.fp \n[.fp] SC ZCMI
+Send a \f(SChand-written\fP thank-you note.
+.fp \n[.fp] Emph TI
+.fp \n[.fp] Strong TB
+Are \f[Emph]these names\f[] \f[Strong]comfortable\f[]?
+
+ +

‘DESC’, ‘P’, and non-negative integers are not usable as font +identifiers. +

+ +

The position of the currently selected font (or abstract style) is +available in the read-only register ‘.f’. It is associated with +the environment (see Environments). +

+

You can copy the value of .f to another register to save it for +later use. +

+
+
.nr saved-font \n[.f]
+… text involving many font changes …
+.ft \n[saved-font]
+
+ + +

The index of the next (non-zero) free font position is available in the +read-only register ‘.fp’. + +Fonts not listed in the DESC file are automatically mounted at +position ‘\n[.fp]’ when selected with the ft request or +\f escape sequence. When mounting a font at a position +explicitly with the fp request, this same practice should be +followed, although GNU troff does not enforce this strictly. +

+ + +
+
+
+

+Next: Using Symbols, Previous: Font Families, Up: Using Fonts   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Font-and-Size-Changes.html b/doc/groff.html.node/Font-and-Size-Changes.html new file mode 100644 index 0000000..d8319bf --- /dev/null +++ b/doc/groff.html.node/Font-and-Size-Changes.html @@ -0,0 +1,56 @@ + + + + + + +Font and Size Changes (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.11 Font and Size Changes

+ +

The formatter’s requests and escape sequences for setting the typeface +and size are not always intuitive, so all macro packages provide macros +to make these operations simpler. They also make it more convenient to +change typefaces in the middle of a word and can handle italic +corrections automatically. See Italic Corrections. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Footnotes-and-Endnotes.html b/doc/groff.html.node/Footnotes-and-Endnotes.html new file mode 100644 index 0000000..82d14e7 --- /dev/null +++ b/doc/groff.html.node/Footnotes-and-Endnotes.html @@ -0,0 +1,60 @@ + + + + + + +Footnotes and Endnotes (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.6 Footnotes and Endnotes

+ + + +

Footnotes and endnotes are forms of delayed +formatting. They are recorded at their points of relevance in +the input, but not formatted there. Instead, a mark cues the +reader to check the “foot”, or bottom, of the current page, or in the +case of endnotes, an annotation list later in the document. Macro +packages that support these features also supply a means of +automatically numbering either type of annotation. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Formatter-Instructions.html b/doc/groff.html.node/Formatter-Instructions.html new file mode 100644 index 0000000..b6527ad --- /dev/null +++ b/doc/groff.html.node/Formatter-Instructions.html @@ -0,0 +1,83 @@ + + + + + + +Formatter Instructions (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.6 Formatter Instructions

+ + + +

To support documents that require more than filling, automatic line +breaking and hyphenation, adjustment, and supplemental inter-sentence +space, the roff language offers two means of embedding +instructions to the formatter. +

+ +

One is a request, which begins with a control character and takes +up the remainder of the input line. Requests often perform relatively +large-scale operations such as setting the page length, breaking the +line, or starting a new page. They also conduct internal operations +like defining macros. +

+ + +

The other is an escape sequence, which begins with the escape +character and can be embedded anywhere in the input, even in arguments +to requests and other escape sequences. Escape sequences interpolate +special characters, strings, or registers, and handle comparatively +minor formatting tasks like sub- and superscripting. +

+

Some operations, such as font selection and type size alteration, are +available via both requests and escape sequences. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/GNU-troff-Reference.html b/doc/groff.html.node/GNU-troff-Reference.html new file mode 100644 index 0000000..396d40a --- /dev/null +++ b/doc/groff.html.node/GNU-troff-Reference.html @@ -0,0 +1,99 @@ + + + + + + +GNU troff Reference (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/groff.html.node/Graphics-Commands.html b/doc/groff.html.node/Graphics-Commands.html new file mode 100644 index 0000000..87a856c --- /dev/null +++ b/doc/groff.html.node/Graphics-Commands.html @@ -0,0 +1,247 @@ + + + + + + +Graphics Commands (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Command Reference   [Contents][Index]

+
+
+

6.1.2.3 Graphics Commands

+ +

Each graphics or drawing command in the intermediate output starts with +the letter ‘D’, followed by one or two characters that specify a +subcommand; this is followed by a fixed or variable number of integer +arguments that are separated by a single space character. A ‘D’ +command may not be followed by another command on the same line (apart +from a comment), so each ‘D’ command is terminated by a syntactical +line break. +

+

gtroff output follows the classical spacing rules (no space +between command and subcommand, all arguments are preceded by a single +space character), but the parser allows optional space between the +command letters and makes the space before the first argument optional. +As usual, each space can be any sequence of tab and space characters. +

+

Some graphics commands can take a variable number of arguments. In this +case, they are integers representing a size measured in basic units +‘u’. The arguments called h1, h2, …, hn +stand for horizontal distances where positive means right, negative +left. The arguments called v1, v2, …, vn stand +for vertical distances where positive means down, negative up. All +these distances are offsets relative to the current location. +

+

Each graphics command directly corresponds to a similar gtroff +\D escape sequence. See Drawing Geometric Objects. +

+

Unknown ‘D’ commands are assumed to be device-specific. Its +arguments are parsed as strings; the whole information is then sent to +the postprocessor. +

+

In the following command reference, the syntax element ‹line +break› means a syntactical line break as defined above. +

+
+
D~ h1 v1 h2 v2 … hn vn‹line break›
+

Draw B-spline from current position to offset (h1,v1), then +to offset (h2,v2), if given, etc., up to +(hn,vn). This command takes a variable number of argument +pairs; the current position is moved to the terminal point of the drawn +curve. +

+
+
Da h1 v1 h2 v2‹line break›
+

Draw arc from current position to +(h1,v1)+(h2,v2) with center at +(h1,v1); then move the current position to the final point +of the arc. +

+
+
DC d‹line break›
+
DC d dummy-arg‹line break›
+

Draw a solid circle using the current fill color with +diameter d (integer in basic units ‘u’) with leftmost +point at the current position; then move the current position to the +rightmost point of the circle. An optional second integer argument is +ignored (this allows the formatter to generate an even number of +arguments). This command is a gtroff extension. +

+
+
Dc d‹line break›
+

Draw circle line with diameter d (integer in basic units +‘u’) with leftmost point at the current position; then move the +current position to the rightmost point of the circle. +

+
+
DE h v‹line break›
+

Draw a solid ellipse in the current fill color with a horizontal +diameter of h and a vertical diameter of v (both +integers in basic units ‘u’) with the leftmost point at the current +position; then move to the rightmost point of the ellipse. This command +is a gtroff extension. +

+
+
De h v‹line break›
+

Draw an outlined ellipse with a horizontal diameter of h and +a vertical diameter of v (both integers in basic units +‘u’) with the leftmost point at current position; then move to the +rightmost point of the ellipse. +

+
+
DF color-scheme [component …]‹line break›
+

Set fill color for solid drawing objects using different color schemes; +the analogous command for setting the color of text, line graphics, and +the outline of graphic objects is ‘m’. The color components are +specified as integer arguments between 0 and 65535. The number of color +components and their meaning vary for the different color schemes. +These commands are generated by gtroff’s escape sequences +‘\D'F …'’ and \M (with no other corresponding +graphics commands). No position changing. This command is a +gtroff extension. +

+
+
DFc cyan magenta yellow‹line break›
+

Set fill color for solid drawing objects using the CMY color scheme, +having the 3 color components cyan, magenta, and +yellow. +

+
+
DFd‹line break›
+

Set fill color for solid drawing objects to the default fill color value +(black in most cases). No component arguments. +

+
+
DFg gray‹line break›
+

Set fill color for solid drawing objects to the shade of gray given by +the argument, an integer between 0 (black) and 65535 (white). +

+
+
DFk cyan magenta yellow black‹line break›
+

Set fill color for solid drawing objects using the CMYK color scheme, +having the 4 color components cyan, magenta, +yellow, and black. +

+
+
DFr red green blue‹line break›
+

Set fill color for solid drawing objects using the RGB color scheme, +having the 3 color components red, green, and +blue. +

+
+ +
+
Df n‹line break›
+

The argument n must be an integer in the range -32767 +to 32767. +

+
+
0 ≤ n ≤ 1000
+

Set the color for filling solid drawing objects to a shade of gray, +where 0 corresponds to solid white, 1000 (the default) to solid black, +and values in between to intermediate shades of gray; this is obsoleted +by command ‘DFg’. +

+
+
n < 0 or n > 1000
+

Set the filling color to the color that is currently being used for the +text and the outline, see command ‘m’. For example, the command +sequence +

+
+
mg 0 0 65535
+Df -1
+
+ +

sets all colors to blue. +

+
+ +

No position changing. This command is a gtroff extension. +

+
+
Dl h v‹line break›
+

Draw line from current position to offset (h,v) (integers in +basic units ‘u’); then set current position to the end of the drawn +line. +

+
+
Dp h1 v1 h2 v2 … hn vn‹line break›
+

Draw a polygon line from current position to offset (h1,v1), +from there to offset (h2,v2), etc., up to offset +(hn,vn), and from there back to the starting position. For +historical reasons, the position is changed by adding the sum of all +arguments with odd index to the actual horizontal position and the even +ones to the vertical position. Although this doesn’t make sense it is +kept for compatibility. +This command is a gtroff extension. +

+
+
DP h1 v1 h2 v2 … hn vn‹line break›
+

Draw a solid polygon in the current fill color rather than an outlined +polygon, using the same arguments and positioning as the corresponding +‘Dp’ command. +This command is a gtroff extension. +

+
+
Dt n‹line break›
+

Set the current line thickness to n (an integer in basic +units ‘u’) if n>0; if n=0 select the +smallest available line thickness; if n<0 set the line +thickness proportional to the type size (this is the default before the +first ‘Dt’ command was specified). For historical reasons, the +horizontal position is changed by adding the argument to the actual +horizontal position, while the vertical position is not changed. +Although this doesn’t make sense it is kept for compatibility. +This command is a gtroff extension. +

+
+ +
+
+
+

+Next: Device Control Commands, Previous: Simple Commands, Up: Command Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Groff-Options.html b/doc/groff.html.node/Groff-Options.html new file mode 100644 index 0000000..48ea5e5 --- /dev/null +++ b/doc/groff.html.node/Groff-Options.html @@ -0,0 +1,536 @@ + + + + + + +Groff Options (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Invoking groff   [Contents][Index]

+
+
+

2.1 Options

+ + + + + + + + + + + + + +

groff normally runs the gtroff program and a +postprocessor appropriate for the selected device. The default device +is ‘ps’ (but it can be changed when groff is configured and +built). It can optionally preprocess with any of gpic, +geqn, gtbl, ggrn, grap, gchem, +grefer, gsoelim, or preconv. +

+

This section documents only options to the groff front end. Many +of the arguments to groff are passed on to gtroff; +therefore, those are also included. Arguments to preprocessors and +output drivers can be found in the man pages gpic(1), +geqn(1), gtbl(1), ggrn(1), +grefer(1), gchem(1), gsoelim(1), +preconv(1), grotty(1), grops(1), +gropdf(1), grohtml(1), grodvi(1), +grolj4(1), grolbp(1), and gxditview(1). +

+

The command-line format for groff is: +

+
+
groff [ -abceghijklpstvzCEGNRSUVXZ ] [ -dcs ] [ -Darg ]
+      [ -ffam ] [ -Fdir ] [ -Idir ] [ -Karg ]
+      [ -Larg ] [ -mname ] [ -Mdir ] [ -nnum ]
+      [ -olist ] [ -Parg ] [ -rcn ] [ -Tdev ]
+      [ -wname ] [ -Wname ] [ files… ]
+
+ +

The command-line format for gtroff is as follows. +

+
+
gtroff [ -abcivzCERU ] [ -dcs ] [ -ffam ] [ -Fdir ]
+       [ -mname ] [ -Mdir ] [ -nnum ] [ -olist ]
+       [ -rcn ] [ -Tname ] [ -wname ] [ -Wname ]
+       [ files… ]
+
+ +

Obviously, many of the options to groff are actually passed on to +gtroff. +

+

Options without an argument can be grouped behind a +single -. A filename of - denotes the +standard input. Whitespace is permitted between an option and its +argument. +

+

The grog command can be used to guess the correct groff +command to format a file. See its man page grog(1); type +‘man grog’ at the command line to view it. +

+

groff’s command-line options are as follows. +

+ +
+
‘-a’
+

Generate a plain text approximation of the typeset output. The +read-only register .A is set to 1. See Built-in Registers. This option produces a sort of abstract preview of the +formatted output. +

+
    +
  • Page breaks are marked by a phrase in angle brackets; for example, +‘<beginning of page>’. + +
  • Lines are broken where they would be in the formatted output. + +
  • A horizontal motion of any size is represented as one space. Adjacent +horizontal motions are not combined. Inter-sentence space nodes (those +arising from the second argument to the ss request) are not +represented. + +
  • Vertical motions are not represented. + +
  • Special characters are rendered in angle brackets; for example, the +default soft hyphen character appears as ‘<hy>’. +
+ +

The above description should not be considered a specification; the +details of -a output are subject to change. +

+
+
‘-b’
+

Write a backtrace reporting the state of gtroff’s input parser +to the standard error stream with each diagnostic message. The line +numbers given in the backtrace might not always be correct, because +gtroff’s idea of line numbers can be confused by requests that +append to +macros. +

+
+
‘-c’
+

Start with color output disabled. +

+
+
‘-C’
+

Enable AT&T troff compatibility mode; implies -c. +See Implementation Differences, for the list of incompatibilities +between groff and AT&T troff. +

+
+
‘-dctext’
+
‘-dstring=text’
+

Define roff string c or string as t or +text. c must be one character; string can be +of arbitrary length. Such string assignments happen before any macro +file is loaded, including the startup file. Due to getopt_long +limitations, c cannot be, and string cannot contain, an +equals sign, even though that is a valid character in a roff +identifier. +

+
+
‘-Denc’
+

Set fallback input encoding used by preconv to enc; +implies -k. +

+
+
‘-e’
+

Run geqn preprocessor. +

+
+
‘-E’
+

Inhibit gtroff error messages. This option does not +suppress messages sent to the standard error stream by documents or +macro packages using tm or related requests. +

+
+
‘-ffam’
+

Use fam as the default font family. See Font Families. +

+
+
‘-Fdir’
+

Search in directory dir for the selected output device’s +directory of device and font description files. See the description of +GROFF_FONT_PATH in Environment below for the default search +locations and ordering. +

+
+
‘-g’
+

Run ggrn preprocessor. +

+
+
‘-G’
+

Run grap preprocessor; implies -p. +

+
+
‘-h’
+

Display a usage message and exit. +

+
+
‘-i’
+

Read the standard input after all the named input files have been +processed. +

+
+
‘-Idir’
+

Search the directory dir for files named in several contexts; +implies -g and -s. +

+
    +
  • gsoelim replaces so requests with the contents of their +file name arguments. + +
  • gtroff searches for files named as operands in its command +line and as arguments to psbb, so, and soquiet +requests. + +
  • Output drivers may search for files; for instance, grops looks +for files named in ‘\X'ps: import …'’, ‘\X'ps: file +…'’, and ‘\X'pdf: pdfpic …'’ device control +escape sequences. +
+ +

This option may be specified more than once; the directories are +searched in the order specified. If you want to search the current +directory before others, add ‘-I .’ at the desired place. The +current working directory is otherwise searched last. -I works +similarly to, and is named for, the “include” option of Unix C +compilers. +

+

-I options are passed to gsoelim, gtroff, +and output drivers; with the flag letter changed to -M, they +are also passed to ggrn. +

+
+
‘-j’
+

Run gchem preprocessor. Implies -p. +

+
+
‘-k’
+

Run preconv preprocessor. Refer to its man page for its +behavior if neither of groff’s -K or -D +options is also specified. +

+
+
‘-Kenc’
+

Set input encoding used by preconv to enc; implies +-k. +

+
+
‘-l’
+

Send the output to a spooler for printing. The print directive +in the device description file specifies the default command to be used; +see Device and Font Description Files. +See options -L and -X. +

+
+
‘-Larg’
+

Pass arg to the print spooler program. If multiple args are +required, pass each with a separate -L option. groff +does not prefix an option dash to arg before passing it to the +spooler program. +

+
+
‘-mname’
+

Process the file name.tmac prior to any input files. +If not found, tmac.name is attempted. name +(in both arrangements) is presumed to be a macro file; see the +description of GROFF_TMAC_PATH in Environment below for the +default search locations and ordering. This option and its argument are +also passed to geqn, grap, and ggrn. +

+
+
‘-Mdir’
+

Search directory dir for macro files; see the description +of GROFF_TMAC_PATH in Environment below for the default +search locations and ordering. This option and its argument are also +passed to geqn, grap, and ggrn. +

+
+
‘-nnum’
+

Number the first page num. +

+
+
‘-N’
+

Prohibit newlines between eqn delimiters: pass -N to +geqn. +

+
+
‘-olist’
+

Output only pages in list, which is a comma-separated list of page +ranges; ‘n’ means page n, ‘m-n’ +means every page between m and n, ‘-n’ means +every page up to n, ‘n-’ means every page from +n on. gtroff stops processing and exits after +formatting the last page enumerated in list. +

+
+
‘-p’
+

Run gpic preprocessor. +

+
+
‘-Parg’
+

Pass arg to the postprocessor. If multiple args are +required, pass each with a separate -P option. groff +does not prefix an option dash to arg before passing it to the +postprocessor. +

+
+
‘-rcnumeric-expression’
+
‘-rregister=expr’
+

Set roff register c or register to the value +numeric-expression (see Numeric Expressions). +c must be one character; register can be of arbitrary +length. Such register assignments happen before any macro file is +loaded, including the startup file. Due to getopt_long +limitations, c cannot be, and register cannot contain, +an equals sign, even though that is a valid character in a roff +identifier. +

+
+
‘-R’
+

Run grefer preprocessor. No mechanism is provided for passing +arguments to grefer because most grefer options have +equivalent language elements that can be specified within the document. +

+ + +

gtroff also accepts a -R option, which is not +accessible via groff. This option prevents the loading of the +troffrc and troffrc-end files. +

+
+
‘-s’
+

Run gsoelim preprocessor. +

+
+
‘-S’
+
+ + + + + +

Operate in “safer” mode; see -U below for its opposite. For +security reasons, safer mode is enabled by default. +

+
+
‘-t’
+

Run gtbl preprocessor. +

+
+
‘-Tdev’
+

Direct gtroff to format the input for the output device +dev. groff then calls an output driver to convert +gtroff’s output to a form appropriate for dev. The +following output devices are available. +

+
+
ps
+

For PostScript printers and previewers. +

+
+
pdf
+

For PDF viewers or printers. +

+
+
dvi
+

For TeX DVI format. +

+
+
X75
+

For a 75dpi X11 previewer. +

+
+
X75-12
+

For a 75dpi X11 previewer with a 12-point base font in the +document. +

+
+
X100
+

For a 100dpi X11 previewer. +

+
+
X100-12
+

For a 100dpi X11 previewer with a 12-point base font in the +document. +

+
+
ascii
+
+ + + + +

For typewriter-like devices using the (7-bit) ASCII +(ISO 646) character set. +

+
+
latin1
+
+ + +

For typewriter-like devices that support the Latin-1 +(ISO 8859-1) character set. +

+
+
utf8
+
+ +

For typewriter-like devices that use the Unicode (ISO 10646) +character set with UTF-8 encoding. +

+
+
cp1047
+
+ + + + + + +

For typewriter-like devices that use the EBCDIC encoding IBM +code page 1047. +

+
+
lj4
+

For HP LaserJet4-compatible (or other PCL5-compatible) printers. +

+
+
lbp
+

For Canon CaPSL printers (LBP-4 and LBP-8 series laser +printers). +

+ + + +
+
html
+
xhtml
+

To produce HTML and XHTML output, respectively. +This driver consists of two parts, a preprocessor +(pre-grohtml) and a postprocessor (post-grohtml). +

+
+ + + +

The predefined GNU troff string .T contains the name of +the output device; the read-only register .T is set to 1 if +this option is used (which is always true if groff is used to +call GNU troff). See Built-in Registers. +

+

The postprocessor to be used for a device is specified by the +postpro command in the device description file. (See Device and Font Description Files.) This can be overridden with the +-X option. +

+
+
‘-U’
+
+

Operate in unsafe mode, which enables the open, +opena, pi, pso, and sy requests. These +requests are disabled by default because they allow an untrusted input +document to write to arbitrary file names and run arbitrary commands. +This option also adds the current directory to the macro package search +path; see the -m option above. -U is passed to +gpic and gtroff. +

+
+
‘-v’
+

Write version information for groff and all programs run by it +to the standard output stream; that is, the given command line is +processed in the usual way, passing -v to the formatter and any +pre- or postprocessors invoked. +

+
+
‘-V’
+

Output the pipeline that would be run by groff +(as a wrapper program) to the standard output stream, but do not execute +it. If given more than once, the pipeline is both written to the +standard error stream and run. +

+
+
‘-wcategory’
+

Enable warnings in category. Categories are listed in +Warnings. +

+
+
‘-Wcategory’
+

Inhibit warnings in category. Categories are listed in +Warnings. +

+
+
‘-X’
+

Use gxditview instead of the usual postprocessor to (pre)view +a document on an X11 display. Combining this option with +-Tps uses the font metrics of the PostScript device, whereas +the -TX75 and -TX100 options use the metrics of X11 +fonts. +

+
+
‘-z’
+

Suppress formatted output from gtroff. +

+
+
‘-Z’
+

Disable postprocessing. gtroff output will appear on the +standard output stream (unless suppressed with -z; see +gtroff Output for a description of this format. +

+
+ + + +
+
+
+

+Next: Environment, Previous: Invoking groff, Up: Invoking groff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Gtroff-Internals.html b/doc/groff.html.node/Gtroff-Internals.html new file mode 100644 index 0000000..2e38fe7 --- /dev/null +++ b/doc/groff.html.node/Gtroff-Internals.html @@ -0,0 +1,187 @@ + + + + + + +Gtroff Internals (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.36 gtroff Internals

+ + + + + +

gtroff processes input in three steps. One or more input +characters are converted to an input token.119 Then, one or more input tokens are converted to +an output node. Finally, output nodes are converted to the +intermediate output language understood by all output devices. +

+

Actually, before step one happens, gtroff converts certain escape +sequences into reserved input characters (not accessible by the user); +such reserved characters are used for other internal processing also – +this is the very reason why not all characters are valid input. +See Identifiers, for more on this topic. +

+

For example, the input string ‘fi\[:u]’ is converted into a +character token ‘f’, a character token ‘i’, and a special +token ‘:u’ (representing u umlaut). Later on, the character +tokens ‘f’ and ‘i’ are merged to a single output node +representing the ligature glyph ‘fi’ (provided the current font has +a glyph for this ligature); the same happens with ‘:u’. All output +glyph nodes are ‘processed’, which means that they are invariably +associated with a given font, font size, advance width, etc. During the +formatting process, gtroff itself adds various nodes to control +the data flow. +

+

Macros, diversions, and strings collect elements in two chained lists: a +list of input tokens that have been passed unprocessed, and a list of +output nodes. Consider the following diversion. +

+
+
.di xxx
+a
+\!b
+c
+.br
+.di
+
+ +

It contains these elements. +

+ + + + + + + + + + + + +
node listtoken listelement number
line start node—1
glyph node a—2
word space node—3
—b4
—\n5
glyph node c—6
vertical size node—7
vertical size node—8
—\n9
+ + +

Elements 1, 7, and 8 are inserted by gtroff; the latter two +(which are always present) specify the vertical extent of the last line, +possibly modified by \x. The br request finishes the +pending output line, inserting a newline input token, which is +subsequently converted to a space when the diversion is reread. Note +that the word space node has a fixed width that isn’t adjustable +anymore. To convert horizontal space nodes back to input tokens, use +the unformat request. +

+

Macros only contain elements in the token list (and the node list is +empty); diversions and strings can contain elements in both lists. +

+

The chop request simply reduces the number of elements in a +macro, string, or diversion by one. Exceptions are compatibility +save and compatibility ignore input tokens, which are ignored. +The substring request also ignores those input tokens. +

+

Some requests like tr or cflags work on glyph identifiers +only; this means that the associated glyph can be changed without +destroying this association. This can be very helpful for substituting +glyphs. In the following example, we assume that glyph ‘foo’ isn’t +available by default, so we provide a substitution using the +fchar request and map it to input character ‘x’. +

+
+
.fchar \[foo] foo
+.tr x \[foo]
+
+ +

Now let us assume that we install an additional special font ‘bar’ +that has glyph ‘foo’. +

+
+
.special bar
+.rchar \[foo]
+
+ +

Since glyphs defined with fchar are searched before glyphs in +special fonts, we must call rchar to remove the definition of the +fallback glyph. Anyway, the translation is still active; ‘x’ now +maps to the real glyph ‘foo’. +

+ + + + + + +

Macro and request arguments preserve compatibility mode enablement. +

+
+
.cp 1     \" switch to compatibility mode
+.de xx
+\\$1
+..
+.cp 0     \" switch compatibility mode off
+.xx caf\['e]
+    ⇒ café
+
+ +

Since compatibility mode is enabled while de is invoked, the +macro xx enables compatibility mode when it is called. Argument +$1 can still be handled properly because it inherits the +compatibility mode enablement status that was active at the point where +xx was called. +

+

After interpolation of the parameters, the compatibility save and +restore tokens are removed. +

+ + + +
+
+
+

+Next: Debugging, Previous: Miscellaneous, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Headers-and-Footers.html b/doc/groff.html.node/Headers-and-Footers.html new file mode 100644 index 0000000..5d1c50a --- /dev/null +++ b/doc/groff.html.node/Headers-and-Footers.html @@ -0,0 +1,61 @@ + + + + + + +Headers and Footers (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.3 Headers and Footers

+ +

Headers and footers occupy the top and bottom of +each page, respectively, and contain data like the page number and the +article or chapter title. Their appearance is not affected by the +running text. Some packages allow for different titles on even- and +odd-numbered pages (for printed, bound material). +

+

Headers and footers are together called titles, and comprise +three parts: left-aligned, centered, and right-aligned. A ‘%’ +character appearing anywhere in a title is automatically replaced by the +page number. See Page Layout. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Headings-in-ms.html b/doc/groff.html.node/Headings-in-ms.html new file mode 100644 index 0000000..a5d0cc7 --- /dev/null +++ b/doc/groff.html.node/Headings-in-ms.html @@ -0,0 +1,214 @@ + + + + + + +Headings in ms (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+
+

4.6.5.4 Headings

+ + +

Use headings to create a sequential or hierarchical structure for your +document. The ms macros print headings in bold using +the same font family and, by default, type size as the body text. +Headings are available with and without automatic numbering. Text on +input lines following the macro call becomes the heading’s title. Call +a paragraphing macro to end the heading text and start the section’s +content. +

+
+
Macro: .NH [depth]
+
+
Macro: .NH S heading-depth-index …
+

Set an automatically numbered heading. +

+

ms produces a numbered heading the form a.b.c…, to +any depth desired, with the numbering of each depth increasing +automatically and being reset to zero when a more significant level is +increased. “1” is the most significant or coarsest division of +the document. Only non-zero values are output. If depth is +omitted, it is taken to be ‘1’. +

+

If you specify depth such that an ascending gap occurs relative to +the previous NH call—that is, you “skip a depth”, as by +‘.NH 1’ and then ‘.NH 3’—groff ms emits a +warning on the standard error stream. +

+

Alternatively, you can give NH a first argument of S, +followed by integers to number the heading depths explicitly. Further +automatic numbering, if used, resumes using the specified indices as +their predecessors. +This feature is a Berkeley extension. +

+ +

An example may be illustrative. +

+
+
+
.NH 1
+Animalia
+.NH 2
+Arthropoda
+.NH 3
+Crustacea
+.NH 2
+Chordata
+.NH S 6 6 6
+Daimonia
+.NH 1
+Plantae
+
+
+ +

The above results in numbering as follows; the vertical space that +normally precedes each heading is omitted. +

+
+
1.  Animalia
+1.1.  Arthropoda
+1.1.1.  Crustacea
+1.2.  Chordata
+6.6.6.  Daimonia
+7.  Plantae
+
+ +
+
String: \*[SN-STYLE]
+
+
String: \*[SN-DOT]
+
+
String: \*[SN-NO-DOT]
+
+
String: \*[SN]
+
+

After NH is called, the assigned number is made available in the +strings SN-DOT (as it appears in a printed heading with default +formatting, followed by a terminating period) and SN-NO-DOT (with +the terminating period omitted). These are GNU extensions. +

+

You can control the style used to print numbered headings by defining an +appropriate alias for the string SN-STYLE. By default, +SN-STYLE is aliased to SN-DOT. If you prefer to omit the +terminating period from numbers appearing in numbered headings, you may +define the alias as follows. +

+
+
.als SN-STYLE SN-NO-DOT
+
+ +

Any such change in numbering style becomes effective from the next use +of NH following redefinition of the alias for SN-STYLE. +The formatted number of the current heading is available in the +SN string (a feature first documented by Berkeley), which +facilitates its inclusion in, for example, table captions, equation +labels, and XS/XA/XE table of contents entries. +

+ +
+
Macro: .SH [depth]
+
+

Set an unnumbered heading. +

+

The optional depth argument is a GNU extension indicating the +heading depth corresponding to the depth argument of NH. +It matches the type size at which the heading is set to that of a +numbered heading at the same depth when the GROWPS and +PSINCR heading size adjustment mechanism is in effect. +

+ +

If the GROWPS register is set to a value greater than the +level argument to NH or SH, the type size of a +heading produced by these macros increases by PSINCR units over +the size specified by PS multiplied by the difference of +GROWPS and level. The value stored in PSINCR is +interpreted in groff basic units; the p scaling unit +should be employed when assigning a value specified in points. For +example, the sequence +

+
+
+
.nr PS 10
+.nr GROWPS 3
+.nr PSINCR 1.5p
+.NH 1
+Carnivora
+.NH 2
+Felinae
+.NH 3
+Felis catus
+.SH 2
+Machairodontinae
+
+
+ +

will cause “1. Carnivora” to be printed in 13-point text, followed by +“1.1. Felinae” in 11.5-point text, while “1.1.1. Felis catus” and +all more deeply nested heading levels will remain in the 10-point text +specified by the PS register. “Machairodontinae” is printed at +11.5 points, since it corresponds to heading level 2. +

+

The HORPHANS register operates in conjunction with the NH +and SH macros to inhibit the printing of isolated headings at the +bottom of a page; it specifies the minimum number of lines of an +immediately subsequent paragraph that must be kept on the same page as +the heading. If insufficient space remains on the current page to +accommodate the heading and this number of lines of paragraph text, a +page break is forced before the heading is printed. Any display macro +call or tbl, pic, or eqn region between the heading +and the subsequent paragraph suppresses this grouping. See Keeps, boxed keeps, and displays and Tables, figures, equations, and references. +

+ +
+
+
+

+Next: Typeface and decoration, Previous: Paragraphs, Up: Body Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Hyphenation.html b/doc/groff.html.node/Hyphenation.html new file mode 100644 index 0000000..ec22419 --- /dev/null +++ b/doc/groff.html.node/Hyphenation.html @@ -0,0 +1,66 @@ + + + + + + +Hyphenation (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+
+

5.1.3 Hyphenation

+ + +

When an output line is nearly full, it is uncommon for the next word +collected from the input to exactly fill it—typically, there is room +left over only for part of the next word. The process of splitting a +word so that it appears partially on one line (with a hyphen to indicate +to the reader that the word has been broken) with its remainder on the +next is hyphenation. Hyphenation points can be manually +specified; GNU troff also uses a hyphenation algorithm and +language-specific pattern files (based on those used in TeX) to +decide which words can be hyphenated and where. +

+

Hyphenation does not always occur even when the hyphenation rules for a +word allow it; it can be disabled, and when not disabled there are +several parameters that can prevent it in certain circumstances. +See Manipulating Hyphenation. +

+ +
+ + + + + diff --git a/doc/groff.html.node/I_002fO.html b/doc/groff.html.node/I_002fO.html new file mode 100644 index 0000000..92a7fc0 --- /dev/null +++ b/doc/groff.html.node/I_002fO.html @@ -0,0 +1,457 @@ + + + + + + +I/O (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.33 I/O

+ + + + + +

gtroff has several requests for including files: +

+
+
Request: .so file
+
+
Request: .soquiet file
+
+ + +

Replace the so request’s control line with the contents of the +file named by the argument, “sourcing” it. file is sought in +the directories specified by -I command-line option. If +file does not exist, a warning in category ‘file’ is produced +and the request has no further effect. See Warnings, for +information about the enablement and suppression of warnings. +

+

so can be useful for large documents; e.g., allowing each chapter +of a book to be kept in a separate file. However, files interpolated +with so are not preprocessed; to overcome this limitation, see +the gsoelim(1) man page. +

+

Since GNU troff replaces the entire control line with the +contents of a file, it matters whether file is terminated with a +newline or not. Assume that file xxx contains only the word +‘foo’ without a trailing newline. +

+
+
$ printf 'foo' > xxx
+
+The situation is
+.so xxx
+bar.
+    ⇒ The situation is foobar.
+
+ +

soquiet works the same way, except that no warning diagnostic is +issued if file does not exist. +

+ +
+
Request: .pso command
+
+

Read the standard output from the specified command and include +it in place of the pso request. +

+ + + + +

It is an error to use this request in safer mode, which is the +default. Invoke GNU troff or a front end with the -U +option to enable unsafe mode. +

+

The comment regarding a final newline for the so request is valid +for pso also. +

+ +
+
Request: .mso file
+
+
Request: .msoquiet file
+
+

Identical to the so and soquiet requests, respectively, +except that gtroff searches for the specified file in the +same directories as macro files for the -m command-line option. +If the file name to be included has the form name.tmac and +it isn’t found, these requests try to include tmac.name and +vice versa. +

+ +
+
Request: .trf file
+
+
Request: .cf file
+
+ + + + + + + + +

Transparently output the contents of file. Each line is output as +if it were preceded by \!; however, the lines are not +subject to copy mode interpretation. If the file does not end with a +newline, trf adds one. Both requests cause a break. +

+

When used in a diversion, these requests embed a node (see gtroff Internals) in it that, when reread, causes the contents of file +to be transparently copied to the output. In AT&T +troff, the contents of file are immediately copied to the +output regardless of whether there is a current diversion; this +behaviour is so anomalous that it must be considered a bug. +

+ + + +

While cf copies the contents of file completely +unprocessed, trf disallows characters such as NUL that are not +valid gtroff input characters (see Identifiers). +

+

For cf, within a diversion, “completely unprocessed” means that +each line of a file to be inserted is handled as if it were preceded by +\!\\!. +

+

To define a macro x containing the contents of +file f, use +

+
+
.ev 1
+.di x
+.trf f
+.di
+.ev
+
+ +

The calls to ev prevent the partially collected output line +from becoming part of the diversion (see Diversions). +

+ +
+
Request: .nx [file]
+
+ + + +

Force gtroff to continue processing of the file specified as an +argument. If no argument is given, immediately jump to the end of file. +

+ +
+
Request: .rd [prompt [arg1 arg2 …]]
+
+ + + +

Read from standard input, and include what is read as though it were +part of the input file. Text is read until a blank line is encountered. +

+

If standard input is a TTY input device (keyboard), write prompt +to standard error, followed by a colon (or send BEL for a beep if no +argument is given). +

+

Arguments after prompt are available for the input. For example, +the line +

+
+
.rd data foo bar
+
+ +

with the input ‘This is \$2.’ prints +

+
+
This is bar.
+
+
+ + + +

Using the nx and rd requests, it is easy to set up form +letters. The form letter template is constructed like this, putting the +following lines into a file called repeat.let: +

+
+
.ce
+\*(td
+.sp 2
+.nf
+.rd
+.sp
+.rd
+.fi
+Body of letter.
+.bp
+.nx repeat.let
+
+ + +

When this is run, a file containing the following lines should be +redirected in. Requests included in this file are executed as though +they were part of the form letter. The last block of input is the +ex request, which tells GNU troff to stop processing. If +this were not there, troff would not know when to stop. +

+
+
Trent A. Fisher
+708 NW 19th Av., #202
+Portland, OR  97209
+
+Dear Trent,
+
+Len Adollar
+4315 Sierra Vista
+San Diego, CA  92103
+
+Dear Mr. Adollar,
+
+.ex
+
+ +
+
Request: .pi pipe
+
+

Pipe the output of gtroff to the shell command(s) specified by +pipe. This request must occur before gtroff has a chance +to print anything. +

+ + + + +

It is an error to use this request in safer mode, which is the +default. Invoke GNU troff or a front end with the -U +option to enable unsafe mode. +

+

Multiple calls to pi are allowed, acting as a chain. For +example, +

+
+
.pi foo
+.pi bar
+...
+
+ +

is the same as ‘.pi foo | bar’. +

+ + +

The intermediate output format of GNU troff is piped to the +specified commands. Consequently, calling groff without the +-Z option normally causes a fatal error. +

+ + + +
+
Request: .sy cmds
+
+
Register: \n[systat]
+
+

Execute the shell command(s) specified by cmds. The output is not +saved anywhere, so it is up to the user to do so. +

+ + + + +

It is an error to use this request in safer mode; this is the default. +Give GNU troff or a front end program the -U option to +enable unsafe mode. +

+

The following code fragment introduces the current time into a document. +

+ +
+
.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
+             (localtime(time))[2,1,0]' > /tmp/x\n[$$]
+.so /tmp/x\n[$$]
+.sy rm /tmp/x\n[$$]
+\nH:\nM:\nS
+
+ +

This works by having the Perl script (run by sy) write +nr requests that set the registers H, M, and +S to a temporary file. The roff document then reads the +temporary file using the so request. +

+ + +

The registers seconds, minutes, and hours, +initialized at startup of GNU troff, should satisfy most +requirements. Use the af request to format their values for +output. +

+
+
.af hours 00
+.af minutes 00
+.af seconds 00
+\n[hours]:\n[minutes]:\n[seconds]
+    ⇒ 02:17:54
+
+ + +

The writable register systat contains the return value of the +system() function executed by the last sy request. +

+ +
+
Request: .open stream file
+
+
Request: .opena stream file
+
+ + + + +

Open the specified file for writing and associates the specified +stream with it. +

+

The opena request is like open, but if the file exists, +append to it instead of truncating it. +

+ + + + +

It is an error to use these requests in safer mode; this is the default. +Give GNU troff or a front end program the -U option to +enable unsafe mode. +

+ +
+
Request: .write stream data
+
+
Request: .writec stream data
+
+ + + + + + + + +

Write to the file associated with the specified stream. The +stream must previously have been the subject of an open request. The +remainder of the line is interpreted as the ds request reads its +second argument: an initial neutral double quote in contents is +stripped to allow embedding of leading spaces, and it is read in copy +mode. +

+

The writec request is like write, but only write +appends a newline to the data. +

+ +
+
Request: .writem stream xx
+
+ +

Write the contents of the macro or string xx to the file +associated with the specified stream. +

+ + + +

xx is read in copy mode, i.e., already formatted elements are +ignored. Consequently, diversions must be unformatted with the +asciify request before calling writem. Usually, this +means a loss of information. +

+ +
+
Request: .close stream
+
+ + +

Close the specified stream; the stream is no longer an acceptable +argument to the write request. +

+

Here a simple macro to write an index entry. +

+
+
.open idx test.idx
+.
+.de IX
+.  write idx \\n[%] \\$*
+..
+.
+.IX test entry
+.
+.close idx
+
+
+ +
+
Escape sequence: \Ve
+
+
Escape sequence: \V(ev
+
Escape sequence: \V[env]
+
+ + +

Interpolate the contents of the specified environment variable env +(one-character name e, two-character name ev) as +returned by the function getenv(3). \V is interpreted +even in copy mode (see Copy Mode). +

+ + + +
+
+
+

+Next: Postprocessor Access, Previous: Suppressing Output, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Identifiers.html b/doc/groff.html.node/Identifiers.html new file mode 100644 index 0000000..5734bb5 --- /dev/null +++ b/doc/groff.html.node/Identifiers.html @@ -0,0 +1,210 @@ + + + + + + +Identifiers (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.5 Identifiers

+ + +

An identifier labels a GNU troff datum such as a register, +name (macro, string, or diversion), typeface, color, special character, +character class, environment, or stream. Valid identifiers consist of +one or more ordinary characters. + + +An ordinary character is an input character that is not the +escape character, a leader, tab, newline, or invalid as GNU troff +input. +

+ + + + +

Invalid input characters are a subset of control characters (from the +sets “C0 Controls” and “C1 Controls” as Unicode describes them). +When GNU troff encounters one in an identifier, it produces a +warning in category ‘input’ (see Warnings). They are removed +during interpretation: an identifier ‘foo’, followed by an invalid +character and then ‘bar’, is processed as ‘foobar’. +

+

On a machine using the ISO 646, 8859, or 10646 character encodings, +invalid input characters are 0x00, 0x08, 0x0B, +0x0D–0x1F, and 0x80–0x9F. On an +EBCDIC host, they are 0x00–0x01, 0x08, +0x09, 0x0B, 0x0D–0x14, +0x17–0x1F, and +0x30–0x3F.40 Some of these code points are used +by GNU troff internally, making it non-trivial to extend the +program to accept UTF-8 or other encodings that use characters from +these ranges.41 +

+

Thus, the identifiers ‘br’, ‘PP’, ‘end-list’, +‘ref*normal-print’, ‘|’, ‘@_’, and ‘!"#$%'()*+,-./’ +are all valid. Discretion should be exercised to prevent confusion. +Identifiers starting with ‘(’ or ‘[’ require care. +

+
+
.nr x 9
+.nr y 1
+.nr (x 2
+.nr [y 3
+.nr sum1 (\n(x + \n[y])
+    error→ a space character is not allowed in an escape
+    error→   sequence parameter
+A:2+3=\n[sum1]
+.nr sum2 (\n((x + \n[[y])
+B:2+3=\n[sum2]
+.nr sum3 (\n[(x] + \n([y)
+C:2+3=\n[sum3]
+    ⇒ A:2+3=1 B:2+3=5 C:2+3=5
+
+ + +

An identifier with a closing bracket (‘]’) in its name can’t be +accessed with bracket-form escape sequences that expect an identifier as +a parameter. For example, ‘\[foo]]’ accesses the glyph ‘foo’, +followed by ‘]’ in whatever the surrounding context is, whereas +‘\C'foo]'’ formats a glyph named ‘foo]’. Similarly, the +identifier ‘(’ can’t be interpolated except with bracket +forms. +

+ + + + +

If you begin a macro, string, or diversion name with either of the +characters ‘[’ or ‘]’, you foreclose use of the grefer +preprocessor, which recognizes ‘.[’ and ‘.]’ as bibliographic +reference delimiters. +

+
+
Escape sequence: \A'anything'
+
+

Interpolate 1 if anything is a valid identifier, and 0 +otherwise. The delimiter need not be a neutral apostrophe; see +Delimiters. Because invalid input characters are removed (see +above), invalid identifiers are empty or contain spaces, tabs, or +newlines. +

+

You can employ \A to validate a macro argument before using it to +construct another escape sequence or identifier. +

+
+
.\" usage: .init-coordinate-pair name val1 val2
+.\" Create a coordinate pair where name!x=val1 and
+.\" name!y=val2.
+.de init-coordinate-pair
+.  if \A'\\$1' \{\
+.    if \B'\\$2' .nr \\$1!x \\$2
+.    if \B'\\$3' .nr \\$1!y \\$3
+.  \}
+..
+.init-coordinate-pair center 5 10
+The center is at (\n[center!x], \n[center!y]).
+.init-coordinate-pair "poi→nt" trash garbage \" ignored
+.init-coordinate-pair point trash garbage \" ignored
+    ⇒ The center is at (5, 10).
+
+ +

In this example, we also validated the numeric arguments; the registers +‘point!x’ and ‘point!y’ remain undefined. See Numeric Expressions for the \B escape sequence. +

+ + + +

How GNU troff handles the interpretation of an undefined +identifier depends on the context. There is no way to invoke an +undefined request; such syntax is interpreted as a macro call instead. +If the identifier is interpreted as a string, macro, or diversion, GNU +troff emits a warning in category ‘mac’, defines it as +empty, and interpolates nothing. If the identifier is interpreted as a +register, GNU troff emits a warning in category ‘reg’, +initializes it to zero, and interpolates that value. See Warnings, +Interpolating Registers, and Strings. Attempting to use an +undefined typeface, special character, color, character class, +environment, or stream generally provokes an error diagnostic. +

+ + + + + +

Identifiers for requests, macros, strings, and diversions share one name +space; special characters and character classes another. No other +object types do. +

+
+
.de xxx
+.  nop foo
+..
+.di xxx
+bar
+.br
+.di
+.
+.xxx
+    ⇒ bar
+
+ +

The foregoing example shows that GNU troff reuses the identifier +‘xxx’, changing it from a macro to a diversion. No warning is +emitted, and the previous contents of ‘xxx’ are lost. +

+ + +
+
+
+

+Next: Formatter Instructions, Previous: Numeric Expressions, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Implementation-Differences.html b/doc/groff.html.node/Implementation-Differences.html new file mode 100644 index 0000000..4645778 --- /dev/null +++ b/doc/groff.html.node/Implementation-Differences.html @@ -0,0 +1,64 @@ + + + + + + +Implementation Differences (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.38 Implementation Differences

+ + + + +

GNU troff has a number of features that cause incompatibilities +with documents written for other versions of troff. Some GNU +extensions to troff have become supported by other +implementations. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/Indented-regions-in-ms.html b/doc/groff.html.node/Indented-regions-in-ms.html new file mode 100644 index 0000000..44c648f --- /dev/null +++ b/doc/groff.html.node/Indented-regions-in-ms.html @@ -0,0 +1,112 @@ + + + + + + +Indented regions in ms (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+
+

4.6.5.7 Indented regions

+ +

You may need to indent a region of text while otherwise formatting it +normally. Indented regions can be nested; you can change \n[PI] +before each call to vary the amount of inset. +

+
+
Macro: .RS
+
+

Begin a region where headings, paragraphs, and displays are indented +(further) by the amount stored in the PI register. +

+ +
+
Macro: .RE
+
+

End the (next) most recent indented region. +

+ +

This feature enables you to easily line up text under hanging and +indented paragraphs. + + +For example, you may wish to structure lists hierarchically. +

+
+
+
.IP \[bu] 2
+Lawyers:
+.RS
+.IP \[bu]
+Dewey,
+.IP \[bu]
+Cheatham,
+and
+.IP \[bu]
+and Howe.
+.RE
+.IP \[bu]
+Guns
+
+
+ +
+
• Lawyers:
+
+  •  Dewey,
+
+  •  Cheatham, and
+
+  •  Howe.
+
+• Guns
+
+ + +
+ + + + + diff --git a/doc/groff.html.node/Indexing.html b/doc/groff.html.node/Indexing.html new file mode 100644 index 0000000..26895ca --- /dev/null +++ b/doc/groff.html.node/Indexing.html @@ -0,0 +1,58 @@ + + + + + + +Indexing (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.8 Indexing

+ + + +

An index is similar to a table of contents, in that entry labels and +locations must be collected, but poses a greater challenge because it +needs to be sorted before it is output. Here, processing the document +in multiple passes is inescapable, and tools like the makeindex +program are necessary. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Input-Conventions.html b/doc/groff.html.node/Input-Conventions.html new file mode 100644 index 0000000..35005bd --- /dev/null +++ b/doc/groff.html.node/Input-Conventions.html @@ -0,0 +1,171 @@ + + + + + + +Input Conventions (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Text   [Contents][Index]

+
+
+

5.1.10 Input Conventions

+ + + +

Since GNU troff fills text automatically, it is common practice +in the roff language to avoid visual composition of text in input +files: the esthetic appeal of the formatted output is what matters. +Therefore, roff input should be arranged such that it is easy for +authors and maintainers to compose and develop the document, understand +the syntax of roff requests, macro calls, and preprocessor +languages used, and predict the behavior of the formatter. Several +traditions have accrued in service of these goals. +

+
    +
  • Follow sentence endings in the input with newlines to ease their +recognition (see Sentences). It is frequently convenient to end +text lines after colons and semicolons as well, as these typically +precede independent clauses. Consider doing so after commas; they often +occur in lists that become easy to scan when itemized by line, or +constitute supplements to the sentence that are added, deleted, or +updated to clarify it. Parenthetical and quoted phrases are also good +candidates for placement on text lines by themselves. + +
  • Set your text editor’s line length to 72 characters or +fewer.32 +This limit, combined with the previous item of advice, makes it less +common that an input line will wrap in your text editor, and thus will +help you perceive excessively long constructions in your text. Recall +that natural languages originate in speech, not writing, and that +punctuation is correlated with pauses for breathing and changes in +prosody. + +
  • Use \& after ‘!’, ‘?’, and ‘.’ if they are +followed by space, tab, or newline characters and don’t end a sentence. + +
  • In filled text lines, use \& before ‘.’ and ‘'’ if they +are preceded by space, so that reflowing the input doesn’t turn them +into control lines. + +
  • Do not use spaces to perform indentation or align columns of a table. +Leading spaces are reliable when text is not being filled. + +
  • Comment your document. It is never too soon to apply comments to +record information of use to future document maintainers (including your +future self). We thus introduce another escape sequence, \", +which causes GNU troff to ignore the remainder of the input line. + +
  • Use the empty request—a control character followed immediately by a +newline—to visually manage separation of material in input files. +Many of the groff project’s own documents use an empty request +between sentences, after macro definitions, and where a break is +expected, and two empty requests between paragraphs or other requests or +macro calls that will introduce vertical space into the document. + +

    You can combine the empty request with the comment escape sequence to +include whole-line comments in your document, and even “comment out” +sections of it. +

+ +

We conclude this section with an example sufficiently long to illustrate +most of the above suggestions in practice. For the purpose of fitting +the example between the margins of this manual with the font used for +its typeset version, we have shortened the input line length to 56 +columns. As before, an arrow → indicates a tab character. +

+
+
+
.\"   nroff this_file.roff | less
+.\"   groff -T ps this_file.roff > this_file.ps
+→The theory of relativity is intimately connected with
+the theory of space and time.
+.
+I shall therefore begin with a brief investigation of
+the origin of our ideas of space and time,
+although in doing so I know that I introduce a
+controversial subject.  \" remainder of paragraph elided
+.
+.
+
+→The experiences of an individual appear to us arranged
+in a series of events;
+in this series the single events which we remember
+appear to be ordered according to the criterion of
+\[lq]earlier\[rq] and \[lq]later\[rq], \" punct swapped
+which cannot be analysed further.
+.
+There exists,
+therefore,
+for the individual,
+an I-time,
+or subjective time.
+.
+This itself is not measurable.
+.
+I can,
+indeed,
+associate numbers with the events,
+in such a way that the greater number is associated with
+the later event than with an earlier one;
+but the nature of this association may be quite
+arbitrary.
+.
+This association I can define by means of a clock by
+comparing the order of events furnished by the clock
+with the order of a given series of events.
+.
+We understand by a clock something which provides a
+series of events which can be counted,
+and which has other properties of which we shall speak
+later.
+.\" Albert Einstein, _The Meaning of Relativity_, 1922
+
+
+ +
+
+
+

+Previous: Input Encodings, Up: Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Input-Encodings.html b/doc/groff.html.node/Input-Encodings.html new file mode 100644 index 0000000..f9ef79d --- /dev/null +++ b/doc/groff.html.node/Input-Encodings.html @@ -0,0 +1,154 @@ + + + + + + +Input Encodings (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+
+

5.1.9 Input Encodings

+ +

The groff command’s -k option calls the +preconv preprocessor to perform input character encoding +conversions. Input to the GNU troff formatter itself, on the +other hand, must be in one of two encodings it can recognize. +

+
+
cp1047
+
+ + + + + + +

The code page 1047 input encoding works only on EBCDIC +platforms (and conversely, the other input encodings don’t work with +EBCDIC); the file cp1047.tmac is loaded at startup. +

+
+
latin1
+
+ + + +

ISO Latin-1, an encoding for Western European languages, is the +default input encoding on non-EBCDIC platforms; the file +latin1.tmac is loaded at startup. +

+
+ +

Any document that is encoded in ISO 646:1991 (a descendant of USAS +X3.4-1968 or “US-ASCII”), or, equivalently, uses only code points +from the “C0 Controls” and “Basic Latin” parts of the Unicode +character set is also a valid ISO Latin-1 document; the standards +are interchangeable in their first 128 code points.30 +

+

Other encodings are supported by means of macro packages. +

+
+
latin2
+
+ + + +

To use ISO Latin-2, an encoding for Central and Eastern European +languages, invoke ‘.mso latin2.tmac’ at the beginning of your +document or supply ‘-mlatin2’ as a command-line argument to +groff. +

+
+
latin5
+
+ + + +

To use ISO Latin-5, an encoding for the Turkish language, invoke +‘.mso latin5.tmac’ at the beginning of your document or +supply ‘-mlatin5’ as a command-line argument to groff. +

+
+
latin9
+
+ + + +

ISO Latin-9 succeeds Latin-1; it includes a Euro sign and better +glyph coverage for French. To use this encoding, invoke ‘.mso latin9.tmac’ at the beginning of your document or supply +‘-mlatin9’ as a command-line argument to groff. +

+
+ +

Some characters from an input encoding may not be available with a +particular output driver, or their glyphs may not have representation in +the font used. For terminal devices, fallbacks are defined, like +‘EUR’ for the Euro sign and ‘(C)’ for the copyright sign. For +typesetter devices, you may need to “mount” fonts that support glyphs +required by the document. See Font Positions. +

+ + +

Because a Euro glyph was not historically defined in PostScript fonts, +groff comes with a font called freeeuro.pfa that provides +the Euro in several styles. Standard PostScript fonts contain the +glyphs from Latin-5 and Latin-9 that Latin-1 lacks, so these +encodings are supported for the ps and pdf output +devices as groff ships, while Latin-2 is not. +

+

Unicode supports characters from all other input encodings; the +utf8 output driver for terminals therefore does as well. The +DVI output driver supports the Latin-2 and Latin-9 encodings if +the command-line option -mec is used as well. 31 +

+ +
+
+
+

+Next: Input Conventions, Previous: Macro Packages, Up: Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Input-Line-Traps.html b/doc/groff.html.node/Input-Line-Traps.html new file mode 100644 index 0000000..f0d7fef --- /dev/null +++ b/doc/groff.html.node/Input-Line-Traps.html @@ -0,0 +1,185 @@ + + + + + + +Input Line Traps (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Traps   [Contents][Index]

+
+
+

5.28.2 Input Line Traps

+ + + +
+
Request: .it [n name]
+
+
Request: .itc [n name]
+
+ + + + + + +

Set an input line trap, calling macro name after processing the +next n productive input lines (recall Manipulating Filling and Adjustment). Any existing input line trap in the +environment is replaced. Without arguments, it and itc +clear any input line trap that has not yet sprung. +

+

Consider a macro ‘.ST s n’ which sets the next +n input lines in the font style s. +

+
+
.de ST \" Use style $1 for next $2 text lines.
+.  it \\$2 ES
+.  ft \\$1
+..
+.de ES \" end ST
+.  ft R
+..
+.ST I 1
+oblique
+face
+.ST I 1
+oblique\c
+face
+    ⇒ oblique face obliqueface  (second “face” upright)
+
+ + + + + +

Unlike the ce and rj requests, it counts lines +interrupted with the \c escape sequence separately (see Line Continuation); itc does not. To see the difference, let’s +change the previous example to use itc instead. +

+
+
…
+.  itc \\$2 ES
+…
+    ⇒ oblique face obliqueface  (second “face” oblique)
+
+ +

You can think of the ce and rj requests as implicitly +creating an input line trap with itc that schedules a break when +the trap is sprung. +

+
+
.de BR
+.  br
+.  internal: disable centering-without-filling
+..
+.
+.de ce
+.  if \\n[.br] .br
+.  itc \\$1 BR
+.  internal: enable centering-without-filling
+..
+
+ +

Let us consider in more detail the sorts of input lines that are or are +not “productive”. +

+
+
.de Trap
+TRAP SPRUNG
+..
+.de Mac
+.if r a \l'5n'
+..
+.it 2 Trap
+.
+foo
+.Mac
+bar
+baz
+.it 1 Trap
+.sp \" moves, but does not write or draw
+qux
+.itc 1 Trap
+\h'5n'\c \" moves, but does not write or draw
+jat
+
+ +

When ‘Trap’ gets called depends on whether the ‘a’ register is +defined; the control line with the if request may or may not +produce written output. We also see that the spacing request sp, +while certainly affecting the output, does not spring the input line +trap. Similarly, the horizontal motion escape sequence \h also +affected the output, but was not “written”. Observe that we had to +follow it with \c and use itc to prevent the newline at +the end of the text line from causing a word break, which, like an +ordinary space character, counts as written output. +

+
+
$ groff -Tascii input-trap-example.groff
+    ⇒ foo bar TRAP SPRUNG baz
+    ⇒
+    ⇒ qux TRAP SPRUNG      jat TRAP SPRUNG
+$ groff -Tascii -ra1 input-trap-example.groff
+    ⇒ foo _____ TRAP SPRUNG bar baz
+    ⇒
+    ⇒ qux TRAP SPRUNG      jat TRAP SPRUNG
+
+
+ +

Input line traps are associated with the environment +(see Environments); switching to another environment suspends the +current input line trap, and going back resumes it, restoring the count +of qualifying lines enumerated in that environment. +

+ +
+
+
+

+Next: Blank Line Traps, Previous: Diversion Traps, Up: Traps   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Installation.html b/doc/groff.html.node/Installation.html new file mode 100644 index 0000000..659fdce --- /dev/null +++ b/doc/groff.html.node/Installation.html @@ -0,0 +1,57 @@ + + + + + + +Installation (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+
+

1.7 Installation

+ + +

Locate installation instructions in the files INSTALL, +INSTALL.extra, and INSTALL.REPO in the groff source +distribution. Being a GNU project, groff supports the familiar +‘./configure && make’ command sequence. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Intermediate-Output-Examples.html b/doc/groff.html.node/Intermediate-Output-Examples.html new file mode 100644 index 0000000..0947e86 --- /dev/null +++ b/doc/groff.html.node/Intermediate-Output-Examples.html @@ -0,0 +1,171 @@ + + + + + + +Intermediate Output Examples (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: gtroff Output   [Contents][Index]

+
+
+

6.1.3 Intermediate Output Examples

+ +

This section presents the intermediate output generated from the same +input for three different devices. The input is the sentence ‘hell +world’ fed into gtroff on the command line. +

+
+
High-resolution device ps
+
+

This is the standard output of gtroff if no -T option is +given. +

+
+
shell> echo "hell world" | groff -Z -T ps
+
+x T ps
+x res 72000 1 1
+x init
+
p1
+x font 5 TR
+f5
+s10000
+V12000
+H72000
+thell
+wh2500
+tw
+H96620
+torld
+n12000 0
+
x trailer
+V792000
+x stop
+
+ +

This output can be fed into grops to get its representation as a +PostScript file. +

+
+
Low-resolution device latin1
+
+

This is similar to the high-resolution device except that the +positioning is done at a minor scale. Some comments (lines starting +with ‘#’) were added for clarification; they were not generated by +the formatter. +

+
+
shell> echo "hell world" | groff -Z -T latin1
+
+# prologue
+x T latin1
+x res 240 24 40
+x init
+
# begin a new page
+p1
+# font setup
+x font 1 R
+f1
+s10
+# initial positioning on the page
+V40
+H0
+# write text 'hell'
+thell
+# inform about space, and issue a horizontal jump
+wh24
+# write text 'world'
+tworld
+# announce line break, but do nothing because...
+n40 0
+
# ...the end of the document has been reached
+x trailer
+V2640
+x stop
+
+ +

This output can be fed into grotty to get a formatted text +document. +

+
+
AT&T troff output
+

Since a computer monitor has a much lower resolution than modern +printers, the intermediate output for X11 devices can use the +jump-and-write command with its 2-digit displacements. +

+
+
shell> echo "hell world" | groff -Z -T X100
+
+x T X100
+x res 100 1 1
+x init
+
p1
+x font 5 TR
+f5
+s10
+V16
+H100
+# write text with jump-and-write commands
+ch07e07l03lw06w11o07r05l03dh7
+n16 0
+
x trailer
+V1100
+x stop
+
+ +

This output can be fed into xditview or gxditview for +displaying in X. +

+

Due to the obsolete jump-and-write command, the text clusters in the +AT&T troff output are almost unreadable. +

+
+ + +
+
+
+

+Next: Output Language Compatibility, Previous: Command Reference, Up: gtroff Output   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Interpolating-Registers.html b/doc/groff.html.node/Interpolating-Registers.html new file mode 100644 index 0000000..21d01f8 --- /dev/null +++ b/doc/groff.html.node/Interpolating-Registers.html @@ -0,0 +1,99 @@ + + + + + + +Interpolating Registers (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Registers   [Contents][Index]

+
+
+

5.8.2 Interpolating Registers

+ + + +

Register contents are interpolated with the \n escape sequence. +

+
+
Escape sequence: \ni
+
+
Escape sequence: \n(id
+
Escape sequence: \n[ident]
+
+ + + +

Interpolate register with name ident (one-character +name i, two-character name id). \n is +interpreted even in copy mode (see Copy Mode). If the register is +undefined, it is created and assigned a value of ‘0’, that +value is interpolated, and a warning in category ‘reg’ is emitted. +See Warnings, for information about the enablement and suppression of +warnings. +

+
+
.nr a 5
+.nr as \na+\na
+\n(as
+    ⇒ 10
+
+ +
+
.nr a1 5
+.nr ab 6
+.ds str b
+.ds num 1
+\n[a\n[num]]
+    ⇒ 5
+\n[a\*[str]]
+    ⇒ 6
+
+
+ + +
+ + + + + diff --git a/doc/groff.html.node/Introduction.html b/doc/groff.html.node/Introduction.html new file mode 100644 index 0000000..65499fc --- /dev/null +++ b/doc/groff.html.node/Introduction.html @@ -0,0 +1,68 @@ + + + + + + +Introduction (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

1 Introduction

+ + +

GNU roff (or groff) is a programming system for +typesetting documents. It is highly flexible and has been used +extensively for over thirty years. +

+ + + + +
+ + + + + diff --git a/doc/groff.html.node/Invocation-Examples.html b/doc/groff.html.node/Invocation-Examples.html new file mode 100644 index 0000000..c72781d --- /dev/null +++ b/doc/groff.html.node/Invocation-Examples.html @@ -0,0 +1,120 @@ + + + + + + +Invocation Examples (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Invoking groff   [Contents][Index]

+
+
+

2.6 Invocation Examples

+ + + +

roff systems are best known for formatting man pages. Once a +man librarian program has located a man page, it may execute +a groff command much like the following. +

+
+
groff -t -man -Tutf8 /usr/share/man/man1/groff.1
+
+ +

The librarian will also pipe the output through a pager, which might not +interpret the SGR terminal escape sequences groff emits for +boldface, underlining, or italics; see the grotty(1) man page +for a discussion. +

+

To process a roff input file using the preprocessors +gtbl and gpic and the me macro package in the +way to which AT&T troff users were accustomed, one would type (or +script) a pipeline. +

+
+
gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty
+
+ +

Using groff, this pipe can be shortened to an equivalent +command. +

+
+
groff -p -t -me -T utf8 foo.me
+
+ +

An even easier way to do this is to use grog to guess the +preprocessor and macro options and execute the result by using the +command substitution feature of the shell. +

+
+
$(grog -Tutf8 foo.me)
+
+ +

Each command-line option to a postprocessor must be specified with any +required leading dashes ‘-’ +because groff passes the arguments as-is to the postprocessor; +this permits arbitrary arguments to be transmitted. For example, to +pass a title to the gxditview postprocessor, +the shell commands +

+
+
groff -X -P -title -P 'trial run' mydoc.t
+
+ +

and +

+
+
groff -X -Z mydoc.t | gxditview -title 'trial run' -
+
+ +

are equivalent. +

+ + + +
+
+
+

+Previous: Paper Format, Up: Invoking groff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Invoking-Requests.html b/doc/groff.html.node/Invoking-Requests.html new file mode 100644 index 0000000..1864553 --- /dev/null +++ b/doc/groff.html.node/Invoking-Requests.html @@ -0,0 +1,143 @@ + + + + + + +Invoking Requests (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Formatter Instructions   [Contents][Index]

+
+
+

5.6.2 Invoking Requests

+ + + +

A control character is optionally followed by tabs and/or spaces and +then an identifier naming a request or macro. The invocation of an +unrecognized request is interpreted as a macro call. Defining a macro +with the same name as a request replaces the request. Deleting a +request name with the rm request makes it unavailable. The +als request can alias requests, permitting them to be wrapped or +non-destructively replaced. See Strings. +

+ + + + + + + + +

There is no inherent limit on argument length or quantity. Most +requests take one or more arguments, and ignore any they do not expect. +A request may be separated from its arguments by tabs or spaces, but +only spaces can separate an argument from its successor. Only one +between arguments is necessary; any excess is ignored. GNU troff +does not allow tabs for argument separation.43 +

+

Generally, a space within a request argument is not relevant, not +meaningful, or is supported by bespoke provisions, as with the tl +request’s delimiters (see Page Layout). Some requests, like +ds, interpret the remainder of the control line as a single +argument. See Strings. +

+ + + + + +

Spaces and tabs immediately after a control character are ignored. +Commonly, authors structure the source of documents or macro files with +them. +

+
+
.de center
+.  if \\n[.br] \
+.    br
+.  ce \\$1
+..
+.
+.
+.de right-align
+.→if \\n[.br] \
+.→→br
+.→rj \\$1
+..
+
+ + + +

If you assign an empty blank line trap, you can separate macro +definitions (or any input lines) with blank lines. +

+
+
.de do-nothing
+..
+.blm do-nothing  \" activate blank line trap
+
+.de center
+.  if \\n[.br] \
+.    br
+.  ce \\$1
+..
+
+
+.de right-align
+.→if \\n[.br] \
+.→→br
+.→rj \\$1
+..
+
+.blm             \" deactivate blank line trap
+
+ +

See Blank Line Traps. +

+ +
+
+
+

+Next: Calling Macros, Previous: Control Characters, Up: Formatter Instructions   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Invoking-groff.html b/doc/groff.html.node/Invoking-groff.html new file mode 100644 index 0000000..a302025 --- /dev/null +++ b/doc/groff.html.node/Invoking-groff.html @@ -0,0 +1,82 @@ + + + + + + +Invoking groff (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

2 Invoking groff

+ + + +

This chapter focuses on how to invoke the groff front end. This +front end takes care of the details of constructing the pipeline among +the preprocessors, gtroff and the postprocessor. +

+

It has become a tradition that GNU programs get the prefix ‘g’ to +distinguish them from their original counterparts provided by the host +(see Environment). Thus, for example, geqn is GNU +eqn. On operating systems like GNU/Linux or the Hurd, which +don’t contain proprietary versions of troff, and on +MS-DOS/MS-Windows, where troff and associated programs are not +available at all, this prefix is omitted since GNU troff is the +only incarnation of troff used. Exception: ‘groff’ is never +replaced by ‘roff’. +

+

In this document, we consequently say ‘gtroff’ when talking about +the GNU troff program. All other implementations of troff are called AT&T +troff, which is the common origin of almost all troff +implementations4 (with more or less compatible changes). Similarly, we say +‘gpic’, ‘geqn’, and so on. +

+ + + + +
+ + + + + diff --git a/doc/groff.html.node/Italic-Corrections.html b/doc/groff.html.node/Italic-Corrections.html new file mode 100644 index 0000000..42620d8 --- /dev/null +++ b/doc/groff.html.node/Italic-Corrections.html @@ -0,0 +1,96 @@ + + + + + + +Italic Corrections (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+
+

5.19.9 Italic Corrections

+ +

When typesetting adjacent glyphs from typefaces of different slants, the +space between them may require adjustment. +

+
+
Escape sequence: \/
+
+ + + + + +

Apply an italic correction: modify the spacing of the preceding +glyph so that the distance between it and the following glyph is correct +if the latter is of upright shape. For example, if an +italic ‘f’ is followed immediately by a roman right +parenthesis, then in many fonts the top right portion of +the ‘f’ overlaps the top left of the right parenthesis, which +is ugly. Use this escape sequence whenever an oblique glyph is +immediately followed by an upright glyph without any intervening space. +

+ +
+
Escape sequence: \,
+
+ + + + + +

Apply a left italic correction: modify the spacing of the +following glyph so that the distance between it and the preceding +glyph is correct if the latter is of upright shape. For example, +if a roman left parenthesis is immediately followed by an +italic ‘f’, then in many fonts the bottom left portion of +the ‘f’ overlaps the bottom of the left parenthesis, which is +ugly. Use this escape sequence whenever an upright glyph is followed +immediately by an oblique glyph without any intervening space. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Language-Concepts.html b/doc/groff.html.node/Language-Concepts.html new file mode 100644 index 0000000..16badc5 --- /dev/null +++ b/doc/groff.html.node/Language-Concepts.html @@ -0,0 +1,70 @@ + + + + + + +Language Concepts (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: gtroff Output   [Contents][Index]

+
+
+

6.1.1 Language Concepts

+ +

The fundamental operation of the GNU troff formatter is the +translation of the groff input language into a device-independent +form primarily concerned with what has to be written or drawn at +specific positions on the output device. This language is simple and +imperative. In the following discussion, the term command always +refers to this intermediate output language, and never to the +groff language intended for direct use by document authors. +Intermediate output commands comprise several categories: glyph output; +font, color, and text size selection; motion of the printing position; +page advancement; drawing of geometric objects; and device control +commands, a catch-all for operations not easily classified as any of the +foregoing, such as directives to start and stop output, identify the +intended output device, or place URL hyperlinks in supported output +formats. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Leaders.html b/doc/groff.html.node/Leaders.html new file mode 100644 index 0000000..1a590e8 --- /dev/null +++ b/doc/groff.html.node/Leaders.html @@ -0,0 +1,126 @@ + + + + + + +Leaders (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Tabs and Fields   [Contents][Index]

+
+
+

5.12.1 Leaders

+ + +

Sometimes it is desirable to fill a tab stop with a given glyph, +but also use tab stops normally on the same output line. An example is +a table of contents entry that uses dots to bridge the entry name with +its page number, which is itself aligned between tab stops. The +roff language provides leaders for this +purpose.67 +

+ +

A leader character (ISO and EBCDIC code +point 1, also known as SOH or “start of heading”), +behaves similarly to a tab character: it moves to the next tab stop. +The difference is that for this movement, the default fill character is +a period ‘.’. +

+
+
Escape sequence: \a
+
+ + + + + +

Interpolate a leader in copy mode; see Copy Mode. +

+ +
+
Request: .lc [c]
+
+ + + +

Set the leader repetition character to the ordinary or special character +c. Recall Tabs and Leaders: when encountering a leader +character in the input, the formatter writes as many dots ‘.’ as +are necessary until +reaching the next tab stop; this is the leader definition +character. Omitting c unsets the leader +character. With no argument, GNU troff treats leaders the same +as tabs. The leader repetition character is associated with the +environment (see Environments). Only a single c is +recognized; any excess is ignored. +

+ + + +

A table of contents, for example, may define tab stops after a section +number, a title, and a gap to be filled with leader dots. The page +number follows the leader, after a right-aligned final tab stop wide +enough to house the largest page number occurring in the document. +

+
+
.ds entry1 19.\tThe Prophet\a\t98
+.ds entry2 20.\tAll Astir\a\t101
+.ta .5i 4.5i +.5iR
+.nf
+\*[entry1]
+\*[entry2]
+    ⇒ 19.  The Prophet.............................   98
+    ⇒ 20.  All Astir...............................  101
+
+ + +
+
+
+

+Next: Fields, Previous: Tabs and Fields, Up: Tabs and Fields   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Leading-Space-Traps.html b/doc/groff.html.node/Leading-Space-Traps.html new file mode 100644 index 0000000..b107793 --- /dev/null +++ b/doc/groff.html.node/Leading-Space-Traps.html @@ -0,0 +1,82 @@ + + + + + + +Leading Space Traps (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Traps   [Contents][Index]

+
+
+

5.28.4 Leading Space Traps

+ + + +
+
Request: .lsm [name]
+
+
Register: \n[lsn]
+
+
Register: \n[lss]
+
+ +

Set a leading space trap, calling the macro name when GNU +troff encounters leading spaces in an input line; the implicit +line break that normally happens in this case is suppressed. If no +argument is supplied, the default leading space behavior is +(re-)established (see Breaking). +

+

The count of leading spaces on an input line is stored in register +lsn, and the amount of corresponding horizontal motion in +register lss, irrespective of whether a leading space trap is +set. When it is, the leading spaces are removed from the input line, +and no motion is produced before calling name. +

+
+ + +
+ + + + + diff --git a/doc/groff.html.node/Ligatures-and-Kerning.html b/doc/groff.html.node/Ligatures-and-Kerning.html new file mode 100644 index 0000000..b00ed74 --- /dev/null +++ b/doc/groff.html.node/Ligatures-and-Kerning.html @@ -0,0 +1,157 @@ + + + + + + +Ligatures and Kerning (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+
+

5.19.8 Ligatures and Kerning

+ + + +

Ligatures are groups of characters that are run together, i.e, producing +a single glyph. For example, the letters ‘f’ and ‘i’ can form a +ligature ‘fi’ as in the word ‘file’. This produces a cleaner look +(albeit subtle) to the printed output. Usually, ligatures are not +available in fonts for TTY output devices. +

+

Most PostScript fonts support the fi and fl ligatures. The C/A/T +typesetter that was the target of AT&T troff also +supported ‘ff’, ‘ffi’, and ‘ffl’ ligatures. Advanced typesetters or +‘expert’ fonts may include ligatures for ‘ft’ and ‘ct’, although GNU +troff does not support these (yet). +

+

Only the current font is checked for ligatures and kerns; neither +special fonts nor special charcters defined with the char request +(and its siblings) are taken into account. +

+
+
Request: .lg [flag]
+
+
Register: \n[.lg]
+
+ + + +

Switch the ligature mechanism on or off; if the parameter is non-zero or +missing, ligatures are enabled, otherwise disabled. Default is on. The +current ligature mode can be found in the read-only register .lg +(set to 1 or 2 if ligatures are enabled, 0 otherwise). +

+

Setting the ligature mode to 2 enables the two-character ligatures +(fi, fl, and ff) and disables the three-character ligatures (ffi and +ffl). +

+ +

Pairwise kerning is another subtle typesetting mechanism that +modifies the distance between a glyph pair to improve readability. In +most cases (but not always) the distance is decreased. +Typewriter-like fonts and fonts for terminals where all glyphs have the +same width don’t use kerning. +

+
+
Request: .kern [flag]
+
+
Register: \n[.kern]
+
+ + + +

Switch kerning on or off. If the parameter is non-zero or missing, +enable pairwise kerning, otherwise disable it. The read-only register +.kern is set to 1 if pairwise kerning is enabled, +0 otherwise. +

+ + +

If the font description file contains pairwise kerning information, +glyphs from that font are kerned. Kerning between two glyphs can be +inhibited by placing \& between them: ‘V\&A’. +

+

See Font Description File Format. +

+ + + +

Track kerning expands or reduces the space between glyphs. This +can be handy, for example, if you need to squeeze a long word onto a +single line or spread some text to fill a narrow column. It must be +used with great care since it is usually considered bad typography if +the reader notices the effect. +

+
+
Request: .tkf f s1 n1 s2 n2
+
+ + +

Enable track kerning for font f. If the current font +is f the width of every glyph is increased by an amount +between n1 and n2 (n1, n2 can be negative); if +the current type size is less than or equal to s1 the width is +increased by n1; if it is greater than or equal to s2 the +width is increased by n2; if the type size is greater than or +equal to s1 and less than or equal to s2 the increase in +width is a linear function of the type size. +

+

The default scaling unit is ‘z’ for s1 and s2, ‘p’ +for n1 and n2. +

+

The track kerning amount is added even to the rightmost glyph in a line; +for large values it is thus recommended to increase the line length by +the same amount to compensate. +

+ + +
+
+
+

+Next: Dummy Characters, Previous: Artificial Fonts, Up: Using Fonts   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Line-Continuation.html b/doc/groff.html.node/Line-Continuation.html new file mode 100644 index 0000000..f818cd9 --- /dev/null +++ b/doc/groff.html.node/Line-Continuation.html @@ -0,0 +1,166 @@ + + + + + + +Line Continuation (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.16 Line Continuation

+ + + +

When filling is enabled, input and output line breaks generally do not +correspond. The roff language therefore distinguishes input and +output line continuation. +

+
+
Escape sequence: \RET
+
+ + + + +

\RET (a backslash immediately followed by a newline) +suppresses the effects of that newline in the input. The next input +line thus retains the classification of its predecessor as a control or +text line. \RET is useful for managing line lengths in the +input during document maintenance; you can break an input line in the +middle of a request invocation, macro call, or escape sequence. Input +line continuation is invisible to the formatter, with two exceptions: +the | operator recognizes the new input line +(see Numeric Expressions), and the input line counter register +.c is incremented. +

+
+
.ll 50n
+.de I
+.  ft I
+.  nop \\$*
+.  ft
+..
+Our film class watched
+.I The Effect of Gamma Rays on Man-in-the-Moon
+Marigolds. \" whoops, the input line wrapped
+.br
+.I My own opus begins on line \n[.c] \
+and ends on line \n[.c].
+
+
+
    ⇒ Our film class watched The Effect of Gamma Rays on
+    ⇒ Man-in-the-Moon Marigolds.
+    ⇒ My own opus begins on line 11 and ends on line 12.
+
+
+ +
+
Escape sequence: \c
+
+
Register: \n[.int]
+
+ + + + + + +

\c continues an output line. Nothing after it on the input line +is formatted. In contrast to \RET, a line after \c +remains a new input line, so a control character is recognized at its +beginning. The visual results depend on whether filling is enabled; see +Manipulating Filling and Adjustment. +

+
    +
  • + + +If filling is enabled, a word interrupted with \c is continued +with the text on the next input text line, without an intervening space. + +
    +
    This is a te\c
+st.
+    ⇒ This is a test.
+
    + +
  • + + +If filling is disabled, the next input text line after \c is +handled as a continuation of the same input text line. + +
    +
    .nf
+This is a \c
+test.
+    ⇒ This is a test.
+
    +
+ +

An intervening control line that causes a break overrides \c, +flushing out the pending output line in the usual way. +

+ + +

The .int register contains a positive value if the last output +line was continued with \c; this datum is associated with the +environment (see Environments).69 +

+ + + +
+
+
+

+Next: Page Layout, Previous: Line Layout, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Line-Layout.html b/doc/groff.html.node/Line-Layout.html new file mode 100644 index 0000000..4cfed5f --- /dev/null +++ b/doc/groff.html.node/Line-Layout.html @@ -0,0 +1,267 @@ + + + + + + +Line Layout (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.15 Line Layout

+ + + + + +

The following drawing shows the dimensions that gtroff uses for +placing a line of output onto the page. They are labeled with the +request that manipulates each dimension. +

+
+
     -->| in |<--
+        |<-----------ll------------>|
+   +----+----+----------------------+----+
+   |    :    :                      :    |
+   +----+----+----------------------+----+
+-->| po |<--
+   |<--------paper width---------------->|
+
+ +

These dimensions are: +

+
+
po
+
+ + + +

Page offset—this is the leftmost position of text on the final +output, defining the left margin. +

+
+
in
+
+ +

Indentation—this is the distance from the left margin where +text is printed. +

+
+
ll
+
+ +

Line length—this is the distance from the left margin to right +margin. +

+
+ + + +

The right margin is not explicitly configured; the combination of page +offset and line length provides the information necessary to derive it. +

+

A simple demonstration: +

+
+
.ll 3i
+This is text without indentation.
+The line length has been set to 3\~inches.
+.in +.5i
+.ll -.5i
+Now the left and right margins are both increased.
+.in
+.ll
+Calling .in and .ll without parameters restores
+the previous values.
+
+ +
+
    ⇒ This  is text without indenta-
+    ⇒ tion.   The  line  length  has
+    ⇒ been set to 3 inches.
+    ⇒      Now   the  left  and
+    ⇒      right  margins   are
+    ⇒      both increased.
+    ⇒ Calling  .in  and  .ll without
+    ⇒ parameters restores the previ-
+    ⇒ ous values.
+
+ +
+
Request: .po [offset]
+
+
Request: .po +offset
+
Request: .po -offset
+
Register: \n[.o]
+
+ +

Set page offset to offset (or increment or decrement its current +value by offset). If invoked without an argument, the page offset +is restored to the value before the previous po request. +This request does not cause a break; the page offset in effect when an +output line is broken prevails (see Manipulating Filling and Adjustment). The initial value is 1i and the default scaling +unit is ‘m’. On terminal devices, the page offset is set to zero +by a driver-specific macro file, tty.tmac. The current page +offset can be found in the read-only register ‘.o’. + + +This request is incorrectly documented in the AT&T +troff manual as using a default scaling unit of ‘v’. +

+
+
.po 3i
+\n[.o]
+    ⇒ 720
+.po -1i
+\n[.o]
+    ⇒ 480
+.po
+\n[.o]
+    ⇒ 720
+
+
+ +
+
Request: .in [indent]
+
+
Request: .in +indent
+
Request: .in -indent
+
Register: \n[.i]
+
+

Set indentation to indent (or increment or decrement the current +value by indent). This request causes a break. Initially, there +is no indentation. +

+

If in is called without an argument, the indentation is reset to +the previous value before the last call to in. The default +scaling unit is ‘m’. +

+

If a negative indentation value is specified (which is not allowed), +gtroff emits a warning in category ‘range’ and sets the +indentation to zero. +

+

The effect of in is delayed until a partially collected line (if +it exists) is output. A temporary indentation value is reset to zero +also. +

+

The current indentation (as set by in) can be found in the +read-only register ‘.i’. The indentation is associated with the +environment (see Environments). +

+ +
+
Request: .ti offset
+
+
Request: .ti +offset
+
Request: .ti -offset
+
Register: \n[.in]
+
+

Temporarily indent the next output line by offset. If an +increment or decrement value is specified, adjust the temporary +indentation relative to the value set by the in request. +

+

This request causes a break; its value is associated with the +environment (see Environments). The default scaling unit is +‘m’. A call of ti without an argument is ignored. +

+

If the total indentation value is negative (which is not allowed), +gtroff emits a warning in category ‘range’ and sets the +temporary indentation to zero. ‘Total indentation’ is either +offset if specified as an absolute value, or the temporary plus +normal indentation, if offset is given as a relative value. +

+

The effect of ti is delayed until a partially collected line (if +it exists) is output. +

+

The read-only register .in is the indentation that applies to the +current output line. +

+

The difference between .i and .in is that the latter takes +into account whether a partially collected line still uses the old +indentation value or a temporary indentation value is active. +

+ +
+
Request: .ll [length]
+
+
Request: .ll +length
+
Request: .ll -length
+
Register: \n[.l]
+
+
Register: \n[.ll]
+
+

Set the line length to length (or increment or decrement the +current value by length). Initially, the line length is set to +6.5i. The effect of ll is delayed until a partially +collected line (if it exists) is output. The default scaling unit is +‘m’. +

+

If ll is called without an argument, the line length is reset to +the previous value before the last call to ll. If a negative +line length is specified (which is not allowed), gtroff emits a +warning in category ‘range’ and sets the line length to zero. The +line length is associated with the environment (see Environments). +

+ +

The current line length (as set by ll) can be found in the +read-only register ‘.l’. The read-only register .ll is the +line length that applies to the current output line. +

+

Similar to .i and .in, the difference between .l +and .ll is that the latter takes into account whether a partially +collected line still uses the old line length value. +

+ + + +
+
+
+

+Next: Line Continuation, Previous: troff and nroff Modes, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Lists-in-ms.html b/doc/groff.html.node/Lists-in-ms.html new file mode 100644 index 0000000..bde2b7c --- /dev/null +++ b/doc/groff.html.node/Lists-in-ms.html @@ -0,0 +1,216 @@ + + + + + + +Lists in ms (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+
+

4.6.5.6 Lists

+ + +

The marker argument to the IP macro can be employed to +present a variety of lists; for instance, you can use a bullet glyph +(\[bu]) for unordered lists, a number (or auto-incrementing +register) for numbered lists, or a word or phrase for glossary-style or +definition lists. If you set the paragraph indentation register +PI before calling IP, you can later reorder the items in +the list without having to ensure that a width argument remains +affixed to the first call. +

+

The following is an example of a bulleted list. + + +

+
+
+
.nr PI 2n
+A bulleted list:
+.IP \[bu]
+lawyers
+.IP \[bu]
+guns
+.IP \[bu]
+money
+
+
+ +
+
A bulleted list:
+
+• lawyers
+
+• guns
+
+• money
+
+ +

The following is an example of a numbered list. + + +

+
+
+
.nr step 0 1
+.nr PI 3n
+A numbered list:
+.IP \n+[step]
+lawyers
+.IP \n+[step]
+guns
+.IP \n+[step]
+money
+
+
+ +
+
A numbered list:
+
+1. lawyers
+
+2. guns
+
+3. money
+
+ +

Here we have employed the nr request to create a register of our +own, ‘step’. We initialized it to zero and assigned it an +auto-increment of 1. Each time we use the escape sequence +‘\n+[PI]’ (note the plus sign), the formatter applies the increment +just before interpolating the register’s value. Preparing the PI +register as well enables us to rearrange the list without the tedium of +updating macro calls. +

+

The next example illustrates a glossary-style list. + + +

+
+
+
A glossary-style list:
+.IP lawyers 0.4i
+Two or more attorneys.
+.IP guns
+Firearms,
+preferably large-caliber.
+.IP money
+Gotta pay for those
+lawyers and guns!
+
+
+ +
+
A glossary-style list:
+
+lawyers
+      Two or more attorneys.
+
+guns  Firearms, preferably large-caliber.
+
+money
+      Gotta pay for those lawyers and guns!
+
+ +

In the previous example, observe how the IP macro places the +definition on the same line as the term if it has enough space. If this +is not what you want, there are a few workarounds we will illustrate by +modifying the example. First, you can use a br request to force +a break after printing the term or label. +

+
+
+
.IP guns
+.br
+Firearms,
+
+
+ +

Second, you could apply the \p escape sequence to force a break. +The space following the escape sequence is important; if you omit it, +groff prints the first word of the paragraph text on the same +line as the term or label (if it fits) then breaks the line. +

+
+
+
.IP guns
+\p Firearms,
+
+
+ +

Finally, you may append a horizontal motion to the marker with the +\h escape sequence; using the same amount as the indentation will +ensure that the marker is too wide for groff to treat it as +“fitting” on the same line as the paragraph text. +

+
+
+
.IP guns\h'0.4i'
+Firearms,
+
+
+ +

In each case, the result is the same. +

+
+
A glossary-style list:
+
+lawyers
+      Two or more attorneys.
+
+guns
+      Firearms, preferably large-caliber.
+
+money
+      Gotta pay for those lawyers and guns!
+
+ + +
+
+
+

+Next: Indented regions, Previous: Typeface and decoration, Up: Body Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Macro-Directories.html b/doc/groff.html.node/Macro-Directories.html new file mode 100644 index 0000000..c1557bd --- /dev/null +++ b/doc/groff.html.node/Macro-Directories.html @@ -0,0 +1,125 @@ + + + + + + +Macro Directories (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Invoking groff   [Contents][Index]

+
+
+

2.3 Macro Directories

+ + + + + +

A macro file must have a name in the form name.tmac or +tmac.name and be placed in a tmac directory to be +found by the -mname command-line option.5 + + + + + + + + + + +Together, these directories constitute the tmac path. Each +directory is searched in the following order until the desired macro +file is found or the list is exhausted. +

+
    +
  • Directories specified with GNU troff’s or groff’s +-M command-line option. + +
  • +Directories listed in the GROFF_TMAC_PATH environment variable. + +
  • + + + + + +The current working directory (only if in unsafe mode using the +-U command-line option). + +
  • + +The user’s home directory, HOME. + +
  • + + + +A platform-dependent directory, a site-local (platform-independent) +directory, and the main tmac directory. The locations +corresponding to your installation are listed in section “Environment” +of gtroff(1). If not otherwise configured, they are as +follows. + +
    +
    /usr/local/lib/groff/site-tmac
+/usr/local/share/groff/site-tmac
+/usr/local/share/groff/1.23.0/tmac
+
    + +

    The foregoing assumes that the version of groff is 1.23.0, and +that the installation prefix was /usr/local. It is possible to +fine-tune these locations during the source configuration process. +

+ + + +
+
+
+

+Next: Font Directories, Previous: Environment, Up: Invoking groff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Macro-Index.html b/doc/groff.html.node/Macro-Index.html new file mode 100644 index 0000000..c727a85 --- /dev/null +++ b/doc/groff.html.node/Macro-Index.html @@ -0,0 +1,335 @@ + + + + + + +Macro Index (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

Appendix F Macro Index

+ +

The macro package a specific macro belongs to is appended in brackets. +They appear without the leading control character (normally ‘.’). +

+
+
Jump to:   1 +   +2 +   +[ +   +] +   +
+A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +K +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +X +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
1
1C [ms]: ms Multiple Columns
2
2C [ms]: ms Multiple Columns
[
[ [ms]: ms Insertions
]
] [ms]: ms Insertions
A
AB [ms]: ms Document Description Macros
AE [ms]: ms Document Description Macros
AI [ms]: ms Document Description Macros
AM [ms]: ms Legacy Features
AU [ms]: ms Document Description Macros
B
B [ms]: Typeface and decoration
B1 [ms]: ms keeps and displays
B2 [ms]: ms keeps and displays
BD [ms]: ms keeps and displays
BI [ms]: Typeface and decoration
BT [man]: Optional man extensions
BX [ms]: Typeface and decoration
C
CD [ms]: ms keeps and displays
CT [man]: Optional man extensions
CW [man]: Optional man extensions
CW [ms]: Typeface and decoration
D
DA [ms]: ms Document Description Macros
De [man]: Optional man extensions
DE [ms]: ms keeps and displays
Ds [man]: Optional man extensions
DS [ms]: ms keeps and displays
DS [ms]: ms keeps and displays
DS [ms]: ms keeps and displays
DS [ms]: ms keeps and displays
DS [ms]: ms keeps and displays
E
EE [man]: Optional man extensions
EF [ms]: ms Headers and Footers
EH [ms]: ms Headers and Footers
EN [ms]: ms Insertions
EQ [ms]: ms Insertions
EX [man]: Optional man extensions
F
FE [ms]: ms Footnotes
FS [ms]: ms Footnotes
G
G [man]: Optional man extensions
GL [man]: Optional man extensions
H
HB [man]: Optional man extensions
I
I [ms]: Typeface and decoration
ID [ms]: ms keeps and displays
IP [ms]: Paragraphs in ms
K
KE [ms]: ms keeps and displays
KF [ms]: ms keeps and displays
KS [ms]: ms keeps and displays
L
LD [ms]: ms keeps and displays
LG [ms]: Typeface and decoration
LP [ms]: Paragraphs in ms
M
MC [ms]: ms Multiple Columns
MS [man]: Optional man extensions
N
ND [ms]: ms Document Description Macros
NE [man]: Optional man extensions
NH [ms]: Headings in ms
NL [ms]: Typeface and decoration
NT [man]: Optional man extensions
O
OF [ms]: ms Headers and Footers
OH [ms]: ms Headers and Footers
P
P1 [ms]: ms Headers and Footers
PE [ms]: ms Insertions
PF [ms]: ms Insertions
PN [man]: Optional man extensions
Pn [man]: Optional man extensions
PP [ms]: Paragraphs in ms
PS [ms]: ms Insertions
PT [man]: Optional man extensions
PX [ms]: ms TOC
Q
QE [ms]: Paragraphs in ms
QP [ms]: Paragraphs in ms
QS [ms]: Paragraphs in ms
R
R [man]: Optional man extensions
R [ms]: Typeface and decoration
RD [ms]: ms keeps and displays
RE [ms]: Indented regions in ms
RN [man]: Optional man extensions
RP [ms]: ms Document Description Macros
RS [ms]: Indented regions in ms
S
SH [ms]: Headings in ms
SM [ms]: Typeface and decoration
T
TA [ms]: Tab Stops in ms
TB [man]: Optional man extensions
TC [ms]: ms TOC
TE [ms]: ms Insertions
TL [ms]: ms Document Description Macros
TS [ms]: ms Insertions
U
UL [ms]: Typeface and decoration
V
VE [man]: Optional man extensions
VS [man]: Optional man extensions
X
XA [ms]: ms TOC
XE [ms]: ms TOC
XH [ms]: ms TOC
XH-REPLACEMENT [ms]: ms TOC
XH-UPDATE-TOC [ms]: ms TOC
XN [ms]: ms TOC
XN-INIT [ms]: ms TOC
XN-REPLACEMENT [ms]: ms TOC
XP [ms]: Paragraphs in ms
XS [ms]: ms TOC
+
Jump to:   1 +   +2 +   +[ +   +] +   +
+A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +K +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +X +   +
+
+ + + + +
+
+
+

+Next: String Index, Previous: Register Index, Up: GNU troff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Macro-Package-Intro.html b/doc/groff.html.node/Macro-Package-Intro.html new file mode 100644 index 0000000..77f2036 --- /dev/null +++ b/doc/groff.html.node/Macro-Package-Intro.html @@ -0,0 +1,63 @@ + + + + + + +Macro Package Intro (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+
+

1.4 Macro Packages

+ + + +

Elemental typesetting functions can be be challenging to use directly +with complex documents. A macro facility specifies how certain +routine operations, such as starting paragraphs, or printing headers and +footers, should be performed in terms of those low-level instructions. +Macros can be specific to one document or collected together into a +macro package for use by many. Several macro packages available; +the most widely used are provided with groff. They are +man, mdoc, me, mm, mom, and +ms. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Macro-Packages.html b/doc/groff.html.node/Macro-Packages.html new file mode 100644 index 0000000..762ea31 --- /dev/null +++ b/doc/groff.html.node/Macro-Packages.html @@ -0,0 +1,64 @@ + + + + + + +Macro Packages (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+
+

5.1.8 Macro Packages

+ + + +

Macro definitions can be collected into macro files, roff +input files designed to produce no output themselves but instead ease +the preparation of other roff documents. There is no syntactical +difference between a macro file and any other roff document; only +its purpose distinguishes it. When a macro file is installed at a +standard location and suitable for use by a general audience, it is +often termed a macro package.29 Macro packages can be +loaded by supplying the -m option to GNU troff or a +groff front end. Alternatively, a document requiring a macro +package can load it with the mso (“macro source”) request. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Major-Macro-Packages.html b/doc/groff.html.node/Major-Macro-Packages.html new file mode 100644 index 0000000..414994f --- /dev/null +++ b/doc/groff.html.node/Major-Macro-Packages.html @@ -0,0 +1,103 @@ + + + + + + +Major Macro Packages (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

4 Macro Packages

+ + + + +

This chapter surveys the “major” macro packages that come with +groff. One, ms, is presented in detail. +

+ + + +

Major macro packages are also sometimes described as full-service +due to the breadth of features they provide and because more than one +cannot be used by the same document; for example +

+
+
groff -m man foo.man -m ms bar.doc
+
+ +

doesn’t work. Option arguments are processed before non-option +arguments; the above (failing) sample is thus reordered to +

+
+
groff -m man -m ms foo.man bar.doc
+
+ + + + + + + +

Many auxiliary, or “minor”, macro packages are also available. They +may in general be used with any full-service macro package and handle a +variety of tasks from character encoding selection, to language +localization, to inlining of raster images. See the +groff_tmac(5) man page for a list. Type ‘man +groff_tmac’ at the command line to view it. +

+ + + + +
+ + + + + diff --git a/doc/groff.html.node/Manipulating-Filling-and-Adjustment.html b/doc/groff.html.node/Manipulating-Filling-and-Adjustment.html new file mode 100644 index 0000000..632aade --- /dev/null +++ b/doc/groff.html.node/Manipulating-Filling-and-Adjustment.html @@ -0,0 +1,501 @@ + + + + + + +Manipulating Filling and Adjustment (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.9 Manipulating Filling and Adjustment

+ + + + + + + + + + + + + + + + + + + +

When an output line is pending (see below), a break moves the drawing +position to the beginning of the next text baseline, interrupting +filling. Various ways of causing breaks were shown in Breaking. +The br request likewise causes a break. Several other requests +imply breaks: bp, ce, cf, fi, fl, +in, nf, rj, sp, ti, and trf. +If the no-break control character is used with any of these requests, +GNU troff suppresses the break; instead the requested operation +takes effect at the next break. ‘'br’ does nothing. +

+
+
.ll 55n
+This line is normally filled and adjusted.
+.br
+A line's alignment is decided
+'ce \" Center the next input line (no break).
+when it is output.
+This line returns to normal filling and adjustment.
+    ⇒ This line is normally filled and adjusted.
+    ⇒    A line's alignment is decided when it is output.
+    ⇒ This line returns to normal filling and adjustment.
+
+ + + + + +

Output line properties like page offset, indentation, adjustment, and +even the location of its text baseline, are not determined until the +line has been broken. An output line is said to be pending if +some input has been collected but an output line corresponding to it has +not yet been written; such an output line is also termed partially +collected. If no output line is pending, it is as if a break has +already happened; additional breaks, whether explicit or implicit, have +no effect. If the vertical drawing position is negative—as it is when +the formatter starts up—a break starts a new page (even if no output +line is pending) unless an end-of-input macro is being interpreted. +See End-of-input Traps. +

+
+
Request: .br
+
+

Break the line: emit any pending output line without adjustment. +

+
+
foo bar
+.br
+baz
+'br
+qux
+    ⇒ foo bar
+    ⇒ baz qux
+
+
+ +

Sometimes you want to prevent a break within a phrase or between a +quantity and its units. +

+
+
Escape sequence: \~
+
+ + +

Insert an unbreakable space that is adjustable like an ordinary space. +It is discarded from the end of an output line if a break is forced. +

+
+
Set the output speed to\~1.
+There are 1,024\~bytes in 1\~KiB.
+J.\~F.\~Ossanna wrote the original CSTR\~#54.
+
+
+ +

By default, GNU troff fills text and adjusts it to reach the +output line length. The nf request disables filling; the +fi request reënables it. +

+
+
Request: .fi
+
+
Register: \n[.u]
+
+ + + + +

Enable filling of output lines; a pending output line is broken. The +read-only register .u is set to 1. The filling enablement +status, sometimes called fill mode, is associated with the +environment (see Environments). See Line Continuation, for +interaction with the \c escape sequence. +

+ +
+
Request: .nf
+
+ + + + + + +

Disable filling of output lines: the output line length (see Line Layout) is ignored and output lines are broken where the input lines +are. A pending output line is broken and adjustment is suppressed. The +read-only register .u is set to 0. The filling enablement +status is associated with the environment (see Environments). See +Line Continuation, for interaction with the \c escape +sequence. +

+ +
+
Request: .ad [mode]
+
+
Register: \n[.j]
+
+

Enable output line adjustment in mode, taking effect when the +pending (or next) output line is broken. Adjustment is suppressed when +filling is. mode can have one of the following values. +

+
+
b
+
n
+

Adjust “normally”: if the output line does not consume the distance +between the indentation and the configured output line length, GNU +troff stretches adjustable spaces within the line until that +length is reached. When the indentation is zero, this mode spreads the +line to both the left and right margins. This is the GNU troff +default. +

+
+
c
+

Center filled text. Contrast with the ce request, which centers +text without filling it. +

+
+
l
+

Align text to the left without adjusting it. +

+
+
r
+

Align text to the right without adjusting it. +

+
+ +

mode can also be a value previously stored in the .j +register. Using ad without an argument is the same as ‘.ad +\n[.j]’; unless filling is disabled, GNU troff resumes adjusting +lines in the same way it did before adjustment was disabled by +invocation of the na request. +

+ +

The adjustment mode and enablement status are encoded in the read-only +register .j. These parameters are associated with the +environment (see Environments). +

+

The value of .j for any adjustment mode is an implementation +detail and should not be relied upon as a programmer’s interface. Do +not write logic to interpret or perform arithmetic on it. +

+
+
.ll 48n
+.de AD
+.  br
+.  ad \\$1
+..
+.de NA
+.  br
+.  na
+..
+left
+.AD r
+.nr ad \n(.j
+right
+.AD c
+center
+.NA
+left
+.AD
+center
+.AD \n(ad
+right
+
+
+
    ⇒ left
+    ⇒                                            right
+    ⇒                      center
+    ⇒ left
+    ⇒                      center
+    ⇒                                            right
+
+
+ +
+
Request: .na
+
+

Disable output line adjustment. This produces the same output as +left-alignment, but the value of the adjustment mode register .j +is altered differently. The adjustment mode and enablement status are +associated with the environment (see Environments). +

+ +
+
Request: .brp
+
+
Escape sequence: \p
+
+

Break, adjusting the line per the current adjustment mode. \p +schedules a break with adjustment at the next word boundary. The escape +sequence is itself neither a break nor a space of any kind; it can thus +be placed in the middle of a word to cause a break at the end of that +word. +

+

Breaking with immediate adjustment can produce ugly results since GNU +troff doesn’t have a sophisticated paragraph-building algorithm, +as TeX has, for example. Instead, GNU troff fills and adjusts +a paragraph line by line. +

+
+
.ll 4.5i
+This is an uninteresting sentence.
+This is an uninteresting sentence.\p
+This is an uninteresting sentence.
+
+ +

is formatted as follows. +

+
+
This  is  an uninteresting sentence.  This is
+an          uninteresting           sentence.
+This is an uninteresting sentence.
+
+
+ + + + +

To clearly present the next couple of requests, we must introduce the +concept of “productive” input lines. A productive input line is +one that directly produces formatted output. Text lines produce +output,53 as do control +lines containing requests like tl or escape sequences like +\D. Macro calls are not directly productive, and thus not +counted, but their interpolated contents can be. Empty requests, and +requests and escape sequences that define registers or strings or alter +the formatting environment (as with changes to the size, face, height, +slant, or color of the type) are not productive. We will also preview +the output line continuation escape sequence, \c, which +“connects” two input lines that would otherwise be counted separately. +54 +

+
+
.de hello
+Hello, world!
+..
+.ce \" center output of next productive input line
+.
+.nr junk-reg 1
+.ft I
+Chorus: \c
+.ft
+.hello
+Went the day well?
+  ⇒                  Chorus: Hello, world!
+  ⇒ Went the day well?
+
+ +
+
Request: .ce [n]
+
+
Register: \n[.ce]
+
+ + + +

Break (unless the no-break control character is used), center the output +of the next n productive input lines with respect to the line +length and indentation without filling, then break again regardless of +the invoking control character. +If the argument is not positive, centering is disabled. Omitting the +argument implies an n of ‘1’. The count of lines remaining +to be centered is stored in the read-only register .ce and is +associated with the environment (see Environments). +

+ +

While the ‘.ad c’ request also centers text, it fills the text +as well. +

+
+
.de FR
+This is a small text fragment that shows the differences
+between the `.ce' and the `.ad c' requests.
+..
+.ll 4i
+.ce 1000
+.FR
+.ce 0
+
+.ad c
+.FR
+    ⇒ This is a small text fragment that shows
+    ⇒              the differences
+    ⇒ between the ‘.ce’ and the ‘.ad c’ requests.
+    ⇒
+    ⇒ This is a small text fragment that shows
+    ⇒  the differences between the ‘.ce’ and
+    ⇒         the ‘.ad c’ requests.
+
+ +

The previous example illustrates a common idiom of turning centering on +for a quantity of lines far in excess of what is required, and off again +after the text to be centered. This technique relieves humans of +counting lines for requests that take a count of input lines as an +argument. +

+ +
+
Request: .rj [n]
+
+
Register: \n[.rj]
+
+ + + +

Break (unless the no-break control character is used), align the output +of the next n productive input lines to the right margin without +filling, then break again regardless of the control character. +If the argument is not positive, right-alignment is disabled. Omitting +the argument implies an n of ‘1’. The count of lines +remaining to be right-aligned is stored in the read-only register +.rj and is associated with the environment +(see Environments). +

+
+
.ll 49n
+.rj 3
+At first I hoped that such a technically unsound
+project would collapse but I soon realized it was
+doomed to success. \[em] C. A. R. Hoare
+    ⇒  At first I hoped that such a technically unsound
+    ⇒ project would collapse but I soon realized it was
+    ⇒              doomed to success. -- C. A. R. Hoare
+
+
+ +
+
Request: .ss word-space-size [additional-sentence-space-size]
+
+
Register: \n[.ss]
+
+
Register: \n[.sss]
+
+ + + + + + + +

Set the sizes of spaces between words and +sentences55 in twelfths +of font’s space width (typically one-fourth to one-third em for Western +scripts). The default for both parameters is 12. Negative values +are erroneous. + + + +The first argument is a minimum; if an output line undergoes adjustment, +such spaces may increase in width. + + + +The optional second argument sets the amount of additional space +separating sentences on the same output line. If omitted, this amount +is set to word-space-size. The request is ignored if there are no +parameters. +

+ + +

Additional inter-sentence space is used only if the output line is not +full when the end of a sentence occurs in the input. If a sentence ends +at the end of an input line, then both an inter-word space and an +inter-sentence space are added to the output; if two spaces follow the +end of a sentence in the middle of an input line, then the second space +becomes an inter-sentence space in the output. Additional +inter-sentence space is not adjusted, but the inter-word space that +always precedes it may be. Further input spaces after the second, if +present, are adjusted as normal. +

+

The read-only registers .ss and .sss hold the minimal +inter-word space and additional inter-sentence space amounts, +respectively. These parameters are part of the environment +(see Environments), and rounded down to the nearest multiple +of 12 on terminals. +

+ + + +

The ss request can insert discardable horizontal space; that is, +space that is discarded at a break. For example, some footnote styles +collect the notes into a single paragraph with large gaps between +each note. +

+
+
.ll 48n
+1.\~J. Fict. Ch. Soc. 6 (2020), 3\[en]14.
+.ss 12 48 \" applies to next sentence ending
+Reprints no longer available through FCS.
+.ss 12 \" go back to normal
+2.\~Better known for other work.
+    ⇒ 1.  J.  Fict. Ch. Soc. 6 (2020), 3-14.  Reprints
+    ⇒ no longer available through FCS.      2.  Better
+    ⇒ known for other work.
+
+ +

If undiscardable space is required, use the \h escape +sequence. +

+ + + +
+
+
+

+Next: Manipulating Hyphenation, Previous: Registers, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Manipulating-Hyphenation.html b/doc/groff.html.node/Manipulating-Hyphenation.html new file mode 100644 index 0000000..6d88ea8 --- /dev/null +++ b/doc/groff.html.node/Manipulating-Hyphenation.html @@ -0,0 +1,580 @@ + + + + + + +Manipulating Hyphenation (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.10 Manipulating Hyphenation

+ + + + + +

When filling, GNU troff hyphenates words as needed at +user-specified and automatically determined hyphenation points. The +machine-driven determination of hyphenation points in words requires +algorithms and data, and is susceptible to conventions and preferences. +Before tackling such automatic hyphenation, let us consider how +hyphenation points can be set explicitly. +

+ + + + +

Explicitly hyphenated words such as “mother-in-law” are eligible for +breaking after each of their hyphens. Relatively few words in a +language offer such obvious break points, however, and automatic +detection of syllabic (or phonetic) boundaries for hyphenation is not +perfect,56 particularly for +unusual words found in technical literature. We can instruct GNU +troff how to hyphenate specific words if the need arises. +

+ +
+
Request: .hw word …
+
+

Define each hyphenation exception word with each hyphen ‘-’ +in the word indicating a hyphenation point. For example, the request +

+
+
.hw in-sa-lub-rious alpha
+
+ +

marks potential hyphenation points in “insalubrious”, and prevents +“alpha” from being hyphenated at all. +

+

Besides the space character, any character whose hyphenation code is +zero can be used to separate the arguments of hw (see the +hcode request below). In addition, this request can be used more +than once. +

+ +

Hyphenation points specified with hw are not subject to the +within-word placement restrictions imposed by the hy request (see +below). +

+

Hyphenation exceptions specified with the hw request are +associated with the hyphenation language (see the hla request +below) and environment (see Environments); invoking the hw +request in the absence of a hyphenation language is an error. +

+

The request is ignored if there are no parameters. +

+ +

These are known as hyphenation exceptions in the expectation +that most users will avail themselves of automatic hyphenation; these +exceptions override any rules that would normally apply to a word +matching a hyphenation exception defined with hw. +

+

Situations also arise when only a specific occurrence of a word needs +its hyphenation altered or suppressed, or when a URL or similar string +needs to be breakable in sensible places without hyphenation. +

+
+
Escape sequence: \%
+
+
Escape sequence: \:
+
+ + + + +

To tell GNU troff how to hyphenate words as they occur in input, +use the \% escape sequence; it is the default hyphenation +character. Each instance within a word indicates to GNU troff +that the word may be hyphenated at that point, while prefixing a word +with this escape sequence prevents it from being otherwise hyphenated. +This mechanism affects only that occurrence of the word; to change the +hyphenation of a word for the remainder of input processing, use the +hw request. +

+ + + +

GNU troff regards the escape sequences \X and \Y as +starting a word; that is, the \% escape sequence in, say, +‘\X'...'\%foobar’ or ‘\Y'...'\%foobar’ no longer +prevents hyphenation of ‘foobar’ but inserts a hyphenation point +just prior to it; most likely this isn’t what you want. +See Postprocessor Access. +

+ + + + + + +

\: inserts a non-printing break point; that is, a word can break +there, but the soft hyphen glyph (see below) is not written to the +output if it does. This escape sequence is an input word boundary, so +the remainder of the word is subject to hyphenation as normal. +

+

You can combine \: and \% to control breaking of a file +name or URL, or to permit hyphenation only after certain explicit +hyphens within a word. +

+
+
The \%Lethbridge-Stewart-\:\%Sackville-Baggins divorce
+was, in retrospect, inevitable once the contents of
+\%/var/log/\:\%httpd/\:\%access_log on the family web
+server came to light, revealing visitors from Hogwarts.
+
+
+ +
+
Request: .hc [char]
+
+

Change the hyphenation character to char. This character then +works as the \% escape sequence normally does, and thus no longer +appears in the output.57 Without an +argument, hc resets the hyphenation character to \% (the +default). The hyphenation character is associated with the environment +(see Environments). +

+ +
+
Request: .shc [c]
+
+ + + + + + +

Set the soft hyphen character, inserted when a word is hyphenated +automatically or at a hyphenation character, to the ordinary or special +character c.58 If the argument is omitted, the soft +hyphen character is set to the default, \[hy]. If no glyph for +c exists in the font in use at a potential hyphenation point, then +the line is not broken there. Neither character definitions (specified +with the char and similar requests) nor translations (specified +with the tr request) are applied to c. +

+ + + +

Several requests influence automatic hyphenation. Because conventions +vary, a variety of hyphenation modes is available to the hy +request; these determine whether hyphenation will apply to a +word prior to breaking a line at the end of a page (more or less; see +below for details), and at which positions within that word +automatically determined hyphenation points are permissible. The places +within a word that are eligible for hyphenation are determined by +language-specific data and lettercase relationships. Furthermore, +hyphenation of a word might be suppressed due to a limit on +consecutive hyphenated lines (hlm), a minimum line length +threshold (hym), or because the line can instead be adjusted with +additional inter-word space (hys). +

+ +
+
Request: .hy [mode]
+
+
Register: \n[.hy]
+
+

Set automatic hyphenation mode to mode, an integer encoding +conditions for hyphenation; if omitted, ‘1’ is implied. The +hyphenation mode is available in the read-only register ‘.hy’; it +is associated with the environment (see Environments). The default +hyphenation mode depends on the localization file loaded when GNU +troff starts up; see the hpf request below. +

+

Typesetting practice generally does not avail itself of every +opportunity for hyphenation, but the details differ by language and site +mandates. The hyphenation modes of AT&T troff were +implemented with English-language publishing practices of the 1970s in +mind, not a scrupulous enumeration of conceivable parameters. GNU +troff extends those modes such that finer-grained control is +possible, favoring compatibility with older implementations over a more +intuitive arrangement. The means of hyphenation mode control is a set +of numbers that can be added up to encode the behavior +sought.59 The entries in the +following table are termed values; the sum of the desired +values is the mode. +

+
+
0
+

disables hyphenation. +

+
+
1
+

enables hyphenation except after the first and before the last character +of a word. +

+
+ +

The remaining values “imply” 1; that is, they enable hyphenation +under the same conditions as ‘.hy 1’, and then apply or lift +restrictions relative to that basis. +

+
+
2
+

disables hyphenation of the last word on a page,60 even for explicitly hyphenated words. +

+
+
4
+

disables hyphenation before the last two characters of a word. +

+
+
8
+

disables hyphenation after the first two characters of a word. +

+
+
16
+

enables hyphenation before the last character of a word. +

+
+
32
+

enables hyphenation after the first character of a word. +

+
+ +

Apart from value 2, restrictions imposed by the hyphenation mode +are not respected for words whose hyphenations have been +specified with the hyphenation character (‘\%’ by default) or the +hw request. +

+

Nonzero values in the previous table are additive. For example, +mode 12 causes GNU troff to hyphenate neither the last two +nor the first two characters of a word. Some values cannot be used +together because they contradict; for instance, values 4 and 16, +and values 8 and 32. As noted, it is superfluous to add 1 to any +non-zero even mode. +

+ + +

The automatic placement of hyphens in words is determined by +pattern files, which are derived from TeX and available for +several languages. The number of characters at the beginning of a word +after which the first hyphenation point should be inserted is determined +by the patterns themselves; it can’t be reduced further without +introducing additional, invalid hyphenation points (unfortunately, this +information is not part of a pattern file—you have to know it in +advance). The same is true for the number of characters at the end of +a word before the last hyphenation point should be inserted. For +example, you can supply the following input to ‘echo $(nroff)’. +

+
+
.ll 1
+.hy 48
+splitting
+
+ +

You will get +

+
+
s- plit- t- in- g
+
+ +

instead of the correct ‘split- ting’. English patterns as distributed +with GNU troff need two characters at the beginning and three +characters at the end; this means that value 4 of hy is +mandatory. Value 8 is possible as an additional restriction, but +values 16 and 32 should be avoided, as should mode 1. +Modes 4 and 6 are typical. +

+

A table of left and right minimum character counts for hyphenation as +needed by the patterns distributed with GNU troff follows; see +the groff_tmac(5) man page for more information on GNU +troff’s language macro files. +

+ + + + + + + + + + +
languagepattern nameleft minright min
Czechcs22
Englishen23
Frenchfr23
German traditionaldet22
German reformedden22
Italianit22
Swedishsv12
+ +

Hyphenation exceptions within pattern files (i.e., the words within a +TeX \hyphenation group) obey the hyphenation restrictions +given by hy. +

+ +
+
Request: .nh
+
+

Disable automatic hyphenation; i.e., set the hyphenation mode to 0 +(see above). The hyphenation mode of the last call to hy is not +remembered. +

+ +
+
Request: .hpf pattern-file
+
+
Request: .hpfa pattern-file
+
+
Request: .hpfcode a b [c d] …
+
+ + +

Read hyphenation patterns from pattern-file, which is sought +in the same way that macro files are with the mso request or the +-mname command-line option to groff. The +pattern-file should have the same format as (simple) TeX +pattern files. More specifically, the following scanning rules are +implemented. +

+
    +
  • A percent sign starts a comment (up to the end of the line) even if +preceded by a backslash. + +
  • “Digraphs” like \$ are not supported. + +
  • ^^xx (where each x is 0–9 or a–f) and +^^c (character c in the code point range 0–127 +decimal) are recognized; other uses of ^ cause an error. + +
  • No macro expansion is performed. + +
  • hpf checks for the expression \patterns{…} +(possibly with whitespace before or after the braces). Everything +between the braces is taken as hyphenation patterns. Consequently, +{ and } are not allowed in patterns. + +
  • Similarly, \hyphenation{…} gives a list of hyphenation +exceptions. + +
  • \endinput is recognized also. + +
  • For backward compatibility, if \patterns is missing, the whole +file is treated as a list of hyphenation patterns (except that the +% character is recognized as the start of a comment). +
+ +

The hpfa request appends a file of patterns to the current list. +

+

The hpfcode request defines mapping values for character codes in +pattern files. It is an older mechanism no longer used by GNU +troff’s own macro files; for its successor, see hcode +below. hpf or hpfa apply the mapping after reading the +patterns but before replacing or appending to the active list of +patterns. Its arguments are pairs of character codes—integers from 0 +to 255. The request maps character code a to +code b, code c to code d, and so on. +Character codes that would otherwise be invalid in GNU troff can +be used. By default, every code maps to itself except those for letters +‘A’ to ‘Z’, which map to those for ‘a’ to ‘z’. +

+ + + + + + + + + + +

The set of hyphenation patterns is associated with the language set by +the hla request (see below). The hpf request is usually +invoked by a localization file loaded by the troffrc +file.61 +

+

A second call to hpf (for the same language) replaces the +hyphenation patterns with the new ones. Invoking hpf or +hpfa causes an error if there is no hyphenation language. If no +hpf request is specified (either in the document, in a file +loaded at startup, or in a macro package), GNU troff won’t +automatically hyphenate at all. +

+ +
+
Request: .hcode c1 code1 [c2 code2] …
+
+ + +

Set the hyphenation code of character c1 to code1, that of +c2 to code2, and so on. A hyphenation code must be an +ordinary character (not a special character escape sequence) other than +a digit or a space. The request is ignored if given no arguments. +

+

For hyphenation to work, hyphenation codes must be set up. At +startup, GNU troff assigns hyphenation codes to the letters +‘a’–‘z’ (mapped to themselves), to the letters +‘A’–‘Z’ (mapped to ‘a’–‘z’), and zero to all other +characters. Normally, hyphenation patterns contain only lowercase +letters which should be applied regardless of case. In other words, +they assume that the words ‘FOO’ and ‘Foo’ should be hyphenated exactly +as ‘foo’ is. The hcode request extends this principle to letters +outside the Unicode basic Latin alphabet; without it, words containing +such letters won’t be hyphenated properly even if the corresponding +hyphenation patterns contain them. +

+

For example, the following hcode requests are necessary to assign +hyphenation codes to the letters ‘ÄäÖöÜüß’, needed for German. +

+
+
.hcode ä ä  Ä ä
+.hcode ö ö  Ö ö
+.hcode ü ü  Ü ü
+.hcode ß ß
+
+ +

Without these assignments, GNU troff treats the German word +‘Kindergärten’ (the plural form of ‘kindergarten’) as two words +‘kinderg’ and ‘rten’ because the hyphenation code of the +umlaut a is zero by default, just like a space. There is a German +hyphenation pattern that covers ‘kinder’, so GNU troff finds +the hyphenation ‘kin-der’. The other two hyphenation points +(‘kin-der-gär-ten’) are missed. +

+ +
+
Request: .hla lang
+
+
Register: \n[.hla]
+
+ + + + +

Set the hyphenation language to lang. Hyphenation exceptions +specified with the hw request and hyphenation patterns and +exceptions specified with the hpf and hpfa requests are +associated with the hyphenation language. The hla request is +usually invoked by a localization file, which is turn loaded by the +troffrc or troffrc-end file; see the hpf request +above. +

+ +

The hyphenation language is available in the read-only string-valued +register ‘.hla’; it is associated with the environment +(see Environments). +

+ +
+
Request: .hlm [n]
+
+
Register: \n[.hlm]
+
+
Register: \n[.hlc]
+
+ + + + + +

Set the maximum quantity of consecutive hyphenated lines to n. If +n is negative, there is no maximum. If omitted, n +is −1. This value is associated with the environment +(see Environments). Only lines output from a given environment +count toward the maximum associated with that environment. Hyphens +resulting from \% are counted; explicit hyphens are not. +

+ + +

The .hlm read-only register stores this maximum. The count of +immediately preceding consecutive hyphenated lines is available in the +read-only register .hlc. +

+ +
+
Request: .hym [length]
+
+
Register: \n[.hym]
+
+ + + +

Set the (right) hyphenation margin to length. If the adjustment +mode is not ‘b’ or ‘n’, the line is not hyphenated if it is +shorter than length. Without an argument, the hyphenation margin +is reset to its default value, 0. The default scaling unit is ‘m’. +The hyphenation margin is associated with the environment +(see Environments). +

+

A negative argument resets the hyphenation margin to zero, emitting a +warning in category ‘range’. +

+ +

The hyphenation margin is available in the .hym read-only +register. +

+ +
+
Request: .hys [hyphenation-space]
+
+
Register: \n[.hys]
+
+ + + +

Suppress hyphenation of the line in adjustment modes ‘b’ or +‘n’ if it can be justified by adding no more than +hyphenation-space extra space to each inter-word space. Without +an argument, the hyphenation space adjustment threshold is set to its +default value, 0. The default scaling unit is ‘m’. The +hyphenation space adjustment threshold is associated with the +environment (see Environments). +

+

A negative argument resets the hyphenation space adjustment threshold to +zero, emitting a warning in category ‘range’. +

+ +

The hyphenation space adjustment threshold is available in the +.hys read-only register. +

+ + + +
+
+
+

+Next: Manipulating Spacing, Previous: Manipulating Filling and Adjustment, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Manipulating-Spacing.html b/doc/groff.html.node/Manipulating-Spacing.html new file mode 100644 index 0000000..6b45b8a --- /dev/null +++ b/doc/groff.html.node/Manipulating-Spacing.html @@ -0,0 +1,220 @@ + + + + + + +Manipulating Spacing (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.11 Manipulating Spacing

+ + + +

A break causes the formatter to update the vertical drawing position at +which the new text baseline is aligned. You can alter this location. +

+
+
Request: .sp [distance]
+
+

Break and move the next text baseline down by distance, or until +springing a page location trap.62 +If invoked with the no-break control character, sp moves the +pending output line’s text baseline by distance. A negative +distance will not reduce the position of the text baseline below +zero. Inside a diversion, any distance argument is ignored. The +default scaling unit is ‘v’. If distance is not specified, +‘1v’ is assumed. +

+
+
.pl 5v \" Set page length to 5 vees.
+.de xx
+\-\-\-
+.  br
+..
+.wh 0 xx \" Set a trap at the top of the page.
+foo on page \n%
+.sp 2v
+bar on page \n%
+.sp 50v \" This will cause a page break.
+baz on page \n%
+.pl \n(nlu \" Truncate page to current position.
+    ⇒ ---
+    ⇒ foo on page 1
+    ⇒
+    ⇒
+    ⇒ bar on page 1
+    ⇒ ---
+    ⇒ baz on page 2
+
+ +

You might use the following macros to set the baseline of the next +output text at a given distance from the top or the bottom of the page. +We subtract one line height (\n[.v]) because the | +operator moves to one vee below the page top (recall Numeric Expressions). +

+
+
.de y-from-top-down
+.  sp |\\$1-\\n[.v]u
+..
+.
+.de y-from-bot-up
+.  sp |\\n[.p]u-\\$1-\\n[.v]u
+..
+
+ +

A call to ‘.y-from-bot-up 10c’ means that the next text baseline +will be 10 cm from the bottom edge of the paper. +

+ +
+
Request: .ls [count]
+
+
Register: \n[.L]
+
+ +

Set the line spacing; add count−1 blank lines after each +line of text. With no argument, GNU troff uses the previous +value before the last ls call. The default is 1. +

+ + +

The read-only register .L contains the current line spacing; it +is associated with the environment (see Environments). +

+ +

The ls request is a coarse mechanism. See Changing the Type Size, for the requests vs and pvs as alternatives to +ls. +

+
+
Escape sequence: \x'spacing'
+
+
Register: \n[.a]
+
+

Sometimes, an output line requires additional vertical spacing, for +instance to allow room for a tall construct like an inline equation with +exponents or subscripts (particularly if they are iterated). The +\x escape sequence takes a delimited measurement (like +‘\x'3p'’) to increase the vertical spacing of the pending output +line. The default scaling unit is ‘v’. If the measurement is +positive, extra vertical space is inserted below the current line; a +negative measurement adds space above. If \x is applied to the +pending output line multiple times, the maxima of the positive and +negative adjustments are separately applied. The delimiter need not be +a neutral apostrophe; see Delimiters. +

+ +

The .a read-only register contains the extra vertical spacing +after the text baseline of the most recently emitted output line. +(In other words, it is the largest positive argument to \x +encountered on that line.) This quantity is exposed via a register +because if an output line requires this “extra post-vertical line +spacing”, and the subsequent output line requires “extra pre-vertical +line spacing” (a negative argument to \x), then applying both +can lead to excessive spacing between the output lines. Text that is +piling high on line n might not require (as much) extra +pre-vertical line spacing if line n−1 carries extra +post-vertical line spacing. +

+

Use of \x can be necessary in combination with the +bracket-building escape sequence \b,63 as the following example shows. +

+
+
.nf
+This is a test of \[rs]b (1).
+This is a test of \[rs]b (2).
+This is a test of \b'xyz'\x'-1m'\x'1m' (3).
+This is a test of \[rs]b (4).
+This is a test of \[rs]b (5).
+    ⇒ This is a test of \b (1).
+    ⇒ This is a test of \b (2).
+    ⇒                   x
+    ⇒ This is a test of y (3).
+    ⇒                   z
+    ⇒ This is a test of \b (4).
+    ⇒ This is a test of \b (5).
+
+
+ +

Without \x, the backslashes on the lines marked ‘(2)’ and +‘(4)’ would be overprinted. +

+
+
Request: .ns
+
+
Request: .rs
+
+
Register: \n[.ns]
+
+ + + + + +

Enable no-space mode. Vertical spacing, whether by sp +requests or blank input lines, is disabled. The bp request to +advance to the next page is also disabled, unless it is accompanied by a +page number (see Page Control). No-space mode ends automatically +when text64 is formatted for output 65 or the rs request is invoked, which ends +no-space mode. The read-only register .ns interpolates a Boolean +value indicating the enablement of no-space mode. +

+

A paragraphing macro might ordinarily insert vertical space to separate +paragraphs. A section heading macro could invoke ns to suppress +this spacing for the first paragraph in a section. +

+ + + +
+
+
+

+Next: Tabs and Fields, Previous: Manipulating Hyphenation, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Manipulating-Type-Size-and-Vertical-Spacing.html b/doc/groff.html.node/Manipulating-Type-Size-and-Vertical-Spacing.html new file mode 100644 index 0000000..e566ad7 --- /dev/null +++ b/doc/groff.html.node/Manipulating-Type-Size-and-Vertical-Spacing.html @@ -0,0 +1,74 @@ + + + + + + +Manipulating Type Size and Vertical Spacing (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.20 Manipulating Type Size and Vertical Spacing

+ + + + + + + + +

These concepts were introduced in Page Geometry. The height of a +font’s tallest glyph is one em, which is equal to the type size in +points.82 A vertical spacing of less than 120% of +the type size can make a document hard to read. Larger proportions can +be useful to spread the text for annotations or proofreader’s marks. By +default, GNU troff uses 10 point type on 12 point +spacing. + +Typographers call the difference between type size and vertical spacing +leading.83 +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/Measurements.html b/doc/groff.html.node/Measurements.html new file mode 100644 index 0000000..a4f1c82 --- /dev/null +++ b/doc/groff.html.node/Measurements.html @@ -0,0 +1,177 @@ + + + + + + +Measurements (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.3 Measurements

+ + + + + + +

The formatter sometimes requires the input of numeric parameters to +specify measurements. These are specified as integers or decimal +fractions with an optional scaling unit suffixed. A scaling unit +is a letter that immediately follows the last digit of a number. Digits +after the decimal point are optional. Measurement expressions include +‘10.5p’, ‘11i’, and ‘3.c’. +

+ + + +

Measurements are scaled by the scaling unit and stored internally (with +any fractional part discarded) in basic units. + + +The device resolution can therefore be obtained by storing a value of +‘1i’ to a register. The only constraint on the basic unit is that +it is at least as small as any other unit. +

+
+
+ + + +
+
u
+

Basic unit. +

+
+
i
+
+ + +

Inch; defined as 2.54 centimeters. +

+
+
c
+
+ + +

Centimeter; a centimeter is about 0.3937 inches. +

+
+
p
+
+ + +

Point; a typesetter’s unit used for measuring type size. +There are 72 points to an inch. +

+
+
P
+
+ + +

Pica; another typesetter’s unit. There are 6 picas to an inch and +12 points to a pica. +

+
+
s
+
z
+

See Using Fractional Type Sizes, for a discussion of these units. +

+
+
f
+

GNU troff defines this unit to scale decimal fractions in the +interval [0, 1] to 16-bit unsigned integers. It multiplies a quantity +by 65,536. See Colors, for usage. +

+
+ +

The magnitudes of other scaling units depend on the text formatting +parameters in effect. These are useful when specifying measurements +that need to scale with the typeface or vertical spacing. +

+
+
m
+
+ + +

Em; an em is equal to the current type size in points. It is named thus +because it is approximately the width of the letter ‘M’. +

+
+
n
+
+ + +

En; an en is one-half em. +

+
+
v
+
+ + + + +

Vee; recall Page Geometry. +

+
+
M
+
+ +

Hundredth of an em. +

+
+ + + + +
+
+
+

+Next: Numeric Expressions, Previous: Text, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Miscellaneous.html b/doc/groff.html.node/Miscellaneous.html new file mode 100644 index 0000000..db1eef3 --- /dev/null +++ b/doc/groff.html.node/Miscellaneous.html @@ -0,0 +1,275 @@ + + + + + + +Miscellaneous (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.35 Miscellaneous

+ +

We document here GNU troff features that fit poorly elsewhere. +

+
+
Request: .nm [start [increment [space [indentation]]]]
+
+
Register: \n[ln]
+
+
Register: \n[.nm]
+
+ + + +

Begin (or, with no arguments, cease) numbering output lines. +start assigns the number of the next output line. Only +line numbers divisible by increment are marked (default: +‘1’). space configures the horizontal spacing between the +number and the text (default: ‘1’). Any given indentation is +applied to the numbers (default: ‘0’). The third and fourth +arguments are reckoned in numeral widths (\0). start must +be non-negative and increment positive. +

+

The formatter aligns the number to the right in a width of three numeral +spaces plus indentation, then catenates space and the output +line. The line length is not reduced. Depending on the value of +the page offset,117 numbers wider than +the allocated space protrude into the left margin, or shift the output +line to the right. +

+

Line numbering parameters corresponding to missing arguments are not +altered. After numbering is disabled, ‘.nm +0’ resumes it using +the previously active parameters. +

+

The parameters of nm are associated with the environment +(see Environments). +

+ + +

While numbering is enabled, the output line number register ln is +updated as each line is output, even if no line number is formatted with +it because it is being skipped (it is not a multiple of increment) +or because numbering is suppressed (see the nn request below). +

+

The .nm register tracks the enablement status of numbering. +Temporary suspension of numbering with the nn request does +not alter its value. +

+
+
.po 5n
+.ll 44n
+Programming,
+when stripped of all its circumstantial irrelevancies,
+.nm 999 1 1 -4
+boils down to no more and no less than
+.nm +0 3
+very effective thinking so as to avoid unmastered
+.nn 2
+complexity,
+to very vigorous separation of your many
+different concerns.
+.br
+\(em Edsger Dijkstra
+.sp
+.nm 1 1 1
+This guy's arrogance takes your breath away.
+.br
+\(em John Backus
+    ⇒      Programming,  when  stripped of all its cir-
+    ⇒  999 cumstantial irrelevancies, boils down to  no
+    ⇒      more  and no less than very effective think-
+    ⇒      ing so as to avoid unmastered complexity, to
+    ⇒      very vigorous separation of your  many  dif-
+    ⇒      ferent concerns.
+    ⇒ 1002 -- Edsger Dijkstra
+    ⇒
+    ⇒    1 This guy’s arrogance takes your breath away.
+    ⇒    2 -- John Backus
+
+
+ +
+
Request: .nn [skip]
+
+
Register: \n[.nn]
+
+

Suppress numbering of the next skip output lines that would +otherwise be numbered. The default is 1. nn can be invoked +when line numbering is not active; suppression of numbering will take +effect for skip lines once nm enables it. +

+

The .nn register stores the count of output lines still to have +their numbering suppressed. +

+

This count is associated with the environment (see Environments). +

+ +

To test whether the current output line will be numbered, you must check +both the .nm and .nn registers. +

+
+
  .de is-numbered
+  .  nop This line
+  .  ie (\\n[.nm] & (1-\\n[.nn])) IS
+  .  el                           ISN'T
+  .  nop numbered.
+  .  br
+  ..
+  Test line numbering.
+  .is-numbered
+  .nm 1
+  .nn 1
+  .is-numbered
+  .is-numbered
+  .nm
+  .is-numbered
+    ⇒ Test line numbering.  This line ISN’T numbered.
+    ⇒ This line ISN’T numbered.
+    ⇒   1 This line IS numbered.
+    ⇒ This line ISN’T numbered.
+
+ +
+
Request: .mc [margin-character [distance]
+
+ + +

Begin (or, with no arguments, cease) writing a margin-character to +the right of each output line. The distance argument separates +margin-character from the right margin. If absent, the most +recent value is used; the default is 10 points. If an output line +exceeds the line length, the margin character is appended to it. + +No margin character is written on lines produced by the tl +request. +

+

The margin character is a property of the output line; the margin +character last configured when the line is output controls. If the +margin character is disabled before an output line breaks, none is +output (but see below). +

+

The margin character is associated with the environment +(see Environments). +

+
+
.ll 5i
+.nf
+.mc \[br]
+This paragraph is marked with a margin character.
+.sp
+As seen above, vertical space isn't thus marked.
+\&
+An output line that is present, but empty, is.
+    ⇒ This paragraph is marked with a margin character.  |
+    ⇒
+    ⇒ As seen above, vertical space isn’t thus marked.   |
+    ⇒                                                    |
+    ⇒ An output line that is present, but empty, is.     |
+
+
+ +

For compatibility with AT&T troff, a call to mc +to set the margin character can’t be undone immediately; at least one +line gets a margin character. +

+
+
.ll 10n
+.nf
+.mc |
+.mc *
+.mc
+foo
+bar
+    ⇒ foo        *
+    ⇒ bar
+
+ + + + + +

The margin character mechanism is commonly used to annotate changes in +documents. The groff distribution ships a program, +gdiffmk, to assist with this task.118 +

+
+
Request: .psbb file
+
+
Register: \n[llx]
+
+
Register: \n[lly]
+
+
Register: \n[urx]
+
+
Register: \n[ury]
+
+ + +

Retrieve the bounding box of the PostScript image found in file, +which must conform to Adobe’s Document Structuring Conventions +(DSC), locate a %%BoundingBox comment, and store the (upper-, +lower-, -left, -right) values into the registers llx, +lly, urx, and ury. If an error occurs (for +example, if no %%BoundingBox comment is present), the formatter +sets these registers to 0. +

+

The search path for file can be controlled with the -I +command-line option. +

+ + + + +
+
+
+

+Next: gtroff Internals, Previous: Postprocessor Access, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Missing-Unix-Version-7-ms-Macros.html b/doc/groff.html.node/Missing-Unix-Version-7-ms-Macros.html new file mode 100644 index 0000000..99f7b62 --- /dev/null +++ b/doc/groff.html.node/Missing-Unix-Version-7-ms-Macros.html @@ -0,0 +1,78 @@ + + + + + + +Missing Unix Version 7 ms Macros (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Differences from AT&T ms   [Contents][Index]

+
+
+

4.6.7.1 Unix Version 7 ms macros not implemented by groff ms

+ +

Several macros described in the Unix Version 7 ms +documentation are unimplemented by groff ms because they +are specific to the requirements of documents produced internally by +Bell Laboratories, some of which also require a glyph for the Bell +System logo that groff does not support. These macros +implemented several document type formats +(EG, IM, MF, MR, TM, TR), were meaningful only in conjunction with the use of certain document +types +(AT, CS, CT, OK, SG), stored the postal addresses of Bell Labs sites +(HO, IH, MH, PY, WH), or lacked a stable definition over time +(UX). To compatibly render historical ms documents using these macros, +we advise your documents to invoke the rm request to remove any +such macros it uses and then define replacements with an authentically +typeset original at hand.17 For +informal purposes, a simple definition of UX should maintain the +readability of the document’s substance. +

+
+
+
.rm UX
+.ds UX Unix\"
+
+
+ + +
+ + + + + diff --git a/doc/groff.html.node/Motion-Quanta.html b/doc/groff.html.node/Motion-Quanta.html new file mode 100644 index 0000000..5df1c72 --- /dev/null +++ b/doc/groff.html.node/Motion-Quanta.html @@ -0,0 +1,93 @@ + + + + + + +Motion Quanta (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Measurements   [Contents][Index]

+
+
+

5.3.1 Motion Quanta

+ + + +

An output device’s basic unit u is not necessarily its smallest +addressable length; u can be smaller to avoid problems with +integer roundoff. The minimum distances that a device can work with in +the horizontal and vertical directions are termed its motion +quanta. Measurements are rounded to applicable motion quanta. +Half-quantum fractions round toward zero. +

+ + + + +
+
Register: \n[.H]
+
+
Register: \n[.V]
+
+

These read-only registers interpolate the horizontal and vertical motion +quanta, respectively, of the output device in basic units. +

+ +

For example, we might draw short baseline rules on a terminal device as +follows. See Drawing Geometric Objects. +

+
+
.tm \n[.H]
+    error→ 24
+.nf
+\l'36u' 36u
+\l'37u' 37u
+    ⇒ _ 36u
+    ⇒ __ 37u
+
+ + +
+ + + + + diff --git a/doc/groff.html.node/Numeric-Expressions.html b/doc/groff.html.node/Numeric-Expressions.html new file mode 100644 index 0000000..7da6bd3 --- /dev/null +++ b/doc/groff.html.node/Numeric-Expressions.html @@ -0,0 +1,395 @@ + + + + + + +Numeric Expressions (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.4 Numeric Expressions

+ + + +

A numeric expression evaluates to an integer: it can be as +simple as a literal ‘0’ or it can be a complex sequence of register +and string interpolations interleaved with measurements and operators. +

+

GNU troff provides a set of mathematical and logical operators +familiar to programmers—as well as some unusual ones—but supports +only integer arithmetic.35 The internal data type +used for computing results is usually a 32-bit signed integer, which +suffices to represent magnitudes within a range of ±2 +billion.36 +

+ + + + + + + + + + + + + +

Arithmetic infix operators perform a function on the numeric expressions +to their left and right; they are + (addition), - +(subtraction), * (multiplication), / (truncating +division), and % (modulus). Truncating division rounds to +the integer nearer to zero, no matter how large the fractional portion. +Overflow and division (or modulus) by zero are errors and abort +evaluation of a numeric expression. + + + + + + + + +

+

Arithmetic unary operators operate on the numeric expression to their +right; they are - (negation) and + (assertion—for +completeness; it does nothing). The unary minus must often be used +with parentheses to avoid confusion with the decrementation operator, +discussed below. +

+

Observe the rounding behavior and effect of negative operands on the +modulus and truncating division operators. +

+
+
.nr T 199/100
+.nr U 5/2
+.nr V (-5)/2
+.nr W 5/-2
+.nr X 5%2
+.nr Y (-5)%2
+.nr Z 5%-2
+T=\n[T] U=\n[U] V=\n[V] W=\n[W] X=\n[X] Y=\n[Y] Z=\n[Z]
+    ⇒ T=1 U=2 V=-2 W=-2 X=1 Y=-1 Z=1
+
+ +

The sign of the modulus of operands of mixed signs is determined by the +sign of the first. Division and modulus operators satisfy the following +property: given a dividend a and a divisor b, a +quotient q formed by ‘(a / b)’ and a +remainder r by ‘(a % b)’, then qb + r = a. +

+ + + +

GNU troff’s scaling operator, used with parentheses as +(c;e), evaluates a numeric expression e +using c as the default scaling unit. If c is omitted, +scaling units are ignored in the evaluation of e. This +operator can save typing by avoiding the attachment of scaling units to +every operand out of caution. Your macros can select a sensible default +unit in case the user neglects to supply one. +

+
+
.\" Indent by amount given in first argument; assume ens.
+.de Indent
+.  in (n;\\$1)
+..
+
+ +

Without the scaling operator, the foregoing macro would, if called with +a unitless argument, cause indentation by the in request’s +default scaling unit (ems). The result would be twice as much +indentation as expected. +

+ + + + + + +

GNU troff also provides a pair of operators to compute the +extrema of two operands: >? (maximum) and <? (minimum). +

+
+
.nr slots 5
+.nr candidates 3
+.nr salaries (\n[slots] <? \n[candidates])
+Looks like we'll end up paying \n[salaries] salaries.
+    ⇒ Looks like we'll end up paying 3 salaries.
+
+ + + + + + + + + + + + +

Comparison operators comprise < (less than), > (greater +than), <= (less than or equal), >= (greater than or +equal), and = (equal). == is a synonym for =. +When evaluated, a comparison is replaced with ‘0’ if it is false +and ‘1’ if true. In the roff language, positive values are +true, others false. +

+ + + + + + + + +

We can operate on truth values with the logical operators & +(logical conjunction or “and”) and : (logical disjunction or +“or”). They evaluate as comparison operators do. +

+ + + + + +

A logical complementation (“not”) operator, !, works only +within if, ie, and while requests. +Furthermore, ! is recognized only at the beginning of a numeric +expression not contained by another numeric expression. In other words, +it must be the “outermost” operator. Including it elsewhere in the +expression produces a warning in the ‘number’ category +(see Warnings), and its expression evaluates false. This +unfortunate limitation maintains compatibility with AT&T +troff. Test a numeric expression for falsity by +comparing it to a false value.37 +

+
+
.nr X 1
+.nr Y 0
+.\" This does not work as expected.
+.if (\n[X])&(!\n[Y]) .nop A: X is true, Y is false
+.
+.\" Use this construct instead.
+.if (\n[X])&(\n[Y]<=0) .nop B: X is true, Y is false
+    error→ warning: expected numeric expression, got '!'
+    ⇒ B: X is true, Y is false
+
+ + + + + + +

The roff language has no operator precedence: expressions are +evaluated strictly from left to right, in contrast to schoolhouse +arithmetic. Use parentheses ( ) to impose a desired +precedence upon subexpressions. +

+
+
.nr X 3+5*4
+.nr Y (3+5)*4
+.nr Z 3+(5*4)
+X=\n[X] Y=\n[Y] Z=\n[Z]
+    ⇒ X=32 Y=32 Z=23
+
+ + + + + + + +

For many requests and escape sequences that cause motion on the page, +the unary operators + and - work differently when leading +a numeric expression. They then indicate a motion relative to the +drawing position: positive is down in vertical contexts, right in +horizontal ones. +

+ + + + + + + + + + + + + + + + +

+ and - are also treated differently by the following +requests and escape sequences: bp, in, ll, +lt, nm, nr, pl, pn, po, +ps, pvs, rt, ti, \H, \R, and +\s. Here, leading plus and minus signs serve as incrementation +and decrementation operators, respectively. To negate an expression, +subtract it from zero or include the unary minus in parentheses with its +argument. See Setting Registers, for examples. +

+ + + + + +

A leading | operator indicates a motion relative not to the +drawing position but to a boundary. For horizontal motions, the +measurement specifies a distance relative to a drawing position +corresponding to the beginning of the input line. By default, +tab stops reckon movements in this way. Most escape sequences do not; +| tells them to do so. +

+
+
Mind the \h'1.2i'gap.
+.br
+Mind the \h'|1.2i'gap.
+.br
+Mind the
+\h'|1.2i'gap.
+    ⇒ Mind the             gap.
+    ⇒ Mind the    gap.
+    ⇒ Mind the             gap.
+
+ +

One use of this feature is to define macros whose scope is limited to +the output they format. +

+
+
.\" underline word $1 with trailing punctuation $2
+.de Underline
+.  nop \\$1\l'|0\[ul]'\\$2
+..
+Typographical emphasis is best used
+.Underline sparingly .
+
+ +

In the above example, ‘|0’ specifies a negative motion from the +current position (at the end of the argument just emitted, \$1) +to the beginning of the input line. Thus, the \l escape sequence +in this case draws a line from right to left. A macro call occurs at +the beginning of an input line;38 if the | +operator were omitted, then the underline would be drawn at zero +distance from the current position, producing device-dependent, and +likely undesirable, results. On the ‘ps’ output device, it +underlines the period. +

+

For vertical motions, the | operator specifies a distance from +the first text baseline on the page or in the current +diversion,39 using the current vertical +spacing. +

+
+
A
+.br
+B \Z'C'\v'|0'D
+    ⇒ A D
+    ⇒ B C
+
+ +

In the foregoing example, we’ve used the \Z escape sequence +(see Page Motions) to restore the drawing position after formatting +‘C’, then moved vertically to the first text baseline on the page. +

+
+
Escape sequence: \B'anything'
+
+ + +

Interpolate 1 if anything is a valid numeric expression, +and 0 otherwise. The delimiter need not be a neutral apostrophe; +see Delimiters. +

+ +

You might use \B along with the if request to filter out +invalid macro or string arguments. See Conditionals and Loops. +

+
+
.\" Indent by amount given in first argument; assume ens.
+.de Indent
+.  if \B'\\$1' .in (n;\\$1)
+..
+
+ +

A register interpolated as an operand in a numeric expression must have +an Arabic format; luckily, this is the default. See Assigning Register Formats. +

+ + +

Because spaces separate arguments to requests, spaces are not allowed in +numeric expressions unless the (sub)expression containing them is +surrounded by parentheses. See Invoking Requests, and +Conditionals and Loops. +

+
+
.nf
+.nr a 1+2 + 2+1
+\na
+    error→ expected numeric expression, got a space
+    ⇒ 3
+.nr a 1+(2 + 2)+1
+\na
+    ⇒ 6
+
+ +

The nr request (see Setting Registers) expects its second and +optional third arguments to be numeric expressions; a bare + does +not qualify, so our first attempt got a warning. +

+ + +
+
+
+

+Next: Identifiers, Previous: Measurements, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Obsolete-Command.html b/doc/groff.html.node/Obsolete-Command.html new file mode 100644 index 0000000..b656c38 --- /dev/null +++ b/doc/groff.html.node/Obsolete-Command.html @@ -0,0 +1,74 @@ + + + + + + +Obsolete Command (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Command Reference   [Contents][Index]

+
+
+

6.1.2.5 Obsolete Command

+

In AT&T troff output, the writing of a single glyph is +mostly done by a very strange command that combines a horizontal move +and a single character giving the glyph name. It doesn’t have a command +code, but is represented by a 3-character argument consisting of exactly +2 digits and a character. +

+
+
ddg
+

Move right dd (exactly two decimal digits) basic units ‘u’, +then print glyph g (represented as a single character). +

+

In GNU troff, arbitrary syntactical space around and within this +command is allowed. Only when a preceding command on the same line ends +with an argument of variable length is a separating space obligatory. +In AT&T troff, large clusters of these and other +commands are used, mostly without spaces; this made such output almost +unreadable. +

+
+ +

For modern high-resolution devices, this command does not make sense +because the width of the glyphs can become much larger than two decimal +digits. In gtroff, this is only used for the devices X75, +X75-12, X100, and X100-12. For other devices, the +commands ‘t’ and ‘u’ provide a better functionality. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Operator-Index.html b/doc/groff.html.node/Operator-Index.html new file mode 100644 index 0000000..b70458f --- /dev/null +++ b/doc/groff.html.node/Operator-Index.html @@ -0,0 +1,188 @@ + + + + + + +Operator Index (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

Appendix D Operator Index

+ +
+
Jump to:   ! +   +% +   +& +   +( +   +) +   +* +   ++ +   +- +   +/ +   +: +   +; +   +< +   += +   +> +   +| +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
!
!: Numeric Expressions
%
%: Numeric Expressions
&
&: Numeric Expressions
(
(: Numeric Expressions
)
): Numeric Expressions
*
*: Numeric Expressions
+
+: Numeric Expressions
+: Numeric Expressions
+ (unary): Numeric Expressions
-
-: Numeric Expressions
-: Numeric Expressions
- (unary): Numeric Expressions
/
/: Numeric Expressions
:
:: Numeric Expressions
;
;: Numeric Expressions
<
<: Numeric Expressions
<=: Numeric Expressions
<?: Numeric Expressions
=
=: Numeric Expressions
==: Numeric Expressions
>
>: Numeric Expressions
>=: Numeric Expressions
>?: Numeric Expressions
|
|: Numeric Expressions
+
Jump to:   ! +   +% +   +& +   +( +   +) +   +* +   ++ +   +- +   +/ +   +: +   +; +   +< +   += +   +> +   +| +
+
+ + + + +
+
+
+

+Next: Register Index, Previous: Escape Sequence Index, Up: GNU troff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Operators-in-Conditionals.html b/doc/groff.html.node/Operators-in-Conditionals.html new file mode 100644 index 0000000..a04b761 --- /dev/null +++ b/doc/groff.html.node/Operators-in-Conditionals.html @@ -0,0 +1,222 @@ + + + + + + +Operators in Conditionals (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Conditionals and Loops   [Contents][Index]

+
+
+

5.23.1 Operators in Conditionals

+ + + + + + +

In if, ie, and while requests, in addition to the +numeric expressions described in Numeric Expressions, several +Boolean operators are available; the members of this expanded class are +termed conditional expressions. +

+
+
c glyph
+

True if glyph is available, where glyph is an ordinary +character, a special character ‘\(xx’ or ‘\[xxx]’, +‘\N'xxx'’, or has been defined by any of the char, +fchar, fschar, or schar requests. +

+
+
d name
+

True if a string, macro, diversion, or request called name exists. +

+
+
e
+

True if the current page is even-numbered. +

+
+
F font
+

True if font exists. font is handled as if it were opened +with the ft request (that is, font translation and styles are +applied), without actually mounting it. +

+
+
m color
+

True if color is defined. +

+
+
n
+
+ +

True if the document is being processed in nroff mode. +See troff and nroff Modes. +

+
+
o
+

True if the current page is odd-numbered. +

+
+
r register
+

True if register exists. +

+
+
S style
+

True if style is available for the current font family. Font +translation is applied. +

+
+
t
+

True if the document is being processed in troff mode. +See troff and nroff Modes. +

+ +
+
v
+

Always false. This condition is recognized only for compatibility with +certain other troff implementations.88 +

+
+ +

If the first argument to an if, ie, or while +request begins with a non-alphanumeric character apart from ! +(see below); it performs an output comparison test. +89 +

+ +
+
'xxx'yyy'
+

True if formatting the comparands xxx and yyy produces the +same output commands. The delimiter need not be a neutral apostrophe: +the output comparison operator accepts the same delimiters as most +escape sequences; see Delimiters. This output comparison +operator formats xxx and yyy in separate environments; +after the comparison, the resulting data are discarded. +

+
+
.ie "|"\fR|\fP" true
+.el false
+    ⇒ true
+
+ +

The resulting glyph properties, including font family, style, size, and +slant, must match, but not necessarily the requests and/or escape +sequences used to obtain them. In the previous example, ‘|’ and +‘\fR|\fP’ result in ‘|’ glyphs in the same typefaces at the +same positions, so the comparands are equal. If ‘.ft I’ had +been added before the ‘.ie’, they would differ: the first ‘|’ +would produce an italic ‘|’, not a roman one. Motions must match +in orientation and magnitude to within the applicable horizontal and +vertical motion quanta of the device, after rounding. ‘.if +"\u\d"\v'0'"’ is false even though both comparands result in zero net +motion, because motions are not interpreted or optimized but sent as-is +to the output.90 On the other hand, ‘.if "\d"\v'0.5m'"’ is true, because +\d is defined as a downward motion of one-half em.91 +

+ + +

Surround the comparands with \? to avoid formatting them; this +causes them to be compared character by character, as with string +comparisons in other programming languages. +

+
+
.ie "\?|\?"\?\fR|\fP\?" true
+.el false
+    ⇒ false
+
+ + + + +

Since comparands protected with \? are read in copy mode +(see Copy Mode), they need not even be valid groff syntax. +The escape character is still lexically recognized, however, and +consumes the next character. +

+
+
.ds a \[
+.ds b \[
+.if '\?\*a\?'\?\*b\?' a and b equivalent
+.if '\?\\?'\?\\?' backslashes equivalent
+    ⇒ a and b equivalent
+
+
+
+ +

The above operators can’t be combined with most others, but a leading +‘!’, not followed immediately by spaces or tabs, complements an +expression. +

+
+
.nr x 1
+.ie !r x register x is not defined
+.el      register x is defined
+    ⇒ register x is defined
+
+ +

Spaces and tabs are optional immediately after the ‘c’, ‘d’, +‘F’, ‘m’, ‘r’, and ‘S’ operators, but right after +‘!’, they end the predicate and the conditional evaluates +true.92 +

+
+
.nr x 1
+.ie ! r x register x is not defined
+.el       register x is defined
+    ⇒ r x register x is not defined
+
+ +

The unexpected ‘r x’ in the output is a clue that our conditional +was not interpreted as we planned, but matters may not always be so +obvious. +

+ +
+
+
+

+Next: if-then, Previous: Conditionals and Loops, Up: Conditionals and Loops   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Optional-man-extensions.html b/doc/groff.html.node/Optional-man-extensions.html new file mode 100644 index 0000000..035f410 --- /dev/null +++ b/doc/groff.html.node/Optional-man-extensions.html @@ -0,0 +1,264 @@ + + + + + + +Optional man extensions (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + +
+
+

+Up: man   [Contents][Index]

+
+
+

4.1.1 Optional man extensions

+ + +

Use the file man.local for local extensions to the man +macros or for style changes. +

+ +
+

Custom headers and footers

+ + +

In groff versions 1.18.2 and later, you can specify custom +headers and footers by redefining the following macros in +man.local. +

+
+
Macro: .PT
+
+

Control the content of the headers. Normally, the header prints the +command name and section number on either side, and the optional fifth +argument to TH in the center. +

+ +
+
Macro: .BT
+
+

Control the content of the footers. Normally, the footer prints the +page number and the third and fourth arguments to TH. +

+

Use the FT register to specify the footer position. The default +is −0.5i. +

+ +
+
+

Ultrix-specific man macros

+ + + + +

The groff source distribution includes a file named +man.ultrix, containing macros compatible with the Ultrix variant +of man. Copy this file into man.local (or use the +mso request to load it) to enable the following macros. +

+
+
Macro: .CT key
+
+

Print ‘<CTRL/key>’. +

+ +
+
Macro: .CW
+
+

Print subsequent text using a “constant-width” (monospaced) typeface +(Courier roman). +

+ +
+
Macro: .Ds
+
+

Begin a non-filled display. +

+ +
+
Macro: .De
+
+

End a non-filled display started with Ds. +

+ +
+
Macro: .EX [indent]
+
+

Begin a non-filled display using a monospaced typeface (Courier roman). +Use the optional indent argument to indent the display. +

+ +
+
Macro: .EE
+
+

End a non-filled display started with EX. +

+ +
+
Macro: .G [text]
+
+

Set text in Helvetica. If no text is present on the line where +the macro is called, then the text of the next line appears in +Helvetica. +

+ +
+
Macro: .GL [text]
+
+

Set text in Helvetica oblique. If no text is present on the line +where the macro is called, then the text of the next line appears in +Helvetica Oblique. +

+ +
+
Macro: .HB [text]
+
+

Set text in Helvetica bold. If no text is present on the line +where the macro is called, then all text up to the next HB +appears in Helvetica bold. +

+ +
+
Macro: .TB [text]
+
+

Identical to HB. +

+ +
+
Macro: .MS title sect [punct]
+
+

Set a man page reference in Ultrix format. The title is in +Courier instead of italic. Optional punctuation follows the section +number without an intervening space. +

+ +
+
Macro: .NT [C] [title]
+
+

Begin a note. Print the optional title, or the word “Note”, +centered on the page. Text following the macro makes up the body of the +note, and is indented on both sides. If the first argument is C, +the body of the note is printed centered (the second argument replaces +the word “Note” if specified). +

+ +
+
Macro: .NE
+
+

End a note begun with NT. +

+ +
+
Macro: .PN path [punct]
+
+

Set the path name in a monospaced typeface (Courier roman), followed by +optional punctuation. +

+ +
+
Macro: .Pn [punct] path [punct]
+
+

If called with two arguments, identical to PN. If called with +three arguments, set the second argument in a monospaced typeface +(Courier roman), bracketed by the first and third arguments in the +current font. +

+ +
+
Macro: .R
+
+

Switch to roman font and turn off any underlining in effect. +

+ +
+
Macro: .RN
+
+

Print the string ‘<RETURN>’. +

+ +
+
Macro: .VS [4]
+
+

Start printing a change bar in the margin if the number 4 is +specified. Otherwise, this macro does nothing. +

+ +
+
Macro: .VE
+
+

End printing the change bar begun by VS. +

+ +
+
+

Simple example

+ +

The following example man.local file alters the SH macro +to add some extra vertical space before printing the heading. Headings +are printed in Helvetica bold. +

+
+
.\" Make the heading fonts Helvetica
+.ds HF HB
+.
+.\" Put more space in front of headings.
+.rn SH SH-orig
+.de SH
+.  if t .sp (u;\\n[PD]*2)
+.  SH-orig \\$*
+..
+
+ + + +
+
+
+
+

+Up: man   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Other-Differences.html b/doc/groff.html.node/Other-Differences.html new file mode 100644 index 0000000..6a92cad --- /dev/null +++ b/doc/groff.html.node/Other-Differences.html @@ -0,0 +1,248 @@ + + + + + + +Other Differences (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Implementation Differences   [Contents][Index]

+
+
+

5.38.3 Other Differences

+ +

groff request names unrecognized by other troff +implementations will likely be ignored by them; escape sequences that +are groff extensions are liable to be interpreted as if the +escape character were not present. + +For example, the adjustable, non-breaking escape sequence \~ +is also supported by Heirloom Doctools troff 050915 (September +2005), mandoc 1.9.5 (2009-09-21), neatroff (commit +1c6ab0f6e, 2016-09-13), and Plan 9 from User Space troff +(commit 93f8143600, 2022-08-12), but not by Solaris or Documenter’s +Workbench troffs. +See Manipulating Filling and Adjustment. +

+ + + + + + + + + + + + + + +

GNU troff does not allow the use of the escape sequences +\|, \^, \&, \{, \}, +\SP, \', \`, \-, \_, \!, +\%, and \c in identifiers; AT&T troff +does. The \A escape sequence (see Identifiers) may be +helpful in avoiding use of these escape sequences in names. +

+ + +

When adjusting to both margins, AT&T troff at first +adjusts spaces starting from the right; GNU troff begins from +the left. Both implementations adjust spaces from opposite ends on +alternating output lines in this adjustment mode to prevent “rivers” +in the text. +

+ +

GNU troff does not always hyphenate words as AT&T +troff does. The AT&T implementation uses a set of +hard-coded rules specific to English, while GNU troff uses +language-specific hyphenation pattern files derived from TeX. +Furthermore, in old versions of troff there was a limited amount +of space to store hyphenation exceptions (arguments to the hw +request); GNU troff has no such restriction. +

+ +

GNU troff predefines a string .T containing the argument +given to the -T command-line option, namely the current output +device (for example, ‘pdf’ or ‘utf8’). The existence of this +string is a common feature of post-CSTR #54 +troffs121 but valid values are specific +to each implementation. +

+ + + +

AT&T troff ignored attempts to remove read-only +registers; GNU troff honors such requests. See Built-in Registers. +

+ +

The (read-only) register .T interpolates 1 if GNU +troff is called with the -T command-line option, and +0 otherwise. This behavior differs from AT&T troff, which +interpolated 1 only if nroff was the formatter and was +called with -T. +

+ +

AT&T troff and other implementations handle the +lf request differently. For them, its line argument +changes the line number of the current line. +

+ +

AT&T troff had only environments named ‘0’, +‘1’, and ‘2’. In GNU troff, any number of environments +may exist, using any valid identifiers for their names +(see Identifiers.) +

+ + + + + + +

Fractional type sizes cause one noteworthy incompatibility. In +AT&T troff the ps request ignores scaling units +and thus ‘.ps 10u’ sets the type size to 10 points, whereas in +GNU troff it sets the type size to 10 scaled points. +See Using Fractional Type Sizes. +

+ +

The ab request differs from AT&T troff: +GNU troff writes no message to the standard error stream if no +arguments are given, and it exits with a failure status instead of a +successful one. +

+ +

The bp request differs from AT&T troff: +GNU troff does not accept a scaling unit on the argument, a page +number; the former (somewhat uselessly) does. +

+ +

The pm request differs from AT&T troff: +GNU troff reports the sizes of macros, strings, and diversions in +bytes and ignores an argument to report only the sum of the sizes. +

+ +

Unlike AT&T troff, GNU troff does not ignore the +ss request if the output is a terminal device; instead, the +values of minimal inter-word and additional inter-sentence space are +each rounded down to the nearest multiple of 12. +

+ + + + + + + + +

In GNU troff there is a fundamental difference between +(unformatted) characters and (formatted) glyphs. Everything that +affects how a glyph is output is stored with the glyph node; once a +glyph node has been constructed, it is unaffected by any subsequent +requests that are executed, including bd, cs, tkf, +tr, or fp requests. Normally, glyphs are constructed from +characters immediately before the glyph is added to an output line. +Macros, diversions, and strings are all, in fact, the same type of +object; they contain a sequence of intermixed character and glyph nodes. +Special characters transform from one to the other: before being added +to the output, they behave as characters; afterward, they are glyphs. A +glyph node does not behave like a character node when it is processed by +a macro: it does not inherit any of the special properties that the +character from which it was constructed might have had. For example, +the input +

+
+
.di x
+\\\\
+.br
+.di
+.x
+
+ +

produces ‘\\’ in GNU troff. Each pair of backslashes +becomes one backslash glyph; the resulting backslashes are thus +not interpreted as escape characters when they are reread as the +diversion is output. AT&T troff would interpret +them as escape characters when rereading them and end up printing one +‘\’. +

+ + + + + + + +

One correct way to obtain a printable backslash in most documents is to +use the \e escape sequence; this always prints a single instance +of the current escape character,122 regardless of whether or not it is used in a diversion; it +also works in both GNU troff and AT&T troff. +

+

The other correct way, appropriate in contexts independent of the +backslash’s common use as a troff escape character—perhaps in +discussion of character sets or other programming languages—is +the character escape \(rs or \[rs], for “reverse +solidus”, from its name in the ECMA-6 (ISO/IEC 646) +standard.123 +

+

To store an escape sequence in a diversion that is interpreted when the +diversion is reread, either use the traditional \! transparent +output facility, or, if this is unsuitable, the new \? escape +sequence. See Diversions and gtroff Internals. +

+

In the somewhat pathological case where a diversion exists containing a +partially collected line and a partially collected line at the top-level +diversion has never existed, AT&T troff will output the +partially collected line at the end of input; GNU troff will not. +

+ + + + +
+
+
+

+Previous: Compatibility Mode, Up: Implementation Differences   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Output-Device-Intro.html b/doc/groff.html.node/Output-Device-Intro.html new file mode 100644 index 0000000..815a509 --- /dev/null +++ b/doc/groff.html.node/Output-Device-Intro.html @@ -0,0 +1,63 @@ + + + + + + +Output Device Intro (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+
+

1.6 Output Devices

+ + + + +

GNU troff’s output is in a device-independent page description +language, which is then read by an output driver that translates +this language into a file format or byte stream that a piece of +(possibly emulated) hardware understands. groff features output +drivers for PostScript devices, terminal emulators (and other simple +typewriter-like machines), X11 (for previewing), TeX DVI, HP +LaserJet 4/PCL5 and Canon LBP printers (which use CaPSL), +HTML, XHTML, and PDF. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Output-Language-Compatibility.html b/doc/groff.html.node/Output-Language-Compatibility.html new file mode 100644 index 0000000..4ad971f --- /dev/null +++ b/doc/groff.html.node/Output-Language-Compatibility.html @@ -0,0 +1,103 @@ + + + + + + +Output Language Compatibility (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: gtroff Output   [Contents][Index]

+
+
+

6.1.4 Output Language Compatibility

+ +

The intermediate output language of AT&T troff was +first documented in A Typesetter-independent TROFF, by Brian +Kernighan, and by 1992 the AT&T troff manual was +updated to incorprate a description of it. +

+

The GNU troff intermediate output format is compatible with this +specification except for the following features. +

+
    +
  • The classical quasi-device independence is not yet implemented. + +
  • The old hardware was very different from what we use today. So the +groff devices are also fundamentally different from the ones +in AT&T troff. For example, the AT&T +PostScript device is called post and has a resolution of only 720 +units per inch, suitable for printers 20 years ago, while groff’s +ps device has a resolution of 72000 units per inch. Maybe, by +implementing some rescaling mechanism similar to the classical +quasi-device independence, groff could emulate AT&T’s +post device. + +
  • The B-spline command ‘D~’ is correctly handled by the intermediate +output parser, but the drawing routines aren’t implemented in some of +the postprocessor programs. + +
  • The argument of the commands ‘s’ and ‘x H’ has the +implicit unit scaled point ‘z’ in gtroff, while +AT&T troff has point (‘p’). This isn’t an +incompatibility but a compatible extension, for both units coincide for +all devices without a sizescale parameter in the DESC +file, including all postprocessors from AT&T and +groff’s text devices. The few groff devices with a +sizescale parameter either do not exist for AT&T +troff, have a different name, or seem to have a different +resolution. So conflicts are very unlikely. + +
  • The position changing after the commands ‘Dp’, ‘DP’, and +‘Dt’ is illogical, but as old versions of gtroff used this +feature it is kept for compatibility reasons. + + +
+ + + +
+
+
+

+Previous: Intermediate Output Examples, Up: gtroff Output   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Page-Control.html b/doc/groff.html.node/Page-Control.html new file mode 100644 index 0000000..da2edc3 --- /dev/null +++ b/doc/groff.html.node/Page-Control.html @@ -0,0 +1,218 @@ + + + + + + +Page Control (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.18 Page Control

+ + + + + + + +

Discretionary page breaks can prevent the unwanted separation of +content. A new page number takes effect during page ejection; see +The Implicit Page Trap. +

+
+
Request: .bp [page-number]
+
+
Request: .bp +page-number
+
Request: .bp -page-number
+
Register: \n[%]
+
+ + +

Break the page and change (increase or decrease) the next page number +per the numeric expression page-number. If page-number is +invalid, GNU troff emits a warning in category ‘number’ and +ignores the argument. This request causes a break. A page break +advances the vertical drawing position to the bottom of the page, +springing traps. See Page Location Traps. + + + +bp has effect only if invoked within the top-level +diversion.71 + + +This request is incorrectly documented in the AT&T +troff manual as having a default scaling unit of ‘v’. +

+ + +

The register % interpolates the current page number. +

+
+
.de BP
+'  bp \" schedule page break once current line is output
+..
+
+
+ +
+
Request: .ne [space]
+
+ + + +

Force a page break if insufficient vertical space is available (assert +“needed” space). ne tests the distance to the next page +location trap; see Page Location Traps, and breaks the page if +that amount is less than space. The default scaling unit is +‘v’. If space is invalid, GNU troff emits a warning +in category ‘number’ and ignores the argument. If space is +not specified, ‘1v’ is assumed. +

+ +

We can require space for at least the first two output lines of a +paragraph, preventing its first line from being widowed at the +page bottom. +

+
+
.ne 2v
+Considering how common illness is,
+how tremendous the spiritual change that it brings,
+how astonishing,
+when the lights of health go down,
+the undiscovered countries that are then disclosed,
+what wastes and deserts of the soul a slight attack
+of influenza brings to view,
+
+ +

This method is reliable only if no output line is pending when ne +is invoked. When macro packages are used, this is often not the case: +their paragraphing macros perform the break. You may need to experiment +with placing the ne after the paragraphing macro, or br +and ne before it. +

+ + +

ne is also useful to force grouping of section headings with +their subsequent paragraphs, or tables with their captions and/or +explanations. Macro packages often use ne with diversions to +implement keeps and displays; see Diversions. They may also offer +parameters for widow and orphan management. +

+ +
+
Request: .sv [space]
+
+
Request: .os
+
+ +

Require vertical space as ne does, but also save it for +later output by the os request. If space is available +before the next page location trap, it is output immediately. Both +requests ignore a partially collected line, taking effect at the next +break. + + +sv and os ignore no-space mode (recall Manipulating Spacing). While the sv request allows negative values for +space, os ignores them. The default scaling unit is +‘v’. If space is not specified, ‘1v’ is assumed. +

+ +
+
Register: \n[nl]
+
+ + + +

nl interpolates or sets the vertical drawing position. When the +formatter starts, the first page transition hasn’t happened yet, and +nl is negative. If a header trap has been planted on the page +(typically at vertical position 0), you can assign a negative +value to nl to spring it if that page has already started +(see Page Location Traps). +

+
+
.de HD
+.  sp
+.  tl ''Goldbach Solution''
+.  sp
+..
+.
+First page.
+.bp
+.wh 0 HD \" plant header trap at top of page
+.nr nl (-1)
+Second page.
+    ⇒ First page.
+    ⇒
+    ⇒ (blank lines elided)
+    ⇒
+    ⇒                         Goldbach Solution
+    ⇒
+    ⇒ (blank lines elided)
+    ⇒
+    ⇒ Second page.
+
+ +

Without resetting nl to a negative value, the trap just planted +would be active beginning with the next page, not the current +one. +

+

See Diversions, for a comparison of nl with the .h and +.d registers. +

+ + + +
+
+
+

+Next: Using Fonts, Previous: Page Layout, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Page-Geometry.html b/doc/groff.html.node/Page-Geometry.html new file mode 100644 index 0000000..1486533 --- /dev/null +++ b/doc/groff.html.node/Page-Geometry.html @@ -0,0 +1,140 @@ + + + + + + +Page Geometry (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.2 Page Geometry

+ + + +

roff systems format text under certain assumptions about the size +of the output medium, or page. For the formatter to correctly break a +line it is filling, it must know the line length, which it derives from +the page width (see Line Layout). For it to decide whether to write +an output line to the current page or wait until the next one, it must +know the page length (see Page Layout). +

+ + + + + + +

A device’s resolution converts practical units like inches or +centimeters to basic units, a convenient length measure for the +output device or file format. The formatter and output driver use basic +units to reckon page measurements. The device description file defines +its resolution and page dimensions (see DESC File Format). +

+ +

A page is a two-dimensional structure upon which a roff +system imposes a rectangular coordinate system with its upper left +corner as the origin. Coordinate values are in basic units and increase +down and to the right. Useful ones are therefore always positive and +within numeric ranges corresponding to the page boundaries. +

+ + +

While the formatter (and, later, output driver) is processing a page, it +keeps track of its drawing position, which is the location at +which the next glyph will be written, from which the next motion will be +measured, or where a geometric object will commence rendering. + + +Notionally, glyphs are drawn from the text baseline upward and to the +right.33 The text baseline is a (usually invisible) line upon +which the glyphs of a typeface are aligned. A glyph therefore +“starts” at its bottom-left corner. If drawn at the origin, a typical +letter glyph would lie partially or wholly off the page, depending on +whether, like “g”, it features a descender below the baseline. +

+ + +

Such a situation is nearly always undesirable. It is furthermore +conventional not to write or draw at the extreme edges of the page. +Therefore the initial drawing position of a roff formatter is not +at the origin, but below and to the right of it. This rightward shift +from the left edge is known as the page +offset.34 The downward shift leaves room for a text output +line. +

+

Text is arranged on a one-dimensional lattice of text baselines from the +top to the bottom of the page. + + + +Vertical spacing is the distance between adjacent text baselines. +Typographic tradition sets this quantity to 120% of the type size. The +initial drawing position is one unit of vertical spacing below the page +top. Typographers term this unit a vee. +

+ + + + +

Vertical spacing has an impact on page-breaking decisions. Generally, +when a break occurs, the formatter moves the drawing position to the +next text baseline automatically. If the formatter were already writing +to the last line that would fit on the page, advancing by one vee would +place the next text baseline off the page. Rather than let that happen, +roff formatters instruct the output driver to eject the page, +start a new one, and again set the drawing position to one vee below the +page top; this is a page break. +

+

When the last line of input text corresponds to the last output line +that fits on the page, the break caused by the end of input will also +break the page, producing a useless blank one. Macro packages keep +users from having to confront this difficulty by setting “traps” +(see Traps); moreover, all but the simplest page layouts tend to +have headers and footers, or at least bear vertical margins larger than +one vee. +

+ + +
+
+
+

+Next: Measurements, Previous: Text, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Page-Layout-Adjustment.html b/doc/groff.html.node/Page-Layout-Adjustment.html new file mode 100644 index 0000000..7570214 --- /dev/null +++ b/doc/groff.html.node/Page-Layout-Adjustment.html @@ -0,0 +1,57 @@ + + + + + + +Page Layout Adjustment (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.4 Page Layout

+ +

Most macro packages let the user specify the size of the page margins. +The top and bottom margins are typically handled differently than the +left and right margins; the latter two are derived from the +page offset, indentation, and line length. +See Line Layout. Commonly, packages support registers to tune these +values. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Page-Layout.html b/doc/groff.html.node/Page-Layout.html new file mode 100644 index 0000000..8a6a4ad --- /dev/null +++ b/doc/groff.html.node/Page-Layout.html @@ -0,0 +1,188 @@ + + + + + + +Page Layout (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.17 Page Layout

+ + + +

The formatter permits configuration of the page length and page number. +

+
+
Request: .pl [length]
+
+
Request: .pl +length
+
Request: .pl -length
+
Register: \n[.p]
+
+ + + + +

Change (increase or decrease) the page length per the numeric expression +length. The default scaling unit is ‘v’. A negative +length is valid, but an uncommon application: it prevents page +location traps from being sprung,70 and each +output line is placed on a new page. If length is invalid, GNU +troff emits a warning in category ‘number’. If length +is absent or invalid, ‘11i’ is assumed. +

+ +

The read-only register ‘.p’ interpolates the current page length. +

+ +
+
Request: .pn num
+
+
Request: .pn +num
+
Request: .pn -num
+
Register: \n[.pn]
+
+ + + +

Change (increase or decrease) the page number of the next page +per the numeric expression num. If num is invalid, GNU +troff emits a warning in category ‘number’ and ignores the +request. Without an argument, pn is ignored. +

+ + +

The read-only register .pn interpolates num if set by +pn on the current page, or the current page number plus 1. +

+ + + + +

The formatter offers special support for typesetting headers and +footers, collectively termed titles. Titles have an independent +line length, and their placement on the page is not restricted. +

+
+
Request: .tl 'left'center'right'
+
+ + + + +

Format an output line as a title consisting of left, center, +and right, each aligned accordingly. The delimiter need not be a +neutral apostrophe: tl accepts the same delimiters as most escape +sequences; see Delimiters. If not used as the delimiter, any +page number character character is replaced with the current page +number; the default is ‘%’; see the the pc request below. +Without an argument, tl is ignored. tl writes the title +line immediately, ignoring any partially collected line. +

+

It is not an error to omit delimiters after the first. For example, +‘.tl /Thesis’ is interpreted as ‘.tl /Thesis///’: it +sets a title line comprising only the left-aligned word ‘Thesis’. +

+ +
+
Request: .lt [length]
+
+
Request: .lt +length
+
Request: .lt -length
+
Register: \n[.lt]
+
+ + +

Change (increase or decrease) the line length used by titles per the +numeric expression length. The default scaling unit is ‘m’. +If length is negative, GNU emits a warning in category +‘range’ and treats length as ‘0’. If length is +invalid, GNU troff emits a warning in category ‘number’ and +ignores the request. The formatter’s default title length is +‘6.5i’. With no argument, the title length is restored to the +previous value. The title length is is associated with the environment +(see Environments). +

+ +

The read-only register ‘.lt’ interpolates the title line length. +

+ +
+
Request: .pc [char]
+
+ + + +

Set the page number character to char. With no argument, the page +number character is disabled. pc does not affect the +register %. +

+ +

The following example exercises title features. +

+
+
.lt 50n
+This is my partially collected
+.tl 'Isomers 2023'%'Dextrose Edition'
+line.
+    ⇒ Isomers 2023             1        Dextrose Edition
+    ⇒ This is my partially collected line.
+
+ +

We most often see titles used in page header and footer traps. +See Traps. +

+ +
+
+
+

+Next: Page Control, Previous: Line Continuation, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Page-Location-Traps.html b/doc/groff.html.node/Page-Location-Traps.html new file mode 100644 index 0000000..3d388bf --- /dev/null +++ b/doc/groff.html.node/Page-Location-Traps.html @@ -0,0 +1,326 @@ + + + + + + +Page Location Traps (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Vertical Position Traps   [Contents][Index]

+
+
+

5.28.1.1 Page Location Traps

+ + + +

A page location trap is a vertical position trap that applies to +the page; that is, to undiverted output. Many can be present; manage +them with the wh and ch requests. +

+
+
Request: .wh dist [name]
+
+

Plant macro name as page location trap at dist. The default +scaling unit is ‘v’. Non-negative values for dist set the +trap relative to the top of the page; negative values set the trap +relative to the bottom of the page. It is not possible to plant a trap +less than one basic unit from the page bottom: a dist of -0 +is interpreted as 0, the top of the page.106 An existing visible trap (see below) at +dist is removed; this is wh’s sole function if name +is missing. +

+

A trap is sprung only if it is visible, meaning that its location +is reachable on the page107 and it +is not hidden by another trap at the same location already planted +there. +

+ + + + + + + + +

A macro package might set headers and footers as follows; this example +configures vertical margins of one inch to the body text, and one +half-inch to the titles. Observe the use of the no-break control +character with sp request to position our text baselines, +and the page number character ‘%’ used with the tl request. +

+
+
.\" hdfo.roff
+.de hd                  \" page header
+'  sp .5i
+'  tl '\\*(Ti''\\*(Da'  \" title and date strings
+'  sp .5i
+..
+.de fo                  \" page footer
+'  sp .5i
+.  tl ''%''
+.  bp
+..
+.wh 0   hd             \" trap at top of the page
+.wh -1i fo             \" trap 1 inch from bottom
+
+ +

To use these traps, copy the above (or load it from a file with the +so or mso requests), then set up the strings it uses. +

+
+
.so hdfo.roff
+.ds Ti Final Report\"
+.ds Da 21 May 2023\"
+.ti
+On 5 August of last year,
+this committee tasked me with the investigation of the
+CFIT (controlled flight into terrain) incident of
+.\" ...and so on...
+
+ +

A trap above the top or at or below the bottom of the page can be made +visible by either moving it into the page area or increasing the page +length so that the trap is on the page. Negative trap values always use +the current page length; they are not converted to an absolute +vertical position. + + +We can use the ptr request to dump our page location traps to the +standard error stream (see Debugging). Their positions are reported +in basic units; an nroff device example follows. +

+
+
.pl 5i
+.wh -1i xx
+.ptr
+    error→ xx      -240
+.pl 100i
+.ptr
+    error→ xx      -240
+
+ +

It is possible to have more than one trap at the same location (although +only one at a time can be visible); to achieve this, the traps must be +defined at different locations, then moved to the same place with the +ch request. In the following example, the many empty lines +caused by the bp request are not shown in the output. +

+
+
.de a
+.  nop a
+..
+.de b
+.  nop b
+..
+.de c
+.  nop c
+..
+.
+.wh 1i a
+.wh 2i b
+.wh 3i c
+.bp
+    ⇒ a b c
+
+
+
.ch b 1i
+.ch c 1i
+.bp
+    ⇒ a
+
+
+
.ch a 0.5i
+.bp
+    ⇒ a b
+
+
+ +
+
Register: \n[.t]
+
+ + +

The read-only register .t holds the distance to the next vertical +position trap. If there are no traps between the current position and +the bottom of the page, it contains the distance to the page bottom. +Within a diversion, in the absence of a diversion trap, this distance is +the largest representable integer in basic units—effectively infinite. +

+ +
+
Request: .ch name [dist]
+
+ + +

Change the location of a trap by moving macro name to new location +dist, or by unplanting it altogether if dist is absent. The +default scaling unit is ‘v’. Parameters to ch are specified +in the opposite order from wh. If name is the earliest +planted macro of multiple traps at the same location, (re)moving it from +that location exposes the macro next least recently planted at the same +place.108 +

+

Changing a trap’s location is useful for building up footnotes in a +diversion to allow more space at the bottom of the page for them. +

+ +
+ +

The same macro can be installed simultaneously at multiple locations; +however, only the earliest-planted instance—that has not yet been +deleted with wh—will be moved by ch. The following +example (using an nroff device) illustrates this behavior. Blank +lines have been elided from the output. +

+
+
.de T
+Trap sprung at \\n(nlu.
+.br
+..
+.wh 1i T
+.wh 2i T
+foo
+.sp 11i
+.bp
+.ch T 4i
+bar
+.sp 11i
+.bp
+.ch T 5i
+baz
+.sp 11i
+.bp
+.wh 5i
+.ch T 6i
+qux
+.sp 11i
+
+
+
    ⇒ foo
+    ⇒ Trap sprung at 240u.
+    ⇒ Trap sprung at 480u.
+    ⇒ bar
+    ⇒ Trap sprung at 480u.
+    ⇒ Trap sprung at 960u.
+    ⇒ baz
+    ⇒ Trap sprung at 480u.
+    ⇒ Trap sprung at 1200u.
+    ⇒ qux
+    ⇒ Trap sprung at 1440u.
+
+ +
+
Register: \n[.ne]
+
+

The read-only register .ne contains the amount of space that was +needed in the last ne request that caused a trap to be sprung; +it is useful in conjunction with the .trunc register. See Page Control. Since the .ne register is set only by traps, it +doesn’t make sense to interpolate it outside of macros called by traps. +

+ +
+
Register: \n[.trunc]
+
+ + +

A read-only register containing the amount of vertical space truncated +from an sp request by the most recently sprung vertical +position trap, or, if the trap was sprung by an ne request, +minus the amount of vertical motion produced by the ne +request. In other words, at the point a trap is sprung, it +represents the difference of what the vertical position would have +been but for the trap, and what the vertical position actually is. +Since the .trunc register is set only by traps, it doesn’t make +sense to interpolate it outside of macros called by traps. +

+ +
+
Register: \n[.pe]
+
+ + + +

This Boolean-valued, read-only register interpolates 1 while a page +is being ejected, and 0 otherwise. +

+

In the following example, we plant the same trap at the top and the +bottom of the page. We also make the trap report its name and the +vertical drawing position. +

+
+
.de T
+.tm \\$0: page \\n%, nl=\\n[nl] .pe=\\n[.pe]
+..
+.ll 46n
+.wh 0 T
+.wh -1v T
+Those who can make you believe absurdities can make you
+commit atrocities. \[em] Voltaire
+    error→ T: page 1, nl=0 .pe=0
+    error→ T: page 1, nl=2600 .pe=1
+    ⇒ Those who can make you believe absurdities can
+    ⇒ make you commit atrocities. -- Voltaire
+
+
+ + + +

When designing macros, keep in mind that diversions and traps do +normally interact. For example, if a trap calls a header macro (while +outputting a diversion) that tries to change the font on the current +page, the effect is not visible before the diversion has completely been +printed (except for input protected with \! or \?) since +the data in the diversion is already formatted. In most cases, this is +not the expected behaviour. +

+ +
+
+
+

+Next: The Implicit Page Trap, Previous: Vertical Position Traps, Up: Vertical Position Traps   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Page-Motions.html b/doc/groff.html.node/Page-Motions.html new file mode 100644 index 0000000..bb94bdb --- /dev/null +++ b/doc/groff.html.node/Page-Motions.html @@ -0,0 +1,454 @@ + + + + + + +Page Motions (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.25 Page Motions

+ + + +

See Manipulating Spacing, for a discussion of the most commonly used +request for vertical motion, sp, which spaces downward by one +vee. +

+
+
Request: .mk [reg]
+
+
Request: .rt [dist]
+
+ + + + + + + + +

You can mark a location on a page for subsequent return. +mk takes an argument, a register name in which to store the +current page location. If given no argument, it stores the location in +an internal register. This location can be used later by the rt +or the sp requests (or the \v escape). +

+

The rt request returns upward to the location marked with +the last mk request. If used with an argument, it returns to a +vertical position dist from the top of the page (no previous +call to mk is necessary in this case). The default scaling +unit is ‘v’. +

+

If a page break occurs between a mk request and its matching +rt request, the rt request is silently ignored. +

+

A simple implementation of a macro to set text in two columns follows. +

+
+
.nr column-length 1.5i
+.nr column-gap 4m
+.nr bottom-margin 1m
+.
+.de 2c
+.  br
+.  mk
+.  ll \\n[column-length]u
+.  wh -\\n[bottom-margin]u 2c-trap
+.  nr right-side 0
+..
+.
+.de 2c-trap
+.  ie \\n[right-side] \{\
+.    nr right-side 0
+.    po -(\\n[column-length]u + \\n[column-gap]u)
+.    \" remove trap
+.    wh -\\n[bottom-margin]u
+.  \}
+.  el \{\
+.    \" switch to right side
+.    nr right-side 1
+.    po +(\\n[column-length]u + \\n[column-gap]u)
+.    rt
+.  \}
+..
+
+ +

Now let us apply our two-column macro. +

+
+
.pl 1.5i
+.ll 4i
+This is a small test that shows how the
+rt request works in combination with mk.
+
+.2c
+Starting here, text is typeset in two columns.
+Note that this implementation isn't robust
+and thus not suited for a real two-column
+macro.
+    ⇒ This is a small test that shows how the
+    ⇒ rt request works in combination with mk.
+    ⇒
+    ⇒ Starting  here,    isn't    robust
+    ⇒ text is typeset    and   thus  not
+    ⇒ in two columns.    suited  for   a
+    ⇒ Note that  this    real two-column
+    ⇒ implementation     macro.
+
+
+ +

Several escape sequences enable fine control of movement about the page. +

+
+
Escape sequence: \v'expr'
+
+ + +

Vertically move the drawing position. expr indicates the +magnitude of motion: positive is downward and and negative upward. The +default scaling unit is ‘v’. The motion is relative to the current +drawing position unless expr begins with the boundary-relative +motion operator ‘|’. See Numeric Expressions. +

+

Text processing continues at the new drawing position; usually, vertical +motions should be in balanced pairs to avoid a confusing page layout. +

+

\v will not spring a vertical position trap. This can be useful; +for example, consider a page bottom trap macro that prints a marker in +the margin to indicate continuation of a footnote. See Traps. +

+ +

A few escape sequences that produce vertical motion are unusual. They +are thought to originate early in AT&T nroff history to achieve +super- and subscripting by half-line motions on line printers and +teletypewriters before the phototypesetter made more precise positioning +available. They are reckoned in ems—not vees—to maintain continuity +with their original purpose of moving relative to the size of the type +rather than the distance between text baselines (vees).103 +

+
+
Escape sequence: \r
+
+
Escape sequence: \u
+
+
Escape sequence: \d
+
+

Move upward 1m, upward .5m, and +downward .5m, respectively. +

+ +

Let us see these escape sequences in use. +

+
+
Obtain 100 cm\u3\d of \ka\d\092\h'|\nau'\r233\dU.
+
+ +

In the foregoing we have paired \u and \d to typeset a +superscript, and later a full em negative (“reverse”) motion to place +a superscript above a subscript. A numeral-width horizontal motion +escape sequence aligns the proton and nucleon numbers, while \k +marks a horizontal position to which \h returns so that we could +stack them. (We shall discuss these horizontal motion escape sequences +presently.) In serious applications, we often want to alter the type +size of the -scripts and to fine-tune the vertical motions, as the +groff ms package does with its super- and subscripting +string definitions. +

+
+
Escape sequence: \h'expr'
+
+ + + + + +

Horizontally move the drawing position. expr indicates the +magnitude of motion: positive is rightward and negative leftward. The +default scaling unit is ‘m’. The motion is relative to the current +drawing position unless expr begins with the boundary-relative +motion operator ‘|’. See Numeric Expressions. +

+ +

The following string definition sets the TeX +logo.104 +

+
+
.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\"
+
+ +

There are a number of special-case escape sequences for horizontal +motion. +

+
+
Escape sequence: \SP
+
+ + + + +

Move right one word space. (The input is a backslash followed by a +space.) This escape sequence can be thought of as a non-adjustable, +unbreakable space. Usually you want \~ instead; see +Manipulating Filling and Adjustment. +

+ + + +
+
Escape sequence: \|
+
+

Move one-sixth em to the right on typesetting output devices. If +a glyph named ‘\|’ is defined in the current font, its width is +used instead, even on terminal output devices. +

+ + + +
+
Escape sequence: \^
+
+

Move one-twelfth em to the right on typesetting output devices. +If a glyph named ‘\^’ is defined in the current font, its width is +used instead, even on terminal output devices. +

+ +
+
Escape sequence: \0
+
+ + + + +

Move right by the width of a numeral in the current font. +

+ +

Horizontal motions are not discarded at the end of an output line as +word spaces are. See Breaking. +

+
+
Escape sequence: \w'anything'
+
+
Register: \n[st]
+
+
Register: \n[sb]
+
+
Register: \n[rst]
+
+
Register: \n[rsb]
+
+
Register: \n[ct]
+
+
Register: \n[ssc]
+
+
Register: \n[skw]
+
+ +

Interpolate the width of anything in basic units. This escape +sequence allows several properties of formatted output to be measured +without writing it out. +

+
+
The length of the string 'abc' is \w'abc'u.
+    ⇒ The length of the string 'abc' is 72u.
+
+ + + +

anything is processed in a dummy environment: this means that +font and type size changes, for example, may occur within it without +affecting subsequent output. +

+

After each use, \w sets several registers. +

+ + + +
+
st
+
sb
+

The maximum vertical displacements of the text baseline above and below, +respectively. The sign convention is opposite that of relative vertical +motions; that is, depth below the (original) baseline is negative. +These registers are incorrectly documented in the AT&T +troff manual as “the highest and lowest extent of [the argument +to \w] relative to the baseline”. +

+
+
rst
+
rsb
+

Like st and sb, but taking account of the heights and +depths of glyphs. In other words, these registers store the highest and +lowest vertical positions attained by anything, doing what +AT&T troff documented st and sb as doing. +

+
+
ct
+

Characterizes the geometry of glyphs occurring in anything. +

+
+
0
+

only short glyphs, no descenders or tall glyphs +

+
+
1
+

at least one descender +

+
+
2
+

at least one tall glyph +

+
+
3
+

at least one each of a descender and a tall glyph +

+
+ +
+
ssc
+

The amount of horizontal space (possibly negative) that should be added +to the last glyph before a subscript. +

+
+
skw
+

How far to right of the center of the last glyph in the \w +argument, the center of an accent from a roman font should be placed +over that glyph. +

+
+
+ +
+
Escape sequence: \kp
+
+
Escape sequence: \k(ps
+
Escape sequence: \k[position]
+
+ + + + +

Store the current horizontal position in the input line in a +register with the name position (one-character name p, +two-character name ps). Use this, for example, to return to the +beginning of a string for highlighting or other decoration. +

+ +
+
Register: \n[hp]
+
+ + + + +

The current horizontal position at the input line. +

+ +
+
Register: \n[.k]
+
+ + + + +

A read-only register containing the current horizontal output position +(relative to the current indentation). +

+ +
+
Escape sequence: \o'abc…'
+
+ + +

Overstrike the glyphs of characters a, b, c, …; +the glyphs are centered, written, and the drawing position advanced by +the widest of the glyphs. +

+ +
+
Escape sequence: \zc
+
+ + +

Format the character c with zero width; that is, without advancing +the drawing position. Use \z to overstrike glyphs aligned to +their left edges, in contrast to \o’s centering. +

+ +
+
Escape sequence: \Z'anything'
+
+ + +

Save the drawing position, format anything, then restore it. Tabs +and leaders in the argument are ignored with an error diagnostic. +

+

We might implement a strike-through macro thus. +

+
+
.de ST
+.nr width \w'\\$1'
+\Z@\v'-.25m'\l'\\n[width]u'@\\$1
+..
+.
+This is
+.ST "a test"
+an actual emergency!
+
+
+ + + +
+
+
+

+Next: Drawing Geometric Objects, Previous: Writing Macros, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Paper-Format.html b/doc/groff.html.node/Paper-Format.html new file mode 100644 index 0000000..f6f9e72 --- /dev/null +++ b/doc/groff.html.node/Paper-Format.html @@ -0,0 +1,101 @@ + + + + + + +Paper Format (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Invoking groff   [Contents][Index]

+
+
+

2.5 Paper Format

+ + + + + + + + +

In groff, the page dimensions for the formatter GNU troff +and for output devices are handled separately. See Page Layout, for +vertical manipulation of the page size, and See Line Layout, for +horizontal changes. + + +The papersize macro package, normally loaded by troffrc at +startup, provides an interface for configuring page dimensions by +convenient names, like ‘letter’ or ‘a4’; see +groff_tmac(5). The default used by the formatter depends on +its build configuration, but is usually one of the foregoing, as +geographically appropriate. +

+

It is up to each macro package to respect the page dimensions configured +in this way. +

+

For each output device, the size of the output medium can be set in its +DESC file. Most output drivers also recognize a command-line +option -p to override the default dimensions and an option +-l to use landscape orientation. See DESC File Format, for +a description of the papersize keyword, which takes an argument +of the same form as -p. The output driver’s man page, such as +grops(1), may also be helpful. +

+

groff uses the command-line option -P to pass options to +postprocessors; for example, use the following for PostScript output on +A4 paper in landscape orientation. +

+
+
groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
+
+ + + +
+
+
+

+Next: Invocation Examples, Previous: Font Directories, Up: Invoking groff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Paragraphs-in-ms.html b/doc/groff.html.node/Paragraphs-in-ms.html new file mode 100644 index 0000000..e6c3a28 --- /dev/null +++ b/doc/groff.html.node/Paragraphs-in-ms.html @@ -0,0 +1,160 @@ + + + + + + +Paragraphs in ms (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+
+

4.6.5.3 Paragraphs

+ + +

Paragraphing macros break, or terminate, any pending output line +so that a new paragraph can begin. Several paragraph types are +available, differing in how indentation applies to them: to left, right, +or both margins; to the first output line of the paragraph, all output +lines, or all but the first. All paragraphing macro calls cause the +insertion of vertical space in the amount stored in the PD +register, except at page or column breaks. Alternatively, a blank input +line breaks the output line and vertically spaces by one vee. +

+
+
Macro: .LP
+
+

Set a paragraph without any (additional) indentation. +

+ +
+
Macro: .PP
+
+

Set a paragraph with a first-line left indentation in the amount stored +in the PI register. +

+ +
+
Macro: .IP [marker [width]]
+
+

Set a paragraph with a left indentation. The optional marker is +not indented and is empty by default. It has several applications; +see Lists. width overrides the indentation amount +stored in the PI register; its default unit is ‘n’. Once +specified, width applies to further IP calls until +specified again or a heading or different paragraphing macro is called. +

+ +
+
Macro: .QP
+
+

Set a paragraph indented from both left and right margins by the amount +stored in the QI register. +

+ +
+
Macro: .QS
+
+
Macro: .QE
+
+

Begin (QS) and end (QE) a region where each paragraph is +indented from both margins by the amount stored in the QI +register. The text between QS and QE can be structured +further by use of other paragraphing macros. +

+ +
+
Macro: .XP
+
+

Set an “exdented” paragraph—one with a left indentation in the +amount stored in the PI register on every line except the +first (also known as a hanging indent). This is a Berkeley extension. +

+ +

The following example illustrates the use of paragraphing macros. +

+
+
+
.NH 2
+Cases used in the 2001 study
+.LP
+Two software releases were considered for this report.
+.PP
+The first is commercial software;
+the second is free.
+.IP \[bu]
+Microsoft Word for Windows,
+starting with version 1.0 through the current version
+(Word 2000).
+.IP \[bu]
+GNU Emacs,
+from its first appearance as a standalone editor through
+the current version (v20).
+See [Bloggs 2002] for details.
+.QP
+Franklin's Law applied to software:
+software expands to outgrow both RAM and disk space over
+time.
+.SH
+Bibliography
+.XP
+Bloggs, Joseph R.,
+.I "Everyone's a Critic" ,
+Underground Press, March 2002.
+A definitive work that answers all questions and
+criticisms about the quality and usability of free
+software.
+
+
+ + +
+
+
+

+Next: Headings, Previous: Typographical symbols, Up: Body Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Paragraphs.html b/doc/groff.html.node/Paragraphs.html new file mode 100644 index 0000000..a230bcd --- /dev/null +++ b/doc/groff.html.node/Paragraphs.html @@ -0,0 +1,109 @@ + + + + + + +Paragraphs (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.1 Paragraphs

+ + +

Paragraphs can be separated and indented in various ways. Some start +with a blank line and have a first-line indentation, like most of the +ones in this manual. Block paragraphs omit the indentation. +

+
+
  ⇒ Some  men  look  at constitutions with sanctimonious
+  ⇒ reverence,  and  deem  them  like  the  ark  of  the
+  ⇒ covenant, too sacred to be touched.
+
+ + + + +

We also frequently encounter tagged paragraphs, which begin +with a tag or label at the left margin and indent the remaining text. +

+
+
  ⇒ one  This  is the first paragraph.  Notice how the
+  ⇒      first line of the resulting  paragraph  lines
+  ⇒      up with the other lines in the paragraph.
+
+ +

If the tag is too wide for the indentation, the line is broken. +

+
+
  ⇒ longlabel
+  ⇒      The  label does not align with the subsequent
+  ⇒      lines, but they align with each other.
+
+ +

A variation of the tagged paragraph is the itemized or enumerated +paragraph, which might use punctuation or a digit for a tag, +respectively. These are frequently used to construct lists. +

+
+
  ⇒ o    This  list  item  starts with a bullet.  When
+  ⇒      producing output for a device using the ASCII
+  ⇒      character set, an 'o' is formatted instead.
+
+ +

Often, use of the same macro without a tag continues such a discussion. +

+
+
  ⇒ -xyz  This option is recognized but ignored.
+  ⇒
+  ⇒       It had a security hole that we don't discuss.
+
+ + +
+
+
+

+Next: Sections and Chapters, Previous: Common Features, Up: Common Features   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Parameters.html b/doc/groff.html.node/Parameters.html new file mode 100644 index 0000000..ddf31cf --- /dev/null +++ b/doc/groff.html.node/Parameters.html @@ -0,0 +1,195 @@ + + + + + + +Parameters (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Writing Macros   [Contents][Index]

+
+
+

5.24.1 Parameters

+ + +

Macro calls and string interpolations optionally accept a list of +arguments; recall Calling Macros. At the time such an +interpolation takes place, these parameters can be examined using +a register and a variety of escape sequences starting with ‘\$’. +All such escape sequences are interpreted even in copy mode, a fact we +shall motivate and explain below (see Copy Mode). +

+
+
Register: \n[.$]
+
+ +

The count of parameters available to a macro or string is kept in this +read-only register. The shift request can change its value. +

+ +

Any individual parameter can be accessed by its position in the list of +arguments to the macro call, numbered from left to right starting at 1, +with one of the following escape sequences. +

+
+
Escape sequence: \$n
+
+
Escape sequence: \$(nn
+
Escape sequence: \$[nnn]
+

Interpolate the nth, nnth, or nnnth parameter. The +first form expects only a single digit (1≤n≤9)), the +second two digits (01≤nn≤99)), and the third any +positive integer nnn. Macros and strings accept an unlimited +number of parameters. +

+ +
+
Request: .shift [n]
+
+

Shift the parameters n places (1 by default). This is a +“left shift”: what was parameter i becomes parameter +i-n. The parameters formerly in positions 1 +to n are no longer available. Shifting by a non-positive +amount performs no operation. The register .$ is adjusted +accordingly. +

+ + + + + +

In practice, parameter interpolations are usually seen prefixed with an +extra escape character. This is because the \$ family of escape +sequences is interpreted even in copy mode.100 +

+
+
Escape sequence: \$*
+
+
Escape sequence: \$@
+
+
Escape sequence: \$^
+
+

In some cases it is convenient to interpolate all of the parameters at +once (to pass them to a request, for instance). The \$* escape +concatenates the parameters, separating them with spaces. \$@ +is similar, concatenating the parameters, surrounding each with double +quotes and separating them with spaces. If not in compatibility mode, +the interpolation depth of double quotes is preserved (see Calling Macros). \$^ interpolates all parameters as if they were +arguments to the ds request. +

+
+
.de foo
+. tm $1='\\$1'
+. tm $2='\\$2'
+. tm $*='\\$*'
+. tm $@='\\$@'
+. tm $^='\\$^'
+..
+.foo " This is a "test"
+    error→ $1=' This is a '
+    error→ $2='test"'
+    error→ $*=' This is a  test"'
+    error→ $@='" This is a " "test""'
+    error→ $^='" This is a "test"'
+
+ +

\$* is useful when writing a macro that doesn’t need to +distinguish its arguments, or even to not interpret them; examples +include macros that produce diagnostic messages by wrapping the +tm or ab requests. Use \$@ when writing a macro +that may need to shift its parameters and/or wrap a macro or request +that finds the count significant. If in doubt, prefer \$@ to +\$*. An application of \$^ is seen in trace.tmac, +which redefines some requests and macros for debugging purposes. +

+ +
+
Escape sequence: \$0
+
+ + +

Interpolate the name by which the macro being interpreted was called. +The als request can cause a macro to have more than one name. +Applying string interpolation to a macro does not change this name. +

+
+
.de foo
+.  tm \\$0
+..
+.als bar foo
+.
+.de aaa
+.  foo
+..
+.de bbb
+.  bar
+..
+.de ccc
+\\*[foo]\\
+..
+.de ddd
+\\*[bar]\\
+..
+.
+.aaa
+    error→ foo
+.bbb
+    error→ bar
+.ccc
+    error→ ccc
+.ddd
+    error→ ddd
+
+
+ + +
+
+
+

+Next: Copy Mode, Previous: Writing Macros, Up: Writing Macros   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Postprocessor-Access.html b/doc/groff.html.node/Postprocessor-Access.html new file mode 100644 index 0000000..3b06a80 --- /dev/null +++ b/doc/groff.html.node/Postprocessor-Access.html @@ -0,0 +1,144 @@ + + + + + + +Postprocessor Access (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.34 Postprocessor Access

+ + + +

Two escape sequences and two requests enable documents to pass +information directly to a postprocessor. These are useful for +exercising device-specific capabilities that the groff language +does not abstract or generalize; examples include the embedding of +hyperlinks and image files. Device-specific functions are documented in +each output driver’s man page, such as gropdf(1), +grops(1), or grotty(1). +

+
+
Request: .device xxx …
+
+
Escape sequence: \X'xxx …'
+
+

Embed all xxx arguments into GNU troff output as parameters +to a device control command ‘x X’. The meaning and +interpretation of such parameters is determined by the output driver or +other postprocessor. +

+ + + +

The device request processes its arguments in copy mode +(see Copy Mode). An initial neutral double quote in contents +is stripped to allow embedding of leading spaces. + + + + +By contrast, within \X arguments, the escape sequences \&, +\), \%, and \: are ignored; \SP and +\~ are converted to single space characters; and \\ has +its escape character stripped. So that the basic Latin subset of the +Unicode character set115 can be reliably encoded in device control +commands, seven special character escape sequences (‘\-’, +‘\[aq]’, ‘\[dq]’, ‘\[ga]’, ‘\[ha]’, ‘\[rs]’, +and ‘\[ti]’,) are mapped to basic Latin characters; see the +groff_char(7) man page. For this transformation, character +translations and special character definitions are +ignored.116 The use of any +other escape sequence in \X parameters is normally an error. +

+ + + +

If the use_charnames_in_special directive appears in the output +device’s DESC file, the use of special character escape sequences +is not an error; they are simply output verbatim (with the +exception of the seven mapped to Unicode basic Latin characters, +discussed above). use_charnames_in_special is currently employed +only by grohtml. +

+ +
+
Request: .devicem name
+
+
Escape sequence: \Yn
+
+
Escape sequence: \Y(nm
+
Escape sequence: \Y[name]
+

This is approximately equivalent to ‘\X'\*[name]'’ +(one-character name n, two-character name nm). +However, the contents of the string or macro name are not +interpreted; also it is permitted for name to have been defined as +a macro and thus contain newlines (it is not permitted for the argument +to \X to contain newlines). The inclusion of newlines requires +an extension to the AT&T troff output format, and +confuses drivers that do not know about this extension (see Device Control Commands). +

+ +
+
Request: .tag name
+
+
Request: .taga name
+
+

Reserved for internal use. +

+ + + +
+
+
+

+Next: Miscellaneous, Previous: I/O, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Predefined-Text.html b/doc/groff.html.node/Predefined-Text.html new file mode 100644 index 0000000..8b03b1f --- /dev/null +++ b/doc/groff.html.node/Predefined-Text.html @@ -0,0 +1,53 @@ + + + + + + +Predefined Text (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.12 Predefined Text

+ +

Most macro packages supply predefined strings to set prepared text like +the date, or to perform operations like super- and subscripting. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Preprocessor-Intro.html b/doc/groff.html.node/Preprocessor-Intro.html new file mode 100644 index 0000000..7bb43a7 --- /dev/null +++ b/doc/groff.html.node/Preprocessor-Intro.html @@ -0,0 +1,78 @@ + + + + + + +Preprocessor Intro (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+
+

1.5 Preprocessors

+ + +

An alternative approach to complexity management, particularly when +constructing tables, setting mathematics, or drawing diagrams, lies in +preprocessing. A preprocessor employs a domian-specific language +to ease the generation of tables, equations, and so forth in terms that +are convenient for human entry. Each preprocessor reads a document and +translates the parts of it that apply to it into GNU troff input. +Command-line options to groff tell it which preprocessors to +use. +

+

groff provides preprocessors for laying out tables +(gtbl), typesetting equations (geqn), drawing +diagrams (gpic and ggrn), inserting bibliographic +references (grefer), and drawing chemical structures +(gchem). An associated program that is useful when dealing +with preprocessors is gsoelim.1 +

+

groff also supports grap, a preprocessor for drawing +graphs. A free implementation of it can be obtained separately. +

+

Unique to groff is the preconv preprocessor that enables +groff to handle documents in a variety of input encodings. +

+

Other preprocessors exist, but no free implementations +are known. An example is ideal, which draws diagrams using a +mathematical constraint language. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Preprocessor-Support.html b/doc/groff.html.node/Preprocessor-Support.html new file mode 100644 index 0000000..43e961c --- /dev/null +++ b/doc/groff.html.node/Preprocessor-Support.html @@ -0,0 +1,56 @@ + + + + + + +Preprocessor Support (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.13 Preprocessor Support

+ +

All macro packages provide support for various preprocessors and may +extend their functionality by defining macros to set their contents in +displays. Examples include TS and TE for gtbl, +EQ and EN for geqn, and PS and PE +for gpic. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Program-and-File-Index.html b/doc/groff.html.node/Program-and-File-Index.html new file mode 100644 index 0000000..ecc30ec --- /dev/null +++ b/doc/groff.html.node/Program-and-File-Index.html @@ -0,0 +1,239 @@ + + + + + + +Program and File Index (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

Appendix I Program and File Index

+ +
+
Jump to:   A +   +C +   +D +   +E +   +F +   +G +   +I +   +J +   +L +   +M +   +N +   +P +   +R +   +S +   +T +   +V +   +Z +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
A
an.tmac: man
C
changebar: Miscellaneous
composite.tmac: Using Symbols
cp1047.tmac: Input Encodings
cs.tmac: Manipulating Hyphenation
D
de.tmac: Manipulating Hyphenation
DESC: Selecting Fonts
DESC: Font Families
DESC: Using Symbols
DESC: Using Symbols
DESC: Special Fonts
diffmk: Miscellaneous
E
ec.tmac: Input Encodings
en.tmac: Manipulating Hyphenation
eqn: ms Insertions
F
fr.tmac: Manipulating Hyphenation
freeeuro.pfa: Input Encodings
G
gchem: Groff Options
gdiffmk: Miscellaneous
geqn: Groff Options
ggrn: Groff Options
gpic: Groff Options
grap: Groff Options
grefer: Groff Options
groff: Groff Options
gsoelim: Groff Options
gtbl: Groff Options
gtroff: Groff Options
I
it.tmac: Manipulating Hyphenation
J
ja.tmac: Manipulating Hyphenation
L
latin1.tmac: Input Encodings
latin2.tmac: Input Encodings
latin5.tmac: Input Encodings
latin9.tmac: Input Encodings
M
makeindex: Indexing
man.local: Optional man extensions
man.tmac: man
man.ultrix: Optional man extensions
N
nrchbar: Miscellaneous
P
papersize.tmac: Paper Format
perl: I/O
pic: ms Insertions
post-grohtml: Groff Options
pre-grohtml: Groff Options
preconv: Groff Options
R
refer: ms Insertions
S
soelim: Debugging
sv.tmac: Manipulating Hyphenation
T
tbl: ms Insertions
trace.tmac: Writing Macros
troffrc: Groff Options
troffrc: Paper Format
troffrc: Manipulating Hyphenation
troffrc: Manipulating Hyphenation
troffrc: troff and nroff Modes
troffrc-end: Groff Options
troffrc-end: Manipulating Hyphenation
troffrc-end: troff and nroff Modes
tty.tmac: troff and nroff Modes
tty.tmac: Line Layout
V
vtroff: Operators in Conditionals
Z
zh.tmac: Manipulating Hyphenation
+
Jump to:   A +   +C +   +D +   +E +   +F +   +G +   +I +   +J +   +L +   +M +   +N +   +P +   +R +   +S +   +T +   +V +   +Z +   +
+
+ + + + +
+
+
+

+Next: Concept Index, Previous: File Keyword Index, Up: GNU troff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Punning-Names.html b/doc/groff.html.node/Punning-Names.html new file mode 100644 index 0000000..dde1a20 --- /dev/null +++ b/doc/groff.html.node/Punning-Names.html @@ -0,0 +1,190 @@ + + + + + + +Punning Names (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.30 Punning Names

+ + +

Macros, strings, and diversions share a name space; recall +Identifiers. Internally, the same mechanism is used to store +them. You can thus call a macro with string interpolation syntax and +vice versa. +

+
+
.de subject
+Typesetting
+..
+.de predicate
+rewards attention to detail
+..
+\*[subject] \*[predicate].
+Truly.
+    ⇒ Typesetting
+    ⇒  rewards attention to detail Truly.
+
+ +

What went wrong? Strings don’t contain newlines, but macros do. String +interpolation placed a newline at the end of ‘\*[subject]’, and the +next thing on the input was a space. Then when ‘\*[predicate]’ was +interpolated, it was followed by the empty request ‘.’ on a line by +itself. If we want to use macros as strings, we must take interpolation +behavior into account. +

+
+
.de subject
+Typesetting\\
+..
+.de predicate
+rewards attention to detail\\
+..
+\*[subject] \*[predicate].
+Truly.
+    ⇒ Typesetting rewards attention to detail.  Truly.
+
+ +

By ending each text line of the macros with an escaped +\RET, we get the desired effect (see Line Continuation).114 +What would have happened if we had used only one backslash at a time +instead? +

+

Interpolating a string does not hide existing macro arguments. We can +also place the escaped newline outside the string interpolation instead +of within the string definition. Thus, in a macro, a more efficient way +of doing +

+
+
.xx \\$@
+
+ +

is +

+
+
\\*[xx]\\
+
+ +

The latter calling syntax doesn’t change the value of \$0, which +is then inherited from the calling macro (see Parameters). +

+

Diversions can be also called with string syntax. It is sometimes +convenient to copy one-line diversions to a string. +

+
+
.di xx
+the
+.ft I
+interpolation system
+.ft
+.br
+.di
+.ds yy This is a test of \*(xx\c
+\*(yy.
+    ⇒ This is a test of the interpolation system.
+
+ +

As the previous example shows, it is possible to store formatted output +in strings. The \c escape sequence prevents the subsequent +newline from being interpreted as a break (again, +see Line Continuation). +

+

Copying multi-output line diversions produces unexpected results. +

+
+
.di xxx
+a funny
+.br
+test
+.br
+.di
+.ds yyy This is \*[xxx]\c
+\*[yyy].
+    ⇒ test This is a funny.
+
+ +

Usually, it is not predictable whether a diversion contains one or more +output lines, so this mechanism should be avoided. With AT&T +troff, this was the only solution to strip off a final newline +from a diversion. Another disadvantage is that the spaces in the copied +string are already formatted, preventing their adjustment. This can +cause ugly results. +

+ + + + + + + +

A clean solution to this problem is available in GNU troff, using +the requests chop to remove the final newline of a diversion, and +unformat to make the horizontal spaces adjustable again. +

+
+
.box xxx
+a funny
+.br
+test
+.br
+.box
+.chop xxx
+.unformat xxx
+This is \*[xxx].
+    ⇒ This is a funny test.
+
+ +

See gtroff Internals. +

+ +
+
+
+

+Next: Environments, Previous: Diversions, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Register-Index.html b/doc/groff.html.node/Register-Index.html new file mode 100644 index 0000000..979a346 --- /dev/null +++ b/doc/groff.html.node/Register-Index.html @@ -0,0 +1,349 @@ + + + + + + +Register Index (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

Appendix E Register Index

+ +

The macro package or program a specific register belongs to is appended +in brackets. +

+

A register name x consisting of exactly one character can be +accessed as ‘\nx’. A register name xx consisting of exactly +two characters can be accessed as ‘\n(xx’. Register names +xxx of any length can be accessed as ‘\n[xxx]’. +

+
+
Jump to:   $ +   +% +   +. +   +
+C +   +D +   +F +   +G +   +H +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +Y +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
$
$$: Built-in Registers
%
%: Page Layout
%: Page Control
.
.$: Parameters
.A: Built-in Registers
.a: Manipulating Spacing
.b: Artificial Fonts
.br: Control Characters
.c: Built-in Registers
.C: Compatibility Mode
.cdp: Environments
.ce: Manipulating Filling and Adjustment
.cht: Environments
.color: Colors
.cp: Compatibility Mode
.csk: Environments
.d: Diversions
.ev: Environments
.F: Built-in Registers
.f: Font Positions
.fam: Font Families
.fn: Selecting Fonts
.fp: Font Positions
.g: Built-in Registers
.H: Motion Quanta
.h: Diversions
.height: Artificial Fonts
.hla: Manipulating Hyphenation
.hlc: Manipulating Hyphenation
.hlm: Manipulating Hyphenation
.hy: Manipulating Hyphenation
.hym: Manipulating Hyphenation
.hys: Manipulating Hyphenation
.i: Line Layout
.in: Line Layout
.int: Line Continuation
.j: Manipulating Filling and Adjustment
.k: Page Motions
.kern: Ligatures and Kerning
.L: Manipulating Spacing
.l: Line Layout
.lg: Ligatures and Kerning
.linetabs: Tabs and Fields
.ll: Line Layout
.lt: Page Layout
.m: Colors
.M: Colors
.n: Environments
.ne: Page Location Traps
.nm: Miscellaneous
.nn: Miscellaneous
.ns: Manipulating Spacing
.o: Line Layout
.O: Suppressing Output
.P: Built-in Registers
.p: Page Layout
.pe: Page Location Traps
.pn: Page Layout
.ps: Using Fractional Type Sizes
.psr: Using Fractional Type Sizes
.pvs: Changing the Vertical Spacing
.R: Built-in Registers
.rj: Manipulating Filling and Adjustment
.s: Changing the Type Size
.slant: Artificial Fonts
.sr: Using Fractional Type Sizes
.ss: Manipulating Filling and Adjustment
.sss: Manipulating Filling and Adjustment
.sty: Font Families
.T: Built-in Registers
.t: Page Location Traps
.tabs: Tabs and Fields
.trunc: Page Location Traps
.U: Built-in Registers
.u: Manipulating Filling and Adjustment
.V: Motion Quanta
.v: Changing the Vertical Spacing
.vpt: Vertical Position Traps
.w: Environments
.warn: Debugging
.x: Built-in Registers
.y: Built-in Registers
.Y: Built-in Registers
.z: Diversions
.zoom: Selecting Fonts
C
c.: Built-in Registers
ct: Page Motions
D
DD [ms]: ms Document Control Settings
DI [ms]: ms Document Control Settings
dl: Diversions
dn: Diversions
dw: Built-in Registers
dy: Built-in Registers
F
FF [ms]: ms Document Control Settings
FI [ms]: ms Document Control Settings
FM [ms]: ms Document Control Settings
FPD [ms]: ms Document Control Settings
FPS [ms]: ms Document Control Settings
FVS [ms]: ms Document Control Settings
G
GROWPS [ms]: ms Document Control Settings
GS [ms]: Differences from AT&T ms
H
HM [ms]: ms Document Control Settings
HORPHANS [ms]: ms Document Control Settings
hours: Built-in Registers
hp: Page Motions
HY [ms]: ms Document Control Settings
L
LL [ms]: ms Document Control Settings
llx: Miscellaneous
lly: Miscellaneous
ln: Miscellaneous
lsn: Leading Space Traps
lss: Leading Space Traps
LT [ms]: ms Document Control Settings
M
MINGW [ms]: ms Document Control Settings
minutes: Built-in Registers
mo: Built-in Registers
N
nl: Page Control
O
opmaxx: Suppressing Output
opmaxy: Suppressing Output
opminx: Suppressing Output
opminy: Suppressing Output
P
PD [ms]: ms Document Control Settings
PI [ms]: ms Document Control Settings
PO [ms]: ms Document Control Settings
PORPHANS [ms]: ms Document Control Settings
PS [ms]: ms Document Control Settings
PSINCR [ms]: ms Document Control Settings
Q
QI [ms]: ms Document Control Settings
R
rsb: Page Motions
rst: Page Motions
S
sb: Page Motions
seconds: Built-in Registers
skw: Page Motions
slimit: Debugging
ssc: Page Motions
st: Page Motions
systat: I/O
T
TC-MARGIN [ms]: ms Document Control Settings
U
urx: Miscellaneous
ury: Miscellaneous
V
VS [ms]: ms Document Control Settings
Y
year: Built-in Registers
yr: Built-in Registers
+
Jump to:   $ +   +% +   +. +   +
+C +   +D +   +F +   +G +   +H +   +L +   +M +   +N +   +O +   +P +   +Q +   +R +   +S +   +T +   +U +   +V +   +Y +   +
+
+ + + + +
+
+
+

+Next: Macro Index, Previous: Operator Index, Up: GNU troff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Registers.html b/doc/groff.html.node/Registers.html new file mode 100644 index 0000000..6f33d51 --- /dev/null +++ b/doc/groff.html.node/Registers.html @@ -0,0 +1,65 @@ + + + + + + +Registers (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.8 Registers

+ + +

In the roff language, numbers can be stored in registers. +Many built-in registers exist, supplying anything from the date to +details of formatting parameters. You can also define your own. +See Identifiers, for information on constructing a valid name for a +register. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/Request-Index.html b/doc/groff.html.node/Request-Index.html new file mode 100644 index 0000000..dc328f2 --- /dev/null +++ b/doc/groff.html.node/Request-Index.html @@ -0,0 +1,394 @@ + + + + + + +Request Index (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

Appendix B Request Index

+ +

Request names appear without a leading control character; the defaults +are . for the regular control character and ' for the +no-break control character. +

+
+
Jump to:   A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +K +   +L +   +M +   +N +   +O +   +P +   +R +   +S +   +T +   +U +   +V +   +W +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
A
ab: Debugging
ad: Manipulating Filling and Adjustment
af: Assigning Register Formats
aln: Setting Registers
als: Strings
am: Writing Macros
am1: Writing Macros
ami: Writing Macros
ami1: Writing Macros
as: Strings
as1: Strings
asciify: Diversions
B
backtrace: Debugging
bd: Artificial Fonts
blm: Blank Line Traps
box: Diversions
boxa: Diversions
bp: Page Control
br: Manipulating Filling and Adjustment
break: while
brp: Manipulating Filling and Adjustment
C
c2: Control Characters
cc: Control Characters
ce: Manipulating Filling and Adjustment
cf: I/O
cflags: Using Symbols
ch: Page Location Traps
char: Using Symbols
chop: Strings
class: Character Classes
close: I/O
color: Colors
composite: Using Symbols
continue: while
cp: Compatibility Mode
cs: Artificial Fonts
cu: Artificial Fonts
D
da: Diversions
de: Writing Macros
de1: Writing Macros
defcolor: Colors
dei: Writing Macros
dei1: Writing Macros
device: Postprocessor Access
devicem: Postprocessor Access
di: Diversions
do: Compatibility Mode
ds: ms Document Control Settings
ds: Strings
ds1: Strings
dt: Diversion Traps
E
ec: Using Escape Sequences
ecr: Using Escape Sequences
ecs: Using Escape Sequences
el: if-else
em: End-of-input Traps
eo: Using Escape Sequences
ev: Environments
evc: Environments
ex: Debugging
F
fam: Font Families
fc: Fields
fchar: Using Symbols
fcolor: Colors
fi: Manipulating Filling and Adjustment
fl: Debugging
fp: Font Positions
fschar: Using Symbols
fspecial: Special Fonts
ft: Selecting Fonts
ftr: Selecting Fonts
fzoom: Selecting Fonts
G
gcolor: Colors
H
hc: Manipulating Hyphenation
hcode: Manipulating Hyphenation
hla: Manipulating Hyphenation
hlm: Manipulating Hyphenation
hpf: Manipulating Hyphenation
hpfa: Manipulating Hyphenation
hpfcode: Manipulating Hyphenation
hw: Manipulating Hyphenation
hy: Manipulating Hyphenation
hym: Manipulating Hyphenation
hys: Manipulating Hyphenation
I
ie: if-else
if: if-then
ig: Comments
in: Line Layout
it: Input Line Traps
itc: Input Line Traps
K
kern: Ligatures and Kerning
L
lc: Leaders
length: Strings
lf: Debugging
lg: Ligatures and Kerning
linetabs: Tabs and Fields
ll: Line Layout
ls: Manipulating Spacing
lsm: Leading Space Traps
lt: Page Layout
M
mc: Miscellaneous
mk: Page Motions
mso: I/O
msoquiet: I/O
N
na: Manipulating Filling and Adjustment
ne: Page Control
nf: Manipulating Filling and Adjustment
nh: Manipulating Hyphenation
nm: Miscellaneous
nn: Miscellaneous
nop: if-then
nr: ms Document Control Settings
nr: Setting Registers
nr: Setting Registers
nr: Auto-increment
nroff: troff and nroff Modes
ns: Manipulating Spacing
nx: I/O
O
open: I/O
opena: I/O
os: Page Control
output: Diversions
P
pc: Page Layout
pev: Debugging
pi: I/O
pl: Page Layout
pm: Debugging
pn: Page Layout
pnr: Debugging
po: Line Layout
ps: Changing the Type Size
psbb: Miscellaneous
pso: I/O
ptr: Debugging
pvs: Changing the Vertical Spacing
R
rchar: Using Symbols
rd: I/O
return: Writing Macros
rfschar: Using Symbols
rj: Manipulating Filling and Adjustment
rm: Strings
rn: Strings
rnn: Setting Registers
rr: Setting Registers
rs: Manipulating Spacing
rt: Page Motions
S
schar: Using Symbols
shc: Manipulating Hyphenation
shift: Parameters
sizes: Changing the Type Size
so: I/O
soquiet: I/O
sp: Manipulating Spacing
special: Special Fonts
spreadwarn: Debugging
ss: Manipulating Filling and Adjustment
stringdown: Strings
stringup: Strings
sty: Font Families
substring: Strings
sv: Page Control
sy: I/O
T
ta: Tabs and Fields
tag: Postprocessor Access
taga: Postprocessor Access
tc: Tabs and Fields
ti: Line Layout
tkf: Ligatures and Kerning
tl: Page Layout
tm: Debugging
tm1: Debugging
tmc: Debugging
tr: Character Translations
trf: I/O
trin: Character Translations
trnt: Character Translations
troff: troff and nroff Modes
U
uf: Artificial Fonts
ul: Artificial Fonts
unformat: Diversions
V
vpt: Vertical Position Traps
vs: Changing the Vertical Spacing
W
warn: Debugging
warnscale: Debugging
wh: Page Location Traps
while: while
write: I/O
writec: I/O
writem: I/O
+
Jump to:   A +   +B +   +C +   +D +   +E +   +F +   +G +   +H +   +I +   +K +   +L +   +M +   +N +   +O +   +P +   +R +   +S +   +T +   +U +   +V +   +W +   +
+
+ + + + +
+
+
+

+Next: Escape Sequence Index, Previous: Copying This Manual, Up: GNU troff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Requests-and-Macros.html b/doc/groff.html.node/Requests-and-Macros.html new file mode 100644 index 0000000..8a009b3 --- /dev/null +++ b/doc/groff.html.node/Requests-and-Macros.html @@ -0,0 +1,221 @@ + + + + + + +Requests and Macros (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+
+

5.1.7 Requests and Macros

+ +

We have now encountered almost all of the syntax there is in the +roff language, with an exception already noted in passing. + + + + + + +A request is an instruction to the formatter that occurs after a +control character, which is recognized at the beginning of an +input line. The regular control character is a dot (.). Its +counterpart, the no-break control character, a neutral apostrophe +('), suppresses the break that is implied by some requests. +These characters were chosen because it is uncommon for lines of text in +natural languages to begin with them. + + +If you require a formatted period or apostrophe (closing single +quotation mark) where GNU troff is expecting a control character, +prefix the dot or neutral apostrophe with the dummy character escape +sequence, ‘\&’. +

+ +

An input line beginning with a control character is called a +control line. + +Every line of input that is not a control line is a text +line.25 +

+ +

Requests often take arguments, words (separated from the request +name and each other by spaces) that specify details of the action GNU +troff is expected to perform. If a request is meaningless +without arguments, it is typically ignored. +

+

GNU troff’s requests and escape sequences comprise the control +language of the formatter. Of key importance are the requests that +define macros. Macros are invoked like requests, enabling the request +repertoire to be extended or overridden.26 +

+ + + +

A macro can be thought of as an abbreviation you can define for a +collection of control and text lines. When the macro is called by +giving its name after a control character, it is replaced with what it +stands for. The process of textual replacement is known as +interpolation.27 Interpolations are handled as soon as they are +recognized, and once performed, a roff formatter scans the +replacement for further requests, macro calls, and escape sequences. +

+

In roff systems, the de request defines a +macro.28 +

+
+
.de DATE
+2020-11-14
+..
+
+ +

The foregoing input produces no output by itself; all we have done is +store some information. Observe the pair of dots that ends the macro +definition. This is a default; you can specify your own terminator for +the macro definition as the second argument to the de request. +

+
+
.de NAME ENDNAME
+Heywood Jabuzzoff
+.ENDNAME
+
+ +

In fact, the ending marker is itself the name of a macro to be +called, or a request to be invoked, if it is defined at the time its +control line is read. +

+
+
.de END
+Big Rip
+..
+.de START END
+Big Bang
+.END
+.START
+    ⇒ Big Rip Big Bang
+
+ +

In the foregoing example, “Big Rip” printed before “Big Bang” +because its macro was called first. Consider what would happen +if we dropped END from the ‘.de START’ line and added +.. after .END. Would the order change? +

+

Let us consider a more elaborate example. +

+
+
.de DATE
+2020-10-05
+..
+.
+.de BOSS
+D.\& Kruger,
+J.\& Peterman
+..
+.
+.de NOTICE
+Approved:
+.DATE
+by
+.BOSS
+..
+.
+Insert tedious regulatory compliance paragraph here.
+
+.NOTICE
+
+Insert tedious liability disclaimer paragraph here.
+
+.NOTICE
+    ⇒ Insert tedious regulatory compliance paragraph here.
+    ⇒
+    ⇒ Approved: 2020-10-05 by D. Kruger, J. Peterman
+    ⇒
+    ⇒ Insert tedious liability disclaimer paragraph here.
+    ⇒
+    ⇒ Approved: 2020-10-05 by D. Kruger, J. Peterman
+
+ +

The above document started with a series of control lines. Three macros +were defined, with a de request declaring each macro’s name, and +the “body” of the macro starting on the next line and continuing until +a line with two dots ‘..’ marked its end. The text proper +began only after the macros were defined; this is a common pattern. +Only the NOTICE macro was called “directly” by the document; +DATE and BOSS were called only by NOTICE itself. +Escape sequences were used in BOSS, two levels of macro +interpolation deep. +

+

The advantage in typing and maintenance economy may not be obvious from +such a short example, but imagine a much longer document with dozens of +such paragraphs, each requiring a notice of managerial approval. +Consider what must happen if you are in charge of generating a new +version of such a document with a different date, for a different boss. +With well-chosen macros, you only have to change each datum in one +place. +

+

In practice, we would probably use strings (see Strings) instead of +macros for such simple interpolations; what is important here is to +glimpse the potential of macros and the power of recursive +interpolation. +

+

We could have defined DATE and BOSS in the opposite order; +perhaps less obviously, we could also have defined them after +NOTICE. “Forward references” like this are acceptable because +the body of a macro definition is not (completely) interpreted, but +stored instead (see Copy Mode). While a macro is being defined (or +appended to), requests are not interpreted and macros not interpolated, +whereas some commonly used escape sequences are interpreted. +roff systems also support recursive macro calls, as long as you +have a way to break the recursion (see Conditionals and Loops). +Maintainable roff documents tend to arrange macro definitions to +minimize forward references. +

+ +
+
+
+

+Next: Macro Packages, Previous: Tabs and Leaders, Up: Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Safer-Mode.html b/doc/groff.html.node/Safer-Mode.html new file mode 100644 index 0000000..eca3efd --- /dev/null +++ b/doc/groff.html.node/Safer-Mode.html @@ -0,0 +1,61 @@ + + + + + + +Safer Mode (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Implementation Differences   [Contents][Index]

+
+
+

5.38.1 Safer Mode

+ + + + + +

The formatter operates in “safer” mode by default; to mitigate risks +from untrusted input documents, the pi and sy requests are +disabled. GNU troff’s -U option enables “unsafe +mode”, restoring their function and enabling additional groff +extension requests, open, opena, and pso. +See I/O. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Sections-and-Chapters.html b/doc/groff.html.node/Sections-and-Chapters.html new file mode 100644 index 0000000..b94de73 --- /dev/null +++ b/doc/groff.html.node/Sections-and-Chapters.html @@ -0,0 +1,56 @@ + + + + + + +Sections and Chapters (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.2 Sections and Chapters

+ +

The simplest kind of section heading is unnumbered, set in a bold or +italic style, and occupies a line by itself. Others possess +automatically numbered multi-level headings and/or different typeface +styles or sizes at different levels. More sophisticated macro packages +supply macros for designating chapters and appendices. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Selecting-Fonts.html b/doc/groff.html.node/Selecting-Fonts.html new file mode 100644 index 0000000..d6a59e7 --- /dev/null +++ b/doc/groff.html.node/Selecting-Fonts.html @@ -0,0 +1,227 @@ + + + + + + +Selecting Fonts (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+
+

5.19.1 Selecting Fonts

+ + +

We use font to refer to any of several means of identifying a +font: by mounting position (‘3’), by abstract style (‘B’), or +by its identifier (‘TB’). +

+
+
Request: .ft [font]
+
+
Escape sequence: \ff
+
+
Escape sequence: \f(fn
+
Escape sequence: \f[font]
+
Register: \n[.fn]
+
+ + + + + + + + + + + +

The ft request selects the typeface font. If the argument +is absent or ‘P’, it selects the previously chosen font. If +font is a non-negative integer, it is interpreted as mounting +position; the font mounted there is selected. If that position refers +to an abstract style, it is combined with the default family (see +fam and \F below) to make a resolved font name. If the +mounting position is not a style and no font is mounted there, GNU +troff emits a warning in category ‘font’ and ignores the +request. +

+

If font matches a style name, it is combined with the current +family to make a resolved font name. Otherwise, font is assumed +to already be a resolved font name. +

+ + + +

The resolved font name is subject to translation (see request ftr +below). Next, the (possibly translated) font name’s mounting position +is looked up; if not mounted, font is sought on the file system as +a font description file and, if located, automatically mounted at the +next available position (see register .fp below). If the font +was mounted using an identifier different from its font description file +name (see request fp below), that file name is then looked up. +If a font description file for the resolved font name is not found, GNU +troff emits a warning in category ‘font’ and ignores the +request. +

+

The \f escape sequence is similar, using one-character name (or +mounting position) f, two-character name fn, or a name +font of arbitrary length. + + +‘\f[]’ selects the previous font. The syntax form ‘\fP’ is +supported for backward compatibility, and ‘\f[P]’ for consistency. +

+
+
eggs, bacon,
+.ft I
+spam,
+.ft
+and sausage.
+.br
+eggs, bacon, \fIspam,\fP and sausage.
+    ⇒ eggs, bacon, spam, and sausage
+    ⇒ eggs, bacon, spam, and sausage
+
+ +

The current and previously selected fonts are properties of the +environment (see Environments). +

+

The read-only string-valued register .fn contains the resolved +font name of the selected font. +

+

\f doesn’t produce an input token in GNU troff; it thus +can be used in requests that expect a single-character argument. We can +assign a font to a margin character as follows (see Miscellaneous). +

+
+
.mc \f[I]x\f[]
+
+
+ +
+
Request: .ftr f [g]
+
+ + + + + + + + + + + + + + +

Translate font f to font g. Whenever a font +named f is referred to in a \f escape sequence, in the +F and S conditional operators, or in the ft, +ul, bd, cs, tkf, special, +fspecial, fp, or sty requests, font g is +used. If g is missing or equal to f the translation is +undone. +

+

Font translations cannot be chained. +

+
+
.ftr XXX TR
+.ftr XXX YYY
+.ft XXX
+    error→ warning: can't find font 'XXX'
+
+
+ +
+
Request: .fzoom f [zoom]
+
+
Register: \n[.zoom]
+
+ + + + + + + + +

Set magnification of font f to factor zoom, which must +be a non-negative integer multiple of 1/1000th. This request is useful +to adjust the optical size of a font in relation to the others. In the +example below, font CR is magnified by 10% (the zoom factor is +thus 1.1). +

+
+
.fam P
+.fzoom CR 1100
+.ps 12
+Palatino and \f[CR]Courier\f[]
+
+ +

A missing or zero value of zoom is the same as a value of 1000, +which means no magnification. f must be a resolved font +name, not an abstract style. +

+

The magnification of a font is completely transparent to GNU +troff; a change of the zoom factor doesn’t cause any effect +except that the dimensions of glyphs, (word) spaces, kerns, etc., of the +affected font are adjusted accordingly. +

+

The zoom factor of the current font is available in the read-only +register ‘.zoom’, in multiples of 1/1000th. It returns zero if +there is no magnification. +

+ + +
+
+
+

+Next: Font Families, Previous: Using Fonts, Up: Using Fonts   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Sentences.html b/doc/groff.html.node/Sentences.html new file mode 100644 index 0000000..47d7462 --- /dev/null +++ b/doc/groff.html.node/Sentences.html @@ -0,0 +1,174 @@ + + + + + + +Sentences (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+
+

5.1.2 Sentences

+ + +

A passionate debate has raged for decades among writers of the English +language over whether more space should appear between adjacent +sentences than between words within a sentence, and if so, how much, and +what other circumstances should influence this spacing.20 +GNU troff follows the example of AT&T troff; +it attempts to detect the boundaries between sentences, and supplies +additional inter-sentence space between them. +

+
+
Hello, world!
+Welcome to groff.
+    ⇒ Hello, world!  Welcome to groff.
+
+ + + + + +

GNU troff flags certain characters (normally ‘!’, ‘?’, +and ‘.’) as potentially ending a sentence. When GNU troff +encounters one of these end-of-sentence characters at the end of +an input line, or one of them is followed by two (unescaped) spaces on +the same input line, it appends an inter-word space followed by an +inter-sentence space in the output. +

+
+
R. Harper subscribes to a maxim of P. T. Barnum.
+    ⇒ R. Harper subscribes to a maxim of P. T. Barnum.
+
+ +

In the above example, inter-sentence space is not added after ‘P.’ +or ‘T.’ because the periods do not occur at the end of an input +line, nor are they followed by two or more spaces. Let’s imagine that +we’ve heard something about defamation from Mr. Harper’s attorney, +recast the sentence, and reflowed it in our text editor. +

+
+
I submit that R. Harper subscribes to a maxim of P. T.
+Barnum.
+    ⇒ I submit that R. Harper subscribes to a maxim of
+    ⇒ P. T.  Barnum.
+
+ +

“Barnum” doesn’t begin a sentence! What to do? Let us meet our first +escape sequence, a series of input characters that give +instructions to GNU troff instead of being used to construct +output device glyphs.21 An escape sequence begins with the backslash character \ +by default, an uncommon character in natural language text, and is +always followed by at least one other character, hence the term +“sequence”. +

+ +

The dummy character escape sequence \& can be used after an +end-of-sentence character to defeat end-of-sentence detection on a +per-instance basis. We can therefore rewrite our input more +defensively. +

+
+
I submit that R.\& Harper subscribes to a maxim of P.\&
+T.\& Barnum.
+    ⇒ I submit that R. Harper subscribes to a maxim of
+    ⇒ P. T. Barnum.
+
+ +

Adding text caused our input to wrap; now, we don’t need \& after +‘T.’ but we do after ‘P.’. Consistent use of the escape +sequence ensures that potential sentence boundaries are robust to +editing activities. Further advice along these lines will follow in +Input Conventions. +

+ + + + + + + + + + + + + +

Normally, the occurrence of a visible non-end-of-sentence character (as +opposed to a space or tab) immediately after an end-of-sentence +character cancels detection of the end of a sentence. For example, it +would be incorrect for GNU troff to infer the end of a sentence +after the dot in ‘3.14159’. However, several characters are +treated transparently after the occurrence of an end-of-sentence +character. That is, GNU troff does not cancel end-of-sentence +detection when it processes them. This is because such characters are +often used as footnote markers or to close quotations and +parentheticals. The default set is ‘"’, ‘'’, ‘)’, +‘]’, ‘*’, \[dg], \[dd], \[rq], and +\[cq]. The last four are examples of special characters, +escape sequences whose purpose is to obtain glyphs that are not easily +typed at the keyboard, or which have special meaning to GNU troff +(like \ itself).22 +

+
+
\[lq]The idea that the poor should have leisure has always
+been shocking to the rich.\[rq]
+(Bertrand Russell, 1935)
+    ⇒ "The idea that the poor should have
+    ⇒ leisure has always been shocking to
+    ⇒ the rich."  (Bertrand Russell, 1935)
+
+ +

The sets of characters that potentially end sentences or are transparent +to sentence endings are configurable. See the cflags request in +Using Symbols. To change the additional inter-sentence space +amount—even to remove it entirely—see Manipulating Filling and Adjustment. +

+ +
+
+
+

+Next: Hyphenation, Previous: Filling, Up: Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Separation.html b/doc/groff.html.node/Separation.html new file mode 100644 index 0000000..d7dfe3e --- /dev/null +++ b/doc/groff.html.node/Separation.html @@ -0,0 +1,94 @@ + + + + + + +Separation (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Language Concepts   [Contents][Index]

+
+
+

6.1.1.1 Separation

+ +

AT&T troff output has strange requirements regarding +whitespace. The gtroff output parser, however, is more tolerant, +making whitespace maximally optional. Such characters, i.e., the tab, +space, and newline, always have a syntactical meaning. They are never +printable because spacing within the output is always done by +positioning commands. +

+

Any sequence of space or tab characters is treated as a single +syntactical space. It separates commands and arguments, but is +only required when there would occur a clashing between the command code +and the arguments without the space. Most often, this happens when +variable-length command names, arguments, argument lists, or command +clusters meet. Commands and arguments with a known, fixed length need +not be separated by syntactical space. +

+

A line break is a syntactical element, too. Every command argument can +be followed by whitespace, a comment, or a newline character. Thus a +syntactical line break is defined to consist of optional +syntactical space that is optionally followed by a comment, and a +newline character. +

+

The normal commands, those for positioning and text, consist of a single +letter taking a fixed number of arguments. For historical reasons, the +parser allows stacking of such commands on the same line, but +fortunately, in gtroff’s intermediate output, every command with +at least one argument is followed by a line break, thus providing +excellent readability. +

+

The other commands—those for drawing and device controlling—have a +more complicated structure; some recognize long command names, and some +take a variable number of arguments. So all ‘D’ and ‘x’ +commands were designed to request a syntactical line break after their +last argument. Only one command, ‘x X’, has an argument that +can span several input lines; all other commands must have all of +their arguments on the same line as the command, i.e., the arguments may +not be split by a line break. +

+

Empty lines (these are lines containing only space and/or a comment), +can occur everywhere. They are just ignored. +

+
+
+
+

+Next: Argument Units, Previous: Language Concepts, Up: Language Concepts   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Setting-Registers.html b/doc/groff.html.node/Setting-Registers.html new file mode 100644 index 0000000..6fdf746 --- /dev/null +++ b/doc/groff.html.node/Setting-Registers.html @@ -0,0 +1,215 @@ + + + + + + +Setting Registers (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Registers   [Contents][Index]

+
+
+

5.8.1 Setting Registers

+ + + +

Define registers and update their values with the nr request or +the \R escape sequence. +

+
+
Request: .nr ident value
+
+
Escape sequence: \R'ident value'
+
+

Set register ident to value. If ident doesn’t exist, +GNU troff creates it. In the \R escape sequence, the +delimiter need not be a neutral apostrophe; see Delimiters. It +also does not produce an input token in GNU troff. See gtroff Internals. +

+
+
.nr a (((17 + (3 * 4))) % 4)
+\n[a]
+.\R'a (((17 + (3 * 4))) % 4)'
+\n[a]
+    ⇒ 1 1
+
+ +

(Later, we will discuss additional forms of nr and \R that +can change a register’s value after it is dereferenced but before it is +interpolated. See Auto-increment.) +

+

The complete transparency of \R can cause surprising effects if +you use registers like .k, which get evaluated at the time they +are accessed. +

+
+
.ll 1.6i
+.
+aaa bbb ccc ddd eee fff ggg hhh\R':k \n[.k]'
+.tm :k == \n[:k]
+    ⇒ :k == 126950
+.
+.br
+.
+aaa bbb ccc ddd eee fff ggg hhh\h'0'\R':k \n[.k]'
+.tm :k == \n[:k]
+    ⇒ :k == 15000
+
+ +

If you process this with the PostScript device (-Tps), there will +be a line break eventually after ggg in both input lines. +However, after processing the space after ggg, the partially +collected line is not overfull yet, so GNU troff continues to +collect input until it sees the space (or in this case, the newline) +after hhh. At this point, the line is longer than the line +length, and the line gets broken. +

+

In the first input line, since the \R escape sequence leaves no +traces, the check for the overfull line hasn’t been done yet at the +point where \R gets handled, and you get a value for the +.k register that is even greater than the current line length. +

+

In the second input line, the insertion of \h'0' to cause a +zero-width motion forces GNU troff to check the line length, +which in turn causes the start of a new output line. Now .k +returns the expected value. +

+ +

nr and \R each have two additional special forms to +increment or decrement a register. +

+
+
Request: .nr ident +value
+
+
Request: .nr ident -value
+
Escape sequence: \R'ident +value'
+
+
Escape sequence: \R'ident -value'
+

Increment (decrement) register ident by value. In the +\R escape sequence, the delimiter need not be a neutral +apostrophe; see Delimiters. +

+
+
.nr a 1
+.nr a +1
+\na
+    ⇒ 2
+
+ + +

A leading minus sign in value is always interpreted as a +decrementation operator, not an algebraic sign. To assign a register a +negative value or the negated value of another register, you can +force GNU troff to interpret ‘-’ as a negation or minus, +rather than decrementation, operator: enclose it with its operand in +parentheses or subtract it from zero. +

+
+
.nr a 7
+.nr b 3
+.nr a -\nb
+\na
+    ⇒ 4
+.nr a (-\nb)
+\na
+    ⇒ -3
+.nr a 0-\nb
+\na
+    ⇒ -3
+
+ +

If a register’s prior value does not exist (the register was undefined), +an increment or decrement is applied as if to 0. +

+ +
+
Request: .rr ident
+
+ + +

Remove register ident. If ident doesn’t exist, the request +is ignored. Technically, only the name is removed; the register’s +contents are still accessible under aliases created with aln, if +any. +

+ +
+
Request: .rnn ident1 ident2
+
+ + +

Rename register ident1 to ident2. If ident1 doesn’t +exist, the request is ignored. Renaming a built-in register does not +otherwise alter its properties. +

+ +
+
Request: .aln new old
+
+ + + +

Create an alias new for an existing register old, causing +the names to refer to the same stored object. If old is +undefined, a warning in category ‘reg’ is produced and the request +is ignored. See Warnings, for information about the enablement and +suppression of warnings. +

+ + + +

To remove a register alias, invoke rr on its name. A register’s +contents do not become inaccessible until it has no more names. +

+ + +
+
+
+

+Next: Interpolating Registers, Previous: Registers, Up: Registers   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Simple-Commands.html b/doc/groff.html.node/Simple-Commands.html new file mode 100644 index 0000000..b76b0a6 --- /dev/null +++ b/doc/groff.html.node/Simple-Commands.html @@ -0,0 +1,207 @@ + + + + + + +Simple Commands (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Command Reference   [Contents][Index]

+
+
+

6.1.2.2 Simple Commands

+ +

The commands in this subsection have a command code consisting of a +single character, taking a fixed number of arguments. Most of them are +commands for positioning and text writing. These commands are tolerant +of whitespace. Optionally, syntactical space can be inserted before, +after, and between the command letter and its arguments. All of these +commands are stackable; i.e., they can be preceded by other simple +commands or followed by arbitrary other commands on the same line. A +separating syntactical space is necessary only when two integer +arguments would clash or if the preceding argument ends with a string +argument. +

+
+
C id‹whitespace›
+

Typeset the glyph of the special character id. Trailing +syntactical space is necessary to allow special character names of +arbitrary length. The drawing position is not advanced. +

+
+
c g
+

Typeset the glyph of the ordinary character c. The drawing +position is not advanced. +

+
+
f n
+

Select the font mounted at position n. n cannot +be negative. +

+
+
H n
+

Horizontally move the drawing position to n basic units from +the left edge of the page. n cannot be negative. +

+
+
h n
+

Move the drawing position right n basic units. AT&T +troff allowed negative n; GNU troff does not produce +such values, but groff’s output driver library handles them. +

+
+
m color-scheme [component …]
+

Select the stroke color using the components in the color space +scheme. Each component is an integer between 0 and 65535. +The quantity of components and their meanings vary with each +scheme. This command is a groff extension. +

+
+
mc cyan magenta yellow
+

Use the CMY color scheme with components cyan, magenta, and yellow. +

+
+
md
+

Use the default color (no components; black in most cases). +

+
+
mg gray
+

Use a grayscale color scheme with a component ranging between 0 (black) +and 65535 (white). +

+
+
mk cyan magenta yellow black
+

Use the CMYK color scheme with components cyan, magenta, yellow, and +black. +

+
+
mr red green blue
+

Use the RGB color scheme with components red, green, and blue. +

+
+ +
+
N n
+

Typeset the glyph with index n in the current font. +n is normally a non-negative integer. The drawing position +is not advanced. The html and xhtml devices use this +command with negative n to produce unbreakable space; the +absolute value of n is taken and interpreted in basic units. +

+
+
n b a
+

Indicate a break. No action is performed; the command is present to +make the output more easily parsed. The integers b +and a describe the vertical space amounts before and after +the break, respectively. GNU troff issues this command but +groff’s output driver library ignores it. See v and +V below. +

+
+
p n
+

Begin a new page, setting its number to n. Each page is +independent, even from those using the same number. The vertical +drawing position is set to 0. All positioning, writing, and +drawing commands are interpreted in the context of a page, so a +p command must precede them. +

+
+
s n
+

Set type size to n scaled points (unit z in GNU +troff. +AT&T troff used unscaled points p instead; +see Output Language Compatibility. +

+
+
t xyz‹whitespace›
+
t xyz dummy-arg‹whitespace›
+

Typeset a word xyz; that is, set a sequence of ordinary glyphs +named x, y, z, …, terminated by a space +character or a line break; an optional second integer argument is +ignored (this allows the formatter to generate an even number of +arguments). Each glyph is set at the current drawing position, and the position is +then advanced horizontally by the glyph’s width. A glyph’s width is +read from its metrics in the font description file, scaled to the +current type size, and rounded to a multiple of the horizontal motion +quantum. Use the C command to emplace glyphs of special +characters. The t command is a groff extension and +is output only for devices whose DESC file contains the +tcommand directive; see DESC File Format. +

+
+
u n xyz‹whitespace›
+

Typeset word xyz with track kerning. As t, but after +placing each glyph, the drawing position is further advanced +horizontally by n basic units (u). The +u command is a groff extension and is output only for +devices whose DESC file contains the tcommand directive; +see DESC File Format. +

+
+
V n
+

Vertically move the drawing position to n basic units from +the top edge of the page. n cannot be negative. +

+
+
v n
+

Move the drawing position down n basic units. AT&T +troff allowed negative n; GNU troff does not produce +such values, but groff’s output driver library handles them. +

+
+
w
+

Indicate an inter-word space. No action is performed; the command is +present to make the output more easily parsed. Only adjustable, +breakable inter-word spaces are thus described; those resulting from +\~ or horizontal motion escape sequences are not. GNU +troff issues this command but groff’s output driver +library ignores it. See h and H above. +

+
+ +
+
+
+

+Next: Graphics Commands, Previous: Comment Command, Up: Command Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Special-Fonts.html b/doc/groff.html.node/Special-Fonts.html new file mode 100644 index 0000000..214c74e --- /dev/null +++ b/doc/groff.html.node/Special-Fonts.html @@ -0,0 +1,93 @@ + + + + + + +Special Fonts (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+
+

5.19.6 Special Fonts

+ + + +

Special fonts are those that gtroff searches when it cannot find +the requested glyph in the current font. The Symbol font is usually a +special font. +

+

gtroff provides the following two requests to add more special +fonts. See Using Symbols, for a detailed description of the glyph +searching mechanism in gtroff. +

+

Usually, only non-TTY devices have special fonts. +

+
+
Request: .special [s1 s2 …]
+
+
Request: .fspecial f [s1 s2 …]
+
+ + +

Use the special request to define special fonts. Initially, this +list is empty. +

+

Use the fspecial request to designate special fonts only when +font f is active. Initially, this list is empty. +

+

Previous calls to special or fspecial are overwritten; +without arguments, the particular list of special fonts is set to empty. +Special fonts are searched in the order they appear as arguments. +

+

All fonts that appear in a call to special or fspecial +are loaded. +

+

See Using Symbols, for the exact search order of glyphs. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/String-Index.html b/doc/groff.html.node/String-Index.html new file mode 100644 index 0000000..335d2b8 --- /dev/null +++ b/doc/groff.html.node/String-Index.html @@ -0,0 +1,344 @@ + + + + + + +String Index (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

Appendix G String Index

+ +

The macro package or program a that defines or uses each string is +appended in brackets. (Only one string, .T, is defined by the +troff formatter itself.) See Strings. +

+ +
+
Jump to:   ! +   +' +   +* +   +, +   +- +   +. +   +/ +   +3 +   +8 +   +: +   +< +   +> +   +? +   +^ +   +_ +   +` +   +{ +   +} +   +~ +   +
+A +   +C +   +D +   +F +   +L +   +M +   +O +   +Q +   +R +   +S +   +T +   +U +   +V +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry  Section
!
! [ms]: ms Legacy Features
'
' [ms]: ms Legacy Features
' [ms]: ms Legacy Features
*
* [ms]: ms Footnotes
,
, [ms]: ms Legacy Features
, [ms]: ms Legacy Features
-
- [ms]: Typographical symbols in ms
.
. [ms]: ms Legacy Features
.T: Strings
.T: Strings
/
/ [ms]: ms Legacy Features
3
3 [ms]: ms Legacy Features
8
8 [ms]: ms Legacy Features
:
: [ms]: ms Legacy Features
: [ms]: ms Legacy Features
<
< [ms]: Typeface and decoration
>
> [ms]: Typeface and decoration
?
? [ms]: ms Legacy Features
^
^ [ms]: ms Legacy Features
^ [ms]: ms Legacy Features
_
_ [ms]: ms Legacy Features
`
` [ms]: ms Legacy Features
` [ms]: ms Legacy Features
{
{ [ms]: Typeface and decoration
}
} [ms]: Typeface and decoration
~
~ [ms]: ms Legacy Features
~ [ms]: ms Legacy Features
A
ABSTRACT [ms]: ms language and localization
ae [ms]: ms Legacy Features
Ae [ms]: ms Legacy Features
C
C [ms]: ms Legacy Features
CF [ms]: ms Document Control Settings
CH [ms]: ms Document Control Settings
D
d- [ms]: ms Legacy Features
D- [ms]: ms Legacy Features
F
FAM [ms]: ms Document Control Settings
FR [ms]: ms Document Control Settings
L
LF [ms]: ms Document Control Settings
LH [ms]: ms Document Control Settings
M
MONTH1 [ms]: ms language and localization
MONTH10 [ms]: ms language and localization
MONTH11 [ms]: ms language and localization
MONTH12 [ms]: ms language and localization
MONTH2 [ms]: ms language and localization
MONTH3 [ms]: ms language and localization
MONTH4 [ms]: ms language and localization
MONTH5 [ms]: ms language and localization
MONTH6 [ms]: ms language and localization
MONTH7 [ms]: ms language and localization
MONTH8 [ms]: ms language and localization
MONTH9 [ms]: ms language and localization
O
o [ms]: ms Legacy Features
oe [ms]: ms Legacy Features
OE [ms]: ms Legacy Features
Q
Q [ms]: Typographical symbols in ms
q [ms]: ms Legacy Features
R
REFERENCES [ms]: ms language and localization
RF [ms]: ms Document Control Settings
RH [ms]: ms Document Control Settings
S
SN [ms]: Headings in ms
SN-DOT [ms]: Headings in ms
SN-NO-DOT [ms]: Headings in ms
SN-STYLE [ms]: ms Document Control Settings
SN-STYLE [ms]: Headings in ms
T
th [ms]: ms Legacy Features
Th [ms]: ms Legacy Features
TOC [ms]: ms language and localization
U
U [ms]: Typographical symbols in ms
V
v [ms]: ms Legacy Features
+
Jump to:   ! +   +' +   +* +   +, +   +- +   +. +   +/ +   +3 +   +8 +   +: +   +< +   +> +   +? +   +^ +   +_ +   +` +   +{ +   +} +   +~ +   +
+A +   +C +   +D +   +F +   +L +   +M +   +O +   +Q +   +R +   +S +   +T +   +U +   +V +   +
+
+ + + + +
+
+
+

+Next: File Keyword Index, Previous: Macro Index, Up: GNU troff   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Strings.html b/doc/groff.html.node/Strings.html new file mode 100644 index 0000000..726e0b0 --- /dev/null +++ b/doc/groff.html.node/Strings.html @@ -0,0 +1,429 @@ + + + + + + +Strings (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.22 Strings

+ + +

GNU troff supports strings primarily for user convenience. +Conventionally, if one would define a macro only to interpolate a small +amount of text, without invoking requests or calling any other macros, +one defines a string instead. Only one string is predefined by the +language. +

+
+
String: \*[.T]
+
+ + +

Contains the name of the output device (for example, ‘utf8’ or +‘pdf’). +

+ +

The ds request creates a string with a specified name and +contents and the \* escape sequence dereferences its name, +interpolating its contents. If the string named by the \* escape +sequence does not exist, it is defined as empty, nothing is +interpolated, and a warning in category ‘mac’ is emitted. +See Warnings, for information about the enablement and suppression of +warnings. +

+
+
Request: .ds name [contents]
+
+
Request: .ds1 name [contents]
+
+
Escape sequence: \*n
+
+
Escape sequence: \*(nm
+
Escape sequence: \*[name [arg1 arg2 …]]
+
+ + + + + +

Define a string called name with contents contents. If +name already exists as an alias, the target of the alias is +redefined; see als and rm below. If ds is called +with only one argument, name is defined as an empty string. +Otherwise, GNU troff stores contents in copy +mode.87 +

+

The \* escape sequence interpolates a previously defined string +variable name (one-character name n, two-character name +nm). The bracketed interpolation form accepts arguments that are +handled as macro arguments are; recall Calling Macros. In +contrast to macro calls, however, if a closing bracket ‘]’ occurs +in a string argument, that argument must be enclosed in double quotes. +\* is interpreted even in copy mode. When defining strings, +argument interpolations must be escaped if they are to reference +parameters from the calling context; See Parameters. +

+
+
.ds cite (\\$1, \\$2)
+Gray codes are explored in \*[cite Morgan 1998].
+    ⇒ Gray codes are explored in (Morgan, 1998).
+
+ + + + + +

Caution: Unlike other requests, the second argument to the +ds request consumes the remainder of the input line, including +trailing spaces. This means that comments on a line with such a request +can introduce unwanted space into a string when they are set off from +the material they annotate, as is conventional. +

+
+
.ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O \" water
+
+ +

Instead, place the comment on another line or put the comment escape +sequence immediately adjacent to the last character of the string. +

+
+
.ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O\" water
+
+ +

Ending string definitions (and appendments) with a comment, even an +empty one, prevents unwanted space from creeping into them during source +document maintenance. +

+
+
.ds author Alice Pleasance Liddell\"
+.ds empty \" might be appended to later with .as
+
+ + + + + + + +

An initial neutral double quote " in contents is stripped +to allow embedding of leading spaces. Any other " is interpreted +literally, but it is wise to use the special character escape sequence +\[dq] instead if the string might be interpolated as part of a +macro argument; see Calling Macros. +

+
+
.ds salutation "         Yours in a white wine sauce,\"
+.ds c-var-defn "  char mydate[]=\[dq]2020-07-29\[dq];\"
+
+ + + + + +

Strings are not limited to a single input line of text. +\RET works just as it does elsewhere. The resulting string +is stored without the newlines. Care is therefore required when +interpolating strings while filling is disabled. +

+
+
.ds foo This string contains \
+text on multiple lines \
+of input.
+
+ +

It is not possible to embed a newline in a string that will be +interpreted as such when the string is interpolated. To achieve that +effect, use \* to interpolate a macro instead; see Punning Names. +

+

Because strings are similar to macros, they too can be defined so as to +suppress AT&T troff compatibility mode when used; see +Writing Macros and Compatibility Mode. The ds1 +request defines a string such that compatibility mode is off when the +string is later interpolated. To be more precise, a compatibility +save input token is inserted at the beginning of the string, and a +compatibility restore input token at the end. +

+
+
.nr xxx 12345
+.ds aa The value of xxx is \\n[xxx].
+.ds1 bb The value of xxx is \\n[xxx].
+.
+.cp 1
+.
+\*(aa
+    error→ warning: register '[' not defined
+    ⇒ The value of xxx is 0xxx].
+\*(bb
+    ⇒ The value of xxx is 12345.
+
+
+ +
+
Request: .as name [contents]
+
+
Request: .as1 name [contents]
+
+ + +

The as request is similar to ds but appends contents +to the string stored as name instead of redefining it. If +name doesn’t exist yet, it is created. If as is called +with only one argument, no operation is performed (beyond dereferencing +the string). +

+
+
.as salutation " with shallots, onions and garlic,\"
+
+ +

The as1 request is similar to as, but compatibility mode +is switched off when the appended portion of the string is later +interpolated. To be more precise, a compatibility save input +token is inserted at the beginning of the appended string, and a +compatibility restore input token at the end. +

+ +

Several requests exist to perform rudimentary string operations. +Strings can be queried (length) and modified (chop, +substring, stringup, stringdown), and their names +can be manipulated through renaming, removal, and aliasing (rn, +rm, als). +

+
+
Request: .length reg anything
+
+ + + + + +

Compute the number of characters of anything and store the count +in the register reg. If reg doesn’t exist, it is created. +anything is read in copy mode. +

+
+
.ds xxx abcd\h'3i'efgh
+.length yyy \*[xxx]
+\n[yyy]
+    ⇒ 14
+
+
+ +
+
Request: .chop object
+
+

Remove the last character from the macro, string, or diversion named +object. This is useful for removing the newline from the end of a +diversion that is to be interpolated as a string. This request can be +used repeatedly on the same object; see gtroff Internals, +for details on nodes inserted additionally by GNU troff. +

+ +
+
Request: .substring str start [end]
+
+ +

Replace the string named str with its substring bounded by the +indices start and end, inclusively. The first character in +the string has index 0. If end is omitted, it is implicitly +set to the largest valid value (the string length minus one). Negative +indices count backward from the end of the string: the last character +has index −1, the character before the last has +index −2, and so on. +

+
+
.ds xxx abcdefgh
+.substring xxx 1 -4
+\*[xxx]
+    ⇒ bcde
+.substring xxx 2
+\*[xxx]
+    ⇒ de
+
+
+ +
+
Request: .stringdown str
+
+
Request: .stringup str
+
+ + + + + +

Alter the string named str by replacing each of its bytes with its +lowercase (stringdown) or uppercase (stringup) version (if +one exists). Special characters in the string will often transform in +the expected way due to the regular naming convention for accented +characters. When they do not, use substrings and/or catenation. +

+
+
.ds resume R\['e]sum\['e]
+\*[resume]
+.stringdown resume
+\*[resume]
+.stringup resume
+\*[resume]
+    ⇒ Résumé résumé RÉSUMÉ
+
+
+ +

(In practice, we would end the ds request with a comment escape +\" to prevent space from creeping into the definition during +source document maintenance.) +

+
+
Request: .rn old new
+
+ + + + + + + + +

Rename the request, macro, diversion, or string old to new. +

+ +
+
Request: .rm name
+
+ + + + + + + + +

Remove the request, macro, diversion, or string name. GNU +troff treats subsequent invocations as if the name had never +been defined. +

+ +
+
Request: .als new old
+
+ + + + + + + + + +

Create an alias new for the existing request, string, macro, or +diversion object named old, causing the names to refer to the same +stored object. If old is undefined, a warning in category +‘mac’ is produced, and the request is ignored. See Warnings, +for information about the enablement and suppression of warnings. +

+

To understand how the als request works, consider two different +storage pools: one for objects (macros, strings, etc.), and another +for names. As soon as an object is defined, GNU troff adds it to +the object pool, adds its name to the name pool, and creates a link +between them. When als creates an alias, it adds a new name to +the name pool that gets linked to the same object as the old name. +

+

Now consider this example. +

+
+
.de foo
+..
+.
+.als bar foo
+.
+.de bar
+.  foo
+..
+.
+.bar
+    error→ input stack limit exceeded (probable infinite
+    error→ loop)
+
+ +

In the above, bar remains an alias—another name +for—the object referred to by foo, which the second de +request replaces. Alternatively, imagine that the de request +dereferences its argument before replacing it. Either way, the +result of calling bar is a recursive loop that finally leads to +an error. See Writing Macros. +

+ + + + + + + + + +

To remove an alias, call rm on its name. The object itself is +not destroyed until it has no more names. +

+

When a request, macro, string, or diversion is aliased, redefinitions +and appendments “write through” alias names. To replace an alias with +a separately defined object, you must use the rm request on its +name first. +

+ + + +
+
+
+

+Next: Conditionals and Loops, Previous: Colors, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Suppressing-Output.html b/doc/groff.html.node/Suppressing-Output.html new file mode 100644 index 0000000..bd32161 --- /dev/null +++ b/doc/groff.html.node/Suppressing-Output.html @@ -0,0 +1,147 @@ + + + + + + +Suppressing Output (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.32 Suppressing Output

+ +
+
Escape sequence: \O[num]
+
+ + +

Suppress GNU troff output of glyphs and geometric objects. The +sequences \O2, \O3, \O4, and \O5 are +intended for internal use by grohtml. +

+
+
‘\O0’
+

Disable the emission of glyphs and geometric objects to the output +driver, provided that this sequence occurs at the outermost suppression +level (see \O3 and \04 below). Horizontal motions +corresponding to non-overstruck glyph widths still occur. +

+
+
‘\O1’
+

Enable the emission of glyphs and geometric objects to the output +driver, provided that this sequence occurs at the outermost suppression +level. +

+
+ + + + + +

\O0 and \O1 also reset the four registers opminx, +opminy, opmaxx, and opmaxy to −1. These +four registers mark the top left and bottom right hand corners of a box +encompassing all written or drawn output. +

+
+
‘\O2’
+

At the outermost suppression level, enable emission of glyphs and +geometric objects, and write to the standard error stream the page +number and values of the four aforementioned registers encompassing +glyphs written since the last interpolation of a \O sequence, as +well as the page offset, line length, image file name (if any), +horizontal and vertical device motion quanta, and input file name. +Numeric values are in basic units. +

+
+
‘\O3’
+

Begin a nested suppression level. grohtml uses this mechanism +to create images of output preprocessed with gpic, +geqn, and gtbl. At startup, GNU troff is at +the outermost suppression level. pre-grohtml generates these +sequences when processing the document, using GNU troff with +the ps output device, Ghostscript, and the PNM tools to produce +images in PNG format. They start a new page if the device is not +html or xhtml, to reduce the number of images crossing a +page boundary. +

+
+
‘\O4’
+

End a nested suppression level. +

+
+ +
+
‘\O[5Pfile]’
+

At the outermost suppression level, write the name file to the +standard error stream at position P, which must be one of +l, r, c, or i, corresponding to left, +right, centered, and inline alignments within the document, +respectively. file is a name associated with the production of +the next image. +

+
+
+ +
+
Register: \n[.O]
+
+ + + +

Output suppression nesting level applied by \O3 and \O4 +escape sequences. +

+ + + +
+
+
+

+Next: Colors, Previous: Environments, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Tab-Stops-in-ms.html b/doc/groff.html.node/Tab-Stops-in-ms.html new file mode 100644 index 0000000..3302ce5 --- /dev/null +++ b/doc/groff.html.node/Tab-Stops-in-ms.html @@ -0,0 +1,67 @@ + + + + + + +Tab Stops in ms (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Page layout   [Contents][Index]

+
+
+

4.6.6.2 Tab stops

+ +

Use the ta request to define tab stops as needed. See Tabs and Fields. +

+
+
Macro: .TA
+
+

Reset the tab stops to the ms default (every 5 ens). +Redefine this macro to create a different set of default tab stops. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Table-of-Contents.html b/doc/groff.html.node/Table-of-Contents.html new file mode 100644 index 0000000..4d169cd --- /dev/null +++ b/doc/groff.html.node/Table-of-Contents.html @@ -0,0 +1,71 @@ + + + + + + +Table of Contents (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Common Features   [Contents][Index]

+
+
+

3.2.7 Table of Contents

+ + + +

A package may handle a table of contents by directing section +heading macros to save section heading text and the page number where it +occurs for use in a later entry for a table of contents. It +writes the collected entries at the end of the document, once all are +known, upon request. A row of dots (a leader) bridges the +text on the left with its location on the right. Other collections +might work in this manner, providing lists of figures or tables. +

+

A table of contents is often found at the end of a GNU troff +document because the formatter processes the document in a single pass. +The gropdf output driver supports a PDF feature that relocates +pages at the time the document is rendered; see the gropdf(1) +man page. Type ‘man gropdf’ at the command line to view it. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Tabs-and-Fields.html b/doc/groff.html.node/Tabs-and-Fields.html new file mode 100644 index 0000000..83c156e --- /dev/null +++ b/doc/groff.html.node/Tabs-and-Fields.html @@ -0,0 +1,276 @@ + + + + + + +Tabs and Fields (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.12 Tabs and Fields

+ + + + +

A tab character (ISO code point 9, EBCDIC +code point 5) causes a horizontal movement to the next tab stop, if +any. +

+
+
Escape sequence: \t
+
+ + + + + +

Interpolate a tab in copy mode; see Copy Mode. +

+ +
+
Request: .ta [[n1 n2 … nn ]T r1 r2 … rn]
+
+
Register: \n[.tabs]
+
+

Change tab stop positions. This request takes a series of tab +specifiers as arguments (optionally divided into two groups with the +letter ‘T’) that indicate where each tab stop is to be, overriding +any previous settings. The default scaling unit is ‘m’. Invoking +ta without an argument removes all tab stops. + + +GNU troff’s startup value is ‘T 0.5i’. +

+

Tab stops can be specified absolutely—as distances from the left +margin. The following example sets six tab stops, one every inch. +

+
+
.ta 1i 2i 3i 4i 5i 6i
+
+ +

Tab stops can also be specified using a leading ‘+’, which means +that the specified tab stop is set relative to the previous tab stop. +For example, the following is equivalent to the previous example. +

+
+
.ta 1i +1i +1i +1i +1i +1i
+
+ +

GNU troff supports an extended syntax to specify repeating tab +stops. These stops appear after a ‘T’ argument. Their values are +always taken as distances relative to the previous tab stop. This is +the idiomatic way to specify tab stops at equal intervals in +groff. The following is, yet again, the same as the previous +examples. It does more, in fact, since it defines an infinite number of +tab stops at one-inch intervals. +

+
+
.ta T 1i
+
+ +

Now we are ready to interpret the full syntax given above. The +ta request sets tabs at positions n1, n2, …, +nn, then at nn+r1, nn+r2, …, +nn+rn, then at nn+rn+r1, +nn+rn+r2, …, nn+rn+rn, and so +on. +

+

For example, ‘4c +6c T 3c 5c 2c’ is equivalent to ‘4c 10c 13c +18c 20c 23c 28c 30c …’. +

+

Text written to a tab column (i.e., between two tab stops, or between a +tab stop and an output line boundary) may be aligned to the right or +left, or centered in the column. This alignment is determined by +appending ‘R’, ‘L’, or ‘C’ to the tab specifier. The +default is ‘L’. +

+
+
.ta 1i 2iC 3iR
+
+ +

The beginning of an output line is not a tab stop; the text that begins +an output line is placed according to the configured alignment and +indentation; see Manipulating Filling and Adjustment and Line Layout. +

+

A tab stop is converted into a non-breakable horizontal movement that +cannot be adjusted. +

+
+
.ll 2i
+.ds foo a\tb\tc
+.ta T 1i
+\*[foo]
+    error→ warning: cannot break line
+    ⇒ a         b         c
+
+ +

The above creates a single output line that is a bit longer than two +inches (we use a string to show exactly where the tab stops are). +Now consider the following. +

+
+
.ll 2i
+.ds bar a\tb c\td
+.ta T 1i
+\*[bar]
+    error→ warning: cannot adjust line
+    ⇒ a         b
+    ⇒ c       d
+
+ +

GNU troff first converts the line’s tab stops into unbreakable +horizontal movements, then breaks after ‘b’. This usually isn’t +what you want. +

+

Superfluous tab characters—those that do not correspond to a tab +stop—are ignored except for the first, which delimits the characters +belonging to the last tab stop for right-alignment or centering. +

+
+
.ds Z   foo\tbar\tbaz
+.ds ZZ  foo\tbar\tbazqux
+.ds ZZZ foo\tbar\tbaz\tqux
+.ta 2i 4iR
+\*[Z]
+.br
+\*[ZZ]
+.br
+\*[ZZZ]
+.br
+    ⇒ foo                 bar              baz
+    ⇒ foo                 bar           bazqux
+    ⇒ foo                 bar              bazqux
+
+ +

The first line right-aligns “baz” within the second tab stop. The +second line right-aligns “bazqux” within it. The third line +right-aligns only “baz” because of the additional tab character, which +marks the end of the text occupying the last tab stop defined. +

+

Tab stops are associated with the environment (see Environments). +

+ + + +

The read-only register .tabs contains a string +representation of the current tab settings suitable for use as an +argument to the ta request.66 +

+
+
.ds tab-string \n[.tabs]
+\*[tab-string]
+    ⇒ T120u
+
+
+ +
+
Request: .tc [c]
+
+ + + +

Set the tab repetition character to the ordinary or special character +c; normally, no glyph is written when moving to a tab stop (and +some output devices may output space characters to achieve this motion). +A tab repetition character causes the formatter to write as many +instances of c as are necessary to occupy the interval from the +horizontal drawing position to the next tab stop. With no argument, GNU +troff reverts to the default behavior. The tab repetition +character is associated with the environment (see Environments). +Only a single character of c is recognized; any excess is ignored. +

+ +
+
Request: .linetabs n
+
+
Register: \n[.linetabs]
+
+ + + +

If n is missing or non-zero, activate line-tabs; deactivate +it otherwise (the default). Active line-tabs cause GNU troff +to compute tab distances relative to the start of the output line +instead of the input line. +

+
+
.de Tabs
+.  ds x a\t\c
+.  ds y b\t\c
+.  ds z c
+.  ta 1i 3i
+\\*x
+\\*y
+\\*z
+..
+.Tabs
+.br
+.linetabs
+.Tabs
+    ⇒ a         b         c
+    ⇒ a         b                   c
+
+ +

Line-tabs activation is associated with the environment +(see Environments). The read-only register .linetabs +interpolates 1 if line-tabs are active, and 0 otherwise. +

+ + + + +
+
+
+

+Next: Character Translations, Previous: Manipulating Spacing, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Tabs-and-Leaders.html b/doc/groff.html.node/Tabs-and-Leaders.html new file mode 100644 index 0000000..c8298a1 --- /dev/null +++ b/doc/groff.html.node/Tabs-and-Leaders.html @@ -0,0 +1,87 @@ + + + + + + +Tabs and Leaders (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Text   [Contents][Index]

+
+
+

5.1.6 Tabs and Leaders

+ + + + + + + + +

GNU troff translates input horizontal tab characters (“tabs”) +and Control+A characters (“leaders”) into movements to the next +tab stop. Tabs simply move to the next tab stop; leaders place enough +periods to fill the space. Tab stops are by default located every half +inch measured from the drawing position corresponding to the beginning +of the input line; see Page Geometry. Tabs and leaders do not +cause breaks and therefore do not interrupt filling. Below, we use +arrows → and bullets • to indicate input tabs and +leaders, respectively. +

+
+
1
+→ 2 → 3 • 4
+→ • 5
+⇒ 1         2       3.......4         ........5
+
+ +

Tabs and leaders lend themselves to table construction.24 The tab and leader glyphs can be +configured, and further facilities for sophisticated table composition +are available; see Tabs and Fields. There are many details to +track when using such low-level features, so most users turn to the +tbl(1) preprocessor to lay out tables. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Text-settings-in-ms.html b/doc/groff.html.node/Text-settings-in-ms.html new file mode 100644 index 0000000..f13be1e --- /dev/null +++ b/doc/groff.html.node/Text-settings-in-ms.html @@ -0,0 +1,76 @@ + + + + + + +Text settings in ms (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+
+

4.6.5.1 Text settings

+ + +

The FAM string, a GNU extension, sets the font family for body +text; the default is ‘T’. The PS and VS registers +set the type size and vertical spacing (distance between text +baselines), respectively. The font family and type size are ignored on +terminal devices. Setting these parameters before the first call of a +heading, paragraphing, or (non-date) document description macro also +applies them to headers, footers, and (for FAM) footnotes. +

+

Which font families are available depends on the output device; as a +convention, T selects a serif family (“Times”), H a +sans-serif family (“Helvetica”), and C a monospaced family +(“Courier”). The man page for the output driver documents its font +repertoire. Consult the groff(1) man page for lists of +available output devices and their drivers. +

+

The hyphenation mode (as used by the hy request) is set from the +HY register. Setting HY to ‘0’ is equivalent to +using the nh request. This is a Tenth Edition Research Unix +extension. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Text.html b/doc/groff.html.node/Text.html new file mode 100644 index 0000000..16a1d83 --- /dev/null +++ b/doc/groff.html.node/Text.html @@ -0,0 +1,81 @@ + + + + + + +Text (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.1 Text

+ + +

AT&T troff was designed to take input as it would be +composed on a typewriter, including the teletypewriters used as early +computer terminals, and relieve the user drafting a document of concern +with details like line length, hyphenation breaking, and the achievement +of straight margins. Early in its development, the program gained the +ability to prepare output for a phototypesetter; a document could then +be prepared for output to either a teletypewriter, a phototypesetter, or +both. GNU troff continues this tradition of permitting an author +to compose a single master version of a document which can then be +rendered for a variety of output formats or devices. +

+

roff input files contain text interspersed with instructions to +control the formatter. Even in the absence of such instructions, GNU +troff still processes its input in several ways, by filling, +hyphenating, breaking, and adjusting it, and supplementing it with +inter-sentence space. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/The-Implicit-Page-Trap.html b/doc/groff.html.node/The-Implicit-Page-Trap.html new file mode 100644 index 0000000..82d1a6b --- /dev/null +++ b/doc/groff.html.node/The-Implicit-Page-Trap.html @@ -0,0 +1,74 @@ + + + + + + +The Implicit Page Trap (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Vertical Position Traps   [Contents][Index]

+
+
+

5.28.1.2 The Implicit Page Trap

+ + + + + + + +

If, after starting GNU troff without loading a macro package, you +use the ptr request to dump a list of the active traps to the +standard error stream,109 nothing is reported. +Yet the .t register will report a steadily decreasing value with +every output line your document produces, and once the value of +.t gets to within .V of zero, you will notice that +something trap-like happens—the page is ejected, a new one begins, and +the value of .t becomes large once more. +

+

This implicit page trap always exists in the top-level +diversion;110 it works like a trap in some +ways but not others. Its purpose is to eject the current page and start +the next one. It has no name, so it cannot be moved or deleted with +wh or ch requests. You cannot hide it by placing another +trap at its location, and can move it only by redefining the page length +with pl. Its operation is suppressed when vertical page traps +are disabled with GNU troff’s vpt request. +

+ +
+ + + + + diff --git a/doc/groff.html.node/Traps.html b/doc/groff.html.node/Traps.html new file mode 100644 index 0000000..3386bdb --- /dev/null +++ b/doc/groff.html.node/Traps.html @@ -0,0 +1,73 @@ + + + + + + +Traps (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.28 Traps

+ + +

Traps are locations in the output or conditions on the input that, +when reached or fulfilled, call a specified macro. These traps can +occur at a given location on the page, at a given location in the +current diversion (together, these are known as vertical +position traps), at a blank line, at a line with leading space +characters, after a quantity of input lines, or at the end of input. +Macros called by traps are passed no arguments. + + +Setting a trap is also called planting one. + + +It is said that a trap is sprung if its condition is fulfilled. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/Tutorial-for-Macro-Users.html b/doc/groff.html.node/Tutorial-for-Macro-Users.html new file mode 100644 index 0000000..3fc9bce --- /dev/null +++ b/doc/groff.html.node/Tutorial-for-Macro-Users.html @@ -0,0 +1,68 @@ + + + + + + +Tutorial for Macro Users (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff   [Contents][Index]

+
+
+

3 Tutorial for Macro Users

+ + + + + +

Most users of the roff language employ a macro package to format +their documents. Successful macro packages ease the composition +process; their users need not have mastered the full formatting +language, nor understand features like diversions, traps, and +environments. This chapter aims to familiarize you with basic concepts +and mechanisms common to many macro packages (like “displays”). If +you prefer a meticulous and comprehensive presentation, try GNU troff Reference instead. +

+ + + + +
+ + + + + diff --git a/doc/groff.html.node/Typeface-and-decoration.html b/doc/groff.html.node/Typeface-and-decoration.html new file mode 100644 index 0000000..759a761 --- /dev/null +++ b/doc/groff.html.node/Typeface-and-decoration.html @@ -0,0 +1,212 @@ + + + + + + +Typeface and decoration (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+
+

4.6.5.5 Typeface and decoration

+ +

The ms macros provide a variety of ways to style text. +Attend closely to the ordering of arguments labeled pre and +post, which is not intuitive. Support for pre +arguments is a GNU extension.10 +

+
+
Macro: .B [text [post [pre]]]
+
+

Style text in bold, followed by post in the previous +font style without intervening space, and preceded by pre +similarly. Without arguments, ms styles subsequent text in bold +until the next paragraphing, heading, or no-argument typeface macro +call. +

+ +
+
Macro: .R [text [post [pre]]]
+
+

As B, but use the roman style (upright text of normal weight) +instead of bold. Argument recognition is a GNU extension. +

+ +
+
Macro: .I [text [post [pre]]]
+
+

As B, but use an italic or oblique style instead of bold. +

+ +
+
Macro: .BI [text [post [pre]]]
+
+

As B, but use a bold italic or bold oblique style instead of +upright bold. This is a Tenth Edition Research Unix extension. +

+ +
+
Macro: .CW [text [post [pre]]]
+
+

As B, but use a constant-width (monospaced) roman typeface +instead of bold. This is a Tenth Edition Research Unix extension. +

+ +
+
Macro: .BX [text]
+
+

Typeset text and draw a box around it. On terminal devices, +reverse video is used instead. If you want text to contain space, +use unbreakable space or horizontal motion escape sequences (\~, +\SP, \^, \|, \0 or \h). +

+ +
+
Macro: .UL [text [post]]
+
+

Typeset text with an underline. post, if present, is set +after text with no intervening space. +

+ +
+
Macro: .LG
+
+

Set subsequent text in larger type (two points larger than the +current size) until the next type size, paragraphing, or heading macro +call. You can specify this macro multiple times to enlarge the type +size as needed. +

+ +
+
Macro: .SM
+
+

Set subsequent text in smaller type (two points smaller than the current +size) until the next type size, paragraphing, or heading macro call. +You can specify this macro multiple times to reduce the type size as +needed. +

+ +
+
Macro: .NL
+
+

Set subsequent text at the normal type size (the amount in the PS +register). +

+ +

pre and post arguments are typically used to simplify the +attachment of punctuation to styled words. When pre is used, +a hyphenation control escape sequence \% that would ordinarily +start text must start pre instead to have the desired +effect. +

+
+
+
The CS course's students found one C language keyword
+.CW static ) \%(
+most troublesome.
+
+
+ +

The foregoing example produces output as follows. +

+
+
+
The CS course’s students found one C language keyword (static)
+most troublesome.
+
+
+ +

You can use the output line continuation escape sequence \c to +achieve the same result (see Line Continuation). It is also +portable to older ms implementations. +

+
+
+
The CS course's students found one C language keyword
+\%(\c
+.CW \%static )
+most troublesome.
+
+
+ +

groff ms also offers strings to begin and end super- and +subscripting. These are GNU extensions. +

+
+
String: \*[{]
+
+
String: \*[}]
+
+

Begin and end superscripting, respectively. +

+ +
+
String: \*[<]
+
+
String: \*[>]
+
+

Begin and end subscripting, respectively. +

+ +

Rather than calling the CW macro, in groff ms you +might prefer to change the font family to Courier by setting the +FAM string to ‘C’. You can then use all four style macros +above, returning to the default family (Times) with ‘.ds FAM T’. +Because changes to FAM take effect only at the next paragraph, +CW remains useful to “inline” a change to the font family, +similarly to the practice of this document in noting syntactical +elements of ms and groff. +

+ +
+
+
+

+Next: Lists, Previous: Headings, Up: Body Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Typographical-symbols-in-ms.html b/doc/groff.html.node/Typographical-symbols-in-ms.html new file mode 100644 index 0000000..3323bcd --- /dev/null +++ b/doc/groff.html.node/Typographical-symbols-in-ms.html @@ -0,0 +1,80 @@ + + + + + + +Typographical symbols in ms (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+
+

4.6.5.2 Typographical symbols

+ + +

ms provides a few strings to obtain typographical symbols not +easily entered with the keyboard. These and many others are available +as special character escape sequences—see the groff_char(7) +man page. +

+
+
String: \*[-]
+
+

Interpolate an em dash. +

+ +
+
String: \*[Q]
+
+
String: \*[U]
+
+

Interpolate typographer’s quotation marks where available, and neutral +double quotes otherwise. \*Q is the left quote and \*U +the right. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Using-Escape-Sequences.html b/doc/groff.html.node/Using-Escape-Sequences.html new file mode 100644 index 0000000..9eabad1 --- /dev/null +++ b/doc/groff.html.node/Using-Escape-Sequences.html @@ -0,0 +1,206 @@ + + + + + + +Using Escape Sequences (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Formatter Instructions   [Contents][Index]

+
+
+

5.6.4 Using Escape Sequences

+ + + +

Whereas requests must occur on control lines, escape sequences can occur +intermixed with text and may appear in arguments to requests, macros, +and other escape sequences. + +An escape sequence is introduced by the escape character, a backslash +\ (but see the ec request below). The next character +selects the escape’s function. +

+

Escape sequences vary in length. Some take an argument, and of those, +some have different syntactical forms for a one-character, +two-character, or arbitrary-length argument. Others accept only +an arbitrary-length argument. In the former scheme, a one-character +argument follows the function character immediately, an opening +parenthesis ‘(’ introduces a two-character argument (no closing +parenthesis is used), and an argument of arbitrary length is enclosed in +brackets ‘[]’. In the latter scheme, the user selects a delimiter +character. A few escape sequences are idiosyncratic, and support both +of the foregoing conventions (\s), designate their own +termination sequence (\?), consume input until the next newline +(\!, \", \#), or support an additional modifier +character (\s again, and \n). As with requests, use of +some escape sequences in source documents may interact poorly with a +macro package you use; consult its documentation to learn of “safe” +sequences or alternative facilities it provides to achieve the desired +result. +

+

If an escape character is followed by a character that does not +identify a defined operation, the escape character is ignored (producing +a diagnostic of the ‘escape’ warning category, which is not enabled +by default) and the following character is processed normally. +

+
+
$ groff -Tps -ww
+.nr N 12
+.ds co white
+.ds animal elephant
+I have \fI\nN \*(co \*[animal]s,\f[]
+said \P.\&\~Pseudo Pachyderm.
+    error→ warning: escape character ignored before 'P'
+    ⇒ I have 12 white elephants, said P. Pseudo Pachyderm.
+
+ +

Escape sequence interpolation is of higher precedence than escape +sequence argument interpretation. This rule affords flexibility in +using escape sequences to construct parameters to other escape +sequences. +

+
+
.ds family C\" Courier
+.ds style I\" oblique
+Choice a typeface \f(\*[family]\*[style]wisely.
+    ⇒ Choose a typeface wisely.
+
+ +

In the above, the syntax form ‘\f(’ accepts only two characters for +an argument; the example works because the subsequent escape sequences +are interpolated before the selection escape sequence argument is +processed, and strings family and style interpolate one +character each.46 +

+

The escape character is nearly always interpreted when encountered; it +is therefore desirable to have a way to interpolate it, disable it, or +change it. +

+ + +
+
Escape sequence: \e
+
+

Interpolate the escape character. +

+ + + +

The \[rs] special character escape sequence formats a backslash +glyph. In macro and string definitions, the input sequences \\ +and \E defer interpretation of escape sequences. See Copy Mode. +

+
+
Request: .eo
+
+ + +

Disable the escape mechanism except in copy mode. Once this request is +invoked, no input character is recognized as starting an escape +sequence in interpretation mode. +

+ +
+
Request: .ec [o]
+
+ + +

Recognize the ordinary character o as the escape character. +If o is absent or invalid, the default escape character +‘\’ is selected. +

+ +

Switching escape sequence interpretation off to define a macro and back +on afterward can obviate the need to double the escape character within +the definition. See Writing Macros. This technique is not available +if your macro needs to interpolate values at the time it is +defined—but many do not. +

+
+
.\" simplified `BR` macro from the man(7) macro package
+.eo
+.de BR
+.  ds result \&
+.  while (\n[.$] >= 2) \{\
+.    as result \fB\$1\fR\$2\"
+.    shift 2
+.  \}
+.  if \n[.$] .as result \fB\$1\"
+\*[result]
+.  rm result
+.  ft R
+..
+.ec
+
+ +
+
Request: .ecs
+
+
Request: .ecr
+
+

The ecs request stores the escape character for recall with +ecr. ecr sets the escape character to ‘\’ if none +has been saved. +

+

Use these requests together to temporarily change the escape character. +

+ +

Using a different escape character, or disabling it, when calling macros +not under your control will likely cause errors, since GNU troff +has no mechanism to “intern” macros—that is, to convert a macro +definition into a form independent of its +representation.47 When a +macro is called, its contents are interpreted literally. +

+ +
+
+
+

+Next: Delimiters, Previous: Calling Macros, Up: Formatter Instructions   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Using-Fonts.html b/doc/groff.html.node/Using-Fonts.html new file mode 100644 index 0000000..81f48e6 --- /dev/null +++ b/doc/groff.html.node/Using-Fonts.html @@ -0,0 +1,148 @@ + + + + + + +Using Fonts (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.19 Using Fonts

+ + + + + + + + + + + + + +

In digital typography, a font is a collection of characters in a +specific typeface that a device can render as glyphs at a desired +size.72 A roff formatter can change typefaces at any +point in the text. The basic faces are a set of styles combining +upright and slanted shapes with normal and heavy stroke weights: +‘R’, ‘I’, ‘B’, and ‘BI’—these stand for +roman, italic, bold, and +bold-italic. For linguistic text, GNU troff groups +typefaces into families containing each of these +styles.73 A text font is thus often a family +combined with a style, but it need not be: consider the ps and +pdf devices’ ZCMI (Zapf Chancery Medium italic)—often, +no other style of Zapf Chancery Medium is provided. On typesetting +devices, at least one special font is available, comprising +unstyled glyphs for mathematical operators and other purposes. +

+ + + + + + + + +

Like AT&T troff, GNU troff does not itself load +or manipulate a digital font file;74 instead it +works with a font description file that characterizes it, +including its glyph repertoire and the metrics (dimensions) of +each glyph.75 This +information permits the formatter to accurately place glyphs with +respect to each other. Before using a font description, the formatter +associates it with a mounting position, a place in an ordered list +of available typefaces. + + + +So that a document need not be strongly coupled to a specific font +family, in GNU troff an output device can associate a style in +the abstract sense with a mounting position. Thus the default family +can be combined with a style dynamically, producing a resolved font +name. +

+

Fonts often have trademarked names, and even Free Software fonts can +require renaming upon modification. groff maintains a +convention that a device’s serif font family is given the name ‘T’ +(“Times”), its sans-serif family ‘H’ (“Helvetica”), and its +monospaced family ‘C’ (“Courier”). Historical inertia has driven +groff’s font identifiers to short uppercase abbreviations of font +names, as with ‘TR’, ‘TI’, ‘TB’, ‘TBI’, and a +special font ‘S’. +

+

The default family used with abstract styles can be changed at any time; +initially, it is ‘T’. Typically, abstract styles are arranged in +the first four mounting positions in the order shown above. The default +mounting position, and therefore style, is always ‘1’ (‘R’). +By issuing appropriate formatter instructions, you can override these +defaults before your document writes its first glyph. +

+ + + + + +

Terminal output devices cannot change font families and lack special +fonts. They support style changes by overstriking, or by altering +ISO 6429/ECMA-48 graphic renditions (character cell +attributes). +

+ + + +
+
+
+

+Next: Manipulating Type Size and Vertical Spacing, Previous: Page Control, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Using-Fractional-Type-Sizes.html b/doc/groff.html.node/Using-Fractional-Type-Sizes.html new file mode 100644 index 0000000..7445fc5 --- /dev/null +++ b/doc/groff.html.node/Using-Fractional-Type-Sizes.html @@ -0,0 +1,172 @@ + + + + + + +Using Fractional Type Sizes (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Manipulating Type Size and Vertical Spacing   [Contents][Index]

+
+
+

5.20.3 Using Fractional Type Sizes

+ + + + + + +

AT&T troff interpreted all type size measurements in points. +Combined with integer arithmetic, this design choice made it impossible +to support, for instance, ten and a half-point type. In GNU +troff, an output device can select a scaling factor that +subdivides a point into “scaled points”. A type size expressed in +scaled points can thus represent a non-integral type size. +

+ + + + + + + + + + + +

A scaled point is equal to 1/sizescale points, where +sizescale is specified in the device description file DESC, +and defaults to 1.85 Requests and escape sequences in GNU troff interpret +arguments that represent a type size in scaled points, which the +formatter multiplies by sizescale and converts to an integer. +Arguments treated in this way comprise those to the escape sequences +\H and \s, to the request ps, the third argument to +the cs request, and the second and fourth arguments to the +tkf request. Scaled points may be specified explicitly with the +z scaling unit. +

+

For example, if sizescale is 1000, then a scaled point is one +thousandth of a point. The request ‘.ps 10.5’ is synonymous with +‘.ps 10.5z’ and sets the type size to 10,500 scaled points, or +10.5 points. Consequently, in GNU troff, the register +.s can interpolate a non-integral type size. +

+
+
Register: \n[.ps]
+
+

This read-only register interpolates the type size in scaled points; it +is associated with the environment (see Environments). +

+ +

It makes no sense to use the ‘z’ scaling unit in a numeric +expression whose default scaling unit is neither ‘u’ nor ‘z’, +so GNU troff disallows this. Similarly, it is nonsensical to use +a scaling unit other than ‘z’ or ‘u’ in a numeric expression +whose default scaling unit is ‘z’, and so GNU troff +disallows this as well. +

+

Another GNU troff scaling unit, ‘s’, multiplies by the +number of basic units in a scaled point. Thus, ‘\n[.ps]s’ is equal +to ‘1m’ by definition. Do not confuse the ‘s’ and ‘z’ +scaling units. +

+
+
Register: \n[.psr]
+
+
Register: \n[.sr]
+
+ + + + + + +

Output devices may be limited in the type sizes they can employ. The +.s and .ps registers represent the type size selected by +the output driver as it understands a device’s capability. The last +requested type size is interpolated in scaled points by the +read-only register .psr and in points as a decimal fraction by +the read-only string-valued register .sr. Both are associated +with the environment (see Environments). +

+

For example, if a type size of 10.95 points is requested, and the +nearest size permitted by a sizes request (or by the sizes +or sizescale directives in the device’s DESC file) is 11 +points, the output driver uses the latter value. +

+ +

The \s escape sequence offers the following syntax forms that +work with fractional type sizes and accept scaling units. You may of +course give them integral arguments. The delimited forms need not use +the neutral apostrophe; see Delimiters. +

+
+
\s[n]
+
\s'n'
+

Set the type size to n scaled points; n is a +numeric expression with a default scaling unit of ‘z’. +

+
+
\s[+n]
+
\s[-n]
+
\s+[n]
+
\s-[n]
+
\s'+n'
+
\s'-n'
+
\s+'n'
+
\s-'n'
+

Increase or decrease the type size by n scaled points; +n is a numeric expression (which may start with a minus sign) +with a default scaling unit of ‘z’. +

+
+ + + +
+
+
+

+Previous: Changing the Type Size, Up: Manipulating Type Size and Vertical Spacing   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Using-Symbols.html b/doc/groff.html.node/Using-Symbols.html new file mode 100644 index 0000000..af4a7cf --- /dev/null +++ b/doc/groff.html.node/Using-Symbols.html @@ -0,0 +1,632 @@ + + + + + + +Using Symbols (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Using Fonts   [Contents][Index]

+
+
+

5.19.4 Using Symbols

+ + + + + + + + +

A glyph is a graphical representation of a character. While +a character is an abstraction of semantic information, a glyph is +something that can be seen on screen or paper. A character has many +possible representation forms (for example, the character ‘A’ can be +written in an upright or slanted typeface, producing distinct +glyphs). Sometimes, a sequence of characters map to a single glyph: +this is a ligature—the most common is ‘fi’. +

+

Space characters never become glyphs in GNU troff. If not +discarded (as when trailing on text lines), they are represented by +horizontal motions in the output. +

+ + + + + + +

A symbol is simply a named glyph. Within gtroff, all glyph +names of a particular font are defined in its font file. If the user +requests a glyph not available in this font, gtroff looks up an +ordered list of special fonts. By default, the PostScript output +device supports the two special fonts ‘SS’ (slanted symbols) and +‘S’ (symbols) (the former is looked up before the latter). Other +output devices use different names for special fonts. Fonts mounted +with the fonts keyword in the DESC file are globally +available. To install additional special fonts locally (i.e., for a +particular font), use the fspecial request. +

+

Here are the exact rules how gtroff searches a given symbol: +

+
    +
  • If the symbol has been defined with the char request, use it. +This hides a symbol with the same name in the current font. + +
  • Check the current font. + +
  • If the symbol has been defined with the fchar request, use it. + +
  • Check whether the current font has a font-specific list of special +fonts; test all fonts in the order of appearance in the last +fspecial call if appropriate. + +
  • If the symbol has been defined with the fschar request for the +current font, use it. + +
  • Check all fonts in the order of appearance in the last special +call. + +
  • If the symbol has been defined with the schar request, use it. + +
  • As a last resort, consult all fonts loaded up to now for special fonts +and check them, starting with the lowest font number. This can +sometimes lead to surprising results since the fonts line in +the DESC file often contains empty positions, which are filled +later on. For example, consider the following: + +
    +
    fonts 3 0 0 FOO
+
    + +

    This mounts font foo at font position 3. We assume that +FOO is a special font, containing glyph foo, and that no +font has been loaded yet. The line +

    +
    +
    .fspecial BAR BAZ
+
    + +

    makes font BAZ special only if font BAR is active. We +further assume that BAZ is really a special font, i.e., the font +description file contains the special keyword, and that it also +contains glyph foo with a special shape fitting to font +BAR. After executing fspecial, font BAR is loaded +at font position 1, and BAZ at position 2. +

    +

    We now switch to a new font XXX, trying to access glyph +foo that is assumed to be missing. There are neither +font-specific special fonts for XXX nor any other fonts made +special with the special request, so gtroff starts the +search for special fonts in the list of already mounted fonts, with +increasing font positions. Consequently, it finds BAZ before +FOO even for XXX, which is not the intended behaviour. +

+ +

See Device and Font Description Files, and Special Fonts, for +more details. +

+ + + + + +

The groff_char(7) man page houses a complete list of +predefined special character names, but the availability of any as a +glyph is device- and font-dependent. For example, say +

+
+
man -Tdvi groff_char > groff_char.dvi
+
+ +

to obtain those available with the DVI device and default font +configuration.77 If you want to use an additional macro package to change +the fonts used, groff (or gtroff) must be run directly. +

+
+
groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
+
+ + + + + + +

Special character names not listed in groff_char(7) are +derived algorithmically, using a simplified version of the Adobe Glyph +List (AGL) algorithm, which is described in +https://github.com/adobe-type-tools/agl-aglfn. The (frozen) +set of names that can’t be derived algorithmically is called the +groff glyph list (GGL). +

+
    +
  • A glyph for Unicode character U+XXXX[X[X]], which is +not a composite character is named +uXXXX[X[X]]. X must be an +uppercase hexadecimal digit. Examples: u1234, u008E, +u12DB8. The largest Unicode value is 0x10FFFF. There must be at +least four X digits; if necessary, add leading zeroes (after the +‘u’). No zero padding is allowed for character codes greater than +0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF +represented with character codes from the surrogate area U+D800-U+DFFF) +are not allowed either. + +
  • A glyph representing more than a single input character is named + +
    +
    ‘u’ component1 ‘_’ component2 ‘_’ component3 …
+
    + +

    Example: u0045_0302_0301. +

    +

    For simplicity, all Unicode characters that are composites must be +maximally decomposed to NFD;78 for example, +u00CA_0301 is not a valid glyph name since U+00CA (LATIN +CAPITAL LETTER E WITH CIRCUMFLEX) can be further decomposed into U+0045 +(LATIN CAPITAL LETTER E) and U+0302 (COMBINING CIRCUMFLEX +ACCENT). u0045_0302_0301 is thus the glyph name for U+1EBE, +LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND ACUTE. +

    +
  • groff maintains a table to decompose all algorithmically derived glyph +names that are composites itself. For example, u0100 (LATIN +LETTER A WITH MACRON) is automatically decomposed into +u0041_0304. Additionally, a glyph name of the GGL is preferred +to an algorithmically derived glyph name; groff also +automatically does the mapping. Example: The glyph u0045_0302 is +mapped to ^E. + +
  • glyph names of the GGL can’t be used in composite glyph names; for +example, ^E_u0301 is invalid. +
+ +
+
Escape sequence: \(nm
+
+
Escape sequence: \[name]
+
Escape sequence: \[base-glyph combining-component …]
+
+ +

Typeset a special character name (two-character name nm) or +a composite glyph consisting of base-glyph overlaid with one or +more combining-components. For example, ‘\[A ho]’ is a +capital letter “A” with a “hook accent” (ogonek). +

+

There is no special syntax for one-character names—the analogous form +‘\n’ would collide with other escape sequences. However, the +four escape sequences \', \-, \_, and \`, +are translated on input to the special character escape sequences +\[aa], \[-], \[ul], and \[ga], respectively. +

+

A special character name of length one is not the same thing as an +ordinary character: that is, the character a is not the same as +\[a]. +

+

If name is undefined, a warning in category ‘char’ is +produced and the escape is ignored. See Warnings, for information +about the enablement and suppression of warnings. +

+

GNU troff resolves \[…] with more than a single +component as follows: +

+
    +
  • Any component that is found in the GGL is converted to the +uXXXX form. + +
  • Any component uXXXX that is found in the list of +decomposable glyphs is decomposed. + +
  • The resulting elements are then concatenated with ‘_’ in between, +dropping the leading ‘u’ in all elements but the first. +
+ +

No check for the existence of any component (similar to tr +request) is done. +

+

Examples: +

+
+
\[A ho]
+

‘A’ maps to u0041, ‘ho’ maps to u02DB, thus the +final glyph name would be u0041_02DB. This is not the expected +result: the ogonek glyph ‘ho’ is a spacing ogonek, but for a +proper composite a non-spacing ogonek (U+0328) is necessary. Looking +into the file composite.tmac, one can find ‘.composite ho u0328’, which changes the mapping of ‘ho’ while a composite glyph +name is constructed, causing the final glyph name to be +u0041_0328. +

+
+
\[^E u0301]
+
\[^E aa]
+
\[E a^ aa]
+
\[E ^ ']
+

‘^E’ maps to u0045_0302, thus the final glyph name is +u0045_0302_0301 in all forms (assuming proper calls of the +composite request). +

+
+ +

It is not possible to define glyphs with names like ‘A ho’ +within a groff font file. This is not really a limitation; +instead, you have to define u0041_0328. +

+ +
+
Escape sequence: \C'xxx'
+
+ + +

Typeset the glyph of the special character xxx. Normally, it is +more convenient to use \[xxx], but \C has some +advantages: it is compatible with AT&T device-independent +troff (and therefore available in compatibility +mode79) and can interpolate special +characters with ‘]’ in their names. The delimiter need not be +a neutral apostrophe; see Delimiters. +

+ +
+
Request: .composite id1 id2
+
+ +

Map special character name id1 to id2 if id1 is used +in \[...] with more than one component. See above for examples. +This is a strict rewriting of the special character name; no check is +performed for the existence of a glyph for either. A set of default +mappings for many accents can be found in the file +composite.tmac, loaded by the default troffrc at startup. +

+ +
+
Escape sequence: \N'n'
+
+ + + + +

Typeset the glyph with code n in the current font +(n is not the input character code). The number +n can be any non-negative decimal integer. Most devices only +have glyphs with codes between 0 and 255; the Unicode output device +uses codes in the range 0–65535. If the current font does not contain +a glyph with that code, special fonts are not searched. The +\N escape sequence can be conveniently used in conjunction with +the char request: +

+
+
.char \[phone] \f[ZD]\N'37'
+
+ + + + +

The code of each glyph is given in the fourth column in the font +description file after the charset command. It is possible to +include unnamed glyphs in the font description file by using a name of +‘---’; the \N escape sequence is the only way to use these. +

+

No kerning is applied to glyphs accessed with \N. The delimiter +need not be a neutral apostrophe; see Delimiters. +

+ +

A few escape sequences are also special characters. +

+
+
Escape sequence: \'
+
+

An escaped neutral apostrophe is a synonym for \[aa] (acute +accent). +

+ +
+
Escape sequence: \`
+
+

An escaped grave accent is a synonym for \[ga] (grave accent). +

+ +
+
Escape sequence: \-
+
+

An escaped hyphen-minus is a synonym for \[-] (minus sign). +

+ +
+
Escape sequence: \_
+
+

An escaped underscore (“low line”) is a synonym for \[ul] +(underrule). On typesetting devices, the underrule is font-invariant +and drawn lower than the underscore ‘_’. +

+ +
+
Request: .cflags n c1 c2 …
+
+ + + + +

Assign properties encoded by the number n to characters c1, +c2, and so on. +

+

Input characters, including special characters introduced by an escape, +have certain properties associated with them.80 +These properties can be modified with this request. The first argument +is the sum of the desired flags and the remaining arguments are the +characters to be assigned those properties. Spaces between the cn +arguments are optional. Any argument cn can be a character class +defined with the class request rather than an individual +character. See Character Classes. +

+

The non-negative integer n is the sum of any of the following. +Some combinations are nonsensical, such as ‘33’ (1 + 32). +

+
+
1
+
+

Recognize the character as ending a sentence if followed by a newline +or two spaces. Initially, characters ‘.?!’ have this property. +

+
+
2
+
+

Enable breaks before the character. A line is not broken at a character +with this property unless the characters on each side both have non-zero +hyphenation codes. This exception can be overridden by adding 64. +Initially, no characters have this property. +

+
+
4
+
+ +

Enable breaks after the character. A line is not broken at a character +with this property unless the characters on each side both have non-zero +hyphenation codes. This exception can be overridden by adding 64. +Initially, characters ‘\-\[hy]\[em]’ have this property. +

+
+
8
+
+ + + + + +

Mark the glyph associated with this character as overlapping other +instances of itself horizontally. Initially, characters +‘\[ul]\[rn]\[ru]\[radicalex]\[sqrtex]’ have this property. +

+
+
16
+

Mark the glyph associated with this character as overlapping other +instances of itself vertically. Initially, the character ‘\[br]’ +has this property. +

+
+
32
+
+ + + + + + + + + +

Mark the character as transparent for the purpose of end-of-sentence +recognition. In other words, an end-of-sentence character followed by +any number of characters with this property is treated as the end of a +sentence if followed by a newline or two spaces. This is the same as +having a zero space factor in TeX. Initially, characters +‘"')]*\[dg]\[dd]\[rq]\[cq]’ have this property. +

+
+
64
+

Ignore hyphenation codes of the surrounding characters. Use this in +combination with values 2 and 4 (initially, no characters have this +property). +

+

For example, if you need an automatic break point after the en-dash in +numeric ranges like “3000–5000”, insert +

+
+
.cflags 68 \[en]
+
+ +

into your document. However, this practice can lead to bad layout if +done thoughtlessly; in most situations, a better solution instead of +changing the cflags value is to insert \: right after the +hyphen at the places that really need a break point. +

+
+ +

The remaining values were implemented for East Asian language support; +those who use alphabetic scripts exclusively can disregard them. +

+
+
128
+

Prohibit a line break before the character, but allow a line break after +the character. This works only in combination with flags 256 and 512 +and has no effect otherwise. Initially, no characters have this +property. +

+
+
256
+

Prohibit a line break after the character, but allow a line break before +the character. This works only in combination with flags 128 and 512 +and has no effect otherwise. Initially, no characters have this +property. +

+
+
512
+

Allow line break before or after the character. This works only in +combination with flags 128 and 256 and has no effect otherwise. +Initially, no characters have this property. +

+
+ +

In contrast to values 2 and 4, the values 128, 256, and 512 work +pairwise. If, for example, the left character has value 512, and the +right character 128, no break will be automatically inserted between +them. If we use value 6 instead for the left character, a break +after the character can’t be suppressed since the neighboring character +on the right doesn’t get examined. +

+ +
+
Request: .char c [contents]
+
+
Request: .fchar c [contents]
+
+
Request: .fschar f c [contents]
+
+
Request: .schar c [contents]
+
+ + + + + + + + + + + + + + + + + + + + + +

Define a new character or glyph c to be contents, which +can be empty. More precisely, char defines a groff object +(or redefines an existing one) that is accessed with the +name c on input, and produces contents on output. +Every time glyph c needs to be printed, contents is +processed in a temporary environment and the result is wrapped up into a +single object. Compatibility mode is turned off and the escape +character is set to \ while contents is processed. +Any emboldening, constant spacing, or track kerning is applied to this +object rather than to individual glyphs in contents. +

+

An object defined by these requests can be used just like a normal glyph +provided by the output device. In particular, other characters can be +translated to it with the tr or trin requests; it can be +made the leader character with the lc request; repeated patterns +can be drawn with it using the \l and \L escape sequences; +and words containing c can be hyphenated correctly if the +hcode request is used to give the object a hyphenation code. +

+

There is a special anti-recursion feature: use of the object within its +own definition is handled like a normal character (not +defined with char). +

+

The tr and trin requests take precedence if char +accesses the same symbol. +

+
+
.tr XY
+X
+    ⇒ Y
+.char X Z
+X
+    ⇒ Y
+.tr XX
+X
+    ⇒ Z
+
+ +

The fchar request defines a fallback glyph: gtroff only +checks for glyphs defined with fchar if it cannot find the glyph +in the current font. gtroff carries out this test before +checking special fonts. +

+

fschar defines a fallback glyph for font f: +gtroff checks for glyphs defined with fschar after the +list of fonts declared as font-specific special fonts with the +fspecial request, but before the list of fonts declared as global +special fonts with the special request. +

+

Finally, the schar request defines a global fallback glyph: +gtroff checks for glyphs defined with schar after the list +of fonts declared as global special fonts with the special +request, but before the already mounted special fonts. +

+

See Character Classes. +

+ +
+
Request: .rchar c …
+
+
Request: .rfschar f c …
+
+ + + +

Remove definition of each ordinary or special character c, +undoing the effect of a char, fchar, or schar +request. Those supplied by font description files cannot be removed. +Spaces and tabs may separate c arguments. +

+

The request rfschar removes glyph definitions defined with +fschar for font f. +

+ + +
+
+
+

+Next: Character Classes, Previous: Font Positions, Up: Using Fonts   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/Vertical-Position-Traps.html b/doc/groff.html.node/Vertical-Position-Traps.html new file mode 100644 index 0000000..d12f564 --- /dev/null +++ b/doc/groff.html.node/Vertical-Position-Traps.html @@ -0,0 +1,94 @@ + + + + + + +Vertical Position Traps (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Traps   [Contents][Index]

+
+
+

5.28.1 Vertical Position Traps

+ + + +

A vertical position trap calls a macro when the formatter’s +vertical drawing position reaches or passes, in the downward direction, +a certain location on the output page or in a diversion. Its +applications include setting page headers and footers, body text in +multiple columns, and footnotes. +

+
+
Request: .vpt [flag]
+
+
Register: \n[.vpt]
+
+ + + +

Enable vertical position traps if flag is non-zero or absent; +disable them otherwise. Vertical position traps are those set by the +wh request or by dt within a diversion. The parameter +that controls whether vertical position traps are enabled is global. +Initially, vertical position traps are enabled. The current value is +stored in the .vpt read-only register. +

+ + + + +

A page can’t be ejected if vpt is set to zero; see The Implicit Page Trap. +

+ + + + +
+ + + + + diff --git a/doc/groff.html.node/Warnings.html b/doc/groff.html.node/Warnings.html new file mode 100644 index 0000000..b61ec3a --- /dev/null +++ b/doc/groff.html.node/Warnings.html @@ -0,0 +1,246 @@ + + + + + + +Warnings (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Debugging   [Contents][Index]

+
+
+

5.37.1 Warnings

+ + +

Warning diagnostics emitted by GNU troff are divided into named, +numbered categories. The name associated with each warning category is +used by the -w and -W options. Each category is also +assigned a power of two; the sum of enabled category values is used by +the warn request and the .warn register. +

+

Warnings of each category are produced under the following +circumstances. +

+ + +
+
‘char’
+
‘1’
+

No mounted font defines a glyph for the requested character. This +category is enabled by default. +

+
+
‘number’
+
‘2’
+

An invalid numeric expression was encountered. This category is enabled +by default. +See Numeric Expressions. +

+
+
‘break’
+
‘4’
+
+

A filled output line could not be broken such that its length was less +than the output line length ‘\n[.l]’. This category is enabled by +default. +

+
+
‘delim’
+
‘8’
+

The closing delimiter in an escape sequence was missing or mismatched. +

+
+
‘el’
+
‘16’
+
+

The el request was encountered with no prior corresponding +ie request. See if-else. +

+
+
‘scale’
+
‘32’
+

A scaling unit inappropriate to its context was used in a numeric +expression. +

+
+
‘range’
+
‘64’
+

A numeric expression was out of range for its context. +

+
+
‘syntax’
+
‘128’
+

A self-contradictory hyphenation mode was requested; an empty or +incomplete numeric expression was encountered; an operand to a numeric +operator was missing; an attempt was made to define a recursive, empty, +or nonsensical character class; or a groff extension conditional +expression operator was used while in compatibility mode. +

+
+
‘di’
+
‘256’
+
+ + +

A di, da, box, or boxa request was invoked +without an argument when there was no current diversion. +

+
+
‘mac’
+
‘512’
+
+ + + + + + +

An undefined string, macro, or diversion was used. When such an object +is dereferenced, an empty one of that name is automatically created. +So, unless it is later deleted, at most one warning is given for each. +

+

This warning is also emitted upon an attempt to move an unplanted trap +macro (see Page Location Traps). In such cases, the unplanted macro +is not dereferenced, so it is not created if it does not exist. +

+
+
‘reg’
+
‘1024’
+
+ +

An undefined register was used. When an undefined register is +dereferenced, it is automatically defined with a value of 0. So, +unless it is later deleted, at most one warning is given for each. +

+
+
‘tab’
+
‘2048’
+

A tab character was encountered where a number was expected, or appeared +in an unquoted macro argument. +

+
+
‘right-brace’
+
‘4096’
+

A right brace escape sequence \} was encountered where a number +was expected. +

+
+
‘missing’
+
‘8192’
+

A request was invoked with a mandatory argument absent. +

+
+
‘input’
+
‘16384’
+

An invalid character occurred on the input stream. +

+
+
‘escape’
+
‘32768’
+

An unsupported escape sequence was encountered. +

+
+
‘space’
+
‘65536’
+

A space was missing between a request or macro and its argument. This +warning is produced when an undefined name longer than two characters is +encountered and the first two characters of the name constitute a +defined name. No request is invoked, no macro called, and an empty +macro is not defined. This category is enabled by default. It never +occurs in compatibility mode. +

+
+
‘font’
+
‘131072’
+

A non-existent font was selected, or the selection was ignored because a +font selection escape sequence was used after the output line +continuation escape sequence on an input line. This category is enabled +by default. +

+
+
‘ig’
+
‘262144’
+

An invalid escape sequence occurred in input ignored using the ig +request. This warning category diagnoses a condition that is an error +when it occurs in non-ignored input. +

+
+
‘color’
+
‘524288’
+

An undefined color was selected, an attempt was made to define a color +using an unrecognized color space, an invalid component in a color +definition was encountered, or an attempt was made to redefine a default +color. +

+
+
‘file’
+
‘1048576’
+

An attempt was made to load a file that does not exist. This category +is enabled by default. +

+
+ +

Two warning names group other warning categories for convenience. +

+
+
‘all’
+

All warning categories except ‘di’, ‘mac’ and ‘reg’. +This shorthand is intended to produce all warnings that are useful with +macro packages written for AT&T troff and its +descendants, which have less fastidious diagnostics than GNU +troff. +

+
+
‘w’
+

All warning categories. Authors of documents and macro packages +targeting groff are encouraged to use this setting. +

+
+ + +
+
+
+

+Previous: Debugging, Up: Debugging   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/What-Is-groff_003f.html b/doc/groff.html.node/What-Is-groff_003f.html new file mode 100644 index 0000000..99939ea --- /dev/null +++ b/doc/groff.html.node/What-Is-groff_003f.html @@ -0,0 +1,68 @@ + + + + + + +What Is groff? (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+
+

1.2 What Is groff?

+ + + +

groff (GNU roff) is a typesetting system that reads plain +text input files that include formatting commands to produce output in +PostScript, PDF, HTML, DVI, or other formats, or for display to a +terminal. Formatting commands can be low-level typesetting primitives, +macros from a supplied package, or user-defined macros. All three +approaches can be combined. +

+

A reimplementation and extension of the typesetter from AT&T +Unix, groff is present on most POSIX systems owing to +its long association with Unix manuals (including man pages). It and +its predecessor are notable for their production of several best-selling +software engineering texts. groff is capable of producing +typographically sophisticated documents while consuming minimal system +resources. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/Writing-Macros.html b/doc/groff.html.node/Writing-Macros.html new file mode 100644 index 0000000..e08b9fa --- /dev/null +++ b/doc/groff.html.node/Writing-Macros.html @@ -0,0 +1,267 @@ + + + + + + +Writing Macros (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.24 Writing Macros

+ + + +

A macro is a stored collection of text and control lines that can +be interpolated multiple times. Use macros to define common operations. +Macros are called in the same way that requests are invoked. While +requests exist for the purpose of creating macros, simply calling an +undefined macro, or interpolating it as a string, will cause it to be +defined as empty. See Identifiers. +

+
+
Request: .de name [end]
+
+

Define a macro name, replacing the definition of any existing +request, macro, string, or diversion called name. If +name already exists as an alias, the target of the alias is +redefined; recall Strings. GNU troff enters copy +mode,97 storing subsequent input lines as the +macro definition. If the optional second argument is not specified, the +definition ends with the control line ‘..’ (two dots). +Alternatively, end identifies a macro whose call syntax at the +start of a control line ends the definition of name; end is +then called normally. A macro definition must end in the same +conditional block (if any) in which it began (see Conditional Blocks). Spaces or tabs are permitted after the control character in +the line containing this ending token (either ‘.’ or +‘end’), but a tab immediately after the token prevents its +recognition as the end of a macro definition. The macro end can +be called with arguments.98 +

+

Here is a small example macro called ‘P’ that causes a break and +inserts some vertical space. It could be used to separate paragraphs. +

+
+
.de P
+.  br
+.  sp .8v
+..
+
+ +

We can define one macro within another. Attempting to nest ‘..’ +naïvely will end the outer definition because the inner definition +isn’t interpreted as such until the outer macro is later interpolated. +We can use an end macro instead. Each level of nesting should use a +unique end macro. +

+

An end macro need not be defined until it is called. This fact enables +a nested macro definition to begin inside one macro and end inside +another. Consider the following example.99 +

+
+
.de m1
+.  de m2 m3
+you
+..
+.de m3
+Hello,
+Joe.
+..
+.de m4
+do
+..
+.m1
+know?
+.  m3
+What
+.m4
+.m2
+    ⇒ Hello, Joe.  What do you know?
+
+ +

A nested macro definition can be terminated with ‘..’ and +nested macros can reuse end macros, but these control lines must +be escaped multiple times for each level of nesting. The necessity of +this escaping and the utility of nested macro definitions will become +clearer when we employ macro parameters and consider the behavior of +copy mode in detail. +

+ +

de defines a macro that inherits the compatibility mode +enablement status of its context (see Implementation Differences). +Often it is desirable to make a macro that uses groff features +callable from contexts where compatibility mode is on; for instance, +when writing extensions to a historical macro package. To achieve this, +compatibility mode needs to be switched off while such a macro is +interpreted—without disturbing that state when it is finished. +

+
+
Request: .de1 name [end]
+
+

The de1 request defines a macro to be interpreted with +compatibility mode disabled. When name is called, compatibility +mode enablement status is saved; it is restored when the call completes. +Observe the extra backlash before the interpolation of register +‘xxx’; we’ll explore this subject in Copy Mode. +

+
+
.nr xxx 12345
+.de aa
+The value of xxx is \\n[xxx].
+.  br
+..
+.de1 bb
+The value of xxx is \\n[xxx].
+..
+.cp 1
+.aa
+    error→ warning: register '[' not defined
+    ⇒ The value of xxx is 0xxx].
+.bb
+    ⇒ The value of xxx is 12345.
+
+
+ +
+
Request: .dei name [end]
+
+
Request: .dei1 name [end]
+
+

The dei request defines a macro with its name and end +macro indirected through strings. That is, it interpolates strings +named name and end before performing the definition. +

+

The following examples are equivalent. +

+
+
.ds xx aa
+.ds yy bb
+.dei xx yy
+
+ +
+
.de aa bb
+
+ +

The dei1 request bears the same relationship to dei as +de1 does to de; it temporarily turns compatibility mode +off when name is called. +

+ +
+
Request: .am name [end]
+
+
Request: .am1 name [end]
+
+
Request: .ami name [end]
+
+
Request: .ami1 name [end]
+
+ + +

am appends subsequent input lines to macro name, extending +its definition, and otherwise working as de does. +

+

To make the previously defined ‘P’ macro set indented instead of +block paragraphs, add the necessary code to the existing macro. +

+
+
.am P
+.ti +5n
+..
+
+ +

The other requests are analogous to their ‘de’ counterparts. The +am1 request turns off compatibility mode during interpretation of +the appendment. The ami request appends indirectly, meaning that +strings name and end are interpolated with the resulting +names used before appending. The ami1 request is similar to +ami, disabling compatibility mode during interpretation of the +appended lines. +

+ + +

Using trace.tmac, you can trace calls to de, +de1, am, and am1. You can also use the +backtrace request at any point desired to troubleshoot tricky +spots (see Debugging). +

+

See Strings, for the als, rm, and rn requests to +create an alias of, remove, and rename a macro, respectively. +

+ +

Macro identifiers share their name space with requests, strings, and +diversions; see Identifiers. The am, as, da, +de, di, and ds requests (together with their +variants) create a new object only if the name of the macro, diversion, +or string is currently undefined or if it is defined as a request; +normally, they modify the value of an existing object. See the +description of the als request, for pitfalls when redefining a +macro that is aliased. +

+
+
Request: .return [anything]
+
+

Exit a macro, immediately returning to the caller. If called with an +argument anything, exit twice—the current macro and the macro +one level higher. This is used to define a wrapper macro for +return in trace.tmac. +

+ + + + +
+
+
+

+Next: Page Motions, Previous: Conditionals and Loops, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/als.html b/doc/groff.html.node/als.html new file mode 100644 index 0000000..711bc84 --- /dev/null +++ b/doc/groff.html.node/als.html @@ -0,0 +1,33 @@ + + + + + + + +als (The GNU Troff Manual) + + + + + + + + + + + + + + +

The node you are looking for is at als.

+ diff --git a/doc/groff.html.node/groff-Capabilities.html b/doc/groff.html.node/groff-Capabilities.html new file mode 100644 index 0000000..424779a --- /dev/null +++ b/doc/groff.html.node/groff-Capabilities.html @@ -0,0 +1,91 @@ + + + + + + +groff Capabilities (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+
+

1.3 groff Capabilities

+ + + +

GNU troff is a typesetting document formatter; it provides a wide +range of low-level text and page operations within the framework of a +programming language. These operations compose to generate footnotes, +tables of contents, mathematical equations, diagrams, multi-column text, +and other elements of typeset works. Here is a survey of formatter +features; all are under precise user control. +

+
    +
  • text filling, breaking, alignment to the left or right margin; centering + +
  • adjustment of inter-word space size to justify text, and of +inter-sentence space size to suit local style conventions + +
  • automatic and manual determination of hyphenation break points + +
  • pagination + +
  • selection of any font available to the output device + +
  • adjustment of type size and vertical spacing (or “leading”) + +
  • configuration of line length and indentation amounts; columnation + +
  • drawing of geometric primitives (lines, arcs, polygons, circles, +…) + +
  • setup of stroke and fill colors (where supported by the output +device) + +
  • embedding of hyperlinks, images, document metadata, and other inclusions +(where supported by the output device) +
+ + + +
+ + + + + diff --git a/doc/groff.html.node/groff.html_fot.html b/doc/groff.html.node/groff.html_fot.html new file mode 100644 index 0000000..1230044 --- /dev/null +++ b/doc/groff.html.node/groff.html_fot.html @@ -0,0 +1,525 @@ + + + + + + +Footnotes (The GNU Troff Manual) + + + + + + + + + + + + + + + + + +
+
+

+   [Contents][Index]

+
+
+

Footnotes

+ +
(1)
+

The ‘g’ prefix is +not used on all systems; see Invoking groff.

+
(2)
+

Unix and related operating systems distinguish +standard output and standard error streams because of +troff: +https://minnie.tuhs.org/pipermail/tuhs/2013-December/006113.html.

+
(3)
+

See Line Layout.

+
(4)
+

Besides groff, neatroff is an +exception.

+
(5)
+

The +mso request does not have these limitations. See I/O.

+
(6)
+

The remainder of this chapter is based on +Writing Papers with nroff using -me by Eric P. Allman, +which is distributed with groff as meintro.me.

+
(7)
+

While manual pages are older, early ones used +macros supplanted by the man package of Seventh Edition Unix +(1979). ms shipped with Sixth Edition (1975) and was documented +by Mike Lesk in a Bell Labs internal memorandum.

+
(8)
+

defined in Footnotes

+
(9)
+

Distinguish a +document title from “titles”, which are what roff systems call +headers and footers collectively.

+
(10)
+

This idiosyncrasy arose through +feature accretion; for example, the B macro in Version 6 +Unix ms (1975) accepted only one argument, the text to be set in +boldface. By Version 7 (1979) it recognized a second argument; in +1990, groff ms added a “pre” argument, placing it third +to avoid breaking support for older documents.

+
(11)
+

“Portable Document Format Publishing with GNU +Troff”, pdfmark.ms in the groff distribution, uses this +technique.

+
(12)
+

Unix Version 7 ms, its descendants, and GNU +ms prior to groff version 1.23.0

+
(13)
+

You could reset it +after each call to .1C, .2C, or .MC.

+
(14)
+

Typing Documents on the UNIX System: Using the +-ms Macros with Troff and Nroff, M. E. Lesk, Bell Laboratories, +1978

+
(15)
+

Register values are converted to and stored as +basic units. See Measurements.

+
(16)
+

If you redefine the ms PT macro +and desire special treatment of certain page numbers (like ‘1’), +you may need to handle a non-Arabic page number format, as groff +ms’s PT does; see the macro package source. groff +ms aliases the PN register to %.

+
(17)
+

The removal beforehand is necessary +because groff ms aliases these macros to a diagnostic +macro, and you want to redefine the aliased name, not its target.

+
(18)
+

See Device and Font Description Files.

+
(19)
+

Tabs and leaders also separate +words. Escape sequences can function as word characters, word +separators, or neither—the last simply have no effect on GNU +troff’s idea of whether an input character is within a word. +We’ll discuss all of these in due course.

+
(20)
+

A +well-researched jeremiad appreciated by groff contributors on +both sides of the sentence-spacing debate can be found at +https://web.archive.org/web/20171217060354/http://www.heracliteanriver.com/?p=324.

+
(21)
+

This statement oversimplifies; there are +escape sequences whose purpose is precisely to produce glyphs on the +output device, and input characters that aren’t part of escape +sequences can undergo a great deal of processing before getting to the +output.

+
(22)
+

The mnemonics for the special +characters shown here are “dagger”, “double dagger”, “right +(double) quote”, and “closing (single) quote”. See the +groff_char(7) man page.

+
(23)
+

“Text lines” are defined in Requests and Macros.

+
(24)
+

“Tab” +is short for “tabulation”, revealing the term’s origin as a spacing +mechanism for table arrangement.

+
(25)
+

The \RET escape sequence can alter how an +input line is classified; see Line Continuation.

+
(26)
+

Argument handling in +macros is more flexible but also more complex. See Calling Macros.

+
(27)
+

Some escape sequences undergo +interpolation as well.

+
(28)
+

GNU troff offers additional ones. See Writing Macros.

+
(29)
+

Macro files and packages +frequently define registers and strings as well.

+
(30)
+

The +semantics of certain punctuation code points have gotten stricter +with the successive standards, a cause of some frustration among man +page writers; see the groff_char(7) man page.

+
(31)
+

The +DVI output device defaults to using the Computer Modern (CM) fonts; +ec.tmac loads the EC fonts instead, which provide Euro +‘\[Eu]’ and per mille ‘\[%0]’ glyphs.

+
(32)
+

Emacs: fill-column: 72; Vim: textwidth=72

+
(33)
+

groff does not yet support right-to-left +scripts.

+
(34)
+

groff’s terminal output devices have page +offsets of zero.

+
(35)
+

Provision is made for interpreting and +reporting decimal fractions in certain cases.

+
(36)
+

If that’s not enough, see the groff_tmac(5) +man page for the 62bit.tmac macro package.

+
(37)
+

See Conditionals and Loops.

+
(38)
+

Control structure syntax +creates an exception to this rule, but is designed to remain useful: +recalling our example, ‘.if 1 .Underline this’ would underline only +“this”, precisely. See Conditionals and Loops.

+
(39)
+

See Diversions.

+
(40)
+

Historically, control characters like +ASCII STX, ETX, and BEL (Control+B, Control+C, and +Control+G) have been observed in roff documents, +particularly in macro packages employing them as delimiters with the +output comparison operator to try to avoid collisions with the content +of arbitrary user-supplied parameters (see Operators in Conditionals). We discourage this expedient; in GNU troff it is +unnecessary (outside of compatibility mode) because delimited arguments +are parsed at a different input level than the surrounding context. +See Implementation Differences.

+
(41)
+

Consider what happens when a C1 control +0x80–0x9F is necessary as a continuation byte in a UTF-8 +sequence.

+
(42)
+

Recall Identifiers.

+
(43)
+

In compatibility +mode, a space is not necessary after a request or macro name of two +characters’ length. Also, Plan 9 troff allows tabs to +separate arguments.

+
(44)
+

\~ is fairly +portable; see Other Differences.

+
(45)
+

Strictly, you can neglect to +close the last quoted macro argument, relying on the end of the control +line to do so. We consider this lethargic practice poor style.

+
(46)
+

The omission of spaces before the comment +escape sequences is necessary; see Strings.

+
(47)
+

TeX does have such a mechanism.

+
(48)
+

This claim may be more aspirational than descriptive.

+
(49)
+

See Conditional Blocks.

+
(50)
+

Exception: auto-incrementing registers defined outside +the ignored region will be modified if interpolated with +\n± inside it. See Auto-increment.

+
(51)
+

A negative auto-increment can be +considered an “auto-decrement”.

+
(52)
+

GNU troff dynamically allocates memory for +as many registers as required.

+
(53)
+

unless diverted; see Diversions

+
(54)
+

See Line Continuation.

+
(55)
+

Recall Filling and Sentences for the +definitions of word and sentence boundaries, respectively.

+
(56)
+

Whether a perfect algorithm for this application is +even possible is an unsolved problem in computer science: +https://tug.org/docs/liang/liang-thesis.pdf.

+
(57)
+

\% itself stops marking +hyphenation points but still produces no output glyph.

+
(58)
+

“Soft” because it appears in output +only where a hyphenation break is performed; a “hard” hyphen, as in +“long-term”, always appears.

+
(59)
+

The mode is a vector of Booleans encoded as an integer. +To a programmer, this fact is easily deduced from the exclusive use of +powers of two for the configuration parameters; they are computationally +easy to “mask off” and compare to zero. To almost everyone else, the +arrangement seems recondite and unfriendly.

+
(60)
+

Hyphenation is +prevented if the next page location trap is closer to the vertical +drawing position than the next text baseline would be. See Page Location Traps.

+
(61)
+

For more on localization, see the +groff_tmac(5) man page.

+
(62)
+

See Page Location Traps.

+
(63)
+

See Drawing Geometric Objects.

+
(64)
+

or geometric objects; see Drawing Geometric Objects

+
(65)
+

to the top-level diversion; +see Diversions

+
(66)
+

Plan 9 troff +uses the register .S for this purpose.

+
(67)
+

This is pronounced to rhyme with “feeder”, and +refers to how the glyphs “lead” the eye across the page to the +corresponding page number or other datum.

+
(68)
+

A +GNU nroff program is available for convenience; it calls GNU +troff to perform the formatting.

+
(69)
+

Historically, the \c +escape sequence has proven challenging to characterize. Some sources +say it “connects the next input text” (to the input line on which it +appears); others describe it as “interrupting” text, on the grounds +that a text line is interrupted without breaking, perhaps to inject a +request invocation or macro call.

+
(70)
+

See Traps.

+
(71)
+

See Diversions.

+
(72)
+

Terminals and some output devices have fonts that render +at only one or two sizes. As examples of the latter, take the +groff lj4 device’s Lineprinter, and lbp’s Courier +and Elite faces.

+
(73)
+

Font designers prepare families such that the styles +share esthetic properties.

+
(74)
+

Historically, the fonts +troffs dealt with were not Free Software or, as with the Graphic +Systems C/A/T, did not even exist in the digital domain.

+
(75)
+

See Font Description File Format.

+
(76)
+

See DESC File Format.

+
(77)
+

Not all versions of the man program +support the -T option; use the subsequent example for an +alternative.

+
(78)
+

This is “Normalization Form D” +as documented in Unicode Standard Annex #15 +(https://unicode.org/reports/tr15/).

+
(79)
+

See Compatibility Mode.

+
(80)
+

Output glyphs +don’t—to GNU troff, a glyph is simply a box with an index into +a font, a given height above and depth below the baseline, and a width.

+
(81)
+

Opinions of this escape sequence’s name abound. +“Zero-width space” is a popular misnomer: roff formatters do +not treat it like a space. Ossanna called it a “non-printing, +zero-width character”, but the character causes output even +though it does not “print”. If no output line is pending, the dummy +character starts one. Contrast an empty input document with one +containing only \&. The former produces no output; the latter, a +blank page.

+
(82)
+

In text fonts, the tallest glyphs are typically +parentheses. Unfortunately, in many cases the actual dimensions of the +glyphs in a font do not closely match its declared type size! For +example, in the standard PostScript font families, 10-point Times sets +better with 9-point Helvetica and 11-point Courier than if all three +were used at 10 points.

+
(83)
+

Rhyme with “sledding”; mechanical typography +used lead metal (Latin plumbum).

+
(84)
+

The claim appears to have been true of Ossanna +troff for the C/A/T device; Kernighan made device-independent +troff more flexible.

+
(85)
+

See Device and Font Description Files.

+
(86)
+

also +known vulgarly as “ANSI colors”

+
(87)
+

See Copy Mode.

+
(88)
+

This refers to +vtroff, a translator that would convert the C/A/T output from +early-vintage AT&T troff to a form suitable for +Versatec and Benson-Varian plotters.

+
(89)
+

Strictly, letters not otherwise recognized are treated +as output comparison delimiters. For portability, it is wise to avoid +using letters not in the list above; for example, Plan 9 +troff uses ‘h’ to test a mode it calls htmlroff, and +GNU troff may provide additional operators in the future.

+
(90)
+

Because formatting of the comparands takes place +in a dummy environment, vertical motions within them cannot spring +traps.

+
(91)
+

All +of this is to say that the lists of output nodes created by formatting +xxx and yyy must be identical. See gtroff Internals.

+
(92)
+

This bizarre behavior maintains compatibility with +AT&T troff.

+
(93)
+

See while.

+
(94)
+

See Copy Mode.

+
(95)
+

unless you redefine it

+
(96)
+

“somewhat less” because +things other than macro calls can be on the input stack

+
(97)
+

See Copy Mode.

+
(98)
+

While it is possible to define and +call a macro ‘.’, you can’t use it as an end macro: during a macro +definition, ‘..’ is never handled as calling ‘.’, even if +‘.de name .’ explicitly precedes it.

+
(99)
+

Its structure is +adapted from, and isomorphic to, part of a solution by Tadziu Hoffman to +the problem of reflowing text multiple times to find an optimal +configuration for it. +https://lists.gnu.org/archive/html/groff/2008-12/msg00006.html

+
(100)
+

If they were not, +parameter interpolations would be similar to command-line +parameters—fixed for the entire duration of a roff program’s +run. The advantage of interpolating \$ escape sequences even in +copy mode is that they can interpolate different contents from one call +to the next, like function parameters in a procedural language. The +additional escape character is the price of this power.

+
(101)
+

Compare this to the \def and \edef +commands in TeX.

+
(102)
+

These are lightly adapted from the groff +implementation of the ms macros.

+
(103)
+

At the +grops defaults of 10-point type on 12-point vertical spacing, the +difference between half a vee and half an em can be subtle: large +spacings like ‘.vs .5i’ make it obvious.

+
(104)
+

See Strings, for an explanation of the trailing +‘\"’.

+
(105)
+

(hc, vc) is adjusted to the point nearest +the perpendicular bisector of the arc’s chord.

+
(106)
+

See The Implicit Page Trap.

+
(107)
+

A trap planted at ‘20i’ or +‘-30i’ will not be sprung on a page of length ‘11i’.

+
(108)
+

It may help to think of each trap location as +maintaining a queue; wh operates on the head of the queue, and +ch operates on its tail. Only the trap at the head of the queue +is visible.

+
(109)
+

See Debugging.

+
(110)
+

See Diversions.

+
(111)
+

While processing an +end-of-input macro, the formatter assumes that the next page break must +be the last; it goes into “sudden death overtime”.

+
(112)
+

Another, taken by the groff man macros, is +to intercept ne requests and wrap bp ones.

+
(113)
+

Thus, the “water” +gets “higher” proceeding down the page.

+
(114)
+

The backslash is doubled. See Copy Mode.

+
(115)
+

that is, ISO 646:1991-IRV or, +popularly, “US-ASCII”

+
(116)
+

They are bypassed because these parameters are not +rendered as glyphs in the output; instead, they remain abstract +characters—in a PDF bookmark or a URL, for example.

+
(117)
+

Recall Line Layout.

+
(118)
+

Historically, +tools named nrchbar and changebar were developed for +marking changes with margin characters and could be found in archives of +the comp.sources.unix USENET group. Some proprietary +Unices also offer(ed) a diffmk program.

+
(119)
+

Except the +escape sequences \f, \F, \H, \m, \M, +\R, \s, and \S, which are processed immediately if +not in copy mode.

+
(120)
+

The +Graphic Systems C/A/T phototypesetter (the original device target for +AT&T troff) supported only a few discrete type sizes +in the range 6–36 points, so Ossanna contrived a special case in the +parser to do what the user must have meant. Kernighan warned of this in +the 1992 revision of CSTR #54 (§2.3), and more recently, McIlroy +referred to it as a “living fossil”.

+
(121)
+

DWB 3.3, Solaris, Heirloom Doctools, and +Plan 9 troff all support it.

+
(122)
+

Naturally, if you’ve changed +the escape character, you need to prefix the e with whatever it +is—and you’ll likely get something other than a backslash in the +output.

+
(123)
+

The rs special character identifier was not +defined in AT&T troff’s font description files, but is +in those of its lineal descendant, Heirloom Doctools troff, as of +the latter’s 060716 release (July 2006).

+
(124)
+

The parser +and postprocessor for intermediate output can be found in the file
+groff-source-dir/src/libs/libdriver/input.cpp.

+
(125)
+

Plan 9 troff has also abandoned the binary +format.

+
(126)
+

800-point type +is not practical for most purposes, but using it enables the quantities +in the font description files to be expressed as integers.

+
(127)
+

groff requests and escape sequences +interpret non-negative font names as mounting positions instead. +Further, a font named ‘0’ cannot be automatically mounted by the +fonts directive of a DESC file.

+
(128)
+

For typesetter devices, this directive is misnamed +since it starts a list of glyphs, not characters.

+
(129)
+

that is, any integer parsable by the C +standard library’s strtol(3) function

+
+
+

+   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/gtroff-Output.html b/doc/groff.html.node/gtroff-Output.html new file mode 100644 index 0000000..cab0daf --- /dev/null +++ b/doc/groff.html.node/gtroff-Output.html @@ -0,0 +1,100 @@ + + + + + + +gtroff Output (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: File Formats   [Contents][Index]

+
+
+

6.1 gtroff Output

+ + + +

This section describes the groff intermediate output format +produced by GNU troff. +

+

As groff is a wrapper program around GNU troff and +automatically calls an output driver (or “postprocessor”), this output +does not show up normally. This is why it is called +intermediate. groff provides the option -Z to +inhibit postprocessing such that the produced intermediate output is +sent to standard output just as it is when calling GNU troff +directly. +

+ + + + +

Here, the term troff output describes what is output by +GNU troff, while intermediate output refers to the language +that is accepted by the parser that prepares this output for the output +drivers. This parser handles whitespace more flexibly than +AT&T’s implementation and implements obsolete elements for +compatibility; otherwise, both formats are the same.124 +

+

The main purpose of the intermediate output concept is to facilitate the +development of postprocessors by providing a common programming +interface for all devices. It has a language of its own that is +completely different from the gtroff language. While the +gtroff language is a high-level programming language for text +processing, the intermediate output language is a kind of low-level +assembler language by specifying all positions on the page for writing +and drawing. +

+

The intermediate output produced by gtroff is fairly readable, +while output from AT&T troff is rather hard to +understand because of strange habits that are still supported, but not +used any longer by gtroff. +

+ + + +
+
+
+

+Next: Device and Font Description Files, Previous: File Formats, Up: File Formats   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/if_002delse.html b/doc/groff.html.node/if_002delse.html new file mode 100644 index 0000000..3c67fa9 --- /dev/null +++ b/doc/groff.html.node/if_002delse.html @@ -0,0 +1,97 @@ + + + + + + +if-else (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Conditionals and Loops   [Contents][Index]

+
+
+

5.23.3 if-else

+ + +
+
Request: .ie cond-expr anything
+
+
Request: .el anything
+
+

Use the ie and el requests to write an if-then-else. The +first request is the “if” part and the latter is the “else” part. +Unusually among programming languages, any number of non-conditional +requests may be interposed between the ie branch and the +el branch. +

+
+
.nr a 0
+.ie \na a is non-zero.
+.nr a +1
+.el a was not positive but is now \na.
+    ⇒ a was not positive but is now 1.
+
+ +

Another way in which el is an ordinary request is that it does +not lexically “bind” more tightly to its ie counterpart than it +does to any other request. This fact can surprise C programmers. +

+
+
.nr a 1
+.nr z 0
+.ie \nz \
+.  ie \na a is true
+.  el     a is false
+.el z is false
+    error→ warning: unbalanced 'el' request
+    ⇒ a is false
+
+ +

To conveniently nest conditionals, keep reading. +

+
+ + +
+ + + + + diff --git a/doc/groff.html.node/if_002dthen.html b/doc/groff.html.node/if_002dthen.html new file mode 100644 index 0000000..e2fba2b --- /dev/null +++ b/doc/groff.html.node/if_002dthen.html @@ -0,0 +1,111 @@ + + + + + + +if-then (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Conditionals and Loops   [Contents][Index]

+
+
+

5.23.2 if-then

+ + +
+
Request: .if cond-expr anything
+
+

Evaluate the conditional expression cond-expr, and if it evaluates +true (or to a positive value), interpret the remainder of the line +anything as if it were an input line. Recall from Invoking Requests that any quantity of spaces between arguments to requests +serves only to separate them; leading spaces in anything are thus +not seen. anything effectively cannot be omitted; if +cond-expr is true and anything is empty, the newline at the +end of the control line is interpreted as a blank input line (and +therefore a blank text line). +

+
+
super\c
+tanker
+.nr force-word-break 1
+super\c
+.if ((\n[force-word-break] = 1) & \n[.int])
+tanker
+    ⇒ supertanker super tanker
+
+
+ +
+
Request: .nop anything
+
+

Interpret anything as if it were an input line. This is similar +to ‘.if 1’. nop is not really “no operation”; its +argument is processed—unconditionally. It can be used to cause +text lines to share indentation with surrounding control lines. +

+
+
.als real-MAC MAC
+.de wrapped-MAC
+.  tm MAC: called with arguments \\$@
+.  nop \\*[real-MAC]\\
+..
+.als MAC wrapped-MAC
+\# Later...
+.als MAC real-MAC
+
+ +

In the above, we’ve used aliasing, nop, and the interpolation of +a macro as a string to interpose a wrapper around the macro ‘MAC’ +(perhaps to debug it). +

+ + +
+
+
+

+Next: if-else, Previous: Operators in Conditionals, Up: Conditionals and Loops   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/index.html b/doc/groff.html.node/index.html new file mode 100644 index 0000000..d1b9973 --- /dev/null +++ b/doc/groff.html.node/index.html @@ -0,0 +1,453 @@ + + + + + + +Top (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: (dir)   [Contents][Index]

+
+
+

GNU troff

+ + +

This manual documents GNU troff version 1.23.0. +

+

Copyright © 1994–2023 Free Software Foundation, Inc. +

+
+

Permission is granted to copy, distribute and/or modify this document +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, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled “GNU Free +Documentation License”. +

+ + + + + +
+

Table of Contents

+ +
+ + +
+
+
+
+
+

+Next: , Previous: , Up: (dir)   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/man.html b/doc/groff.html.node/man.html new file mode 100644 index 0000000..93ec854 --- /dev/null +++ b/doc/groff.html.node/man.html @@ -0,0 +1,71 @@ + + + + + + +man (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Macro Packages   [Contents][Index]

+
+
+

4.1 man

+ + + + + +

The man macro package is the most widely used and probably the +most important ever developed for troff. It is easy to use, and +a vast majority of manual pages (“man pages”) are written in it. +

+

groff’s implementation is documented in the +groff_man(7) man page. Type ‘man groff_man’ at the +command line to view it. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/mdoc.html b/doc/groff.html.node/mdoc.html new file mode 100644 index 0000000..d752098 --- /dev/null +++ b/doc/groff.html.node/mdoc.html @@ -0,0 +1,61 @@ + + + + + + +mdoc (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Macro Packages   [Contents][Index]

+
+
+

4.2 mdoc

+ + +

groff’s implementation of the BSD doc package for man +pages is documented in the groff_mdoc(7) man page. Type +‘man groff_mdoc’ at the command line to view it. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/me.html b/doc/groff.html.node/me.html new file mode 100644 index 0000000..35da9f2 --- /dev/null +++ b/doc/groff.html.node/me.html @@ -0,0 +1,67 @@ + + + + + + +me (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Macro Packages   [Contents][Index]

+
+
+

4.3 me

+ + +

groff’s implementation of the BSD me macro package is +documented using itself. A tutorial, meintro.me, and reference, +meref.me, are available in groff’s documentation +directory. A groff_me(7) man page is also available and +identifies the installation path for these documents. Type ‘man +groff_me’ at the command line to view it. +

+

A French translation of the tutorial is available as +meintro_fr.me and installed parallel to the English version. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/mm.html b/doc/groff.html.node/mm.html new file mode 100644 index 0000000..38dc3b9 --- /dev/null +++ b/doc/groff.html.node/mm.html @@ -0,0 +1,64 @@ + + + + + + +mm (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Macro Packages   [Contents][Index]

+
+
+

4.4 mm

+ + +

groff’s implementation of the AT&T memorandum macro +package is documented in the groff_mm(7) man page. Type +‘man groff_mm’ at the command line) to view it. +

+

A Swedish localization of mm is also available; see +groff_mmse(7). +

+ + +
+ + + + + diff --git a/doc/groff.html.node/mom.html b/doc/groff.html.node/mom.html new file mode 100644 index 0000000..6d0840d --- /dev/null +++ b/doc/groff.html.node/mom.html @@ -0,0 +1,85 @@ + + + + + + +mom (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Macro Packages   [Contents][Index]

+
+
+

4.5 mom

+ + +

The main documentation files for the mom macros are in +HTML format. Additional, useful documentation is in +PDF format. See the groff(1) man page, section +“Installation Directories”, for their location. +

+
    +
  • toc.html +Entry point to the full mom manual. + +
  • macrolist.html +Hyperlinked index of macros with brief descriptions, arranged by +category. + +
  • mom-pdf.pdf +PDF features and usage. +
+ +

The mom macros are in active development between groff releases. +The most recent version, along with up-to-date documentation, is +available at http://www.schaffter.ca/mom/mom-05.html. +

+

The groff_mom(7) man page (type ‘man groff_mom’ at +the command line) contains a partial list of available macros, however +their usage is best understood by consulting the HTML +documentation. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/ms-Body-Text.html b/doc/groff.html.node/ms-Body-Text.html new file mode 100644 index 0000000..f2d370b --- /dev/null +++ b/doc/groff.html.node/ms-Body-Text.html @@ -0,0 +1,70 @@ + + + + + + +ms Body Text (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+
+

4.6.5 Body Text

+ + +

A variety of macros, registers, and strings can be used to structure and +style the body of your document. They organize your text into +paragraphs, headings, footnotes, and inclusions of material such as +tables and figures. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/ms-Document-Control-Settings.html b/doc/groff.html.node/ms-Document-Control-Settings.html new file mode 100644 index 0000000..ef8f2a4 --- /dev/null +++ b/doc/groff.html.node/ms-Document-Control-Settings.html @@ -0,0 +1,524 @@ + + + + + + +ms Document Control Settings (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+
+

4.6.3 Document Control Settings

+ + +

ms exposes many aspects of document layout to user control via +groff requests. To use them, you must understand how to define +registers and strings. +

+
+
Request: .nr reg value
+
+

Set register reg to value. If reg doesn’t exist, GNU +troff creates it. +

+ +
+
Request: .ds name contents
+
+

Set string name to contents. +

+ +

A list of document control registers and strings follows. For any +parameter whose default is unsatisfactory, define its register or string +before calling any ms macro other than RP. +

+ +
+

Margin settings

+ +
+
Register: \n[PO]
+
+

Defines the page offset (i.e., the left margin). +

+

Effective: next page. +

+

Default: Varies by output device and paper format; 1i is used for +typesetters using U.S. letter paper, and zero for terminals. +See Paper Format. +

+ +
+
Register: \n[LL]
+
+

Defines the line length (i.e., the width of the body text). +

+

Effective: next paragraph. +

+

Default: Varies by output device and paper format; 6.5i is used +for typesetters using U.S. letter paper (see Paper Format) and +65n on terminals. +

+ +
+
Register: \n[LT]
+
+

Defines the title line length (i.e., the header and footer width). This +is usually the same as LL, but need not be. +

+

Effective: next paragraph. +

+

Default: Varies by output device and paper format; 6.5i is used +for typesetters using U.S. letter paper (see Paper Format) and +65n on terminals. +

+ +
+
Register: \n[HM]
+
+

Defines the header margin height at the top of the page. +

+

Effective: next page. +

+

Default: 1i. +

+ +
+
Register: \n[FM]
+
+

Defines the footer margin height at the bottom of the page. +

+

Effective: next page. +

+

Default: 1i. +

+ +
+
+

Titles (headers, footers)

+ +
+
String: \*[LH]
+
+

Defines the text displayed in the left header position. +

+

Effective: next header. +

+

Default: empty. +

+ +
+
String: \*[CH]
+
+

Defines the text displayed in the center header position. +

+

Effective: next header. +

+

Default: ‘-\n[%]-’. +

+ +
+
String: \*[RH]
+
+

Defines the text displayed in the right header position. +

+

Effective: next header. +

+

Default: empty. +

+ +
+
String: \*[LF]
+
+

Defines the text displayed in the left footer position. +

+

Effective: next footer. +

+

Default: empty. +

+ +
+
String: \*[CF]
+
+

Defines the text displayed in the center footer position. +

+

Effective: next footer. +

+

Default: empty. +

+ +
+
String: \*[RF]
+
+

Defines the text displayed in the right footer position. +

+

Effective: next footer. +

+

Default: empty. +

+ +
+
+

Text settings

+ +
+
Register: \n[PS]
+
+

Defines the type size of the body text. +

+

Effective: next paragraph. +

+

Default: 10p. +

+ +
+
Register: \n[VS]
+
+

Defines the vertical spacing (type size plus leading). +

+

Effective: next paragraph. +

+

Default: 12p. +

+ +
+
Register: \n[HY]
+
+

Defines the automatic hyphenation mode used with the hy request. +Setting HY to 0 is equivalent to using the nh +request. This is a Tenth Edition Research Unix extension. +

+

Effective: next paragraph. +

+

Default: 6. +

+ +
+
String: \*[FAM]
+
+

Defines the font family used to typeset the document. This is a GNU +extension. +

+

Effective: next paragraph. +

+

Default: defined by the output device; often ‘T’ (see Body Text) +

+ +
+
+

Paragraph settings

+ +
+
Register: \n[PI]
+
+

Defines the indentation amount used by the PP, IP (unless +overridden by an optional argument), XP, and RS macros. +

+

Effective: next paragraph. +

+

Default: 5n. +

+ +
+
Register: \n[PD]
+
+

Defines the space between paragraphs. +

+

Effective: next paragraph. +

+

Default: 0.3v (1v on low-resolution devices). +

+ +
+
Register: \n[QI]
+
+

Defines the indentation amount used on both sides of a paragraph set +with the QP or between the QS and QE macros. +

+

Effective: next paragraph. +

+

Default: 5n. +

+ +
+
Register: \n[PORPHANS]
+
+

Defines the minimum number of initial lines of any paragraph that must +be kept together to avoid isolated lines at the bottom of a page. If a +new paragraph is started close to the bottom of a page, and there is +insufficient space to accommodate PORPHANS lines before an +automatic page break, then a page break is forced before the start of +the paragraph. This is a GNU extension. +

+

Effective: next paragraph. +

+

Default: 1. +

+ +
+
+

Heading settings

+ +
+
Register: \n[PSINCR]
+
+

Defines an increment in type size to be applied to a heading at a +lesser depth than that specified in GROWPS. The value of +PSINCR should be specified in points with the p scaling +unit and may include a fractional component; for example, ‘.nr PSINCR 1.5p’ sets a type size increment of 1.5p. This is a GNU +extension. +

+

Effective: next heading. +

+

Default: 1p. +

+ +
+
Register: \n[GROWPS]
+
+

Defines the heading depth above which the type size increment set by +PSINCR becomes effective. For each heading depth less than the +value of GROWPS, the type size is increased by PSINCR. +Setting GROWPS to any value less than 2 disables the +incremental heading size feature. This is a GNU extension. +

+

Effective: next heading. +

+

Default: 0. +

+ +
+
Register: \n[HORPHANS]
+
+

Defines the minimum number of lines of an immediately succeeding +paragraph that should be kept together with any heading introduced by +the NH or SH macros. If a heading is placed close to the +bottom of a page, and there is insufficient space to accommodate both +the heading and at least HORPHANS lines of the following +paragraph, before an automatic page break, then the page break is forced +before the heading. This is a GNU extension. +

+

Effective: next paragraph. +

+

Default: 1. +

+ +
+
String: \*[SN-STYLE]
+
+

Defines the style used to print numbered headings. See Headings. This is a GNU extension. +

+

Effective: next heading. +

+

Default: alias of SN-DOT +

+ +
+
+

Footnote settings

+ +
+
Register: \n[FI]
+
+

Defines the footnote indentation. This is a Berkeley extension. +

+

Effective: next footnote. +

+

Default: 2n. +

+ +
+
Register: \n[FF]
+
+

Defines the format of automatically numbered footnotes, +and those for which the FS request is given a marker argument, at +the bottom of a column or page. This is a Berkeley extension. +

+
0
+

Set an automatic number8 as a +superscript (on typesetter devices) or surrounded by square brackets (on +terminals). The footnote paragraph is indented as with PP if +there is an FS argument or an automatic number, and as with +LP otherwise. This is the default. +

+
+
1
+

As 0, but set the marker as regular text and follow an +automatic number with a period. +

+
+
2
+

As 1, but without indentation (like LP). +

+
+
3
+

As 1, but set the footnote paragraph with the marker hanging +(like IP). +

+
+ +

Effective: next footnote. +

+

Default: 0. +

+ +
+
Register: \n[FPS]
+
+

Defines the footnote type size. +

+

Effective: next footnote. +

+

Default: \n[PS] - 2p. +

+ +
+
Register: \n[FVS]
+
+

Defines the footnote vertical spacing. +

+

Effective: next footnote. +

+

Default: \n[FPS] + 2p. +

+ +
+
Register: \n[FPD]
+
+

Defines the footnote paragraph spacing. This is a GNU extension. +

+

Effective: next footnote. +

+

Default: \n[PD] / 2. +

+ +
+
String: \*[FR]
+
+

Defines the ratio of the footnote line length to the current line +length. This is a GNU extension. +

+

Effective: next footnote in single-column arrangements, next page +otherwise. +

+

Default: 11/12. +

+ +
+
+

Display settings

+ +
+
Register: \n[DD]
+
+

Sets the display distance—the vertical spacing before and after a +display, a tbl table, an eqn equation, or a pic +image. This is a Berkeley extension. +

+

Effective: next display boundary. +

+

Default: 0.5v (1v on low-resolution devices). +

+ +
+
Register: \n[DI]
+
+

Sets the default amount by which to indent a display started with +DS and ID without arguments, to ‘.DS I’ without +an indentation argument, and to equations set with ‘.EQ I’. +This is a GNU extension. +

+

Effective: next indented display. +

+

Default: 0.5i. +

+ +
+
+

Other settings

+ +
+
Register: \n[MINGW]
+
+

Defines the default minimum width between columns in a multi-column +document. This is a GNU extension. +

+

Effective: next page. +

+

Default: 2n. +

+ +
+
Register: \n[TC-MARGIN]
+
+

Defines the width of the field in which page numbers are set in a table +of contents entry; the right margin thus moves inboard by this amount. +This is a GNU extension. +

+

Effective: next PX call. +

+

Default: \w'000' +

+ + + +
+
+
+
+

+Next: Document Description Macros, Previous: Document Structure, Up: ms   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/ms-Document-Description-Macros.html b/doc/groff.html.node/ms-Document-Description-Macros.html new file mode 100644 index 0000000..4801e47 --- /dev/null +++ b/doc/groff.html.node/ms-Document-Description-Macros.html @@ -0,0 +1,189 @@ + + + + + + +ms Document Description Macros (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+
+

4.6.4 Document Description Macros

+ + + +

Only the simplest document lacks a title.9 As its level of sophistication (or +complexity) increases, it tends to acquire a date of revision, +explicitly identified authors, sponsoring institutions for authors, and, +at the rarefied heights, an abstract of its content. Define these +data by calling the macros below in the order shown; DA or +ND can be called to set the document date (or other identifier) +at any time before (a) the abstract, if present, or (b) its information +is required in a header or footer. Use of these macros is optional, +except that TL is mandatory if any of RP, AU, +AI, or AB is called, and AE is mandatory if +AB is called. +

+
+
Macro: .RP [no-repeat-info] [no-renumber]
+
+

Use the “report” (AT&T: “released paper”) format for your +document, creating a separate cover page. The default arrangement is to +place most of the document description (title, author names and +institutions, and abstract, but not the date) at the top of the first +page. If the optional no-repeat-info argument is given, +ms produces a cover page but does not repeat any of its +information subsequently (but see the DA macro below regarding +the date). Normally, RP sets the page number following the cover +page to 1. Specifying the optional no-renumber argument +suppresses this alteration. Optional arguments can occur in any order. +no is recognized as a synonym of no-repeat-info for +AT&T compatibility. +

+ +
+
Macro: .TL
+
+

Specify the document title. ms collects text on input lines +following this call into the title until reaching AU, AB, +or a heading or paragraphing macro call. +

+ +
+
Macro: .AU
+
+

Specify an author’s name. ms collects text on input lines +following this call into the author’s name until reaching AI, +AB, another AU, or a heading or paragraphing macro call. +Call it repeatedly to specify multiple authors. +

+ +
+
Macro: .AI
+
+

Specify the preceding author’s institution. An AU call is +usefully followed by at most one AI call; if there are more, the +last AI call controls. ms collects text on input lines +following this call into the author’s institution until reaching +AU, AB, or a heading or paragraphing macro call. +

+ +
+
Macro: .DA [x …]
+
+

Typeset the current date, or any arguments x, in the center +footer, and, if RP is also called, left-aligned at the end of the +description information on the cover page. +

+ +
+
Macro: .ND [x …]
+
+

Typeset the current date, or any arguments x, if RP is also +called, left-aligned at the end of the document description on the cover +page. This is groff ms’s default. +

+ +
+
Macro: .AB [no]
+
+

Begin the abstract. ms collects text on input lines following +this call into the abstract until reaching an AE call. By +default, ms places the word “ABSTRACT” centered and in italics +above the text of the abstract. The optional argument no +suppresses this heading. +

+ +
+
Macro: .AE
+
+

End the abstract. +

+ +

An example document description, using a cover page, follows. + + +

+
+
+
.RP
+.TL
+The Inevitability of Code Bloat
+in Commercial and Free Software
+.AU
+J.\& Random Luser
+.AI
+University of West Bumblefuzz
+.AB
+This report examines the long-term growth of the code
+bases in two large,
+popular software packages;
+the free Emacs and the commercial Microsoft Word.
+While differences appear in the type or order of
+features added,
+due to the different methodologies used,
+the results are the same in the end.
+.PP
+The free software approach is shown to be superior in
+that while free software can become as bloated as
+commercial offerings,
+free software tends to have fewer serious bugs and the
+added features are more in line with user demand.
+.AE
+
+…the rest of the paper…
+
+
+ + +
+
+
+

+Next: Body Text, Previous: Document Control Settings, Up: ms   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/ms-Document-Structure.html b/doc/groff.html.node/ms-Document-Structure.html new file mode 100644 index 0000000..de4be0e --- /dev/null +++ b/doc/groff.html.node/ms-Document-Structure.html @@ -0,0 +1,106 @@ + + + + + + +ms Document Structure (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+
+

4.6.2 Document Structure

+ + +

The ms macro package expects a certain amount of structure: +a well-formed document contains at least one paragraphing or heading +macro call. Longer documents have a structure as follows. +

+
+
Document type
+

Calling the RP macro at the beginning of your document puts the +document description (see below) on a cover page. Otherwise, ms +places the information (if any) on the first page, followed immediately +by the body text. Some document types found in other ms +implementations are specific to AT&T or Berkeley, and are not +supported by groff ms. +

+
+
Format and layout
+

By setting registers and strings, you can configure your document’s +typeface, margins, spacing, headers and footers, and footnote +arrangement. See Document Control Settings. +

+
+
Document description
+

A document description consists of any of: a title, one or more authors’ +names and affiliated institutions, an abstract, and a date or other +identifier. See Document Description Macros. +

+
+
Body text
+

The main matter of your document follows its description (if any). +ms supports highly structured text consisting of paragraphs +interspersed with multi-level headings (chapters, sections, subsections, +and so forth) and augmented by lists, footnotes, tables, diagrams, and +similar material. See Body Text. +

+
+
Tables of contents
+

Macros enable the collection of entries for a table of contents (or +index) as the material they discuss appears in the document. You then +call a macro to emit the table of contents at the end of your document. +The table of contents must necessarily follow the rest of the text since +GNU troff is a single-pass formatter; it thus cannot determine +the page number of a division of the text until it has been set and +output. Since ms was designed for the production of hard copy, +the traditional procedure was to manually relocate the pages containing +the table of contents between the cover page and the body text. Today, +page resequencing is more often done in the digital domain. An index +works similarly, but because it typically needs to be sorted after +collection, its preparation requires separate processing. +

+
+ + +
+
+
+

+Next: Document Control Settings, Previous: Introduction, Up: ms   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/ms-Footnotes.html b/doc/groff.html.node/ms-Footnotes.html new file mode 100644 index 0000000..8c5f1f5 --- /dev/null +++ b/doc/groff.html.node/ms-Footnotes.html @@ -0,0 +1,155 @@ + + + + + + +ms Footnotes (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Body Text   [Contents][Index]

+
+
+

4.6.5.10 Footnotes

+ + + + + +

A footnote is typically anchored to a place in the text with a +marker, which is a small integer, a symbol such as a dagger, or +arbitrary user-specified text. +

+
+
String: \*[*]
+
+

Place an automatic number, an automatically generated numeric +footnote marker, in the text. Each time this string is interpolated, +the number it produces increments by one. Automatic numbers start at 1. +This is a Berkeley extension. +

+ +

Enclose the footnote text in FS and FE macro calls to set +it at the nearest available “foot”, or bottom, of a text column or +page. +

+
+
Macro: .FS [marker]
+
+
Macro: .FE
+
+

Begin (FS) and end (FE) a footnote. FS calls +FS-MARK with any supplied marker argument, which is then +also placed at the beginning of the footnote text. If marker is +omitted, the next pending automatic footnote number enqueued by +interpolation of the * string is used, and if none exists, +nothing is prefixed. +

+ +

You may not desire automatically numbered footnotes in spite of their +convenience. You can indicate a footnote with a symbol or other text by +specifying its marker at the appropriate place (for example, by using +\[dg] for the dagger glyph) and as an argument to the +FS macro. Such manual marks should be repeated as arguments to +FS or as part of the footnote text to disambiguate their +correspondence. You may wish to use \*{ and \*} to +superscript the marker at the anchor point, in the footnote text, or +both. +

+

groff ms provides a hook macro, FS-MARK, for +user-determined operations to be performed when the FS macro is +called. It is passed the same arguments as FS itself. An +application of FS-MARK is anchor placement for a hyperlink +reference, so that a footnote can link back to its referential +context.11 By default, this macro has an empty definition. +FS-MARK is a GNU extension. +

+ + + + +

Footnotes can be safely used within keeps and displays, but you should +avoid using automatically numbered footnotes within floating keeps. You +can place a second \** interpolation between a \** and its +corresponding FS call as long as each FS call occurs +after the corresponding \** and occurrences of FS +are in the same order as corresponding occurrences of \**. +

+

Footnote text is formatted as paragraphs are, using analogous +parameters. The registers FI, FPD, FPS, and +FVS correspond to PI, PD, PS, and CS, +respectively; FPD, FPS, and FVS are GNU extensions. +

+

The FF register controls the formatting of automatically numbered +footnote paragraphs and those for which FS is given a marker +argument. See Document Control Settings. +

+

The default footnote line length is 11/12ths of the normal line length +for compatibility with the expectations of historical ms +documents; you may wish to set the FR string to ‘1’ to align +with contemporary typesetting practices. In the +past,12 an FL register +was used for the line length in footnotes; however, setting this +register at document initialization time had no effect on the footnote +line length in multi-column arrangements.13 +

+

FR should be used in preference to the old FL register in +contemporary documents. The footnote line length is effectively +computed as ‘column-width * \*[FR]’. If an absolute +footnote line length is required, recall that arithmetic expressions in +roff input are evaluated strictly from left to right, with no +operator precedence (parentheses are honored). +

+
+
.ds FR 0+3i \" Set footnote line length to 3 inches.
+
+ + +
+
+
+

+Previous: Tables, figures, equations, and references, Up: Body Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/ms-Headers-and-Footers.html b/doc/groff.html.node/ms-Headers-and-Footers.html new file mode 100644 index 0000000..472f19c --- /dev/null +++ b/doc/groff.html.node/ms-Headers-and-Footers.html @@ -0,0 +1,122 @@ + + + + + + +ms Headers and Footers (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Page layout   [Contents][Index]

+
+
+

4.6.6.1 Headers and footers

+ + + + + +

There are multiple ways to produce headers and footers. One is to +define the strings LH, CH, and RH to set the left, +center, and right headers, respectively; and LF, CF, and +RF to set the left, center, and right footers. This approach +suffices for documents that do not distinguish odd- and even-numbered +pages. +

+

Another method is to call macros that set headers or footers for odd- or +even-numbered pages. Each such macro takes a delimited argument +separating the left, center, and right header or footer texts from each +other. You can replace the neutral apostrophes (') shown below +with any character not appearing in the header or footer text. These +macros are Berkeley extensions. +

+
+
Macro: .OH 'left'center'right'
+
+
Macro: .EH 'left'center'right'
+
+
Macro: .OF 'left'center'right'
+
+
Macro: .EF 'left'center'right'
+
+

The OH and EH macros define headers for odd- (recto) +and even-numbered (verso) pages, respectively; the OF and +EF macros define footers for them. +

+ +

With either method, a percent sign % in header or footer text is +replaced by the current page number. By default, ms places no +header on a page numbered “1” (regardless of its number format). +

+
+
Macro: .P1
+
+

Typeset the header even on page 1. To be effective, this macro +must be called before the header trap is sprung on any page numbered +“1”; in practice, unless your page numbering is unusual, this means +that you should call it early, before TL or any heading or +paragraphing macro. This is a Berkeley extension. +

+ +

For even greater flexibility, ms is designed to permit the +redefinition of the macros that are called when the groff traps +that ordinarily cause the headers and footers to be output are sprung. +PT (“page trap”) is called by ms when the header is to +be written, and BT (“bottom trap”) when the footer is to be. +The groff page location trap that ms sets up to format the +header also calls the (normally undefined) HD macro after +PT; you can define HD if you need additional processing +after setting the header (for example, to draw a line below it). +The HD hook is a Berkeley extension. Any such macros you +(re)define must implement any desired specialization for odd-, even-, or +first numbered pages. +

+ +
+
+
+

+Next: Tab stops, Previous: Page layout, Up: Page layout   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/ms-Insertions.html b/doc/groff.html.node/ms-Insertions.html new file mode 100644 index 0000000..bb58a90 --- /dev/null +++ b/doc/groff.html.node/ms-Insertions.html @@ -0,0 +1,181 @@ + + + + + + +ms Insertions (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+
+

4.6.5.9 Tables, figures, equations, and references

+ + + + + + + + + +

The ms package is often used with the tbl, pic, +eqn, and refer preprocessors. + + + + +Mark text meant for preprocessors by enclosing it in pairs of tokens +as follows, with nothing between the dot and the macro name. The +preprocessors match these tokens only at the start of an input line. +

+
+
Macro: .TS [H]
+
+
Macro: .TE
+
+

Demarcate a table to be processed by the tbl preprocessor. The +optional argument H to TS instructs ms to +repeat table rows (often column headings) at the top of each new page +the table spans, if applicable; calling the TH macro marks the +end of such rows. The GNU tbl(1) man page provides a +comprehensive reference to the preprocessor and offers examples of its +use. +

+ +
+
Macro: .PS
+
+
Macro: .PE
+
+
Macro: .PF
+
+

PS begins a picture to be processed by the gpic +preprocessor; either of PE or PF ends it, the latter with +“flyback” to the vertical position at its top. You can create +pic input manually or with a program such as xfig. +

+ +
+
Macro: .EQ [align [label]]
+
+
Macro: .EN
+
+

Demarcate an equation to be processed by the eqn preprocessor. +The equation is centered by default; align can be ‘C’, +‘L’, or ‘I’ to (explicitly) center, left-align, or indent it +by the amount stored in the DI register, respectively. If +specified, label is set right-aligned. +

+ +
+
Macro: .[
+
+
Macro: .]
+
+

Demarcate a bibliographic citation to be processed by the refer +preprocessor. The GNU refer(1) man page provides a +comprehensive reference to the preprocessor and the format of its +bibliographic database. Type ‘man refer’ at the command line to +view it. +

+ +

When refer emits collected references (as might be done on a +“Works Cited” page), it interpolates the REFERENCES string as +an unnumbered heading (SH). +

+ + +

The following is an example of how to set up a table that may print +across two or more pages. +

+
+
+
.TS H
+allbox;
+Cb | Cb .
+Part→Description
+_
+.TH
+.T&
+GH-1978→Fribulating gonkulator
+…the rest of the table follows…
+.TE
+
+
+ +

Attempting to place a multi-page table inside a keep can lead to +unpleasant results, particularly if the tbl allbox option +is used. +

+ +

Mathematics can be typeset using the language of the eqn +preprocessor. +

+
+
+
.EQ C (\*[SN-NO-DOT]a)
+p ~ = ~ q sqrt { ( 1 + ~ ( x / q sup 2 ) }
+.EN
+
+
+ +

This input formats a labelled equation. We used the SN-NO-DOT +string to base the equation label on the current heading number, giving +us more flexibility to reorganize the document. +

+

Use groff options to run preprocessors on the input: +-e for geqn, -p for gpic, +-R for grefer, and -t for gtbl. +

+ +
+
+
+

+Next: Footnotes, Previous: Keeps, boxed keeps, and displays, Up: Body Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/ms-Introduction.html b/doc/groff.html.node/ms-Introduction.html new file mode 100644 index 0000000..4069ac7 --- /dev/null +++ b/doc/groff.html.node/ms-Introduction.html @@ -0,0 +1,60 @@ + + + + + + +ms Introduction (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+
+

4.6.1 Introduction

+ +

The ms macros are the oldest surviving package for roff +systems.7 While the man +package was designed for brief reference documents, the ms macros +are also suitable for longer works intended for printing and possible +publication. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/ms-Legacy-Features.html b/doc/groff.html.node/ms-Legacy-Features.html new file mode 100644 index 0000000..2f24f41 --- /dev/null +++ b/doc/groff.html.node/ms-Legacy-Features.html @@ -0,0 +1,285 @@ + + + + + + +ms Legacy Features (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+
+

4.6.8 Legacy Features

+ + + + + + + +

groff ms retains some legacy features solely to support +formatting of historical documents; contemporary ones should not use +them because they can render poorly. See the groff_char(7) +man page. +

+ +
+

AT&T accent mark strings

+ +

AT&T ms defined accent mark strings as follows. +

+
+
String: \*[']
+
+

Apply acute accent to subsequent glyph. +

+ +
+
String: \*[`]
+
+

Apply grave accent to subsequent glyph. +

+ +
+
String: \*[:]
+
+

Apply dieresis (umlaut) to subsequent glyph. +

+ +
+
String: \*[^]
+
+

Apply circumflex accent to subsequent glyph. +

+ +
+
String: \*[~]
+
+

Apply tilde accent to subsequent glyph. +

+ +
+
String: \*[C]
+
+

Apply caron to subsequent glyph. +

+ +
+
String: \*[,]
+
+

Apply cedilla to subsequent glyph. +

+ +
+
+

Berkeley accent mark and glyph strings

+ +

Berkeley ms offered an AM macro; calling it redefined the +AT&T accent mark strings (except for ‘\*C’), applied them to the +preceding glyph, and defined additional strings, some for spacing +glyphs. +

+
+
Macro: .AM
+
+

Enable alternative accent mark and glyph-producing strings. +

+ +
+
String: \*[']
+
+

Apply acute accent to preceding glyph. +

+ +
+
String: \*[`]
+
+

Apply grave accent to preceding glyph. +

+ +
+
String: \*[:]
+
+

Apply dieresis (umlaut) to preceding glyph. +

+ +
+
String: \*[^]
+
+

Apply circumflex accent to preceding glyph. +

+ +
+
String: \*[~]
+
+

Apply tilde accent to preceding glyph. +

+ +
+
String: \*[,]
+
+

Apply cedilla to preceding glyph. +

+ +
+
String: \*[/]
+
+

Apply stroke (slash) to preceding glyph. +

+ +
+
String: \*[v]
+
+

Apply caron to preceding glyph. +

+ +
+
String: \*[_]
+
+

Apply macron to preceding glyph. +

+ +
+
String: \*[.]
+
+

Apply underdot to preceding glyph. +

+ +
+
String: \*[o]
+
+

Apply ring accent to preceding glyph. +

+ +
+
String: \*[?]
+
+

Interpolate inverted question mark. +

+ +
+
String: \*[!]
+
+

Interpolate inverted exclamation mark. +

+ +
+
String: \*[8]
+
+

Interpolate small letter sharp s. +

+ +
+
String: \*[q]
+
+

Interpolate small letter o with hook accent (ogonek). +

+ +
+
String: \*[3]
+
+

Interpolate small letter yogh. +

+ +
+
String: \*[d-]
+
+

Interpolate small letter eth. +

+ +
+
String: \*[D-]
+
+

Interpolate capital letter eth. +

+ +
+
String: \*[th]
+
+

Interpolate small letter thorn. +

+ +
+
String: \*[Th]
+
+

Interpolate capital letter thorn. +

+ +
+
String: \*[ae]
+
+

Interpolate small æ ligature. +

+ +
+
String: \*[Ae]
+
+

Interpolate capital Æ ligature. +

+ +
+
String: \*[oe]
+
+

Interpolate small oe ligature. +

+ +
+
String: \*[OE]
+
+

Interpolate capital OE ligature. +

+ + +
+
+
+
+

+Next: Naming Conventions, Previous: Differences from AT&T ms, Up: ms   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/ms-Margins.html b/doc/groff.html.node/ms-Margins.html new file mode 100644 index 0000000..f47f698 --- /dev/null +++ b/doc/groff.html.node/ms-Margins.html @@ -0,0 +1,56 @@ + + + + + + +ms Margins (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Page layout   [Contents][Index]

+
+
+

4.6.6.3 Margins

+ + +

Control margins using the registers summarized in “Margin settings” in +Document Control Settings above. There is no setting for the +right margin; the combination of page offset \n[PO] and line +length \n[LL] determines it. +

+ +
+ + + + + diff --git a/doc/groff.html.node/ms-Multiple-Columns.html b/doc/groff.html.node/ms-Multiple-Columns.html new file mode 100644 index 0000000..c95792f --- /dev/null +++ b/doc/groff.html.node/ms-Multiple-Columns.html @@ -0,0 +1,88 @@ + + + + + + +ms Multiple Columns (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Page layout   [Contents][Index]

+
+
+

4.6.6.4 Multiple columns

+ + + +

ms can set text in as many columns as reasonably fit on the page. +The following macros force a page break if a multi-column layout is +active when they are called. The MINGW register stores the +default minimum gutter width; it is a GNU extension. When multiple +columns are in use, keeps and the HORPHANS and PORPHANS +registers work with respect to column breaks instead of page breaks. +

+
+
Macro: .1C
+
+

Arrange page text in a single column (the default). +

+ +
+
Macro: .2C
+
+

Arrange page text in two columns. +

+ +
+
Macro: .MC [column-width [gutter-width]]
+
+

Arrange page text in multiple columns. If you specify no arguments, it +is equivalent to the 2C macro. Otherwise, column-width is +the width of each column and gutter-width is the minimum distance +between columns. +

+ + +
+ + + + + diff --git a/doc/groff.html.node/ms-Naming-Conventions.html b/doc/groff.html.node/ms-Naming-Conventions.html new file mode 100644 index 0000000..db31955 --- /dev/null +++ b/doc/groff.html.node/ms-Naming-Conventions.html @@ -0,0 +1,89 @@ + + + + + + +ms Naming Conventions (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: ms   [Contents][Index]

+
+
+

4.6.9 Naming Conventions

+ + + +

The following conventions are used for names of macros, strings, and +registers. External names available to documents that use the +groff ms macros contain only uppercase letters and digits. +

+

Internally, the macros are divided into modules. Conventions for +identifier names are as follows. +

+
    +
  • Names used only within one module are of the form +module*name. + +
  • Names used outside the module in which they are defined are of the form +module@name. + +
  • Names associated with a particular environment are of the form +environment:name; these are used only within the +par module. + +
  • name does not have a module prefix. + +
  • Constructed names used to implement arrays are of the form +array!index. +
+ +

Thus the groff ms macros reserve the following names. +

+
    +
  • Names containing the characters *, @, and :. + +
  • Names containing only uppercase letters and digits. +
+ + + +
+ + + + + diff --git a/doc/groff.html.node/ms-Page-Layout.html b/doc/groff.html.node/ms-Page-Layout.html new file mode 100644 index 0000000..7bea36d --- /dev/null +++ b/doc/groff.html.node/ms-Page-Layout.html @@ -0,0 +1,64 @@ + + + + + + +ms Page Layout (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: ms   [Contents][Index]

+
+
+

4.6.6 Page layout

+ + + +

ms’s default page layout arranges text in a single column with +the page number between hyphens centered in a header on each page except +the first, and produces no footers. You can customize this arrangement. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/ms-TOC.html b/doc/groff.html.node/ms-TOC.html new file mode 100644 index 0000000..96a2f76 --- /dev/null +++ b/doc/groff.html.node/ms-TOC.html @@ -0,0 +1,242 @@ + + + + + + +ms TOC (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Page layout   [Contents][Index]

+
+
+

4.6.6.5 Creating a table of contents

+ + + +

Because roff formatters process their input in a single pass, +material on page 50, for example, cannot influence what appears on +page 1—this poses a challenge for a table of contents at its +traditional location in front matter, if you wish to avoid manually +maintaining it. ms enables the collection of material to be +presented in the table of contents as it appears, saving its page number +along with it, and then emitting the collected contents on demand toward +the end of the document. The table of contents can then be resequenced +to its desired location by physically rearranging the pages of a printed +document, or as part of post-processing—with a sed(1) +script to reorder the pages in troff’s output, with +pdfjam(1), or with gropdf(1)’s +‘.pdfswitchtopage’ feature, for example. +

+

Define an entry to appear in the table of contents by bracketing its +text between calls to the XS and XE macros. A typical +application is to call them immediately after NH or SH and +repeat the heading text within them. The XA macro, used within +‘.XS’/‘.XE’ pairs, supplements an entry—for instance, when +it requires multiple output lines, whether because a heading is too long +to fit or because style dictates that page numbers not be repeated. You +may wish to indent the text thus wrapped to correspond to its heading +depth; this can be done in the entry text by prefixing it with tabs or +horizontal motion escape sequences, or by providing a second argument to +the XA macro. XS and XA automatically associate +the page number where they are called with the text following them, but +they accept arguments to override this behavior. At the end of the +document, call TC or PX to emit the table of contents; +TC resets the page number to ‘i’ (Roman numeral one), and +then calls PX. All of these macros are Berkeley extensions. +

+
+
Macro: .XS [page-number]
+
+
Macro: .XA [page-number [indentation]]
+
+
Macro: .XE
+
+

Begin, supplement, and end a table of contents entry. Each entry is +associated with page-number (otherwise the current page number); a +page-number of ‘no’ prevents a leader and page number from +being emitted for that entry. Use of XA within +XS/XE is optional; it can be repeated. If +indentation is present, a supplemental entry is indented by that +amount; ens are assumed if no unit is indicated. Text on input lines +between XS and XE is stored for later recall by PX. +

+ +
+
Macro: .PX [no]
+
+

Switch to single-column layout. Unless no is specified, center +and interpolate the TOC string in bold and two points larger than +the body text. Emit the table of contents entries. +

+ +
+
Macro: .TC [no]
+
+

Set the page number to 1, the page number format to lowercase Roman +numerals, and call PX (with a no argument, if present). +

+ +

Here’s an example of typical ms table of contents preparation. +We employ horizontal escape sequences \h to indent the entries by +sectioning depth. +

+
+
+
.NH 1
+Introduction
+.XS
+Introduction
+.XE
+…
+.NH 2
+Methodology
+.XS
+\h'2n'Methodology
+.XA
+\h'4n'Fassbinder's Approach
+\h'4n'Kahiu's Approach
+.XE
+…
+.NH 1
+Findings
+.XS
+Findings
+.XE
+…
+.TC
+
+
+ +

The remaining features in this subsubsection are GNU extensions. +groff ms obviates the need to repeat heading text after +XS calls. Call XN and XH after NH and +SH, respectively. +

+
+
Macro: .XN heading-text
+
+
Macro: .XH depth heading-text
+
+

Format heading-text and create a corresponding table of contents +entry. XN computes the indentation from the depth of the +preceding NH call; XH requires a depth argument to +do so. +

+ +

groff ms encourages customization of table of contents +entry production. +

+
+
Macro: .XN-REPLACEMENT heading-text
+
+
Macro: .XH-REPLACEMENT depth heading-text
+
+

These hook macros implement XN and XH, respectively. +They call XN-INIT and pass their heading-text arguments to +XH-UPDATE-TOC. +

+ +
+
Macro: .XN-INIT
+
+
Macro: .XH-UPDATE-TOC depth heading-text
+
+

The XN-INIT hook macro does nothing by default. +XH-UPDATE-TOC brackets heading-text with XS and +XE calls, indenting it by 2 ens per level of depth beyond +the first. +

+ +

We could therefore produce a table of contents similar to that in the +previous example with fewer macro calls. (The difference is that this +input follows the “Approach” entries with leaders and page numbers.) +

+
+
+
.NH 1
+.XN Introduction
+…
+.NH 2
+.XN Methodology
+.XH 3 "Fassbinder's Approach"
+.XH 3 "Kahiu's Approach"
+…
+.NH 1
+.XN Findings
+…
+
+
+ +

To get the section number of the numbered headings into the table of +contents entries, we might define XN-REPLACEMENT as follows. +(We obtain the heading depth from groff ms’s internal +register nh*hl.) +

+
+
+
.de XN-REPLACEMENT
+.XN-INIT
+.XH-UPDATE-TOC \\n[nh*hl] \\$@
+\&\\*[SN] \\$*
+..
+
+
+ +

You can change the style of the leader that bridges each table of +contents entry with its page number; define the TC-LEADER special +character by using the char request. A typical leader combines +the dot glyph ‘.’ with a horizontal motion escape sequence to +spread the dots. The width of the page number field is stored in the +TC-MARGIN register. +

+ +
+
+
+

+Next: Differences from AT&T ms, Previous: Multiple columns, Up: Page layout   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/ms-basic-information.html b/doc/groff.html.node/ms-basic-information.html new file mode 100644 index 0000000..cc87b0b --- /dev/null +++ b/doc/groff.html.node/ms-basic-information.html @@ -0,0 +1,211 @@ + + + + + + +ms basic information (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Introduction   [Contents][Index]

+
+
+

4.6.1.1 Basic information

+ +

ms documents are plain text files; prepare them with your +preferred text editor. If you’re in a hurry to start, know that +ms needs one of its macros called at the beginning of a document +so that it can initialize. A macro is a formatting instruction to +ms. Put a macro call on a line by itself. Use ‘.PP’ if you +want your paragraph’s first line to be indented, or ‘.LP’ if you +don’t. +

+

After that, start typing normally. It is a good practice to start each +sentence on a new line, or to put two spaces after sentence-ending +punctuation, so that the formatter knows where the sentence boundaries +are. You can separate paragraphs with further paragraphing macros, or +with blank lines, and you can indent with tabs. When you need one of +the features mentioned earlier (see ms), return to this part of the +manual. +

+

Format the document with the groff command. nroff +can be useful for previewing. +

+
+
+
$ editor radical.ms
+$ nroff -ww -z -ms radical.ms # check for errors
+$ nroff -ms radical.ms | less -R
+$ groff -T ps -ms radical.ms > radical.ps
+$ see radical.ps
+
+
+ +

Our radical.ms document might look like this. +

+
+
+
.LP
+Radical novelties are so disturbing that they tend to be
+suppressed or ignored, to the extent that even the
+possibility of their existence in general is more often
+denied than admitted.
+
+→That's what Dijkstra said, anyway.
+
+
+ +

ms exposes many aspects of document layout to user control via +groff’s registers and strings, which store numbers +and text, respectively. Measurements in groff are expressed with +a suffix called a scaling unit. +

+
+
i
+

inches +

+
+
c
+

centimeters +

+
+
p
+

points (1/72 inch) +

+
+
P
+

picas (1/6 inch) +

+
+
v
+

vees; current vertical spacing +

+
+
m
+

ems; width of an “M” in the current font +

+
+
n
+

ens; one-half em +

+
+ +

Set registers with the nr request and strings with the ds +request. Requests are like macro calls; they go on lines by +themselves and start with the control character, a dot (.). +The difference is that they directly instruct the formatter program, +rather than the macro package. We’ll discuss a few as applicable. It +is wise to specify a scaling unit when setting any register that +represents a length, size, or distance. +

+
+
+
.nr PS 10.5p \" Use 10.5-point type.
+.ds FAM P    \" Use Palatino font family.
+
+
+ +

In the foregoing, we see that \" begins a comment. This is an +example of an escape sequence, the other kind of formatting +instruction. Escape sequences can appear anywhere. They begin with the +escape character (\) and are followed by at least one more +character. ms documents +tend to use only a few of groff’s many requests and escape +sequences; see Request Index and Escape Sequence Index or +the groff(7) man page for complete lists. +

+
+
\"
+

Begin comment; ignore remainder of line. +

+
+
\n[reg]
+

Interpolate value of register reg. +

+
+
\*[str]
+

Interpolate contents of string str. +

+
+
\*s
+

abbreviation of \*[s]; the name s must be only one +character +

+
+
\[char]
+

Interpolate glyph of special character named char. +

+
+
\&
+

dummy character +

+
+
\~
+

Insert an unbreakable space that is adjustable like a normal space. +

+
+
\|
+

Move horizontally by one-sixth em (“thin space”). +

+
+ +

Prefix any words that start with a dot ‘.’ or neutral apostrophe +‘'’ with \& if they are at the beginning of an input line +(or might become that way in editing) to prevent them from being +interpreted as macro calls or requests. Suffix ‘.’, ‘?’, and +‘!’ with \& when needed to cancel end-of-sentence detection. +

+
+
+
My exposure was \&.5 to \&.6 Sv of neutrons, said Dr.\&
+Wallace after the criticality incident.
+
+
+ + +
+
+
+

+Next: Document Structure, Previous: Introduction, Up: Introduction   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/ms-keeps-and-displays.html b/doc/groff.html.node/ms-keeps-and-displays.html new file mode 100644 index 0000000..47088aa --- /dev/null +++ b/doc/groff.html.node/ms-keeps-and-displays.html @@ -0,0 +1,207 @@ + + + + + + +ms keeps and displays (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+
+

4.6.5.8 Keeps, boxed keeps, and displays

+ + + + +

On occasion, you may want to keep several lines of text, or a +region of a document, together on a single page, preventing an automatic +page break within certain boundaries. This can cause a page break to +occur earlier than it normally would. For example, you may want to keep +two paragraphs together, or a paragraph that refers to a table, list, or +figure adjacent to the item it discusses. ms provides the +KS and KE macros for this purpose. +

+

You can alternatively specify a floating keep: if a keep cannot +fit on the current page, ms holds its contents and +allows material following the keep (in the source document) to fill the +remainder of the current page. When the page breaks, whether by +reaching the end or bp request, ms puts the floating keep +at the beginning of the next page. This is useful for placing large +graphics or tables that do not need to appear exactly where they occur +in the source document. +

+
+
Macro: .KS
+
+
Macro: .KF
+
+
Macro: .KE
+
+

KS begins a keep, KF a floating keep, and KE ends a +keep of either kind. +

+ +

As an alternative to the keep mechanism, the ne request forces a +page break if there is not at least the amount of vertical space +specified in its argument remaining on the page (see Page Control). +One application of ne is to reserve space on the page for a +figure or illustration to be included later. +

+ +

A boxed keep has a frame drawn around it. +

+
+
Macro: .B1
+
+
Macro: .B2
+
+

B1 begins a keep with a box drawn around it. B2 ends a +boxed keep. +

+ +

Boxed keep macros cause breaks; if you need to box a word or phrase +within a line, see the BX macro in Typeface and decoration. +Box lines are drawn as close as possible to the text they enclose so +that they are usable within paragraphs. If you wish to box one or more +paragraphs, you may improve the appearance by calling B1 after +the first paragraphing macro, and by adding a small amount of vertical +space before calling B2. +

+
+
+
.LP
+.B1
+.I Warning:
+Happy Fun Ball may suddenly accelerate to dangerous
+speeds.
+.sp \n[PD]/2 \" space by half the inter-paragraph distance
+.B2
+
+
+ +

If you want a boxed keep to float, you will need to enclose the +B1 and B2 calls within a pair of KF and KE +calls. +

+ +

Displays turn off filling; lines of verse or program code are +shown with their lines broken as in the source document without +requiring br requests between lines. Displays can be kept on a +single page or allowed to break across pages. The DS macro +begins a kept display of the layout specified in its first argument; +non-kept displays are begun with dedicated macros corresponding to their +layout. +

+
+
Macro: .DS L
+
+
Macro: .LD
+
+

Begin (DS: kept) left-aligned display. +

+ +
+
Macro: .DS [I [indent]]
+
+
Macro: .ID [indent]
+
+

Begin (DS: kept) display indented by indent if specified, +and by the amount of the DI register otherwise. +

+ +
+
Macro: .DS B
+
+
Macro: .BD
+
+

Begin a (DS: kept) a block display: the entire display is +left-aligned, but indented such that the longest line in the display +is centered on the page. +

+ +
+
Macro: .DS C
+
+
Macro: .CD
+
+

Begin a (DS: kept) centered display: each line in the display +is centered. +

+ +
+
Macro: .DS R
+
+
Macro: .RD
+
+

Begin a (DS: kept) right-aligned display. This is a GNU +extension. +

+ +
+
Macro: .DE
+
+

End any display. +

+ +

The distance stored in the DD register is inserted before and +after each pair of display macros; this is a Berkeley extension. In +groff ms, this distance replaces any adjacent +inter-paragraph distance or subsequent spacing prior to a section +heading. The DI register is a GNU extension; its value is an +indentation applied to displays created with ‘.DS’ and ‘.ID’ +without arguments, to ‘.DS I’ without an indentation argument, and +to indented equations set with ‘.EQ’. Changes to either register +take effect at the next display boundary. +

+ +
+
+
+

+Next: Tables, figures, equations, and references, Previous: Indented regions, Up: Body Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/ms-language-and-localization.html b/doc/groff.html.node/ms-language-and-localization.html new file mode 100644 index 0000000..032b4a0 --- /dev/null +++ b/doc/groff.html.node/ms-language-and-localization.html @@ -0,0 +1,135 @@ + + + + + + +ms language and localization (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: Body Text   [Contents][Index]

+
+
+

4.6.5.11 Language and localization

+ + + + + +

groff ms provides several strings that you can customize +for your own purposes, or redefine to adapt the macro package to +languages other than English. It is already localized for +Czech, German, French, Italian, and Swedish. Load the desired +localization macro package after ms; see the +groff_tmac(5) man page. +

+
+
+
$ groff -ms -mfr bienvenue.ms
+
+
+ +

The following strings are available. +

+
+
String: \*[REFERENCES]
+
+

Contains the string printed at the beginning of a references +(bibliography) page produced with GNU refer(1). The default +is ‘References’. +

+ +
+
String: \*[ABSTRACT]
+
+

Contains the string printed at the beginning of the abstract. The +default is ‘\f[I]ABSTRACT\f[]’; it includes font selection escape +sequences to set the word in italics. +

+ +
+
String: \*[TOC]
+
+

Contains the string printed at the beginning of the table of contents. +The default is ‘Table of Contents’. +

+ +
+
String: \*[MONTH1]
+
+
String: \*[MONTH2]
+
+
String: \*[MONTH3]
+
+
String: \*[MONTH4]
+
+
String: \*[MONTH5]
+
+
String: \*[MONTH6]
+
+
String: \*[MONTH7]
+
+
String: \*[MONTH8]
+
+
String: \*[MONTH9]
+
+
String: \*[MONTH10]
+
+
String: \*[MONTH11]
+
+
String: \*[MONTH12]
+
+

Contain the full names of the calendar months. The defaults are in +English: ‘January’, ‘February’, and so on. +

+ + +
+
+
+

+Next: Page layout, Previous: Footnotes, Up: Body Text   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/ms.html b/doc/groff.html.node/ms.html new file mode 100644 index 0000000..aaf7bf1 --- /dev/null +++ b/doc/groff.html.node/ms.html @@ -0,0 +1,75 @@ + + + + + + +ms (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Macro Packages   [Contents][Index]

+
+
+

4.6 ms

+ + +

The ms (“manuscript”) package is suitable for the preparation +of letters, memoranda, reports, and books. These groff +macros feature cover page and table of contents generation, +automatically numbered headings, several paragraph styles, a variety of +text styling options, footnotes, and multi-column page layouts. +ms supports the tbl, eqn, pic, and +refer preprocessors for inclusion of tables, mathematical +equations, diagrams, and standardized bibliographic citations. This +implementation is mostly compatible with the documented interface and +behavior of AT&T Unix Version 7 ms. Many extensions from +4.2BSD (Berkeley) +and Tenth Edition Research Unix have been recreated. +

+ + + +
+ + + + + diff --git a/doc/groff.html.node/troff-and-nroff-Modes.html b/doc/groff.html.node/troff-and-nroff-Modes.html new file mode 100644 index 0000000..257d36e --- /dev/null +++ b/doc/groff.html.node/troff-and-nroff-Modes.html @@ -0,0 +1,114 @@ + + + + + + +troff and nroff Modes (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + + +
+
+

+Next: , Previous: , Up: GNU troff Reference   [Contents][Index]

+
+
+

5.14 troff and nroff Modes

+ + + + + +

Historically, nroff and troff were two separate programs; +the former for terminal output, the latter for typesetters. GNU +troff merges both functions into one executable68 that sends its output to a +device driver (grotty for terminal devices, grops for +PostScript, and so on) which interprets this intermediate output format. +When discussing AT&T troff, it makes sense to talk +about nroff mode and troff mode since the +differences are hard-coded. GNU troff takes information from +device and font description files without handling requests specially if +a terminal output device is used, so such a strong distinction is +unnecessary. +

+

Usually, a macro package can be used with all output devices. +Nevertheless, it is sometimes necessary to make a distinction between +terminal and non-terminal devices: GNU troff provides two +built-in conditions ‘n’ and ‘t’ for the if, ie, +and while requests to decide whether GNU troff shall +behave like nroff or like troff. +

+
+
Request: .troff
+
+ + +

Make the ‘t’ built-in condition true (and the ‘n’ built-in +condition false) for if, ie, and while conditional +requests. This is the default if GNU troff (not +groff) is started with the -R switch to avoid loading of +the startup files troffrc and troffrc-end. Without +-R, GNU troff stays in troff mode if the output +device is not a terminal (e.g., ‘ps’). +

+ +
+
Request: .nroff
+
+ +

Make the ‘n’ built-in condition true (and the ‘t’ built-in +condition false) for if, ie, and while conditional +requests. This is the default if GNU troff uses a terminal +output device; the code for switching to nroff mode is in the +file tty.tmac, which is loaded by the startup file +troffrc. +

+ +

See Conditionals and Loops, for more details on built-in conditions. +

+ + +
+
+
+

+Next: Line Layout, Previous: Character Translations, Up: GNU troff Reference   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.html.node/while.html b/doc/groff.html.node/while.html new file mode 100644 index 0000000..f9a0bae --- /dev/null +++ b/doc/groff.html.node/while.html @@ -0,0 +1,161 @@ + + + + + + +while (The GNU Troff Manual) + + + + + + + + + + + + + + + + + + + +
+
+

+Previous: , Up: Conditionals and Loops   [Contents][Index]

+
+
+

5.23.5 while

+ + +

groff provides a looping construct: the while request. +Its syntax matches the if request. +

+ +
+
Request: .while cond-expr anything
+
+

Evaluate the conditional expression cond-expr, and repeatedly +execute anything unless and until cond-expr evaluates false. +anything, which is often a conditional block, is referred to as +the while request’s body. +

+
+
.nr a 0 1
+.while (\na < 9) \{\
+\n+a,
+.\}
+\n+a
+    ⇒ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
+
+ + +

GNU troff treats the body of a while request similarly to +that of a de request (albeit one not read in copy +mode94), but stores it under an internal name +and deletes it when the loop finishes. The operation of a macro +containing a while request can slow significantly if the +while body is large. Each time the macro is executed, the +while body is parsed and stored again. +

+
+
.de xxx
+.  nr num 10
+.  while (\\n[num] > 0) \{\
+.    \" many lines of code
+.    nr num -1
+.  \}
+..
+
+ + + +

An often better solution—and one that is more portable, since +AT&T troff lacked the while request—is to +instead write a recursive macro. It will be parsed only +once.95 +

+
+
.de yyy
+.  if (\\n[num] > 0) \{\
+.    \" many lines of code
+.    nr num -1
+.    yyy
+.  \}
+..
+.
+.de xxx
+.  nr num 10
+.  yyy
+..
+
+ +

To prevent infinite loops, the default number of available recursion +levels is 1,000 or somewhat less.96 You can +disable this protective measure, or raise the limit, by setting the +slimit register. See Debugging. +

+

As noted above, if a while body begins with a conditional block, +its closing brace must end an input line. +

+
+
.if 1 \{\
+.  nr a 0 1
+.  while (\n[a] < 10) \{\
+.    nop \n+[a]
+.\}\}
+    error→ unbalanced brace escape sequences
+
+
+ +
+
Request: .break
+
+ + + +

Exit a while loop. Do not confuse this request with a +typographical break or the br request. +

+ +
+
Request: .continue
+
+

Skip the remainder of a while loop’s body, immediately starting +the next iteration. +

+ + + +
+
+
+

+Previous: if-else, Up: Conditionals and Loops   [Contents][Index]

+
+ + + + + diff --git a/doc/groff.info b/doc/groff.info new file mode 100644 index 0000000..0b36c23 --- /dev/null +++ b/doc/groff.info @@ -0,0 +1,423 @@ +This is groff.info, produced by makeinfo version 7.0.3 from groff.texi. + +This manual documents GNU 'troff' version 1.23.0. + + Copyright © 1994-2023 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document 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, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". +INFO-DIR-SECTION Typesetting +START-INFO-DIR-ENTRY +* Groff: (groff). The GNU roff document formatting system. +END-INFO-DIR-ENTRY + + +Indirect: +groff.info-1: 723 +groff.info-2: 303755 +groff.info-3: 616581 + +Tag Table: +(Indirect) +Node: Top723 +Node: Introduction1683 +Node: Background2155 +Node: What Is groff?3968 +Node: groff Capabilities4894 +Node: Macro Package Intro6241 +Node: Preprocessor Intro6920 +Node: Preprocessor Intro-Footnotes8331 +Ref: Preprocessor Intro-Footnote-18413 +Node: Output Device Intro8492 +Node: Installation9120 +Node: Conventions Used in This Manual9504 +Node: Conventions Used in This Manual-Footnotes12548 +Ref: Conventions Used in This Manual-Footnote-112656 +Ref: Conventions Used in This Manual-Footnote-212844 +Node: Credits12873 +Node: Invoking groff13398 +Node: Invoking groff-Footnotes14739 +Ref: Invoking groff-Footnote-114813 +Node: Groff Options14866 +Node: Environment27526 +Node: Macro Directories30791 +Node: Macro Directories-Footnotes32254 +Ref: Macro Directories-Footnote-132334 +Node: Font Directories32407 +Node: Paper Format34380 +Node: Invocation Examples35840 +Node: Tutorial for Macro Users37422 +Node: Basics38129 +Node: Basics-Footnotes44199 +Ref: Basics-Footnote-144257 +Node: Common Features44415 +Node: Paragraphs45648 +Node: Sections and Chapters47257 +Node: Headers and Footers47761 +Node: Page Layout Adjustment48487 +Node: Displays and Keeps48979 +Node: Footnotes and Endnotes50257 +Node: Table of Contents50860 +Node: Indexing51812 +Node: Document Formats52253 +Node: Columnation52749 +Node: Font and Size Changes53032 +Node: Predefined Text53542 +Node: Preprocessor Support53852 +Node: Configuration and Customization54295 +Node: Major Macro Packages54667 +Node: man55737 +Node: Optional man extensions56224 +Node: mdoc60222 +Node: me60495 +Node: mm61061 +Node: mom61398 +Node: ms62297 +Node: ms Introduction63317 +Node: ms Introduction-Footnotes63762 +Ref: ms Introduction-Footnote-163838 +Node: ms basic information64073 +Node: ms Document Structure67998 +Node: ms Document Control Settings70473 +Node: ms Document Control Settings-Footnotes79653 +Ref: ms Document Control Settings-Footnote-179755 +Node: ms Document Description Macros79795 +Node: ms Document Description Macros-Footnotes84030 +Ref: ms Document Description Macros-Footnote-184136 +Node: ms Body Text84257 +Node: Text settings in ms84898 +Node: Typographical symbols in ms86081 +Node: Paragraphs in ms86721 +Node: Headings in ms89617 +Node: Typeface and decoration94721 +Node: Typeface and decoration-Footnotes98631 +Ref: Typeface and decoration-Footnote-198723 +Node: Lists in ms99063 +Node: Indented regions in ms102246 +Node: ms keeps and displays103228 +Node: ms Insertions107422 +Node: ms Footnotes110390 +Node: ms Footnotes-Footnotes114176 +Ref: ms Footnotes-Footnote-1114246 +Ref: ms Footnotes-Footnote-2114371 +Ref: ms Footnotes-Footnote-3114462 +Node: ms language and localization114532 +Node: ms Page Layout116058 +Node: ms Headers and Footers116520 +Node: Tab Stops in ms119000 +Node: ms Margins119381 +Node: ms Multiple Columns119765 +Node: ms TOC120726 +Node: Differences from AT&T ms126332 +Node: Differences from AT&T ms-Footnotes131038 +Ref: Differences from AT&T ms-Footnote-1131132 +Ref: Differences from AT&T ms-Footnote-2131258 +Ref: Differences from AT&T ms-Footnote-3131348 +Node: Missing Unix Version 7 ms Macros131620 +Node: Missing Unix Version 7 ms Macros-Footnotes132934 +Ref: Missing Unix Version 7 ms Macros-Footnote-1133044 +Node: ms Legacy Features133212 +Node: ms Naming Conventions135940 +Node: GNU troff Reference136988 +Node: Text138082 +Node: Filling139361 +Node: Filling-Footnotes140444 +Ref: Filling-Footnote-1140504 +Ref: Filling-Footnote-2140555 +Node: Sentences140825 +Node: Sentences-Footnotes145108 +Ref: Sentences-Footnote-1145172 +Ref: Sentences-Footnote-2145389 +Ref: Sentences-Footnote-3145651 +Node: Hyphenation145830 +Node: Breaking146782 +Node: Breaking-Footnotes149367 +Ref: Breaking-Footnote-1149429 +Node: Adjustment149494 +Node: Tabs and Leaders149985 +Node: Tabs and Leaders-Footnotes151169 +Ref: Tabs and Leaders-Footnote-1151247 +Node: Requests and Macros151362 +Node: Requests and Macros-Footnotes157082 +Ref: Requests and Macros-Footnote-1157166 +Ref: Requests and Macros-Footnote-2157277 +Ref: Requests and Macros-Footnote-3157378 +Ref: Requests and Macros-Footnote-4157439 +Node: Macro Packages157508 +Node: Macro Packages-Footnotes158336 +Ref: Macro Packages-Footnote-1158410 +Node: Input Encodings158492 +Node: Input Encodings-Footnotes161415 +Ref: Input Encodings-Footnote-1161491 +Ref: Input Encodings-Footnote-2161688 +Node: Input Conventions161863 +Node: Input Conventions-Footnotes166824 +Ref: Input Conventions-Footnote-1166904 +Node: Page Geometry166958 +Node: Page Geometry-Footnotes170630 +Ref: Page Geometry-Footnote-1170702 +Ref: Page Geometry-Footnote-2170762 +Node: Measurements170831 +Node: Motion Quanta172770 +Node: Default Units173707 +Node: Numeric Expressions175213 +Node: Numeric Expressions-Footnotes183975 +Ref: Numeric Expressions-Footnote-1184059 +Ref: Numeric Expressions-Footnote-2184152 +Ref: Numeric Expressions-Footnote-3184251 +Ref: Numeric Expressions-Footnote-4184291 +Ref: Numeric Expressions-Footnote-5184513 +Node: Identifiers184541 +Node: Identifiers-Footnotes189589 +Ref: Identifiers-Footnote-1189657 +Ref: Identifiers-Footnote-2190254 +Node: Formatter Instructions190373 +Node: Control Characters191643 +Node: Control Characters-Footnotes193934 +Ref: Control Characters-Footnote-1194016 +Node: Invoking Requests194052 +Node: Invoking Requests-Footnotes196161 +Ref: Invoking Requests-Footnote-1196241 +Node: Calling Macros196411 +Node: Calling Macros-Footnotes200319 +Ref: Calling Macros-Footnote-1200393 +Ref: Calling Macros-Footnote-2200457 +Node: Using Escape Sequences200630 +Node: Using Escape Sequences-Footnotes205504 +Ref: Using Escape Sequences-Footnote-1205594 +Ref: Using Escape Sequences-Footnote-2205696 +Node: Delimiters205736 +Node: Comments208561 +Node: Comments-Footnotes211181 +Ref: Comments-Footnote-1211243 +Ref: Comments-Footnote-2211305 +Ref: Comments-Footnote-3211341 +Node: Registers211504 +Node: Setting Registers212084 +Node: Interpolating Registers216559 +Node: Auto-increment217536 +Node: Auto-increment-Footnotes219451 +Ref: Auto-increment-Footnote-1219525 +Node: Assigning Register Formats219598 +Node: Built-in Registers223328 +Node: Built-in Registers-Footnotes227032 +Ref: Built-in Registers-Footnote-1227114 +Node: Manipulating Filling and Adjustment227198 +Node: Manipulating Filling and Adjustment-Footnotes240315 +Ref: Manipulating Filling and Adjustment-Footnote-1240431 +Ref: Manipulating Filling and Adjustment-Footnote-2240479 +Ref: Manipulating Filling and Adjustment-Footnote-3240514 +Node: Manipulating Hyphenation240634 +Node: Manipulating Hyphenation-Footnotes258827 +Ref: Manipulating Hyphenation-Footnote-1258921 +Ref: Manipulating Hyphenation-Footnote-2259086 +Ref: Manipulating Hyphenation-Footnote-3259175 +Ref: Manipulating Hyphenation-Footnote-4259316 +Ref: Manipulating Hyphenation-Footnote-5259639 +Ref: Manipulating Hyphenation-Footnote-6259813 +Node: Manipulating Spacing259881 +Node: Manipulating Spacing-Footnotes265594 +Ref: Manipulating Spacing-Footnote-1265680 +Ref: Manipulating Spacing-Footnote-2265717 +Ref: Manipulating Spacing-Footnote-3265760 +Ref: Manipulating Spacing-Footnote-4265828 +Node: Tabs and Fields265887 +Node: Tabs and Fields-Footnotes272139 +Ref: Tabs and Fields-Footnote-1272215 +Node: Leaders272279 +Node: Leaders-Footnotes274266 +Ref: Leaders-Footnote-1274326 +Node: Fields274486 +Node: Character Translations275876 +Node: troff and nroff Modes279395 +Node: troff and nroff Modes-Footnotes281486 +Ref: troff and nroff Modes-Footnote-1281574 +Node: Line Layout281682 +Node: Line Continuation287718 +Node: Line Continuation-Footnotes290503 +Ref: Line Continuation-Footnote-1290583 +Node: Page Layout290925 +Node: Page Layout-Footnotes294492 +Ref: Page Layout-Footnote-1294560 +Node: Page Control294583 +Node: Page Control-Footnotes299166 +Ref: Page Control-Footnote-1299236 +Node: Using Fonts299264 +Node: Using Fonts-Footnotes302473 +Ref: Using Fonts-Footnote-1302541 +Ref: Using Fonts-Footnote-2302742 +Ref: Using Fonts-Footnote-3302830 +Ref: Using Fonts-Footnote-4302986 +Node: Selecting Fonts303755 +Node: Font Families308177 +Node: Font Families-Footnotes312061 +Ref: Font Families-Footnote-1312133 +Node: Font Positions312167 +Node: Using Symbols315056 +Node: Using Symbols-Footnotes333721 +Ref: Using Symbols-Footnote-1333793 +Ref: Using Symbols-Footnote-2333911 +Ref: Using Symbols-Footnote-3334033 +Ref: Using Symbols-Footnote-4334069 +Node: Character Classes334229 +Node: Special Fonts337008 +Node: Artificial Fonts338195 +Node: Ligatures and Kerning343712 +Node: Italic Corrections347081 +Node: Dummy Characters348505 +Node: Dummy Characters-Footnotes351282 +Ref: Dummy Characters-Footnote-1351360 +Node: Manipulating Type Size and Vertical Spacing351819 +Node: Manipulating Type Size and Vertical Spacing-Footnotes352771 +Ref: Manipulating Type Size and Vertical Spacing-Footnote-1352903 +Ref: Manipulating Type Size and Vertical Spacing-Footnote-2353261 +Node: Changing the Type Size353349 +Node: Changing the Type Size-Footnotes356390 +Ref: Changing the Type Size-Footnote-1356480 +Node: Changing the Vertical Spacing356622 +Node: Using Fractional Type Sizes359239 +Node: Using Fractional Type Sizes-Footnotes362878 +Ref: Using Fractional Type Sizes-Footnote-1362978 +Node: Colors363029 +Node: Colors-Footnotes367195 +Ref: Colors-Footnote-1367253 +Node: Strings367298 +Ref: als375644 +Node: Strings-Footnotes377468 +Ref: Strings-Footnote-1377528 +Node: Conditionals and Loops377555 +Node: Operators in Conditionals378008 +Node: Operators in Conditionals-Footnotes382841 +Ref: Operators in Conditionals-Footnote-1382937 +Ref: Operators in Conditionals-Footnote-2383111 +Ref: Operators in Conditionals-Footnote-3383421 +Ref: Operators in Conditionals-Footnote-4383552 +Ref: Operators in Conditionals-Footnote-5383693 +Node: if-then383766 +Node: if-else385440 +Node: Conditional Blocks386605 +Node: Conditional Blocks-Footnotes389892 +Ref: Conditional Blocks-Footnote-1389974 +Node: while389997 +Node: while-Footnotes392531 +Ref: while-Footnote-1392587 +Ref: while-Footnote-2392614 +Ref: while-Footnote-3392645 +Node: Writing Macros392733 +Node: Writing Macros-Footnotes399609 +Ref: Writing Macros-Footnote-1399683 +Ref: Writing Macros-Footnote-2399710 +Ref: Writing Macros-Footnote-3399915 +Node: Parameters400164 +Node: Parameters-Footnotes404230 +Ref: Parameters-Footnote-1404296 +Node: Copy Mode404707 +Node: Copy Mode-Footnotes410433 +Ref: Copy Mode-Footnote-1410497 +Ref: Copy Mode-Footnote-2410561 +Node: Page Motions410647 +Node: Page Motions-Footnotes420569 +Ref: Page Motions-Footnote-1420639 +Ref: Page Motions-Footnote-2420829 +Node: Drawing Geometric Objects420895 +Node: Drawing Geometric Objects-Footnotes429469 +Ref: Drawing Geometric Objects-Footnote-1429565 +Node: Deferring Output429662 +Node: Traps432701 +Node: Vertical Position Traps433531 +Node: Page Location Traps434625 +Node: Page Location Traps-Footnotes442638 +Ref: Page Location Traps-Footnote-1442722 +Ref: Page Location Traps-Footnote-2442762 +Ref: Page Location Traps-Footnote-3442850 +Node: The Implicit Page Trap443048 +Node: The Implicit Page Trap-Footnotes444309 +Ref: The Implicit Page Trap-Footnote-1444399 +Ref: The Implicit Page Trap-Footnote-2444426 +Node: Diversion Traps444454 +Node: Input Line Traps445241 +Node: Blank Line Traps448690 +Node: Leading Space Traps449222 +Node: End-of-input Traps450106 +Node: End-of-input Traps-Footnotes454067 +Ref: End-of-input Traps-Footnote-1454149 +Ref: End-of-input Traps-Footnote-2454300 +Node: Diversions454402 +Node: Diversions-Footnotes463874 +Ref: Diversions-Footnote-1463940 +Node: Punning Names464008 +Node: Punning Names-Footnotes467295 +Ref: Punning Names-Footnote-1467367 +Node: Environments467421 +Node: Suppressing Output472573 +Node: I/O475340 +Node: Postprocessor Access484470 +Node: Postprocessor Access-Footnotes487454 +Ref: Postprocessor Access-Footnote-1487540 +Ref: Postprocessor Access-Footnote-2487600 +Node: Miscellaneous487776 +Node: Miscellaneous-Footnotes494416 +Ref: Miscellaneous-Footnote-1494488 +Ref: Miscellaneous-Footnote-2494524 +Node: Gtroff Internals494774 +Node: Gtroff Internals-Footnotes499136 +Ref: Gtroff Internals-Footnote-1499214 +Node: Debugging499355 +Node: Warnings506281 +Node: Implementation Differences511010 +Node: Safer Mode511464 +Node: Compatibility Mode511946 +Node: Compatibility Mode-Footnotes517233 +Ref: Compatibility Mode-Footnote-1517315 +Node: Other Differences517696 +Node: Other Differences-Footnotes524092 +Ref: Other Differences-Footnote-1524172 +Ref: Other Differences-Footnote-2524252 +Ref: Other Differences-Footnote-3524429 +Node: File Formats524649 +Node: gtroff Output524960 +Node: gtroff Output-Footnotes526820 +Ref: gtroff Output-Footnote-1526892 +Node: Language Concepts527027 +Node: Separation528140 +Node: Argument Units530374 +Node: Document Parts531511 +Node: Command Reference532909 +Node: Comment Command533325 +Node: Simple Commands533823 +Node: Graphics Commands539265 +Node: Device Control Commands546605 +Node: Obsolete Command550738 +Node: Intermediate Output Examples552015 +Node: Output Language Compatibility554799 +Node: Device and Font Description Files556878 +Node: Device and Font Description Files-Footnotes558261 +Ref: Device and Font Description Files-Footnote-1558373 +Node: DESC File Format558434 +Node: Font Description File Format564511 +Node: Font Description File Format-Footnotes572537 +Ref: Font Description File Format-Footnote-1572639 +Ref: Font Description File Format-Footnote-2572793 +Ref: Font Description File Format-Footnote-3573006 +Ref: Font Description File Format-Footnote-4573115 +Node: Copying This Manual573202 +Node: Request Index598317 +Node: Escape Sequence Index616581 +Node: Operator Index623925 +Node: Register Index625858 +Node: Macro Index640236 +Node: String Index651800 +Node: File Keyword Index659362 +Node: Program and File Index663322 +Node: Concept Index669178 + +End Tag Table + + +Local Variables: +coding: iso-8859-1 +End: diff --git a/doc/groff.info-1 b/doc/groff.info-1 new file mode 100644 index 0000000..e2db4ec --- /dev/null +++ b/doc/groff.info-1 @@ -0,0 +1,7824 @@ +This is groff.info, produced by makeinfo version 7.0.3 from groff.texi. + +This manual documents GNU 'troff' version 1.23.0. + + Copyright © 1994-2023 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document 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, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". +INFO-DIR-SECTION Typesetting +START-INFO-DIR-ENTRY +* Groff: (groff). The GNU roff document formatting system. +END-INFO-DIR-ENTRY + + +File: groff.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +GNU 'troff' +*********** + +* Menu: + +* Introduction:: +* Invoking groff:: +* Tutorial for Macro Users:: +* Major Macro Packages:: +* GNU troff Reference:: +* File Formats:: +* Copying This Manual:: +* Request Index:: +* Escape Sequence Index:: +* Operator Index:: +* Register Index:: +* Macro Index:: +* String Index:: +* File Keyword Index:: +* Program and File Index:: +* Concept Index:: + +This manual documents GNU 'troff' version 1.23.0. + + Copyright © 1994-2023 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document 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, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". + + +File: groff.info, Node: Introduction, Next: Invoking groff, Prev: Top, Up: Top + +1 Introduction +************** + +GNU 'roff' (or 'groff') is a programming system for typesetting +documents. It is highly flexible and has been used extensively for over +thirty years. + +* Menu: + +* Background:: +* What Is groff?:: +* groff Capabilities:: +* Macro Package Intro:: +* Preprocessor Intro:: +* Output Device Intro:: +* Conventions Used in This Manual:: +* Installation:: +* Credits:: + + +File: groff.info, Node: Background, Next: What Is groff?, Prev: Introduction, Up: Introduction + +1.1 Background +============== + +M. Douglas McIlroy, formerly of AT&T Bell Laboratories and present at +the creation of the Unix operating system, offers an authoritative +historical summary. + + The prime reason for Unix was the desire of Ken [Thompson], Dennis + [Ritchie], and Joe Ossanna to have a pleasant environment for + software development. The fig leaf that got the nod from ... + management was that an early use would be to develop a + "stand-alone" word-processing system for use in typing pools and + secretarial offices. Perhaps they had in mind "dedicated", as + distinct from "stand-alone"; that's what eventuated in various + cases, most notably in the legal/patent department and in the AT&T + CEO's office. + + Both those systems were targets of opportunity, not foreseen from + the start. When Unix was up and running on the PDP-11, Joe got + wind of the legal department having installed a commercial word + processor. He went to pitch Unix as an alternative and clinched a + trial by promising to make 'roff' able to number lines by tomorrow + in order to fulfill a patent-office requirement that the commercial + system did not support. + + Modems were installed so legal-department secretaries could try the + Research machine. They liked it and Joe's superb customer service. + Soon the legal department got a system of their own. Joe went on + to create 'nroff' and 'troff'. Document preparation became a + widespread use of Unix, but no stand-alone word-processing system + was ever undertaken. + + A history relating 'groff' to its predecessors 'roff', 'nroff', and +'troff' is available in the 'roff(7)' man page. + + +File: groff.info, Node: What Is groff?, Next: groff Capabilities, Prev: Introduction, Up: Introduction + +1.2 What Is 'groff'? +==================== + +'groff' (GNU 'roff') is a typesetting system that reads plain text input +files that include formatting commands to produce output in PostScript, +PDF, HTML, DVI, or other formats, or for display to a terminal. +Formatting commands can be low-level typesetting primitives, macros from +a supplied package, or user-defined macros. All three approaches can be +combined. + + A reimplementation and extension of the typesetter from AT&T Unix, +'groff' is present on most POSIX systems owing to its long association +with Unix manuals (including man pages). It and its predecessor are +notable for their production of several best-selling software +engineering texts. 'groff' is capable of producing typographically +sophisticated documents while consuming minimal system resources. + + +File: groff.info, Node: groff Capabilities, Next: Macro Package Intro, Prev: What Is groff?, Up: Introduction + +1.3 'groff' Capabilities +======================== + +GNU 'troff' is a typesetting document formatter; it provides a wide +range of low-level text and page operations within the framework of a +programming language. These operations compose to generate footnotes, +tables of contents, mathematical equations, diagrams, multi-column text, +and other elements of typeset works. Here is a survey of formatter +features; all are under precise user control. + + * text filling, breaking, alignment to the left or right margin; + centering + + * adjustment of inter-word space size to justify text, and of + inter-sentence space size to suit local style conventions + + * automatic and manual determination of hyphenation break points + + * pagination + + * selection of any font available to the output device + + * adjustment of type size and vertical spacing (or "leading") + + * configuration of line length and indentation amounts; columnation + + * drawing of geometric primitives (lines, arcs, polygons, circles, + ...) + + * setup of stroke and fill colors (where supported by the output + device) + + * embedding of hyperlinks, images, document metadata, and other + inclusions (where supported by the output device) + + +File: groff.info, Node: Macro Package Intro, Next: Preprocessor Intro, Prev: groff Capabilities, Up: Introduction + +1.4 Macro Packages +================== + +Elemental typesetting functions can be be challenging to use directly +with complex documents. A "macro" facility specifies how certain +routine operations, such as starting paragraphs, or printing headers and +footers, should be performed in terms of those low-level instructions. +Macros can be specific to one document or collected together into a +"macro package" for use by many. Several macro packages available; the +most widely used are provided with 'groff'. They are 'man', 'mdoc', +'me', 'mm', 'mom', and 'ms'. + + +File: groff.info, Node: Preprocessor Intro, Next: Output Device Intro, Prev: Macro Package Intro, Up: Introduction + +1.5 Preprocessors +================= + +An alternative approach to complexity management, particularly when +constructing tables, setting mathematics, or drawing diagrams, lies in +preprocessing. A "preprocessor" employs a domian-specific language to +ease the generation of tables, equations, and so forth in terms that are +convenient for human entry. Each preprocessor reads a document and +translates the parts of it that apply to it into GNU 'troff' input. +Command-line options to 'groff' tell it which preprocessors to use. + + 'groff' provides preprocessors for laying out tables ('gtbl'), +typesetting equations ('geqn'), drawing diagrams ('gpic' and 'ggrn'), +inserting bibliographic references ('grefer'), and drawing chemical +structures ('gchem'). An associated program that is useful when dealing +with preprocessors is 'gsoelim'.(1) (*note Preprocessor +Intro-Footnote-1::) + + 'groff' also supports 'grap', a preprocessor for drawing graphs. A +free implementation of it can be obtained separately. + + Unique to 'groff' is the 'preconv' preprocessor that enables 'groff' +to handle documents in a variety of input encodings. + + Other preprocessors exist, but no free implementations are known. An +example is 'ideal', which draws diagrams using a mathematical constraint +language. + + +File: groff.info, Node: Preprocessor Intro-Footnotes, Up: Preprocessor Intro + + (1) The 'g' prefix is not used on all systems; see *note Invoking +groff::. + + +File: groff.info, Node: Output Device Intro, Next: Installation, Prev: Preprocessor Intro, Up: Introduction + +1.6 Output Devices +================== + +GNU 'troff''s output is in a device-independent page description +language, which is then read by an "output driver" that translates this +language into a file format or byte stream that a piece of (possibly +emulated) hardware understands. 'groff' features output drivers for +PostScript devices, terminal emulators (and other simple typewriter-like +machines), X11 (for previewing), TeX DVI, HP LaserJet 4/PCL5 and Canon +LBP printers (which use CaPSL), HTML, XHTML, and PDF. + + +File: groff.info, Node: Installation, Next: Conventions Used in This Manual, Prev: Output Device Intro, Up: Introduction + +1.7 Installation +================ + +Locate installation instructions in the files 'INSTALL', +'INSTALL.extra', and 'INSTALL.REPO' in the 'groff' source distribution. +Being a GNU project, 'groff' supports the familiar './configure && make' +command sequence. + + +File: groff.info, Node: Conventions Used in This Manual, Next: Credits, Prev: Installation, Up: Introduction + +1.8 Conventions Used in This Manual +=================================== + +We apply the term "groff" to the language documented here, the GNU +implementation of the overall system, the project that develops that +system, and the command of that name. In the first sense, 'groff' is an +extended dialect of the 'roff' language, for which many similar +implementations exist. + + The 'roff' language features several major categories for which many +items are predefined. Presentations of these items feature the form in +which the item is most commonly used on the left, and, aligned to the +right margin, the name of the category in brackets. + + -- Register: \n[example] + The register 'example' is one that that 'groff' _doesn't_ + predefine. You can create it yourself, though; see *note Setting + Registers::. + + To make this document useful as a reference and not merely amiable +bedtime reading, we tend to present these syntax items in exhaustive +detail when they arise. References to topics discussed later in the +text are frequent; skip material you don't understand yet. + + We use Texinfo's "result" (=>) and error-> notations to present +output written to the standard output and standard error streams, +respectively. Diagnostic messages from the GNU 'troff' formatter and +other programs are examples of the latter, but the formatter can also be +directed to write user-specified messages to the standard error stream. +The notation then serves to identify the output stream and does not +necessarily mean that an error has occurred.(1) (*note Conventions Used +in This Manual-Footnote-1::) + + $ echo "Twelve o'clock and" | groff -Tascii | sed '/^$/d' + => Twelve o'clock and + $ echo '.tm all is well.' | groff > /dev/null + error-> all is well. + + Sometimes we use => somewhat abstractly to represent formatted text +that you will need to use a PostScript or PDF viewer program (or a +printer) to observe. While arguably an abuse of notation, we think this +preferable to requiring the reader to understand the syntax of these +page description languages. + + We also present diagnostic messages in an abbreviated form, often +omitting the name of the program issuing them, the input file name, and +line number or other positional information when such data do not serve +to illuminate the topic under discussion. + + Most examples are of 'roff' language input that would be placed in a +text file. Occasionally, we start an example with a '$' character to +indicate a shell prompt, as seen above. + + You are encouraged to try the examples yourself, and to alter them to +better learn 'groff''s behavior. Our examples frequently need to direct +the formatter to set a line length (with '.ll') that will fit within the +page margins of this manual. We mention this so that you know why it is +there before we discuss the 'll' request formally.(2) (*note +Conventions Used in This Manual-Footnote-2::) + + +File: groff.info, Node: Conventions Used in This Manual-Footnotes, Up: Conventions Used in This Manual + + (1) Unix and related operating systems distinguish standard output +and standard error streams _because_ of 'troff': +. + + (2) *Note Line Layout::. + + +File: groff.info, Node: Credits, Prev: Conventions Used in This Manual, Up: Introduction + +1.9 Credits +=========== + +We adapted portions of this manual from existing documents. James +Clark's man pages were an essential resource; we have updated them in +parallel with the development of this manual. We based the tutorial for +macro users on Eric Allman's introduction to his 'me' macro package +(which we also provide, little altered from 4.4BSD). Larry Kollar +contributed much of the material on the 'ms' macro package. + + +File: groff.info, Node: Invoking groff, Next: Tutorial for Macro Users, Prev: Introduction, Up: Top + +2 Invoking 'groff' +****************** + +This chapter focuses on how to invoke the 'groff' front end. This front +end takes care of the details of constructing the pipeline among the +preprocessors, 'gtroff' and the postprocessor. + + It has become a tradition that GNU programs get the prefix 'g' to +distinguish them from their original counterparts provided by the host +(*note Environment::). Thus, for example, 'geqn' is GNU 'eqn'. On +operating systems like GNU/Linux or the Hurd, which don't contain +proprietary versions of 'troff', and on MS-DOS/MS-Windows, where 'troff' +and associated programs are not available at all, this prefix is omitted +since GNU 'troff' is the only incarnation of 'troff' used. Exception: +'groff' is never replaced by 'roff'. + + In this document, we consequently say 'gtroff' when talking about the +GNU 'troff' program. All other implementations of 'troff' are called +AT&T 'troff', which is the common origin of almost all 'troff' +implementations(1) (*note Invoking groff-Footnote-1::) (with more or +less compatible changes). Similarly, we say 'gpic', 'geqn', and so on. + +* Menu: + +* Groff Options:: +* Environment:: +* Macro Directories:: +* Font Directories:: +* Paper Format:: +* Invocation Examples:: + + +File: groff.info, Node: Invoking groff-Footnotes, Up: Invoking groff + + (1) Besides 'groff', 'neatroff' is an exception. + + +File: groff.info, Node: Groff Options, Next: Environment, Prev: Invoking groff, Up: Invoking groff + +2.1 Options +=========== + +'groff' normally runs the 'gtroff' program and a postprocessor +appropriate for the selected device. The default device is 'ps' (but it +can be changed when 'groff' is configured and built). It can optionally +preprocess with any of 'gpic', 'geqn', 'gtbl', 'ggrn', 'grap', 'gchem', +'grefer', 'gsoelim', or 'preconv'. + + This section documents only options to the 'groff' front end. Many +of the arguments to 'groff' are passed on to 'gtroff'; therefore, those +are also included. Arguments to preprocessors and output drivers can be +found in the man pages 'gpic(1)', 'geqn(1)', 'gtbl(1)', 'ggrn(1)', +'grefer(1)', 'gchem(1)', 'gsoelim(1)', 'preconv(1)', 'grotty(1)', +'grops(1)', 'gropdf(1)', 'grohtml(1)', 'grodvi(1)', 'grolj4(1)', +'grolbp(1)', and 'gxditview(1)'. + + The command-line format for 'groff' is: + + groff [ -abceghijklpstvzCEGNRSUVXZ ] [ -dCS ] [ -DARG ] + [ -fFAM ] [ -FDIR ] [ -IDIR ] [ -KARG ] + [ -LARG ] [ -mNAME ] [ -MDIR ] [ -nNUM ] + [ -oLIST ] [ -PARG ] [ -rCN ] [ -TDEV ] + [ -wNAME ] [ -WNAME ] [ FILES... ] + + The command-line format for 'gtroff' is as follows. + + gtroff [ -abcivzCERU ] [ -dCS ] [ -fFAM ] [ -FDIR ] + [ -mNAME ] [ -MDIR ] [ -nNUM ] [ -oLIST ] + [ -rCN ] [ -TNAME ] [ -wNAME ] [ -WNAME ] + [ FILES... ] + +Obviously, many of the options to 'groff' are actually passed on to +'gtroff'. + + Options without an argument can be grouped behind a single '-'. A +filename of '-' denotes the standard input. Whitespace is permitted +between an option and its argument. + + The 'grog' command can be used to guess the correct 'groff' command +to format a file. See its man page 'grog(1)'; type 'man grog' at the +command line to view it. + + 'groff''s command-line options are as follows. + +'-a' + Generate a plain text approximation of the typeset output. The + read-only register '.A' is set to 1. *Note Built-in Registers::. + This option produces a sort of abstract preview of the formatted + output. + + * Page breaks are marked by a phrase in angle brackets; for + example, ''. + + * Lines are broken where they would be in the formatted output. + + * A horizontal motion of any size is represented as one space. + Adjacent horizontal motions are not combined. Inter-sentence + space nodes (those arising from the second argument to the + 'ss' request) are not represented. + + * Vertical motions are not represented. + + * Special characters are rendered in angle brackets; for + example, the default soft hyphen character appears as ''. + + The above description should not be considered a specification; the + details of '-a' output are subject to change. + +'-b' + Write a backtrace reporting the state of 'gtroff''s input parser to + the standard error stream with each diagnostic message. The line + numbers given in the backtrace might not always be correct, because + 'gtroff''s idea of line numbers can be confused by requests that + append to macros. + +'-c' + Start with color output disabled. + +'-C' + Enable AT&T 'troff' compatibility mode; implies '-c'. *Note + Implementation Differences::, for the list of incompatibilities + between 'groff' and AT&T 'troff'. + +'-dCTEXT' +'-dSTRING=TEXT' + Define 'roff' string C or STRING as T or TEXT. C must be one + character; STRING can be of arbitrary length. Such string + assignments happen before any macro file is loaded, including the + startup file. Due to 'getopt_long' limitations, C cannot be, and + STRING cannot contain, an equals sign, even though that is a valid + character in a 'roff' identifier. + +'-DENC' + Set fallback input encoding used by 'preconv' to ENC; implies '-k'. + +'-e' + Run 'geqn' preprocessor. + +'-E' + Inhibit 'gtroff' error messages. This option does _not_ suppress + messages sent to the standard error stream by documents or macro + packages using 'tm' or related requests. + +'-fFAM' + Use FAM as the default font family. *Note Font Families::. + +'-FDIR' + Search in directory 'DIR' for the selected output device's + directory of device and font description files. See the + description of 'GROFF_FONT_PATH' in *note Environment:: below for + the default search locations and ordering. + +'-g' + Run 'ggrn' preprocessor. + +'-G' + Run 'grap' preprocessor; implies '-p'. + +'-h' + Display a usage message and exit. + +'-i' + Read the standard input after all the named input files have been + processed. + +'-IDIR' + Search the directory DIR for files named in several contexts; + implies '-g' and '-s'. + + * 'gsoelim' replaces 'so' requests with the contents of their + file name arguments. + + * 'gtroff' searches for files named as operands in its command + line and as arguments to 'psbb', 'so', and 'soquiet' requests. + + * Output drivers may search for files; for instance, 'grops' + looks for files named in '\X'ps: import ...'', '\X'ps: file + ...'', and '\X'pdf: pdfpic ...'' device control escape + sequences. + + This option may be specified more than once; the directories are + searched in the order specified. If you want to search the current + directory before others, add '-I .' at the desired place. The + current working directory is otherwise searched last. '-I' works + similarly to, and is named for, the "include" option of Unix C + compilers. + + '-I' options are passed to 'gsoelim', 'gtroff', and output drivers; + with the flag letter changed to '-M', they are also passed to + 'ggrn'. + +'-j' + Run 'gchem' preprocessor. Implies '-p'. + +'-k' + Run 'preconv' preprocessor. Refer to its man page for its behavior + if neither of 'groff''s '-K' or '-D' options is also specified. + +'-KENC' + Set input encoding used by 'preconv' to ENC; implies '-k'. + +'-l' + Send the output to a spooler for printing. The 'print' directive + in the device description file specifies the default command to be + used; see *note Device and Font Description Files::. See options + '-L' and '-X'. + +'-LARG' + Pass ARG to the print spooler program. If multiple ARGs are + required, pass each with a separate '-L' option. 'groff' does not + prefix an option dash to ARG before passing it to the spooler + program. + +'-mNAME' + Process the file 'NAME.tmac' prior to any input files. If not + found, 'tmac.NAME' is attempted. NAME (in both arrangements) is + presumed to be a macro file; see the description of + 'GROFF_TMAC_PATH' in *note Environment:: below for the default + search locations and ordering. This option and its argument are + also passed to 'geqn', 'grap', and 'ggrn'. + +'-MDIR' + Search directory 'DIR' for macro files; see the description of + 'GROFF_TMAC_PATH' in *note Environment:: below for the default + search locations and ordering. This option and its argument are + also passed to 'geqn', 'grap', and 'ggrn'. + +'-nNUM' + Number the first page NUM. + +'-N' + Prohibit newlines between 'eqn' delimiters: pass '-N' to 'geqn'. + +'-oLIST' + Output only pages in LIST, which is a comma-separated list of page + ranges; 'N' means page N, 'M-N' means every page between M and N, + '-N' means every page up to N, 'N-' means every page from N on. + 'gtroff' stops processing and exits after formatting the last page + enumerated in LIST. + +'-p' + Run 'gpic' preprocessor. + +'-PARG' + Pass ARG to the postprocessor. If multiple ARGs are required, pass + each with a separate '-P' option. 'groff' does not prefix an + option dash to ARG before passing it to the postprocessor. + +'-rCNUMERIC-EXPRESSION' +'-rREGISTER=EXPR' + Set 'roff' register C or REGISTER to the value NUMERIC-EXPRESSION + (*note Numeric Expressions::). C must be one character; REGISTER + can be of arbitrary length. Such register assignments happen + before any macro file is loaded, including the startup file. Due + to 'getopt_long' limitations, C cannot be, and REGISTER cannot + contain, an equals sign, even though that is a valid character in a + 'roff' identifier. + +'-R' + Run 'grefer' preprocessor. No mechanism is provided for passing + arguments to 'grefer' because most 'grefer' options have equivalent + language elements that can be specified within the document. + + 'gtroff' also accepts a '-R' option, which is not accessible via + 'groff'. This option prevents the loading of the 'troffrc' and + 'troffrc-end' files. + +'-s' + Run 'gsoelim' preprocessor. + +'-S' + Operate in "safer" mode; see '-U' below for its opposite. For + security reasons, safer mode is enabled by default. + +'-t' + Run 'gtbl' preprocessor. + +'-TDEV' + Direct 'gtroff' to format the input for the output device DEV. + 'groff' then calls an output driver to convert 'gtroff''s output to + a form appropriate for DEV. The following output devices are + available. + + 'ps' + For PostScript printers and previewers. + + 'pdf' + For PDF viewers or printers. + + 'dvi' + For TeX DVI format. + + 'X75' + For a 75dpi X11 previewer. + + 'X75-12' + For a 75dpi X11 previewer with a 12-point base font in the + document. + + 'X100' + For a 100dpi X11 previewer. + + 'X100-12' + For a 100dpi X11 previewer with a 12-point base font in the + document. + + 'ascii' + For typewriter-like devices using the (7-bit) ASCII (ISO 646) + character set. + + 'latin1' + For typewriter-like devices that support the Latin-1 + (ISO 8859-1) character set. + + 'utf8' + For typewriter-like devices that use the Unicode (ISO 10646) + character set with UTF-8 encoding. + + 'cp1047' + For typewriter-like devices that use the EBCDIC encoding IBM + code page 1047. + + 'lj4' + For HP LaserJet4-compatible (or other PCL5-compatible) + printers. + + 'lbp' + For Canon CaPSL printers (LBP-4 and LBP-8 series laser + printers). + + 'html' + 'xhtml' + To produce HTML and XHTML output, respectively. This driver + consists of two parts, a preprocessor ('pre-grohtml') and a + postprocessor ('post-grohtml'). + + The predefined GNU 'troff' string '.T' contains the name of the + output device; the read-only register '.T' is set to 1 if this + option is used (which is always true if 'groff' is used to call GNU + 'troff'). *Note Built-in Registers::. + + The postprocessor to be used for a device is specified by the + 'postpro' command in the device description file. (*Note Device + and Font Description Files::.) This can be overridden with the + '-X' option. + +'-U' + Operate in "unsafe mode", which enables the 'open', 'opena', 'pi', + 'pso', and 'sy' requests. These requests are disabled by default + because they allow an untrusted input document to write to + arbitrary file names and run arbitrary commands. This option also + adds the current directory to the macro package search path; see + the '-m' option above. '-U' is passed to 'gpic' and 'gtroff'. + +'-v' + Write version information for 'groff' and all programs run by it to + the standard output stream; that is, the given command line is + processed in the usual way, passing '-v' to the formatter and any + pre- or postprocessors invoked. + +'-V' + Output the pipeline that would be run by 'groff' (as a wrapper + program) to the standard output stream, but do not execute it. If + given more than once, the pipeline is both written to the standard + error stream and run. + +'-wCATEGORY' + Enable warnings in CATEGORY. Categories are listed in *note + Warnings::. + +'-WCATEGORY' + Inhibit warnings in CATEGORY. Categories are listed in *note + Warnings::. + +'-X' + Use 'gxditview' instead of the usual postprocessor to (pre)view a + document on an X11 display. Combining this option with '-Tps' uses + the font metrics of the PostScript device, whereas the '-TX75' and + '-TX100' options use the metrics of X11 fonts. + +'-z' + Suppress formatted output from 'gtroff'. + +'-Z' + Disable postprocessing. 'gtroff' output will appear on the + standard output stream (unless suppressed with '-z'; see *note + gtroff Output:: for a description of this format. + + +File: groff.info, Node: Environment, Next: Macro Directories, Prev: Groff Options, Up: Invoking groff + +2.2 Environment +=============== + +There are also several environment variables (of the operating system, +not within 'gtroff') that can modify the behavior of 'groff'. + +'GROFF_BIN_PATH' + This search path, followed by 'PATH', is used for commands executed + by 'groff'. + +'GROFF_COMMAND_PREFIX' + If this is set to X, then 'groff' runs 'Xtroff' instead of + 'gtroff'. This also applies to 'tbl', 'pic', 'eqn', 'grn', 'chem', + 'refer', and 'soelim'. It does not apply to 'grops', 'grodvi', + 'grotty', 'pre-grohtml', 'post-grohtml', 'preconv', 'grolj4', + 'gropdf', and 'gxditview'. + + The default command prefix is determined during the installation + process. If a non-GNU 'troff' system is found, prefix 'g' is used, + none otherwise. + +'GROFF_ENCODING' + The value of this variable is passed to the 'preconv' + preprocessor's '-e' option to select the character encoding of + input files. This variable's existence implies the 'groff' option + '-k'. If set but empty, 'groff' calls 'preconv' without an '-e' + option. 'groff''s '-K' option overrides 'GROFF_ENCODING'. See the + 'preconv(7)' man page; type 'man preconv' at the command line to + view it. + +'GROFF_FONT_PATH' + A list of directories in which to seek the selected output device's + directory of device and font description files. GNU 'troff' will + search directories given as arguments to any specified '-F' options + before these, and a built-in list of directories after them. *Note + Font Directories:: and the 'troff(1)' or 'gtroff(1)' man pages. + +'GROFF_TMAC_PATH' + A list of directories in which to seek macro files. GNU 'troff' + will search directories given as arguments to any specified '-M' + options before these, and a built-in list of directories after + them. *Note Macro Directories:: and the 'troff(1)' or 'gtroff(1)' + man pages. + +'GROFF_TMPDIR' + The directory in which 'groff' creates temporary files. If this is + not set and 'TMPDIR' is set, temporary files are created in that + directory. Otherwise temporary files are created in a + system-dependent default directory (on Unix and GNU/Linux systems, + this is usually '/tmp'). 'grops', 'grefer', 'pre-grohtml', and + 'post-grohtml' can create temporary files in this directory. + +'GROFF_TYPESETTER' + Sets the default output device. If empty or not set, a build-time + default (often 'ps') is used. The '-TDEV' option overrides + 'GROFF_TYPESETTER'. + +'SOURCE_DATE_EPOCH' + A timestamp (expressed as seconds since the Unix epoch) to use as + the output creation timestamp in place of the current time. The + time is converted to human-readable form using 'localtime(3)' when + the formatter starts up and stored in registers usable by documents + and macro packages (*note Built-in Registers::). + +'TZ' + The time zone to use when converting the current time (or value of + 'SOURCE_DATE_EPOCH') to human-readable form; see 'tzset(3)'. + + MS-DOS and MS-Windows ports of 'groff' use semicolons, rather than +colons, to separate the directories in the lists described above. + + +File: groff.info, Node: Macro Directories, Next: Font Directories, Prev: Environment, Up: Invoking groff + +2.3 Macro Directories +===================== + +A macro file must have a name in the form 'NAME.tmac' or 'tmac.NAME' and +be placed in a "tmac directory" to be found by the '-mNAME' command-line +option.(1) (*note Macro Directories-Footnote-1::) Together, these +directories constitute the "tmac path". Each directory is searched in +the following order until the desired macro file is found or the list is +exhausted. + + * Directories specified with GNU 'troff''s or 'groff''s '-M' + command-line option. + + * Directories listed in the 'GROFF_TMAC_PATH' environment variable. + + * The current working directory (only if in unsafe mode using the + '-U' command-line option). + + * The user's home directory, 'HOME'. + + * A platform-dependent directory, a site-local (platform-independent) + directory, and the main tmac directory. The locations + corresponding to your installation are listed in section + "Environment" of 'gtroff(1)'. If not otherwise configured, they + are as follows. + + /usr/local/lib/groff/site-tmac + /usr/local/share/groff/site-tmac + /usr/local/share/groff/1.23.0/tmac + + The foregoing assumes that the version of 'groff' is 1.23.0, and + that the installation prefix was '/usr/local'. It is possible to + fine-tune these locations during the source configuration process. + + +File: groff.info, Node: Macro Directories-Footnotes, Up: Macro Directories + + (1) The 'mso' request does not have these limitations. *Note I/O::. + + +File: groff.info, Node: Font Directories, Next: Paper Format, Prev: Macro Directories, Up: Invoking groff + +2.4 Font Directories +==================== + +'groff' enforces few restrictions on how font description files are +named. For its family/style mechanism to work (*note Font Families::), +the names of fonts within a family should start with the family name, +followed by the style. For example, the Times family uses 'T' for the +family name and 'R', 'B', 'I', and 'BI' to indicate the styles 'roman', +'bold', 'italic', and 'bold italic', respectively. Thus the final font +names are 'TR', 'TB', 'TI', and 'TBI'. + + Font description files are kept in "font directories", which together +constitute the "font path". The search procedure always appends the +directory 'dev'NAME, where NAME is the name of the output device. +Assuming TeX DVI output, and '/foo/bar' as a font directory, the font +description files for 'grodvi' must be in '/foo/bar/devdvi'. Each +directory in the font path is searched in the following order until the +desired font description file is found or the list is exhausted. + + * Directories specified with GNU 'troff''s or 'groff''s '-f' + command-line option. All output drivers (and some preprocessors) + support this option as well, because they require information about + the glyphs to be rendered in the document. + + * Directories listed in the 'GROFF_FONT_PATH' environment variable. + + * A site-local directory and the main font description directory. + The locations corresponding to your installation are listed in + section "Environment" of 'gtroff(1)'. If not otherwise configured, + they are as follows. + + /usr/local/share/groff/site-font + /usr/local/share/groff/1.23.0/font + + The foregoing assumes that the version of 'groff' is 1.23.0, and + that the installation prefix was '/usr/local'. It is possible to + fine-tune these locations during the source configuration process. + + +File: groff.info, Node: Paper Format, Next: Invocation Examples, Prev: Font Directories, Up: Invoking groff + +2.5 Paper Format +================ + +In 'groff', the page dimensions for the formatter GNU 'troff' and for +output devices are handled separately. *Note Page Layout::, for +vertical manipulation of the page size, and *Note Line Layout::, for +horizontal changes. The 'papersize' macro package, normally loaded by +'troffrc' at startup, provides an interface for configuring page +dimensions by convenient names, like 'letter' or 'a4'; see +'groff_tmac(5)'. The default used by the formatter depends on its build +configuration, but is usually one of the foregoing, as geographically +appropriate. + + It is up to each macro package to respect the page dimensions +configured in this way. + + For each output device, the size of the output medium can be set in +its 'DESC' file. Most output drivers also recognize a command-line +option '-p' to override the default dimensions and an option '-l' to use +landscape orientation. *Note DESC File Format::, for a description of +the 'papersize' keyword, which takes an argument of the same form as +'-p'. The output driver's man page, such as 'grops(1)', may also be +helpful. + + 'groff' uses the command-line option '-P' to pass options to +postprocessors; for example, use the following for PostScript output on +A4 paper in landscape orientation. + + groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps + + +File: groff.info, Node: Invocation Examples, Prev: Paper Format, Up: Invoking groff + +2.6 Invocation Examples +======================= + +'roff' systems are best known for formatting man pages. Once a 'man' +librarian program has located a man page, it may execute a 'groff' +command much like the following. + + groff -t -man -Tutf8 /usr/share/man/man1/groff.1 + + The librarian will also pipe the output through a pager, which might +not interpret the SGR terminal escape sequences 'groff' emits for +boldface, underlining, or italics; see the 'grotty(1)' man page for a +discussion. + + To process a 'roff' input file using the preprocessors 'gtbl' and +'gpic' and the 'me' macro package in the way to which AT&T 'troff' users +were accustomed, one would type (or script) a pipeline. + + gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty + + Using 'groff', this pipe can be shortened to an equivalent command. + + groff -p -t -me -T utf8 foo.me + + An even easier way to do this is to use 'grog' to guess the +preprocessor and macro options and execute the result by using the +command substitution feature of the shell. + + $(grog -Tutf8 foo.me) + + Each command-line option to a postprocessor must be specified with +any required leading dashes '-' because 'groff' passes the arguments +as-is to the postprocessor; this permits arbitrary arguments to be +transmitted. For example, to pass a title to the 'gxditview' +postprocessor, the shell commands + + groff -X -P -title -P 'trial run' mydoc.t + +and + + groff -X -Z mydoc.t | gxditview -title 'trial run' - + +are equivalent. + + +File: groff.info, Node: Tutorial for Macro Users, Next: Major Macro Packages, Prev: Invoking groff, Up: Top + +3 Tutorial for Macro Users +************************** + +Most users of the 'roff' language employ a macro package to format their +documents. Successful macro packages ease the composition process; +their users need not have mastered the full formatting language, nor +understand features like diversions, traps, and environments. This +chapter aims to familiarize you with basic concepts and mechanisms +common to many macro packages (like "displays"). If you prefer a +meticulous and comprehensive presentation, try *note GNU troff +Reference:: instead. + +* Menu: + +* Basics:: +* Common Features:: + + +File: groff.info, Node: Basics, Next: Common Features, Prev: Tutorial for Macro Users, Up: Tutorial for Macro Users + +3.1 Basics +========== + +Let us first survey some basic concepts necessary to use a macro package +fruitfully.(1) (*note Basics-Footnote-1::) References are made +throughout to more detailed information. + + GNU 'troff' reads an input file prepared by the user and outputs a +formatted document suitable for publication or framing. The input +consists of text, or words to be printed, and embedded commands +(requests and escape sequences), which tell GNU 'troff' how to format +the output. *Note Formatter Instructions::. + + The word argument is used in this chapter to mean a word or number +that appears on the same line as a request, and which modifies the +meaning of that request. For example, the request + + .sp + +spaces one line, but + + .sp 4 + +spaces four lines. The number 4 is an argument to the 'sp' request, +which says to space four lines instead of one. Arguments are separated +from the request and from each other by spaces (_not_ tabs). *Note +Invoking Requests::. + + The primary function of GNU 'troff' is to collect words from input +lines, fill output lines with those words, adjust the line to the +right-hand margin by widening spaces, and output the result. For +example, the input: + + Now is the time + for all good men + to come to the aid + of their party. + Four score and seven + years ago, etc. + +is read, packed onto output lines, and justified to produce: + + => Now is the time for all good men to come to the aid of + => their party. Four score and seven years ago, etc. + + Sometimes a new output line should be started even though the current +line is not yet full--for example, at the end of a paragraph. To do +this it is possible to force a break, starting a new output line. Some +requests cause a break automatically, as do (normally) blank input lines +and input lines beginning with a space or tab. + + Not all input lines are text lines--words to be formatted. Some are +control lines that tell a macro package (or GNU 'troff' directly) how to +format the text. Control lines start with a dot ('.') or an apostrophe +(''') as the first character, and can be followed by a macro call. + + The formatter also does more complex things, such as automatically +numbering pages, skipping over page boundaries, putting footnotes in the +correct place, and so forth. + + Here are a few hints for preparing text for input to GNU 'troff'. + + * First, keep the input lines short. Short input lines are easier to + edit, and GNU 'troff' packs words onto longer lines anyhow. + + * In keeping with this, it is helpful to begin a new line after every + comma or phrase, since common corrections are to add or delete + sentences or phrases. + + * End each sentence with two spaces--or better, start each sentence + on a new line. GNU 'troff' recognizes characters that usually end + a sentence, and inserts inter-sentence space accordingly. + + * Do not hyphenate words at the end of lines--GNU 'troff' is smart + enough to hyphenate words as needed, but is not smart enough to + take hyphens out and join a word back together. Also, words such + as "mother-in-law" should not be broken over a line, since then a + space can occur where not wanted, such as "mother- in-law". + + We offer further advice in *note Input Conventions::. + + GNU 'troff' permits alteration of the distance between lines of text. +This is termed vertical spacing and is expressed in the same units as +the type size--the point. The default is 10-point type on 12-point +spacing. To get double-spaced text you would set the vertical spacing +to 24 points. Some, but not all, macro packages expose a macro or +register to configure the vertical spacing. + + A number of requests allow you to change the way the output is +arranged on the page, sometimes called the layout of the output page. +Most macro packages don't supply macros for performing these (at least +not without performing other actions besides), as they are such basic +operations. The macro packages for writing man pages, 'man' and 'mdoc', +don't encourage explicit use of these requests at all. + + The request '.sp N' leaves N lines of blank space. N can be omitted +(skipping a single line) or can be of the form Ni (for N inches) or Nc +(for N centimeters). For example, the input: + + .sp 1.5i + My thoughts on the subject + .sp + +leaves one and a half inches of space, followed by the line "My thoughts +on the subject", followed by a single blank line (more measurement units +are available; see *note Measurements::). + + If you seek precision in spacing, be advised when using a macro +package that it might not honor 'sp' requests as you expect; it can use +a formatter feature called no-space mode to prevent excess space from +accumulating. Macro packages typically offer registers to control +spacing between paragraphs, before section headings, and around displays +(discussed below); use these facilities preferentially. *Note +Manipulating Spacing::. + + Text lines can be centered by using the 'ce' request. The line after +'ce' is centered (horizontally) on the page. To center more than one +line, use '.ce N' (where N is the number of lines to center), followed +by the N lines. To center many lines without counting them, type: + + .ce 1000 + lines to center + .ce 0 + +The '.ce 0' request tells GNU 'troff' to center zero more lines, in +other words, stop centering. + + GNU 'troff' also offers the 'rj' request for right-aligning text. It +works analogously to 'ce' and is convenient for setting epigraphs. + + The 'bp' request starts a new page; this necessarily implies an +ordinary (line) break. + + All of these requests cause a break; that is, they always start a new +line. To start a new line without performing any other action, use +'br'. If you invoke them with the apostrophe ''', the no-break control +character, the (initial) break they normally perform is suppressed. +''br' does nothing. + + +File: groff.info, Node: Basics-Footnotes, Up: Basics + + (1) The remainder of this chapter is based on 'Writing Papers with +nroff using -me' by Eric P. Allman, which is distributed with 'groff' as +'meintro.me'. + + +File: groff.info, Node: Common Features, Prev: Basics, Up: Tutorial for Macro Users + +3.2 Common Features +=================== + +GNU 'troff' provides low-level operations for formatting a document. +Many routine operations are undertaken in nearly all documents that +require a series of such primitive operations to be performed. These +common tasks are grouped into macros, which are then collected into a +macro package. + + Macro packages come in two varieties: "major" or "full-service" ones +that manage page layout, and "minor" or "auxiliary" ones that do not, +instead fulfilling narrow, specific tasks. Find a list in the +'groff_tmac(5)' man page. Type 'man groff_tmac' at the command line to +view it. + + We survey several capabilities of full-service macro package below. +Each package employs its own macros to exercise them. For details, +consult its man page or, for 'ms', see *note ms::. + +* Menu: + +* Paragraphs:: +* Sections and Chapters:: +* Headers and Footers:: +* Page Layout Adjustment:: +* Displays and Keeps:: +* Footnotes and Endnotes:: +* Table of Contents:: +* Indexing:: +* Document Formats:: +* Columnation:: +* Font and Size Changes:: +* Predefined Text:: +* Preprocessor Support:: +* Configuration and Customization:: + + +File: groff.info, Node: Paragraphs, Next: Sections and Chapters, Prev: Common Features, Up: Common Features + +3.2.1 Paragraphs +---------------- + +Paragraphs can be separated and indented in various ways. Some start +with a blank line and have a first-line indentation, like most of the +ones in this manual. Block paragraphs omit the indentation. + + => Some men look at constitutions with sanctimonious + => reverence, and deem them like the ark of the + => covenant, too sacred to be touched. + +We also frequently encounter tagged paragraphs, which begin with a tag +or label at the left margin and indent the remaining text. + + => one This is the first paragraph. Notice how the + => first line of the resulting paragraph lines + => up with the other lines in the paragraph. + +If the tag is too wide for the indentation, the line is broken. + + => longlabel + => The label does not align with the subsequent + => lines, but they align with each other. + +A variation of the tagged paragraph is the itemized or enumerated +paragraph, which might use punctuation or a digit for a tag, +respectively. These are frequently used to construct lists. + + => o This list item starts with a bullet. When + => producing output for a device using the ASCII + => character set, an 'o' is formatted instead. + +Often, use of the same macro without a tag continues such a discussion. + + => -xyz This option is recognized but ignored. + => + => It had a security hole that we don't discuss. + + +File: groff.info, Node: Sections and Chapters, Next: Headers and Footers, Prev: Paragraphs, Up: Common Features + +3.2.2 Sections and Chapters +--------------------------- + +The simplest kind of section heading is unnumbered, set in a bold or +italic style, and occupies a line by itself. Others possess +automatically numbered multi-level headings and/or different typeface +styles or sizes at different levels. More sophisticated macro packages +supply macros for designating chapters and appendices. + + +File: groff.info, Node: Headers and Footers, Next: Page Layout Adjustment, Prev: Sections and Chapters, Up: Common Features + +3.2.3 Headers and Footers +------------------------- + +Headers and footers occupy the top and bottom of each page, +respectively, and contain data like the page number and the article or +chapter title. Their appearance is not affected by the running text. +Some packages allow for different titles on even- and odd-numbered pages +(for printed, bound material). + + Headers and footers are together called titles, and comprise three +parts: left-aligned, centered, and right-aligned. A '%' character +appearing anywhere in a title is automatically replaced by the page +number. *Note Page Layout::. + + +File: groff.info, Node: Page Layout Adjustment, Next: Displays and Keeps, Prev: Headers and Footers, Up: Common Features + +3.2.4 Page Layout +----------------- + +Most macro packages let the user specify the size of the page margins. +The top and bottom margins are typically handled differently than the +left and right margins; the latter two are derived from the page offset, +indentation, and line length. *Note Line Layout::. Commonly, packages +support registers to tune these values. + + +File: groff.info, Node: Displays and Keeps, Next: Footnotes and Endnotes, Prev: Page Layout Adjustment, Up: Common Features + +3.2.5 Displays and Keeps +------------------------ + +Displays are sections of text set off from the surrounding material +(typically paragraphs), often differing in indentation, and/or spacing. +Tables, block quotations, and figures are displayed. Equations and code +examples, when not much shorter than an output line, often are. Lists +may or may not be. Packages for setting man pages support example +displays but not keeps. + + A keep is a group of output lines, often a display, that is formatted +on a single page if possible; it causes a page break to happen early so +as to not interrupt the kept material. + + Floating keeps can move, or "float", relative to the text around them +in the input. They are useful for displays that are captioned and +referred to by name, as with "See figure 3". Depending on the package, +a floating keep appears at the bottom of the current page if it fits, +and at the top of the next otherwise. Alternatively, floating keeps +might be deferred to the end of a section. Using a floating keep can +avoid the large vertical spaces that may precede a tall keep of the +ordinary sort when it won't fit on the page. + + +File: groff.info, Node: Footnotes and Endnotes, Next: Table of Contents, Prev: Displays and Keeps, Up: Common Features + +3.2.6 Footnotes and Endnotes +---------------------------- + +Footnotes and endnotes are forms of delayed formatting. They are +recorded at their points of relevance in the input, but not formatted +there. Instead, a mark cues the reader to check the "foot", or bottom, +of the current page, or in the case of endnotes, an annotation list +later in the document. Macro packages that support these features also +supply a means of automatically numbering either type of annotation. + + +File: groff.info, Node: Table of Contents, Next: Indexing, Prev: Footnotes and Endnotes, Up: Common Features + +3.2.7 Table of Contents +----------------------- + +A package may handle a table of contents by directing section heading +macros to save section heading text and the page number where it occurs +for use in a later entry for a table of contents. It writes the +collected entries at the end of the document, once all are known, upon +request. A row of dots (a leader) bridges the text on the left with its +location on the right. Other collections might work in this manner, +providing lists of figures or tables. + + A table of contents is often found at the end of a GNU 'troff' +document because the formatter processes the document in a single pass. +The 'gropdf' output driver supports a PDF feature that relocates pages +at the time the document is rendered; see the 'gropdf(1)' man page. +Type 'man gropdf' at the command line to view it. + + +File: groff.info, Node: Indexing, Next: Document Formats, Prev: Table of Contents, Up: Common Features + +3.2.8 Indexing +-------------- + +An index is similar to a table of contents, in that entry labels and +locations must be collected, but poses a greater challenge because it +needs to be sorted before it is output. Here, processing the document +in multiple passes is inescapable, and tools like the 'makeindex' +program are necessary. + + +File: groff.info, Node: Document Formats, Next: Columnation, Prev: Indexing, Up: Common Features + +3.2.9 Document Formats +---------------------- + +Some macro packages supply stock configurations of certain documents, +like business letters and memoranda. These often also have provision +for a cover sheet, which may be rigid in its format. With these +features, it is even more important to use the package's macros in +preference to the formatter requests presented earlier, where possible. + + +File: groff.info, Node: Columnation, Next: Font and Size Changes, Prev: Document Formats, Up: Common Features + +3.2.10 Columnation +------------------ + +Macro packages apart from 'man' and 'mdoc' for man page formatting offer +a facility for setting multiple columns on the page. + + +File: groff.info, Node: Font and Size Changes, Next: Predefined Text, Prev: Columnation, Up: Common Features + +3.2.11 Font and Size Changes +---------------------------- + +The formatter's requests and escape sequences for setting the typeface +and size are not always intuitive, so all macro packages provide macros +to make these operations simpler. They also make it more convenient to +change typefaces in the middle of a word and can handle italic +corrections automatically. *Note Italic Corrections::. + + +File: groff.info, Node: Predefined Text, Next: Preprocessor Support, Prev: Font and Size Changes, Up: Common Features + +3.2.12 Predefined Text +---------------------- + +Most macro packages supply predefined strings to set prepared text like +the date, or to perform operations like super- and subscripting. + + +File: groff.info, Node: Preprocessor Support, Next: Configuration and Customization, Prev: Predefined Text, Up: Common Features + +3.2.13 Preprocessor Support +--------------------------- + +All macro packages provide support for various preprocessors and may +extend their functionality by defining macros to set their contents in +displays. Examples include 'TS' and 'TE' for 'gtbl', 'EQ' and 'EN' for +'geqn', and 'PS' and 'PE' for 'gpic'. + + +File: groff.info, Node: Configuration and Customization, Prev: Preprocessor Support, Up: Common Features + +3.2.14 Configuration and Customization +-------------------------------------- + +Packages provide means of customizing many of the details of how the +package behaves. These range from setting the default type size to +changing the appearance of section headers. + + +File: groff.info, Node: Major Macro Packages, Next: GNU troff Reference, Prev: Tutorial for Macro Users, Up: Top + +4 Macro Packages +**************** + +This chapter surveys the "major" macro packages that come with 'groff'. +One, 'ms', is presented in detail. + + Major macro packages are also sometimes described as "full-service" +due to the breadth of features they provide and because more than one +cannot be used by the same document; for example + + groff -m man foo.man -m ms bar.doc + +doesn't work. Option arguments are processed before non-option +arguments; the above (failing) sample is thus reordered to + + groff -m man -m ms foo.man bar.doc + + Many auxiliary, or "minor", macro packages are also available. They +may in general be used with any full-service macro package and handle a +variety of tasks from character encoding selection, to language +localization, to inlining of raster images. See the 'groff_tmac(5)' man +page for a list. Type 'man groff_tmac' at the command line to view it. + +* Menu: + +* man:: +* mdoc:: +* me:: +* mm:: +* mom:: +* ms:: + + +File: groff.info, Node: man, Next: mdoc, Prev: Major Macro Packages, Up: Major Macro Packages + +4.1 'man' +========= + +The 'man' macro package is the most widely used and probably the most +important ever developed for 'troff'. It is easy to use, and a vast +majority of manual pages ("man pages") are written in it. + + 'groff''s implementation is documented in the 'groff_man(7)' man +page. Type 'man groff_man' at the command line to view it. + +* Menu: + +* Optional man extensions:: + + +File: groff.info, Node: Optional man extensions, Up: man + +4.1.1 Optional 'man' extensions +------------------------------- + +Use the file 'man.local' for local extensions to the 'man' macros or for +style changes. + +Custom headers and footers +.......................... + +In 'groff' versions 1.18.2 and later, you can specify custom headers and +footers by redefining the following macros in 'man.local'. + + -- Macro: .PT + Control the content of the headers. Normally, the header prints + the command name and section number on either side, and the + optional fifth argument to 'TH' in the center. + + -- Macro: .BT + Control the content of the footers. Normally, the footer prints + the page number and the third and fourth arguments to 'TH'. + + Use the 'FT' register to specify the footer position. The default + is -0.5i. + +Ultrix-specific man macros +.......................... + +The 'groff' source distribution includes a file named 'man.ultrix', +containing macros compatible with the Ultrix variant of 'man'. Copy +this file into 'man.local' (or use the 'mso' request to load it) to +enable the following macros. + + -- Macro: .CT key + Print ''. + + -- Macro: .CW + Print subsequent text using a "constant-width" (monospaced) + typeface (Courier roman). + + -- Macro: .Ds + Begin a non-filled display. + + -- Macro: .De + End a non-filled display started with 'Ds'. + + -- Macro: .EX [indent] + Begin a non-filled display using a monospaced typeface (Courier + roman). Use the optional INDENT argument to indent the display. + + -- Macro: .EE + End a non-filled display started with 'EX'. + + -- Macro: .G [text] + Set TEXT in Helvetica. If no text is present on the line where the + macro is called, then the text of the next line appears in + Helvetica. + + -- Macro: .GL [text] + Set TEXT in Helvetica oblique. If no text is present on the line + where the macro is called, then the text of the next line appears + in Helvetica Oblique. + + -- Macro: .HB [text] + Set TEXT in Helvetica bold. If no text is present on the line + where the macro is called, then all text up to the next 'HB' + appears in Helvetica bold. + + -- Macro: .TB [text] + Identical to 'HB'. + + -- Macro: .MS title sect [punct] + Set a man page reference in Ultrix format. The TITLE is in Courier + instead of italic. Optional punctuation follows the section number + without an intervening space. + + -- Macro: .NT [C] [title] + Begin a note. Print the optional title, or the word "Note", + centered on the page. Text following the macro makes up the body + of the note, and is indented on both sides. If the first argument + is 'C', the body of the note is printed centered (the second + argument replaces the word "Note" if specified). + + -- Macro: .NE + End a note begun with 'NT'. + + -- Macro: .PN path [punct] + Set the path name in a monospaced typeface (Courier roman), + followed by optional punctuation. + + -- Macro: .Pn [punct] path [punct] + If called with two arguments, identical to 'PN'. If called with + three arguments, set the second argument in a monospaced typeface + (Courier roman), bracketed by the first and third arguments in the + current font. + + -- Macro: .R + Switch to roman font and turn off any underlining in effect. + + -- Macro: .RN + Print the string ''. + + -- Macro: .VS [4] + Start printing a change bar in the margin if the number '4' is + specified. Otherwise, this macro does nothing. + + -- Macro: .VE + End printing the change bar begun by 'VS'. + +Simple example +.............. + +The following example 'man.local' file alters the 'SH' macro to add some +extra vertical space before printing the heading. Headings are printed +in Helvetica bold. + + .\" Make the heading fonts Helvetica + .ds HF HB + . + .\" Put more space in front of headings. + .rn SH SH-orig + .de SH + . if t .sp (u;\\n[PD]*2) + . SH-orig \\$* + .. + + +File: groff.info, Node: mdoc, Next: me, Prev: man, Up: Major Macro Packages + +4.2 'mdoc' +========== + +'groff''s implementation of the BSD 'doc' package for man pages is +documented in the 'groff_mdoc(7)' man page. Type 'man groff_mdoc' at +the command line to view it. + + +File: groff.info, Node: me, Next: mm, Prev: mdoc, Up: Major Macro Packages + +4.3 'me' +======== + +'groff''s implementation of the BSD 'me' macro package is documented +using itself. A tutorial, 'meintro.me', and reference, 'meref.me', are +available in 'groff''s documentation directory. A 'groff_me(7)' man +page is also available and identifies the installation path for these +documents. Type 'man groff_me' at the command line to view it. + + A French translation of the tutorial is available as 'meintro_fr.me' +and installed parallel to the English version. + + +File: groff.info, Node: mm, Next: mom, Prev: me, Up: Major Macro Packages + +4.4 'mm' +======== + +'groff''s implementation of the AT&T memorandum macro package is +documented in the 'groff_mm(7)' man page. Type 'man groff_mm' at the +command line) to view it. + + A Swedish localization of 'mm' is also available; see +'groff_mmse(7)'. + + +File: groff.info, Node: mom, Next: ms, Prev: mm, Up: Major Macro Packages + +4.5 'mom' +========= + +The main documentation files for the 'mom' macros are in HTML format. +Additional, useful documentation is in PDF format. See the 'groff(1)' +man page, section "Installation Directories", for their location. + + * 'toc.html' Entry point to the full mom manual. + + * 'macrolist.html' Hyperlinked index of macros with brief + descriptions, arranged by category. + + * 'mom-pdf.pdf' PDF features and usage. + + The mom macros are in active development between 'groff' releases. +The most recent version, along with up-to-date documentation, is +available at . + + The 'groff_mom(7)' man page (type 'man groff_mom' at the command +line) contains a partial list of available macros, however their usage +is best understood by consulting the HTML documentation. + + +File: groff.info, Node: ms, Prev: mom, Up: Major Macro Packages + +4.6 'ms' +======== + +The 'ms' ("manuscript") package is suitable for the preparation of +letters, memoranda, reports, and books. These 'groff' macros feature +cover page and table of contents generation, automatically numbered +headings, several paragraph styles, a variety of text styling options, +footnotes, and multi-column page layouts. 'ms' supports the 'tbl', +'eqn', 'pic', and 'refer' preprocessors for inclusion of tables, +mathematical equations, diagrams, and standardized bibliographic +citations. This implementation is mostly compatible with the documented +interface and behavior of AT&T Unix Version 7 'ms'. Many extensions +from 4.2BSD (Berkeley) and Tenth Edition Research Unix have been +recreated. + +* Menu: + +* ms Introduction:: +* ms Document Structure:: +* ms Document Control Settings:: +* ms Document Description Macros:: +* ms Body Text:: +* ms Page Layout:: +* Differences from AT&T ms:: +* ms Legacy Features:: +* ms Naming Conventions:: + + +File: groff.info, Node: ms Introduction, Next: ms Document Structure, Prev: ms, Up: ms + +4.6.1 Introduction +------------------ + +The 'ms' macros are the oldest surviving package for 'roff' systems.(1) +(*note ms Introduction-Footnote-1::) While the 'man' package was +designed for brief reference documents, the 'ms' macros are also +suitable for longer works intended for printing and possible +publication. + +* Menu: + +* ms basic information:: + + +File: groff.info, Node: ms Introduction-Footnotes, Up: ms Introduction + + (1) While manual _pages_ are older, early ones used macros supplanted +by the 'man' package of Seventh Edition Unix (1979). 'ms' shipped with +Sixth Edition (1975) and was documented by Mike Lesk in a Bell Labs +internal memorandum. + + +File: groff.info, Node: ms basic information, Next: ms Document Structure, Prev: ms Introduction, Up: ms Introduction + +4.6.1.1 Basic information +......................... + +'ms' documents are plain text files; prepare them with your preferred +text editor. If you're in a hurry to start, know that 'ms' needs one of +its macros called at the beginning of a document so that it can +initialize. A "macro" is a formatting instruction to 'ms'. Put a macro +call on a line by itself. Use '.PP' if you want your paragraph's first +line to be indented, or '.LP' if you don't. + + After that, start typing normally. It is a good practice to start +each sentence on a new line, or to put two spaces after sentence-ending +punctuation, so that the formatter knows where the sentence boundaries +are. You can separate paragraphs with further paragraphing macros, or +with blank lines, and you can indent with tabs. When you need one of +the features mentioned earlier (*note ms::), return to this part of the +manual. + + Format the document with the 'groff' command. 'nroff' can be useful +for previewing. + + $ editor radical.ms + $ nroff -ww -z -ms radical.ms # check for errors + $ nroff -ms radical.ms | less -R + $ groff -T ps -ms radical.ms > radical.ps + $ see radical.ps + + Our 'radical.ms' document might look like this. + + .LP + Radical novelties are so disturbing that they tend to be + suppressed or ignored, to the extent that even the + possibility of their existence in general is more often + denied than admitted. + + ->That's what Dijkstra said, anyway. + + 'ms' exposes many aspects of document layout to user control via +'groff''s "registers" and "strings", which store numbers and text, +respectively. Measurements in 'groff' are expressed with a suffix +called a "scaling unit". + +'i' + inches + +'c' + centimeters + +'p' + points (1/72 inch) + +'P' + picas (1/6 inch) + +'v' + vees; current vertical spacing + +'m' + ems; width of an "M" in the current font + +'n' + ens; one-half em + + Set registers with the 'nr' request and strings with the 'ds' +request. "Requests" are like macro calls; they go on lines by +themselves and start with the "control character", a dot ('.'). The +difference is that they directly instruct the formatter program, rather +than the macro package. We'll discuss a few as applicable. It is wise +to specify a scaling unit when setting any register that represents a +length, size, or distance. + + .nr PS 10.5p \" Use 10.5-point type. + .ds FAM P \" Use Palatino font family. + +In the foregoing, we see that '\"' begins a comment. This is an example +of an "escape sequence", the other kind of formatting instruction. +Escape sequences can appear anywhere. They begin with the escape +character ('\') and are followed by at least one more character. 'ms' +documents tend to use only a few of 'groff''s many requests and escape +sequences; see *note Request Index:: and *note Escape Sequence Index:: +or the 'groff(7)' man page for complete lists. + +'\"' + Begin comment; ignore remainder of line. + +'\n[REG]' + Interpolate value of register REG. + +'\*[STR]' + Interpolate contents of string STR. + +'\*S' + abbreviation of '\*[S]'; the name S must be only one character + +'\[CHAR]' + Interpolate glyph of special character named CHAR. + +'\&' + dummy character + +'\~' + Insert an unbreakable space that is adjustable like a normal space. + +'\|' + Move horizontally by one-sixth em ("thin space"). + + Prefix any words that start with a dot '.' or neutral apostrophe ''' +with '\&' if they are at the beginning of an input line (or might become +that way in editing) to prevent them from being interpreted as macro +calls or requests. Suffix '.', '?', and '!' with '\&' when needed to +cancel end-of-sentence detection. + + My exposure was \&.5 to \&.6 Sv of neutrons, said Dr.\& + Wallace after the criticality incident. + + +File: groff.info, Node: ms Document Structure, Next: ms Document Control Settings, Prev: ms Introduction, Up: ms + +4.6.2 Document Structure +------------------------ + +The 'ms' macro package expects a certain amount of structure: a +well-formed document contains at least one paragraphing or heading macro +call. Longer documents have a structure as follows. + +*Document type* + Calling the 'RP' macro at the beginning of your document puts the + document description (see below) on a cover page. Otherwise, 'ms' + places the information (if any) on the first page, followed + immediately by the body text. Some document types found in other + 'ms' implementations are specific to AT&T or Berkeley, and are not + supported by 'groff' 'ms'. + +*Format and layout* + By setting registers and strings, you can configure your document's + typeface, margins, spacing, headers and footers, and footnote + arrangement. *Note ms Document Control Settings::. + +*Document description* + A document description consists of any of: a title, one or more + authors' names and affiliated institutions, an abstract, and a date + or other identifier. *Note ms Document Description Macros::. + +*Body text* + The main matter of your document follows its description (if any). + 'ms' supports highly structured text consisting of paragraphs + interspersed with multi-level headings (chapters, sections, + subsections, and so forth) and augmented by lists, footnotes, + tables, diagrams, and similar material. *Note ms Body Text::. + +*Tables of contents* + Macros enable the collection of entries for a table of contents (or + index) as the material they discuss appears in the document. You + then call a macro to emit the table of contents at the end of your + document. The table of contents must necessarily follow the rest + of the text since GNU 'troff' is a single-pass formatter; it thus + cannot determine the page number of a division of the text until it + has been set and output. Since 'ms' was designed for the + production of hard copy, the traditional procedure was to manually + relocate the pages containing the table of contents between the + cover page and the body text. Today, page resequencing is more + often done in the digital domain. An index works similarly, but + because it typically needs to be sorted after collection, its + preparation requires separate processing. + + +File: groff.info, Node: ms Document Control Settings, Next: ms Document Description Macros, Prev: ms Document Structure, Up: ms + +4.6.3 Document Control Settings +------------------------------- + +'ms' exposes many aspects of document layout to user control via 'groff' +requests. To use them, you must understand how to define registers and +strings. + + -- Request: .nr reg value + Set register REG to VALUE. If REG doesn't exist, GNU 'troff' + creates it. + + -- Request: .ds name contents + Set string NAME to CONTENTS. + + A list of document control registers and strings follows. For any +parameter whose default is unsatisfactory, define its register or string +before calling any 'ms' macro other than 'RP'. + +Margin settings +............... + + -- Register: \n[PO] + Defines the page offset (i.e., the left margin). + + Effective: next page. + + Default: Varies by output device and paper format; 1i is used for + typesetters using U.S. letter paper, and zero for terminals. *Note + Paper Format::. + + -- Register: \n[LL] + Defines the line length (i.e., the width of the body text). + + Effective: next paragraph. + + Default: Varies by output device and paper format; 6.5i is used for + typesetters using U.S. letter paper (*note Paper Format::) and 65n + on terminals. + + -- Register: \n[LT] + Defines the title line length (i.e., the header and footer width). + This is usually the same as 'LL', but need not be. + + Effective: next paragraph. + + Default: Varies by output device and paper format; 6.5i is used for + typesetters using U.S. letter paper (*note Paper Format::) and 65n + on terminals. + + -- Register: \n[HM] + Defines the header margin height at the top of the page. + + Effective: next page. + + Default: 1i. + + -- Register: \n[FM] + Defines the footer margin height at the bottom of the page. + + Effective: next page. + + Default: 1i. + +Titles (headers, footers) +......................... + + -- String: \*[LH] + Defines the text displayed in the left header position. + + Effective: next header. + + Default: empty. + + -- String: \*[CH] + Defines the text displayed in the center header position. + + Effective: next header. + + Default: '-\n[%]-'. + + -- String: \*[RH] + Defines the text displayed in the right header position. + + Effective: next header. + + Default: empty. + + -- String: \*[LF] + Defines the text displayed in the left footer position. + + Effective: next footer. + + Default: empty. + + -- String: \*[CF] + Defines the text displayed in the center footer position. + + Effective: next footer. + + Default: empty. + + -- String: \*[RF] + Defines the text displayed in the right footer position. + + Effective: next footer. + + Default: empty. + +Text settings +............. + + -- Register: \n[PS] + Defines the type size of the body text. + + Effective: next paragraph. + + Default: 10p. + + -- Register: \n[VS] + Defines the vertical spacing (type size plus leading). + + Effective: next paragraph. + + Default: 12p. + + -- Register: \n[HY] + Defines the automatic hyphenation mode used with the 'hy' request. + Setting 'HY' to 0 is equivalent to using the 'nh' request. This is + a Tenth Edition Research Unix extension. + + Effective: next paragraph. + + Default: 6. + + -- String: \*[FAM] + Defines the font family used to typeset the document. This is a + GNU extension. + + Effective: next paragraph. + + Default: defined by the output device; often 'T' (*note ms Body + Text::) + +Paragraph settings +.................. + + -- Register: \n[PI] + Defines the indentation amount used by the 'PP', 'IP' (unless + overridden by an optional argument), 'XP', and 'RS' macros. + + Effective: next paragraph. + + Default: 5n. + + -- Register: \n[PD] + Defines the space between paragraphs. + + Effective: next paragraph. + + Default: 0.3v (1v on low-resolution devices). + + -- Register: \n[QI] + Defines the indentation amount used on both sides of a paragraph + set with the 'QP' or between the 'QS' and 'QE' macros. + + Effective: next paragraph. + + Default: 5n. + + -- Register: \n[PORPHANS] + Defines the minimum number of initial lines of any paragraph that + must be kept together to avoid isolated lines at the bottom of a + page. If a new paragraph is started close to the bottom of a page, + and there is insufficient space to accommodate 'PORPHANS' lines + before an automatic page break, then a page break is forced before + the start of the paragraph. This is a GNU extension. + + Effective: next paragraph. + + Default: 1. + +Heading settings +................ + + -- Register: \n[PSINCR] + Defines an increment in type size to be applied to a heading at a + lesser depth than that specified in 'GROWPS'. The value of + 'PSINCR' should be specified in points with the p scaling unit and + may include a fractional component; for example, '.nr PSINCR 1.5p' + sets a type size increment of 1.5p. This is a GNU extension. + + Effective: next heading. + + Default: 1p. + + -- Register: \n[GROWPS] + Defines the heading depth above which the type size increment set + by 'PSINCR' becomes effective. For each heading depth less than + the value of 'GROWPS', the type size is increased by 'PSINCR'. + Setting 'GROWPS' to any value less than 2 disables the incremental + heading size feature. This is a GNU extension. + + Effective: next heading. + + Default: 0. + + -- Register: \n[HORPHANS] + Defines the minimum number of lines of an immediately succeeding + paragraph that should be kept together with any heading introduced + by the 'NH' or 'SH' macros. If a heading is placed close to the + bottom of a page, and there is insufficient space to accommodate + both the heading and at least 'HORPHANS' lines of the following + paragraph, before an automatic page break, then the page break is + forced before the heading. This is a GNU extension. + + Effective: next paragraph. + + Default: 1. + + -- String: \*[SN-STYLE] + Defines the style used to print numbered headings. *Note Headings + in ms::. This is a GNU extension. + + Effective: next heading. + + Default: alias of 'SN-DOT' + +Footnote settings +................. + + -- Register: \n[FI] + Defines the footnote indentation. This is a Berkeley extension. + + Effective: next footnote. + + Default: 2n. + + -- Register: \n[FF] + Defines the format of automatically numbered footnotes, and those + for which the 'FS' request is given a marker argument, at the + bottom of a column or page. This is a Berkeley extension. + '0' + Set an automatic number(1) (*note ms Document Control + Settings-Footnote-1::) as a superscript (on typesetter + devices) or surrounded by square brackets (on terminals). The + footnote paragraph is indented as with 'PP' if there is an + 'FS' argument or an automatic number, and as with 'LP' + otherwise. This is the default. + + '1' + As '0', but set the marker as regular text and follow an + automatic number with a period. + + '2' + As '1', but without indentation (like 'LP'). + + '3' + As '1', but set the footnote paragraph with the marker hanging + (like 'IP'). + + Effective: next footnote. + + Default: 0. + + -- Register: \n[FPS] + Defines the footnote type size. + + Effective: next footnote. + + Default: '\n[PS] - 2p'. + + -- Register: \n[FVS] + Defines the footnote vertical spacing. + + Effective: next footnote. + + Default: '\n[FPS] + 2p'. + + -- Register: \n[FPD] + Defines the footnote paragraph spacing. This is a GNU extension. + + Effective: next footnote. + + Default: '\n[PD] / 2'. + + -- String: \*[FR] + Defines the ratio of the footnote line length to the current line + length. This is a GNU extension. + + Effective: next footnote in single-column arrangements, next page + otherwise. + + Default: '11/12'. + +Display settings +................ + + -- Register: \n[DD] + Sets the display distance--the vertical spacing before and after a + display, a 'tbl' table, an 'eqn' equation, or a 'pic' image. This + is a Berkeley extension. + + Effective: next display boundary. + + Default: 0.5v (1v on low-resolution devices). + + -- Register: \n[DI] + Sets the default amount by which to indent a display started with + 'DS' and 'ID' without arguments, to '.DS I' without an indentation + argument, and to equations set with '.EQ I'. This is a GNU + extension. + + Effective: next indented display. + + Default: 0.5i. + +Other settings +.............. + + -- Register: \n[MINGW] + Defines the default minimum width between columns in a multi-column + document. This is a GNU extension. + + Effective: next page. + + Default: 2n. + + -- Register: \n[TC-MARGIN] + Defines the width of the field in which page numbers are set in a + table of contents entry; the right margin thus moves inboard by + this amount. This is a GNU extension. + + Effective: next 'PX' call. + + Default: '\w'000'' + + +File: groff.info, Node: ms Document Control Settings-Footnotes, Up: ms Document Control Settings + + (1) defined in *note ms Footnotes:: + + +File: groff.info, Node: ms Document Description Macros, Next: ms Body Text, Prev: ms Document Control Settings, Up: ms + +4.6.4 Document Description Macros +--------------------------------- + +Only the simplest document lacks a title.(1) (*note ms Document +Description Macros-Footnote-1::) As its level of sophistication (or +complexity) increases, it tends to acquire a date of revision, +explicitly identified authors, sponsoring institutions for authors, and, +at the rarefied heights, an abstract of its content. Define these data +by calling the macros below in the order shown; 'DA' or 'ND' can be +called to set the document date (or other identifier) at any time before +(a) the abstract, if present, or (b) its information is required in a +header or footer. Use of these macros is optional, except that 'TL' is +mandatory if any of 'RP', 'AU', 'AI', or 'AB' is called, and 'AE' is +mandatory if 'AB' is called. + + -- Macro: .RP [no-repeat-info] [no-renumber] + Use the "report" (AT&T: "released paper") format for your document, + creating a separate cover page. The default arrangement is to + place most of the document description (title, author names and + institutions, and abstract, but not the date) at the top of the + first page. If the optional 'no-repeat-info' argument is given, + 'ms' produces a cover page but does not repeat any of its + information subsequently (but see the 'DA' macro below regarding + the date). Normally, 'RP' sets the page number following the cover + page to 1. Specifying the optional 'no-renumber' argument + suppresses this alteration. Optional arguments can occur in any + order. 'no' is recognized as a synonym of 'no-repeat-info' for + 'AT&T' compatibility. + + -- Macro: .TL + Specify the document title. 'ms' collects text on input lines + following this call into the title until reaching 'AU', 'AB', or a + heading or paragraphing macro call. + + -- Macro: .AU + Specify an author's name. 'ms' collects text on input lines + following this call into the author's name until reaching 'AI', + 'AB', another 'AU', or a heading or paragraphing macro call. Call + it repeatedly to specify multiple authors. + + -- Macro: .AI + Specify the preceding author's institution. An 'AU' call is + usefully followed by at most one 'AI' call; if there are more, the + last 'AI' call controls. 'ms' collects text on input lines + following this call into the author's institution until reaching + 'AU', 'AB', or a heading or paragraphing macro call. + + -- Macro: .DA [x ...] + Typeset the current date, or any arguments X, in the center footer, + and, if 'RP' is also called, left-aligned at the end of the + description information on the cover page. + + -- Macro: .ND [x ...] + Typeset the current date, or any arguments X, if 'RP' is also + called, left-aligned at the end of the document description on the + cover page. This is 'groff' 'ms''s default. + + -- Macro: .AB [no] + Begin the abstract. 'ms' collects text on input lines following + this call into the abstract until reaching an 'AE' call. By + default, 'ms' places the word "ABSTRACT" centered and in italics + above the text of the abstract. The optional argument 'no' + suppresses this heading. + + -- Macro: .AE + End the abstract. + + An example document description, using a cover page, follows. + + .RP + .TL + The Inevitability of Code Bloat + in Commercial and Free Software + .AU + J.\& Random Luser + .AI + University of West Bumblefuzz + .AB + This report examines the long-term growth of the code + bases in two large, + popular software packages; + the free Emacs and the commercial Microsoft Word. + While differences appear in the type or order of + features added, + due to the different methodologies used, + the results are the same in the end. + .PP + The free software approach is shown to be superior in + that while free software can become as bloated as + commercial offerings, + free software tends to have fewer serious bugs and the + added features are more in line with user demand. + .AE + + ...the rest of the paper... + + +File: groff.info, Node: ms Document Description Macros-Footnotes, Up: ms Document Description Macros + + (1) Distinguish a document title from "titles", which are what 'roff' +systems call headers and footers collectively. + + +File: groff.info, Node: ms Body Text, Next: ms Page Layout, Prev: ms Document Description Macros, Up: ms + +4.6.5 Body Text +--------------- + +A variety of macros, registers, and strings can be used to structure and +style the body of your document. They organize your text into +paragraphs, headings, footnotes, and inclusions of material such as +tables and figures. + +* Menu: + +* Text settings in ms:: +* Typographical symbols in ms:: +* Paragraphs in ms:: +* Headings in ms:: +* Typeface and decoration:: +* Lists in ms:: +* Indented regions in ms:: +* ms keeps and displays:: +* ms Insertions:: +* ms Footnotes:: +* ms language and localization:: + + +File: groff.info, Node: Text settings in ms, Next: Typographical symbols in ms, Prev: ms Body Text, Up: ms Body Text + +4.6.5.1 Text settings +..................... + +The 'FAM' string, a GNU extension, sets the font family for body text; +the default is 'T'. The 'PS' and 'VS' registers set the type size and +vertical spacing (distance between text baselines), respectively. The +font family and type size are ignored on terminal devices. Setting +these parameters before the first call of a heading, paragraphing, or +(non-date) document description macro also applies them to headers, +footers, and (for 'FAM') footnotes. + + Which font families are available depends on the output device; as a +convention, 'T' selects a serif family ("Times"), 'H' a sans-serif +family ("Helvetica"), and 'C' a monospaced family ("Courier"). The man +page for the output driver documents its font repertoire. Consult the +'groff(1)' man page for lists of available output devices and their +drivers. + + The hyphenation mode (as used by the 'hy' request) is set from the +'HY' register. Setting 'HY' to '0' is equivalent to using the 'nh' +request. This is a Tenth Edition Research Unix extension. + + +File: groff.info, Node: Typographical symbols in ms, Next: Paragraphs in ms, Prev: Text settings in ms, Up: ms Body Text + +4.6.5.2 Typographical symbols +............................. + +'ms' provides a few strings to obtain typographical symbols not easily +entered with the keyboard. These and many others are available as +special character escape sequences--see the 'groff_char(7)' man page. + + -- String: \*[-] + Interpolate an em dash. + + -- String: \*[Q] + -- String: \*[U] + Interpolate typographer's quotation marks where available, and + neutral double quotes otherwise. '\*Q' is the left quote and '\*U' + the right. + + +File: groff.info, Node: Paragraphs in ms, Next: Headings in ms, Prev: Typographical symbols in ms, Up: ms Body Text + +4.6.5.3 Paragraphs +.................. + +Paragraphing macros "break", or terminate, any pending output line so +that a new paragraph can begin. Several paragraph types are available, +differing in how indentation applies to them: to left, right, or both +margins; to the first output line of the paragraph, all output lines, or +all but the first. All paragraphing macro calls cause the insertion of +vertical space in the amount stored in the 'PD' register, except at page +or column breaks. Alternatively, a blank input line breaks the output +line and vertically spaces by one vee. + + -- Macro: .LP + Set a paragraph without any (additional) indentation. + + -- Macro: .PP + Set a paragraph with a first-line left indentation in the amount + stored in the 'PI' register. + + -- Macro: .IP [marker [width]] + Set a paragraph with a left indentation. The optional MARKER is + not indented and is empty by default. It has several applications; + see *note Lists in ms::. WIDTH overrides the indentation amount + stored in the 'PI' register; its default unit is 'n'. Once + specified, WIDTH applies to further 'IP' calls until specified + again or a heading or different paragraphing macro is called. + + -- Macro: .QP + Set a paragraph indented from both left and right margins by the + amount stored in the 'QI' register. + + -- Macro: .QS + -- Macro: .QE + Begin ('QS') and end ('QE') a region where each paragraph is + indented from both margins by the amount stored in the 'QI' + register. The text between 'QS' and 'QE' can be structured further + by use of other paragraphing macros. + + -- Macro: .XP + Set an "exdented" paragraph--one with a left indentation in the + amount stored in the 'PI' register on every line _except_ the first + (also known as a hanging indent). This is a Berkeley extension. + + The following example illustrates the use of paragraphing macros. + + .NH 2 + Cases used in the 2001 study + .LP + Two software releases were considered for this report. + .PP + The first is commercial software; + the second is free. + .IP \[bu] + Microsoft Word for Windows, + starting with version 1.0 through the current version + (Word 2000). + .IP \[bu] + GNU Emacs, + from its first appearance as a standalone editor through + the current version (v20). + See [Bloggs 2002] for details. + .QP + Franklin's Law applied to software: + software expands to outgrow both RAM and disk space over + time. + .SH + Bibliography + .XP + Bloggs, Joseph R., + .I "Everyone's a Critic" , + Underground Press, March 2002. + A definitive work that answers all questions and + criticisms about the quality and usability of free + software. + + +File: groff.info, Node: Headings in ms, Next: Typeface and decoration, Prev: Paragraphs in ms, Up: ms Body Text + +4.6.5.4 Headings +................ + +Use headings to create a sequential or hierarchical structure for your +document. The 'ms' macros print headings in *bold* using the same font +family and, by default, type size as the body text. Headings are +available with and without automatic numbering. Text on input lines +following the macro call becomes the heading's title. Call a +paragraphing macro to end the heading text and start the section's +content. + + -- Macro: .NH [depth] + -- Macro: .NH S heading-depth-index ... + Set an automatically numbered heading. + + 'ms' produces a numbered heading the form A.B.C..., to any depth + desired, with the numbering of each depth increasing automatically + and being reset to zero when a more significant level is increased. + "1" is the most significant or coarsest division of the document. + Only non-zero values are output. If DEPTH is omitted, it is taken + to be '1'. + + If you specify DEPTH such that an ascending gap occurs relative to + the previous 'NH' call--that is, you "skip a depth", as by '.NH 1' + and then '.NH 3'--'groff' 'ms' emits a warning on the standard + error stream. + + Alternatively, you can give 'NH' a first argument of 'S', followed + by integers to number the heading depths explicitly. Further + automatic numbering, if used, resumes using the specified indices + as their predecessors. This feature is a Berkeley extension. + + An example may be illustrative. + + .NH 1 + Animalia + .NH 2 + Arthropoda + .NH 3 + Crustacea + .NH 2 + Chordata + .NH S 6 6 6 + Daimonia + .NH 1 + Plantae + + The above results in numbering as follows; the vertical space that +normally precedes each heading is omitted. + + 1. Animalia + 1.1. Arthropoda + 1.1.1. Crustacea + 1.2. Chordata + 6.6.6. Daimonia + 7. Plantae + + -- String: \*[SN-STYLE] + -- String: \*[SN-DOT] + -- String: \*[SN-NO-DOT] + -- String: \*[SN] + After 'NH' is called, the assigned number is made available in the + strings 'SN-DOT' (as it appears in a printed heading with default + formatting, followed by a terminating period) and 'SN-NO-DOT' (with + the terminating period omitted). These are GNU extensions. + + You can control the style used to print numbered headings by + defining an appropriate alias for the string 'SN-STYLE'. By + default, 'SN-STYLE' is aliased to 'SN-DOT'. If you prefer to omit + the terminating period from numbers appearing in numbered headings, + you may define the alias as follows. + + .als SN-STYLE SN-NO-DOT + + Any such change in numbering style becomes effective from the next + use of 'NH' following redefinition of the alias for 'SN-STYLE'. + The formatted number of the current heading is available in the + 'SN' string (a feature first documented by Berkeley), which + facilitates its inclusion in, for example, table captions, equation + labels, and 'XS'/'XA'/'XE' table of contents entries. + + -- Macro: .SH [depth] + Set an unnumbered heading. + + The optional DEPTH argument is a GNU extension indicating the + heading depth corresponding to the DEPTH argument of 'NH'. It + matches the type size at which the heading is set to that of a + numbered heading at the same depth when the 'GROWPS' and 'PSINCR' + heading size adjustment mechanism is in effect. + + If the 'GROWPS' register is set to a value greater than the LEVEL +argument to 'NH' or 'SH', the type size of a heading produced by these +macros increases by 'PSINCR' units over the size specified by 'PS' +multiplied by the difference of 'GROWPS' and LEVEL. The value stored in +'PSINCR' is interpreted in 'groff' basic units; the 'p' scaling unit +should be employed when assigning a value specified in points. For +example, the sequence + + .nr PS 10 + .nr GROWPS 3 + .nr PSINCR 1.5p + .NH 1 + Carnivora + .NH 2 + Felinae + .NH 3 + Felis catus + .SH 2 + Machairodontinae + +will cause "1. Carnivora" to be printed in 13-point text, followed by +"1.1. Felinae" in 11.5-point text, while "1.1.1. Felis catus" and all +more deeply nested heading levels will remain in the 10-point text +specified by the 'PS' register. "Machairodontinae" is printed at 11.5 +points, since it corresponds to heading level 2. + + The 'HORPHANS' register operates in conjunction with the 'NH' and +'SH' macros to inhibit the printing of isolated headings at the bottom +of a page; it specifies the minimum number of lines of an immediately +subsequent paragraph that must be kept on the same page as the heading. +If insufficient space remains on the current page to accommodate the +heading and this number of lines of paragraph text, a page break is +forced before the heading is printed. Any display macro call or 'tbl', +'pic', or 'eqn' region between the heading and the subsequent paragraph +suppresses this grouping. *Note ms keeps and displays:: and *note ms +Insertions::. + + +File: groff.info, Node: Typeface and decoration, Next: Lists in ms, Prev: Headings in ms, Up: ms Body Text + +4.6.5.5 Typeface and decoration +............................... + +The 'ms' macros provide a variety of ways to style text. Attend closely +to the ordering of arguments labeled PRE and POST, which is not +intuitive. Support for PRE arguments is a GNU extension.(1) (*note +Typeface and decoration-Footnote-1::) + + -- Macro: .B [text [post [pre]]] + Style TEXT in bold, followed by POST in the previous font style + without intervening space, and preceded by PRE similarly. Without + arguments, 'ms' styles subsequent text in bold until the next + paragraphing, heading, or no-argument typeface macro call. + + -- Macro: .R [text [post [pre]]] + As 'B', but use the roman style (upright text of normal weight) + instead of bold. Argument recognition is a GNU extension. + + -- Macro: .I [text [post [pre]]] + As 'B', but use an italic or oblique style instead of bold. + + -- Macro: .BI [text [post [pre]]] + As 'B', but use a bold italic or bold oblique style instead of + upright bold. This is a Tenth Edition Research Unix extension. + + -- Macro: .CW [text [post [pre]]] + As 'B', but use a constant-width (monospaced) roman typeface + instead of bold. This is a Tenth Edition Research Unix extension. + + -- Macro: .BX [text] + Typeset TEXT and draw a box around it. On terminal devices, + reverse video is used instead. If you want TEXT to contain space, + use unbreakable space or horizontal motion escape sequences ('\~', + '\', '\^', '\|', '\0' or '\h'). + + -- Macro: .UL [text [post]] + Typeset TEXT with an underline. POST, if present, is set after + TEXT with no intervening space. + + -- Macro: .LG + Set subsequent text in larger type (two points larger than the + current size) until the next type size, paragraphing, or heading + macro call. You can specify this macro multiple times to enlarge + the type size as needed. + + -- Macro: .SM + Set subsequent text in smaller type (two points smaller than the + current size) until the next type size, paragraphing, or heading + macro call. You can specify this macro multiple times to reduce + the type size as needed. + + -- Macro: .NL + Set subsequent text at the normal type size (the amount in the 'PS' + register). + + PRE and POST arguments are typically used to simplify the attachment +of punctuation to styled words. When PRE is used, a hyphenation control +escape sequence '\%' that would ordinarily start TEXT must start PRE +instead to have the desired effect. + + The CS course's students found one C language keyword + .CW static ) \%( + most troublesome. + + The foregoing example produces output as follows. + + The CS course's students found one C language keyword (static) + most troublesome. + + You can use the output line continuation escape sequence '\c' to +achieve the same result (*note Line Continuation::). It is also +portable to older 'ms' implementations. + + The CS course's students found one C language keyword + \%(\c + .CW \%static ) + most troublesome. + + 'groff' 'ms' also offers strings to begin and end super- and +subscripting. These are GNU extensions. + + -- String: \*[{] + -- String: \*[}] + Begin and end superscripting, respectively. + + -- String: \*[<] + -- String: \*[>] + Begin and end subscripting, respectively. + + Rather than calling the 'CW' macro, in 'groff' 'ms' you might prefer +to change the font family to Courier by setting the 'FAM' string to 'C'. +You can then use all four style macros above, returning to the default +family (Times) with '.ds FAM T'. Because changes to 'FAM' take effect +only at the next paragraph, 'CW' remains useful to "inline" a change to +the font family, similarly to the practice of this document in noting +syntactical elements of 'ms' and 'groff'. + + +File: groff.info, Node: Typeface and decoration-Footnotes, Up: Typeface and decoration + + (1) This idiosyncrasy arose through feature accretion; for example, +the 'B' macro in Version 6 Unix 'ms' (1975) accepted only one argument, +the text to be set in boldface. By Version 7 (1979) it recognized a +second argument; in 1990, 'groff' 'ms' added a "pre" argument, placing +it third to avoid breaking support for older documents. + + +File: groff.info, Node: Lists in ms, Next: Indented regions in ms, Prev: Typeface and decoration, Up: ms Body Text + +4.6.5.6 Lists +............. + +The MARKER argument to the 'IP' macro can be employed to present a +variety of lists; for instance, you can use a bullet glyph ('\[bu]') for +unordered lists, a number (or auto-incrementing register) for numbered +lists, or a word or phrase for glossary-style or definition lists. If +you set the paragraph indentation register 'PI' before calling 'IP', you +can later reorder the items in the list without having to ensure that a +WIDTH argument remains affixed to the first call. + + The following is an example of a bulleted list. + + .nr PI 2n + A bulleted list: + .IP \[bu] + lawyers + .IP \[bu] + guns + .IP \[bu] + money + + A bulleted list: + + * lawyers + + * guns + + * money + + The following is an example of a numbered list. + + .nr step 0 1 + .nr PI 3n + A numbered list: + .IP \n+[step] + lawyers + .IP \n+[step] + guns + .IP \n+[step] + money + + A numbered list: + + 1. lawyers + + 2. guns + + 3. money + + Here we have employed the 'nr' request to create a register of our +own, 'step'. We initialized it to zero and assigned it an +auto-increment of 1. Each time we use the escape sequence '\n+[PI]' +(note the plus sign), the formatter applies the increment just before +interpolating the register's value. Preparing the 'PI' register as well +enables us to rearrange the list without the tedium of updating macro +calls. + + The next example illustrates a glossary-style list. + + A glossary-style list: + .IP lawyers 0.4i + Two or more attorneys. + .IP guns + Firearms, + preferably large-caliber. + .IP money + Gotta pay for those + lawyers and guns! + + A glossary-style list: + + lawyers + Two or more attorneys. + + guns Firearms, preferably large-caliber. + + money + Gotta pay for those lawyers and guns! + + In the previous example, observe how the 'IP' macro places the +definition on the same line as the term if it has enough space. If this +is not what you want, there are a few workarounds we will illustrate by +modifying the example. First, you can use a 'br' request to force a +break after printing the term or label. + + .IP guns + .br + Firearms, + + Second, you could apply the '\p' escape sequence to force a break. +The space following the escape sequence is important; if you omit it, +'groff' prints the first word of the paragraph text on the same line as +the term or label (if it fits) _then_ breaks the line. + + .IP guns + \p Firearms, + + Finally, you may append a horizontal motion to the marker with the +'\h' escape sequence; using the same amount as the indentation will +ensure that the marker is too wide for 'groff' to treat it as "fitting" +on the same line as the paragraph text. + + .IP guns\h'0.4i' + Firearms, + + In each case, the result is the same. + + A glossary-style list: + + lawyers + Two or more attorneys. + + guns + Firearms, preferably large-caliber. + + money + Gotta pay for those lawyers and guns! + + +File: groff.info, Node: Indented regions in ms, Next: ms keeps and displays, Prev: Lists in ms, Up: ms Body Text + +4.6.5.7 Indented regions +........................ + +You may need to indent a region of text while otherwise formatting it +normally. Indented regions can be nested; you can change '\n[PI]' +before each call to vary the amount of inset. + + -- Macro: .RS + Begin a region where headings, paragraphs, and displays are + indented (further) by the amount stored in the 'PI' register. + + -- Macro: .RE + End the (next) most recent indented region. + + This feature enables you to easily line up text under hanging and +indented paragraphs. For example, you may wish to structure lists +hierarchically. + + .IP \[bu] 2 + Lawyers: + .RS + .IP \[bu] + Dewey, + .IP \[bu] + Cheatham, + and + .IP \[bu] + and Howe. + .RE + .IP \[bu] + Guns + + * Lawyers: + + * Dewey, + + * Cheatham, and + + * Howe. + + * Guns + + +File: groff.info, Node: ms keeps and displays, Next: ms Insertions, Prev: Indented regions in ms, Up: ms Body Text + +4.6.5.8 Keeps, boxed keeps, and displays +........................................ + +On occasion, you may want to "keep" several lines of text, or a region +of a document, together on a single page, preventing an automatic page +break within certain boundaries. This can cause a page break to occur +earlier than it normally would. For example, you may want to keep two +paragraphs together, or a paragraph that refers to a table, list, or +figure adjacent to the item it discusses. 'ms' provides the 'KS' and +'KE' macros for this purpose. + + You can alternatively specify a "floating keep": if a keep cannot fit +on the current page, 'ms' holds its contents and allows material +following the keep (in the source document) to fill the remainder of the +current page. When the page breaks, whether by reaching the end or 'bp' +request, 'ms' puts the floating keep at the beginning of the next page. +This is useful for placing large graphics or tables that do not need to +appear exactly where they occur in the source document. + + -- Macro: .KS + -- Macro: .KF + -- Macro: .KE + 'KS' begins a keep, 'KF' a floating keep, and 'KE' ends a keep of + either kind. + + As an alternative to the keep mechanism, the 'ne' request forces a +page break if there is not at least the amount of vertical space +specified in its argument remaining on the page (*note Page Control::). +One application of 'ne' is to reserve space on the page for a figure or +illustration to be included later. + + A "boxed keep" has a frame drawn around it. + + -- Macro: .B1 + -- Macro: .B2 + 'B1' begins a keep with a box drawn around it. 'B2' ends a boxed + keep. + + Boxed keep macros cause breaks; if you need to box a word or phrase +within a line, see the 'BX' macro in *note Typeface and decoration::. +Box lines are drawn as close as possible to the text they enclose so +that they are usable within paragraphs. If you wish to box one or more +paragraphs, you may improve the appearance by calling 'B1' after the +first paragraphing macro, and by adding a small amount of vertical space +before calling 'B2'. + + .LP + .B1 + .I Warning: + Happy Fun Ball may suddenly accelerate to dangerous + speeds. + .sp \n[PD]/2 \" space by half the inter-paragraph distance + .B2 + + If you want a boxed keep to float, you will need to enclose the 'B1' +and 'B2' calls within a pair of 'KF' and 'KE' calls. + + "Displays" turn off filling; lines of verse or program code are shown +with their lines broken as in the source document without requiring 'br' +requests between lines. Displays can be kept on a single page or +allowed to break across pages. The 'DS' macro begins a kept display of +the layout specified in its first argument; non-kept displays are begun +with dedicated macros corresponding to their layout. + + -- Macro: .DS L + -- Macro: .LD + Begin ('DS': kept) left-aligned display. + + -- Macro: .DS [I [indent]] + -- Macro: .ID [indent] + Begin ('DS': kept) display indented by INDENT if specified, and by + the amount of the 'DI' register otherwise. + + -- Macro: .DS B + -- Macro: .BD + Begin a ('DS': kept) a block display: the entire display is + left-aligned, but indented such that the longest line in the + display is centered on the page. + + -- Macro: .DS C + -- Macro: .CD + Begin a ('DS': kept) centered display: each line in the display is + centered. + + -- Macro: .DS R + -- Macro: .RD + Begin a ('DS': kept) right-aligned display. This is a GNU + extension. + + -- Macro: .DE + End any display. + + The distance stored in the 'DD' register is inserted before and after +each pair of display macros; this is a Berkeley extension. In 'groff' +'ms', this distance replaces any adjacent inter-paragraph distance or +subsequent spacing prior to a section heading. The 'DI' register is a +GNU extension; its value is an indentation applied to displays created +with '.DS' and '.ID' without arguments, to '.DS I' without an +indentation argument, and to indented equations set with '.EQ'. Changes +to either register take effect at the next display boundary. + + +File: groff.info, Node: ms Insertions, Next: ms Footnotes, Prev: ms keeps and displays, Up: ms Body Text + +4.6.5.9 Tables, figures, equations, and references +.................................................. + +The 'ms' package is often used with the 'tbl', 'pic', 'eqn', and 'refer' +preprocessors. Mark text meant for preprocessors by enclosing it in +pairs of tokens as follows, with nothing between the dot and the macro +name. The preprocessors match these tokens only at the start of an +input line. + + -- Macro: .TS [H] + -- Macro: .TE + Demarcate a table to be processed by the 'tbl' preprocessor. The + optional argument 'H' to 'TS' instructs 'ms' to repeat table rows + (often column headings) at the top of each new page the table + spans, if applicable; calling the 'TH' macro marks the end of such + rows. The GNU 'tbl(1)' man page provides a comprehensive reference + to the preprocessor and offers examples of its use. + + -- Macro: .PS + -- Macro: .PE + -- Macro: .PF + 'PS' begins a picture to be processed by the 'gpic' preprocessor; + either of 'PE' or 'PF' ends it, the latter with "flyback" to the + vertical position at its top. You can create 'pic' input manually + or with a program such as 'xfig'. + + -- Macro: .EQ [align [label]] + -- Macro: .EN + Demarcate an equation to be processed by the 'eqn' preprocessor. + The equation is centered by default; ALIGN can be 'C', 'L', or 'I' + to (explicitly) center, left-align, or indent it by the amount + stored in the 'DI' register, respectively. If specified, LABEL is + set right-aligned. + + -- Macro: .[ + -- Macro: .] + Demarcate a bibliographic citation to be processed by the 'refer' + preprocessor. The GNU 'refer(1)' man page provides a comprehensive + reference to the preprocessor and the format of its bibliographic + database. Type 'man refer' at the command line to view it. + + When 'refer' emits collected references (as might be done on a "Works +Cited" page), it interpolates the 'REFERENCES' string as an unnumbered +heading ('SH'). + + The following is an example of how to set up a table that may print +across two or more pages. + + .TS H + allbox; + Cb | Cb . + Part->Description + _ + .TH + .T& + GH-1978->Fribulating gonkulator + ...the rest of the table follows... + .TE + +Attempting to place a multi-page table inside a keep can lead to +unpleasant results, particularly if the 'tbl' 'allbox' option is used. + + Mathematics can be typeset using the language of the 'eqn' +preprocessor. + + .EQ C (\*[SN-NO-DOT]a) + p ~ = ~ q sqrt { ( 1 + ~ ( x / q sup 2 ) } + .EN + +This input formats a labelled equation. We used the 'SN-NO-DOT' string +to base the equation label on the current heading number, giving us more +flexibility to reorganize the document. + + Use 'groff' options to run preprocessors on the input: '-e' for +'geqn', '-p' for 'gpic', '-R' for 'grefer', and '-t' for 'gtbl'. + + +File: groff.info, Node: ms Footnotes, Prev: ms Insertions, Up: ms Body Text + +4.6.5.10 Footnotes +.................. + +A footnote is typically anchored to a place in the text with a "marker", +which is a small integer, a symbol such as a dagger, or arbitrary +user-specified text. + + -- String: \*[*] + Place an "automatic number", an automatically generated numeric + footnote marker, in the text. Each time this string is + interpolated, the number it produces increments by one. Automatic + numbers start at 1. This is a Berkeley extension. + + Enclose the footnote text in 'FS' and 'FE' macro calls to set it at +the nearest available "foot", or bottom, of a text column or page. + + -- Macro: .FS [marker] + -- Macro: .FE + Begin ('FS') and end ('FE') a footnote. 'FS' calls 'FS-MARK' with + any supplied MARKER argument, which is then also placed at the + beginning of the footnote text. If MARKER is omitted, the next + pending automatic footnote number enqueued by interpolation of the + '*' string is used, and if none exists, nothing is prefixed. + + You may not desire automatically numbered footnotes in spite of their +convenience. You can indicate a footnote with a symbol or other text by +specifying its marker at the appropriate place (for example, by using +'\[dg]' for the dagger glyph) _and_ as an argument to the 'FS' macro. +Such manual marks should be repeated as arguments to 'FS' or as part of +the footnote text to disambiguate their correspondence. You may wish to +use '\*{' and '\*}' to superscript the marker at the anchor point, in +the footnote text, or both. + + 'groff' 'ms' provides a hook macro, 'FS-MARK', for user-determined +operations to be performed when the 'FS' macro is called. It is passed +the same arguments as 'FS' itself. An application of 'FS-MARK' is +anchor placement for a hyperlink reference, so that a footnote can link +back to its referential context.(1) (*note ms Footnotes-Footnote-1::) +By default, this macro has an empty definition. 'FS-MARK' is a GNU +extension. + + Footnotes can be safely used within keeps and displays, but you +should avoid using automatically numbered footnotes within floating +keeps. You can place a second '\**' interpolation between a '\**' and +its corresponding 'FS' call as long as each 'FS' call occurs _after_ the +corresponding '\**' and occurrences of 'FS' are in the same order as +corresponding occurrences of '\**'. + + Footnote text is formatted as paragraphs are, using analogous +parameters. The registers 'FI', 'FPD', 'FPS', and 'FVS' correspond to +'PI', 'PD', 'PS', and 'CS', respectively; 'FPD', 'FPS', and 'FVS' are +GNU extensions. + + The 'FF' register controls the formatting of automatically numbered +footnote paragraphs and those for which 'FS' is given a marker argument. +*Note ms Document Control Settings::. + + The default footnote line length is 11/12ths of the normal line +length for compatibility with the expectations of historical 'ms' +documents; you may wish to set the 'FR' string to '1' to align with +contemporary typesetting practices. In the past,(2) (*note ms +Footnotes-Footnote-2::) an 'FL' register was used for the line length in +footnotes; however, setting this register at document initialization +time had no effect on the footnote line length in multi-column +arrangements.(3) (*note ms Footnotes-Footnote-3::) + + 'FR' should be used in preference to the old 'FL' register in +contemporary documents. The footnote line length is effectively +computed as 'column-width * \*[FR]'. If an absolute footnote line +length is required, recall that arithmetic expressions in 'roff' input +are evaluated strictly from left to right, with no operator precedence +(parentheses are honored). + + .ds FR 0+3i \" Set footnote line length to 3 inches. + + +File: groff.info, Node: ms Footnotes-Footnotes, Up: ms Footnotes + + (1) "Portable Document Format Publishing with GNU Troff", +'pdfmark.ms' in the 'groff' distribution, uses this technique. + + (2) Unix Version 7 'ms', its descendants, and GNU 'ms' prior to +'groff' version 1.23.0 + + (3) You could reset it after each call to '.1C', '.2C', or '.MC'. + + +File: groff.info, Node: ms language and localization, Next: ms Page Layout, Prev: ms Footnotes, Up: ms Body Text + +4.6.5.11 Language and localization +.................................. + +'groff' 'ms' provides several strings that you can customize for your +own purposes, or redefine to adapt the macro package to languages other +than English. It is already localized for Czech, German, French, +Italian, and Swedish. Load the desired localization macro package after +'ms'; see the 'groff_tmac(5)' man page. + + $ groff -ms -mfr bienvenue.ms + + The following strings are available. + + -- String: \*[REFERENCES] + Contains the string printed at the beginning of a references + (bibliography) page produced with GNU 'refer(1)'. The default is + 'References'. + + -- String: \*[ABSTRACT] + Contains the string printed at the beginning of the abstract. The + default is '\f[I]ABSTRACT\f[]'; it includes font selection escape + sequences to set the word in italics. + + -- String: \*[TOC] + Contains the string printed at the beginning of the table of + contents. The default is 'Table of Contents'. + + -- String: \*[MONTH1] + -- String: \*[MONTH2] + -- String: \*[MONTH3] + -- String: \*[MONTH4] + -- String: \*[MONTH5] + -- String: \*[MONTH6] + -- String: \*[MONTH7] + -- String: \*[MONTH8] + -- String: \*[MONTH9] + -- String: \*[MONTH10] + -- String: \*[MONTH11] + -- String: \*[MONTH12] + Contain the full names of the calendar months. The defaults are in + English: 'January', 'February', and so on. + + +File: groff.info, Node: ms Page Layout, Next: Differences from AT&T ms, Prev: ms Body Text, Up: ms + +4.6.6 Page layout +----------------- + +'ms''s default page layout arranges text in a single column with the +page number between hyphens centered in a header on each page except the +first, and produces no footers. You can customize this arrangement. + +* Menu: + +* ms Headers and Footers:: +* Tab Stops in ms:: +* ms Margins:: +* ms Multiple Columns:: +* ms TOC:: + + +File: groff.info, Node: ms Headers and Footers, Next: Tab Stops in ms, Prev: ms Page Layout, Up: ms Page Layout + +4.6.6.1 Headers and footers +........................... + +There are multiple ways to produce headers and footers. One is to +define the strings 'LH', 'CH', and 'RH' to set the left, center, and +right headers, respectively; and 'LF', 'CF', and 'RF' to set the left, +center, and right footers. This approach suffices for documents that do +not distinguish odd- and even-numbered pages. + + Another method is to call macros that set headers or footers for odd- +or even-numbered pages. Each such macro takes a delimited argument +separating the left, center, and right header or footer texts from each +other. You can replace the neutral apostrophes (''') shown below with +any character not appearing in the header or footer text. These macros +are Berkeley extensions. + + -- Macro: .OH 'left'center'right' + -- Macro: .EH 'left'center'right' + -- Macro: .OF 'left'center'right' + -- Macro: .EF 'left'center'right' + The 'OH' and 'EH' macros define headers for odd- (recto) and + even-numbered (verso) pages, respectively; the 'OF' and 'EF' macros + define footers for them. + + With either method, a percent sign '%' in header or footer text is +replaced by the current page number. By default, 'ms' places no header +on a page numbered "1" (regardless of its number format). + + -- Macro: .P1 + Typeset the header even on page 1. To be effective, this macro + must be called before the header trap is sprung on any page + numbered "1"; in practice, unless your page numbering is unusual, + this means that you should call it early, before 'TL' or any + heading or paragraphing macro. This is a Berkeley extension. + + For even greater flexibility, 'ms' is designed to permit the +redefinition of the macros that are called when the 'groff' traps that +ordinarily cause the headers and footers to be output are sprung. 'PT' +("page trap") is called by 'ms' when the header is to be written, and +'BT' ("bottom trap") when the footer is to be. The 'groff' page +location trap that 'ms' sets up to format the header also calls the +(normally undefined) 'HD' macro after 'PT'; you can define 'HD' if you +need additional processing after setting the header (for example, to +draw a line below it). The 'HD' hook is a Berkeley extension. Any such +macros you (re)define must implement any desired specialization for +odd-, even-, or first numbered pages. + + +File: groff.info, Node: Tab Stops in ms, Next: ms Margins, Prev: ms Headers and Footers, Up: ms Page Layout + +4.6.6.2 Tab stops +................. + +Use the 'ta' request to define tab stops as needed. *Note Tabs and +Fields::. + + -- Macro: .TA + Reset the tab stops to the 'ms' default (every 5 ens). Redefine + this macro to create a different set of default tab stops. + + +File: groff.info, Node: ms Margins, Next: ms Multiple Columns, Prev: Tab Stops in ms, Up: ms Page Layout + +4.6.6.3 Margins +............... + +Control margins using the registers summarized in "Margin settings" in +*note ms Document Control Settings:: above. There is no setting for the +right margin; the combination of page offset '\n[PO]' and line length +'\n[LL]' determines it. + + +File: groff.info, Node: ms Multiple Columns, Next: ms TOC, Prev: ms Margins, Up: ms Page Layout + +4.6.6.4 Multiple columns +........................ + +'ms' can set text in as many columns as reasonably fit on the page. The +following macros force a page break if a multi-column layout is active +when they are called. The 'MINGW' register stores the default minimum +gutter width; it is a GNU extension. When multiple columns are in use, +keeps and the 'HORPHANS' and 'PORPHANS' registers work with respect to +column breaks instead of page breaks. + + -- Macro: .1C + Arrange page text in a single column (the default). + + -- Macro: .2C + Arrange page text in two columns. + + -- Macro: .MC [column-width [gutter-width]] + Arrange page text in multiple columns. If you specify no + arguments, it is equivalent to the '2C' macro. Otherwise, + COLUMN-WIDTH is the width of each column and GUTTER-WIDTH is the + minimum distance between columns. + + +File: groff.info, Node: ms TOC, Next: Differences from AT&T ms, Prev: ms Multiple Columns, Up: ms Page Layout + +4.6.6.5 Creating a table of contents +.................................... + +Because 'roff' formatters process their input in a single pass, material +on page 50, for example, cannot influence what appears on page 1--this +poses a challenge for a table of contents at its traditional location in +front matter, if you wish to avoid manually maintaining it. 'ms' +enables the collection of material to be presented in the table of +contents as it appears, saving its page number along with it, and then +emitting the collected contents on demand toward the end of the +document. The table of contents can then be resequenced to its desired +location by physically rearranging the pages of a printed document, or +as part of post-processing--with a 'sed(1)' script to reorder the pages +in 'troff''s output, with 'pdfjam(1)', or with 'gropdf(1)''s +'.pdfswitchtopage' feature, for example. + + Define an entry to appear in the table of contents by bracketing its +text between calls to the 'XS' and 'XE' macros. A typical application +is to call them immediately after 'NH' or 'SH' and repeat the heading +text within them. The 'XA' macro, used within '.XS'/'.XE' pairs, +supplements an entry--for instance, when it requires multiple output +lines, whether because a heading is too long to fit or because style +dictates that page numbers not be repeated. You may wish to indent the +text thus wrapped to correspond to its heading depth; this can be done +in the entry text by prefixing it with tabs or horizontal motion escape +sequences, or by providing a second argument to the 'XA' macro. 'XS' +and 'XA' automatically associate the page number where they are called +with the text following them, but they accept arguments to override this +behavior. At the end of the document, call 'TC' or 'PX' to emit the +table of contents; 'TC' resets the page number to 'i' (Roman numeral +one), and then calls 'PX'. All of these macros are Berkeley extensions. + + -- Macro: .XS [page-number] + -- Macro: .XA [page-number [indentation]] + -- Macro: .XE + Begin, supplement, and end a table of contents entry. Each entry + is associated with PAGE-NUMBER (otherwise the current page number); + a PAGE-NUMBER of 'no' prevents a leader and page number from being + emitted for that entry. Use of 'XA' within 'XS'/'XE' is optional; + it can be repeated. If INDENTATION is present, a supplemental + entry is indented by that amount; ens are assumed if no unit is + indicated. Text on input lines between 'XS' and 'XE' is stored for + later recall by 'PX'. + + -- Macro: .PX [no] + Switch to single-column layout. Unless 'no' is specified, center + and interpolate the 'TOC' string in bold and two points larger than + the body text. Emit the table of contents entries. + + -- Macro: .TC [no] + Set the page number to 1, the page number format to lowercase Roman + numerals, and call 'PX' (with a 'no' argument, if present). + + Here's an example of typical 'ms' table of contents preparation. We +employ horizontal escape sequences '\h' to indent the entries by +sectioning depth. + + .NH 1 + Introduction + .XS + Introduction + .XE + ... + .NH 2 + Methodology + .XS + \h'2n'Methodology + .XA + \h'4n'Fassbinder's Approach + \h'4n'Kahiu's Approach + .XE + ... + .NH 1 + Findings + .XS + Findings + .XE + ... + .TC + + The remaining features in this subsubsection are GNU extensions. +'groff' 'ms' obviates the need to repeat heading text after 'XS' calls. +Call 'XN' and 'XH' after 'NH' and 'SH', respectively. + + -- Macro: .XN heading-text + -- Macro: .XH depth heading-text + Format HEADING-TEXT and create a corresponding table of contents + entry. 'XN' computes the indentation from the depth of the + preceding 'NH' call; 'XH' requires a DEPTH argument to do so. + + 'groff' 'ms' encourages customization of table of contents entry +production. + + -- Macro: .XN-REPLACEMENT heading-text + -- Macro: .XH-REPLACEMENT depth heading-text + These hook macros implement 'XN' and 'XH', respectively. They call + 'XN-INIT' and pass their HEADING-TEXT arguments to 'XH-UPDATE-TOC'. + + -- Macro: .XN-INIT + -- Macro: .XH-UPDATE-TOC depth heading-text + The 'XN-INIT' hook macro does nothing by default. 'XH-UPDATE-TOC' + brackets HEADING-TEXT with 'XS' and 'XE' calls, indenting it by 2 + ens per level of DEPTH beyond the first. + + We could therefore produce a table of contents similar to that in the +previous example with fewer macro calls. (The difference is that this +input follows the "Approach" entries with leaders and page numbers.) + + .NH 1 + .XN Introduction + ... + .NH 2 + .XN Methodology + .XH 3 "Fassbinder's Approach" + .XH 3 "Kahiu's Approach" + ... + .NH 1 + .XN Findings + ... + + To get the section number of the numbered headings into the table of +contents entries, we might define 'XN-REPLACEMENT' as follows. (We +obtain the heading depth from 'groff' 'ms''s internal register 'nh*hl'.) + + .de XN-REPLACEMENT + .XN-INIT + .XH-UPDATE-TOC \\n[nh*hl] \\$@ + \&\\*[SN] \\$* + .. + + You can change the style of the leader that bridges each table of +contents entry with its page number; define the 'TC-LEADER' special +character by using the 'char' request. A typical leader combines the +dot glyph '.' with a horizontal motion escape sequence to spread the +dots. The width of the page number field is stored in the 'TC-MARGIN' +register. + + +File: groff.info, Node: Differences from AT&T ms, Next: ms Naming Conventions, Prev: ms Page Layout, Up: ms + +4.6.7 Differences from AT&T 'ms' +-------------------------------- + +The 'groff' 'ms' macros are an independent reimplementation, using no +AT&T code. Since they take advantage of the extended features of +'groff', they cannot be used with AT&T 'troff'. 'groff' 'ms' supports +features described above as Berkeley and Tenth Edition Research Unix +extensions, and adds several of its own. + + * The internals of 'groff' 'ms' differ from the internals of AT&T + 'ms'. Documents that depend upon implementation details of AT&T + 'ms' may not format properly with 'groff' 'ms'. Such details + include macros whose function was not documented in the AT&T 'ms' + manual.(1) (*note Differences from AT&T ms-Footnote-1::) + + * The error-handling policy of 'groff' 'ms' is to detect and report + errors, rather than to ignore them silently. + + * Tenth Edition Research Unix supported 'P1'/'P2' macros to bracket + code examples; 'groff' 'ms' does not. + + * 'groff' 'ms' does not work in GNU 'troff''s AT&T compatibility + mode. If loaded when that mode is enabled, it aborts processing + with a diagnostic message. + + * Multiple line spacing is not supported. Use a larger vertical + spacing instead. + + * 'groff' 'ms' uses the same header and footer defaults in both + 'nroff' and 'troff' modes as AT&T 'ms' does in 'troff' mode; AT&T's + default in 'nroff' mode is to put the date, in U.S. traditional + format (e.g., "January 1, 2021"), in the center footer (the 'CF' + string). + + * Many 'groff' 'ms' macros, including those for paragraphs, headings, + and displays, cause a reset of paragraph rendering parameters, and + may change the indentation; they do so not by incrementing or + decrementing it, but by setting it absolutely. This can cause + problems for documents that define additional macros of their own + that try to manipulate indentation. Use the 'ms' 'RS' and 'RE' + macros instead of the 'in' request. + + * AT&T 'ms' interpreted the values of the registers 'PS' and 'VS' in + points, and did not support the use of scaling units with them. + 'groff' 'ms' interprets values of the registers 'PS', 'VS', 'FPS', + and 'FVS' equal to or larger than 1,000 (one thousand) as decimal + fractions multiplied by 1,000.(2) (*note Differences from AT&T + ms-Footnote-2::) This threshold makes use of a scaling unit with + these parameters practical for high-resolution devices while + preserving backward compatibility. It also permits expression of + non-integral type sizes. For example, 'groff -rPS=10.5p' at the + shell prompt is equivalent to placing '.nr PS 10.5p' at the + beginning of the document. + + * AT&T 'ms''s 'AU' macro supported arguments used with some document + types; 'groff' 'ms' does not. + + * Right-aligned displays are available. The AT&T 'ms' manual + observes that "it is tempting to assume that '.DS R' will right + adjust lines, but it doesn't work". In 'groff' 'ms', it does. + + * To make 'groff' 'ms' use the default page offset (which also + specifies the left margin), the 'PO' register must stay undefined + until the first 'ms' macro is called. + + This implies that '\n[PO]' should not be used early in the + document, unless it is changed also: accessing an undefined + register automatically defines it. + + * 'groff' 'ms' supports the 'PN' register, but it is not necessary; + you can access the page number via the usual '%' register and + invoke the 'af' request to assign a different format to it if + desired.(3) (*note Differences from AT&T ms-Footnote-3::) + + * The AT&T 'ms' manual documents registers 'CW' and 'GW' as setting + the default column width and "intercolumn gap", respectively, and + which applied when 'MC' was called with fewer than two arguments. + 'groff' 'ms' instead treats 'MC' without arguments as synonymous + with '2C'; there is thus no occasion for a default column width + register. Further, the 'MINGW' register and the second argument to + 'MC' specify a _minimum_ space between columns, not the fixed + gutter width of AT&T 'ms'. + + * The AT&T 'ms' manual did not document the 'QI' register; Berkeley + and 'groff' 'ms' do. + + -- Register: \n[GS] + The register 'GS' is set to 1 by the 'groff' 'ms' macros, but is + not used by the AT&T 'ms' package. Documents that need to + determine whether they are being formatted with 'groff' 'ms' or + another implementation should test this register. + +* Menu: + +* Missing Unix Version 7 ms Macros:: + + +File: groff.info, Node: Differences from AT&T ms-Footnotes, Up: Differences from AT&T ms + + (1) 'Typing Documents on the UNIX System: Using the -ms Macros with +Troff and Nroff', M. E. Lesk, Bell Laboratories, 1978 + + (2) Register values are converted to and stored as basic units. +*Note Measurements::. + + (3) If you redefine the 'ms' 'PT' macro and desire special treatment +of certain page numbers (like '1'), you may need to handle a non-Arabic +page number format, as 'groff' 'ms''s 'PT' does; see the macro package +source. 'groff' 'ms' aliases the 'PN' register to '%'. + + +File: groff.info, Node: Missing Unix Version 7 ms Macros, Prev: Differences from AT&T ms, Up: Differences from AT&T ms + +4.6.7.1 Unix Version 7 'ms' macros not implemented by 'groff' 'ms' +.................................................................. + +Several macros described in the Unix Version 7 'ms' documentation are +unimplemented by 'groff' 'ms' because they are specific to the +requirements of documents produced internally by Bell Laboratories, some +of which also require a glyph for the Bell System logo that 'groff' does +not support. These macros implemented several document type formats +('EG', 'IM', 'MF', 'MR', 'TM', 'TR'), were meaningful only in +conjunction with the use of certain document types ('AT', 'CS', 'CT', +'OK', 'SG'), stored the postal addresses of Bell Labs sites ('HO', 'IH', +'MH', 'PY', 'WH'), or lacked a stable definition over time ('UX'). To +compatibly render historical 'ms' documents using these macros, we +advise your documents to invoke the 'rm' request to remove any such +macros it uses and then define replacements with an authentically +typeset original at hand.(1) (*note Missing Unix Version 7 ms +Macros-Footnote-1::) For informal purposes, a simple definition of 'UX' +should maintain the readability of the document's substance. + + .rm UX + .ds UX Unix\" + + +File: groff.info, Node: Missing Unix Version 7 ms Macros-Footnotes, Up: Missing Unix Version 7 ms Macros + + (1) The removal beforehand is necessary because 'groff' 'ms' aliases +these macros to a diagnostic macro, and you want to redefine the aliased +name, not its target. + + +File: groff.info, Node: ms Legacy Features, Next: ms Naming Conventions, Prev: Differences from AT&T ms, Up: ms + +4.6.8 Legacy Features +--------------------- + +'groff' 'ms' retains some legacy features solely to support formatting +of historical documents; contemporary ones should not use them because +they can render poorly. See the 'groff_char(7)' man page. + +AT&T accent mark strings +........................ + +AT&T 'ms' defined accent mark strings as follows. + + -- String: \*['] + Apply acute accent to subsequent glyph. + + -- String: \*[`] + Apply grave accent to subsequent glyph. + + -- String: \*[:] + Apply dieresis (umlaut) to subsequent glyph. + + -- String: \*[^] + Apply circumflex accent to subsequent glyph. + + -- String: \*[~] + Apply tilde accent to subsequent glyph. + + -- String: \*[C] + Apply caron to subsequent glyph. + + -- String: \*[,] + Apply cedilla to subsequent glyph. + +Berkeley accent mark and glyph strings +...................................... + +Berkeley 'ms' offered an 'AM' macro; calling it redefined the AT&T +accent mark strings (except for '\*C'), applied them to the _preceding_ +glyph, and defined additional strings, some for spacing glyphs. + + -- Macro: .AM + Enable alternative accent mark and glyph-producing strings. + + -- String: \*['] + Apply acute accent to preceding glyph. + + -- String: \*[`] + Apply grave accent to preceding glyph. + + -- String: \*[:] + Apply dieresis (umlaut) to preceding glyph. + + -- String: \*[^] + Apply circumflex accent to preceding glyph. + + -- String: \*[~] + Apply tilde accent to preceding glyph. + + -- String: \*[,] + Apply cedilla to preceding glyph. + + -- String: \*[/] + Apply stroke (slash) to preceding glyph. + + -- String: \*[v] + Apply caron to preceding glyph. + + -- String: \*[_] + Apply macron to preceding glyph. + + -- String: \*[.] + Apply underdot to preceding glyph. + + -- String: \*[o] + Apply ring accent to preceding glyph. + + -- String: \*[?] + Interpolate inverted question mark. + + -- String: \*[!] + Interpolate inverted exclamation mark. + + -- String: \*[8] + Interpolate small letter sharp s. + + -- String: \*[q] + Interpolate small letter o with hook accent (ogonek). + + -- String: \*[3] + Interpolate small letter yogh. + + -- String: \*[d-] + Interpolate small letter eth. + + -- String: \*[D-] + Interpolate capital letter eth. + + -- String: \*[th] + Interpolate small letter thorn. + + -- String: \*[Th] + Interpolate capital letter thorn. + + -- String: \*[ae] + Interpolate small æ ligature. + + -- String: \*[Ae] + Interpolate capital Æ ligature. + + -- String: \*[oe] + Interpolate small oe ligature. + + -- String: \*[OE] + Interpolate capital OE ligature. + + +File: groff.info, Node: ms Naming Conventions, Prev: ms Legacy Features, Up: ms + +4.6.9 Naming Conventions +------------------------ + +The following conventions are used for names of macros, strings, and +registers. External names available to documents that use the 'groff' +'ms' macros contain only uppercase letters and digits. + + Internally, the macros are divided into modules. Conventions for +identifier names are as follows. + + * Names used only within one module are of the form MODULE'*'NAME. + + * Names used outside the module in which they are defined are of the + form MODULE'@'NAME. + + * Names associated with a particular environment are of the form + ENVIRONMENT':'NAME; these are used only within the 'par' module. + + * NAME does not have a module prefix. + + * Constructed names used to implement arrays are of the form + ARRAY'!'INDEX. + + Thus the 'groff' 'ms' macros reserve the following names. + + * Names containing the characters '*', '@', and ':'. + + * Names containing only uppercase letters and digits. + + +File: groff.info, Node: GNU troff Reference, Next: File Formats, Prev: Major Macro Packages, Up: Top + +5 GNU 'troff' Reference +*********************** + +This chapter covers _all_ of the facilities of the GNU 'troff' +formatting engine. Users of macro packages may skip it if not +interested in details. + +* Menu: + +* Text:: +* Page Geometry:: +* Measurements:: +* Numeric Expressions:: +* Identifiers:: +* Formatter Instructions:: +* Comments:: +* Registers:: +* Manipulating Filling and Adjustment:: +* Manipulating Hyphenation:: +* Manipulating Spacing:: +* Tabs and Fields:: +* Character Translations:: +* troff and nroff Modes:: +* Line Layout:: +* Line Continuation:: +* Page Layout:: +* Page Control:: +* Using Fonts:: +* Manipulating Type Size and Vertical Spacing:: +* Colors:: +* Strings:: +* Conditionals and Loops:: +* Writing Macros:: +* Page Motions:: +* Drawing Geometric Objects:: +* Deferring Output:: +* Traps:: +* Diversions:: +* Punning Names:: +* Environments:: +* Suppressing Output:: +* I/O:: +* Postprocessor Access:: +* Miscellaneous:: +* Gtroff Internals:: +* Debugging:: +* Implementation Differences:: + + +File: groff.info, Node: Text, Next: Measurements, Prev: GNU troff Reference, Up: GNU troff Reference + +5.1 Text +======== + +AT&T 'troff' was designed to take input as it would be composed on a +typewriter, including the teletypewriters used as early computer +terminals, and relieve the user drafting a document of concern with +details like line length, hyphenation breaking, and the achievement of +straight margins. Early in its development, the program gained the +ability to prepare output for a phototypesetter; a document could then +be prepared for output to either a teletypewriter, a phototypesetter, or +both. GNU 'troff' continues this tradition of permitting an author to +compose a single master version of a document which can then be rendered +for a variety of output formats or devices. + + 'roff' input files contain text interspersed with instructions to +control the formatter. Even in the absence of such instructions, GNU +'troff' still processes its input in several ways, by filling, +hyphenating, breaking, and adjusting it, and supplementing it with +inter-sentence space. + +* Menu: + +* Filling:: +* Hyphenation:: +* Sentences:: +* Breaking:: +* Adjustment:: +* Tabs and Leaders:: +* Requests and Macros:: +* Macro Packages:: +* Input Encodings:: +* Input Conventions:: + + +File: groff.info, Node: Filling, Next: Sentences, Prev: Text, Up: Text + +5.1.1 Filling +------------- + +When GNU 'troff' starts up, it obtains information about the device for +which it is preparing output.(1) (*note Filling-Footnote-1::) An +essential property is the length of the output line, such as "6.5 +inches". + + GNU 'troff' interprets plain text files employing the Unix +line-ending convention. It reads input a character at a time, +collecting words as it goes, and fits as many words together on an +output line as it can--this is known as "filling". To GNU 'troff', a +"word" is any sequence of one or more characters that aren't spaces or +newlines. The exceptions separate words.(2) (*note +Filling-Footnote-2::) To disable filling, see *note Manipulating Filling +and Adjustment::. + + It is a truth universally acknowledged + that a single man in possession of a + good fortune must be in want of a wife. + => It is a truth universally acknowledged that a + => single man in possession of a good fortune must + => be in want of a wife. + + +File: groff.info, Node: Filling-Footnotes, Up: Filling + + (1) *Note Device and Font Description Files::. + + (2) Tabs and leaders also separate words. Escape sequences can +function as word characters, word separators, or neither--the last +simply have no effect on GNU 'troff''s idea of whether an input +character is within a word. We'll discuss all of these in due course. + + +File: groff.info, Node: Sentences, Next: Hyphenation, Prev: Filling, Up: Text + +5.1.2 Sentences +--------------- + +A passionate debate has raged for decades among writers of the English +language over whether more space should appear between adjacent +sentences than between words within a sentence, and if so, how much, and +what other circumstances should influence this spacing.(1) (*note +Sentences-Footnote-1::) GNU 'troff' follows the example of AT&T 'troff'; +it attempts to detect the boundaries between sentences, and supplies +additional inter-sentence space between them. + + Hello, world! + Welcome to groff. + => Hello, world! Welcome to groff. + + GNU 'troff' flags certain characters (normally '!', '?', and '.') as +potentially ending a sentence. When GNU 'troff' encounters one of these +"end-of-sentence characters" at the end of an input line, or one of them +is followed by two (unescaped) spaces on the same input line, it appends +an inter-word space followed by an inter-sentence space in the output. + + R. Harper subscribes to a maxim of P. T. Barnum. + => R. Harper subscribes to a maxim of P. T. Barnum. + + In the above example, inter-sentence space is not added after 'P.' or +'T.' because the periods do not occur at the end of an input line, nor +are they followed by two or more spaces. Let's imagine that we've heard +something about defamation from Mr. Harper's attorney, recast the +sentence, and reflowed it in our text editor. + + I submit that R. Harper subscribes to a maxim of P. T. + Barnum. + => I submit that R. Harper subscribes to a maxim of + => P. T. Barnum. + + "Barnum" doesn't begin a sentence! What to do? Let us meet our +first "escape sequence", a series of input characters that give +instructions to GNU 'troff' instead of being used to construct output +device glyphs.(2) (*note Sentences-Footnote-2::) An escape sequence +begins with the backslash character '\' by default, an uncommon +character in natural language text, and is _always_ followed by at least +one other character, hence the term "sequence". + + The dummy character escape sequence '\&' can be used after an +end-of-sentence character to defeat end-of-sentence detection on a +per-instance basis. We can therefore rewrite our input more +defensively. + + I submit that R.\& Harper subscribes to a maxim of P.\& + T.\& Barnum. + => I submit that R. Harper subscribes to a maxim of + => P. T. Barnum. + + Adding text caused our input to wrap; now, we don't need '\&' after +'T.' but we do after 'P.'. Consistent use of the escape sequence +ensures that potential sentence boundaries are robust to editing +activities. Further advice along these lines will follow in *note Input +Conventions::. + + Normally, the occurrence of a visible non-end-of-sentence character +(as opposed to a space or tab) immediately after an end-of-sentence +character cancels detection of the end of a sentence. For example, it +would be incorrect for GNU 'troff' to infer the end of a sentence after +the dot in '3.14159'. However, several characters are treated +_transparently_ after the occurrence of an end-of-sentence character. +That is, GNU 'troff' does not cancel end-of-sentence detection when it +processes them. This is because such characters are often used as +footnote markers or to close quotations and parentheticals. The default +set is '"', ''', ')', ']', '*', '\[dg]', '\[dd]', '\[rq]', and '\[cq]'. +The last four are examples of "special characters", escape sequences +whose purpose is to obtain glyphs that are not easily typed at the +keyboard, or which have special meaning to GNU 'troff' (like '\' +itself).(3) (*note Sentences-Footnote-3::) + + \[lq]The idea that the poor should have leisure has always + been shocking to the rich.\[rq] + (Bertrand Russell, 1935) + => "The idea that the poor should have + => leisure has always been shocking to + => the rich." (Bertrand Russell, 1935) + + The sets of characters that potentially end sentences or are +transparent to sentence endings are configurable. See the 'cflags' +request in *note Using Symbols::. To change the additional +inter-sentence space amount--even to remove it entirely--see *note +Manipulating Filling and Adjustment::. + + +File: groff.info, Node: Sentences-Footnotes, Up: Sentences + + (1) A well-researched jeremiad appreciated by 'groff' contributors on +both sides of the sentence-spacing debate can be found at +. + + (2) This statement oversimplifies; there are escape sequences whose +purpose is precisely to produce glyphs on the output device, and input +characters that _aren't_ part of escape sequences can undergo a great +deal of processing before getting to the output. + + (3) The mnemonics for the special characters shown here are "dagger", +"double dagger", "right (double) quote", and "closing (single) quote". +See the 'groff_char(7)' man page. + + +File: groff.info, Node: Hyphenation, Next: Breaking, Prev: Sentences, Up: Text + +5.1.3 Hyphenation +----------------- + +When an output line is nearly full, it is uncommon for the next word +collected from the input to exactly fill it--typically, there is room +left over only for part of the next word. The process of splitting a +word so that it appears partially on one line (with a hyphen to indicate +to the reader that the word has been broken) with its remainder on the +next is "hyphenation". Hyphenation points can be manually specified; +GNU 'troff' also uses a hyphenation algorithm and language-specific +pattern files (based on those used in TeX) to decide which words can be +hyphenated and where. + + Hyphenation does not always occur even when the hyphenation rules for +a word allow it; it can be disabled, and when not disabled there are +several parameters that can prevent it in certain circumstances. *Note +Manipulating Hyphenation::. + + +File: groff.info, Node: Breaking, Next: Adjustment, Prev: Hyphenation, Up: Text + +5.1.4 Breaking +-------------- + +Once an output line is full, the next word (or remainder of a hyphenated +one) is placed on a different output line; this is called a "break". In +this manual and in 'roff' discussions generally, a "break" if not +further qualified always refers to the termination of an output line. +When the formatter is filling text, it introduces breaks automatically +to keep output lines from exceeding the configured line length. After +an automatic break, GNU 'troff' adjusts the line if applicable (see +below), and then resumes collecting and filling text on the next output +line. + + Sometimes, a line cannot be broken automatically. This usually does +not happen with natural language text unless the output line length has +been manipulated to be extremely short, but it can with specialized text +like program source code. We can use 'perl' at the shell prompt to +contrive an example of failure to break the line. We also employ the +'-z' option to suppress normal output. + + $ perl -e 'print "#" x 80, "\n";' | nroff -z + error-> warning: cannot break line + + The remedy for these cases is to tell GNU 'troff' where the line may +be broken without hyphens. This is done with the non-printing break +point escape sequence '\:'; see *note Manipulating Hyphenation::. + + What if the document author wants to stop filling lines temporarily, +for instance to start a new paragraph? There are several solutions. A +blank input line not only causes a break, but by default it also outputs +a one-line vertical space (effectively a blank output line). This +behavior can be modified; see *note Blank Line Traps::. Macro packages +may discourage or disable the blank line method of paragraphing in favor +of their own macros. + + A line that begins with one or more spaces causes a break. The +spaces are output at the beginning of the next line without being +_adjusted_ (see below); however, this behavior can be modified (*note +Leading Space Traps::). Again, macro packages may provide other methods +of producing indented paragraphs. Trailing spaces on text lines are +discarded.(1) (*note Breaking-Footnote-1::) + + What if the file ends before enough words have been collected to fill +an output line? Or the output line is exactly full but not yet broken, +and there is no more input? GNU 'troff' interprets the end of input as +a break. Certain requests also cause breaks, implicitly or explicitly. +This is discussed in *note Manipulating Filling and Adjustment::. + + +File: groff.info, Node: Breaking-Footnotes, Up: Breaking + + (1) "Text lines" are defined in *note Requests and Macros::. + + +File: groff.info, Node: Adjustment, Next: Tabs and Leaders, Prev: Breaking, Up: Text + +5.1.5 Adjustment +---------------- + +After GNU 'troff' performs an automatic break, it may then "adjust" the +line, widening inter-word spaces until the text reaches the right +margin. Extra spaces between words are preserved. Leading and trailing +spaces are handled as noted above. Text can be aligned to the left or +right margin only, or centered; see *note Manipulating Filling and +Adjustment::. + + +File: groff.info, Node: Tabs and Leaders, Next: Input Conventions, Prev: Adjustment, Up: Text + +5.1.6 Tabs and Leaders +---------------------- + +GNU 'troff' translates input horizontal tab characters ("tabs") and + characters ("leaders") into movements to the next tab stop. +Tabs simply move to the next tab stop; leaders place enough periods to +fill the space. Tab stops are by default located every half inch +measured from the drawing position corresponding to the beginning of the +input line; see *note Page Geometry::. Tabs and leaders do not cause +breaks and therefore do not interrupt filling. Below, we use arrows -> +and bullets * to indicate input tabs and leaders, respectively. + + 1 + -> 2 -> 3 * 4 + -> * 5 + => 1 2 3.......4 ........5 + + Tabs and leaders lend themselves to table construction.(1) (*note +Tabs and Leaders-Footnote-1::) The tab and leader glyphs can be +configured, and further facilities for sophisticated table composition +are available; see *note Tabs and Fields::. There are many details to +track when using such low-level features, so most users turn to the +'tbl(1)' preprocessor to lay out tables. + + +File: groff.info, Node: Tabs and Leaders-Footnotes, Up: Tabs and Leaders + + (1) "Tab" is short for "tabulation", revealing the term's origin as a +spacing mechanism for table arrangement. + + +File: groff.info, Node: Requests and Macros, Next: Macro Packages, Prev: Tabs and Leaders, Up: Text + +5.1.7 Requests and Macros +------------------------- + +We have now encountered almost all of the syntax there is in the 'roff' +language, with an exception already noted in passing. A "request" is an +instruction to the formatter that occurs after a "control character", +which is recognized at the beginning of an input line. The regular +control character is a dot ('.'). Its counterpart, the "no-break +control character", a neutral apostrophe ('''), suppresses the break +that is implied by some requests. These characters were chosen because +it is uncommon for lines of text in natural languages to begin with +them. If you require a formatted period or apostrophe (closing single +quotation mark) where GNU 'troff' is expecting a control character, +prefix the dot or neutral apostrophe with the dummy character escape +sequence, '\&'. + + An input line beginning with a control character is called a "control +line". Every line of input that is not a control line is a "text +line".(1) (*note Requests and Macros-Footnote-1::) + + Requests often take "arguments", words (separated from the request +name and each other by spaces) that specify details of the action GNU +'troff' is expected to perform. If a request is meaningless without +arguments, it is typically ignored. + + GNU 'troff''s requests and escape sequences comprise the control +language of the formatter. Of key importance are the requests that +define macros. Macros are invoked like requests, enabling the request +repertoire to be extended or overridden.(2) (*note Requests and +Macros-Footnote-2::) + + A "macro" can be thought of as an abbreviation you can define for a +collection of control and text lines. When the macro is "called" by +giving its name after a control character, it is replaced with what it +stands for. The process of textual replacement is known as +"interpolation".(3) (*note Requests and Macros-Footnote-3::) +Interpolations are handled as soon as they are recognized, and once +performed, a 'roff' formatter scans the replacement for further +requests, macro calls, and escape sequences. + + In 'roff' systems, the 'de' request defines a macro.(4) (*note +Requests and Macros-Footnote-4::) + + .de DATE + 2020-11-14 + .. + +The foregoing input produces no output by itself; all we have done is +store some information. Observe the pair of dots that ends the macro +definition. This is a default; you can specify your own terminator for +the macro definition as the second argument to the 'de' request. + + .de NAME ENDNAME + Heywood Jabuzzoff + .ENDNAME + + In fact, the ending marker is itself the name of a macro to be +called, or a request to be invoked, if it is defined at the time its +control line is read. + + .de END + Big Rip + .. + .de START END + Big Bang + .END + .START + => Big Rip Big Bang + +In the foregoing example, "Big Rip" printed before "Big Bang" because +its macro was _called_ first. Consider what would happen if we dropped +'END' from the '.de START' line and added '..' after '.END'. Would the +order change? + + Let us consider a more elaborate example. + + .de DATE + 2020-10-05 + .. + . + .de BOSS + D.\& Kruger, + J.\& Peterman + .. + . + .de NOTICE + Approved: + .DATE + by + .BOSS + .. + . + Insert tedious regulatory compliance paragraph here. + + .NOTICE + + Insert tedious liability disclaimer paragraph here. + + .NOTICE + => Insert tedious regulatory compliance paragraph here. + => + => Approved: 2020-10-05 by D. Kruger, J. Peterman + => + => Insert tedious liability disclaimer paragraph here. + => + => Approved: 2020-10-05 by D. Kruger, J. Peterman + +The above document started with a series of control lines. Three macros +were defined, with a 'de' request declaring each macro's name, and the +"body" of the macro starting on the next line and continuing until a +line with two dots ''..'' marked its end. The text proper began only +after the macros were defined; this is a common pattern. Only the +'NOTICE' macro was called "directly" by the document; 'DATE' and 'BOSS' +were called only by 'NOTICE' itself. Escape sequences were used in +'BOSS', two levels of macro interpolation deep. + + The advantage in typing and maintenance economy may not be obvious +from such a short example, but imagine a much longer document with +dozens of such paragraphs, each requiring a notice of managerial +approval. Consider what must happen if you are in charge of generating +a new version of such a document with a different date, for a different +boss. With well-chosen macros, you only have to change each datum in +one place. + + In practice, we would probably use strings (*note Strings::) instead +of macros for such simple interpolations; what is important here is to +glimpse the potential of macros and the power of recursive +interpolation. + + We could have defined 'DATE' and 'BOSS' in the opposite order; +perhaps less obviously, we could also have defined them _after_ +'NOTICE'. "Forward references" like this are acceptable because the +body of a macro definition is not (completely) interpreted, but stored +instead (*note Copy Mode::). While a macro is being defined (or +appended to), requests are not interpreted and macros not interpolated, +whereas some commonly used escape sequences _are_ interpreted. 'roff' +systems also support recursive macro calls, as long as you have a way to +break the recursion (*note Conditionals and Loops::). Maintainable +'roff' documents tend to arrange macro definitions to minimize forward +references. + + +File: groff.info, Node: Requests and Macros-Footnotes, Up: Requests and Macros + + (1) The '\' escape sequence can alter how an input line is +classified; see *note Line Continuation::. + + (2) Argument handling in macros is more flexible but also more +complex. *Note Calling Macros::. + + (3) Some escape sequences undergo interpolation as well. + + (4) GNU 'troff' offers additional ones. *Note Writing Macros::. + + +File: groff.info, Node: Macro Packages, Next: Input Encodings, Prev: Requests and Macros, Up: Text + +5.1.8 Macro Packages +-------------------- + +Macro definitions can be collected into "macro files", 'roff' input +files designed to produce no output themselves but instead ease the +preparation of other 'roff' documents. There is no syntactical +difference between a macro file and any other 'roff' document; only its +purpose distinguishes it. When a macro file is installed at a standard +location and suitable for use by a general audience, it is often termed +a "macro package".(1) (*note Macro Packages-Footnote-1::) Macro +packages can be loaded by supplying the '-m' option to GNU 'troff' or a +'groff' front end. Alternatively, a document requiring a macro package +can load it with the 'mso' ("macro source") request. + + +File: groff.info, Node: Macro Packages-Footnotes, Up: Macro Packages + + (1) Macro files and packages frequently define registers and strings +as well. + + +File: groff.info, Node: Input Encodings, Next: Input Conventions, Prev: Macro Packages, Up: Text + +5.1.9 Input Encodings +--------------------- + +The 'groff' command's '-k' option calls the 'preconv' preprocessor to +perform input character encoding conversions. Input to the GNU 'troff' +formatter itself, on the other hand, must be in one of two encodings it +can recognize. + +'cp1047' + The code page 1047 input encoding works only on EBCDIC platforms + (and conversely, the other input encodings don't work with EBCDIC); + the file 'cp1047.tmac' is loaded at startup. + +'latin1' + ISO Latin-1, an encoding for Western European languages, is the + default input encoding on non-EBCDIC platforms; the file + 'latin1.tmac' is loaded at startup. + +Any document that is encoded in ISO 646:1991 (a descendant of USAS +X3.4-1968 or "US-ASCII"), or, equivalently, uses only code points from +the "C0 Controls" and "Basic Latin" parts of the Unicode character set +is also a valid ISO Latin-1 document; the standards are interchangeable +in their first 128 code points.(1) (*note Input Encodings-Footnote-1::) + + Other encodings are supported by means of macro packages. + +'latin2' + To use ISO Latin-2, an encoding for Central and Eastern European + languages, invoke '.mso latin2.tmac' at the beginning of your + document or supply '-mlatin2' as a command-line argument to + 'groff'. + +'latin5' + To use ISO Latin-5, an encoding for the Turkish language, invoke + '.mso latin5.tmac' at the beginning of your document or supply + '-mlatin5' as a command-line argument to 'groff'. + +'latin9' + ISO Latin-9 succeeds Latin-1; it includes a Euro sign and better + glyph coverage for French. To use this encoding, invoke + '.mso latin9.tmac' at the beginning of your document or supply + '-mlatin9' as a command-line argument to 'groff'. + + Some characters from an input encoding may not be available with a +particular output driver, or their glyphs may not have representation in +the font used. For terminal devices, fallbacks are defined, like 'EUR' +for the Euro sign and '(C)' for the copyright sign. For typesetter +devices, you may need to "mount" fonts that support glyphs required by +the document. *Note Font Positions::. + + Because a Euro glyph was not historically defined in PostScript +fonts, 'groff' comes with a font called 'freeeuro.pfa' that provides the +Euro in several styles. Standard PostScript fonts contain the glyphs +from Latin-5 and Latin-9 that Latin-1 lacks, so these encodings are +supported for the 'ps' and 'pdf' output devices as 'groff' ships, while +Latin-2 is not. + + Unicode supports characters from all other input encodings; the +'utf8' output driver for terminals therefore does as well. The DVI +output driver supports the Latin-2 and Latin-9 encodings if the +command-line option '-mec' is used as well. (2) (*note Input +Encodings-Footnote-2::) + + +File: groff.info, Node: Input Encodings-Footnotes, Up: Input Encodings + + (1) The _semantics_ of certain punctuation code points have gotten +stricter with the successive standards, a cause of some frustration +among man page writers; see the 'groff_char(7)' man page. + + (2) The DVI output device defaults to using the Computer Modern (CM) +fonts; 'ec.tmac' loads the EC fonts instead, which provide Euro '\[Eu]' +and per mille '\[%0]' glyphs. + + +File: groff.info, Node: Input Conventions, Prev: Input Encodings, Up: Text + +5.1.10 Input Conventions +------------------------ + +Since GNU 'troff' fills text automatically, it is common practice in the +'roff' language to avoid visual composition of text in input files: the +esthetic appeal of the formatted output is what matters. Therefore, +'roff' input should be arranged such that it is easy for authors and +maintainers to compose and develop the document, understand the syntax +of 'roff' requests, macro calls, and preprocessor languages used, and +predict the behavior of the formatter. Several traditions have accrued +in service of these goals. + + * Follow sentence endings in the input with newlines to ease their + recognition (*note Sentences::). It is frequently convenient to + end text lines after colons and semicolons as well, as these + typically precede independent clauses. Consider doing so after + commas; they often occur in lists that become easy to scan when + itemized by line, or constitute supplements to the sentence that + are added, deleted, or updated to clarify it. Parenthetical and + quoted phrases are also good candidates for placement on text lines + by themselves. + + * Set your text editor's line length to 72 characters or fewer.(1) + (*note Input Conventions-Footnote-1::) This limit, combined with + the previous item of advice, makes it less common that an input + line will wrap in your text editor, and thus will help you perceive + excessively long constructions in your text. Recall that natural + languages originate in speech, not writing, and that punctuation is + correlated with pauses for breathing and changes in prosody. + + * Use '\&' after '!', '?', and '.' if they are followed by space, + tab, or newline characters and don't end a sentence. + + * In filled text lines, use '\&' before '.' and ''' if they are + preceded by space, so that reflowing the input doesn't turn them + into control lines. + + * Do not use spaces to perform indentation or align columns of a + table. Leading spaces are reliable when text is not being filled. + + * Comment your document. It is never too soon to apply comments to + record information of use to future document maintainers (including + your future self). We thus introduce another escape sequence, + '\"', which causes GNU 'troff' to ignore the remainder of the input + line. + + * Use the empty request--a control character followed immediately by + a newline--to visually manage separation of material in input + files. Many of the 'groff' project's own documents use an empty + request between sentences, after macro definitions, and where a + break is expected, and two empty requests between paragraphs or + other requests or macro calls that will introduce vertical space + into the document. + + You can combine the empty request with the comment escape sequence + to include whole-line comments in your document, and even "comment + out" sections of it. + + We conclude this section with an example sufficiently long to +illustrate most of the above suggestions in practice. For the purpose +of fitting the example between the margins of this manual with the font +used for its typeset version, we have shortened the input line length to +56 columns. As before, an arrow -> indicates a tab character. + + .\" nroff this_file.roff | less + .\" groff -T ps this_file.roff > this_file.ps + ->The theory of relativity is intimately connected with + the theory of space and time. + . + I shall therefore begin with a brief investigation of + the origin of our ideas of space and time, + although in doing so I know that I introduce a + controversial subject. \" remainder of paragraph elided + . + . + + ->The experiences of an individual appear to us arranged + in a series of events; + in this series the single events which we remember + appear to be ordered according to the criterion of + \[lq]earlier\[rq] and \[lq]later\[rq], \" punct swapped + which cannot be analysed further. + . + There exists, + therefore, + for the individual, + an I-time, + or subjective time. + . + This itself is not measurable. + . + I can, + indeed, + associate numbers with the events, + in such a way that the greater number is associated with + the later event than with an earlier one; + but the nature of this association may be quite + arbitrary. + . + This association I can define by means of a clock by + comparing the order of events furnished by the clock + with the order of a given series of events. + . + We understand by a clock something which provides a + series of events which can be counted, + and which has other properties of which we shall speak + later. + .\" Albert Einstein, _The Meaning of Relativity_, 1922 + + +File: groff.info, Node: Input Conventions-Footnotes, Up: Input Conventions + + (1) Emacs: 'fill-column: 72'; Vim: 'textwidth=72' + + +File: groff.info, Node: Page Geometry, Next: Measurements, Prev: Text, Up: GNU troff Reference + +5.2 Page Geometry +================= + +'roff' systems format text under certain assumptions about the size of +the output medium, or page. For the formatter to correctly break a line +it is filling, it must know the line length, which it derives from the +page width (*note Line Layout::). For it to decide whether to write an +output line to the current page or wait until the next one, it must know +the page length (*note Page Layout::). + + A device's "resolution" converts practical units like inches or +centimeters to "basic units", a convenient length measure for the output +device or file format. The formatter and output driver use basic units +to reckon page measurements. The device description file defines its +resolution and page dimensions (*note DESC File Format::). + + A "page" is a two-dimensional structure upon which a 'roff' system +imposes a rectangular coordinate system with its upper left corner as +the origin. Coordinate values are in basic units and increase down and +to the right. Useful ones are therefore always positive and within +numeric ranges corresponding to the page boundaries. + + While the formatter (and, later, output driver) is processing a page, +it keeps track of its "drawing position", which is the location at which +the next glyph will be written, from which the next motion will be +measured, or where a geometric object will commence rendering. +Notionally, glyphs are drawn from the text baseline upward and to the +right.(1) (*note Page Geometry-Footnote-1::) The "text baseline" is a +(usually invisible) line upon which the glyphs of a typeface are +aligned. A glyph therefore "starts" at its bottom-left corner. If +drawn at the origin, a typical letter glyph would lie partially or +wholly off the page, depending on whether, like "g", it features a +descender below the baseline. + + Such a situation is nearly always undesirable. It is furthermore +conventional not to write or draw at the extreme edges of the page. +Therefore the initial drawing position of a 'roff' formatter is not at +the origin, but below and to the right of it. This rightward shift from +the left edge is known as the "page offset".(2) (*note Page +Geometry-Footnote-2::) The downward shift leaves room for a text output +line. + + Text is arranged on a one-dimensional lattice of text baselines from +the top to the bottom of the page. "Vertical spacing" is the distance +between adjacent text baselines. Typographic tradition sets this +quantity to 120% of the type size. The initial drawing position is one +unit of vertical spacing below the page top. Typographers term this +unit a vee. + + Vertical spacing has an impact on page-breaking decisions. +Generally, when a break occurs, the formatter moves the drawing position +to the next text baseline automatically. If the formatter were already +writing to the last line that would fit on the page, advancing by one +vee would place the next text baseline off the page. Rather than let +that happen, 'roff' formatters instruct the output driver to eject the +page, start a new one, and again set the drawing position to one vee +below the page top; this is a "page break". + + When the last line of input text corresponds to the last output line +that fits on the page, the break caused by the end of input will also +break the page, producing a useless blank one. Macro packages keep +users from having to confront this difficulty by setting "traps" (*note +Traps::); moreover, all but the simplest page layouts tend to have +headers and footers, or at least bear vertical margins larger than one +vee. + + +File: groff.info, Node: Page Geometry-Footnotes, Up: Page Geometry + + (1) 'groff' does not yet support right-to-left scripts. + + (2) 'groff''s terminal output devices have page offsets of zero. + + +File: groff.info, Node: Measurements, Next: Numeric Expressions, Prev: Text, Up: GNU troff Reference + +5.3 Measurements +================ + +The formatter sometimes requires the input of numeric parameters to +specify measurements. These are specified as integers or decimal +fractions with an optional "scaling unit" suffixed. A scaling unit is a +letter that immediately follows the last digit of a number. Digits +after the decimal point are optional. Measurement expressions include +'10.5p', '11i', and '3.c'. + + Measurements are scaled by the scaling unit and stored internally +(with any fractional part discarded) in basic units. The device +resolution can therefore be obtained by storing a value of '1i' to a +register. The only constraint on the basic unit is that it is at least +as small as any other unit. + +'u' + Basic unit. + +'i' + Inch; defined as 2.54 centimeters. + +'c' + Centimeter; a centimeter is about 0.3937 inches. + +'p' + Point; a typesetter's unit used for measuring type size. There are + 72 points to an inch. + +'P' + Pica; another typesetter's unit. There are 6 picas to an inch and + 12 points to a pica. + +'s' +'z' + *Note Using Fractional Type Sizes::, for a discussion of these + units. + +'f' + GNU 'troff' defines this unit to scale decimal fractions in the + interval [0, 1] to 16-bit unsigned integers. It multiplies a + quantity by 65,536. *Note Colors::, for usage. + + The magnitudes of other scaling units depend on the text formatting +parameters in effect. These are useful when specifying measurements +that need to scale with the typeface or vertical spacing. + +'m' + Em; an em is equal to the current type size in points. It is named + thus because it is approximately the width of the letter 'M'. + +'n' + En; an en is one-half em. + +'v' + Vee; recall *note Page Geometry::. + +'M' + Hundredth of an em. + +* Menu: + +* Motion Quanta:: +* Default Units:: + + +File: groff.info, Node: Motion Quanta, Next: Default Units, Prev: Measurements, Up: Measurements + +5.3.1 Motion Quanta +------------------- + +An output device's basic unit 'u' is not necessarily its smallest +addressable length; 'u' can be smaller to avoid problems with integer +roundoff. The minimum distances that a device can work with in the +horizontal and vertical directions are termed its "motion quanta". +Measurements are rounded to applicable motion quanta. Half-quantum +fractions round toward zero. + + -- Register: \n[.H] + -- Register: \n[.V] + These read-only registers interpolate the horizontal and vertical + motion quanta, respectively, of the output device in basic units. + + For example, we might draw short baseline rules on a terminal device +as follows. *Note Drawing Geometric Objects::. + + .tm \n[.H] + error-> 24 + .nf + \l'36u' 36u + \l'37u' 37u + => _ 36u + => __ 37u + + +File: groff.info, Node: Default Units, Prev: Motion Quanta, Up: Measurements + +5.3.2 Default Units +------------------- + +A general-purpose register (one created or updated with the 'nr' +request; see *note Registers::) is implicitly dimensionless, or reckoned +in basic units if interpreted in a measurement context. But it is +convenient for many requests and escape sequences to infer a scaling +unit for an argument if none is specified. An explicit scaling unit +(not after a closing parenthesis) can override an undesirable default. +Effectively, the default unit is suffixed to the expression if a scaling +unit is not already present. GNU 'troff''s use of integer arithmetic +should also be kept in mind (*note Numeric Expressions::). + + The 'll' request interprets its argument in ems by default. Consider +several attempts to set a line length of 3.5 inches when the type size +is 10 points on a terminal device with a resolution of 240 basic units +and horizontal motion quantum of 24. Some expressions become zero; the +request clamps them to that quantum. + + .ll 3.5i \" 3.5i (= 840u) + .ll 7/2 \" 7u/2u -> 3u -> 3m -> 0, clamped to 24u + .ll (7 / 2)u \" 7u/2u -> as above + .ll 7/2i \" 7u/2i -> 7u/480u -> 0 -> as above + .ll 7i/2 \" 7i/2u -> 1680u/2m -> 1680u/24u -> 35u + .ll 7i/2u \" 3.5i (= 840u) + +The safest way to specify measurements is to attach a scaling unit. To +multiply or divide by a dimensionless quantity, use 'u' as its scaling +unit. + + +File: groff.info, Node: Numeric Expressions, Next: Identifiers, Prev: Measurements, Up: GNU troff Reference + +5.4 Numeric Expressions +======================= + +A "numeric expression" evaluates to an integer: it can be as simple as a +literal '0' or it can be a complex sequence of register and string +interpolations interleaved with measurements and operators. + + GNU 'troff' provides a set of mathematical and logical operators +familiar to programmers--as well as some unusual ones--but supports only +integer arithmetic.(1) (*note Numeric Expressions-Footnote-1::) The +internal data type used for computing results is usually a 32-bit signed +integer, which suffices to represent magnitudes within a range of ±2 +billion.(2) (*note Numeric Expressions-Footnote-2::) + + Arithmetic infix operators perform a function on the numeric +expressions to their left and right; they are '+' (addition), '-' +(subtraction), '*' (multiplication), '/' (truncating division), and '%' +(modulus). "Truncating division" rounds to the integer nearer to zero, +no matter how large the fractional portion. Overflow and division (or +modulus) by zero are errors and abort evaluation of a numeric +expression. + + Arithmetic unary operators operate on the numeric expression to their +right; they are '-' (negation) and '+' (assertion--for completeness; it +does nothing). The unary minus must often be used with parentheses to +avoid confusion with the decrementation operator, discussed below. + + Observe the rounding behavior and effect of negative operands on the +modulus and truncating division operators. + + .nr T 199/100 + .nr U 5/2 + .nr V (-5)/2 + .nr W 5/-2 + .nr X 5%2 + .nr Y (-5)%2 + .nr Z 5%-2 + T=\n[T] U=\n[U] V=\n[V] W=\n[W] X=\n[X] Y=\n[Y] Z=\n[Z] + => T=1 U=2 V=-2 W=-2 X=1 Y=-1 Z=1 + +The sign of the modulus of operands of mixed signs is determined by the +sign of the first. Division and modulus operators satisfy the following +property: given a dividend A and a divisor B, a quotient Q formed by '(a +/ b)' and a remainder R by '(a % b)', then qb + r = a. + + GNU 'troff''s scaling operator, used with parentheses as '(C;E)', +evaluates a numeric expression E using C as the default scaling unit. +If C is omitted, scaling units are ignored in the evaluation of E. This +operator can save typing by avoiding the attachment of scaling units to +every operand out of caution. Your macros can select a sensible default +unit in case the user neglects to supply one. + + .\" Indent by amount given in first argument; assume ens. + .de Indent + . in (n;\\$1) + .. + +Without the scaling operator, the foregoing macro would, if called with +a unitless argument, cause indentation by the 'in' request's default +scaling unit (ems). The result would be twice as much indentation as +expected. + + GNU 'troff' also provides a pair of operators to compute the extrema +of two operands: '>?' (maximum) and ' Looks like we'll end up paying 3 salaries. + + Comparison operators comprise '<' (less than), '>' (greater than), +'<=' (less than or equal), '>=' (greater than or equal), and '=' +(equal). '==' is a synonym for '='. When evaluated, a comparison is +replaced with '0' if it is false and '1' if true. In the 'roff' +language, positive values are true, others false. + + We can operate on truth values with the logical operators '&' +(logical conjunction or "and") and ':' (logical disjunction or "or"). +They evaluate as comparison operators do. + + A logical complementation ("not") operator, '!', works only within +'if', 'ie', and 'while' requests. Furthermore, '!' is recognized only +at the beginning of a numeric expression not contained by another +numeric expression. In other words, it must be the "outermost" +operator. Including it elsewhere in the expression produces a warning +in the 'number' category (*note Warnings::), and its expression +evaluates false. This unfortunate limitation maintains compatibility +with AT&T 'troff'. Test a numeric expression for falsity by comparing +it to a false value.(3) (*note Numeric Expressions-Footnote-3::) + + .nr X 1 + .nr Y 0 + .\" This does not work as expected. + .if (\n[X])&(!\n[Y]) .nop A: X is true, Y is false + . + .\" Use this construct instead. + .if (\n[X])&(\n[Y]<=0) .nop B: X is true, Y is false + error-> warning: expected numeric expression, got '!' + => B: X is true, Y is false + + The 'roff' language has no operator precedence: expressions are +evaluated strictly from left to right, in contrast to schoolhouse +arithmetic. Use parentheses '(' ')' to impose a desired precedence upon +subexpressions. + + .nr X 3+5*4 + .nr Y (3+5)*4 + .nr Z 3+(5*4) + X=\n[X] Y=\n[Y] Z=\n[Z] + => X=32 Y=32 Z=23 + + For many requests and escape sequences that cause motion on the page, +the unary operators '+' and '-' work differently when leading a numeric +expression. They then indicate a motion relative to the drawing +position: positive is down in vertical contexts, right in horizontal +ones. + + '+' and '-' are also treated differently by the following requests +and escape sequences: 'bp', 'in', 'll', 'lt', 'nm', 'nr', 'pl', 'pn', +'po', 'ps', 'pvs', 'rt', 'ti', '\H', '\R', and '\s'. Here, leading plus +and minus signs serve as incrementation and decrementation operators, +respectively. To negate an expression, subtract it from zero or include +the unary minus in parentheses with its argument. *Note Setting +Registers::, for examples. + + A leading '|' operator indicates a motion relative not to the drawing +position but to a boundary. For horizontal motions, the measurement +specifies a distance relative to a drawing position corresponding to the +beginning of the _input_ line. By default, tab stops reckon movements +in this way. Most escape sequences do not; '|' tells them to do so. + + Mind the \h'1.2i'gap. + .br + Mind the \h'|1.2i'gap. + .br + Mind the + \h'|1.2i'gap. + => Mind the gap. + => Mind the gap. + => Mind the gap. + + One use of this feature is to define macros whose scope is limited to +the output they format. + + .\" underline word $1 with trailing punctuation $2 + .de Underline + . nop \\$1\l'|0\[ul]'\\$2 + .. + Typographical emphasis is best used + .Underline sparingly . + +In the above example, '|0' specifies a negative motion from the current +position (at the end of the argument just emitted, '\$1') to the +beginning of the input line. Thus, the '\l' escape sequence in this +case draws a line from right to left. A macro call occurs at the +beginning of an input line;(4) (*note Numeric Expressions-Footnote-4::) +if the '|' operator were omitted, then the underline would be drawn at +zero distance from the current position, producing device-dependent, and +likely undesirable, results. On the 'ps' output device, it underlines +the period. + + For vertical motions, the '|' operator specifies a distance from the +first text baseline on the page or in the current diversion,(5) (*note +Numeric Expressions-Footnote-5::) using the current vertical spacing. + + A + .br + B \Z'C'\v'|0'D + => A D + => B C + + In the foregoing example, we've used the '\Z' escape sequence (*note +Page Motions::) to restore the drawing position after formatting 'C', +then moved vertically to the first text baseline on the page. + + -- Escape sequence: \B'anything' + Interpolate 1 if ANYTHING is a valid numeric expression, and 0 + otherwise. The delimiter need not be a neutral apostrophe; see + *note Delimiters::. + + You might use '\B' along with the 'if' request to filter out invalid +macro or string arguments. *Note Conditionals and Loops::. + + .\" Indent by amount given in first argument; assume ens. + .de Indent + . if \B'\\$1' .in (n;\\$1) + .. + + A register interpolated as an operand in a numeric expression must +have an Arabic format; luckily, this is the default. *Note Assigning +Register Formats::. + + Because spaces separate arguments to requests, spaces are not allowed +in numeric expressions unless the (sub)expression containing them is +surrounded by parentheses. *Note Invoking Requests::, and *note +Conditionals and Loops::. + + .nf + .nr a 1+2 + 2+1 + \na + error-> expected numeric expression, got a space + => 3 + .nr a 1+(2 + 2)+1 + \na + => 6 + + The 'nr' request (*note Setting Registers::) expects its second and +optional third arguments to be numeric expressions; a bare '+' does not +qualify, so our first attempt got a warning. + + +File: groff.info, Node: Numeric Expressions-Footnotes, Up: Numeric Expressions + + (1) Provision is made for interpreting and reporting decimal +fractions in certain cases. + + (2) If that's not enough, see the 'groff_tmac(5)' man page for the +'62bit.tmac' macro package. + + (3) *Note Conditionals and Loops::. + + (4) Control structure syntax creates an exception to this rule, but +is designed to remain useful: recalling our example, '.if 1 .Underline +this' would underline only "this", precisely. *Note Conditionals and +Loops::. + + (5) *Note Diversions::. + + +File: groff.info, Node: Identifiers, Next: Formatter Instructions, Prev: Numeric Expressions, Up: GNU troff Reference + +5.5 Identifiers +=============== + +An "identifier" labels a GNU 'troff' datum such as a register, name +(macro, string, or diversion), typeface, color, special character, +character class, environment, or stream. Valid identifiers consist of +one or more ordinary characters. An ordinary character is an input +character that is not the escape character, a leader, tab, newline, or +invalid as GNU 'troff' input. + + Invalid input characters are a subset of control characters (from the +sets "C0 Controls" and "C1 Controls" as Unicode describes them). When +GNU 'troff' encounters one in an identifier, it produces a warning in +category 'input' (*note Warnings::). They are removed during +interpretation: an identifier 'foo', followed by an invalid character +and then 'bar', is processed as 'foobar'. + + On a machine using the ISO 646, 8859, or 10646 character encodings, +invalid input characters are '0x00', '0x08', '0x0B', '0x0D'-'0x1F', and +'0x80'-'0x9F'. On an EBCDIC host, they are '0x00'-'0x01', '0x08', +'0x09', '0x0B', '0x0D'-'0x14', '0x17'-'0x1F', and '0x30'-'0x3F'.(1) +(*note Identifiers-Footnote-1::) Some of these code points are used by +GNU 'troff' internally, making it non-trivial to extend the program to +accept UTF-8 or other encodings that use characters from these +ranges.(2) (*note Identifiers-Footnote-2::) + + Thus, the identifiers 'br', 'PP', 'end-list', 'ref*normal-print', +'|', '@_', and '!"#$%'()*+,-./' are all valid. Discretion should be +exercised to prevent confusion. Identifiers starting with '(' or '[' +require care. + + .nr x 9 + .nr y 1 + .nr (x 2 + .nr [y 3 + .nr sum1 (\n(x + \n[y]) + error-> a space character is not allowed in an escape + error-> sequence parameter + A:2+3=\n[sum1] + .nr sum2 (\n((x + \n[[y]) + B:2+3=\n[sum2] + .nr sum3 (\n[(x] + \n([y) + C:2+3=\n[sum3] + => A:2+3=1 B:2+3=5 C:2+3=5 + +An identifier with a closing bracket (']') in its name can't be accessed +with bracket-form escape sequences that expect an identifier as a +parameter. For example, '\[foo]]' accesses the glyph 'foo', followed by +']' in whatever the surrounding context is, whereas '\C'foo]'' formats a +glyph named 'foo]'. Similarly, the identifier '(' can't be interpolated +_except_ with bracket forms. + + If you begin a macro, string, or diversion name with either of the +characters '[' or ']', you foreclose use of the 'grefer' preprocessor, +which recognizes '.[' and '.]' as bibliographic reference delimiters. + + -- Escape sequence: \A'anything' + Interpolate 1 if ANYTHING is a valid identifier, and 0 otherwise. + The delimiter need not be a neutral apostrophe; see *note + Delimiters::. Because invalid input characters are removed (see + above), invalid identifiers are empty or contain spaces, tabs, or + newlines. + + You can employ '\A' to validate a macro argument before using it to + construct another escape sequence or identifier. + + .\" usage: .init-coordinate-pair name val1 val2 + .\" Create a coordinate pair where name!x=val1 and + .\" name!y=val2. + .de init-coordinate-pair + . if \A'\\$1' \{\ + . if \B'\\$2' .nr \\$1!x \\$2 + . if \B'\\$3' .nr \\$1!y \\$3 + . \} + .. + .init-coordinate-pair center 5 10 + The center is at (\n[center!x], \n[center!y]). + .init-coordinate-pair "poi->nt" trash garbage \" ignored + .init-coordinate-pair point trash garbage \" ignored + => The center is at (5, 10). + + In this example, we also validated the numeric arguments; the + registers 'point!x' and 'point!y' remain undefined. *Note Numeric + Expressions:: for the '\B' escape sequence. + + How GNU 'troff' handles the interpretation of an undefined identifier +depends on the context. There is no way to invoke an undefined request; +such syntax is interpreted as a macro call instead. If the identifier +is interpreted as a string, macro, or diversion, GNU 'troff' emits a +warning in category 'mac', defines it as empty, and interpolates +nothing. If the identifier is interpreted as a register, GNU 'troff' +emits a warning in category 'reg', initializes it to zero, and +interpolates that value. *Note Warnings::, *note Interpolating +Registers::, and *note Strings::. Attempting to use an undefined +typeface, special character, color, character class, environment, or +stream generally provokes an error diagnostic. + + Identifiers for requests, macros, strings, and diversions share one +name space; special characters and character classes another. No other +object types do. + + .de xxx + . nop foo + .. + .di xxx + bar + .br + .di + . + .xxx + => bar + +The foregoing example shows that GNU 'troff' reuses the identifier +'xxx', changing it from a macro to a diversion. No warning is emitted, +and the previous contents of 'xxx' are lost. + + +File: groff.info, Node: Identifiers-Footnotes, Up: Identifiers + + (1) Historically, control characters like ASCII STX, ETX, and BEL +(, , and ) have been observed in 'roff' +documents, particularly in macro packages employing them as delimiters +with the output comparison operator to try to avoid collisions with the +content of arbitrary user-supplied parameters (*note Operators in +Conditionals::). We discourage this expedient; in GNU 'troff' it is +unnecessary (outside of compatibility mode) because delimited arguments +are parsed at a different input level than the surrounding context. +*Note Implementation Differences::. + + (2) Consider what happens when a C1 control '0x80'-'0x9F' is +necessary as a continuation byte in a UTF-8 sequence. + + +File: groff.info, Node: Formatter Instructions, Next: Registers, Prev: Identifiers, Up: GNU troff Reference + +5.6 Formatter Instructions +========================== + +To support documents that require more than filling, automatic line +breaking and hyphenation, adjustment, and supplemental inter-sentence +space, the 'roff' language offers two means of embedding instructions to +the formatter. + + One is a "request", which begins with a control character and takes +up the remainder of the input line. Requests often perform relatively +large-scale operations such as setting the page length, breaking the +line, or starting a new page. They also conduct internal operations +like defining macros. + + The other is an "escape sequence", which begins with the escape +character and can be embedded anywhere in the input, even in arguments +to requests and other escape sequences. Escape sequences interpolate +special characters, strings, or registers, and handle comparatively +minor formatting tasks like sub- and superscripting. + + Some operations, such as font selection and type size alteration, are +available via both requests and escape sequences. + +* Menu: + +* Control Characters:: +* Invoking Requests:: +* Calling Macros:: +* Using Escape Sequences:: +* Delimiters:: + + +File: groff.info, Node: Control Characters, Next: Invoking Requests, Prev: Formatter Instructions, Up: Formatter Instructions + +5.6.1 Control Characters +------------------------ + +The mechanism of using 'roff''s control characters to invoke requests +and call macros was introduced in *note Requests and Macros::. Control +characters are recognized only at the beginning of an input line, or at +the beginning of the branch of a control structure request; see *note +Conditionals and Loops::. + + A few requests cause a break implicitly; use the no-break control +character to prevent the break. Break suppression is its sole +behavioral distinction. Employing the no-break control character to +invoke requests that don't cause breaks is harmless but poor style. +*Note Manipulating Filling and Adjustment::. + + The control '.' and no-break control ''' characters can each be +changed to any ordinary character(1) (*note Control +Characters-Footnote-1::) with the 'cc' and 'c2' requests, respectively. + + -- Request: .cc [o] + Recognize the ordinary character O as the control character. If O + is absent or invalid, the default control character '.' is + selected. The identity of the control character is associated with + the environment (*note Environments::). + + -- Request: .c2 [o] + Recognize the ordinary character O as the no-break control + character. If O is absent or invalid, the default no-break control + character ''' is selected. The identity of the no-break control + character is associated with the environment (*note + Environments::). + + When writing a macro, you might wish to know which control character +was used to call it. + + -- Register: \n[.br] + This read-only register interpolates 1 if the currently executing + macro was called using the normal control character and 0 + otherwise. If a macro is interpolated as a string, the '.br' + register's value is inherited from the context of the string + interpolation. *Note Strings::. + + Use this register to reliably intercept requests that imply breaks. + + .als bp*orig bp + .de bp + . ie \\n[.br] .bp*orig + . el 'bp*orig + .. + + Testing the '.br' register outside of a macro definition makes no + sense. + + +File: groff.info, Node: Control Characters-Footnotes, Up: Control Characters + + (1) Recall *note Identifiers::. + + +File: groff.info, Node: Invoking Requests, Next: Calling Macros, Prev: Control Characters, Up: Formatter Instructions + +5.6.2 Invoking Requests +----------------------- + +A control character is optionally followed by tabs and/or spaces and +then an identifier naming a request or macro. The invocation of an +unrecognized request is interpreted as a macro call. Defining a macro +with the same name as a request replaces the request. Deleting a +request name with the 'rm' request makes it unavailable. The 'als' +request can alias requests, permitting them to be wrapped or +non-destructively replaced. *Note Strings::. + + There is no inherent limit on argument length or quantity. Most +requests take one or more arguments, and ignore any they do not expect. +A request may be separated from its arguments by tabs or spaces, but +only spaces can separate an argument from its successor. Only one +between arguments is necessary; any excess is ignored. GNU 'troff' does +not allow tabs for argument separation.(1) (*note Invoking +Requests-Footnote-1::) + + Generally, a space _within_ a request argument is not relevant, not +meaningful, or is supported by bespoke provisions, as with the 'tl' +request's delimiters (*note Page Layout::). Some requests, like 'ds', +interpret the remainder of the control line as a single argument. *Note +Strings::. + + Spaces and tabs immediately after a control character are ignored. +Commonly, authors structure the source of documents or macro files with +them. + + .de center + . if \\n[.br] \ + . br + . ce \\$1 + .. + . + . + .de right-align + .->if \\n[.br] \ + .->->br + .->rj \\$1 + .. + + If you assign an empty blank line trap, you can separate macro +definitions (or any input lines) with blank lines. + + .de do-nothing + .. + .blm do-nothing \" activate blank line trap + + .de center + . if \\n[.br] \ + . br + . ce \\$1 + .. + + + .de right-align + .->if \\n[.br] \ + .->->br + .->rj \\$1 + .. + + .blm \" deactivate blank line trap + + *Note Blank Line Traps::. + + +File: groff.info, Node: Invoking Requests-Footnotes, Up: Invoking Requests + + (1) In compatibility mode, a space is not necessary after a request +or macro name of two characters' length. Also, Plan 9 'troff' allows +tabs to separate arguments. + + +File: groff.info, Node: Calling Macros, Next: Using Escape Sequences, Prev: Invoking Requests, Up: Formatter Instructions + +5.6.3 Calling Macros +-------------------- + +If a macro of the desired name does not exist when called, it is +created, assigned an empty definition, and a warning in category 'mac' +is emitted. Calling an undefined macro _does_ end a macro definition +naming it as its end macro (*note Writing Macros::). + + To embed spaces _within_ a macro argument, enclose the argument in +neutral double quotes '"'. Horizontal motion escape sequences are +sometimes a better choice for arguments to be formatted as text. + + Consider calls to a hypothetical section heading macro 'uh'. + + .uh The Mouse Problem + .uh "The Mouse Problem" + .uh The\~Mouse\~Problem + .uh The\ Mouse\ Problem + +The first line calls 'uh' with three arguments: 'The', 'Mouse', and +'Problem'. The remainder call the 'uh' macro with one argument, 'The +Mouse Problem'. The last solution, using escaped spaces, can be found +in documents prepared for AT&T 'troff'. It can cause surprise when text +is adjusted, because '\' inserts a _fixed-width_, non-breaking +space. GNU 'troff''s '\~' escape sequence inserts an adjustable, +non-breaking space.(1) (*note Calling Macros-Footnote-1::) + + The foregoing raises the question of how to embed neutral double +quotes or backslashes in macro arguments when _those_ characters are +desired as literals. In GNU 'troff', the special character escape +sequence '\[rs]' produces a backslash and '\[dq]' a neutral double +quote. + + In GNU 'troff''s AT&T compatibility mode, these characters remain +available as '\(rs' and '\(dq', respectively. AT&T 'troff' did not +consistently define these special characters, but its descendants can be +made to support them. *Note Device and Font Description Files::. + + If even that is not feasible, options remain. To obtain a literal +escape character in a macro argument, you can simply type it if you +change or disable the escape character first. *Note Using Escape +Sequences::. Otherwise, you must escape the escape character repeatedly +to a context-dependent extent. *Note Copy Mode::. + + For the (neutral) double quote, you have recourse to an obscure +syntactical feature of AT&T 'troff'. Because a double quote can begin a +macro argument, the formatter keeps track of whether the current +argument was started thus, and doesn't require a space after the double +quote that ends it.(2) (*note Calling Macros-Footnote-2::) In the +argument list to a macro, a double quote that _isn't_ preceded by a +space _doesn't_ start a macro argument. If not preceded by a double +quote that began an argument, this double quote becomes part of the +argument. Furthermore, within a quoted argument, a pair of adjacent +double quotes becomes a literal double quote. + + .de eq + . tm arg1:\\$1 arg2:\\$2 arg3:\\$3 + . tm arg4:\\$4 arg5:\\$5 arg6:\\$6 + .. \" 4 backslashes on the next line + .eq a" "b c" "de"f\\\\g" h""i "j""k" + error-> arg1:a" arg2:b c arg3:de + error-> arg4:f\g" arg5:h""i arg6:j"k + + Apart from the complexity of the rules, this traditional solution has +the disadvantage that double quotes don't survive repeated argument +expansion in AT&T 'troff' or GNU 'troff''s compatibility mode. This can +frustrate efforts to pass such arguments intact through multiple macro +calls. + + .cp 1 + .de eq + . tm arg1:\\$1 arg2:\\$2 arg3:\\$3 + . tm arg4:\\$4 arg5:\\$5 arg6:\\$6 + .. + .de xe + . eq \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 + .. \" 8 backslashes on the next line + .xe a" "b c" "de"f\\\\\\\\g" h""i "j""k" + error-> arg1:a" arg2:b arg3:c + error-> arg4:de arg5:f\g" arg6:h""i + + Outside of compatibility mode, GNU 'troff' doesn't exhibit this +problem because it tracks the nesting depth of interpolations. *Note +Implementation Differences::. + + +File: groff.info, Node: Calling Macros-Footnotes, Up: Calling Macros + + (1) '\~' is fairly portable; see *note Other Differences::. + + (2) Strictly, you can neglect to close the last quoted macro +argument, relying on the end of the control line to do so. We consider +this lethargic practice poor style. + + +File: groff.info, Node: Using Escape Sequences, Next: Delimiters, Prev: Calling Macros, Up: Formatter Instructions + +5.6.4 Using Escape Sequences +---------------------------- + +Whereas requests must occur on control lines, escape sequences can occur +intermixed with text and may appear in arguments to requests, macros, +and other escape sequences. An escape sequence is introduced by the +escape character, a backslash '\' (but see the 'ec' request below). The +next character selects the escape's function. + + Escape sequences vary in length. Some take an argument, and of +those, some have different syntactical forms for a one-character, +two-character, or arbitrary-length argument. Others accept _only_ an +arbitrary-length argument. In the former scheme, a one-character +argument follows the function character immediately, an opening +parenthesis '(' introduces a two-character argument (no closing +parenthesis is used), and an argument of arbitrary length is enclosed in +brackets '[]'. In the latter scheme, the user selects a delimiter +character. A few escape sequences are idiosyncratic, and support both +of the foregoing conventions ('\s'), designate their own termination +sequence ('\?'), consume input until the next newline ('\!', '\"', +'\#'), or support an additional modifier character ('\s' again, and +'\n'). As with requests, use of some escape sequences in source +documents may interact poorly with a macro package you use; consult its +documentation to learn of "safe" sequences or alternative facilities it +provides to achieve the desired result. + + If an escape character is followed by a character that does not +identify a defined operation, the escape character is ignored (producing +a diagnostic of the 'escape' warning category, which is not enabled by +default) and the following character is processed normally. + + $ groff -Tps -ww + .nr N 12 + .ds co white + .ds animal elephant + I have \fI\nN \*(co \*[animal]s,\f[] + said \P.\&\~Pseudo Pachyderm. + error-> warning: escape character ignored before 'P' + => I have 12 white elephants, said P. Pseudo Pachyderm. + + Escape sequence interpolation is of higher precedence than escape +sequence argument interpretation. This rule affords flexibility in +using escape sequences to construct parameters to other escape +sequences. + + .ds family C\" Courier + .ds style I\" oblique + Choice a typeface \f(\*[family]\*[style]wisely. + => Choose a typeface wisely. + +In the above, the syntax form '\f(' accepts only two characters for an +argument; the example works because the subsequent escape sequences are +interpolated before the selection escape sequence argument is processed, +and strings 'family' and 'style' interpolate one character each.(1) +(*note Using Escape Sequences-Footnote-1::) + + The escape character is nearly always interpreted when encountered; +it is therefore desirable to have a way to interpolate it, disable it, +or change it. + + -- Escape sequence: \e + Interpolate the escape character. + + The '\[rs]' special character escape sequence formats a backslash +glyph. In macro and string definitions, the input sequences '\\' and +'\E' defer interpretation of escape sequences. *Note Copy Mode::. + + -- Request: .eo + Disable the escape mechanism except in copy mode. Once this + request is invoked, no input character is recognized as starting an + escape sequence in interpretation mode. + + -- Request: .ec [o] + Recognize the ordinary character O as the escape character. If O + is absent or invalid, the default escape character '\' is selected. + + Switching escape sequence interpretation off to define a macro and +back on afterward can obviate the need to double the escape character +within the definition. *Note Writing Macros::. This technique is not +available if your macro needs to interpolate values at the time it is +_defined_--but many do not. + + .\" simplified `BR` macro from the man(7) macro package + .eo + .de BR + . ds result \& + . while (\n[.$] >= 2) \{\ + . as result \fB\$1\fR\$2\" + . shift 2 + . \} + . if \n[.$] .as result \fB\$1\" + \*[result] + . rm result + . ft R + .. + .ec + + -- Request: .ecs + -- Request: .ecr + The 'ecs' request stores the escape character for recall with + 'ecr'. 'ecr' sets the escape character to '\' if none has been + saved. + + Use these requests together to temporarily change the escape + character. + + Using a different escape character, or disabling it, when calling +macros not under your control will likely cause errors, since GNU +'troff' has no mechanism to "intern" macros--that is, to convert a macro +definition into a form independent of its representation.(2) (*note +Using Escape Sequences-Footnote-2::) When a macro is called, its +contents are interpreted literally. + + +File: groff.info, Node: Using Escape Sequences-Footnotes, Up: Using Escape Sequences + + (1) The omission of spaces before the comment escape sequences is +necessary; see *note Strings::. + + (2) TeX does have such a mechanism. + + +File: groff.info, Node: Delimiters, Prev: Using Escape Sequences, Up: Formatter Instructions + +5.6.5 Delimiters +---------------- + +Some escape sequences that require parameters use delimiters. The +neutral apostrophe ''' is a popular choice and shown in this document. +The neutral double quote '"' is also commonly seen. Letters, numerals, +and leaders can be used. Punctuation characters are likely better +choices, except for those defined as infix operators in numeric +expressions; see below. + + \l'1.5i\[bu]' \" draw 1.5 inches of bullet glyphs + + The following escape sequences don't take arguments and thus are +allowed as delimiters: '\', '\%', '\|', '\^', '\{', '\}', '\'', +'\`', '\-', '\_', '\!', '\?', '\)', '\/', '\,', '\&', '\:', '\~', '\0', +'\a', '\c', '\d', '\e', '\E', '\p', '\r', '\t', and '\u'. However, +using them this way is discouraged; they can make the input confusing to +read. + + A few escape sequences, '\A', '\b', '\o', '\w', '\X', and '\Z', +accept a newline as a delimiter. Newlines that serve as delimiters +continue to be recognized as input line terminators. + + A caf\o + e\(aa + in Paris + => A café in Paris + +Use of newlines as delimiters in escape sequences is also discouraged. + + Finally, the escape sequences '\D', '\h', '\H', '\l', '\L', '\N', +'\R', '\s', '\S', '\v', and '\x' prohibit many delimiters. + + * the numerals '0'-'9' and the decimal point '.' + + * the (single-character) operators '+-/*%<>=&:()' + + * the space and tab characters + + * any escape sequences other than '\%', '\:', '\{', '\}', '\'', '\`', + '\-', '\_', '\!', '\/', '\c', '\e', and '\p' + + Delimiter syntax is complex and flexible primarily for historical +reasons; the foregoing restrictions need be kept in mind mainly when +using 'groff' in AT&T compatibility mode. GNU 'troff' keeps track of +the nesting depth of escape sequence interpolations, so the only +characters you need to avoid using as delimiters are those that appear +in the arguments you input, not any that result from interpolation. +Typically, ''' works fine. *Note Implementation Differences::. + + $ groff -Tps + .de Mw + . nr wd \w'\\$1' + . tm "\\$1" is \\n(wd units wide. + .. + .Mw Wet'suwet'en + .Mw Wet+200i + .cp 1 \" turn on compatibility mode + .Mw Wet'suwet'en + .Mw Wet' + .Mw Wet+200i + error-> "Wet'suwet'en" is 54740 units wide. + error-> "Wet'+200i" is 42610 units wide. + error-> "Wet'suwet'en" is 15860 units wide. + error-> "Wet'" is 15860 units wide. + error-> "Wet'+200i" is 14415860 units wide. + + We see here that in compatibility mode, the part of the argument +after the ''' delimiter escapes from its context and, if nefariously +crafted, influences the computation of the WD register's value in a +surprising way. + + +File: groff.info, Node: Comments, Next: Registers, Prev: Formatter Instructions, Up: GNU troff Reference + +5.7 Comments +============ + +One of the most common forms of escape sequence is the comment.(1) +(*note Comments-Footnote-1::) + + -- Escape sequence: \" + Start a comment. Everything up to the next newline is ignored. + + This may sound simple, but it can be tricky to keep the comments + from interfering with the appearance of the output. If the escape + sequence is to the right of some text or a request, that portion of + the line is ignored, but spaces preceding it are processed normally + by GNU 'troff'. This affects only the 'ds' and 'as' requests and + their variants. + + One possibly irritating idiosyncrasy is that tabs should not be + used to vertically align comments in the source document. Tab + characters are not treated as separators between a request name and + its first argument, nor between arguments. + + A comment on a line by itself is treated as a blank line, because + after eliminating the comment, that is all that remains. + + Test + \" comment + Test + => Test + => + => Test + + To avoid this, it is common to combine the empty request with the + comment escape sequence as '.\"', causing the input line to be + ignored. + + Another commenting scheme sometimes seen is three consecutive + single quotes (''''') at the beginning of a line. This works, but + GNU 'troff' emits a warning diagnostic (if enabled) about an + undefined macro (namely ''''). + + -- Escape sequence: \# + Start a comment; everything up to and including the next newline is + ignored. This 'groff' extension was introduced to avoid the + problems described above. + + Test + \# comment + Test + => Test Test + + -- Request: .ig [end] + Ignore input until, in the current conditional block (if any),(2) + (*note Comments-Footnote-2::) the macro END is called at the start + of a control line, or the control line '..' is encountered if END + is not specified. 'ig' is parsed as if it were a macro definition, + but its contents are discarded, not stored.(3) (*note + Comments-Footnote-3::) + + hand\c + .de TX + fasting + .. + .ig TX + This is part of a large block of input that has been + temporarily(?) commented out. + We can restore it simply by removing the .ig request and + the call of its end macro. + .TX + => handfasting + + +File: groff.info, Node: Comments-Footnotes, Up: Comments + + (1) This claim may be more aspirational than descriptive. + + (2) *Note Conditional Blocks::. + + (3) Exception: auto-incrementing registers defined outside the +ignored region _will_ be modified if interpolated with '\n±' inside it. +*Note Auto-increment::. + + +File: groff.info, Node: Registers, Next: Manipulating Filling and Adjustment, Prev: Formatter Instructions, Up: GNU troff Reference + +5.8 Registers +============= + +In the 'roff' language, numbers can be stored in "registers". Many +built-in registers exist, supplying anything from the date to details of +formatting parameters. You can also define your own. *Note +Identifiers::, for information on constructing a valid name for a +register. + +* Menu: + +* Setting Registers:: +* Interpolating Registers:: +* Auto-increment:: +* Assigning Register Formats:: +* Built-in Registers:: + + +File: groff.info, Node: Setting Registers, Next: Interpolating Registers, Prev: Registers, Up: Registers + +5.8.1 Setting Registers +----------------------- + +Define registers and update their values with the 'nr' request or the +'\R' escape sequence. + + -- Request: .nr ident value + -- Escape sequence: \R'ident value' + Set register IDENT to VALUE. If IDENT doesn't exist, GNU 'troff' + creates it. In the '\R' escape sequence, the delimiter need not be + a neutral apostrophe; see *note Delimiters::. It also does not + produce an input token in GNU 'troff'. *Note Gtroff Internals::. + + .nr a (((17 + (3 * 4))) % 4) + \n[a] + .\R'a (((17 + (3 * 4))) % 4)' + \n[a] + => 1 1 + + (Later, we will discuss additional forms of 'nr' and '\R' that can + change a register's value after it is dereferenced but before it is + interpolated. *Note Auto-increment::.) + + The complete transparency of '\R' can cause surprising effects if + you use registers like '.k', which get evaluated at the time they + are accessed. + + .ll 1.6i + . + aaa bbb ccc ddd eee fff ggg hhh\R':k \n[.k]' + .tm :k == \n[:k] + => :k == 126950 + . + .br + . + aaa bbb ccc ddd eee fff ggg hhh\h'0'\R':k \n[.k]' + .tm :k == \n[:k] + => :k == 15000 + + If you process this with the PostScript device ('-Tps'), there will + be a line break eventually after 'ggg' in both input lines. + However, after processing the space after 'ggg', the partially + collected line is not overfull yet, so GNU 'troff' continues to + collect input until it sees the space (or in this case, the + newline) after 'hhh'. At this point, the line is longer than the + line length, and the line gets broken. + + In the first input line, since the '\R' escape sequence leaves no + traces, the check for the overfull line hasn't been done yet at the + point where '\R' gets handled, and you get a value for the '.k' + register that is even greater than the current line length. + + In the second input line, the insertion of '\h'0'' to cause a + zero-width motion forces GNU 'troff' to check the line length, + which in turn causes the start of a new output line. Now '.k' + returns the expected value. + + 'nr' and '\R' each have two additional special forms to increment or +decrement a register. + + -- Request: .nr ident +value + -- Request: .nr ident -value + -- Escape sequence: \R'ident +value' + -- Escape sequence: \R'ident -value' + Increment (decrement) register IDENT by VALUE. In the '\R' escape + sequence, the delimiter need not be a neutral apostrophe; see *note + Delimiters::. + + .nr a 1 + .nr a +1 + \na + => 2 + + A leading minus sign in VALUE is always interpreted as a + decrementation operator, not an algebraic sign. To assign a + register a negative value or the negated value of another register, + you can force GNU 'troff' to interpret '-' as a negation or minus, + rather than decrementation, operator: enclose it with its operand + in parentheses or subtract it from zero. + + .nr a 7 + .nr b 3 + .nr a -\nb + \na + => 4 + .nr a (-\nb) + \na + => -3 + .nr a 0-\nb + \na + => -3 + + If a register's prior value does not exist (the register was + undefined), an increment or decrement is applied as if to 0. + + -- Request: .rr ident + Remove register IDENT. If IDENT doesn't exist, the request is + ignored. Technically, only the name is removed; the register's + contents are still accessible under aliases created with 'aln', if + any. + + -- Request: .rnn ident1 ident2 + Rename register IDENT1 to IDENT2. If IDENT1 doesn't exist, the + request is ignored. Renaming a built-in register does not + otherwise alter its properties. + + -- Request: .aln new old + Create an alias NEW for an existing register OLD, causing the names + to refer to the same stored object. If OLD is undefined, a warning + in category 'reg' is produced and the request is ignored. *Note + Warnings::, for information about the enablement and suppression of + warnings. + + To remove a register alias, invoke 'rr' on its name. A register's + contents do not become inaccessible until it has no more names. + + +File: groff.info, Node: Interpolating Registers, Next: Auto-increment, Prev: Setting Registers, Up: Registers + +5.8.2 Interpolating Registers +----------------------------- + +Register contents are interpolated with the '\n' escape sequence. + + -- Escape sequence: \ni + -- Escape sequence: \n(id + -- Escape sequence: \n[ident] + Interpolate register with name IDENT (one-character name I, + two-character name ID). '\n' is interpreted even in copy mode + (*note Copy Mode::). If the register is undefined, it is created + and assigned a value of '0', that value is interpolated, and a + warning in category 'reg' is emitted. *Note Warnings::, for + information about the enablement and suppression of warnings. + + .nr a 5 + .nr as \na+\na + \n(as + => 10 + + .nr a1 5 + .nr ab 6 + .ds str b + .ds num 1 + \n[a\n[num]] + => 5 + \n[a\*[str]] + => 6 + + +File: groff.info, Node: Auto-increment, Next: Assigning Register Formats, Prev: Interpolating Registers, Up: Registers + +5.8.3 Auto-increment +-------------------- + +Registers can also be incremented or decremented by a configured amount +at the time they are interpolated. The value of the increment is +specified with a third argument to the 'nr' request, and a special +interpolation syntax is used to alter and then retrieve the register's +value. Together, these features are called "auto-increment".(1) (*note +Auto-increment-Footnote-1::) + + -- Request: .nr ident value incr + Set register IDENT to VALUE and its auto-incrementation amount to + to INCR. The '\R' escape sequence doesn't support an INCR + argument. + + Auto-incrementation is not _completely_ automatic; the '\n' escape +sequence in its basic form never alters the value of a register. To +apply auto-incrementation to a register, interpolate it with '\n±'. + + -- Escape sequence: \n+i + -- Escape sequence: \n-i + -- Escape sequence: \n+(id + -- Escape sequence: \n-(id + -- Escape sequence: \n+[ident] + -- Escape sequence: \n-[ident] + Increment or decrement IDENT (one-character name I, two-character + name ID) by the register's auto-incrementation value and then + interpolate the new register value. If IDENT has no + auto-incrementation value, interpolate as with '\n'. + + .nr a 0 1 + .nr xx 0 5 + .nr foo 0 -2 + \n+a, \n+a, \n+a, \n+a, \n+a + .br + \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx + .br + \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] + => 1, 2, 3, 4, 5 + => -5, -10, -15, -20, -25 + => -2, -4, -6, -8, -10 + + To change the increment value without changing the value of a +register, assign the register's value to itself by interpolating it, and +specify the desired increment normally. Apply an increment of '0' to +disable auto-incrementation of the register. + + +File: groff.info, Node: Auto-increment-Footnotes, Up: Auto-increment + + (1) A negative auto-increment can be considered an "auto-decrement". + + +File: groff.info, Node: Assigning Register Formats, Next: Built-in Registers, Prev: Auto-increment, Up: Registers + +5.8.4 Assigning Register Formats +-------------------------------- + +A writable register's value can be interpolated in several number +formats. By default, conventional Arabic numerals are used. Other +formats see use in sectioning and outlining schemes and alternative page +numbering arrangements. + + -- Request: .af reg fmt + Use number format FMT when interpolating register REG. Valid + number formats are as follows. + + '0...' + Arabic numerals 0, 1, 2, and so on. Any decimal digit is + equivalent to '0'; the formatter merely counts the digits + specified. Multiple Arabic numerals in FMT cause + interpolations to be zero-padded on the left if necessary to + at least as many digits as specified (interpolations never + truncate a register value). A register with format '00' + interpolates values 1, 2, 3 as '01', '02', '03'. The default + format for all writable registers is '0'. + + 'I' + Uppercase Roman numerals: 0, I, II, III, IV, ... + + 'i' + Lowercase Roman numerals: 0, i, ii, iii, iv, ... + + 'A' + Uppercase letters: 0, A, B, C, ..., Z, AA, AB, ... + + 'a' + Lowercase letters: 0, a, b, c, ..., z, aa, ab, ... + + Omitting FMT causes a warning in category 'missing'. *Note + Warnings::, for information about the enablement and suppression of + warnings. Specifying an unrecognized format is an error. + + Zero values are interpolated as '0' in non-Arabic formats. + Negative quantities are prefixed with '-' irrespective of format. + In Arabic formats, the sign supplements the field width. If REG + doesn't exist, it is created with a zero value. + + .nr a 10 + .af a 0 \" the default format + \na, + .af a I + \na, + .af a 321 + .nr a (-\na) + \na, + .af a a + \na + => 10, X, -010, -j + + The representable extrema in the 'i' and 'I' formats correspond to + Arabic ±39,999. GNU 'troff' uses 'w' and 'z' to represent 5,000 + and 10,000 in Roman numerals, respectively, following the + convention of AT&T 'troff'--currently, the correct glyphs for Roman + numerals five thousand ('U+2181') and ten thousand ('U+2182') are + not used. + + Assigning the format of a read-only register is an error. Instead, + copy the read-only register's value to, and assign the format of, a + writable register. + + -- Escape sequence: \gr + -- Escape sequence: \g(rg + -- Escape sequence: \g[reg] + Interpolate the format of the register REG (one-character name R, + two-character name RG). Zeroes represent Arabic formats. If REG + is not defined, REG is not created and nothing is interpolated. + '\g' is interpreted even in copy mode (*note Copy Mode::). + + GNU 'troff' interprets only Arabic numerals. The Roman numeral or +alphabetic formats cannot be used as operands to arithmetic operators in +expressions (*note Numeric Expressions::). For instance, it may be +desirable to test the page number independently of its format. + + .af % i \" front matter + .de header-trap + . \" To test the page number, we need it in Arabic. + . ds saved-page-number-format \\g%\" + . af % 0 + . nr page-number-in-decimal \\n% + . af % \\*[saved-page-number-format] + . ie \\n[page-number-in-decimal]=1 .do-first-page-stuff + . el \{\ + . ie o .do-odd-numbered-page-stuff + . el .do-even-numbered-page-stuff + . \} + . rm saved-page-number-format + .. + .wh 0 header-trap + + +File: groff.info, Node: Built-in Registers, Prev: Assigning Register Formats, Up: Registers + +5.8.5 Built-in Registers +------------------------ + +Predefined registers whose identifiers start with a dot are read-only. +Many are Boolean-valued, interpolating a true or false value testable +with the 'if', 'ie', or 'while' requests. Some read-only registers are +string-valued, meaning that they interpolate text. + + *Caution:* Built-in registers are subject to removal like others; +once removed, they can be recreated only as normal writable registers +and will not reflect formatter state. + + A register name (without the dot) is often associated with a request +of the same name. A complete listing of all built-in registers can be +found in *note Register Index::. + + We present here a few built-in registers that are not described +elsewhere in this manual; they have to do with invariant properties of +GNU 'troff', or obtain information about the formatter's command-line +options, processing progress, or the operating environment. + +'\n[.A]' + Approximate output is being formatted (Boolean-valued); see 'groff' + '-a' option (*note Groff Options::). + +'\n[.c]' +'\n[c.]' + Input line number. 'c.' is a writable synonym, affecting + subsequent interpolations of both '.c' and 'c.'. + +'\n[.F]' + Name of input file (string-valued). + +'\n[.g]' + Always true in GNU 'troff' (Boolean-valued). Documents can use + this to ask the formatter if it claims 'groff' compatibility. + +'\n[.P]' + Output page selection status (Boolean-valued); see 'groff' '-o' + option (*note Groff Options::). + +'\n[.R]' + Count of available unused registers; always 10,000 in GNU + 'troff'.(1) (*note Built-in Registers-Footnote-1::) + +'\n[.T]' + Indicator of output device selection (Boolean-valued); see 'groff' + '-T' option (*note Groff Options::). + +'\n[.U]' + Unsafe mode enablement status (Boolean-valued); see 'groff' '-U' + option (*note Groff Options::). + +'\n[.x]' + Major version number of the running GNU 'troff' formatter. For + example, if the version number is 1.23.0, then '.x' contains '1'. + +'\n[.y]' + Minor version number of the running GNU 'troff' formatter. For + example, if the version number is 1.23.0, then '.y' contains '23'. + +'\n[.Y]' + Revision number of the running GNU 'troff' formatter. For example, + if the version number is 1.23.0, then '.Y' contains '0'. + +'\n[$$]' + Process identifier (PID) of the GNU 'troff' program in its + operating environment. + + Date- and time-related registers are set per the local time as +determined by 'localtime(3)' when the formatter launches. This +initialization can be overridden by 'SOURCE_DATE_EPOCH' and 'TZ'; see +*note Environment::. + +'\n[seconds]' + Count of seconds elapsed in the minute (0-60). + +'\n[minutes]' + Count of minutes elapsed in the hour (0-59). + +'\n[hours]' + Count of hours elapsed since midnight (0-23). + +'\n[dw]' + Day of the week (1-7; 1 is Sunday). + +'\n[dy]' + Day of the month (1-31). + +'\n[mo]' + Month of the year (1-12). + +'\n[year]' + Gregorian year. + +'\n[yr]' + Gregorian year minus 1900. This register is incorrectly documented + in the AT&T 'troff' manual as storing the last two digits of the + current year. That claim stopped being true in 2000. Old 'troff' + input that looks like: + + '\" The year number is a surprise after 1999. + This document was formatted in 19\n(yr. + + can be corrected to: + + This document was formatted in \n[year]. + + or, for portability across many 'roff' programs, to the following. + + .nr y4 1900+\n(yr + This document was formatted in \n(y4. + + +File: groff.info, Node: Built-in Registers-Footnotes, Up: Built-in Registers + + (1) GNU 'troff' dynamically allocates memory for as many registers as +required. + + +File: groff.info, Node: Manipulating Filling and Adjustment, Next: Manipulating Hyphenation, Prev: Registers, Up: GNU troff Reference + +5.9 Manipulating Filling and Adjustment +======================================= + +When an output line is pending (see below), a break moves the drawing +position to the beginning of the next text baseline, interrupting +filling. Various ways of causing breaks were shown in *note Breaking::. +The 'br' request likewise causes a break. Several other requests imply +breaks: 'bp', 'ce', 'cf', 'fi', 'fl', 'in', 'nf', 'rj', 'sp', 'ti', and +'trf'. If the no-break control character is used with any of these +requests, GNU 'troff' suppresses the break; instead the requested +operation takes effect at the next break. ''br' does nothing. + + .ll 55n + This line is normally filled and adjusted. + .br + A line's alignment is decided + 'ce \" Center the next input line (no break). + when it is output. + This line returns to normal filling and adjustment. + => This line is normally filled and adjusted. + => A line's alignment is decided when it is output. + => This line returns to normal filling and adjustment. + +Output line properties like page offset, indentation, adjustment, and +even the location of its text baseline, are not determined until the +line has been broken. An output line is said to be "pending" if some +input has been collected but an output line corresponding to it has not +yet been written; such an output line is also termed "partially +collected". If no output line is pending, it is as if a break has +already happened; additional breaks, whether explicit or implicit, have +no effect. If the vertical drawing position is negative--as it is when +the formatter starts up--a break starts a new page (even if no output +line is pending) unless an end-of-input macro is being interpreted. +*Note End-of-input Traps::. + + -- Request: .br + Break the line: emit any pending output line without adjustment. + + foo bar + .br + baz + 'br + qux + => foo bar + => baz qux + + Sometimes you want to prevent a break within a phrase or between a +quantity and its units. + + -- Escape sequence: \~ + Insert an unbreakable space that is adjustable like an ordinary + space. It is discarded from the end of an output line if a break + is forced. + + Set the output speed to\~1. + There are 1,024\~bytes in 1\~KiB. + J.\~F.\~Ossanna wrote the original CSTR\~#54. + + By default, GNU 'troff' fills text and adjusts it to reach the output +line length. The 'nf' request disables filling; the 'fi' request +reënables it. + + -- Request: .fi + -- Register: \n[.u] + Enable filling of output lines; a pending output line is broken. + The read-only register '.u' is set to 1. The filling enablement + status, sometimes called "fill mode", is associated with the + environment (*note Environments::). *Note Line Continuation::, for + interaction with the '\c' escape sequence. + + -- Request: .nf + Disable filling of output lines: the output line length (*note Line + Layout::) is ignored and output lines are broken where the input + lines are. A pending output line is broken and adjustment is + suppressed. The read-only register '.u' is set to 0. The filling + enablement status is associated with the environment (*note + Environments::). See *note Line Continuation::, for interaction + with the '\c' escape sequence. + + -- Request: .ad [mode] + -- Register: \n[.j] + Enable output line adjustment in MODE, taking effect when the + pending (or next) output line is broken. Adjustment is suppressed + when filling is. MODE can have one of the following values. + + 'b' + 'n' + Adjust "normally": if the output line does not consume the + distance between the indentation and the configured output + line length, GNU 'troff' stretches adjustable spaces within + the line until that length is reached. When the indentation + is zero, this mode spreads the line to both the left and right + margins. This is the GNU 'troff' default. + + 'c' + Center filled text. Contrast with the 'ce' request, which + centers text _without_ filling it. + + 'l' + Align text to the left without adjusting it. + + 'r' + Align text to the right without adjusting it. + + MODE can also be a value previously stored in the '.j' register. + Using 'ad' without an argument is the same as '.ad \n[.j]'; unless + filling is disabled, GNU 'troff' resumes adjusting lines in the + same way it did before adjustment was disabled by invocation of the + 'na' request. + + The adjustment mode and enablement status are encoded in the + read-only register '.j'. These parameters are associated with the + environment (*note Environments::). + + The value of '.j' for any adjustment mode is an implementation + detail and should not be relied upon as a programmer's interface. + Do not write logic to interpret or perform arithmetic on it. + + .ll 48n + .de AD + . br + . ad \\$1 + .. + .de NA + . br + . na + .. + left + .AD r + .nr ad \n(.j + right + .AD c + center + .NA + left + .AD + center + .AD \n(ad + right + => left + => right + => center + => left + => center + => right + + -- Request: .na + Disable output line adjustment. This produces the same output as + left-alignment, but the value of the adjustment mode register '.j' + is altered differently. The adjustment mode and enablement status + are associated with the environment (*note Environments::). + + -- Request: .brp + -- Escape sequence: \p + Break, adjusting the line per the current adjustment mode. '\p' + schedules a break with adjustment at the next word boundary. The + escape sequence is itself neither a break nor a space of any kind; + it can thus be placed in the middle of a word to cause a break at + the end of that word. + + Breaking with immediate adjustment can produce ugly results since + GNU 'troff' doesn't have a sophisticated paragraph-building + algorithm, as TeX has, for example. Instead, GNU 'troff' fills and + adjusts a paragraph line by line. + + .ll 4.5i + This is an uninteresting sentence. + This is an uninteresting sentence.\p + This is an uninteresting sentence. + + is formatted as follows. + + This is an uninteresting sentence. This is + an uninteresting sentence. + This is an uninteresting sentence. + + To clearly present the next couple of requests, we must introduce the +concept of "productive" input lines. A "productive input line" is one +that directly produces formatted output. Text lines produce output,(1) +(*note Manipulating Filling and Adjustment-Footnote-1::) as do control +lines containing requests like 'tl' or escape sequences like '\D'. +Macro calls are not _directly_ productive, and thus not counted, but +their interpolated contents can be. Empty requests, and requests and +escape sequences that define registers or strings or alter the +formatting environment (as with changes to the size, face, height, +slant, or color of the type) are not productive. We will also preview +the output line continuation escape sequence, '\c', which "connects" two +input lines that would otherwise be counted separately. (2) (*note +Manipulating Filling and Adjustment-Footnote-2::) + + .de hello + Hello, world! + .. + .ce \" center output of next productive input line + . + .nr junk-reg 1 + .ft I + Chorus: \c + .ft + .hello + Went the day well? + => Chorus: Hello, world! + => Went the day well? + + -- Request: .ce [n] + -- Register: \n[.ce] + Break (unless the no-break control character is used), center the + output of the next N productive input lines with respect to the + line length and indentation without filling, then break again + regardless of the invoking control character. If the argument is + not positive, centering is disabled. Omitting the argument implies + an N of '1'. The count of lines remaining to be centered is stored + in the read-only register '.ce' and is associated with the + environment (*note Environments::). + + While the '.ad c' request also centers text, it fills the text as + well. + + .de FR + This is a small text fragment that shows the differences + between the `.ce' and the `.ad c' requests. + .. + .ll 4i + .ce 1000 + .FR + .ce 0 + + .ad c + .FR + => This is a small text fragment that shows + => the differences + => between the `.ce' and the `.ad c' requests. + => + => This is a small text fragment that shows + => the differences between the `.ce' and + => the `.ad c' requests. + + The previous example illustrates a common idiom of turning + centering on for a quantity of lines far in excess of what is + required, and off again after the text to be centered. This + technique relieves humans of counting lines for requests that take + a count of input lines as an argument. + + -- Request: .rj [n] + -- Register: \n[.rj] + Break (unless the no-break control character is used), align the + output of the next N productive input lines to the right margin + without filling, then break again regardless of the control + character. If the argument is not positive, right-alignment is + disabled. Omitting the argument implies an N of '1'. The count of + lines remaining to be right-aligned is stored in the read-only + register '.rj' and is associated with the environment (*note + Environments::). + + .ll 49n + .rj 3 + At first I hoped that such a technically unsound + project would collapse but I soon realized it was + doomed to success. \[em] C. A. R. Hoare + => At first I hoped that such a technically unsound + => project would collapse but I soon realized it was + => doomed to success. -- C. A. R. Hoare + + -- Request: .ss word-space-size [additional-sentence-space-size] + -- Register: \n[.ss] + -- Register: \n[.sss] + Set the sizes of spaces between words and sentences(3) (*note + Manipulating Filling and Adjustment-Footnote-3::) in twelfths of + font's space width (typically one-fourth to one-third em for + Western scripts). The default for both parameters is 12. Negative + values are erroneous. The first argument is a minimum; if an + output line undergoes adjustment, such spaces may increase in + width. The optional second argument sets the amount of additional + space separating sentences on the same output line. If omitted, + this amount is set to WORD-SPACE-SIZE. The request is ignored if + there are no parameters. + + Additional inter-sentence space is used only if the output line is + not full when the end of a sentence occurs in the input. If a + sentence ends at the end of an input line, then both an inter-word + space and an inter-sentence space are added to the output; if two + spaces follow the end of a sentence in the middle of an input line, + then the second space becomes an inter-sentence space in the + output. Additional inter-sentence space is not adjusted, but the + inter-word space that always precedes it may be. Further input + spaces after the second, if present, are adjusted as normal. + + The read-only registers '.ss' and '.sss' hold the minimal + inter-word space and additional inter-sentence space amounts, + respectively. These parameters are part of the environment (*note + Environments::), and rounded down to the nearest multiple of 12 on + terminals. + + The 'ss' request can insert discardable horizontal space; that is, + space that is discarded at a break. For example, some footnote + styles collect the notes into a single paragraph with large gaps + between each note. + + .ll 48n + 1.\~J. Fict. Ch. Soc. 6 (2020), 3\[en]14. + .ss 12 48 \" applies to next sentence ending + Reprints no longer available through FCS. + .ss 12 \" go back to normal + 2.\~Better known for other work. + => 1. J. Fict. Ch. Soc. 6 (2020), 3-14. Reprints + => no longer available through FCS. 2. Better + => known for other work. + + If _undiscardable_ space is required, use the '\h' escape sequence. + + +File: groff.info, Node: Manipulating Filling and Adjustment-Footnotes, Up: Manipulating Filling and Adjustment + + (1) unless diverted; see *note Diversions:: + + (2) *Note Line Continuation::. + + (3) Recall *note Filling:: and *note Sentences:: for the definitions +of word and sentence boundaries, respectively. + + +File: groff.info, Node: Manipulating Hyphenation, Next: Manipulating Spacing, Prev: Manipulating Filling and Adjustment, Up: GNU troff Reference + +5.10 Manipulating Hyphenation +============================= + +When filling, GNU 'troff' hyphenates words as needed at user-specified +and automatically determined hyphenation points. The machine-driven +determination of hyphenation points in words requires algorithms and +data, and is susceptible to conventions and preferences. Before +tackling such "automatic hyphenation", let us consider how hyphenation +points can be set explicitly. + + Explicitly hyphenated words such as "mother-in-law" are eligible for +breaking after each of their hyphens. Relatively few words in a +language offer such obvious break points, however, and automatic +detection of syllabic (or phonetic) boundaries for hyphenation is not +perfect,(1) (*note Manipulating Hyphenation-Footnote-1::) particularly +for unusual words found in technical literature. We can instruct GNU +'troff' how to hyphenate specific words if the need arises. + + -- Request: .hw word ... + Define each "hyphenation exception" WORD with each hyphen '-' in + the word indicating a hyphenation point. For example, the request + + .hw in-sa-lub-rious alpha + + marks potential hyphenation points in "insalubrious", and prevents + "alpha" from being hyphenated at all. + + Besides the space character, any character whose hyphenation code + is zero can be used to separate the arguments of 'hw' (see the + 'hcode' request below). In addition, this request can be used more + than once. + + Hyphenation points specified with 'hw' are not subject to the + within-word placement restrictions imposed by the 'hy' request (see + below). + + Hyphenation exceptions specified with the 'hw' request are + associated with the hyphenation language (see the 'hla' request + below) and environment (*note Environments::); invoking the 'hw' + request in the absence of a hyphenation language is an error. + + The request is ignored if there are no parameters. + + These are known as hyphenation exceptions in the expectation that +most users will avail themselves of automatic hyphenation; these +exceptions override any rules that would normally apply to a word +matching a hyphenation exception defined with 'hw'. + + Situations also arise when only a specific occurrence of a word needs +its hyphenation altered or suppressed, or when a URL or similar string +needs to be breakable in sensible places without hyphenation. + + -- Escape sequence: \% + -- Escape sequence: \: + To tell GNU 'troff' how to hyphenate words as they occur in input, + use the '\%' escape sequence; it is the default "hyphenation + character". Each instance within a word indicates to GNU 'troff' + that the word may be hyphenated at that point, while prefixing a + word with this escape sequence prevents it from being otherwise + hyphenated. This mechanism affects only that occurrence of the + word; to change the hyphenation of a word for the remainder of + input processing, use the 'hw' request. + + GNU 'troff' regards the escape sequences '\X' and '\Y' as starting + a word; that is, the '\%' escape sequence in, say, + '\X'...'\%foobar' or '\Y'...'\%foobar' no longer prevents + hyphenation of 'foobar' but inserts a hyphenation point just prior + to it; most likely this isn't what you want. *Note Postprocessor + Access::. + + '\:' inserts a non-printing break point; that is, a word can break + there, but the soft hyphen glyph (see below) is not written to the + output if it does. This escape sequence is an input word boundary, + so the remainder of the word is subject to hyphenation as normal. + + You can combine '\:' and '\%' to control breaking of a file name or + URL, or to permit hyphenation only after certain explicit hyphens + within a word. + + The \%Lethbridge-Stewart-\:\%Sackville-Baggins divorce + was, in retrospect, inevitable once the contents of + \%/var/log/\:\%httpd/\:\%access_log on the family web + server came to light, revealing visitors from Hogwarts. + + -- Request: .hc [char] + Change the hyphenation character to CHAR. This character then + works as the '\%' escape sequence normally does, and thus no longer + appears in the output.(2) (*note Manipulating + Hyphenation-Footnote-2::) Without an argument, 'hc' resets the + hyphenation character to '\%' (the default). The hyphenation + character is associated with the environment (*note + Environments::). + + -- Request: .shc [c] + Set the "soft hyphen character", inserted when a word is hyphenated + automatically or at a hyphenation character, to the ordinary or + special character C.(3) (*note Manipulating + Hyphenation-Footnote-3::) If the argument is omitted, the soft + hyphen character is set to the default, '\[hy]'. If no glyph for C + exists in the font in use at a potential hyphenation point, then + the line is not broken there. Neither character definitions + (specified with the 'char' and similar requests) nor translations + (specified with the 'tr' request) are applied to C. + + Several requests influence automatic hyphenation. Because +conventions vary, a variety of hyphenation modes is available to the +'hy' request; these determine whether hyphenation will apply to a word +prior to breaking a line at the end of a page (more or less; see below +for details), and at which positions within that word automatically +determined hyphenation points are permissible. The places within a word +that are eligible for hyphenation are determined by language-specific +data and lettercase relationships. Furthermore, hyphenation of a word +might be suppressed due to a limit on consecutive hyphenated lines +('hlm'), a minimum line length threshold ('hym'), or because the line +can instead be adjusted with additional inter-word space ('hys'). + + -- Request: .hy [mode] + -- Register: \n[.hy] + Set automatic hyphenation mode to MODE, an integer encoding + conditions for hyphenation; if omitted, '1' is implied. The + hyphenation mode is available in the read-only register '.hy'; it + is associated with the environment (*note Environments::). The + default hyphenation mode depends on the localization file loaded + when GNU 'troff' starts up; see the 'hpf' request below. + + Typesetting practice generally does not avail itself of every + opportunity for hyphenation, but the details differ by language and + site mandates. The hyphenation modes of AT&T 'troff' were + implemented with English-language publishing practices of the 1970s + in mind, not a scrupulous enumeration of conceivable parameters. + GNU 'troff' extends those modes such that finer-grained control is + possible, favoring compatibility with older implementations over a + more intuitive arrangement. The means of hyphenation mode control + is a set of numbers that can be added up to encode the behavior + sought.(4) (*note Manipulating Hyphenation-Footnote-4::) The + entries in the following table are termed "values"; the sum of the + desired values is the "mode". + + '0' + disables hyphenation. + + '1' + enables hyphenation except after the first and before the last + character of a word. + + The remaining values "imply" 1; that is, they enable hyphenation + under the same conditions as '.hy 1', and then apply or lift + restrictions relative to that basis. + + '2' + disables hyphenation of the last word on a page,(5) (*note + Manipulating Hyphenation-Footnote-5::) even for explicitly + hyphenated words. + + '4' + disables hyphenation before the last two characters of a word. + + '8' + disables hyphenation after the first two characters of a word. + + '16' + enables hyphenation before the last character of a word. + + '32' + enables hyphenation after the first character of a word. + + Apart from value 2, restrictions imposed by the hyphenation mode + are _not_ respected for words whose hyphenations have been + specified with the hyphenation character ('\%' by default) or the + 'hw' request. + + Nonzero values in the previous table are additive. For example, + mode 12 causes GNU 'troff' to hyphenate neither the last two nor + the first two characters of a word. Some values cannot be used + together because they contradict; for instance, values 4 and 16, + and values 8 and 32. As noted, it is superfluous to add 1 to any + non-zero even mode. + + The automatic placement of hyphens in words is determined by + "pattern files", which are derived from TeX and available for + several languages. The number of characters at the beginning of a + word after which the first hyphenation point should be inserted is + determined by the patterns themselves; it can't be reduced further + without introducing additional, invalid hyphenation points + (unfortunately, this information is not part of a pattern file--you + have to know it in advance). The same is true for the number of + characters at the end of a word before the last hyphenation point + should be inserted. For example, you can supply the following + input to 'echo $(nroff)'. + + .ll 1 + .hy 48 + splitting + + You will get + + s- plit- t- in- g + + instead of the correct 'split- ting'. English patterns as + distributed with GNU 'troff' need two characters at the beginning + and three characters at the end; this means that value 4 of 'hy' is + mandatory. Value 8 is possible as an additional restriction, but + values 16 and 32 should be avoided, as should mode 1. Modes 4 + and 6 are typical. + + A table of left and right minimum character counts for hyphenation + as needed by the patterns distributed with GNU 'troff' follows; see + the 'groff_tmac(5)' man page for more information on GNU 'troff''s + language macro files. + + language pattern name left min right min + ----------------------------------------------------------- + Czech cs 2 2 + English en 2 3 + French fr 2 3 + German traditional det 2 2 + German reformed den 2 2 + Italian it 2 2 + Swedish sv 1 2 + + Hyphenation exceptions within pattern files (i.e., the words within + a TeX '\hyphenation' group) obey the hyphenation restrictions given + by 'hy'. + + -- Request: .nh + Disable automatic hyphenation; i.e., set the hyphenation mode to 0 + (see above). The hyphenation mode of the last call to 'hy' is not + remembered. + + -- Request: .hpf pattern-file + -- Request: .hpfa pattern-file + -- Request: .hpfcode a b [c d] ... + Read hyphenation patterns from PATTERN-FILE, which is sought in the + same way that macro files are with the 'mso' request or the + '-mNAME' command-line option to 'groff'. The PATTERN-FILE should + have the same format as (simple) TeX pattern files. More + specifically, the following scanning rules are implemented. + + * A percent sign starts a comment (up to the end of the line) + even if preceded by a backslash. + + * "Digraphs" like '\$' are not supported. + + * '^^XX' (where each X is 0-9 or a-f) and '^^C' (character C in + the code point range 0-127 decimal) are recognized; other uses + of '^' cause an error. + + * No macro expansion is performed. + + * 'hpf' checks for the expression '\patterns{...}' (possibly + with whitespace before or after the braces). Everything + between the braces is taken as hyphenation patterns. + Consequently, '{' and '}' are not allowed in patterns. + + * Similarly, '\hyphenation{...}' gives a list of hyphenation + exceptions. + + * '\endinput' is recognized also. + + * For backward compatibility, if '\patterns' is missing, the + whole file is treated as a list of hyphenation patterns + (except that the '%' character is recognized as the start of a + comment). + + The 'hpfa' request appends a file of patterns to the current list. + + The 'hpfcode' request defines mapping values for character codes in + pattern files. It is an older mechanism no longer used by GNU + 'troff''s own macro files; for its successor, see 'hcode' below. + 'hpf' or 'hpfa' apply the mapping after reading the patterns but + before replacing or appending to the active list of patterns. Its + arguments are pairs of character codes--integers from 0 to 255. + The request maps character code A to code B, code C to code D, and + so on. Character codes that would otherwise be invalid in GNU + 'troff' can be used. By default, every code maps to itself except + those for letters 'A' to 'Z', which map to those for 'a' to 'z'. + + The set of hyphenation patterns is associated with the language set + by the 'hla' request (see below). The 'hpf' request is usually + invoked by a localization file loaded by the 'troffrc' file.(6) + (*note Manipulating Hyphenation-Footnote-6::) + + A second call to 'hpf' (for the same language) replaces the + hyphenation patterns with the new ones. Invoking 'hpf' or 'hpfa' + causes an error if there is no hyphenation language. If no 'hpf' + request is specified (either in the document, in a file loaded at + startup, or in a macro package), GNU 'troff' won't automatically + hyphenate at all. + + -- Request: .hcode c1 code1 [c2 code2] ... + Set the hyphenation code of character C1 to CODE1, that of C2 to + CODE2, and so on. A hyphenation code must be an ordinary character + (not a special character escape sequence) other than a digit or a + space. The request is ignored if given no arguments. + + For hyphenation to work, hyphenation codes must be set up. At + startup, GNU 'troff' assigns hyphenation codes to the letters + 'a'-'z' (mapped to themselves), to the letters 'A'-'Z' (mapped to + 'a'-'z'), and zero to all other characters. Normally, hyphenation + patterns contain only lowercase letters which should be applied + regardless of case. In other words, they assume that the words + 'FOO' and 'Foo' should be hyphenated exactly as 'foo' is. The + 'hcode' request extends this principle to letters outside the + Unicode basic Latin alphabet; without it, words containing such + letters won't be hyphenated properly even if the corresponding + hyphenation patterns contain them. + + For example, the following 'hcode' requests are necessary to assign + hyphenation codes to the letters 'ÄäÖöÜüß', needed for German. + + .hcode ä ä Ä ä + .hcode ö ö Ö ö + .hcode ü ü Ü ü + .hcode ß ß + + Without these assignments, GNU 'troff' treats the German word + 'Kindergärten' (the plural form of 'kindergarten') as two words + 'kinderg' and 'rten' because the hyphenation code of the umlaut a + is zero by default, just like a space. There is a German + hyphenation pattern that covers 'kinder', so GNU 'troff' finds the + hyphenation 'kin-der'. The other two hyphenation points + ('kin-der-gär-ten') are missed. + + -- Request: .hla lang + -- Register: \n[.hla] + Set the hyphenation language to LANG. Hyphenation exceptions + specified with the 'hw' request and hyphenation patterns and + exceptions specified with the 'hpf' and 'hpfa' requests are + associated with the hyphenation language. The 'hla' request is + usually invoked by a localization file, which is turn loaded by the + 'troffrc' or 'troffrc-end' file; see the 'hpf' request above. + + The hyphenation language is available in the read-only + string-valued register '.hla'; it is associated with the + environment (*note Environments::). + + -- Request: .hlm [n] + -- Register: \n[.hlm] + -- Register: \n[.hlc] + Set the maximum quantity of consecutive hyphenated lines to N. If + N is negative, there is no maximum. If omitted, N is -1. This + value is associated with the environment (*note Environments::). + Only lines output from a given environment count toward the maximum + associated with that environment. Hyphens resulting from '\%' are + counted; explicit hyphens are not. + + The '.hlm' read-only register stores this maximum. The count of + immediately preceding consecutive hyphenated lines is available in + the read-only register '.hlc'. + + -- Request: .hym [length] + -- Register: \n[.hym] + Set the (right) hyphenation margin to LENGTH. If the adjustment + mode is not 'b' or 'n', the line is not hyphenated if it is shorter + than LENGTH. Without an argument, the hyphenation margin is reset + to its default value, 0. The default scaling unit is 'm'. The + hyphenation margin is associated with the environment (*note + Environments::). + + A negative argument resets the hyphenation margin to zero, emitting + a warning in category 'range'. + + The hyphenation margin is available in the '.hym' read-only + register. + + -- Request: .hys [hyphenation-space] + -- Register: \n[.hys] + Suppress hyphenation of the line in adjustment modes 'b' or 'n' if + it can be justified by adding no more than HYPHENATION-SPACE extra + space to each inter-word space. Without an argument, the + hyphenation space adjustment threshold is set to its default value, + 0. The default scaling unit is 'm'. The hyphenation space + adjustment threshold is associated with the environment (*note + Environments::). + + A negative argument resets the hyphenation space adjustment + threshold to zero, emitting a warning in category 'range'. + + The hyphenation space adjustment threshold is available in the + '.hys' read-only register. + + +File: groff.info, Node: Manipulating Hyphenation-Footnotes, Up: Manipulating Hyphenation + + (1) Whether a perfect algorithm for this application is even possible +is an unsolved problem in computer science: +. + + (2) '\%' itself stops marking hyphenation points but still produces +no output glyph. + + (3) "Soft" because it appears in output only where a hyphenation +break is performed; a "hard" hyphen, as in "long-term", always appears. + + (4) The mode is a vector of Booleans encoded as an integer. To a +programmer, this fact is easily deduced from the exclusive use of powers +of two for the configuration parameters; they are computationally easy +to "mask off" and compare to zero. To almost everyone else, the +arrangement seems recondite and unfriendly. + + (5) Hyphenation is prevented if the next page location trap is closer +to the vertical drawing position than the next text baseline would be. +*Note Page Location Traps::. + + (6) For more on localization, see the 'groff_tmac(5)' man page. + + +File: groff.info, Node: Manipulating Spacing, Next: Tabs and Fields, Prev: Manipulating Hyphenation, Up: GNU troff Reference + +5.11 Manipulating Spacing +========================= + +A break causes the formatter to update the vertical drawing position at +which the new text baseline is aligned. You can alter this location. + + -- Request: .sp [distance] + Break and move the next text baseline down by DISTANCE, or until + springing a page location trap.(1) (*note Manipulating + Spacing-Footnote-1::) If invoked with the no-break control + character, 'sp' moves the pending output line's text baseline by + DISTANCE. A negative DISTANCE will not reduce the position of the + text baseline below zero. Inside a diversion, any DISTANCE + argument is ignored. The default scaling unit is 'v'. If DISTANCE + is not specified, '1v' is assumed. + + .pl 5v \" Set page length to 5 vees. + .de xx + \-\-\- + . br + .. + .wh 0 xx \" Set a trap at the top of the page. + foo on page \n% + .sp 2v + bar on page \n% + .sp 50v \" This will cause a page break. + baz on page \n% + .pl \n(nlu \" Truncate page to current position. + => --- + => foo on page 1 + => + => + => bar on page 1 + => --- + => baz on page 2 + + You might use the following macros to set the baseline of the next + output text at a given distance from the top or the bottom of the + page. We subtract one line height ('\n[.v]') because the '|' + operator moves to one vee below the page top (recall *note Numeric + Expressions::). + + .de y-from-top-down + . sp |\\$1-\\n[.v]u + .. + . + .de y-from-bot-up + . sp |\\n[.p]u-\\$1-\\n[.v]u + .. + + A call to '.y-from-bot-up 10c' means that the next text baseline + will be 10 cm from the bottom edge of the paper. + + -- Request: .ls [count] + -- Register: \n[.L] + Set the line spacing; add COUNT-1 blank lines after each line of + text. With no argument, GNU 'troff' uses the previous value before + the last 'ls' call. The default is '1'. + + The read-only register '.L' contains the current line spacing; it + is associated with the environment (*note Environments::). + + The 'ls' request is a coarse mechanism. *Note Changing the Type +Size::, for the requests 'vs' and 'pvs' as alternatives to 'ls'. + + -- Escape sequence: \x'spacing' + -- Register: \n[.a] + Sometimes, an output line requires additional vertical spacing, for + instance to allow room for a tall construct like an inline equation + with exponents or subscripts (particularly if they are iterated). + The '\x' escape sequence takes a delimited measurement (like + '\x'3p'') to increase the vertical spacing of the pending output + line. The default scaling unit is 'v'. If the measurement is + positive, extra vertical space is inserted below the current line; + a negative measurement adds space above. If '\x' is applied to the + pending output line multiple times, the maxima of the positive and + negative adjustments are separately applied. The delimiter need + not be a neutral apostrophe; see *note Delimiters::. + + The '.a' read-only register contains the extra vertical spacing + _after_ the text baseline of the most recently emitted output line. + (In other words, it is the largest positive argument to '\x' + encountered on that line.) This quantity is exposed via a register + because if an output line requires this "extra post-vertical line + spacing", and the subsequent output line requires "extra + pre-vertical line spacing" (a negative argument to '\x'), then + applying both can lead to excessive spacing between the output + lines. Text that is piling high on line N might not require (as + much) extra pre-vertical line spacing if line N-1 carries extra + post-vertical line spacing. + + Use of '\x' can be necessary in combination with the + bracket-building escape sequence '\b',(2) (*note Manipulating + Spacing-Footnote-2::) as the following example shows. + + .nf + This is a test of \[rs]b (1). + This is a test of \[rs]b (2). + This is a test of \b'xyz'\x'-1m'\x'1m' (3). + This is a test of \[rs]b (4). + This is a test of \[rs]b (5). + => This is a test of \b (1). + => This is a test of \b (2). + => x + => This is a test of y (3). + => z + => This is a test of \b (4). + => This is a test of \b (5). + +Without '\x', the backslashes on the lines marked '(2)' and '(4)' would +be overprinted. + + -- Request: .ns + -- Request: .rs + -- Register: \n[.ns] + Enable "no-space mode". Vertical spacing, whether by 'sp' requests + or blank input lines, is disabled. The 'bp' request to advance to + the next page is also disabled, unless it is accompanied by a page + number (*note Page Control::). No-space mode ends automatically + when text(3) (*note Manipulating Spacing-Footnote-3::) is formatted + for output (4) (*note Manipulating Spacing-Footnote-4::) or the + 'rs' request is invoked, which ends no-space mode. The read-only + register '.ns' interpolates a Boolean value indicating the + enablement of no-space mode. + + A paragraphing macro might ordinarily insert vertical space to + separate paragraphs. A section heading macro could invoke 'ns' to + suppress this spacing for the first paragraph in a section. + + +File: groff.info, Node: Manipulating Spacing-Footnotes, Up: Manipulating Spacing + + (1) *Note Page Location Traps::. + + (2) *Note Drawing Geometric Objects::. + + (3) or geometric objects; see *note Drawing Geometric Objects:: + + (4) to the top-level diversion; see *note Diversions:: + + +File: groff.info, Node: Tabs and Fields, Next: Character Translations, Prev: Manipulating Spacing, Up: GNU troff Reference + +5.12 Tabs and Fields +==================== + +A tab character (ISO code point 9, EBCDIC code point 5) causes a +horizontal movement to the next tab stop, if any. + + -- Escape sequence: \t + Interpolate a tab in copy mode; see *note Copy Mode::. + + -- Request: .ta [[n1 n2 ... nn ]T r1 r2 ... rn] + -- Register: \n[.tabs] + Change tab stop positions. This request takes a series of tab + specifiers as arguments (optionally divided into two groups with + the letter 'T') that indicate where each tab stop is to be, + overriding any previous settings. The default scaling unit is 'm'. + Invoking 'ta' without an argument removes all tab stops. GNU + 'troff''s startup value is 'T 0.5i'. + + Tab stops can be specified absolutely--as distances from the left + margin. The following example sets six tab stops, one every inch. + + .ta 1i 2i 3i 4i 5i 6i + + Tab stops can also be specified using a leading '+', which means + that the specified tab stop is set relative to the previous tab + stop. For example, the following is equivalent to the previous + example. + + .ta 1i +1i +1i +1i +1i +1i + + GNU 'troff' supports an extended syntax to specify repeating tab + stops. These stops appear after a 'T' argument. Their values are + always taken as distances relative to the previous tab stop. This + is the idiomatic way to specify tab stops at equal intervals in + 'groff'. The following is, yet again, the same as the previous + examples. It does more, in fact, since it defines an infinite + number of tab stops at one-inch intervals. + + .ta T 1i + + Now we are ready to interpret the full syntax given above. The + 'ta' request sets tabs at positions N1, N2, ..., NN, then at NN+R1, + NN+R2, ..., NN+RN, then at NN+RN+R1, NN+RN+R2, ..., NN+RN+RN, and + so on. + + For example, '4c +6c T 3c 5c 2c' is equivalent to '4c 10c 13c 18c + 20c 23c 28c 30c ...'. + + Text written to a tab column (i.e., between two tab stops, or + between a tab stop and an output line boundary) may be aligned to + the right or left, or centered in the column. This alignment is + determined by appending 'R', 'L', or 'C' to the tab specifier. The + default is 'L'. + + .ta 1i 2iC 3iR + + The beginning of an output line is not a tab stop; the text that + begins an output line is placed according to the configured + alignment and indentation; see *note Manipulating Filling and + Adjustment:: and *note Line Layout::. + + A tab stop is converted into a non-breakable horizontal movement + that cannot be adjusted. + + .ll 2i + .ds foo a\tb\tc + .ta T 1i + \*[foo] + error-> warning: cannot break line + => a b c + + The above creates a single output line that is a bit longer than + two inches (we use a string to show exactly where the tab stops + are). Now consider the following. + + .ll 2i + .ds bar a\tb c\td + .ta T 1i + \*[bar] + error-> warning: cannot adjust line + => a b + => c d + + GNU 'troff' first converts the line's tab stops into unbreakable + horizontal movements, then breaks after 'b'. This usually isn't + what you want. + + Superfluous tab characters--those that do not correspond to a tab + stop--are ignored except for the first, which delimits the + characters belonging to the last tab stop for right-alignment or + centering. + + .ds Z foo\tbar\tbaz + .ds ZZ foo\tbar\tbazqux + .ds ZZZ foo\tbar\tbaz\tqux + .ta 2i 4iR + \*[Z] + .br + \*[ZZ] + .br + \*[ZZZ] + .br + => foo bar baz + => foo bar bazqux + => foo bar bazqux + + The first line right-aligns "baz" within the second tab stop. The + second line right-aligns "bazqux" within it. The third line + right-aligns only "baz" because of the additional tab character, + which marks the end of the text occupying the last tab stop + defined. + + Tab stops are associated with the environment (*note + Environments::). + + The read-only register '.tabs' contains a string representation of + the current tab settings suitable for use as an argument to the + 'ta' request.(1) (*note Tabs and Fields-Footnote-1::) + + .ds tab-string \n[.tabs] + \*[tab-string] + => T120u + + -- Request: .tc [c] + Set the tab repetition character to the ordinary or special + character C; normally, no glyph is written when moving to a tab + stop (and some output devices may output space characters to + achieve this motion). A "tab repetition character" causes the + formatter to write as many instances of C as are necessary to + occupy the interval from the horizontal drawing position to the + next tab stop. With no argument, GNU 'troff' reverts to the + default behavior. The tab repetition character is associated with + the environment (*note Environments::). Only a single character of + C is recognized; any excess is ignored. + + -- Request: .linetabs n + -- Register: \n[.linetabs] + If N is missing or non-zero, activate "line-tabs"; deactivate it + otherwise (the default). Active line-tabs cause GNU 'troff' to + compute tab distances relative to the start of the output line + instead of the input line. + + .de Tabs + . ds x a\t\c + . ds y b\t\c + . ds z c + . ta 1i 3i + \\*x + \\*y + \\*z + .. + .Tabs + .br + .linetabs + .Tabs + => a b c + => a b c + + Line-tabs activation is associated with the environment (*note + Environments::). The read-only register '.linetabs' interpolates 1 + if line-tabs are active, and 0 otherwise. + +* Menu: + +* Leaders:: +* Fields:: + + +File: groff.info, Node: Tabs and Fields-Footnotes, Up: Tabs and Fields + + (1) Plan 9 'troff' uses the register '.S' for this purpose. + + +File: groff.info, Node: Leaders, Next: Fields, Prev: Tabs and Fields, Up: Tabs and Fields + +5.12.1 Leaders +-------------- + +Sometimes it is desirable to fill a tab stop with a given glyph, but +also use tab stops normally on the same output line. An example is a +table of contents entry that uses dots to bridge the entry name with its +page number, which is itself aligned between tab stops. The 'roff' +language provides "leaders" for this purpose.(1) (*note +Leaders-Footnote-1::) + + A leader character (ISO and EBCDIC code point 1, also known as SOH or +"start of heading"), behaves similarly to a tab character: it moves to +the next tab stop. The difference is that for this movement, the +default fill character is a period '.'. + + -- Escape sequence: \a + Interpolate a leader in copy mode; see *note Copy Mode::. + + -- Request: .lc [c] + Set the leader repetition character to the ordinary or special + character C. Recall *note Tabs and Leaders::: when encountering a + leader character in the input, the formatter writes as many dots + '.' as are necessary until reaching the next tab stop; this is the + "leader definition character". Omitting C unsets the leader + character. With no argument, GNU 'troff' treats leaders the same + as tabs. The leader repetition character is associated with the + environment (*note Environments::). Only a single C is recognized; + any excess is ignored. + + A table of contents, for example, may define tab stops after a +section number, a title, and a gap to be filled with leader dots. The +page number follows the leader, after a right-aligned final tab stop +wide enough to house the largest page number occurring in the document. + + .ds entry1 19.\tThe Prophet\a\t98 + .ds entry2 20.\tAll Astir\a\t101 + .ta .5i 4.5i +.5iR + .nf + \*[entry1] + \*[entry2] + => 19. The Prophet............................. 98 + => 20. All Astir............................... 101 + + +File: groff.info, Node: Leaders-Footnotes, Up: Leaders + + (1) This is pronounced to rhyme with "feeder", and refers to how the +glyphs "lead" the eye across the page to the corresponding page number +or other datum. + + +File: groff.info, Node: Fields, Prev: Leaders, Up: Tabs and Fields + +5.12.2 Fields +------------- + +"Fields" are a more general way of laying out tabular data. A field is +defined as the data between a pair of "delimiting characters". It +contains substrings that are separated by "padding characters". The +width of a field is the distance on the _input_ line from the position +where the field starts to the next tab stop. A padding character +inserts an adjustable space similar to TeX's '\hss' command (thus it can +even be negative) to make the sum of all substring lengths plus the +adjustable space equal to the field width. If more than one padding +character is inserted, the available space is evenly distributed among +them. + + -- Request: .fc [delim-char [padding-char]] + Define a delimiting and a padding character for fields. If the + latter is missing, the padding character defaults to a space + character. If there is no argument at all, the field mechanism is + disabled (which is the default). In contrast to, e.g., the tab + repetition character, delimiting and padding characters are _not_ + associated with the environment (*note Environments::). + + .fc # ^ + .ta T 3i + #foo^bar^smurf# + .br + #foo^^bar^smurf# + => foo bar smurf + => foo bar smurf + + +File: groff.info, Node: Character Translations, Next: troff and nroff Modes, Prev: Tabs and Fields, Up: GNU troff Reference + +5.13 Character Translations +=========================== + +A "translation" is a mapping of an input character to an output glyph. +The mapping occurs at output time, i.e., the input character gets +assigned the metric information of the mapped output character right +before input tokens are converted to nodes (*note Gtroff Internals::, +for more on this process). + + -- Request: .tr abcd... + -- Request: .trin abcd... + Translate character A to glyph B, character C to glyph D, and so + on. If there is an odd number of characters in the argument, the + last one is translated to a fixed-width space (the same one + obtained by the '\' escape sequence). + + The 'trin' request is identical to 'tr', but when you unformat a + diversion with 'asciify' it ignores the translation. *Note + Diversions::, for details about the 'asciify' request. + + Some notes: + + * Special characters ('\(XX', '\[XXX]', '\C'XXX'', '\'', '\`', + '\-', '\_'), glyphs defined with the 'char' request, and + numbered glyphs ('\N'XXX'') can be translated also. + + * The '\e' escape can be translated also. + + * Characters can be mapped onto the '\%' and '\~' escape + sequences (but '\%' and '\~' can't be mapped onto another + glyph). + + * The following characters can't be translated: space (with one + exception, see below), backspace, newline, leader (and '\a'), + tab (and '\t'). + + * Translations are not considered for finding the soft hyphen + character set with the 'shc' request. + + * The pair 'C\&' (an arbitrary character C followed by the dummy + character) maps this character to "nothing". + + .tr a\& + foo bar + => foo br + + Even the space character can be mapped to the dummy character. + + .tr aa \& + foo bar + => foobar + + As shown in the example, the space character can't be the + first character/glyph pair as an argument of 'tr'. + Additionally, it is not possible to map the space character to + any other glyph; requests like '.tr aa x' undo '.tr aa \&' + instead. + + If justification is active, lines are justified in spite of + the 'empty' space character (but there is no minimal distance, + i.e., the space character, between words). + + * After an output glyph has been constructed (this happens at + the moment immediately before the glyph is appended to an + output glyph list, either by direct output, in a macro, + diversion, or string), it is no longer affected by 'tr'. + + * Translating character to glyphs where one of them or both are + undefined is possible also; 'tr' does not check whether the + elements of its argument exist. + + *Note Gtroff Internals::. + + * Without an argument, the 'tr' request is ignored. + + -- Request: .trnt abcd... + 'trnt' is the same as the 'tr' request except that the translations + do not apply to text that is transparently throughput into a + diversion with '\!'. *Note Diversions::. + + For example, + + .tr ab + .di x + \!.tm a + .di + .x + + prints 'b' to the standard error stream; if 'trnt' is used instead + of 'tr' it prints 'a'. + + +File: groff.info, Node: troff and nroff Modes, Next: Line Layout, Prev: Character Translations, Up: GNU troff Reference + +5.14 'troff' and 'nroff' Modes +============================== + +Historically, 'nroff' and 'troff' were two separate programs; the former +for terminal output, the latter for typesetters. GNU 'troff' merges +both functions into one executable(1) (*note troff and nroff +Modes-Footnote-1::) that sends its output to a device driver ('grotty' +for terminal devices, 'grops' for PostScript, and so on) which +interprets this intermediate output format. When discussing AT&T +'troff', it makes sense to talk about "'nroff' mode" and "'troff' mode" +since the differences are hard-coded. GNU 'troff' takes information +from device and font description files without handling requests +specially if a terminal output device is used, so such a strong +distinction is unnecessary. + + Usually, a macro package can be used with all output devices. +Nevertheless, it is sometimes necessary to make a distinction between +terminal and non-terminal devices: GNU 'troff' provides two built-in +conditions 'n' and 't' for the 'if', 'ie', and 'while' requests to +decide whether GNU 'troff' shall behave like 'nroff' or like 'troff'. + + -- Request: .troff + Make the 't' built-in condition true (and the 'n' built-in + condition false) for 'if', 'ie', and 'while' conditional requests. + This is the default if GNU 'troff' (_not_ 'groff') is started with + the '-R' switch to avoid loading of the startup files 'troffrc' and + 'troffrc-end'. Without '-R', GNU 'troff' stays in 'troff' mode if + the output device is not a terminal (e.g., 'ps'). + + -- Request: .nroff + Make the 'n' built-in condition true (and the 't' built-in + condition false) for 'if', 'ie', and 'while' conditional requests. + This is the default if GNU 'troff' uses a terminal output device; + the code for switching to 'nroff' mode is in the file 'tty.tmac', + which is loaded by the startup file 'troffrc'. + + *Note Conditionals and Loops::, for more details on built-in +conditions. + + +File: groff.info, Node: troff and nroff Modes-Footnotes, Up: troff and nroff Modes + + (1) A GNU 'nroff' program is available for convenience; it calls GNU +'troff' to perform the formatting. + + +File: groff.info, Node: Line Layout, Next: Line Continuation, Prev: troff and nroff Modes, Up: GNU troff Reference + +5.15 Line Layout +================ + +The following drawing shows the dimensions that 'gtroff' uses for +placing a line of output onto the page. They are labeled with the +request that manipulates each dimension. + + -->| in |<-- + |<-----------ll------------>| + +----+----+----------------------+----+ + | : : : | + +----+----+----------------------+----+ + -->| po |<-- + |<--------paper width---------------->| + +These dimensions are: + +'po' + "Page offset"--this is the leftmost position of text on the final + output, defining the "left margin". + +'in' + "Indentation"--this is the distance from the left margin where text + is printed. + +'ll' + "Line length"--this is the distance from the left margin to right + margin. + + The right margin is not explicitly configured; the combination of +page offset and line length provides the information necessary to derive +it. + + A simple demonstration: + + .ll 3i + This is text without indentation. + The line length has been set to 3\~inches. + .in +.5i + .ll -.5i + Now the left and right margins are both increased. + .in + .ll + Calling .in and .ll without parameters restores + the previous values. + + => This is text without indenta- + => tion. The line length has + => been set to 3 inches. + => Now the left and + => right margins are + => both increased. + => Calling .in and .ll without + => parameters restores the previ- + => ous values. + + -- Request: .po [offset] + -- Request: .po +offset + -- Request: .po -offset + -- Register: \n[.o] + Set page offset to OFFSET (or increment or decrement its current + value by OFFSET). If invoked without an argument, the page offset + is restored to the value before the previous 'po' request. This + request does not cause a break; the page offset in effect when an + output line is broken prevails (*note Manipulating Filling and + Adjustment::). The initial value is 1i and the default scaling + unit is 'm'. On terminal devices, the page offset is set to zero + by a driver-specific macro file, 'tty.tmac'. The current page + offset can be found in the read-only register '.o'. This request + is incorrectly documented in the AT&T 'troff' manual as using a + default scaling unit of 'v'. + + .po 3i + \n[.o] + => 720 + .po -1i + \n[.o] + => 480 + .po + \n[.o] + => 720 + + -- Request: .in [indent] + -- Request: .in +indent + -- Request: .in -indent + -- Register: \n[.i] + Set indentation to INDENT (or increment or decrement the current + value by INDENT). This request causes a break. Initially, there + is no indentation. + + If 'in' is called without an argument, the indentation is reset to + the previous value before the last call to 'in'. The default + scaling unit is 'm'. + + If a negative indentation value is specified (which is not + allowed), 'gtroff' emits a warning in category 'range' and sets the + indentation to zero. + + The effect of 'in' is delayed until a partially collected line (if + it exists) is output. A temporary indentation value is reset to + zero also. + + The current indentation (as set by 'in') can be found in the + read-only register '.i'. The indentation is associated with the + environment (*note Environments::). + + -- Request: .ti offset + -- Request: .ti +offset + -- Request: .ti -offset + -- Register: \n[.in] + Temporarily indent the next output line by OFFSET. If an increment + or decrement value is specified, adjust the temporary indentation + relative to the value set by the 'in' request. + + This request causes a break; its value is associated with the + environment (*note Environments::). The default scaling unit is + 'm'. A call of 'ti' without an argument is ignored. + + If the total indentation value is negative (which is not allowed), + 'gtroff' emits a warning in category 'range' and sets the temporary + indentation to zero. 'Total indentation' is either OFFSET if + specified as an absolute value, or the temporary plus normal + indentation, if OFFSET is given as a relative value. + + The effect of 'ti' is delayed until a partially collected line (if + it exists) is output. + + The read-only register '.in' is the indentation that applies to the + current output line. + + The difference between '.i' and '.in' is that the latter takes into + account whether a partially collected line still uses the old + indentation value or a temporary indentation value is active. + + -- Request: .ll [length] + -- Request: .ll +length + -- Request: .ll -length + -- Register: \n[.l] + -- Register: \n[.ll] + Set the line length to LENGTH (or increment or decrement the + current value by LENGTH). Initially, the line length is set to + 6.5i. The effect of 'll' is delayed until a partially collected + line (if it exists) is output. The default scaling unit is 'm'. + + If 'll' is called without an argument, the line length is reset to + the previous value before the last call to 'll'. If a negative + line length is specified (which is not allowed), 'gtroff' emits a + warning in category 'range' and sets the line length to zero. The + line length is associated with the environment (*note + Environments::). + + The current line length (as set by 'll') can be found in the + read-only register '.l'. The read-only register '.ll' is the line + length that applies to the current output line. + + Similar to '.i' and '.in', the difference between '.l' and '.ll' is + that the latter takes into account whether a partially collected + line still uses the old line length value. + + +File: groff.info, Node: Line Continuation, Next: Page Layout, Prev: Line Layout, Up: GNU troff Reference + +5.16 Line Continuation +====================== + +When filling is enabled, input and output line breaks generally do not +correspond. The 'roff' language therefore distinguishes input and +output line continuation. + + -- Escape sequence: \ + '\' (a backslash immediately followed by a newline) suppresses + the effects of that newline in the input. The next input line thus + retains the classification of its predecessor as a control or text + line. '\' is useful for managing line lengths in the input + during document maintenance; you can break an input line in the + middle of a request invocation, macro call, or escape sequence. + Input line continuation is invisible to the formatter, with two + exceptions: the '|' operator recognizes the new input line (*note + Numeric Expressions::), and the input line counter register '.c' is + incremented. + + .ll 50n + .de I + . ft I + . nop \\$* + . ft + .. + Our film class watched + .I The Effect of Gamma Rays on Man-in-the-Moon + Marigolds. \" whoops, the input line wrapped + .br + .I My own opus begins on line \n[.c] \ + and ends on line \n[.c]. + => Our film class watched The Effect of Gamma Rays on + => Man-in-the-Moon Marigolds. + => My own opus begins on line 11 and ends on line 12. + + -- Escape sequence: \c + -- Register: \n[.int] + '\c' continues an output line. Nothing after it on the input line + is formatted. In contrast to '\', a line after '\c' remains a + new input line, so a control character is recognized at its + beginning. The visual results depend on whether filling is + enabled; see *note Manipulating Filling and Adjustment::. + + * If filling is enabled, a word interrupted with '\c' is + continued with the text on the next input text line, without + an intervening space. + + This is a te\c + st. + => This is a test. + + * If filling is disabled, the next input text line after '\c' is + handled as a continuation of the same input text line. + + .nf + This is a \c + test. + => This is a test. + + An intervening control line that causes a break overrides '\c', + flushing out the pending output line in the usual way. + + The '.int' register contains a positive value if the last output + line was continued with '\c'; this datum is associated with the + environment (*note Environments::).(1) (*note Line + Continuation-Footnote-1::) + + +File: groff.info, Node: Line Continuation-Footnotes, Up: Line Continuation + + (1) Historically, the '\c' escape sequence has proven challenging to +characterize. Some sources say it "connects the next input text" (to +the input line on which it appears); others describe it as +"interrupting" text, on the grounds that a text line is interrupted +without breaking, perhaps to inject a request invocation or macro call. + + +File: groff.info, Node: Page Layout, Next: Page Control, Prev: Line Continuation, Up: GNU troff Reference + +5.17 Page Layout +================ + +The formatter permits configuration of the page length and page number. + + -- Request: .pl [length] + -- Request: .pl +length + -- Request: .pl -length + -- Register: \n[.p] + Change (increase or decrease) the page length per the numeric + expression LENGTH. The default scaling unit is 'v'. A negative + LENGTH is valid, but an uncommon application: it prevents page + location traps from being sprung,(1) (*note Page + Layout-Footnote-1::) and each output line is placed on a new page. + If LENGTH is invalid, GNU 'troff' emits a warning in category + 'number'. If LENGTH is absent or invalid, '11i' is assumed. + + The read-only register '.p' interpolates the current page length. + + -- Request: .pn num + -- Request: .pn +num + -- Request: .pn -num + -- Register: \n[.pn] + Change (increase or decrease) the page number of the _next_ page + per the numeric expression NUM. If NUM is invalid, GNU 'troff' + emits a warning in category 'number' and ignores the request. + Without an argument, 'pn' is ignored. + + The read-only register '.pn' interpolates NUM if set by 'pn' on the + current page, or the current page number plus 1. + + The formatter offers special support for typesetting headers and +footers, collectively termed "titles". Titles have an independent line +length, and their placement on the page is not restricted. + + -- Request: .tl 'left'center'right' + Format an output line as a title consisting of LEFT, CENTER, and + RIGHT, each aligned accordingly. The delimiter need not be a + neutral apostrophe: 'tl' accepts the same delimiters as most escape + sequences; see *note Delimiters::. If not used as the delimiter, + any "page number character" character is replaced with the current + page number; the default is '%'; see the the 'pc' request below. + Without an argument, 'tl' is ignored. 'tl' writes the title line + immediately, ignoring any partially collected line. + + It is not an error to omit delimiters after the first. For + example, '.tl /Thesis' is interpreted as '.tl /Thesis///': it sets + a title line comprising only the left-aligned word 'Thesis'. + + -- Request: .lt [length] + -- Request: .lt +length + -- Request: .lt -length + -- Register: \n[.lt] + Change (increase or decrease) the line length used by titles per + the numeric expression LENGTH. The default scaling unit is 'm'. + If LENGTH is negative, GNU emits a warning in category 'range' and + treats LENGTH as '0'. If LENGTH is invalid, GNU 'troff' emits a + warning in category 'number' and ignores the request. The + formatter's default title length is '6.5i'. With no argument, the + title length is restored to the previous value. The title length + is is associated with the environment (*note Environments::). + + The read-only register '.lt' interpolates the title line length. + + -- Request: .pc [char] + Set the page number character to CHAR. With no argument, the page + number character is disabled. 'pc' does not affect the + register '%'. + + The following example exercises title features. + + .lt 50n + This is my partially collected + .tl 'Isomers 2023'%'Dextrose Edition' + line. + => Isomers 2023 1 Dextrose Edition + => This is my partially collected line. + + We most often see titles used in page header and footer traps. *Note +Traps::. + + +File: groff.info, Node: Page Layout-Footnotes, Up: Page Layout + + (1) *Note Traps::. + + +File: groff.info, Node: Page Control, Next: Using Fonts, Prev: Page Layout, Up: GNU troff Reference + +5.18 Page Control +================= + +Discretionary page breaks can prevent the unwanted separation of +content. A new page number takes effect during page ejection; see *note +The Implicit Page Trap::. + + -- Request: .bp [page-number] + -- Request: .bp +page-number + -- Request: .bp -page-number + -- Register: \n[%] + Break the page and change (increase or decrease) the next page + number per the numeric expression PAGE-NUMBER. If PAGE-NUMBER is + invalid, GNU 'troff' emits a warning in category 'number' and + ignores the argument. This request causes a break. A page break + advances the vertical drawing position to the bottom of the page, + springing traps. *Note Page Location Traps::. 'bp' has effect + only if invoked within the top-level diversion.(1) (*note Page + Control-Footnote-1::) This request is incorrectly documented in the + AT&T 'troff' manual as having a default scaling unit of 'v'. + + The register '%' interpolates the current page number. + + .de BP + ' bp \" schedule page break once current line is output + .. + + -- Request: .ne [space] + Force a page break if insufficient vertical space is available + (assert "needed" space). 'ne' tests the distance to the next page + location trap; see *note Page Location Traps::, and breaks the page + if that amount is less than SPACE. The default scaling unit is + 'v'. If SPACE is invalid, GNU 'troff' emits a warning in category + 'number' and ignores the argument. If SPACE is not specified, '1v' + is assumed. + + We can require space for at least the first two output lines of a + paragraph, preventing its first line from being widowed at the page + bottom. + + .ne 2v + Considering how common illness is, + how tremendous the spiritual change that it brings, + how astonishing, + when the lights of health go down, + the undiscovered countries that are then disclosed, + what wastes and deserts of the soul a slight attack + of influenza brings to view, + + This method is reliable only if no output line is pending when 'ne' + is invoked. When macro packages are used, this is often not the + case: their paragraphing macros perform the break. You may need to + experiment with placing the 'ne' after the paragraphing macro, or + 'br' and 'ne' before it. + + 'ne' is also useful to force grouping of section headings with + their subsequent paragraphs, or tables with their captions and/or + explanations. Macro packages often use 'ne' with diversions to + implement keeps and displays; see *note Diversions::. They may + also offer parameters for widow and orphan management. + + -- Request: .sv [space] + -- Request: .os + Require vertical space as 'ne' does, but also save it for later + output by the 'os' request. If SPACE is available before the next + page location trap, it is output immediately. Both requests ignore + a partially collected line, taking effect at the next break. 'sv' + and 'os' ignore no-space mode (recall *note Manipulating + Spacing::). While the 'sv' request allows negative values for + SPACE, 'os' ignores them. The default scaling unit is 'v'. If + SPACE is not specified, '1v' is assumed. + + -- Register: \n[nl] + 'nl' interpolates or sets the vertical drawing position. When the + formatter starts, the first page transition hasn't happened yet, + and 'nl' is negative. If a header trap has been planted on the + page (typically at vertical position '0'), you can assign a + negative value to 'nl' to spring it if that page has already + started (*note Page Location Traps::). + + .de HD + . sp + . tl ''Goldbach Solution'' + . sp + .. + . + First page. + .bp + .wh 0 HD \" plant header trap at top of page + .nr nl (-1) + Second page. + => First page. + => + => (blank lines elided) + => + => Goldbach Solution + => + => (blank lines elided) + => + => Second page. + + Without resetting 'nl' to a negative value, the trap just planted + would be active beginning with the _next_ page, not the current + one. + + *Note Diversions::, for a comparison of 'nl' with the '.h' and '.d' + registers. + + +File: groff.info, Node: Page Control-Footnotes, Up: Page Control + + (1) *Note Diversions::. + + +File: groff.info, Node: Using Fonts, Next: Manipulating Type Size and Vertical Spacing, Prev: Page Control, Up: GNU troff Reference + +5.19 Using Fonts +================ + +In digital typography, a "font" is a collection of characters in a +specific typeface that a device can render as glyphs at a desired +size.(1) (*note Using Fonts-Footnote-1::) A 'roff' formatter can change +typefaces at any point in the text. The basic faces are a set of +"styles" combining upright and slanted shapes with normal and heavy +stroke weights: 'R', 'I', 'B', and 'BI'--these stand for roman, italic, +bold, and bold-italic. For linguistic text, GNU 'troff' groups +typefaces into "families" containing each of these styles.(2) (*note +Using Fonts-Footnote-2::) A "text font" is thus often a family combined +with a style, but it need not be: consider the 'ps' and 'pdf' devices' +'ZCMI' (Zapf Chancery Medium italic)--often, no other style of Zapf +Chancery Medium is provided. On typesetting devices, at least one +"special font" is available, comprising "unstyled" glyphs for +mathematical operators and other purposes. + + Like AT&T 'troff', GNU 'troff' does not itself load or manipulate a +digital font file;(3) (*note Using Fonts-Footnote-3::) instead it works +with a "font description file" that characterizes it, including its +glyph repertoire and the "metrics" (dimensions) of each glyph.(4) +(*note Using Fonts-Footnote-4::) This information permits the formatter +to accurately place glyphs with respect to each other. Before using a +font description, the formatter associates it with a "mounting +position", a place in an ordered list of available typefaces. So that a +document need not be strongly coupled to a specific font family, in GNU +'troff' an output device can associate a style in the abstract sense +with a mounting position. Thus the default family can be combined with +a style dynamically, producing a "resolved font name". + + Fonts often have trademarked names, and even Free Software fonts can +require renaming upon modification. 'groff' maintains a convention that +a device's serif font family is given the name 'T' ("Times"), its +sans-serif family 'H' ("Helvetica"), and its monospaced family 'C' +("Courier"). Historical inertia has driven 'groff''s font identifiers +to short uppercase abbreviations of font names, as with 'TR', 'TI', +'TB', 'TBI', and a special font 'S'. + + The default family used with abstract styles can be changed at any +time; initially, it is 'T'. Typically, abstract styles are arranged in +the first four mounting positions in the order shown above. The default +mounting position, and therefore style, is always '1' ('R'). By issuing +appropriate formatter instructions, you can override these defaults +before your document writes its first glyph. + + Terminal output devices cannot change font families and lack special +fonts. They support style changes by overstriking, or by altering +ISO 6429/ECMA-48 "graphic renditions" (character cell attributes). + +* Menu: + +* Selecting Fonts:: +* Font Families:: +* Font Positions:: +* Using Symbols:: +* Character Classes:: +* Special Fonts:: +* Artificial Fonts:: +* Ligatures and Kerning:: +* Italic Corrections:: +* Dummy Characters:: + + +File: groff.info, Node: Using Fonts-Footnotes, Up: Using Fonts + + (1) Terminals and some output devices have fonts that render at only +one or two sizes. As examples of the latter, take the 'groff' 'lj4' +device's Lineprinter, and 'lbp''s Courier and Elite faces. + + (2) Font designers prepare families such that the styles share +esthetic properties. + + (3) Historically, the fonts 'troff's dealt with were not Free +Software or, as with the Graphic Systems C/A/T, did not even exist in +the digital domain. + + (4) *Note Font Description File Format::. + diff --git a/doc/groff.info-2 b/doc/groff.info-2 new file mode 100644 index 0000000..44572a0 --- /dev/null +++ b/doc/groff.info-2 @@ -0,0 +1,7529 @@ +This is groff.info, produced by makeinfo version 7.0.3 from groff.texi. + +This manual documents GNU 'troff' version 1.23.0. + + Copyright © 1994-2023 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document 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, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". +INFO-DIR-SECTION Typesetting +START-INFO-DIR-ENTRY +* Groff: (groff). The GNU roff document formatting system. +END-INFO-DIR-ENTRY + + +File: groff.info, Node: Selecting Fonts, Next: Font Families, Prev: Using Fonts, Up: Using Fonts + +5.19.1 Selecting Fonts +---------------------- + +We use "font" to refer to any of several means of identifying a font: by +mounting position ('3'), by abstract style ('B'), or by its identifier +('TB'). + + -- Request: .ft [font] + -- Escape sequence: \ff + -- Escape sequence: \f(fn + -- Escape sequence: \f[font] + -- Register: \n[.fn] + The 'ft' request selects the typeface FONT. If the argument is + absent or 'P', it selects the previously chosen font. If FONT is a + non-negative integer, it is interpreted as mounting position; the + font mounted there is selected. If that position refers to an + abstract style, it is combined with the default family (see 'fam' + and '\F' below) to make a resolved font name. If the mounting + position is not a style and no font is mounted there, GNU 'troff' + emits a warning in category 'font' and ignores the request. + + If FONT matches a style name, it is combined with the current + family to make a resolved font name. Otherwise, FONT is assumed to + already be a resolved font name. + + The resolved font name is subject to translation (see request 'ftr' + below). Next, the (possibly translated) font name's mounting + position is looked up; if not mounted, FONT is sought on the file + system as a font description file and, if located, automatically + mounted at the next available position (see register '.fp' below). + If the font was mounted using an identifier different from its font + description file name (see request 'fp' below), that file name is + then looked up. If a font description file for the resolved font + name is not found, GNU 'troff' emits a warning in category 'font' + and ignores the request. + + The '\f' escape sequence is similar, using one-character name (or + mounting position) F, two-character name FN, or a name FONT of + arbitrary length. '\f[]' selects the previous font. The syntax + form '\fP' is supported for backward compatibility, and '\f[P]' for + consistency. + + eggs, bacon, + .ft I + spam, + .ft + and sausage. + .br + eggs, bacon, \fIspam,\fP and sausage. + => eggs, bacon, spam, and sausage + => eggs, bacon, spam, and sausage + + The current and previously selected fonts are properties of the + environment (*note Environments::). + + The read-only string-valued register '.fn' contains the resolved + font name of the selected font. + + '\f' doesn't produce an input token in GNU 'troff'; it thus can be + used in requests that expect a single-character argument. We can + assign a font to a margin character as follows (*note + Miscellaneous::). + + .mc \f[I]x\f[] + + -- Request: .ftr f [g] + Translate font F to font G. Whenever a font named F is referred to + in a '\f' escape sequence, in the 'F' and 'S' conditional + operators, or in the 'ft', 'ul', 'bd', 'cs', 'tkf', 'special', + 'fspecial', 'fp', or 'sty' requests, font G is used. If G is + missing or equal to F the translation is undone. + + Font translations cannot be chained. + + .ftr XXX TR + .ftr XXX YYY + .ft XXX + error-> warning: can't find font 'XXX' + + -- Request: .fzoom f [zoom] + -- Register: \n[.zoom] + Set magnification of font F to factor ZOOM, which must be a + non-negative integer multiple of 1/1000th. This request is useful + to adjust the optical size of a font in relation to the others. In + the example below, font 'CR' is magnified by 10% (the zoom factor + is thus 1.1). + + .fam P + .fzoom CR 1100 + .ps 12 + Palatino and \f[CR]Courier\f[] + + A missing or zero value of ZOOM is the same as a value of 1000, + which means no magnification. F must be a resolved font name, not + an abstract style. + + The magnification of a font is completely transparent to GNU + 'troff'; a change of the zoom factor doesn't cause any effect + except that the dimensions of glyphs, (word) spaces, kerns, etc., + of the affected font are adjusted accordingly. + + The zoom factor of the current font is available in the read-only + register '.zoom', in multiples of 1/1000th. It returns zero if + there is no magnification. + + +File: groff.info, Node: Font Families, Next: Font Positions, Prev: Selecting Fonts, Up: Using Fonts + +5.19.2 Font Families +-------------------- + +To accommodate the wide variety of fonts available, GNU 'troff' +distinguishes "font families" and "font styles". A resolved font name +is the catenation of a font family and a style. Selecting an abstract +style causes GNU 'troff' to combine it with the default font family. + + You can thus compose a document using abstract styles exclusively for +its body or running text, selecting a specific family only for titles or +examples, for instance, and change the default family on the command +line (recall *note Groff Options::). + + Fonts for the devices 'ps', 'pdf', 'dvi', 'lj4', 'lbp', and the X11 +devices support this mechanism. By default, GNU 'troff' uses the Times +family with the four styles 'R', 'I', 'B', and 'BI'. + + -- Request: .fam [family] + -- Register: \n[.fam] + -- Escape sequence: \Ff + -- Escape sequence: \F(fm + -- Escape sequence: \F[family] + Set the default font family, used in combination with abstract + styles to construct a resolved font name, to FAMILY (one-character + name F, two-character name FM). If no argument is given, GNU + 'troff' selects the previous font family; if there none, is it + falls back to the device's default(1) (*note Font + Families-Footnote-1::) or its own ('T'). + + The '\F' escape sequence works similarly. In disanalogy to '\f', + '\FP' makes 'P' the default family. Use '\F[]' to select the + previous default family. The default font family is available in + the read-only string-valued register '.fam'; it is associated with + the environment (*note Environments::). + + spam, \" startup defaults are T (Times) R (roman) + .fam H \" make Helvetica the default family + spam, \" family H + style R = HR + .ft B \" family H + style B = HB + spam, + .ft CR \" Courier roman (default family not changed) + spam, + .ft \" back to Helvetica bold + spam, + .fam T \" make Times the default family + spam, \" family T + style B = TB + .ft AR \" font AR (not a style) + baked beans, + .ft R \" family T + style R = TR + and spam. + + '\F' doesn't produce an input token in GNU 'troff'. As a + consequence, it can be used in requests like 'mc' (which expects a + single character as an argument) to change the font family on the + fly. + + .mc \F[P]x\F[] + + -- Request: .sty n style + -- Register: \n[.sty] + Associate an abstract style STYLE with mounting position N, which + must be a non-negative integer. If the requests 'cs', 'bd', 'tkf', + 'uf', or 'fspecial' are applied to an abstract style, they are + instead applied to the member of the current family corresponding + to that style. + + The default family can be set with the '-f' option (*note Groff + Options::). The 'styles' command in the 'DESC' file controls which + font positions (if any) are initially associated with abstract + styles rather than fonts. + + *Caution:* The STYLE argument is not validated. Errors may occur + later, when the formatter attempts to construct a resolved font + name, or format a character for output. + + .nr BarPos \n[.fp] + .sty \n[.fp] Bar + .fam Foo + .ft \n[BarPos] + .tm .f=\n[.f] + A + error-> error: no font family named 'Foo' exists + error-> .f=41 + error-> error: cannot format glyph: no current font + + When an abstract style has been selected, the read-only + string-valued register '.sty' interpolates its name; this datum is + associated with the environment (*note Environments::). Otherwise, + '.sty' interpolates nothing. + + +File: groff.info, Node: Font Families-Footnotes, Up: Font Families + + (1) *Note DESC File Format::. + + +File: groff.info, Node: Font Positions, Next: Using Symbols, Prev: Font Families, Up: Using Fonts + +5.19.3 Font Positions +--------------------- + +To support typeface indirection through abstract styles, and for +compatibility with AT&T 'troff', the formatter maintains a list of font +"positions" at which fonts required by a document are "mounted". An +output device's description file 'DESC' typically configures a set of +pre-mounted fonts; see *note Device and Font Description Files::. A +font need not be explicitly mounted before it is selected; GNU 'troff' +will search 'GROFF_FONT_PATH' for it by name and mount it at the first +free mounting position on demand. + + -- Request: .fp pos id [font-description-file-name] + -- Register: \n[.f] + -- Register: \n[.fp] + Mount a font under the name ID at mounting position POS, a + non-negative integer. When the formatter starts up, it reads the + output device's description to mount an initial set of faces, and + selects font position 1. Position 0 is unused by default. Unless + the FONT-DESCRIPTION-FILE-NAME argument is given, ID should be the + name of a font description file stored in a directory corresponding + to the selected output device. GNU 'troff' does not traverse + directories to locate the font description file. + + The optional third argument enables font names to be aliased, which + can be necessary in compatibility mode since AT&T 'troff' syntax + affords no means of identifying fonts with names longer than two + characters, like 'TBI' or 'ZCMI', in a font selection escape + sequence. *Note Compatibility Mode::. You can also alias fonts on + mounting for convenience or abstraction. (See below regarding the + '.fp' register.) + + .fp \n[.fp] SC ZCMI + Send a \f(SChand-written\fP thank-you note. + .fp \n[.fp] Emph TI + .fp \n[.fp] Strong TB + Are \f[Emph]these names\f[] \f[Strong]comfortable\f[]? + + 'DESC', 'P', and non-negative integers are not usable as font + identifiers. + + The position of the currently selected font (or abstract style) is + available in the read-only register '.f'. It is associated with + the environment (*note Environments::). + + You can copy the value of '.f' to another register to save it for + later use. + + .nr saved-font \n[.f] + ... text involving many font changes ... + .ft \n[saved-font] + + The index of the next (non-zero) free font position is available in + the read-only register '.fp'. Fonts not listed in the 'DESC' file + are automatically mounted at position '\n[.fp]' when selected with + the 'ft' request or '\f' escape sequence. When mounting a font at + a position explicitly with the 'fp' request, this same practice + should be followed, although GNU 'troff' does not enforce this + strictly. + + +File: groff.info, Node: Using Symbols, Next: Character Classes, Prev: Font Positions, Up: Using Fonts + +5.19.4 Using Symbols +-------------------- + +A "glyph" is a graphical representation of a "character". While a +character is an abstraction of semantic information, a glyph is +something that can be seen on screen or paper. A character has many +possible representation forms (for example, the character 'A' can be +written in an upright or slanted typeface, producing distinct glyphs). +Sometimes, a sequence of characters map to a single glyph: this is a +"ligature"--the most common is 'fi'. + + Space characters never become glyphs in GNU 'troff'. If not +discarded (as when trailing on text lines), they are represented by +horizontal motions in the output. + + A "symbol" is simply a named glyph. Within 'gtroff', all glyph names +of a particular font are defined in its font file. If the user requests +a glyph not available in this font, 'gtroff' looks up an ordered list of +"special fonts". By default, the PostScript output device supports the +two special fonts 'SS' (slanted symbols) and 'S' (symbols) (the former +is looked up before the latter). Other output devices use different +names for special fonts. Fonts mounted with the 'fonts' keyword in the +'DESC' file are globally available. To install additional special fonts +locally (i.e., for a particular font), use the 'fspecial' request. + + Here are the exact rules how 'gtroff' searches a given symbol: + + * If the symbol has been defined with the 'char' request, use it. + This hides a symbol with the same name in the current font. + + * Check the current font. + + * If the symbol has been defined with the 'fchar' request, use it. + + * Check whether the current font has a font-specific list of special + fonts; test all fonts in the order of appearance in the last + 'fspecial' call if appropriate. + + * If the symbol has been defined with the 'fschar' request for the + current font, use it. + + * Check all fonts in the order of appearance in the last 'special' + call. + + * If the symbol has been defined with the 'schar' request, use it. + + * As a last resort, consult all fonts loaded up to now for special + fonts and check them, starting with the lowest font number. This + can sometimes lead to surprising results since the 'fonts' line in + the 'DESC' file often contains empty positions, which are filled + later on. For example, consider the following: + + fonts 3 0 0 FOO + + This mounts font 'foo' at font position 3. We assume that 'FOO' is + a special font, containing glyph 'foo', and that no font has been + loaded yet. The line + + .fspecial BAR BAZ + + makes font 'BAZ' special only if font 'BAR' is active. We further + assume that 'BAZ' is really a special font, i.e., the font + description file contains the 'special' keyword, and that it also + contains glyph 'foo' with a special shape fitting to font 'BAR'. + After executing 'fspecial', font 'BAR' is loaded at font + position 1, and 'BAZ' at position 2. + + We now switch to a new font 'XXX', trying to access glyph 'foo' + that is assumed to be missing. There are neither font-specific + special fonts for 'XXX' nor any other fonts made special with the + 'special' request, so 'gtroff' starts the search for special fonts + in the list of already mounted fonts, with increasing font + positions. Consequently, it finds 'BAZ' before 'FOO' even for + 'XXX', which is not the intended behaviour. + + *Note Device and Font Description Files::, and *note Special Fonts::, +for more details. + + The 'groff_char(7)' man page houses a complete list of predefined +special character names, but the availability of any as a glyph is +device- and font-dependent. For example, say + + man -Tdvi groff_char > groff_char.dvi + +to obtain those available with the DVI device and default font +configuration.(1) (*note Using Symbols-Footnote-1::) If you want to use +an additional macro package to change the fonts used, 'groff' (or +'gtroff') must be run directly. + + groff -Tdvi -mec -man groff_char.7 > groff_char.dvi + + Special character names not listed in 'groff_char(7)' are derived +algorithmically, using a simplified version of the Adobe Glyph List +(AGL) algorithm, which is described in +. The (frozen) set of +names that can't be derived algorithmically is called the "'groff' glyph +list (GGL)". + + * A glyph for Unicode character U+XXXX[X[X]], which is not a + composite character is named 'uXXXX[X[X]]'. X must be an uppercase + hexadecimal digit. Examples: 'u1234', 'u008E', 'u12DB8'. The + largest Unicode value is 0x10FFFF. There must be at least four 'X' + digits; if necessary, add leading zeroes (after the 'u'). No zero + padding is allowed for character codes greater than 0xFFFF. + Surrogates (i.e., Unicode values greater than 0xFFFF represented + with character codes from the surrogate area U+D800-U+DFFF) are not + allowed either. + + * A glyph representing more than a single input character is named + + 'u' COMPONENT1 '_' COMPONENT2 '_' COMPONENT3 ... + + Example: 'u0045_0302_0301'. + + For simplicity, all Unicode characters that are composites must be + maximally decomposed to NFD;(2) (*note Using Symbols-Footnote-2::) + for example, 'u00CA_0301' is not a valid glyph name since U+00CA + (LATIN CAPITAL LETTER E WITH CIRCUMFLEX) can be further decomposed + into U+0045 (LATIN CAPITAL LETTER E) and U+0302 (COMBINING + CIRCUMFLEX ACCENT). 'u0045_0302_0301' is thus the glyph name for + U+1EBE, LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND ACUTE. + + * groff maintains a table to decompose all algorithmically derived + glyph names that are composites itself. For example, 'u0100' + (LATIN LETTER A WITH MACRON) is automatically decomposed into + 'u0041_0304'. Additionally, a glyph name of the GGL is preferred + to an algorithmically derived glyph name; 'groff' also + automatically does the mapping. Example: The glyph 'u0045_0302' is + mapped to '^E'. + + * glyph names of the GGL can't be used in composite glyph names; for + example, '^E_u0301' is invalid. + + -- Escape sequence: \(nm + -- Escape sequence: \[name] + -- Escape sequence: \[base-glyph combining-component ...] + Typeset a special character NAME (two-character name NM) or a + composite glyph consisting of BASE-GLYPH overlaid with one or more + COMBINING-COMPONENTs. For example, '\[A ho]' is a capital letter + "A" with a "hook accent" (ogonek). + + There is no special syntax for one-character names--the analogous + form '\N' would collide with other escape sequences. However, the + four escape sequences '\'', '\-', '\_', and '\`', are translated on + input to the special character escape sequences '\[aa]', '\[-]', + '\[ul]', and '\[ga]', respectively. + + A special character name of length one is not the same thing as an + ordinary character: that is, the character 'a' is not the same as + '\[a]'. + + If NAME is undefined, a warning in category 'char' is produced and + the escape is ignored. *Note Warnings::, for information about the + enablement and suppression of warnings. + + GNU 'troff' resolves '\[...]' with more than a single component as + follows: + + * Any component that is found in the GGL is converted to the + 'uXXXX' form. + + * Any component 'uXXXX' that is found in the list of + decomposable glyphs is decomposed. + + * The resulting elements are then concatenated with '_' in + between, dropping the leading 'u' in all elements but the + first. + + No check for the existence of any component (similar to 'tr' + request) is done. + + Examples: + + '\[A ho]' + 'A' maps to 'u0041', 'ho' maps to 'u02DB', thus the final + glyph name would be 'u0041_02DB'. This is not the expected + result: the ogonek glyph 'ho' is a spacing ogonek, but for a + proper composite a non-spacing ogonek (U+0328) is necessary. + Looking into the file 'composite.tmac', one can find + '.composite ho u0328', which changes the mapping of 'ho' while + a composite glyph name is constructed, causing the final glyph + name to be 'u0041_0328'. + + '\[^E u0301]' + '\[^E aa]' + '\[E a^ aa]' + '\[E ^ ']' + '^E' maps to 'u0045_0302', thus the final glyph name is + 'u0045_0302_0301' in all forms (assuming proper calls of the + 'composite' request). + + It is not possible to define glyphs with names like 'A ho' within a + 'groff' font file. This is not really a limitation; instead, you + have to define 'u0041_0328'. + + -- Escape sequence: \C'xxx' + Typeset the glyph of the special character XXX. Normally, it is + more convenient to use '\[XXX]', but '\C' has some advantages: it + is compatible with AT&T device-independent 'troff' (and therefore + available in compatibility mode(3) (*note Using + Symbols-Footnote-3::)) and can interpolate special characters with + ']' in their names. The delimiter need not be a neutral + apostrophe; see *note Delimiters::. + + -- Request: .composite id1 id2 + Map special character name ID1 to ID2 if ID1 is used in '\[...]' + with more than one component. See above for examples. This is a + strict rewriting of the special character name; no check is + performed for the existence of a glyph for either. A set of + default mappings for many accents can be found in the file + 'composite.tmac', loaded by the default 'troffrc' at startup. + + -- Escape sequence: \N'n' + Typeset the glyph with code N in the current font ('n' is _not_ the + input character code). The number N can be any non-negative + decimal integer. Most devices only have glyphs with codes between + 0 and 255; the Unicode output device uses codes in the range + 0-65535. If the current font does not contain a glyph with that + code, special fonts are _not_ searched. The '\N' escape sequence + can be conveniently used in conjunction with the 'char' request: + + .char \[phone] \f[ZD]\N'37' + + The code of each glyph is given in the fourth column in the font + description file after the 'charset' command. It is possible to + include unnamed glyphs in the font description file by using a name + of '---'; the '\N' escape sequence is the only way to use these. + + No kerning is applied to glyphs accessed with '\N'. The delimiter + need not be a neutral apostrophe; see *note Delimiters::. + + A few escape sequences are also special characters. + + -- Escape sequence: \' + An escaped neutral apostrophe is a synonym for '\[aa]' (acute + accent). + + -- Escape sequence: \` + An escaped grave accent is a synonym for '\[ga]' (grave accent). + + -- Escape sequence: \- + An escaped hyphen-minus is a synonym for '\[-]' (minus sign). + + -- Escape sequence: \_ + An escaped underscore ("low line") is a synonym for '\[ul]' + (underrule). On typesetting devices, the underrule is + font-invariant and drawn lower than the underscore '_'. + + -- Request: .cflags n c1 c2 ... + Assign properties encoded by the number N to characters C1, C2, and + so on. + + Input characters, including special characters introduced by an + escape, have certain properties associated with them.(4) (*note + Using Symbols-Footnote-4::) These properties can be modified with + this request. The first argument is the sum of the desired flags + and the remaining arguments are the characters to be assigned those + properties. Spaces between the CN arguments are optional. Any + argument CN can be a character class defined with the 'class' + request rather than an individual character. *Note Character + Classes::. + + The non-negative integer N is the sum of any of the following. + Some combinations are nonsensical, such as '33' (1 + 32). + + '1' + Recognize the character as ending a sentence if followed by a + newline or two spaces. Initially, characters '.?!' have this + property. + + '2' + Enable breaks before the character. A line is not broken at a + character with this property unless the characters on each + side both have non-zero hyphenation codes. This exception can + be overridden by adding 64. Initially, no characters have + this property. + + '4' + Enable breaks after the character. A line is not broken at a + character with this property unless the characters on each + side both have non-zero hyphenation codes. This exception can + be overridden by adding 64. Initially, characters + '\-\[hy]\[em]' have this property. + + '8' + Mark the glyph associated with this character as overlapping + other instances of itself horizontally. Initially, characters + '\[ul]\[rn]\[ru]\[radicalex]\[sqrtex]' have this property. + + '16' + Mark the glyph associated with this character as overlapping + other instances of itself vertically. Initially, the + character '\[br]' has this property. + + '32' + Mark the character as transparent for the purpose of + end-of-sentence recognition. In other words, an + end-of-sentence character followed by any number of characters + with this property is treated as the end of a sentence if + followed by a newline or two spaces. This is the same as + having a zero space factor in TeX. Initially, characters + '"')]*\[dg]\[dd]\[rq]\[cq]' have this property. + + '64' + Ignore hyphenation codes of the surrounding characters. Use + this in combination with values 2 and 4 (initially, no + characters have this property). + + For example, if you need an automatic break point after the + en-dash in numeric ranges like "3000-5000", insert + + .cflags 68 \[en] + + into your document. However, this practice can lead to bad + layout if done thoughtlessly; in most situations, a better + solution instead of changing the 'cflags' value is to insert + '\:' right after the hyphen at the places that really need a + break point. + + The remaining values were implemented for East Asian language + support; those who use alphabetic scripts exclusively can disregard + them. + + '128' + Prohibit a line break before the character, but allow a line + break after the character. This works only in combination + with flags 256 and 512 and has no effect otherwise. + Initially, no characters have this property. + + '256' + Prohibit a line break after the character, but allow a line + break before the character. This works only in combination + with flags 128 and 512 and has no effect otherwise. + Initially, no characters have this property. + + '512' + Allow line break before or after the character. This works + only in combination with flags 128 and 256 and has no effect + otherwise. Initially, no characters have this property. + + In contrast to values 2 and 4, the values 128, 256, and 512 work + pairwise. If, for example, the left character has value 512, and + the right character 128, no break will be automatically inserted + between them. If we use value 6 instead for the left character, a + break after the character can't be suppressed since the neighboring + character on the right doesn't get examined. + + -- Request: .char c [contents] + -- Request: .fchar c [contents] + -- Request: .fschar f c [contents] + -- Request: .schar c [contents] + Define a new character or glyph C to be CONTENTS, which can be + empty. More precisely, 'char' defines a 'groff' object (or + redefines an existing one) that is accessed with the name C on + input, and produces CONTENTS on output. Every time glyph C needs + to be printed, CONTENTS is processed in a temporary environment and + the result is wrapped up into a single object. Compatibility mode + is turned off and the escape character is set to '\' while CONTENTS + is processed. Any emboldening, constant spacing, or track kerning + is applied to this object rather than to individual glyphs in + CONTENTS. + + An object defined by these requests can be used just like a normal + glyph provided by the output device. In particular, other + characters can be translated to it with the 'tr' or 'trin' + requests; it can be made the leader character with the 'lc' + request; repeated patterns can be drawn with it using the '\l' and + '\L' escape sequences; and words containing C can be hyphenated + correctly if the 'hcode' request is used to give the object a + hyphenation code. + + There is a special anti-recursion feature: use of the object within + its own definition is handled like a normal character (not defined + with 'char'). + + The 'tr' and 'trin' requests take precedence if 'char' accesses the + same symbol. + + .tr XY + X + => Y + .char X Z + X + => Y + .tr XX + X + => Z + + The 'fchar' request defines a fallback glyph: 'gtroff' only checks + for glyphs defined with 'fchar' if it cannot find the glyph in the + current font. 'gtroff' carries out this test before checking + special fonts. + + 'fschar' defines a fallback glyph for font F: 'gtroff' checks for + glyphs defined with 'fschar' after the list of fonts declared as + font-specific special fonts with the 'fspecial' request, but before + the list of fonts declared as global special fonts with the + 'special' request. + + Finally, the 'schar' request defines a global fallback glyph: + 'gtroff' checks for glyphs defined with 'schar' after the list of + fonts declared as global special fonts with the 'special' request, + but before the already mounted special fonts. + + *Note Character Classes::. + + -- Request: .rchar c ... + -- Request: .rfschar f c ... + Remove definition of each ordinary or special character C, undoing + the effect of a 'char', 'fchar', or 'schar' request. Those + supplied by font description files cannot be removed. Spaces and + tabs may separate C arguments. + + The request 'rfschar' removes glyph definitions defined with + 'fschar' for font F. + + +File: groff.info, Node: Using Symbols-Footnotes, Up: Using Symbols + + (1) Not all versions of the 'man' program support the '-T' option; +use the subsequent example for an alternative. + + (2) This is "Normalization Form D" as documented in Unicode Standard +Annex #15 (). + + (3) *Note Compatibility Mode::. + + (4) Output glyphs don't--to GNU 'troff', a glyph is simply a box with +an index into a font, a given height above and depth below the baseline, +and a width. + + +File: groff.info, Node: Character Classes, Next: Special Fonts, Prev: Using Symbols, Up: Using Fonts + +5.19.5 Character Classes +------------------------ + +Classes are particularly useful for East Asian languages such as +Chinese, Japanese, and Korean, where the number of needed characters is +much larger than in European languages, and where large sets of +characters share the same properties. + + -- Request: .class name c1 c2 ... + Define a character class (or simply "class") NAME comprising the + characters C1, C2, and so on. + + A class thus defined can then be referred to in lieu of listing all + the characters within it. Currently, only the 'cflags' request can + handle references to character classes. + + In the request's simplest form, each CN is a character (or special + character). + + .class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq] + + Since class and glyph names share the same name space, it is + recommended to start and end the class name with '[' and ']', + respectively, to avoid collisions with existing character names + defined by GNU 'troff' or the user (with 'char' and related + requests). This practice applies the presence of ']' in the class + name to prevent the use of the special character escape form + '\[...]', thus you must use the '\C' escape to access a class with + such a name. + + You can also use a character range notation consisting of a start + character followed by '-' and then an end character. Internally, + GNU 'troff' converts these two symbol names to Unicode code points + (according to the 'groff' glyph list [GGL]), which then give the + start and end value of the range. If that fails, the class + definition is skipped. + + Furthermore, classes can be nested. + + .class [prepunct] , : ; > } + .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016] + + The class '[prepunctx]' thus contains the contents of the class + '[prepunct]' as defined above (the set ', : ; > }'), and characters + in the range between 'U+2013' and 'U+2016'. + + If you want to include '-' in a class, it must be the first + character value in the argument list, otherwise it gets + misinterpreted as part of the range syntax. + + It is not possible to use class names as end points of range + definitions. + + A typical use of the 'class' request is to control line-breaking + and hyphenation rules as defined by the 'cflags' request. For + example, to inhibit line breaks before the characters belonging to + the 'prepunctx' class defined in the previous example, you can + write the following. + + .cflags 2 \C'[prepunctx]' + + See the 'cflags' request in *note Using Symbols::, for more + details. + + +File: groff.info, Node: Special Fonts, Next: Artificial Fonts, Prev: Character Classes, Up: Using Fonts + +5.19.6 Special Fonts +-------------------- + +Special fonts are those that 'gtroff' searches when it cannot find the +requested glyph in the current font. The Symbol font is usually a +special font. + + 'gtroff' provides the following two requests to add more special +fonts. *Note Using Symbols::, for a detailed description of the glyph +searching mechanism in 'gtroff'. + + Usually, only non-TTY devices have special fonts. + + -- Request: .special [s1 s2 ...] + -- Request: .fspecial f [s1 s2 ...] + Use the 'special' request to define special fonts. Initially, this + list is empty. + + Use the 'fspecial' request to designate special fonts only when + font F is active. Initially, this list is empty. + + Previous calls to 'special' or 'fspecial' are overwritten; without + arguments, the particular list of special fonts is set to empty. + Special fonts are searched in the order they appear as arguments. + + All fonts that appear in a call to 'special' or 'fspecial' are + loaded. + + *Note Using Symbols::, for the exact search order of glyphs. + + +File: groff.info, Node: Artificial Fonts, Next: Ligatures and Kerning, Prev: Special Fonts, Up: Using Fonts + +5.19.7 Artificial Fonts +----------------------- + +There are a number of requests and escape sequences for artificially +creating fonts. These are largely vestiges of the days when output +devices did not have a wide variety of fonts, and when 'nroff' and +'troff' were separate programs. Most of them are no longer necessary in +GNU 'troff'. Nevertheless, they are supported. + + -- Escape sequence: \H'height' + -- Escape sequence: \H'+height' + -- Escape sequence: \H'-height' + -- Register: \n[.height] + Change (increment, decrement) the height of the current font, but + not the width. If HEIGHT is zero, restore the original height. + Default scaling unit is 'z'. + + The read-only register '.height' contains the font height as set by + '\H'. + + Currently, only the '-Tps' and '-Tpdf' devices support this + feature. + + '\H' doesn't produce an input token in GNU 'troff'. As a + consequence, it can be used in requests like 'mc' (which expects a + single character as an argument) to change the font on the fly: + + .mc \H'+5z'x\H'0' + + In compatibility mode, 'gtroff' behaves differently: If an + increment or decrement is used, it is always taken relative to the + current type size and not relative to the previously selected font + height. Thus, + + .cp 1 + \H'+5'test \H'+5'test + + prints the word 'test' twice with the same font height (five points + larger than the current font size). + + -- Escape sequence: \S'slant' + -- Register: \n[.slant] + Slant the current font by SLANT degrees. Positive values slant to + the right. Only integer values are possible. + + The read-only register '.slant' contains the font slant as set by + '\S'. + + Currently, only the '-Tps' and '-Tpdf' devices support this + feature. + + '\S' doesn't produce an input token in GNU 'troff'. As a + consequence, it can be used in requests like 'mc' (which expects a + single character as an argument) to change the font on the fly: + + .mc \S'20'x\S'0' + + This escape is incorrectly documented in the AT&T 'troff' manual; + the slant is always set to an absolute value. + + -- Request: .ul [lines] + The 'ul' request normally underlines subsequent lines if a TTY + output device is used. Otherwise, the lines are printed in italics + (only the term 'underlined' is used in the following). The single + argument is the quantity of input lines to be underlined; with no + argument, the next line is underlined. If LINES is zero or + negative, stop the effects of 'ul' (if it was active). Requests + and empty lines do not count for computing the number of underlined + input lines, even if they produce some output like 'tl'. Lines + inserted by macros (e.g., invoked by a trap) do count. + + At the beginning of 'ul', the current font is stored and the + underline font is activated. Within the span of a 'ul' request, it + is possible to change fonts, but after the last line affected by + 'ul' the saved font is restored. + + This number of lines still to be underlined is associated with the + environment (*note Environments::). The underline font can be + changed with the 'uf' request. + + The 'ul' request does not underline spaces. + + -- Request: .cu [lines] + The 'cu' request is similar to 'ul' but underlines spaces as well + (if a TTY output device is used). + + -- Request: .uf font + Set the underline font (globally) used by 'ul' and 'cu'. By + default, this is the font at position 2. FONT can be either a + non-negative font position or the name of a font. + + -- Request: .bd font [offset] + -- Request: .bd font1 font2 [offset] + -- Register: \n[.b] + Embolden FONT by overstriking its glyphs offset by OFFSET units + minus one. + + Two syntax forms are available. + + * Imitate a bold font unconditionally. The first argument + specifies the font to embolden, and the second is the number + of basic units, minus one, by which the two glyphs are offset. + If the second argument is missing, emboldening is turned off. + + FONT can be either a non-negative font position or the name of + a font. + + OFFSET is available in the '.b' read-only register if a + special font is active; in the 'bd' request, its default unit + is 'u'. + + * Imitate a bold form conditionally. Embolden FONT1 by OFFSET + only if font FONT2 is the current font. This request can be + issued repeatedly to set up different emboldening values for + different current fonts. If the second argument is missing, + emboldening is turned off for this particular current font. + + This affects special fonts only (either set up with the + 'special' command in font files or with the 'fspecial' + request). + + -- Request: .cs font [width [em-size]] + Switch to and from "constant glyph space mode". If activated, the + width of every glyph is WIDTH/36 ems. The em size is given + absolutely by EM-SIZE; if this argument is missing, the em value is + taken from the current font size (as set with the 'ps' request) + when the font is effectively in use. Without second and third + argument, constant glyph space mode is deactivated. + + Default scaling unit for EM-SIZE is 'z'; WIDTH is an integer. + + +File: groff.info, Node: Ligatures and Kerning, Next: Dummy Characters, Prev: Artificial Fonts, Up: Using Fonts + +5.19.8 Ligatures and Kerning +---------------------------- + +Ligatures are groups of characters that are run together, i.e, producing +a single glyph. For example, the letters 'f' and 'i' can form a +ligature 'fi' as in the word 'file'. This produces a cleaner look +(albeit subtle) to the printed output. Usually, ligatures are not +available in fonts for TTY output devices. + + Most PostScript fonts support the fi and fl ligatures. The C/A/T +typesetter that was the target of AT&T 'troff' also supported 'ff', +'ffi', and 'ffl' ligatures. Advanced typesetters or 'expert' fonts may +include ligatures for 'ft' and 'ct', although GNU 'troff' does not +support these (yet). + + Only the current font is checked for ligatures and kerns; neither +special fonts nor special charcters defined with the 'char' request (and +its siblings) are taken into account. + + -- Request: .lg [flag] + -- Register: \n[.lg] + Switch the ligature mechanism on or off; if the parameter is + non-zero or missing, ligatures are enabled, otherwise disabled. + Default is on. The current ligature mode can be found in the + read-only register '.lg' (set to 1 or 2 if ligatures are enabled, + 0 otherwise). + + Setting the ligature mode to 2 enables the two-character ligatures + (fi, fl, and ff) and disables the three-character ligatures (ffi + and ffl). + + "Pairwise kerning" is another subtle typesetting mechanism that +modifies the distance between a glyph pair to improve readability. In +most cases (but not always) the distance is decreased. Typewriter-like +fonts and fonts for terminals where all glyphs have the same width don't +use kerning. + + -- Request: .kern [flag] + -- Register: \n[.kern] + Switch kerning on or off. If the parameter is non-zero or missing, + enable pairwise kerning, otherwise disable it. The read-only + register '.kern' is set to 1 if pairwise kerning is enabled, + 0 otherwise. + + If the font description file contains pairwise kerning information, + glyphs from that font are kerned. Kerning between two glyphs can + be inhibited by placing '\&' between them: 'V\&A'. + + *Note Font Description File Format::. + + "Track kerning" expands or reduces the space between glyphs. This +can be handy, for example, if you need to squeeze a long word onto a +single line or spread some text to fill a narrow column. It must be +used with great care since it is usually considered bad typography if +the reader notices the effect. + + -- Request: .tkf f s1 n1 s2 n2 + Enable track kerning for font F. If the current font is F the + width of every glyph is increased by an amount between N1 and N2 + (N1, N2 can be negative); if the current type size is less than or + equal to S1 the width is increased by N1; if it is greater than or + equal to S2 the width is increased by N2; if the type size is + greater than or equal to S1 and less than or equal to S2 the + increase in width is a linear function of the type size. + + The default scaling unit is 'z' for S1 and S2, 'p' for N1 and N2. + + The track kerning amount is added even to the rightmost glyph in a + line; for large values it is thus recommended to increase the line + length by the same amount to compensate. + + +File: groff.info, Node: Italic Corrections, Next: Dummy Characters, Prev: Ligatures and Kerning, Up: Using Fonts + +5.19.9 Italic Corrections +------------------------- + +When typesetting adjacent glyphs from typefaces of different slants, the +space between them may require adjustment. + + -- Escape sequence: \/ + Apply an "italic correction": modify the spacing of the preceding + glyph so that the distance between it and the following glyph is + correct if the latter is of upright shape. For example, if an + italic 'f' is followed immediately by a roman right parenthesis, + then in many fonts the top right portion of the 'f' overlaps the + top left of the right parenthesis, which is ugly. Use this escape + sequence whenever an oblique glyph is immediately followed by an + upright glyph without any intervening space. + + -- Escape sequence: \, + Apply a "left italic correction": modify the spacing of the + following glyph so that the distance between it and the preceding + glyph is correct if the latter is of upright shape. For example, + if a roman left parenthesis is immediately followed by an + italic 'f', then in many fonts the bottom left portion of the 'f' + overlaps the bottom of the left parenthesis, which is ugly. Use + this escape sequence whenever an upright glyph is followed + immediately by an oblique glyph without any intervening space. + + +File: groff.info, Node: Dummy Characters, Prev: Italic Corrections, Up: Using Fonts + +5.19.10 Dummy Characters +------------------------ + +As discussed in *note Requests and Macros::, the first character on an +input line is treated specially. Further, formatting a glyph has many +consequences on formatter state (*note Environments::). Occasionally, +we want to escape this context or embrace some of those consequences +without actually rendering a glyph to the output. + + -- Escape sequence: \& + Interpolate a dummy character, which is constitutive of output but + invisible.(1) (*note Dummy Characters-Footnote-1::) Its presence + alters the interpretation context of a subsequent input character, + and enjoys several applications. + + * Prevent insertion of extra space after an end-of-sentence + character. + + Test. + Test. + => Test. Test. + Test.\& + Test. + => Test. Test. + + * Prevent recognition of a control character. + + .Test + error-> warning: macro 'Test' not defined + \&.Test + => .Test + + * Prevent kerning between two glyphs. + + * Translate a character to "nothing". + + .tr JIjiK\&k\&UVuv + Post universitum, alea jacta est, OK? + => Post vniversitvm, alea iacta est, O? + + The dummy character escape sequence sees use in macro definitions + as a means of ensuring that arguments are treated as text even if + they begin with spaces or control characters. + + .de HD \" typeset a simple bold heading + . sp + . ft B + \&\\$1 \" exercise: remove the \& + . ft + . sp + .. + .HD .\|.\|.\|surprised? + + One way to think about the dummy character is to imagine placing the +symbol '&' in the input at a certain location; if doing so has all the +side effects on formatting that you desire except for sticking an ugly +ampersand in the midst of your text, the dummy character is what you +want in its place. + + -- Escape sequence: \) + Interpolate a transparent dummy character--one that is transparent + to end-of-sentence detection. It behaves as '\&', except that '\&' + is treated as letters and numerals normally are after '.', '?' and + '!'; '\&' cancels end-of-sentence detection, and '\)' does not. + + .de Suffix-& + . nop \&\\$1 + .. + . + .de Suffix-) + . nop \)\\$1 + .. + . + Here's a sentence.\c + .Suffix-& ' + Another one.\c + .Suffix-) ' + And a third. + => Here's a sentence.' Another one.' And a third. + + +File: groff.info, Node: Dummy Characters-Footnotes, Up: Dummy Characters + + (1) Opinions of this escape sequence's name abound. "Zero-width +space" is a popular misnomer: 'roff' formatters do not treat it like a +space. Ossanna called it a "non-printing, zero-width character", but +the character causes _output_ even though it does not "print". If no +output line is pending, the dummy character starts one. Contrast an +empty input document with one containing only '\&'. The former produces +no output; the latter, a blank page. + + +File: groff.info, Node: Manipulating Type Size and Vertical Spacing, Next: Colors, Prev: Using Fonts, Up: GNU troff Reference + +5.20 Manipulating Type Size and Vertical Spacing +================================================ + +These concepts were introduced in *note Page Geometry::. The height of +a font's tallest glyph is one em, which is equal to the type size in +points.(1) (*note Manipulating Type Size and Vertical +Spacing-Footnote-1::) A vertical spacing of less than 120% of the type +size can make a document hard to read. Larger proportions can be useful +to spread the text for annotations or proofreader's marks. By default, +GNU 'troff' uses 10 point type on 12 point spacing. Typographers call +the difference between type size and vertical spacing "leading".(2) +(*note Manipulating Type Size and Vertical Spacing-Footnote-2::) + +* Menu: + +* Changing the Type Size:: +* Changing the Vertical Spacing:: +* Using Fractional Type Sizes:: + + +File: groff.info, Node: Manipulating Type Size and Vertical Spacing-Footnotes, Up: Manipulating Type Size and Vertical Spacing + + (1) In text fonts, the tallest glyphs are typically parentheses. +Unfortunately, in many cases the actual dimensions of the glyphs in a +font do not closely match its declared type size! For example, in the +standard PostScript font families, 10-point Times sets better with +9-point Helvetica and 11-point Courier than if all three were used at +10 points. + + (2) Rhyme with "sledding"; mechanical typography used lead metal +(Latin _plumbum_). + + +File: groff.info, Node: Changing the Type Size, Next: Changing the Vertical Spacing, Prev: Manipulating Type Size and Vertical Spacing, Up: Manipulating Type Size and Vertical Spacing + +5.20.1 Changing the Type Size +----------------------------- + + -- Request: .ps [size] + -- Request: .ps +size + -- Request: .ps -size + -- Escape sequence: \ssize + -- Register: \n[.s] + Use the 'ps' request or the '\s' escape sequence to change + (increase, decrease) the type size (in scaled points). Specify + SIZE as either an absolute type size, or as a relative change from + the current size. 'ps' with no argument restores the previous + size. The 'ps' request's default scaling unit is 'z'. The + requested size is rounded to the nearest valid size (with ties + rounding down) within the limits supported by the device. If the + requested size is non-positive, it is treated as 1u. + + Type size alteration is incorrectly documented in the AT&T 'troff' + manual, which claims "if [the requested size] is invalid, the next + larger valid size will result, with a maximum of 36".(1) (*note + Changing the Type Size-Footnote-1::) + + The read-only string-valued register '.s' interpolates the type + size in points as a decimal fraction; it is associated with the + environment (*note Environments::). To obtain the type size in + scaled points, interpolate the '.ps' register instead (*note Using + Fractional Type Sizes::). + + The '\s' escape sequence supports a variety of syntax forms. + + '\sN' + Set the type size to N points. N must be a single digit. If + N is 0, restore the previous size. + + '\s+N' + '\s-N' + Increase or decrease the type size by N points. N must be + exactly one digit. + + '\s(NN' + Set the type size to NN points. NN must be exactly two + digits. + + '\s+(NN' + '\s-(NN' + '\s(+NN' + '\s(-NN' + Alter the type size in points by the two-digit value NN. + + *Note Using Fractional Type Sizes::, for further syntactical forms + of the '\s' escape sequence that additionally accept decimal + fractions. + + snap, snap, + .ps +2 + grin, grin, + .ps +2 + wink, wink, \s+2nudge, nudge,\s+8 say no more! + .ps 10 + + The '\s' escape sequence affects the environment immediately and +doesn't produce an input token. Consequently, it can be used in +requests like 'mc', which expects a single character as an argument, to +change the type size on the fly. + + .mc \s[20]x\s[0] + + -- Request: .sizes s1 s2 ... sn [0] + The 'DESC' file specifies which type sizes are allowed by the + output device; see *note DESC File Format::. Use the 'sizes' + request to change this set of permissible sizes. Arguments are in + scaled points; see *note Using Fractional Type Sizes::. Each can + be a single type size (such as '12000'), or a range of sizes (such + as '4000-72000'). You can optionally end the list with a '0'. + + +File: groff.info, Node: Changing the Type Size-Footnotes, Up: Changing the Type Size + + (1) The claim appears to have been true of Ossanna 'troff' for the +C/A/T device; Kernighan made device-independent 'troff' more flexible. + + +File: groff.info, Node: Changing the Vertical Spacing, Next: Using Fractional Type Sizes, Prev: Changing the Type Size, Up: Manipulating Type Size and Vertical Spacing + +5.20.2 Changing the Vertical Spacing +------------------------------------ + + -- Request: .vs [space] + -- Request: .vs +space + -- Request: .vs -space + -- Register: \n[.v] + Set the vertical spacing to, or alter it by, SPACE. The default + scaling unit is 'p'. If 'vs' is called without an argument, the + vertical spacing is reset to the previous value before the last + call to 'vs'. GNU 'troff' emits a warning in category 'range' if + SPACE is negative; the vertical spacing is then set to the smallest + possible positive value, the vertical motion quantum (as found in + the '.V' register). + + '.vs 0' isn't saved in a diversion since it doesn't result in a + vertical motion. You must explicitly issue this request before + interpolating the diversion. + + The read-only register '.v' contains the vertical spacing; it is + associated with the environment (*note Environments::). + +When a break occurs, GNU 'troff' performs the following procedure. + + * Move the drawing position vertically by the "extra pre-vertical + line space", the minimum of all negative '\x' escape sequence + arguments in the pending output line. + + * Move the drawing position vertically by the vertical line spacing. + + * Write out the pending output line. + + * Move the drawing position vertically by the "extra post-vertical + line space", the maximum of all positive '\x' escape sequence + arguments in the line that has just been output. + + * Move the drawing position vertically by the "post-vertical line + spacing" (see below). + + Prefer 'vs' or 'pvs' over 'ls' to produce double-spaced documents. +'vs' and 'pvs' have finer granularity than 'ls'; moreover, some +preprocessors assume single spacing. *Note Manipulating Spacing::, +regarding the '\x' escape sequence and the 'ls' request. + + -- Request: .pvs [space] + -- Request: .pvs +space + -- Request: .pvs -space + -- Register: \n[.pvs] + Set the post-vertical spacing to, or alter it by, SPACE. The + default scaling unit is 'p'. If 'pvs' is called without an + argument, the post-vertical spacing is reset to the previous value + before the last call to 'pvs'. GNU 'troff' emits a warning in + category 'range' if SPACE is negative; the post-vertical spacing is + then set to zero. + + The read-only register '.pvs' contains the post-vertical spacing; + it is associated with the environment (*note Environments::). + + +File: groff.info, Node: Using Fractional Type Sizes, Prev: Changing the Type Size, Up: Manipulating Type Size and Vertical Spacing + +5.20.3 Using Fractional Type Sizes +---------------------------------- + +AT&T 'troff' interpreted all type size measurements in points. Combined +with integer arithmetic, this design choice made it impossible to +support, for instance, ten and a half-point type. In GNU 'troff', an +output device can select a scaling factor that subdivides a point into +"scaled points". A type size expressed in scaled points can thus +represent a non-integral type size. + + A "scaled point" is equal to 1/SIZESCALE points, where SIZESCALE is +specified in the device description file 'DESC', and defaults to 1.(1) +(*note Using Fractional Type Sizes-Footnote-1::) Requests and escape +sequences in GNU 'troff' interpret arguments that represent a type size +in scaled points, which the formatter multiplies by SIZESCALE and +converts to an integer. Arguments treated in this way comprise those to +the escape sequences '\H' and '\s', to the request 'ps', the third +argument to the 'cs' request, and the second and fourth arguments to the +'tkf' request. Scaled points may be specified explicitly with the 'z' +scaling unit. + + For example, if SIZESCALE is 1000, then a scaled point is one +thousandth of a point. The request '.ps 10.5' is synonymous with '.ps +10.5z' and sets the type size to 10,500 scaled points, or 10.5 points. +Consequently, in GNU 'troff', the register '.s' can interpolate a +non-integral type size. + + -- Register: \n[.ps] + This read-only register interpolates the type size in scaled + points; it is associated with the environment (*note + Environments::). + + It makes no sense to use the 'z' scaling unit in a numeric expression +whose default scaling unit is neither 'u' nor 'z', so GNU 'troff' +disallows this. Similarly, it is nonsensical to use a scaling unit +other than 'z' or 'u' in a numeric expression whose default scaling unit +is 'z', and so GNU 'troff' disallows this as well. + + Another GNU 'troff' scaling unit, 's', multiplies by the number of +basic units in a scaled point. Thus, '\n[.ps]s' is equal to '1m' by +definition. Do not confuse the 's' and 'z' scaling units. + + -- Register: \n[.psr] + -- Register: \n[.sr] + Output devices may be limited in the type sizes they can employ. + The '.s' and '.ps' registers represent the type size selected by + the output driver as it understands a device's capability. The + last _requested_ type size is interpolated in scaled points by the + read-only register '.psr' and in points as a decimal fraction by + the read-only string-valued register '.sr'. Both are associated + with the environment (*note Environments::). + + For example, if a type size of 10.95 points is requested, and the + nearest size permitted by a 'sizes' request (or by the 'sizes' or + 'sizescale' directives in the device's 'DESC' file) is 11 points, + the output driver uses the latter value. + + The '\s' escape sequence offers the following syntax forms that work +with fractional type sizes and accept scaling units. You may of course +give them integral arguments. The delimited forms need not use the +neutral apostrophe; see *note Delimiters::. + +'\s[N]' +'\s'N'' + Set the type size to N scaled points; N is a numeric expression + with a default scaling unit of 'z'. + +'\s[+N]' +'\s[-N]' +'\s+[N]' +'\s-[N]' +'\s'+N'' +'\s'-N'' +'\s+'N'' +'\s-'N'' + Increase or decrease the type size by N scaled points; N is a + numeric expression (which may start with a minus sign) with a + default scaling unit of 'z'. + + +File: groff.info, Node: Using Fractional Type Sizes-Footnotes, Up: Using Fractional Type Sizes + + (1) *Note Device and Font Description Files::. + + +File: groff.info, Node: Colors, Next: Strings, Prev: Manipulating Type Size and Vertical Spacing, Up: GNU troff Reference + +5.21 Colors +=========== + +GNU 'troff' supports color output with a variety of color spaces and up +to 16 bits per channel. Some devices, particularly terminals, may be +more limited. When color support is enabled, two colors are current at +any given time: the "stroke color", with which glyphs, rules (lines), +and geometric objects like circles and polygons are drawn, and the "fill +color", which can be used to paint the interior of a closed geometric +figure. + + -- Request: .color [n] + -- Register: \n[.color] + If N is missing or non-zero, enable the output of color-related + device-independent output commands (this is the default); + otherwise, disable them. This request sets a global flag; it does + not produce an input token (*note Gtroff Internals::). + + The read-only register '.color' is 1 if colors are enabled, + 0 otherwise. + + Color can also be disabled with the '-c' command-line option. + + -- Request: .defcolor ident scheme color-component ... + Define a color named IDENT. SCHEME selects a color space and + determines the quantity of required COLOR-COMPONENTs; it must be + one of 'rgb' (three components), 'cmy' (three), 'cmyk' (four), or + 'gray' (one). 'grey' is accepted as a synonym of 'gray'. The + color components can be encoded as a single hexadecimal value + starting with '#' or '##'. The former indicates that each + component is in the range 0-255 (0-FF), the latter the range + 0-65,535 (0-FFFF). + + .defcolor half gray #7f + .defcolor pink rgb #FFC0CB + .defcolor magenta rgb ##ffff0000ffff + + Alternatively, each color component can be specified as a decimal + fraction in the range 0-1, interpreted using a default scaling unit + of 'f', which multiplies its value by 65,536 (but clamps it at + 65,535). + + .defcolor gray50 rgb 0.5 0.5 0.5 + .defcolor darkgreen rgb 0.1f 0.5f 0.2f + + Each output device has a color named 'default', which cannot be +redefined. A device's default stroke and fill colors are not +necessarily the same. For the 'dvi', 'html', 'pdf', 'ps', and 'xhtml' +output devices, GNU 'troff' automatically loads a macro file defining +many color names at startup. By the same mechanism, the devices +supported by 'grotty' recognize the eight standard ISO 6429/EMCA-48 +color names.(1) (*note Colors-Footnote-1::) + + -- Request: .gcolor [color] + -- Escape sequence: \mc + -- Escape sequence: \m(co + -- Escape sequence: \m[color] + -- Register: \n[.m] + Set the stroke color to COLOR. + + .gcolor red + The next words + .gcolor + \m[red]are in red\m[] + and these words are in the previous color. + + The escape sequence '\m[]' restores the previous stroke color, as + does a 'gcolor' request without an argument. + + The name of the current stroke color is available in the read-only + string-valued register '.m'; it is associated with the environment + (*note Environments::). It interpolates nothing when the stroke + color is the default. + + '\m' doesn't produce an input token in GNU 'troff' (*note Gtroff + Internals::). It therefore can be used in requests like 'mc' + (which expects a single character as an argument) to change the + color on the fly: + + .mc \m[red]x\m[] + + -- Request: .fcolor [color] + -- Escape sequence: \Mc + -- Escape sequence: \M(co + -- Escape sequence: \M[color] + -- Register: \n[.M] + Set the fill color for objects drawn with '\D'...'' escape + sequences. The escape sequence '\M[]' restores the previous fill + color, as does an 'fcolor' request without an argument. + + The name of the current fill color is available in the read-only + string-valued register '.M'; it is associated with the environment + (*note Environments::). It interpolates nothing when the fill + color is the default. '\M' doesn't produce an input token in GNU + 'troff'. + + Create an ellipse with a red interior as follows. + + \M[red]\h'0.5i'\D'E 2i 1i'\M[] + + +File: groff.info, Node: Colors-Footnotes, Up: Colors + + (1) also known vulgarly as "ANSI colors" + + +File: groff.info, Node: Strings, Next: Conditionals and Loops, Prev: Colors, Up: GNU troff Reference + +5.22 Strings +============ + +GNU 'troff' supports strings primarily for user convenience. +Conventionally, if one would define a macro only to interpolate a small +amount of text, without invoking requests or calling any other macros, +one defines a string instead. Only one string is predefined by the +language. + + -- String: \*[.T] + Contains the name of the output device (for example, 'utf8' or + 'pdf'). + + The 'ds' request creates a string with a specified name and contents +and the '\*' escape sequence dereferences its name, interpolating its +contents. If the string named by the '\*' escape sequence does not +exist, it is defined as empty, nothing is interpolated, and a warning in +category 'mac' is emitted. *Note Warnings::, for information about the +enablement and suppression of warnings. + + -- Request: .ds name [contents] + -- Request: .ds1 name [contents] + -- Escape sequence: \*n + -- Escape sequence: \*(nm + -- Escape sequence: \*[name [arg1 arg2 ...]] + Define a string called NAME with contents CONTENTS. If NAME + already exists as an alias, the target of the alias is redefined; + see 'als' and 'rm' below. If 'ds' is called with only one + argument, NAME is defined as an empty string. Otherwise, GNU + 'troff' stores CONTENTS in copy mode.(1) (*note + Strings-Footnote-1::) + + The '\*' escape sequence interpolates a previously defined string + variable NAME (one-character name N, two-character name NM). The + bracketed interpolation form accepts arguments that are handled as + macro arguments are; recall *note Calling Macros::. In contrast to + macro calls, however, if a closing bracket ']' occurs in a string + argument, that argument must be enclosed in double quotes. '\*' is + interpreted even in copy mode. When defining strings, argument + interpolations must be escaped if they are to reference parameters + from the calling context; *Note Parameters::. + + .ds cite (\\$1, \\$2) + Gray codes are explored in \*[cite Morgan 1998]. + => Gray codes are explored in (Morgan, 1998). + + *Caution:* Unlike other requests, the second argument to the 'ds' + request consumes the remainder of the input line, including + trailing spaces. This means that comments on a line with such a + request can introduce unwanted space into a string when they are + set off from the material they annotate, as is conventional. + + .ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O \" water + + Instead, place the comment on another line or put the comment + escape sequence immediately adjacent to the last character of the + string. + + .ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O\" water + + Ending string definitions (and appendments) with a comment, even an + empty one, prevents unwanted space from creeping into them during + source document maintenance. + + .ds author Alice Pleasance Liddell\" + .ds empty \" might be appended to later with .as + + An initial neutral double quote '"' in CONTENTS is stripped to + allow embedding of leading spaces. Any other '"' is interpreted + literally, but it is wise to use the special character escape + sequence '\[dq]' instead if the string might be interpolated as + part of a macro argument; see *note Calling Macros::. + + .ds salutation " Yours in a white wine sauce,\" + .ds c-var-defn " char mydate[]=\[dq]2020-07-29\[dq];\" + + Strings are not limited to a single input line of text. '\' + works just as it does elsewhere. The resulting string is stored + _without_ the newlines. Care is therefore required when + interpolating strings while filling is disabled. + + .ds foo This string contains \ + text on multiple lines \ + of input. + + It is not possible to embed a newline in a string that will be + interpreted as such when the string is interpolated. To achieve + that effect, use '\*' to interpolate a macro instead; see *note + Punning Names::. + + Because strings are similar to macros, they too can be defined so + as to suppress AT&T 'troff' compatibility mode when used; see *note + Writing Macros:: and *note Compatibility Mode::. The 'ds1' request + defines a string such that compatibility mode is off when the + string is later interpolated. To be more precise, a "compatibility + save" input token is inserted at the beginning of the string, and a + "compatibility restore" input token at the end. + + .nr xxx 12345 + .ds aa The value of xxx is \\n[xxx]. + .ds1 bb The value of xxx is \\n[xxx]. + . + .cp 1 + . + \*(aa + error-> warning: register '[' not defined + => The value of xxx is 0xxx]. + \*(bb + => The value of xxx is 12345. + + -- Request: .as name [contents] + -- Request: .as1 name [contents] + The 'as' request is similar to 'ds' but appends CONTENTS to the + string stored as NAME instead of redefining it. If NAME doesn't + exist yet, it is created. If 'as' is called with only one + argument, no operation is performed (beyond dereferencing the + string). + + .as salutation " with shallots, onions and garlic,\" + + The 'as1' request is similar to 'as', but compatibility mode is + switched off when the appended portion of the string is later + interpolated. To be more precise, a "compatibility save" input + token is inserted at the beginning of the appended string, and a + "compatibility restore" input token at the end. + + Several requests exist to perform rudimentary string operations. +Strings can be queried ('length') and modified ('chop', 'substring', +'stringup', 'stringdown'), and their names can be manipulated through +renaming, removal, and aliasing ('rn', 'rm', 'als'). + + -- Request: .length reg anything + Compute the number of characters of ANYTHING and store the count in + the register REG. If REG doesn't exist, it is created. ANYTHING + is read in copy mode. + + .ds xxx abcd\h'3i'efgh + .length yyy \*[xxx] + \n[yyy] + => 14 + + -- Request: .chop object + Remove the last character from the macro, string, or diversion + named OBJECT. This is useful for removing the newline from the end + of a diversion that is to be interpolated as a string. This + request can be used repeatedly on the same OBJECT; see *note Gtroff + Internals::, for details on nodes inserted additionally by GNU + 'troff'. + + -- Request: .substring str start [end] + Replace the string named STR with its substring bounded by the + indices START and END, inclusively. The first character in the + string has index 0. If END is omitted, it is implicitly set to the + largest valid value (the string length minus one). Negative + indices count backward from the end of the string: the last + character has index -1, the character before the last has index -2, + and so on. + + .ds xxx abcdefgh + .substring xxx 1 -4 + \*[xxx] + => bcde + .substring xxx 2 + \*[xxx] + => de + + -- Request: .stringdown str + -- Request: .stringup str + Alter the string named STR by replacing each of its bytes with its + lowercase ('stringdown') or uppercase ('stringup') version (if one + exists). Special characters in the string will often transform in + the expected way due to the regular naming convention for accented + characters. When they do not, use substrings and/or catenation. + + .ds resume R\['e]sum\['e] + \*[resume] + .stringdown resume + \*[resume] + .stringup resume + \*[resume] + => Résumé résumé RÉSUMÉ + + (In practice, we would end the 'ds' request with a comment escape +'\"' to prevent space from creeping into the definition during source +document maintenance.) + + -- Request: .rn old new + Rename the request, macro, diversion, or string OLD to NEW. + + -- Request: .rm name + Remove the request, macro, diversion, or string NAME. GNU 'troff' + treats subsequent invocations as if the name had never been + defined. + + -- Request: .als new old + Create an alias NEW for the existing request, string, macro, or + diversion object named OLD, causing the names to refer to the same + stored object. If OLD is undefined, a warning in category 'mac' is + produced, and the request is ignored. *Note Warnings::, for + information about the enablement and suppression of warnings. + + To understand how the 'als' request works, consider two different + storage pools: one for objects (macros, strings, etc.), and another + for names. As soon as an object is defined, GNU 'troff' adds it to + the object pool, adds its name to the name pool, and creates a link + between them. When 'als' creates an alias, it adds a new name to + the name pool that gets linked to the same object as the old name. + + Now consider this example. + + .de foo + .. + . + .als bar foo + . + .de bar + . foo + .. + . + .bar + error-> input stack limit exceeded (probable infinite + error-> loop) + + In the above, 'bar' remains an _alias_--another name for--the + object referred to by 'foo', which the second 'de' request + replaces. Alternatively, imagine that the 'de' request + _dereferences_ its argument before replacing it. Either way, the + result of calling 'bar' is a recursive loop that finally leads to + an error. *Note Writing Macros::. + + To remove an alias, call 'rm' on its name. The object itself is + not destroyed until it has no more names. + + When a request, macro, string, or diversion is aliased, + redefinitions and appendments "write through" alias names. To + replace an alias with a separately defined object, you must use the + 'rm' request on its name first. + + +File: groff.info, Node: Strings-Footnotes, Up: Strings + + (1) *Note Copy Mode::. + + +File: groff.info, Node: Conditionals and Loops, Next: Writing Macros, Prev: Strings, Up: GNU troff Reference + +5.23 Conditionals and Loops +=========================== + +'groff' has 'if' and 'while' control structures like other languages. +However, the syntax for grouping multiple input lines in the branches or +bodies of these structures is unusual. + +* Menu: + +* Operators in Conditionals:: +* if-then:: +* if-else:: +* Conditional Blocks:: +* while:: + + +File: groff.info, Node: Operators in Conditionals, Next: if-then, Prev: Conditionals and Loops, Up: Conditionals and Loops + +5.23.1 Operators in Conditionals +-------------------------------- + +In 'if', 'ie', and 'while' requests, in addition to the numeric +expressions described in *note Numeric Expressions::, several Boolean +operators are available; the members of this expanded class are termed +"conditional expressions". + +'c GLYPH' + True if GLYPH is available, where GLYPH is an ordinary character, a + special character '\(XX' or '\[XXX]', '\N'XXX'', or has been + defined by any of the 'char', 'fchar', 'fschar', or 'schar' + requests. + +'d NAME' + True if a string, macro, diversion, or request called NAME exists. + +'e' + True if the current page is even-numbered. + +'F FONT' + True if FONT exists. FONT is handled as if it were opened with the + 'ft' request (that is, font translation and styles are applied), + without actually mounting it. + +'m COLOR' + True if COLOR is defined. + +'n' + True if the document is being processed in 'nroff' mode. *Note + troff and nroff Modes::. + +'o' + True if the current page is odd-numbered. + +'r REGISTER' + True if REGISTER exists. + +'S STYLE' + True if STYLE is available for the current font family. Font + translation is applied. + +'t' + True if the document is being processed in 'troff' mode. *Note + troff and nroff Modes::. + +'v' + Always false. This condition is recognized only for compatibility + with certain other 'troff' implementations.(1) (*note Operators in + Conditionals-Footnote-1::) + + If the first argument to an 'if', 'ie', or 'while' request begins +with a non-alphanumeric character apart from '!' (see below); it +performs an output comparison test. (2) (*note Operators in +Conditionals-Footnote-2::) + +''XXX'YYY'' + True if formatting the comparands XXX and YYY produces the same + output commands. The delimiter need not be a neutral apostrophe: + the output comparison operator accepts the same delimiters as most + escape sequences; see *note Delimiters::. This "output comparison + operator" formats XXX and YYY in separate environments; after the + comparison, the resulting data are discarded. + + .ie "|"\fR|\fP" true + .el false + => true + + The resulting glyph properties, including font family, style, size, + and slant, must match, but not necessarily the requests and/or + escape sequences used to obtain them. In the previous example, '|' + and '\fR|\fP' result in '|' glyphs in the same typefaces at the + same positions, so the comparands are equal. If '.ft I' had been + added before the '.ie', they would differ: the first '|' would + produce an italic '|', not a roman one. Motions must match in + orientation and magnitude to within the applicable horizontal and + vertical motion quanta of the device, after rounding. '.if + "\u\d"\v'0'"' is false even though both comparands result in zero + net motion, because motions are not interpreted or optimized but + sent as-is to the output.(3) (*note Operators in + Conditionals-Footnote-3::) On the other hand, '.if "\d"\v'0.5m'"' + is true, because '\d' is defined as a downward motion of one-half + em.(4) (*note Operators in Conditionals-Footnote-4::) + + Surround the comparands with '\?' to avoid formatting them; this + causes them to be compared character by character, as with string + comparisons in other programming languages. + + .ie "\?|\?"\?\fR|\fP\?" true + .el false + => false + + Since comparands protected with '\?' are read in copy mode (*note + Copy Mode::), they need not even be valid 'groff' syntax. The + escape character is still lexically recognized, however, and + consumes the next character. + + .ds a \[ + .ds b \[ + .if '\?\*a\?'\?\*b\?' a and b equivalent + .if '\?\\?'\?\\?' backslashes equivalent + => a and b equivalent + + The above operators can't be combined with most others, but a leading +'!', not followed immediately by spaces or tabs, complements an +expression. + + .nr x 1 + .ie !r x register x is not defined + .el register x is defined + => register x is defined + + Spaces and tabs are optional immediately after the 'c', 'd', 'F', +'m', 'r', and 'S' operators, but right after '!', they end the predicate +and the conditional evaluates true.(5) (*note Operators in +Conditionals-Footnote-5::) + + .nr x 1 + .ie ! r x register x is not defined + .el register x is defined + => r x register x is not defined + +The unexpected 'r x' in the output is a clue that our conditional was +not interpreted as we planned, but matters may not always be so obvious. + + +File: groff.info, Node: Operators in Conditionals-Footnotes, Up: Operators in Conditionals + + (1) This refers to 'vtroff', a translator that would convert the +C/A/T output from early-vintage AT&T 'troff' to a form suitable for +Versatec and Benson-Varian plotters. + + (2) Strictly, letters not otherwise recognized _are_ treated as +output comparison delimiters. For portability, it is wise to avoid +using letters not in the list above; for example, Plan 9 'troff' uses +'h' to test a mode it calls 'htmlroff', and GNU 'troff' may provide +additional operators in the future. + + (3) Because formatting of the comparands takes place in a dummy +environment, vertical motions within them cannot spring traps. + + (4) All of this is to say that the lists of output nodes created by +formatting XXX and YYY must be identical. *Note Gtroff Internals::. + + (5) This bizarre behavior maintains compatibility with AT&T 'troff'. + + +File: groff.info, Node: if-then, Next: if-else, Prev: Operators in Conditionals, Up: Conditionals and Loops + +5.23.2 if-then +-------------- + + -- Request: .if cond-expr anything + Evaluate the conditional expression COND-EXPR, and if it evaluates + true (or to a positive value), interpret the remainder of the line + ANYTHING as if it were an input line. Recall from *note Invoking + Requests:: that any quantity of spaces between arguments to + requests serves only to separate them; leading spaces in ANYTHING + are thus not seen. ANYTHING effectively _cannot_ be omitted; if + COND-EXPR is true and ANYTHING is empty, the newline at the end of + the control line is interpreted as a blank input line (and + therefore a blank text line). + + super\c + tanker + .nr force-word-break 1 + super\c + .if ((\n[force-word-break] = 1) & \n[.int]) + tanker + => supertanker super tanker + + -- Request: .nop anything + Interpret ANYTHING as if it were an input line. This is similar to + '.if 1'. 'nop' is not really "no operation"; its argument _is_ + processed--unconditionally. It can be used to cause text lines to + share indentation with surrounding control lines. + + .als real-MAC MAC + .de wrapped-MAC + . tm MAC: called with arguments \\$@ + . nop \\*[real-MAC]\\ + .. + .als MAC wrapped-MAC + \# Later... + .als MAC real-MAC + + In the above, we've used aliasing, 'nop', and the interpolation of + a macro as a string to interpose a wrapper around the macro 'MAC' + (perhaps to debug it). + + +File: groff.info, Node: if-else, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops + +5.23.3 if-else +-------------- + + -- Request: .ie cond-expr anything + -- Request: .el anything + Use the 'ie' and 'el' requests to write an if-then-else. The first + request is the "if" part and the latter is the "else" part. + Unusually among programming languages, any number of + non-conditional requests may be interposed between the 'ie' branch + and the 'el' branch. + + .nr a 0 + .ie \na a is non-zero. + .nr a +1 + .el a was not positive but is now \na. + => a was not positive but is now 1. + + Another way in which 'el' is an ordinary request is that it does + not lexically "bind" more tightly to its 'ie' counterpart than it + does to any other request. This fact can surprise C programmers. + + .nr a 1 + .nr z 0 + .ie \nz \ + . ie \na a is true + . el a is false + .el z is false + error-> warning: unbalanced 'el' request + => a is false + + To conveniently nest conditionals, keep reading. + + +File: groff.info, Node: Conditional Blocks, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops + +5.23.4 Conditional Blocks +------------------------- + +It is frequently desirable for a control structure to govern more than +one request, macro call, text line, or a combination of the foregoing. +The opening and closing brace escape sequences '\{' and '\}' define such +groups. These "conditional blocks" can furthermore be nested. + + -- Escape sequence: \{ + -- Escape sequence: \} + '\{' begins a conditional block; it must appear (after optional + spaces and tabs) immediately subsequent to the conditional + expression of an 'if', 'ie', or 'while' request,(1) (*note + Conditional Blocks-Footnote-1::) or as the argument to an 'el' + request. + + '\}' ends a condition block and should appear on a line with other + occurrences of itself as necessary to match '\{' sequences. It can + be preceded by a control character, spaces, and tabs. Input after + any quantity of '\}' sequences on the same line is processed only + if all of the preceding conditions to which they correspond are + true. Furthermore, a '\}' closing the body of a 'while' request + must be the last such escape sequence on an input line. + + Brace escape sequences outside of control structures have no + meaning and produce no output. + + *Caution:* Input lines using '\{' often end with '\RET', especially + in macros that consist primarily of control lines. Forgetting to + use '\RET' on an input line after '\{' is a common source of error. + + We might write the following in a page header macro. If we delete +'\RET', the header will carry an unwanted extra empty line (except on +page 1). + + .if (\\n[%] != 1) \{\ + . ie ((\\n[%] % 2) = 0) .tl \\*[even-numbered-page-title] + . el .tl \\*[odd-numbered-page-title] + .\} + + Let us take a closer look at how conditional blocks nest. + + A + .if 0 \{ B + C + D + \}E + F + => A F + + N + .if 1 \{ O + . if 0 \{ P + Q + R\} S\} T + U + => N O U + + The above behavior may challenge the intuition; it was implemented to +retain compatibility with AT&T 'troff'. For clarity, it is idiomatic to +end input lines with '\{' (followed by '\' if appropriate), and to +precede '\}' on an input line with nothing more than a control +character, spaces, tabs, and other instances of itself. + + We can use 'ie', 'el', and conditional blocks to simulate the +multi-way "switch" or "case" control structures of other languages. The +following example is adapted from the 'groff' 'man' package. +Indentation is used to clarify the logic. + + .\" Simulate switch/case in roff. + . ie '\\$2'1' .ds title General Commands\" + .el \{.ie '\\$2'2' .ds title System Calls\" + .el \{.ie '\\$2'3' .ds title Library Functions\" + .el \{.ie '\\$2'4' .ds title Kernel Interfaces\" + .el \{.ie '\\$2'5' .ds title File Formats\" + .el \{.ie '\\$2'6' .ds title Games\" + .el \{.ie '\\$2'7' .ds title Miscellaneous Information\" + .el \{.ie '\\$2'8' .ds title System Management\" + .el \{.ie '\\$2'9' .ds title Kernel Development\" + .el .ds title \" empty + .\}\}\}\}\}\}\}\} + + +File: groff.info, Node: Conditional Blocks-Footnotes, Up: Conditional Blocks + + (1) *Note while::. + + +File: groff.info, Node: while, Prev: if-else, Up: Conditionals and Loops + +5.23.5 while +------------ + +'groff' provides a looping construct: the 'while' request. Its syntax +matches the 'if' request. + + -- Request: .while cond-expr anything + Evaluate the conditional expression COND-EXPR, and repeatedly + execute ANYTHING unless and until COND-EXPR evaluates false. + ANYTHING, which is often a conditional block, is referred to as the + 'while' request's "body". + + .nr a 0 1 + .while (\na < 9) \{\ + \n+a, + .\} + \n+a + => 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 + + GNU 'troff' treats the body of a 'while' request similarly to that + of a 'de' request (albeit one not read in copy mode(1) (*note + while-Footnote-1::)), but stores it under an internal name and + deletes it when the loop finishes. The operation of a macro + containing a 'while' request can slow significantly if the 'while' + body is large. Each time the macro is executed, the 'while' body + is parsed and stored again. + + .de xxx + . nr num 10 + . while (\\n[num] > 0) \{\ + . \" many lines of code + . nr num -1 + . \} + .. + + An often better solution--and one that is more portable, since AT&T + 'troff' lacked the 'while' request--is to instead write a recursive + macro. It will be parsed only once.(2) (*note while-Footnote-2::) + + .de yyy + . if (\\n[num] > 0) \{\ + . \" many lines of code + . nr num -1 + . yyy + . \} + .. + . + .de xxx + . nr num 10 + . yyy + .. + + To prevent infinite loops, the default number of available + recursion levels is 1,000 or somewhat less.(3) (*note + while-Footnote-3::) You can disable this protective measure, or + raise the limit, by setting the 'slimit' register. *Note + Debugging::. + + As noted above, if a 'while' body begins with a conditional block, + its closing brace must end an input line. + + .if 1 \{\ + . nr a 0 1 + . while (\n[a] < 10) \{\ + . nop \n+[a] + .\}\} + error-> unbalanced brace escape sequences + + -- Request: .break + Exit a 'while' loop. Do not confuse this request with a + typographical break or the 'br' request. + + -- Request: .continue + Skip the remainder of a 'while' loop's body, immediately starting + the next iteration. + + +File: groff.info, Node: while-Footnotes, Up: while + + (1) *Note Copy Mode::. + + (2) unless you redefine it + + (3) "somewhat less" because things other than macro calls can be on +the input stack + + +File: groff.info, Node: Writing Macros, Next: Page Motions, Prev: Conditionals and Loops, Up: GNU troff Reference + +5.24 Writing Macros +=================== + +A "macro" is a stored collection of text and control lines that can be +interpolated multiple times. Use macros to define common operations. +Macros are called in the same way that requests are invoked. While +requests exist for the purpose of creating macros, simply calling an +undefined macro, or interpolating it as a string, will cause it to be +defined as empty. *Note Identifiers::. + + -- Request: .de name [end] + Define a macro NAME, replacing the definition of any existing + request, macro, string, or diversion called NAME. If NAME already + exists as an alias, the target of the alias is redefined; recall + *note Strings::. GNU 'troff' enters copy mode,(1) (*note Writing + Macros-Footnote-1::) storing subsequent input lines as the macro + definition. If the optional second argument is not specified, the + definition ends with the control line '..' (two dots). + Alternatively, END identifies a macro whose call syntax at the + start of a control line ends the definition of NAME; END is then + called normally. A macro definition must end in the same + conditional block (if any) in which it began (*note Conditional + Blocks::). Spaces or tabs are permitted after the control + character in the line containing this ending token (either '.' or + 'END'), but a tab immediately after the token prevents its + recognition as the end of a macro definition. The macro END can be + called with arguments.(2) (*note Writing Macros-Footnote-2::) + + Here is a small example macro called 'P' that causes a break and + inserts some vertical space. It could be used to separate + paragraphs. + + .de P + . br + . sp .8v + .. + + We can define one macro within another. Attempting to nest '..' + naïvely will end the outer definition because the inner definition + isn't interpreted as such until the outer macro is later + interpolated. We can use an end macro instead. Each level of + nesting should use a unique end macro. + + An end macro need not be defined until it is called. This fact + enables a nested macro definition to begin inside one macro and end + inside another. Consider the following example.(3) (*note Writing + Macros-Footnote-3::) + + .de m1 + . de m2 m3 + you + .. + .de m3 + Hello, + Joe. + .. + .de m4 + do + .. + .m1 + know? + . m3 + What + .m4 + .m2 + => Hello, Joe. What do you know? + + A nested macro definition _can_ be terminated with '..' and nested + macros _can_ reuse end macros, but these control lines must be + escaped multiple times for each level of nesting. The necessity of + this escaping and the utility of nested macro definitions will + become clearer when we employ macro parameters and consider the + behavior of copy mode in detail. + + 'de' defines a macro that inherits the compatibility mode enablement +status of its context (*note Implementation Differences::). Often it is +desirable to make a macro that uses 'groff' features callable from +contexts where compatibility mode is on; for instance, when writing +extensions to a historical macro package. To achieve this, +compatibility mode needs to be switched off while such a macro is +interpreted--without disturbing that state when it is finished. + + -- Request: .de1 name [end] + The 'de1' request defines a macro to be interpreted with + compatibility mode disabled. When NAME is called, compatibility + mode enablement status is saved; it is restored when the call + completes. Observe the extra backlash before the interpolation of + register 'xxx'; we'll explore this subject in *note Copy Mode::. + + .nr xxx 12345 + .de aa + The value of xxx is \\n[xxx]. + . br + .. + .de1 bb + The value of xxx is \\n[xxx]. + .. + .cp 1 + .aa + error-> warning: register '[' not defined + => The value of xxx is 0xxx]. + .bb + => The value of xxx is 12345. + + -- Request: .dei name [end] + -- Request: .dei1 name [end] + The 'dei' request defines a macro with its name and end macro + indirected through strings. That is, it interpolates strings named + NAME and END before performing the definition. + + The following examples are equivalent. + + .ds xx aa + .ds yy bb + .dei xx yy + + .de aa bb + + The 'dei1' request bears the same relationship to 'dei' as 'de1' + does to 'de'; it temporarily turns compatibility mode off when NAME + is called. + + -- Request: .am name [end] + -- Request: .am1 name [end] + -- Request: .ami name [end] + -- Request: .ami1 name [end] + 'am' appends subsequent input lines to macro NAME, extending its + definition, and otherwise working as 'de' does. + + To make the previously defined 'P' macro set indented instead of + block paragraphs, add the necessary code to the existing macro. + + .am P + .ti +5n + .. + + The other requests are analogous to their 'de' counterparts. The + 'am1' request turns off compatibility mode during interpretation of + the appendment. The 'ami' request appends indirectly, meaning that + strings NAME and END are interpolated with the resulting names used + before appending. The 'ami1' request is similar to 'ami', + disabling compatibility mode during interpretation of the appended + lines. + + Using 'trace.tmac', you can trace calls to 'de', 'de1', 'am', and +'am1'. You can also use the 'backtrace' request at any point desired to +troubleshoot tricky spots (*note Debugging::). + + *Note Strings::, for the 'als', 'rm', and 'rn' requests to create an +alias of, remove, and rename a macro, respectively. + + Macro identifiers share their name space with requests, strings, and +diversions; see *note Identifiers::. The 'am', 'as', 'da', 'de', 'di', +and 'ds' requests (together with their variants) create a new object +only if the name of the macro, diversion, or string is currently +undefined or if it is defined as a request; normally, they modify the +value of an existing object. *Note the description of the 'als' +request: als, for pitfalls when redefining a macro that is aliased. + + -- Request: .return [anything] + Exit a macro, immediately returning to the caller. If called with + an argument ANYTHING, exit twice--the current macro and the macro + one level higher. This is used to define a wrapper macro for + 'return' in 'trace.tmac'. + +* Menu: + +* Parameters:: +* Copy Mode:: + + +File: groff.info, Node: Writing Macros-Footnotes, Up: Writing Macros + + (1) *Note Copy Mode::. + + (2) While it is possible to define and call a macro '.', you can't +use it as an end macro: during a macro definition, '..' is never handled +as calling '.', even if '.de NAME .' explicitly precedes it. + + (3) Its structure is adapted from, and isomorphic to, part of a +solution by Tadziu Hoffman to the problem of reflowing text multiple +times to find an optimal configuration for it. + + + +File: groff.info, Node: Parameters, Next: Copy Mode, Prev: Writing Macros, Up: Writing Macros + +5.24.1 Parameters +----------------- + +Macro calls and string interpolations optionally accept a list of +arguments; recall *note Calling Macros::. At the time such an +interpolation takes place, these "parameters" can be examined using a +register and a variety of escape sequences starting with '\$'. All such +escape sequences are interpreted even in copy mode, a fact we shall +motivate and explain below (*note Copy Mode::). + + -- Register: \n[.$] + The count of parameters available to a macro or string is kept in + this read-only register. The 'shift' request can change its value. + + Any individual parameter can be accessed by its position in the list +of arguments to the macro call, numbered from left to right starting at +1, with one of the following escape sequences. + + -- Escape sequence: \$n + -- Escape sequence: \$(nn + -- Escape sequence: \$[nnn] + Interpolate the Nth, NNth, or NNNth parameter. The first form + expects only a single digit (1<=N<=9)), the second two digits + (01<=NN<=99)), and the third any positive integer NNN. Macros and + strings accept an unlimited number of parameters. + + -- Request: .shift [n] + Shift the parameters N places (1 by default). This is a "left + shift": what was parameter I becomes parameter I-N. The parameters + formerly in positions 1 to N are no longer available. Shifting by + a non-positive amount performs no operation. The register '.$' is + adjusted accordingly. + + In practice, parameter interpolations are usually seen prefixed with +an extra escape character. This is because the '\$' family of escape +sequences is interpreted even in copy mode.(1) (*note +Parameters-Footnote-1::) + + -- Escape sequence: \$* + -- Escape sequence: \$@ + -- Escape sequence: \$^ + In some cases it is convenient to interpolate all of the parameters + at once (to pass them to a request, for instance). The '\$*' + escape concatenates the parameters, separating them with spaces. + '\$@' is similar, concatenating the parameters, surrounding each + with double quotes and separating them with spaces. If not in + compatibility mode, the interpolation depth of double quotes is + preserved (*note Calling Macros::). '\$^' interpolates all + parameters as if they were arguments to the 'ds' request. + + .de foo + . tm $1='\\$1' + . tm $2='\\$2' + . tm $*='\\$*' + . tm $@='\\$@' + . tm $^='\\$^' + .. + .foo " This is a "test" + error-> $1=' This is a ' + error-> $2='test"' + error-> $*=' This is a test"' + error-> $@='" This is a " "test""' + error-> $^='" This is a "test"' + + '\$*' is useful when writing a macro that doesn't need to + distinguish its arguments, or even to not interpret them; examples + include macros that produce diagnostic messages by wrapping the + 'tm' or 'ab' requests. Use '\$@' when writing a macro that may + need to shift its parameters and/or wrap a macro or request that + finds the count significant. If in doubt, prefer '\$@' to '\$*'. + An application of '\$^' is seen in 'trace.tmac', which redefines + some requests and macros for debugging purposes. + + -- Escape sequence: \$0 + Interpolate the name by which the macro being interpreted was + called. The 'als' request can cause a macro to have more than one + name. Applying string interpolation to a macro does not change + this name. + + .de foo + . tm \\$0 + .. + .als bar foo + . + .de aaa + . foo + .. + .de bbb + . bar + .. + .de ccc + \\*[foo]\\ + .. + .de ddd + \\*[bar]\\ + .. + . + .aaa + error-> foo + .bbb + error-> bar + .ccc + error-> ccc + .ddd + error-> ddd + + +File: groff.info, Node: Parameters-Footnotes, Up: Parameters + + (1) If they were not, parameter interpolations would be similar to +command-line parameters--fixed for the entire duration of a 'roff' +program's run. The advantage of interpolating '\$' escape sequences +even in copy mode is that they can interpolate different contents from +one call to the next, like function parameters in a procedural language. +The additional escape character is the price of this power. + + +File: groff.info, Node: Copy Mode, Prev: Parameters, Up: Writing Macros + +5.24.2 Copy Mode +---------------- + +When GNU 'troff' processes certain requests, most importantly those +which define or append to a macro or string, it does so in "copy mode": +it copies the characters of the definition into a dedicated storage +region, interpolating the escape sequences '\n', '\g', '\$', '\*', '\V', +and '\?' normally; interpreting '\' immediately; discarding +comments '\"' and '\#'; interpolating the current leader, escape, or tab +character with '\a', '\e', and '\t', respectively; and storing all other +escape sequences in an encoded form. + + The complement of copy mode--a 'roff' formatter's behavior when not +defining or appending to a macro, string, or diversion--where all macros +are interpolated, requests invoked, and valid escape sequences processed +immediately upon recognition, can be termed "interpretation mode". + + -- Escape sequence: \\ + The escape character, '\' by default, can escape itself. This + enables you to control whether a given '\n', '\g', '\$', '\*', + '\V', or '\?' escape sequence is interpreted at the time the macro + containing it is defined, or later when the macro is called.(1) + (*note Copy Mode-Footnote-1::) + + .nr x 20 + .de y + .nr x 10 + \&\nx + \&\\nx + .. + .y + => 20 10 + + You can think of '\\' as a "delayed" backslash; it is the escape + character followed by a backslash from which the escape character + has removed its special meaning. Consequently, '\\' is not an + escape sequence in the usual sense. In any escape sequence '\X' + that GNU 'troff' does not recognize, the escape character is + ignored and X is output. An unrecognized escape sequence causes a + warning in category 'escape', with two exceptions--'\\' is the + first. + + -- Escape sequence: \. + '\.' escapes the control character. It is similar to '\\' in that + it isn't a true escape sequence. It is used to permit nested macro + definitions to end without a named macro call to conclude them. + Without a syntax for escaping the control character, this would not + be possible. + + .de m1 + foo + . + . de m2 + bar + \\.. + . + .. + .m1 + .m2 + => foo bar + + The first backslash is consumed while the macro is read, and the + second is interpreted when macro 'm1' is called. + + 'roff' documents should not use the '\\' or '\.' character sequences +outside of copy mode; they serve only to obfuscate the input. Use '\e' +to represent the escape character, '\[rs]' to obtain a backslash glyph, +and '\&' before '.' and ''' where GNU 'troff' expects them as control +characters if you mean to use them literally (recall *note Requests and +Macros::). + + Macro definitions can be nested to arbitrary depth. The mechanics of +parsing the escape character have significant consequences for this +practice. + + .de M1 + \\$1 + . de M2 + \\\\$1 + . de M3 + \\\\\\\\$1 + \\\\.. + . M3 hand. + \\.. + . M2 of + .. + This understeer is getting + .M1 out + => This understeer is getting out of hand. + + Each escape character is interpreted twice--once in copy mode, when +the macro is defined, and once in interpretation mode, when the macro is +called. As seen above, this fact leads to exponential growth in the +quantity of escape characters required to delay interpolation of '\n', +'\g', '\$', '\*', '\V', and '\?' at each nesting level, which can be +daunting. GNU 'troff' offers a solution. + + -- Escape sequence: \E + '\E' represents an escape character that is not interpreted in copy + mode. You can use it to ease the writing of nested macro + definitions. + + .de M1 + . nop \E$1 + . de M2 + . nop \E$1 + . de M3 + . nop \E$1 + \\\\.. + . M3 better. + \\.. + . M2 bit + .. + This vehicle handles + .M1 a + => This vehicle handles a bit better. + + Observe that because '\.' is not a true escape sequence, we can't + use '\E' to keep '..' from ending a macro definition prematurely. + If the multiplicity of backslashes complicates maintenance, use end + macros. + + '\E' is also convenient to define strings containing escape + sequences that need to work when used in copy mode (for example, as + macro arguments), or which will be interpolated at varying macro + nesting depths. We might define strings to begin and end + superscripting as follows.(2) (*note Copy Mode-Footnote-2::) + + .ds { \v'-.9m\s'\En[.s]*7u/10u'+.7m' + .ds } \v'-.7m\s0+.9m' + + When the 'ec' request is used to redefine the escape character, + '\E' also makes it easier to distinguish the semantics of an escape + character from the other meaning(s) its character might have. + Consider the use of an unusual escape character, '-'. + + .nr a 1 + .ec - + .de xx + --na + .. + .xx + => -na + + This result may surprise you; some people expect '1' to be output + since register 'a' has clearly been defined with that value. What + has happened? The robotic replacement of '\' with '-' has led us + astray. You might recognize the sequence '--' more readily with + the default escape character as '\-', the special character escape + sequence for the minus sign glyph. + + .nr a 1 + .ec - + .de xx + -Ena + .. + .xx + => 1 + + +File: groff.info, Node: Copy Mode-Footnotes, Up: Copy Mode + + (1) Compare this to the '\def' and '\edef' commands in TeX. + + (2) These are lightly adapted from the 'groff' implementation of the +'ms' macros. + + +File: groff.info, Node: Page Motions, Next: Drawing Geometric Objects, Prev: Writing Macros, Up: GNU troff Reference + +5.25 Page Motions +================= + +*Note Manipulating Spacing::, for a discussion of the most commonly used +request for vertical motion, 'sp', which spaces downward by one vee. + + -- Request: .mk [reg] + -- Request: .rt [dist] + You can "mark" a location on a page for subsequent "return". 'mk' + takes an argument, a register name in which to store the current + page location. If given no argument, it stores the location in an + internal register. This location can be used later by the 'rt' or + the 'sp' requests (or the '\v' escape). + + The 'rt' request returns _upward_ to the location marked with the + last 'mk' request. If used with an argument, it returns to a + vertical position DIST from the top of the page (no previous call + to 'mk' is necessary in this case). The default scaling unit is + 'v'. + + If a page break occurs between a 'mk' request and its matching 'rt' + request, the 'rt' request is silently ignored. + + A simple implementation of a macro to set text in two columns + follows. + + .nr column-length 1.5i + .nr column-gap 4m + .nr bottom-margin 1m + . + .de 2c + . br + . mk + . ll \\n[column-length]u + . wh -\\n[bottom-margin]u 2c-trap + . nr right-side 0 + .. + . + .de 2c-trap + . ie \\n[right-side] \{\ + . nr right-side 0 + . po -(\\n[column-length]u + \\n[column-gap]u) + . \" remove trap + . wh -\\n[bottom-margin]u + . \} + . el \{\ + . \" switch to right side + . nr right-side 1 + . po +(\\n[column-length]u + \\n[column-gap]u) + . rt + . \} + .. + + Now let us apply our two-column macro. + + .pl 1.5i + .ll 4i + This is a small test that shows how the + rt request works in combination with mk. + + .2c + Starting here, text is typeset in two columns. + Note that this implementation isn't robust + and thus not suited for a real two-column + macro. + => This is a small test that shows how the + => rt request works in combination with mk. + => + => Starting here, isn't robust + => text is typeset and thus not + => in two columns. suited for a + => Note that this real two-column + => implementation macro. + + Several escape sequences enable fine control of movement about the +page. + + -- Escape sequence: \v'expr' + Vertically move the drawing position. EXPR indicates the magnitude + of motion: positive is downward and and negative upward. The + default scaling unit is 'v'. The motion is relative to the current + drawing position unless EXPR begins with the boundary-relative + motion operator '|'. *Note Numeric Expressions::. + + Text processing continues at the new drawing position; usually, + vertical motions should be in balanced pairs to avoid a confusing + page layout. + + '\v' will not spring a vertical position trap. This can be useful; + for example, consider a page bottom trap macro that prints a marker + in the margin to indicate continuation of a footnote. *Note + Traps::. + + A few escape sequences that produce vertical motion are unusual. +They are thought to originate early in AT&T 'nroff' history to achieve +super- and subscripting by half-line motions on line printers and +teletypewriters before the phototypesetter made more precise positioning +available. They are reckoned in ems--not vees--to maintain continuity +with their original purpose of moving relative to the size of the type +rather than the distance between text baselines (vees).(1) (*note Page +Motions-Footnote-1::) + + -- Escape sequence: \r + -- Escape sequence: \u + -- Escape sequence: \d + Move upward 1m, upward .5m, and downward .5m, respectively. + +Let us see these escape sequences in use. + + Obtain 100 cm\u3\d of \ka\d\092\h'|\nau'\r233\dU. + + In the foregoing we have paired '\u' and '\d' to typeset a +superscript, and later a full em negative ("reverse") motion to place a +superscript above a subscript. A numeral-width horizontal motion escape +sequence aligns the proton and nucleon numbers, while '\k' marks a +horizontal position to which '\h' returns so that we could stack them. +(We shall discuss these horizontal motion escape sequences presently.) +In serious applications, we often want to alter the type size of the +-scripts and to fine-tune the vertical motions, as the 'groff' 'ms' +package does with its super- and subscripting string definitions. + + -- Escape sequence: \h'expr' + Horizontally move the drawing position. EXPR indicates the + magnitude of motion: positive is rightward and negative leftward. + The default scaling unit is 'm'. The motion is relative to the + current drawing position unless EXPR begins with the + boundary-relative motion operator '|'. *Note Numeric + Expressions::. + + The following string definition sets the TeX logo.(2) (*note Page +Motions-Footnote-2::) + + .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\" + + There are a number of special-case escape sequences for horizontal +motion. + + -- Escape sequence: \ + Move right one word space. (The input is a backslash followed by a + space.) This escape sequence can be thought of as a + non-adjustable, unbreakable space. Usually you want '\~' instead; + see *note Manipulating Filling and Adjustment::. + + -- Escape sequence: \| + Move one-sixth em to the right on typesetting output devices. If a + glyph named '\|' is defined in the current font, its width is used + instead, even on terminal output devices. + + -- Escape sequence: \^ + Move one-twelfth em to the right on typesetting output devices. If + a glyph named '\^' is defined in the current font, its width is + used instead, even on terminal output devices. + + -- Escape sequence: \0 + Move right by the width of a numeral in the current font. + + Horizontal motions are not discarded at the end of an output line as +word spaces are. *Note Breaking::. + + -- Escape sequence: \w'anything' + -- Register: \n[st] + -- Register: \n[sb] + -- Register: \n[rst] + -- Register: \n[rsb] + -- Register: \n[ct] + -- Register: \n[ssc] + -- Register: \n[skw] + Interpolate the width of ANYTHING in basic units. This escape + sequence allows several properties of formatted output to be + measured without writing it out. + + The length of the string 'abc' is \w'abc'u. + => The length of the string 'abc' is 72u. + + ANYTHING is processed in a dummy environment: this means that font + and type size changes, for example, may occur within it without + affecting subsequent output. + + After each use, '\w' sets several registers. + + 'st' + 'sb' + The maximum vertical displacements of the text baseline above + and below, respectively. The sign convention is opposite that + of relative vertical motions; that is, depth below the + (original) baseline is negative. These registers are + incorrectly documented in the AT&T 'troff' manual as "the + highest and lowest extent of [the argument to '\w'] relative + to the baseline". + + 'rst' + 'rsb' + Like 'st' and 'sb', but taking account of the heights and + depths of glyphs. In other words, these registers store the + highest and lowest vertical positions attained by ANYTHING, + doing what AT&T 'troff' documented 'st' and 'sb' as doing. + + 'ct' + Characterizes the geometry of glyphs occurring in ANYTHING. + + 0 + only short glyphs, no descenders or tall glyphs + + 1 + at least one descender + + 2 + at least one tall glyph + + 3 + at least one each of a descender and a tall glyph + + 'ssc' + The amount of horizontal space (possibly negative) that should + be added to the last glyph before a subscript. + + 'skw' + How far to right of the center of the last glyph in the '\w' + argument, the center of an accent from a roman font should be + placed over that glyph. + + -- Escape sequence: \kp + -- Escape sequence: \k(ps + -- Escape sequence: \k[position] + Store the current horizontal position in the _input_ line in a + register with the name POSITION (one-character name P, + two-character name PS). Use this, for example, to return to the + beginning of a string for highlighting or other decoration. + + -- Register: \n[hp] + The current horizontal position at the input line. + + -- Register: \n[.k] + A read-only register containing the current horizontal output + position (relative to the current indentation). + + -- Escape sequence: \o'abc...' + Overstrike the glyphs of characters A, B, C, ...; the glyphs are + centered, written, and the drawing position advanced by the widest + of the glyphs. + + -- Escape sequence: \zc + Format the character C with zero width; that is, without advancing + the drawing position. Use '\z' to overstrike glyphs aligned to + their left edges, in contrast to '\o''s centering. + + -- Escape sequence: \Z'anything' + Save the drawing position, format ANYTHING, then restore it. Tabs + and leaders in the argument are ignored with an error diagnostic. + + We might implement a strike-through macro thus. + + .de ST + .nr width \w'\\$1' + \Z@\v'-.25m'\l'\\n[width]u'@\\$1 + .. + . + This is + .ST "a test" + an actual emergency! + + +File: groff.info, Node: Page Motions-Footnotes, Up: Page Motions + + (1) At the 'grops' defaults of 10-point type on 12-point vertical +spacing, the difference between half a vee and half an em can be subtle: +large spacings like '.vs .5i' make it obvious. + + (2) *Note Strings::, for an explanation of the trailing '\"'. + + +File: groff.info, Node: Drawing Geometric Objects, Next: Traps, Prev: Page Motions, Up: GNU troff Reference + +5.26 Drawing Geometric Objects +============================== + +A few of the formatter's escape sequences draw lines and other geometric +objects. Combined with each other and with page motion commands (*note +Page Motions::), a wide variety of figures is possible. For complex +drawings, these operations can be cumbersome; the preprocessors 'gpic' +or 'ggrn' are typically used instead. + + The '\l' and '\L' escape sequences draw horizontal and vertical +sequences of glyphs, respectively. Even the simplest of output devices +supports them. + + -- Escape sequence: \l'l' + -- Escape sequence: \l'lc' + Draw a horizontal line of length L from the drawing position. + Rightward motion is positive. Afterward, the drawing position is + at the right end of the line. The default scaling unit is 'm'. + + The optional second parameter C is a character with which to draw + the line. The default is the baseline rule special character, + '\[ru]'. + + If C is a valid scaling unit, put '\&' after L to disambiguate the + input. + + .de textbox + \[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' + .. + + The foregoing outputs a box rule (a vertical line), the text + argument(s), and another box rule. We employ the boundary-relative + motion operator '|'. Finally, the line-drawing escape sequences + draw a radical extender (a form of overline) and an underline from + the drawing position to the position coresponding to beginning of + the _input_ line. The drawing position returns to just after the + right-hand box rule because the lengths of the drawn lines are + negative, as noted above. + + -- Escape sequence: \L'l' + -- Escape sequence: \L'lc' + Draw a vertical line of length L from the drawing position. + Downward motion is positive. The default scaling unit is 'v'. The + default character is the box rule, '\[br]'. As with vertical + motion escape sequences, text processing continues where the line + ends. '\L' is otherwise similar to '\l'. + + $ nroff < This is a + => | + => | + => |test. + + When writing text, the drawing position is at the text baseline; + recall *note Page Geometry::. + + The '\D' escape sequence provides "drawing commands" that direct the +output device to render geometrical objects rather than glyphs. +Specific devices may support only a subset, or may feature additional +ones; consult the man page for the output driver in use. Terminal +devices in particular implement almost none. *Note Graphics Commands::. + + Rendering starts at the drawing position; when finished, the drawing +position is left at the rightmost point of the object, even for closed +figures, except where noted. GNU 'troff' draws stroked (outlined) +objects with the stroke color, and shades filled ones with the fill +color. *Note Colors::. Coordinates H and V are horizontal and vertical +motions relative to the drawing position or previous point in the +command. The default scaling unit for horizontal measurements (and +diameters of circles) is 'm'; for vertical ones, 'v'. + + Circles, ellipses, and polygons can be drawn filled or stroked. +These are independent properties; if you want a filled, stroked figure, +you must draw the same figure twice using each drawing command. A +filled figure is always smaller than an outlined one because the former +is drawn only within its defined area, whereas strokes have a line +thickness (set with '\D't''). + + \h'1i'\v'1i'\ + \# increase line thickness + \Z'\D't 5p''\ + \# draw stroked (unfilled) polygon + \Z'\D'p 3 3 -6 0''\ + \# draw filled (solid) polygon + \Z'\D'P 3 3 -6 0'' + + -- Escape sequence: \D'command argument ...' + Drawing command escape sequence parameters begin with an ordinary + character, COMMAND, selecting the type of object to be drawn, + followed by ARGUMENTs whose meaning is determined by COMMAND. + + '\D'~ H1 V1 ... HN VN'' + Draw a B-spline to each point in sequence, leaving the drawing + position at (HN, VN). + + '\D'a HC VC H V'' + Draw a circular arc centered at (HC, VC) counterclockwise from + the drawing position to a point (H, V) relative to the center. + (1) (*note Drawing Geometric Objects-Footnote-1::) + + '\D'c D'' + Draw a circle of diameter D with its leftmost point at the + drawing position. + + '\D'C D'' + As '\D'C ...'', but the circle is filled. + + '\D'e H V'' + Draw an ellipse of width H and height V with its leftmost + point at the drawing position. + + '\D'E X Y'' + As '\D'e ...'', but the ellipse is filled. + + '\D'l DX DY'' + Draw line from the drawing position to (H, V). + + The following is a macro for drawing a box around a text + argument; for simplicity, the box margin is a fixed at 0.2m. + + .de TEXTBOX + . nr @wd \w'\\$1' + \h'.2m'\ + \h'-.2m'\v'(.2m - \\n[rsb]u)'\ + \D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\ + \D'l (\\n[@wd]u + .4m) 0'\ + \D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\ + \D'l -(\\n[@wd]u + .4m) 0'\ + \h'.2m'\v'-(.2m - \\n[rsb]u)'\ + \\$1\ + \h'.2m' + .. + + The argument is measured with the '\w' escape sequence. Its + width is stored in register '@wd'. '\w' also sets the + registers 'rst' and 'rsb'; these contain its maximum vertical + extents of the argument. Then, four lines are drawn to form a + box, offset by the box margin. + + '\D'p H1 V1 ... HN VN'' + Draw polygon with vertices at drawing position and each point + in sequence. GNU 'troff' closes the polygon by drawing a line + from (HN, VN) back to the initial drawing position. + Afterward, the drawing position is left at (HN, VN). + + '\D'P DX1 DY1 DX2 DY2 ...'' + As '\D'P ...'', but the polygon is filled. + + The following macro is like the '\D'l'' example, but shades + the box. We draw the box before writing the text because + colors in GNU 'troff' have no transparency; in othe opposite + order, the filled polygon would occlude the text. + + .de TEXTBOX + . nr @wd \w'\\$1' + \h'.2m'\ + \h'-.2m'\v'(.2m - \\n[rsb]u)'\ + \M[lightcyan]\ + \D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \ + (\\n[@wd]u + .4m) 0 \ + 0 (\\n[rst]u - \\n[rsb]u + .4m) \ + -(\\n[@wd]u + .4m) 0'\ + \h'.2m'\v'-(.2m - \\n[rsb]u)'\ + \M[]\ + \\$1\ + \h'.2m' + .. + + '\D't N'' + Set the stroke thickness of geometric objects to N basic + units. A zero N selects the minimal supported thickness. A + negative N selects a thickness proportional to the type size; + this is the default. + + In a hazy penumbra between text rendering and drawing commands we +locate the bracket-building escape sequence, '\b'. It can assemble +apparently large glyphs by vertically stacking ordinary ones. + + -- Escape sequence: \b'contents' + Pile and center a sequence of glyphs vertically on the output line. + "Piling" stacks glyphs corresponding to each character in CONTENTS, + read from left to right, and placed from top to bottom. GNU + 'troff' separates the glyphs vertically by 1m, and the pile itself + is centered 0.5m above the text baseline. The horizontal drawing + position is then advanced by the width of the widest glyph in the + pile. + + This rather inflexible positioning algorithm doesn't work with the + 'dvi' output device since its bracket pieces vary in height. + Instead, use the 'geqn' preprocessor. + + *note Manipulating Spacing:: describes how to adjust the vertical + spacing of the output line with the '\x' escape sequence. + + The application of '\b' that lends its name is construction of + brackets, braces, and parentheses when typesetting mathematics. We + might construct a large opening (left) brace as follows. + + \b'\[lt]\[bv]\[lk]\[bv]\[lb]' + + See 'groff_char(7)' for a list of special character identifiers. + + +File: groff.info, Node: Drawing Geometric Objects-Footnotes, Up: Drawing Geometric Objects + + (1) (HC, VC) is adjusted to the point nearest the perpendicular +bisector of the arc's chord. + + +File: groff.info, Node: Deferring Output, Next: Traps, Prev: Drawing Geometric Objects, Up: GNU troff Reference + +5.27 Deferring Output +===================== + +A few 'roff' language elements are generally not used in simple +documents, but arise as page layouts become more sophisticated and +demanding. "Environments" collect formatting parameters like line +length and typeface. A "diversion" stores formatted output for later +use. A "trap" is a condition on the input or output, tested +automatically by the formatter, that is associated with a macro, causing +it to be called when that condition is fulfilled. + + Footnote support often exercises all three of the foregoing features. +A simple implementation might work as follows. A pair of macros is +defined: one starts a footnote and the other ends it. The author calls +the first macro where a footnote marker is desired. The macro +establishes a diversion so that the footnote text is collected at the +place in the body text where its corresponding marker appears. An +environment is created for the footnote so that it is set at a smaller +typeface. The footnote text is formatted in the diversion using that +environment, but it does not yet appear in the output. The document +author calls the footnote end macro, which returns to the previous +environment and ends the diversion. Later, after much more body text in +the document, a trap, set a small distance above the page bottom, is +sprung. The macro called by the trap draws a line across the page and +emits the stored diversion. Thus, the footnote is rendered. + + Diversions and traps make the text formatting process non-linear. +Let us imagine a set of text lines or paragraphs labelled 'A', 'B', and +so on. If we set up a trap that produces text 'T' (as a page footer, +say), and we also use a diversion to store the formatted text 'D', then +a document with input text in the order 'A B C D E F' might render as 'A +B C E T F'. The diversion 'D' will never be output if we do not call +for it. + + Environments of themselves are not a source of non-linearity in +document formatting: environment switches have immediate effect. One +could always write a macro to change as many formatting parameters as +desired with a single convenient call. But because diversions can be +nested and macros called by traps that are sprung by other trap-called +macros, they may be called upon in varying contexts. For example, +consider a page header that is always to be set in Helvetica. A +document that uses Times for most of its body text, but Courier for +displayed code examples, poses a challenge if a page break occurs in the +middle of a code display; if the header trap assumes that the "previous +font" is always Times, the rest of the example will be formatted in the +wrong typeface. One could carefully save all formatting parameters upon +entering the trap and restore them upon leaving it, but this is verbose, +error-prone, and not future-proof as the 'groff' language develops. +Environments save us considerable effort. + + +File: groff.info, Node: Traps, Next: Diversions, Prev: Deferring Output, Up: GNU troff Reference + +5.28 Traps +========== + +"Traps" are locations in the output or conditions on the input that, +when reached or fulfilled, call a specified macro. These traps can +occur at a given location on the page, at a given location in the +current diversion (together, these are known as vertical position +traps), at a blank line, at a line with leading space characters, after +a quantity of input lines, or at the end of input. Macros called by +traps are passed no arguments. Setting a trap is also called "planting" +one. It is said that a trap is "sprung" if its condition is fulfilled. + +* Menu: + +* Vertical Position Traps:: +* Diversion Traps:: +* Input Line Traps:: +* Blank Line Traps:: +* Leading Space Traps:: +* End-of-input Traps:: + + +File: groff.info, Node: Vertical Position Traps, Next: Page Location Traps, Prev: Traps, Up: Traps + +5.28.1 Vertical Position Traps +------------------------------ + +A "vertical position trap" calls a macro when the formatter's vertical +drawing position reaches or passes, in the downward direction, a certain +location on the output page or in a diversion. Its applications include +setting page headers and footers, body text in multiple columns, and +footnotes. + + -- Request: .vpt [flag] + -- Register: \n[.vpt] + Enable vertical position traps if FLAG is non-zero or absent; + disable them otherwise. Vertical position traps are those set by + the 'wh' request or by 'dt' within a diversion. The parameter that + controls whether vertical position traps are enabled is global. + Initially, vertical position traps are enabled. The current value + is stored in the '.vpt' read-only register. + + A page can't be ejected if 'vpt' is set to zero; see *note The + Implicit Page Trap::. + +* Menu: + +* Page Location Traps:: +* The Implicit Page Trap:: +* Diversion Traps:: + + +File: groff.info, Node: Page Location Traps, Next: The Implicit Page Trap, Prev: Vertical Position Traps, Up: Vertical Position Traps + +5.28.1.1 Page Location Traps +............................ + +A "page location trap" is a vertical position trap that applies to the +page; that is, to undiverted output. Many can be present; manage them +with the 'wh' and 'ch' requests. + + -- Request: .wh dist [name] + Plant macro NAME as page location trap at DIST. The default + scaling unit is 'v'. Non-negative values for DIST set the trap + relative to the top of the page; negative values set the trap + relative to the bottom of the page. It is not possible to plant a + trap less than one basic unit from the page bottom: a DIST of '-0' + is interpreted as '0', the top of the page.(1) (*note Page + Location Traps-Footnote-1::) An existing _visible_ trap (see below) + at DIST is removed; this is 'wh''s sole function if NAME is + missing. + + A trap is sprung only if it is "visible", meaning that its location + is reachable on the page(2) (*note Page Location + Traps-Footnote-2::) and it is not hidden by another trap at the + same location already planted there. + + A macro package might set headers and footers as follows; this + example configures vertical margins of one inch to the body text, + and one half-inch to the titles. Observe the use of the no-break + control character with 'sp' request to position our text baselines, + and the page number character '%' used with the 'tl' request. + + .\" hdfo.roff + .de hd \" page header + ' sp .5i + ' tl '\\*(Ti''\\*(Da' \" title and date strings + ' sp .5i + .. + .de fo \" page footer + ' sp .5i + . tl ''%'' + . bp + .. + .wh 0 hd \" trap at top of the page + .wh -1i fo \" trap 1 inch from bottom + + To use these traps, copy the above (or load it from a file with the + 'so' or 'mso' requests), then set up the strings it uses. + + .so hdfo.roff + .ds Ti Final Report\" + .ds Da 21 May 2023\" + .ti + On 5 August of last year, + this committee tasked me with the investigation of the + CFIT (controlled flight into terrain) incident of + .\" ...and so on... + + A trap above the top or at or below the bottom of the page can be + made visible by either moving it into the page area or increasing + the page length so that the trap is on the page. Negative trap + values always use the _current_ page length; they are not converted + to an absolute vertical position. We can use the 'ptr' request to + dump our page location traps to the standard error stream (*note + Debugging::). Their positions are reported in basic units; an + 'nroff' device example follows. + + .pl 5i + .wh -1i xx + .ptr + error-> xx -240 + .pl 100i + .ptr + error-> xx -240 + + It is possible to have more than one trap at the same location + (although only one at a time can be visible); to achieve this, the + traps must be defined at different locations, then moved to the + same place with the 'ch' request. In the following example, the + many empty lines caused by the 'bp' request are not shown in the + output. + + .de a + . nop a + .. + .de b + . nop b + .. + .de c + . nop c + .. + . + .wh 1i a + .wh 2i b + .wh 3i c + .bp + => a b c + .ch b 1i + .ch c 1i + .bp + => a + .ch a 0.5i + .bp + => a b + + -- Register: \n[.t] + The read-only register '.t' holds the distance to the next vertical + position trap. If there are no traps between the current position + and the bottom of the page, it contains the distance to the page + bottom. Within a diversion, in the absence of a diversion trap, + this distance is the largest representable integer in basic + units--effectively infinite. + + -- Request: .ch name [dist] + Change the location of a trap by moving macro NAME to new location + DIST, or by unplanting it altogether if DIST is absent. The + default scaling unit is 'v'. Parameters to 'ch' are specified in + the opposite order from 'wh'. If NAME is the earliest planted + macro of multiple traps at the same location, (re)moving it from + that location exposes the macro next least recently planted at the + same place.(3) (*note Page Location Traps-Footnote-3::) + + Changing a trap's location is useful for building up footnotes in a + diversion to allow more space at the bottom of the page for them. + + The same macro can be installed simultaneously at multiple locations; +however, only the earliest-planted instance--that has not yet been +deleted with 'wh'--will be moved by 'ch'. The following example (using +an 'nroff' device) illustrates this behavior. Blank lines have been +elided from the output. + + .de T + Trap sprung at \\n(nlu. + .br + .. + .wh 1i T + .wh 2i T + foo + .sp 11i + .bp + .ch T 4i + bar + .sp 11i + .bp + .ch T 5i + baz + .sp 11i + .bp + .wh 5i + .ch T 6i + qux + .sp 11i + => foo + => Trap sprung at 240u. + => Trap sprung at 480u. + => bar + => Trap sprung at 480u. + => Trap sprung at 960u. + => baz + => Trap sprung at 480u. + => Trap sprung at 1200u. + => qux + => Trap sprung at 1440u. + + -- Register: \n[.ne] + The read-only register '.ne' contains the amount of space that was + needed in the last 'ne' request that caused a trap to be sprung; it + is useful in conjunction with the '.trunc' register. *Note Page + Control::. Since the '.ne' register is set only by traps, it + doesn't make sense to interpolate it outside of macros called by + traps. + + -- Register: \n[.trunc] + A read-only register containing the amount of vertical space + truncated from an 'sp' request by the most recently sprung vertical + position trap, or, if the trap was sprung by an 'ne' request, minus + the amount of vertical motion produced by the 'ne' request. In + other words, at the point a trap is sprung, it represents the + difference of what the vertical position would have been but for + the trap, and what the vertical position actually is. Since the + '.trunc' register is set only by traps, it doesn't make sense to + interpolate it outside of macros called by traps. + + -- Register: \n[.pe] + This Boolean-valued, read-only register interpolates 1 while a page + is being ejected, and 0 otherwise. + + In the following example, we plant the same trap at the top and the + bottom of the page. We also make the trap report its name and the + vertical drawing position. + + .de T + .tm \\$0: page \\n%, nl=\\n[nl] .pe=\\n[.pe] + .. + .ll 46n + .wh 0 T + .wh -1v T + Those who can make you believe absurdities can make you + commit atrocities. \[em] Voltaire + error-> T: page 1, nl=0 .pe=0 + error-> T: page 1, nl=2600 .pe=1 + => Those who can make you believe absurdities can + => make you commit atrocities. -- Voltaire + + When designing macros, keep in mind that diversions and traps do +normally interact. For example, if a trap calls a header macro (while +outputting a diversion) that tries to change the font on the current +page, the effect is not visible before the diversion has completely been +printed (except for input protected with '\!' or '\?') since the data in +the diversion is already formatted. In most cases, this is not the +expected behaviour. + + +File: groff.info, Node: Page Location Traps-Footnotes, Up: Page Location Traps + + (1) *Note The Implicit Page Trap::. + + (2) A trap planted at '20i' or '-30i' will not be sprung on a page of +length '11i'. + + (3) It may help to think of each trap location as maintaining a +queue; 'wh' operates on the head of the queue, and 'ch' operates on its +tail. Only the trap at the head of the queue is visible. + + +File: groff.info, Node: The Implicit Page Trap, Next: Diversion Traps, Prev: Page Location Traps, Up: Vertical Position Traps + +5.28.1.2 The Implicit Page Trap +............................... + +If, after starting GNU 'troff' without loading a macro package, you use +the 'ptr' request to dump a list of the active traps to the standard +error stream,(1) (*note The Implicit Page Trap-Footnote-1::) nothing is +reported. Yet the '.t' register will report a steadily decreasing value +with every output line your document produces, and once the value of +'.t' gets to within '.V' of zero, you will notice that something +trap-like happens--the page is ejected, a new one begins, and the value +of '.t' becomes large once more. + + This "implicit page trap" always exists in the top-level +diversion;(2) (*note The Implicit Page Trap-Footnote-2::) it works like +a trap in some ways but not others. Its purpose is to eject the current +page and start the next one. It has no name, so it cannot be moved or +deleted with 'wh' or 'ch' requests. You cannot hide it by placing +another trap at its location, and can move it only by redefining the +page length with 'pl'. Its operation is suppressed when vertical page +traps are disabled with GNU 'troff''s 'vpt' request. + + +File: groff.info, Node: The Implicit Page Trap-Footnotes, Up: The Implicit Page Trap + + (1) *Note Debugging::. + + (2) *Note Diversions::. + + +File: groff.info, Node: Diversion Traps, Next: Input Line Traps, Prev: The Implicit Page Trap, Up: Vertical Position Traps + +5.28.1.3 Diversion Traps +........................ + +A diversion is not formatted in the context of a page, so it lacks page +location traps; instead it can have a "diversion trap". There can exist +at most one such vertical position trap per diversion. + + -- Request: .dt [dist name] + Set a trap _within_ a diversion at location DIST, which is + interpreted relative to diversion rather than page boundaries. If + invoked with fewer than two arguments, any diversion trap in the + current diversion is removed. The register '.t' works within + diversions. It is an error to invoke 'dt' in the top-level + diversion. *Note Diversions::. + + +File: groff.info, Node: Input Line Traps, Next: Blank Line Traps, Prev: Diversion Traps, Up: Traps + +5.28.2 Input Line Traps +----------------------- + + -- Request: .it [n name] + -- Request: .itc [n name] + Set an input line trap, calling macro NAME after processing the + next N productive input lines (recall *note Manipulating Filling + and Adjustment::). Any existing input line trap in the environment + is replaced. Without arguments, 'it' and 'itc' clear any input + line trap that has not yet sprung. + + Consider a macro '.ST S N' which sets the next N input lines in the + font style S. + + .de ST \" Use style $1 for next $2 text lines. + . it \\$2 ES + . ft \\$1 + .. + .de ES \" end ST + . ft R + .. + .ST I 1 + oblique + face + .ST I 1 + oblique\c + face + => oblique face obliqueface (second "face" upright) + + Unlike the 'ce' and 'rj' requests, 'it' counts lines interrupted + with the '\c' escape sequence separately (*note Line + Continuation::); 'itc' does not. To see the difference, let's + change the previous example to use 'itc' instead. + + ... + . itc \\$2 ES + ... + => oblique face obliqueface (second "face" oblique) + + You can think of the 'ce' and 'rj' requests as implicitly creating + an input line trap with 'itc' that schedules a break when the trap + is sprung. + + .de BR + . br + . internal: disable centering-without-filling + .. + . + .de ce + . if \\n[.br] .br + . itc \\$1 BR + . internal: enable centering-without-filling + .. + + Let us consider in more detail the sorts of input lines that are or + are not "productive". + + .de Trap + TRAP SPRUNG + .. + .de Mac + .if r a \l'5n' + .. + .it 2 Trap + . + foo + .Mac + bar + baz + .it 1 Trap + .sp \" moves, but does not write or draw + qux + .itc 1 Trap + \h'5n'\c \" moves, but does not write or draw + jat + + When 'Trap' gets called depends on whether the 'a' register is + defined; the control line with the 'if' request may or may not + produce written output. We also see that the spacing request 'sp', + while certainly affecting the output, does not spring the input + line trap. Similarly, the horizontal motion escape sequence '\h' + also affected the output, but was not "written". Observe that we + had to follow it with '\c' and use 'itc' to prevent the newline at + the end of the text line from causing a word break, which, like an + ordinary space character, counts as written output. + + $ groff -Tascii input-trap-example.groff + => foo bar TRAP SPRUNG baz + => + => qux TRAP SPRUNG jat TRAP SPRUNG + $ groff -Tascii -ra1 input-trap-example.groff + => foo _____ TRAP SPRUNG bar baz + => + => qux TRAP SPRUNG jat TRAP SPRUNG + + Input line traps are associated with the environment (*note +Environments::); switching to another environment suspends the current +input line trap, and going back resumes it, restoring the count of +qualifying lines enumerated in that environment. + + +File: groff.info, Node: Blank Line Traps, Next: Leading Space Traps, Prev: Input Line Traps, Up: Traps + +5.28.3 Blank Line Traps +----------------------- + + -- Request: .blm [name] + Set a blank line trap, calling the macro NAME when GNU 'troff' + encounters a blank line in an input file, instead of the usual + behavior (*note Breaking::). A line consisting only of spaces is + also treated as blank and subject to this trap. If no argument is + supplied, the default blank line behavior is (re-)established. + + +File: groff.info, Node: Leading Space Traps, Next: End-of-input Traps, Prev: Blank Line Traps, Up: Traps + +5.28.4 Leading Space Traps +-------------------------- + + -- Request: .lsm [name] + -- Register: \n[lsn] + -- Register: \n[lss] + Set a leading space trap, calling the macro NAME when GNU 'troff' + encounters leading spaces in an input line; the implicit line break + that normally happens in this case is suppressed. If no argument + is supplied, the default leading space behavior is (re-)established + (*note Breaking::). + + The count of leading spaces on an input line is stored in register + 'lsn', and the amount of corresponding horizontal motion in + register 'lss', irrespective of whether a leading space trap is + set. When it is, the leading spaces are removed from the input + line, and no motion is produced before calling NAME. + + +File: groff.info, Node: End-of-input Traps, Prev: Leading Space Traps, Up: Traps + +5.28.5 End-of-input Traps +------------------------- + + -- Request: .em [name] + Set a trap at the end of input, calling macro NAME after the last + line of the last input file has been processed. If no argument is + given, any existing end-of-input trap is removed. + + For example, if the document had to have a section at the bottom of + the last page for someone to approve it, the 'em' request could be + used. + + .de approval + \c + . ne 3v + . sp (\\n[.t]u - 3v) + . in +4i + . lc _ + . br + Approved:\t\a + . sp + Date:\t\t\a + .. + . + .em approval + + The '\c' in the above example needs explanation. For historical + reasons (compatibility with AT&T 'troff'), the end-of-input macro + exits as soon as it causes a page break if no partially collected + line remains.(1) (*note End-of-input Traps-Footnote-1::) + + Let us assume that there is no '\c' in the above 'approval' macro, + that the page is full, and last output line has been broken with, + say, a 'br' request. Because there is no more room, a 'ne' request + at this point causes a page ejection, which in turn makes 'troff' + exit immediately as just described. In most situations, this is + not desired; people generally want to format the input after 'ne'. + + To force processing of the whole end-of-input macro independently + of this behavior, it is thus advisable to (invisibly) ensure the + existence of a partially collected line ('\c') whenever there is a + chance that a page break can happen. In the above example, + invoking the 'ne' request ensures that there is room for the + subsequent formatted output on the same page, so we need insert + '\c' only once. + + The next example shows how to append three lines, then start a new + page unconditionally. Since '.ne 1' doesn't give the desired + effect--there is always one line available or we are already at the + beginning of the next page--we temporarily increase the page length + by one line so that we can use '.ne 2'. + + .de EM + .pl +1v + \c + .ne 2 + line one + .br + \c + .ne 2 + line two + .br + \c + .ne 2 + line three + .br + .pl -1v + \c + 'bp + .. + .em EM + + This specific feature affects only the first potential page break + caused by the end-of-input macro; further page breaks emitted by + the macro are handled normally. + + Another possible use of the 'em' request is to make GNU 'troff' + emit a single large page instead of multiple pages. For example, + one may want to produce a long plain text file for reading in a + terminal or emulator without page footers and headers interrupting + the body of the document. One approach is to set the page length + at the beginning of the document to a very large value to hold all + the text,(2) (*note End-of-input Traps-Footnote-2::) and + automatically adjust it to the exact height of the document after + the text has been output. + + .de adjust-page-length + . br + . pl \\n[nl]u \" \n[nl]: current vertical position + .. + . + .de single-page-mode + . pl 99999 + . em adjust-page-length + .. + . + .\" Activate the above code if configured. + .if \n[do-continuous-rendering] \ + . single-page-mode + + Since only one end-of-input trap exists and another macro package + may already use it, care must be taken not to break the mechanism. + A simple solution would be to append the above macro to the macro + package's end-of-input macro using the 'am' request. + + +File: groff.info, Node: End-of-input Traps-Footnotes, Up: End-of-input Traps + + (1) While processing an end-of-input macro, the formatter assumes +that the next page break must be the last; it goes into "sudden death +overtime". + + (2) Another, taken by the 'groff' 'man' macros, is to intercept 'ne' +requests and wrap 'bp' ones. + + +File: groff.info, Node: Diversions, Next: Punning Names, Prev: Traps, Up: GNU troff Reference + +5.29 Diversions +=============== + +In 'roff' systems it is possible to format text as if for output, but +instead of writing it immediately, one can "divert" the formatted text +into a named storage area. It is retrieved later by specifying its name +after a control character. The same name space is used for such +diversions as for strings and macros; see *note Identifiers::. Such +text is sometimes said to be "stored in a macro", but this coinage +obscures the important distinction between macros and strings on one +hand and diversions on the other; the former store _unformatted_ input +text, and the latter capture _formatted_ output. Diversions also do not +interpret arguments. Applications of diversions include "keeps" +(preventing a page break from occurring at an inconvenient place by +forcing a set of output lines to be set as a group), footnotes, tables +of contents, and indices. For orthogonality it is said that GNU 'troff' +is in the "top-level diversion" if no diversion is active (that is, +formatted output is being "diverted" immediately to the output device). + + Dereferencing an undefined diversion will create an empty one of that +name and cause a warning in category 'mac' to be emitted. *Note +Warnings::, for information about the enablement and suppression of +warnings. A diversion does not exist for the purpose of testing with +the 'd' conditional operator until its initial definition ends (*note +Operators in Conditionals::). The following requests are used to create +and alter diversions. + + -- Request: .di [name] + -- Request: .da [name] + Start collecting formatted output in a diversion called NAME. The + 'da' request appends to a diversion called NAME, creating it if + necessary. If NAME already exists as an alias, the target of the + alias is replaced or appended to; recall *note Strings::. The + pending output line is diverted as well. Switching to another + environment (with the 'ev' request) before invoking 'di' or 'da' + avoids including any pending output line in the diversion; see + *note Environments::. + + Invoking 'di' or 'da' without an argument stops diverting output to + the diversion named by the most recent corresponding request. If + 'di' or 'da' is called without an argument when there is no current + diversion, a warning in category 'di' is produced. *Note + Warnings::, for information about the enablement and suppression of + warnings. + + Before the diversion. + .di yyy + In the diversion. + .br + .di + After the diversion. + .br + => After the diversion. + .yyy + => Before the diversion. In the diversion. + + GNU 'troff' supports "box" requests to exclude a partially collected +line from a diversion, as this is often desirable. + + -- Request: .box [name] + -- Request: .boxa [name] + Divert (or append) output to NAME, similarly to the 'di' and 'da' + requests, respectively. Any pending output line is _not_ included + in the diversion. Without an argument, stop diverting output; any + pending output line inside the diversion is discarded. + + Before the box. + .box xxx + In the box. + .br + Hidden treasure. + .box + After the box. + .br + => Before the box. After the box. + .xxx + => In the box. + + Apart from pending output line inclusion and the request names that +populate them, boxes are handled exactly as diversions are. All of the +following 'groff' language elements can be used with them +interchangeably. + + -- Register: \n[.z] + -- Register: \n[.d] + Diversions may be nested. The read-only string-valued register + '.z' contains the name of the current diversion. The read-only + register '.d' contains the current vertical place in the diversion. + If the input text is not being diverted, '.d' reports the same + location as the register 'nl'. + + -- Register: \n[.h] + The read-only register '.h' stores the "high-water mark" on the + current page or in the current diversion. It corresponds to the + text baseline of the lowest line on the page.(1) (*note + Diversions-Footnote-1::) + + .tm .h==\n[.h], nl==\n[nl] + => .h==0, nl==-1 + This is a test. + .br + .sp 2 + .tm .h==\n[.h], nl==\n[nl] + => .h==40, nl==120 + + As implied by the example, vertical motion does not produce text + baselines and thus does not increase the value interpolated by + '\n[.h]'. + + -- Register: \n[dn] + -- Register: \n[dl] + After completing a diversion, the writable registers 'dn' and 'dl' + contain its vertical and horizontal sizes. Only the lines just + processed are counted: for the computation of 'dn' and 'dl', the + requests 'da' and 'boxa' are handled as if 'di' and 'box' had been + used, respectively--lines that have been already stored in the + diversion (box) are not taken into account. + + .\" Center text both horizontally and vertically. + .\" Macro .(c starts centering mode; .)c terminates it. + . + .\" Disable the escape character with .eo so that we + .\" don't have to double backslashes on the "\n"s. + .eo + .de (c + . br + . ev (c + . evc 0 + . in 0 + . nf + . di @c + .. + .de )c + . br + . ev + . di + . nr @s (((\n[.t]u - \n[dn]u) / 2u) - 1v) + . sp \n[@s]u + . ce 1000 + . @c + . ce 0 + . sp \n[@s]u + . br + . fi + . rr @s + . rm @c + .. + .ec + + -- Escape sequence: \!anything + -- Escape sequence: \?anything\? + "Transparently" embed ANYTHING into the current diversion, + preventing requests, macro calls, and escape sequences from being + interpreted when read into a diversion. This is useful for + preventing them from taking effect until the diverted text is + actually output. The '\!' escape sequence transparently embeds + input up to and including the end of the line. The '\?' escape + sequence transparently embeds input until its own next occurrence. + + ANYTHING may not contain newlines; use '\!' by itself to embed + newlines in a diversion. The escape sequence '\?' is also + recognized in copy mode and turned into a single internal code; it + is this code that terminates ANYTHING. Thus the following example + prints 4. + + .nr x 1 + .nf + .di d + \?\\?\\\\?\\\\\\\\nx\\\\?\\?\? + .di + .nr x 2 + .di e + .d + .di + .nr x 3 + .di f + .e + .di + .nr x 4 + .f + + Both escape sequences read the data in copy mode. + + If '\!' is used in the top-level diversion, its argument is + directly embedded into GNU 'troff''s intermediate output. This can + be used, for example, to control a postprocessor that processes the + data before it is sent to an output driver. + + The '\?' escape used in the top-level diversion produces no output + at all; its argument is simply ignored. + + -- Request: .output contents + Emit CONTENTS directly to GNU 'troff''s intermediate output + (subject to copy mode interpretation); this is similar to '\!' used + at the top level. An initial neutral double quote in CONTENTS is + stripped to allow embedding of leading spaces. + + This request can't be used before the first page has started--if + you get an error, simply insert '.br' before the 'output' request. + + Use with caution! It is normally only needed for mark-up used by a + postprocessor that does something with the output before sending it + to the output device, filtering out CONTENTS again. + + -- Request: .asciify div + "Unformat" the diversion DIV in a way such that Unicode basic Latin + (ASCII) characters, characters translated with the 'trin' request, + space characters, and some escape sequences, that were formatted + and diverted into DIV are treated like ordinary input characters + when DIV is reread. Doing so can be useful in conjunction with the + 'writem' request. 'asciify' can be also used for gross hacks; for + example, the following sets register 'n' to 1. + + .tr @. + .di x + @nr n 1 + .br + .di + .tr @@ + .asciify x + .x + + 'asciify' cannot return all items in a diversion to their source + equivalent: nodes such as those produced by the '\N' escape + sequence will remain nodes, so the result cannot be guaranteed to + be a pure string. *Note Copy Mode::. Glyph parameters such as the + type face and size are not preserved; use 'unformat' to achieve + that. + + -- Request: .unformat div + Like 'asciify', unformat the diversion DIV. However, 'unformat' + handles only tabs and spaces between words, the latter usually + arising from spaces or newlines in the input. Tabs are treated as + input tokens, and spaces become adjustable again. The vertical + sizes of lines are not preserved, but glyph information (font, type + size, space width, and so on) is retained. + + +File: groff.info, Node: Diversions-Footnotes, Up: Diversions + + (1) Thus, the "water" gets "higher" proceeding _down_ the page. + + +File: groff.info, Node: Punning Names, Next: Environments, Prev: Diversions, Up: GNU troff Reference + +5.30 Punning Names +================== + +Macros, strings, and diversions share a name space; recall *note +Identifiers::. Internally, the same mechanism is used to store them. +You can thus call a macro with string interpolation syntax and vice +versa. + + .de subject + Typesetting + .. + .de predicate + rewards attention to detail + .. + \*[subject] \*[predicate]. + Truly. + => Typesetting + => rewards attention to detail Truly. + +What went wrong? Strings don't contain newlines, but macros do. String +interpolation placed a newline at the end of '\*[subject]', and the next +thing on the input was a space. Then when '\*[predicate]' was +interpolated, it was followed by the empty request '.' on a line by +itself. If we want to use macros as strings, we must take interpolation +behavior into account. + + .de subject + Typesetting\\ + .. + .de predicate + rewards attention to detail\\ + .. + \*[subject] \*[predicate]. + Truly. + => Typesetting rewards attention to detail. Truly. + +By ending each text line of the macros with an escaped '\', we get +the desired effect (*note Line Continuation::).(1) (*note Punning +Names-Footnote-1::) What would have happened if we had used only one +backslash at a time instead? + + Interpolating a string does not hide existing macro arguments. We +can also place the escaped newline outside the string interpolation +instead of within the string definition. Thus, in a macro, a more +efficient way of doing + + .xx \\$@ + +is + + \\*[xx]\\ + +The latter calling syntax doesn't change the value of '\$0', which is +then inherited from the calling macro (*note Parameters::). + + Diversions can be also called with string syntax. It is sometimes +convenient to copy one-line diversions to a string. + + .di xx + the + .ft I + interpolation system + .ft + .br + .di + .ds yy This is a test of \*(xx\c + \*(yy. + => This is a test of the interpolation system. + +As the previous example shows, it is possible to store formatted output +in strings. The '\c' escape sequence prevents the subsequent newline +from being interpreted as a break (again, *note Line Continuation::). + + Copying multi-output line diversions produces unexpected results. + + .di xxx + a funny + .br + test + .br + .di + .ds yyy This is \*[xxx]\c + \*[yyy]. + => test This is a funny. + + Usually, it is not predictable whether a diversion contains one or +more output lines, so this mechanism should be avoided. With AT&T +'troff', this was the only solution to strip off a final newline from a +diversion. Another disadvantage is that the spaces in the copied string +are already formatted, preventing their adjustment. This can cause ugly +results. + + A clean solution to this problem is available in GNU 'troff', using +the requests 'chop' to remove the final newline of a diversion, and +'unformat' to make the horizontal spaces adjustable again. + + .box xxx + a funny + .br + test + .br + .box + .chop xxx + .unformat xxx + This is \*[xxx]. + => This is a funny test. + + *Note Gtroff Internals::. + + +File: groff.info, Node: Punning Names-Footnotes, Up: Punning Names + + (1) The backslash is doubled. *Note Copy Mode::. + + +File: groff.info, Node: Environments, Next: Suppressing Output, Prev: Diversions, Up: GNU troff Reference + +5.31 Environments +================= + +As discussed in *note Deferring Output::, environments store most of the +parameters that determine the appearance of text. A default environment +named '0' exists when GNU 'troff' starts up; it is modified by +formatting-related requests and escape sequences. + + You can create new environments and switch among them. Only one is +current at any given time. Active environments are managed using a +"stack", a data structure supporting "push" and "pop" operations. The +current environment is at the top of the stack. The same environment +name can be pushed onto the stack multiple times, possibly interleaved +with others. Popping the environment stack does not destroy the current +environment; it remains accessible by name and can be made current again +by pushing it at any time. Environments cannot be renamed or deleted, +and can only be modified when current. To inspect the environment +stack, use the 'pev' request; see *note Debugging::. + + Environments store the following information. + + * a partially collected line, if any + + * data about the most recently output glyph and line (registers + '.cdp', '.cht', '.csk', '.n', '.w') + + * typeface parameters (size, family, style, height and slant, + inter-word and inter-sentence space sizes) + + * page parameters (line length, title length, vertical spacing, line + spacing, indentation, line numbering, centering, right-alignment, + underlining, hyphenation parameters) + + * filling enablement; adjustment enablement and mode + + * tab stops; tab, leader, escape, control, no-break control, + hyphenation, and margin characters + + * input line traps + + * stroke and fill colors + + -- Request: .ev [ident] + -- Register: \n[.ev] + Enter the environment IDENT, which is created if it does not + already exist, using the same parameters as for the default + environment used at startup. With no argument, GNU 'troff' + switches to the previous environment. + + Invoking 'ev' with an argument puts environment IDENT onto the top + of the environment stack. (If it isn't already present in the + stack, this is a proper push.) Without an argument, 'ev' pops the + environment stack, making the previous environment current. It is + an error to pop the environment stack with no previous environment + available. The read-only string-valued register '.ev' contains the + name of the current environment--the one at the top of the stack. + + .ev footnote-env + .fam N + .ps 6 + .vs 8 + .ll -.5i + .ev + + ... + + .ev footnote-env + \[dg] Observe the smaller text and vertical spacing. + .ev + + We can familiarize ourselves with stack behavior by wrapping the + 'ev' request with a macro that reports the contents of the '.ev' + register to the standard error stream. + + .de EV + . ev \\$1 + . tm environment is now \\n[.ev] + .. + . + .EV foo + .EV bar + .EV + .EV baz + .EV + .EV + .EV + + error-> environment is now foo + error-> environment is now bar + error-> environment is now foo + error-> environment is now baz + error-> environment is now foo + error-> environment is now 0 + error-> error: environment stack underflow + error-> environment is now 0 + + -- Request: .evc environment + Copy the contents of ENVIRONMENT to the current environment. + + The following environment data are not copied. + + * a partially collected line, if present; + + * the interruption status of the previous input line (due to use + of the '\c' escape sequence); + + * the count of remaining lines to center, to right-justify, or + to underline (with or without underlined spaces)--these are + set to zero; + + * the activation status of temporary indentation; + + * input line traps and their associated data; + + * the activation status of line numbering (which can be + reactivated with '.nm +0'); and + + * the count of consecutive hyphenated lines (set to zero). + + -- Register: \n[.w] + -- Register: \n[.cht] + -- Register: \n[.cdp] + -- Register: \n[.csk] + The '\n[.w]' register contains the width of the last glyph + formatted in the environment. + + The '\n[.cht]' register contains the height of the last glyph + formatted in the environment. + + The '\n[.cdp]' register contains the depth of the last glyph + formatted in the environment. It is positive for glyphs extending + below the baseline. + + The '\n[.csk]' register contains the "skew" (how far to the right + of the glyph's center that GNU 'troff' should place an accent) of + the last glyph formatted in the environment. + + -- Register: \n[.n] + The '\n[.n]' register contains the length of the previous output + line emitted in the environment. + + +File: groff.info, Node: Suppressing Output, Next: Colors, Prev: Environments, Up: GNU troff Reference + +5.32 Suppressing Output +======================= + + -- Escape sequence: \O[num] + Suppress GNU 'troff' output of glyphs and geometric objects. The + sequences '\O2', '\O3', '\O4', and '\O5' are intended for internal + use by 'grohtml'. + + '\O0' + Disable the emission of glyphs and geometric objects to the + output driver, provided that this sequence occurs at the + outermost suppression level (see '\O3' and '\04' below). + Horizontal motions corresponding to non-overstruck glyph + widths still occur. + + '\O1' + Enable the emission of glyphs and geometric objects to the + output driver, provided that this sequence occurs at the + outermost suppression level. + + '\O0' and '\O1' also reset the four registers 'opminx', 'opminy', + 'opmaxx', and 'opmaxy' to -1. These four registers mark the top + left and bottom right hand corners of a box encompassing all + written or drawn output. + + '\O2' + At the outermost suppression level, enable emission of glyphs + and geometric objects, and write to the standard error stream + the page number and values of the four aforementioned + registers encompassing glyphs written since the last + interpolation of a '\O' sequence, as well as the page offset, + line length, image file name (if any), horizontal and vertical + device motion quanta, and input file name. Numeric values are + in basic units. + + '\O3' + Begin a nested suppression level. 'grohtml' uses this + mechanism to create images of output preprocessed with 'gpic', + 'geqn', and 'gtbl'. At startup, GNU 'troff' is at the + outermost suppression level. 'pre-grohtml' generates these + sequences when processing the document, using GNU 'troff' with + the 'ps' output device, Ghostscript, and the PNM tools to + produce images in PNG format. They start a new page if the + device is not 'html' or 'xhtml', to reduce the number of + images crossing a page boundary. + + '\O4' + End a nested suppression level. + + '\O[5PFILE]' + At the outermost suppression level, write the name 'file' to + the standard error stream at position P, which must be one of + 'l', 'r', 'c', or 'i', corresponding to left, right, centered, + and inline alignments within the document, respectively. FILE + is a name associated with the production of the next image. + + -- Register: \n[.O] + Output suppression nesting level applied by '\O3' and '\O4' escape + sequences. + + +File: groff.info, Node: I/O, Next: Postprocessor Access, Prev: Suppressing Output, Up: GNU troff Reference + +5.33 I/O +======== + +'gtroff' has several requests for including files: + + -- Request: .so file + -- Request: .soquiet file + Replace the 'so' request's control line with the contents of the + file named by the argument, "sourcing" it. FILE is sought in the + directories specified by '-I' command-line option. If FILE does + not exist, a warning in category 'file' is produced and the request + has no further effect. *Note Warnings::, for information about the + enablement and suppression of warnings. + + 'so' can be useful for large documents; e.g., allowing each chapter + of a book to be kept in a separate file. However, files + interpolated with 'so' are not preprocessed; to overcome this + limitation, see the 'gsoelim(1)' man page. + + Since GNU 'troff' replaces the entire control line with the + contents of a file, it matters whether 'file' is terminated with a + newline or not. Assume that file 'xxx' contains only the word + 'foo' without a trailing newline. + + $ printf 'foo' > xxx + + The situation is + .so xxx + bar. + => The situation is foobar. + + 'soquiet' works the same way, except that no warning diagnostic is + issued if FILE does not exist. + + -- Request: .pso command + Read the standard output from the specified COMMAND and include it + in place of the 'pso' request. + + It is an error to use this request in safer mode, which is the + default. Invoke GNU 'troff' or a front end with the '-U' option to + enable unsafe mode. + + The comment regarding a final newline for the 'so' request is valid + for 'pso' also. + + -- Request: .mso file + -- Request: .msoquiet file + Identical to the 'so' and 'soquiet' requests, respectively, except + that 'gtroff' searches for the specified FILE in the same + directories as macro files for the '-m' command-line option. If + the file name to be included has the form 'NAME.tmac' and it isn't + found, these requests try to include 'tmac.NAME' and vice versa. + + -- Request: .trf file + -- Request: .cf file + Transparently output the contents of FILE. Each line is output as + if it were preceded by '\!'; however, the lines are _not_ subject + to copy mode interpretation. If the file does not end with a + newline, 'trf' adds one. Both requests cause a break. + + When used in a diversion, these requests embed a node (*note Gtroff + Internals::) in it that, when reread, causes the contents of FILE + to be transparently copied to the output. In AT&T 'troff', the + contents of FILE are immediately copied to the output regardless of + whether there is a current diversion; this behaviour is so + anomalous that it must be considered a bug. + + While 'cf' copies the contents of FILE completely unprocessed, + 'trf' disallows characters such as NUL that are not valid 'gtroff' + input characters (*note Identifiers::). + + For 'cf', within a diversion, "completely unprocessed" means that + each line of a file to be inserted is handled as if it were + preceded by '\!\\!'. + + To define a macro 'x' containing the contents of file 'f', use + + .ev 1 + .di x + .trf f + .di + .ev + + The calls to 'ev' prevent the partially collected output line from + becoming part of the diversion (*note Diversions::). + + -- Request: .nx [file] + Force 'gtroff' to continue processing of the file specified as an + argument. If no argument is given, immediately jump to the end of + file. + + -- Request: .rd [prompt [arg1 arg2 ...]] + Read from standard input, and include what is read as though it + were part of the input file. Text is read until a blank line is + encountered. + + If standard input is a TTY input device (keyboard), write PROMPT to + standard error, followed by a colon (or send BEL for a beep if no + argument is given). + + Arguments after PROMPT are available for the input. For example, + the line + + .rd data foo bar + + with the input 'This is \$2.' prints + + This is bar. + + Using the 'nx' and 'rd' requests, it is easy to set up form letters. +The form letter template is constructed like this, putting the following +lines into a file called 'repeat.let': + + .ce + \*(td + .sp 2 + .nf + .rd + .sp + .rd + .fi + Body of letter. + .bp + .nx repeat.let + +When this is run, a file containing the following lines should be +redirected in. Requests included in this file are executed as though +they were part of the form letter. The last block of input is the 'ex' +request, which tells GNU 'troff' to stop processing. If this were not +there, 'troff' would not know when to stop. + + Trent A. Fisher + 708 NW 19th Av., #202 + Portland, OR 97209 + + Dear Trent, + + Len Adollar + 4315 Sierra Vista + San Diego, CA 92103 + + Dear Mr. Adollar, + + .ex + + -- Request: .pi pipe + Pipe the output of 'gtroff' to the shell command(s) specified by + PIPE. This request must occur before 'gtroff' has a chance to + print anything. + + It is an error to use this request in safer mode, which is the + default. Invoke GNU 'troff' or a front end with the '-U' option to + enable unsafe mode. + + Multiple calls to 'pi' are allowed, acting as a chain. For + example, + + .pi foo + .pi bar + ... + + is the same as '.pi foo | bar'. + + The intermediate output format of GNU 'troff' is piped to the + specified commands. Consequently, calling 'groff' without the '-Z' + option normally causes a fatal error. + + -- Request: .sy cmds + -- Register: \n[systat] + Execute the shell command(s) specified by CMDS. The output is not + saved anywhere, so it is up to the user to do so. + + It is an error to use this request in safer mode; this is the + default. Give GNU 'troff' or a front end program the '-U' option + to enable unsafe mode. + + The following code fragment introduces the current time into a + document. + + .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ + (localtime(time))[2,1,0]' > /tmp/x\n[$$] + .so /tmp/x\n[$$] + .sy rm /tmp/x\n[$$] + \nH:\nM:\nS + + This works by having the Perl script (run by 'sy') write 'nr' + requests that set the registers 'H', 'M', and 'S' to a temporary + file. The 'roff' document then reads the temporary file using the + 'so' request. + + The registers 'seconds', 'minutes', and 'hours', initialized at + startup of GNU 'troff', should satisfy most requirements. Use the + 'af' request to format their values for output. + + .af hours 00 + .af minutes 00 + .af seconds 00 + \n[hours]:\n[minutes]:\n[seconds] + => 02:17:54 + + The writable register 'systat' contains the return value of the + 'system()' function executed by the last 'sy' request. + + -- Request: .open stream file + -- Request: .opena stream file + Open the specified FILE for writing and associates the specified + STREAM with it. + + The 'opena' request is like 'open', but if the file exists, append + to it instead of truncating it. + + It is an error to use these requests in safer mode; this is the + default. Give GNU 'troff' or a front end program the '-U' option + to enable unsafe mode. + + -- Request: .write stream data + -- Request: .writec stream data + Write to the file associated with the specified STREAM. The stream + must previously have been the subject of an open request. The + remainder of the line is interpreted as the 'ds' request reads its + second argument: an initial neutral double quote in CONTENTS is + stripped to allow embedding of leading spaces, and it is read in + copy mode. + + The 'writec' request is like 'write', but only 'write' appends a + newline to the data. + + -- Request: .writem stream xx + Write the contents of the macro or string XX to the file associated + with the specified STREAM. + + XX is read in copy mode, i.e., already formatted elements are + ignored. Consequently, diversions must be unformatted with the + 'asciify' request before calling 'writem'. Usually, this means a + loss of information. + + -- Request: .close stream + Close the specified STREAM; the stream is no longer an acceptable + argument to the 'write' request. + + Here a simple macro to write an index entry. + + .open idx test.idx + . + .de IX + . write idx \\n[%] \\$* + .. + . + .IX test entry + . + .close idx + + -- Escape sequence: \Ve + -- Escape sequence: \V(ev + -- Escape sequence: \V[env] + Interpolate the contents of the specified environment variable ENV + (one-character name E, two-character name EV) as returned by the + function 'getenv(3)'. '\V' is interpreted even in copy mode (*note + Copy Mode::). + + +File: groff.info, Node: Postprocessor Access, Next: Miscellaneous, Prev: I/O, Up: GNU troff Reference + +5.34 Postprocessor Access +========================= + +Two escape sequences and two requests enable documents to pass +information directly to a postprocessor. These are useful for +exercising device-specific capabilities that the 'groff' language does +not abstract or generalize; examples include the embedding of hyperlinks +and image files. Device-specific functions are documented in each +output driver's man page, such as 'gropdf(1)', 'grops(1)', or +'grotty(1)'. + + -- Request: .device xxx ... + -- Escape sequence: \X'xxx ...' + Embed all XXX arguments into GNU 'troff' output as parameters to a + device control command 'x X'. The meaning and interpretation of + such parameters is determined by the output driver or other + postprocessor. + + The 'device' request processes its arguments in copy mode (*note + Copy Mode::). An initial neutral double quote in CONTENTS is + stripped to allow embedding of leading spaces. By contrast, within + '\X' arguments, the escape sequences '\&', '\)', '\%', and '\:' are + ignored; '\' and '\~' are converted to single space characters; + and '\\' has its escape character stripped. So that the basic + Latin subset of the Unicode character set(1) (*note Postprocessor + Access-Footnote-1::) can be reliably encoded in device control + commands, seven special character escape sequences ('\-', '\[aq]', + '\[dq]', '\[ga]', '\[ha]', '\[rs]', and '\[ti]',) are mapped to + basic Latin characters; see the 'groff_char(7)' man page. For this + transformation, character translations and special character + definitions are ignored.(2) (*note Postprocessor + Access-Footnote-2::) The use of any other escape sequence in '\X' + parameters is normally an error. + + If the 'use_charnames_in_special' directive appears in the output + device's 'DESC' file, the use of special character escape sequences + is _not_ an error; they are simply output verbatim (with the + exception of the seven mapped to Unicode basic Latin characters, + discussed above). 'use_charnames_in_special' is currently employed + only by 'grohtml'. + + -- Request: .devicem name + -- Escape sequence: \Yn + -- Escape sequence: \Y(nm + -- Escape sequence: \Y[name] + This is approximately equivalent to '\X'\*[NAME]'' (one-character + name N, two-character name NM). However, the contents of the + string or macro NAME are not interpreted; also it is permitted for + NAME to have been defined as a macro and thus contain newlines (it + is not permitted for the argument to '\X' to contain newlines). + The inclusion of newlines requires an extension to the AT&T 'troff' + output format, and confuses drivers that do not know about this + extension (*note Device Control Commands::). + + -- Request: .tag name + -- Request: .taga name + Reserved for internal use. + + +File: groff.info, Node: Postprocessor Access-Footnotes, Up: Postprocessor Access + + (1) that is, ISO 646:1991-IRV or, popularly, "US-ASCII" + + (2) They are bypassed because these parameters are not rendered as +glyphs in the output; instead, they remain abstract characters--in a PDF +bookmark or a URL, for example. + + +File: groff.info, Node: Miscellaneous, Next: Gtroff Internals, Prev: Postprocessor Access, Up: GNU troff Reference + +5.35 Miscellaneous +================== + +We document here GNU 'troff' features that fit poorly elsewhere. + + -- Request: .nm [start [increment [space [indentation]]]] + -- Register: \n[ln] + -- Register: \n[.nm] + Begin (or, with no arguments, cease) numbering output lines. START + assigns the number of the _next_ output line. Only line numbers + divisible by INCREMENT are marked (default: '1'). SPACE configures + the horizontal spacing between the number and the text (default: + '1'). Any given INDENTATION is applied to the numbers (default: + '0'). The third and fourth arguments are reckoned in numeral + widths ('\0'). START must be non-negative and INCREMENT positive. + + The formatter aligns the number to the right in a width of three + numeral spaces plus INDENTATION, then catenates SPACE and the + output line. The line length is _not_ reduced. Depending on the + value of the page offset,(1) (*note Miscellaneous-Footnote-1::) + numbers wider than the allocated space protrude into the left + margin, or shift the output line to the right. + + Line numbering parameters corresponding to missing arguments are + not altered. After numbering is disabled, '.nm +0' resumes it + using the previously active parameters. + + The parameters of 'nm' are associated with the environment (*note + Environments::). + + While numbering is enabled, the output line number register 'ln' is + updated as each line is output, even if no line number is formatted + with it because it is being skipped (it is not a multiple of + INCREMENT) or because numbering is suppressed (see the 'nn' request + below). + + The '.nm' register tracks the enablement status of numbering. + Temporary suspension of numbering with the 'nn' request does _not_ + alter its value. + + .po 5n + .ll 44n + Programming, + when stripped of all its circumstantial irrelevancies, + .nm 999 1 1 -4 + boils down to no more and no less than + .nm +0 3 + very effective thinking so as to avoid unmastered + .nn 2 + complexity, + to very vigorous separation of your many + different concerns. + .br + \(em Edsger Dijkstra + .sp + .nm 1 1 1 + This guy's arrogance takes your breath away. + .br + \(em John Backus + => Programming, when stripped of all its cir- + => 999 cumstantial irrelevancies, boils down to no + => more and no less than very effective think- + => ing so as to avoid unmastered complexity, to + => very vigorous separation of your many dif- + => ferent concerns. + => 1002 -- Edsger Dijkstra + => + => 1 This guy's arrogance takes your breath away. + => 2 -- John Backus + + -- Request: .nn [skip] + -- Register: \n[.nn] + Suppress numbering of the next SKIP output lines that would + otherwise be numbered. The default is 1. 'nn' can be invoked when + line numbering is not active; suppression of numbering will take + effect for SKIP lines once 'nm' enables it. + + The '.nn' register stores the count of output lines still to have + their numbering suppressed. + + This count is associated with the environment (*note + Environments::). + + To test whether the current output line will be numbered, you must +check both the '.nm' and '.nn' registers. + + .de is-numbered + . nop This line + . ie (\\n[.nm] & (1-\\n[.nn])) IS + . el ISN'T + . nop numbered. + . br + .. + Test line numbering. + .is-numbered + .nm 1 + .nn 1 + .is-numbered + .is-numbered + .nm + .is-numbered + => Test line numbering. This line ISN'T numbered. + => This line ISN'T numbered. + => 1 This line IS numbered. + => This line ISN'T numbered. + + -- Request: .mc [margin-character [distance] + Begin (or, with no arguments, cease) writing a "margin-character" + to the right of each output line. The DISTANCE argument separates + MARGIN-CHARACTER from the right margin. If absent, the most recent + value is used; the default is 10 points. If an output line exceeds + the line length, the margin character is appended to it. No margin + character is written on lines produced by the 'tl' request. + + The margin character is a property of the output line; the margin + character last configured when the line is output controls. If the + margin character is disabled before an output line breaks, none is + output (but see below). + + The margin character is associated with the environment (*note + Environments::). + + .ll 5i + .nf + .mc \[br] + This paragraph is marked with a margin character. + .sp + As seen above, vertical space isn't thus marked. + \& + An output line that is present, but empty, is. + => This paragraph is marked with a margin character. | + => + => As seen above, vertical space isn't thus marked. | + => | + => An output line that is present, but empty, is. | + + For compatibility with AT&T 'troff', a call to 'mc' to set the margin +character can't be undone immediately; at least one line gets a margin +character. + + .ll 10n + .nf + .mc | + .mc * + .mc + foo + bar + => foo * + => bar + + The margin character mechanism is commonly used to annotate changes +in documents. The 'groff' distribution ships a program, 'gdiffmk', to +assist with this task.(2) (*note Miscellaneous-Footnote-2::) + + -- Request: .psbb file + -- Register: \n[llx] + -- Register: \n[lly] + -- Register: \n[urx] + -- Register: \n[ury] + Retrieve the bounding box of the PostScript image found in FILE, + which must conform to Adobe's "Document Structuring Conventions" + (DSC), locate a '%%BoundingBox' comment, and store the (upper-, + lower-, -left, -right) values into the registers 'llx', 'lly', + 'urx', and 'ury'. If an error occurs (for example, if no + '%%BoundingBox' comment is present), the formatter sets these + registers to 0. + + The search path for FILE can be controlled with the '-I' + command-line option. + + +File: groff.info, Node: Miscellaneous-Footnotes, Up: Miscellaneous + + (1) Recall *note Line Layout::. + + (2) Historically, tools named 'nrchbar' and 'changebar' were +developed for marking changes with margin characters and could be found +in archives of the 'comp.sources.unix' USENET group. Some proprietary +Unices also offer(ed) a 'diffmk' program. + + +File: groff.info, Node: Gtroff Internals, Next: Debugging, Prev: Miscellaneous, Up: GNU troff Reference + +5.36 'gtroff' Internals +======================= + +'gtroff' processes input in three steps. One or more input characters +are converted to an "input token".(1) (*note Gtroff +Internals-Footnote-1::) Then, one or more input tokens are converted to +an "output node". Finally, output nodes are converted to the +intermediate output language understood by all output devices. + + Actually, before step one happens, 'gtroff' converts certain escape +sequences into reserved input characters (not accessible by the user); +such reserved characters are used for other internal processing also - +this is the very reason why not all characters are valid input. *Note +Identifiers::, for more on this topic. + + For example, the input string 'fi\[:u]' is converted into a character +token 'f', a character token 'i', and a special token ':u' (representing +u umlaut). Later on, the character tokens 'f' and 'i' are merged to a +single output node representing the ligature glyph 'fi' (provided the +current font has a glyph for this ligature); the same happens with ':u'. +All output glyph nodes are 'processed', which means that they are +invariably associated with a given font, font size, advance width, etc. +During the formatting process, 'gtroff' itself adds various nodes to +control the data flow. + + Macros, diversions, and strings collect elements in two chained +lists: a list of input tokens that have been passed unprocessed, and a +list of output nodes. Consider the following diversion. + + .di xxx + a + \!b + c + .br + .di + +It contains these elements. + +node list token list element number + +line start node -- 1 +glyph node 'a' -- 2 +word space node -- 3 +-- 'b' 4 +-- '\n' 5 +glyph node 'c' -- 6 +vertical size node -- 7 +vertical size node -- 8 +-- '\n' 9 + +Elements 1, 7, and 8 are inserted by 'gtroff'; the latter two (which are +always present) specify the vertical extent of the last line, possibly +modified by '\x'. The 'br' request finishes the pending output line, +inserting a newline input token, which is subsequently converted to a +space when the diversion is reread. Note that the word space node has a +fixed width that isn't adjustable anymore. To convert horizontal space +nodes back to input tokens, use the 'unformat' request. + + Macros only contain elements in the token list (and the node list is +empty); diversions and strings can contain elements in both lists. + + The 'chop' request simply reduces the number of elements in a macro, +string, or diversion by one. Exceptions are "compatibility save" and +"compatibility ignore" input tokens, which are ignored. The 'substring' +request also ignores those input tokens. + + Some requests like 'tr' or 'cflags' work on glyph identifiers only; +this means that the associated glyph can be changed without destroying +this association. This can be very helpful for substituting glyphs. In +the following example, we assume that glyph 'foo' isn't available by +default, so we provide a substitution using the 'fchar' request and map +it to input character 'x'. + + .fchar \[foo] foo + .tr x \[foo] + +Now let us assume that we install an additional special font 'bar' that +has glyph 'foo'. + + .special bar + .rchar \[foo] + +Since glyphs defined with 'fchar' are searched before glyphs in special +fonts, we must call 'rchar' to remove the definition of the fallback +glyph. Anyway, the translation is still active; 'x' now maps to the +real glyph 'foo'. + + Macro and request arguments preserve compatibility mode enablement. + + .cp 1 \" switch to compatibility mode + .de xx + \\$1 + .. + .cp 0 \" switch compatibility mode off + .xx caf\['e] + => café + +Since compatibility mode is enabled while 'de' is invoked, the macro +'xx' enables compatibility mode when it is called. Argument '$1' can +still be handled properly because it inherits the compatibility mode +enablement status that was active at the point where 'xx' was called. + + After interpolation of the parameters, the compatibility save and +restore tokens are removed. + + +File: groff.info, Node: Gtroff Internals-Footnotes, Up: Gtroff Internals + + (1) Except the escape sequences '\f', '\F', '\H', '\m', '\M', '\R', +'\s', and '\S', which are processed immediately if not in copy mode. + + +File: groff.info, Node: Debugging, Next: Implementation Differences, Prev: Gtroff Internals, Up: GNU troff Reference + +5.37 Debugging +============== + + Standard troff voodoo, just put a power of two backslashes in + front of it until it works and if you still have problems add a \c. + -- Ron Natalie + + GNU 'troff' is not the easiest language to debug, in part thanks to +its design features of recursive interpolation and the use of +multi-stage pipeline processing in the surrounding system. Nevertheless +there exist several features useful for troubleshooting. + + Preprocessors use the 'lf' request to preserve the identity of the +line numbers and names of input files. GNU 'troff' emits a variety of +error diagnostics and supports several categories of warning; the output +of these can be selectively suppressed. A trace of the formatter's +input processing stack can be emitted when errors or warnings occur by +means of GNU 'troff''s '-b' option, or produced on demand with the +'backtrace' request. The 'tm' and related requests can be used to emit +customized diagnostic messages or for instrumentation while +troubleshooting. The 'ex' and 'ab' requests cause early termination +with successful and error exit codes respectively, to halt further +processing when continuing would be fruitless. Examine the state of the +formatter with requests that write lists of defined names (macros, +strings, and diversions), environments, registers, and page location +traps to the standard error stream. + + -- Request: .lf line [file] + Set the input line number (and, optionally, the file name) GNU + 'troff' shall use for error and warning messages. LINE is the + input line number of the _next_ line. Without an argument, the + request is ignored. + + 'lf''s primary purpose is to aid the debugging of documents that + undergo preprocessing. Programs like 'tbl' that transform input in + their own languages into 'roff' requests use it so that any + diagnostic messages emitted by 'troff' correspond to the source + document. + + -- Request: .tm message + -- Request: .tm1 message + -- Request: .tmc message + Send MESSAGE, which consumes the remainder of the input line and + cannot contain special characters, to the standard error stream, + followed by a newline. Leading spaces in MESSAGE are ignored. + + 'tm1' is similar, but recognizes and strips a leading neutral + double quote from MESSAGE to allow the embedding of leading spaces. + + 'tmc' works as 'tm1', but does not append a newline. + + -- Request: .ab [message] + Write any MESSAGE to the standard error stream (like 'tm') and then + abort GNU 'troff'; that is, stop processing and terminate with a + failure status. + + -- Request: .ex + Exit GNU 'troff'; that is, stop processing and terminate with a + successful status. To stop processing only the current file, use + the 'nx' request; see *note I/O::. + + When doing something involved, it is useful to leave the debugging +statements in the code and have them turned on by a command-line flag. + + .if \n[DB] .tm debugging output + +To activate such statements, use the '-r' option to set the register. + + groff -rDB=1 file + + If it is known in advance that there are many errors and no useful +output, GNU 'troff' can be forced to suppress formatted output with the +'-z' option. + + -- Request: .pev + Report the state of the current environment followed by that of all + other environments to the standard error stream. + + -- Request: .pm + Report, to the standard error stream, the names of all defined + macros, strings, and diversions with their sizes in bytes. + + -- Request: .pnr + Report the names and contents of all currently defined registers to + the standard error stream. + + -- Request: .ptr + Report the names and positions of all page location traps to the + standard error stream. Empty slots in the list, where a trap has + been planted but subsequently (re)moved, are printed as well. + + -- Request: .fl + Instruct 'gtroff' to flush its output immediately. The intent is + for interactive use, but this behaviour is currently not + implemented in 'gtroff'. Contrary to Unix 'troff', TTY output is + sent to a device driver also ('grotty'), making it non-trivial to + communicate interactively. + + This request causes a line break. + + -- Request: .backtrace + Write the state of the input stack to the standard error stream. + + Consider the following in a file 'test'. + + .de xxx + . backtrace + .. + .de yyy + . xxx + .. + . + .yyy + error-> troff: backtrace: 'test':2: macro 'xxx' + error-> troff: backtrace: 'test':5: macro 'yyy' + error-> troff: backtrace: file 'test':8 + + The '-b' option of GNU 'troff' causes a backtrace to be generated + on each error or warning. Some warnings have to be enabled; *Note + Warnings::. + + -- Register: \n[slimit] + If greater than 0, sets the maximum quantity of objects on GNU + 'troff''s internal input stack. If less than or equal to 0, there + is no limit: recursion can continue until program memory is + exhausted. The default is 1,000. + + -- Request: .warnscale su + Set the scaling unit used in certain warnings to SU, which can take + the values 'u', 'i', 'c', 'p', and 'P'. The default is 'i'. + + -- Request: .spreadwarn [limit] + Emit a 'break' warning if the additional space inserted for each + space between words in an output line adjusted to both margins with + '.ad b' is larger than or equal to LIMIT. A negative value is + treated as zero; an absent argument toggles the warning on and off + without changing LIMIT. The default scaling unit is 'm'. At + startup, 'spreadwarn' is inactive and LIMIT is 3m. + + For example, + + .spreadwarn 0.2m + + causes a warning if 'break' warnings are not suppressed and + 'gtroff' must add 0.2m or more for each inter-word space in a line. + *Note Warnings::. + + GNU 'troff' has command-line options for reporting warnings ('-w') +and backtraces ('-b') when a warning or an error occurs. + + -- Request: .warn [n] + -- Register: \n[.warn] + Select the categories, or "types", of reported warnings. N is the + sum of the numeric codes associated with each warning category that + is to be enabled; all other categories are disabled. The + categories and their associated codes are listed in *note + Warnings::. For example, '.warn 0' disables all warnings, and + '.warn 1' disables all warnings except those about missing glyphs. + If no argument is given, all warning categories are enabled. + + The read-only register '.warn' contains the sum of the numeric + codes of enabled warning categories. + +* Menu: + +* Warnings:: + + +File: groff.info, Node: Warnings, Prev: Debugging, Up: Debugging + +5.37.1 Warnings +--------------- + +Warning diagnostics emitted by GNU 'troff' are divided into named, +numbered categories. The name associated with each warning category is +used by the '-w' and '-W' options. Each category is also assigned a +power of two; the sum of enabled category values is used by the 'warn' +request and the '.warn' register. + + Warnings of each category are produced under the following +circumstances. + +'char' +'1' + No mounted font defines a glyph for the requested character. This + category is enabled by default. + +'number' +'2' + An invalid numeric expression was encountered. This category is + enabled by default. *Note Numeric Expressions::. + +'break' +'4' + A filled output line could not be broken such that its length was + less than the output line length '\n[.l]'. This category is + enabled by default. + +'delim' +'8' + The closing delimiter in an escape sequence was missing or + mismatched. + +'el' +'16' + The 'el' request was encountered with no prior corresponding 'ie' + request. *Note if-else::. + +'scale' +'32' + A scaling unit inappropriate to its context was used in a numeric + expression. + +'range' +'64' + A numeric expression was out of range for its context. + +'syntax' +'128' + A self-contradictory hyphenation mode was requested; an empty or + incomplete numeric expression was encountered; an operand to a + numeric operator was missing; an attempt was made to define a + recursive, empty, or nonsensical character class; or a 'groff' + extension conditional expression operator was used while in + compatibility mode. + +'di' +'256' + A 'di', 'da', 'box', or 'boxa' request was invoked without an + argument when there was no current diversion. + +'mac' +'512' + An undefined string, macro, or diversion was used. When such an + object is dereferenced, an empty one of that name is automatically + created. So, unless it is later deleted, at most one warning is + given for each. + + This warning is also emitted upon an attempt to move an unplanted + trap macro (*note Page Location Traps::). In such cases, the + unplanted macro is _not_ dereferenced, so it is not created if it + does not exist. + +'reg' +'1024' + An undefined register was used. When an undefined register is + dereferenced, it is automatically defined with a value of 0. So, + unless it is later deleted, at most one warning is given for each. + +'tab' +'2048' + A tab character was encountered where a number was expected, or + appeared in an unquoted macro argument. + +'right-brace' +'4096' + A right brace escape sequence '\}' was encountered where a number + was expected. + +'missing' +'8192' + A request was invoked with a mandatory argument absent. + +'input' +'16384' + An invalid character occurred on the input stream. + +'escape' +'32768' + An unsupported escape sequence was encountered. + +'space' +'65536' + A space was missing between a request or macro and its argument. + This warning is produced when an undefined name longer than two + characters is encountered and the first two characters of the name + constitute a defined name. No request is invoked, no macro called, + and an empty macro is not defined. This category is enabled by + default. It never occurs in compatibility mode. + +'font' +'131072' + A non-existent font was selected, or the selection was ignored + because a font selection escape sequence was used after the output + line continuation escape sequence on an input line. This category + is enabled by default. + +'ig' +'262144' + An invalid escape sequence occurred in input ignored using the 'ig' + request. This warning category diagnoses a condition that is an + error when it occurs in non-ignored input. + +'color' +'524288' + An undefined color was selected, an attempt was made to define a + color using an unrecognized color space, an invalid component in a + color definition was encountered, or an attempt was made to + redefine a default color. + +'file' +'1048576' + An attempt was made to load a file that does not exist. This + category is enabled by default. + + Two warning names group other warning categories for convenience. + +'all' + All warning categories except 'di', 'mac' and 'reg'. This + shorthand is intended to produce all warnings that are useful with + macro packages written for AT&T 'troff' and its descendants, which + have less fastidious diagnostics than GNU 'troff'. + +'w' + All warning categories. Authors of documents and macro packages + targeting 'groff' are encouraged to use this setting. + + +File: groff.info, Node: Implementation Differences, Next: Safer Mode, Prev: Debugging, Up: GNU troff Reference + +5.38 Implementation Differences +=============================== + +GNU 'troff' has a number of features that cause incompatibilities with +documents written for other versions of 'troff'. Some GNU extensions to +'troff' have become supported by other implementations. + +* Menu: + +* Safer Mode:: +* Compatibility Mode:: +* Other Differences:: + + +File: groff.info, Node: Safer Mode, Next: Compatibility Mode, Prev: Implementation Differences, Up: Implementation Differences + +5.38.1 Safer Mode +----------------- + +The formatter operates in "safer" mode by default; to mitigate risks +from untrusted input documents, the 'pi' and 'sy' requests are disabled. +GNU 'troff''s '-U' option enables "unsafe mode", restoring their +function and enabling additional 'groff' extension requests, 'open', +'opena', and 'pso'. *Note I/O::. + + +File: groff.info, Node: Compatibility Mode, Next: Safer Mode, Prev: Other Differences, Up: Implementation Differences + +5.38.2 Compatibility Mode +------------------------- + +Long identifier names may be GNU 'troff''s most obvious innovation. +AT&T 'troff' interprets '.dsabcd' as defining a string 'ab' with +contents 'cd'. Normally, GNU 'troff' interprets this as a call of a +macro named 'dsabcd'. AT&T 'troff' also interprets '\*[' and '\n[' as +an interpolation of a string or register, respectively, named '['. In +GNU 'troff', however, the '[' is normally interpreted as delimiting a +long name. In compatibility mode, GNU 'troff' interprets names in the +traditional way; they thus can be two characters long at most. + + -- Request: .cp [n] + -- Register: \n[.C] + If N is missing or non-zero, turn on compatibility mode; otherwise, + turn it off. + + The read-only register '.C' is 1 if compatibility mode is on, + 0 otherwise. + + Compatibility mode can be also turned on with the '-C' command-line + option. + + -- Request: .do name + -- Register: \n[.cp] + The 'do' request interprets the string, request, diversion, or + macro NAME (along with any further arguments) with compatibility + mode disabled. Compatibility mode is restored (only if it was + active) when the _expansion_ of NAME is interpreted; that is, the + restored compatibility state applies to the contents of the macro, + string, or diversion NAME as well as data read from files or pipes + if NAME is any of the 'so', 'soquiet', 'mso', 'msoquiet', or 'pso' + requests. + + The following example illustrates several aspects of 'do' behavior. + + .de mac1 + FOO + .. + .de1 mac2 + groff + .mac1 + .. + .de mac3 + compatibility + .mac1 + .. + .de ma + \\$1 + .. + .cp 1 + .do mac1 + .do mac2 \" mac2, defined with .de1, calls "mac1" + .do mac3 \" mac3 calls "ma" with argument "c1" + .do mac3 \[ti] \" groff syntax accepted in .do arguments + => FOO groff FOO compatibility c1 ~ + + The read-only register '.cp', meaningful only when dereferenced + from a 'do' request, is 1 if compatibility mode was on when the + 'do' request was encountered, and 0 if it was not. This register + is specialized and may require a statement of rationale. + + When writing macro packages or documents that use GNU 'troff' + features and which may be mixed with other packages or documents + that do not--common scenarios include serial processing of man + pages or use of the 'so' or 'mso' requests--you may desire correct + operation regardless of compatibility mode enablement in the + surrounding context. It may occur to you to save the existing + value of '\n(.C' into a register, say, '_C', at the beginning of + your file, turn compatibility mode off with '.cp 0', then restore + it from that register at the end with '.cp \n(_C'. At the same + time, a modular design of a document or macro package may lead you + to multiple layers of inclusion. You cannot use the same register + name everywhere lest you "clobber" the value from a preceding or + enclosing context. The two-character register name space of AT&T + 'troff' is confining and mnemonically challenging; you may wish to + use the more capacious name space of GNU 'troff'. However, + attempting '.nr _my_saved_C \n(.C' will not work in compatibility + mode; the register name is too long. "This is exactly what 'do' is + for," you think, '.do nr _my_saved_C \n(.C'. The foregoing will + always save zero to your register, because 'do' turns compatibility + mode _off_ while it interprets its argument list. + + To robustly save compatibility mode before switching it off, use + + .do nr _my_saved_C \n[.cp] + .cp 0 + + at the beginning of your file, followed by + + .cp \n[_my_saved_C] + .do rr _my_saved_C + + at the end. As in the C language, we all have to share one big + name space, so choose a register name that is unlikely to collide + with other uses. + + Normally, GNU 'troff' preserves the interpolation depth in delimited +arguments, but not in compatibility mode. + + .ds xx ' + \w'abc\*(xxdef' + => 168 (normal mode on a terminal device) + => 72def' (compatibility mode on a terminal device) + + Furthermore, the escape sequences '\f', '\H', '\m', '\M', '\R', '\s', +and '\S' are transparent for the purpose of recognizing a control +character at the beginning of a line only in compatibility mode. For +example, this code produces bold output in both cases, but the text +differs. + + .de xx + Hello! + .. + \fB.xx\fP + => .xx (normal mode) + => Hello! (compatibility mode) + + Normally, the syntax form '\s'N accepts only a single character (a +digit) for N, consistently with other forms that originated in AT&T +'troff', like '\*', '\$', '\f', '\g', '\k', '\n', and '\z'. In +compatibility mode only, a non-zero N must be in the range 4-39. Legacy +documents relying upon this quirk of parsing(1) (*note Compatibility +Mode-Footnote-1::) should be migrated to another '\s' form. + + +File: groff.info, Node: Compatibility Mode-Footnotes, Up: Compatibility Mode + + (1) The Graphic Systems C/A/T phototypesetter (the original device +target for AT&T 'troff') supported only a few discrete type sizes in the +range 6-36 points, so Ossanna contrived a special case in the parser to +do what the user must have meant. Kernighan warned of this in the 1992 +revision of CSTR #54 (§2.3), and more recently, McIlroy referred to it +as a "living fossil". + + +File: groff.info, Node: Other Differences, Prev: Compatibility Mode, Up: Implementation Differences + +5.38.3 Other Differences +------------------------ + +'groff' request names unrecognized by other 'troff' implementations will +likely be ignored by them; escape sequences that are 'groff' extensions +are liable to be interpreted as if the escape character were not +present. For example, the adjustable, non-breaking escape sequence '\~' +is also supported by Heirloom Doctools 'troff' 050915 (September 2005), +'mandoc' 1.9.5 (2009-09-21), 'neatroff' (commit 1c6ab0f6e, 2016-09-13), +and Plan 9 from User Space 'troff' (commit 93f8143600, 2022-08-12), but +not by Solaris or Documenter's Workbench 'troff's. *Note Manipulating +Filling and Adjustment::. + + GNU 'troff' does not allow the use of the escape sequences '\|', +'\^', '\&', '\{', '\}', '\', '\'', '\`', '\-', '\_', '\!', '\%', and +'\c' in identifiers; AT&T 'troff' does. The '\A' escape sequence (*note +Identifiers::) may be helpful in avoiding use of these escape sequences +in names. + + When adjusting to both margins, AT&T 'troff' at first adjusts spaces +starting from the right; GNU 'troff' begins from the left. Both +implementations adjust spaces from opposite ends on alternating output +lines in this adjustment mode to prevent "rivers" in the text. + + GNU 'troff' does not always hyphenate words as AT&T 'troff' does. +The AT&T implementation uses a set of hard-coded rules specific to +English, while GNU 'troff' uses language-specific hyphenation pattern +files derived from TeX. Furthermore, in old versions of 'troff' there +was a limited amount of space to store hyphenation exceptions (arguments +to the 'hw' request); GNU 'troff' has no such restriction. + + GNU 'troff' predefines a string '.T' containing the argument given to +the '-T' command-line option, namely the current output device (for +example, 'pdf' or 'utf8'). The existence of this string is a common +feature of post-CSTR #54 'troff's(1) (*note Other +Differences-Footnote-1::) but valid values are specific to each +implementation. + + AT&T 'troff' ignored attempts to remove read-only registers; GNU +'troff' honors such requests. *Note Built-in Registers::. + + The (read-only) register '.T' interpolates 1 if GNU 'troff' is called +with the '-T' command-line option, and 0 otherwise. This behavior +differs from AT&T 'troff', which interpolated 1 only if 'nroff' was the +formatter and was called with '-T'. + + AT&T 'troff' and other implementations handle the 'lf' request +differently. For them, its LINE argument changes the line number of the +_current_ line. + + AT&T 'troff' had only environments named '0', '1', and '2'. In GNU +'troff', any number of environments may exist, using any valid +identifiers for their names (*note Identifiers::.) + + Fractional type sizes cause one noteworthy incompatibility. In AT&T +'troff' the 'ps' request ignores scaling units and thus '.ps 10u' sets +the type size to 10 points, whereas in GNU 'troff' it sets the type size +to 10 _scaled_ points. *Note Using Fractional Type Sizes::. + + The 'ab' request differs from AT&T 'troff': GNU 'troff' writes no +message to the standard error stream if no arguments are given, and it +exits with a failure status instead of a successful one. + + The 'bp' request differs from AT&T 'troff': GNU 'troff' does not +accept a scaling unit on the argument, a page number; the former +(somewhat uselessly) does. + + The 'pm' request differs from AT&T 'troff': GNU 'troff' reports the +sizes of macros, strings, and diversions in bytes and ignores an +argument to report only the sum of the sizes. + + Unlike AT&T 'troff', GNU 'troff' does not ignore the 'ss' request if +the output is a terminal device; instead, the values of minimal +inter-word and additional inter-sentence space are each rounded down to +the nearest multiple of 12. + + In GNU 'troff' there is a fundamental difference between +(unformatted) characters and (formatted) glyphs. Everything that +affects how a glyph is output is stored with the glyph node; once a +glyph node has been constructed, it is unaffected by any subsequent +requests that are executed, including 'bd', 'cs', 'tkf', 'tr', or 'fp' +requests. Normally, glyphs are constructed from characters immediately +before the glyph is added to an output line. Macros, diversions, and +strings are all, in fact, the same type of object; they contain a +sequence of intermixed character and glyph nodes. Special characters +transform from one to the other: before being added to the output, they +behave as characters; afterward, they are glyphs. A glyph node does not +behave like a character node when it is processed by a macro: it does +not inherit any of the special properties that the character from which +it was constructed might have had. For example, the input + + .di x + \\\\ + .br + .di + .x + +produces '\\' in GNU 'troff'. Each pair of backslashes becomes one +backslash _glyph_; the resulting backslashes are thus not interpreted as +escape _characters_ when they are reread as the diversion is output. +AT&T 'troff' _would_ interpret them as escape characters when rereading +them and end up printing one '\'. + + One correct way to obtain a printable backslash in most documents is +to use the '\e' escape sequence; this always prints a single instance of +the current escape character,(2) (*note Other Differences-Footnote-2::) +regardless of whether or not it is used in a diversion; it also works in +both GNU 'troff' and AT&T 'troff'. + + The other correct way, appropriate in contexts independent of the +backslash's common use as a 'troff' escape character--perhaps in +discussion of character sets or other programming languages--is the +character escape '\(rs' or '\[rs]', for "reverse solidus", from its name +in the ECMA-6 (ISO/IEC 646) standard.(3) (*note Other +Differences-Footnote-3::) + + To store an escape sequence in a diversion that is interpreted when +the diversion is reread, either use the traditional '\!' transparent +output facility, or, if this is unsuitable, the new '\?' escape +sequence. *Note Diversions:: and *note Gtroff Internals::. + + In the somewhat pathological case where a diversion exists containing +a partially collected line and a partially collected line at the +top-level diversion has never existed, AT&T 'troff' will output the +partially collected line at the end of input; GNU 'troff' will not. + + +File: groff.info, Node: Other Differences-Footnotes, Up: Other Differences + + (1) DWB 3.3, Solaris, Heirloom Doctools, and Plan 9 'troff' all +support it. + + (2) Naturally, if you've changed the escape character, you need to +prefix the 'e' with whatever it is--and you'll likely get something +other than a backslash in the output. + + (3) The 'rs' special character identifier was not defined in AT&T +'troff''s font description files, but is in those of its lineal +descendant, Heirloom Doctools 'troff', as of the latter's 060716 release +(July 2006). + + +File: groff.info, Node: File Formats, Next: Copying This Manual, Prev: GNU troff Reference, Up: Top + +6 File Formats +************** + +All files read and written by 'gtroff' are text files. The following +two sections describe their format. + +* Menu: + +* gtroff Output:: +* Device and Font Description Files:: + + +File: groff.info, Node: gtroff Output, Next: Device and Font Description Files, Prev: File Formats, Up: File Formats + +6.1 'gtroff' Output +=================== + +This section describes the 'groff' intermediate output format produced +by GNU 'troff'. + + As 'groff' is a wrapper program around GNU 'troff' and automatically +calls an output driver (or "postprocessor"), this output does not show +up normally. This is why it is called _intermediate_. 'groff' provides +the option '-Z' to inhibit postprocessing such that the produced +intermediate output is sent to standard output just as it is when +calling GNU 'troff' directly. + + Here, the term "troff output" describes what is output by GNU +'troff', while "intermediate output" refers to the language that is +accepted by the parser that prepares this output for the output drivers. +This parser handles whitespace more flexibly than AT&T's implementation +and implements obsolete elements for compatibility; otherwise, both +formats are the same.(1) (*note gtroff Output-Footnote-1::) + + The main purpose of the intermediate output concept is to facilitate +the development of postprocessors by providing a common programming +interface for all devices. It has a language of its own that is +completely different from the 'gtroff' language. While the 'gtroff' +language is a high-level programming language for text processing, the +intermediate output language is a kind of low-level assembler language +by specifying all positions on the page for writing and drawing. + + The intermediate output produced by 'gtroff' is fairly readable, +while output from AT&T 'troff' is rather hard to understand because of +strange habits that are still supported, but not used any longer by +'gtroff'. + +* Menu: + +* Language Concepts:: +* Command Reference:: +* Intermediate Output Examples:: +* Output Language Compatibility:: + + +File: groff.info, Node: gtroff Output-Footnotes, Up: gtroff Output + + (1) The parser and postprocessor for intermediate output can be found +in the file +'GROFF-SOURCE-DIR/src/libs/libdriver/input.cpp'. + + +File: groff.info, Node: Language Concepts, Next: Command Reference, Prev: gtroff Output, Up: gtroff Output + +6.1.1 Language Concepts +----------------------- + +The fundamental operation of the GNU 'troff' formatter is the +translation of the 'groff' input language into a device-independent form +primarily concerned with what has to be written or drawn at specific +positions on the output device. This language is simple and imperative. +In the following discussion, the term "command" always refers to this +intermediate output language, and never to the 'groff' language intended +for direct use by document authors. Intermediate output commands +comprise several categories: glyph output; font, color, and text size +selection; motion of the printing position; page advancement; drawing of +geometric objects; and device control commands, a catch-all for +operations not easily classified as any of the foregoing, such as +directives to start and stop output, identify the intended output +device, or place URL hyperlinks in supported output formats. + +* Menu: + +* Separation:: +* Argument Units:: +* Document Parts:: + + +File: groff.info, Node: Separation, Next: Argument Units, Prev: Language Concepts, Up: Language Concepts + +6.1.1.1 Separation +.................. + +AT&T 'troff' output has strange requirements regarding whitespace. The +'gtroff' output parser, however, is more tolerant, making whitespace +maximally optional. Such characters, i.e., the tab, space, and newline, +always have a syntactical meaning. They are never printable because +spacing within the output is always done by positioning commands. + + Any sequence of space or tab characters is treated as a single +"syntactical space". It separates commands and arguments, but is only +required when there would occur a clashing between the command code and +the arguments without the space. Most often, this happens when +variable-length command names, arguments, argument lists, or command +clusters meet. Commands and arguments with a known, fixed length need +not be separated by syntactical space. + + A line break is a syntactical element, too. Every command argument +can be followed by whitespace, a comment, or a newline character. Thus +a "syntactical line break" is defined to consist of optional syntactical +space that is optionally followed by a comment, and a newline character. + + The normal commands, those for positioning and text, consist of a +single letter taking a fixed number of arguments. For historical +reasons, the parser allows stacking of such commands on the same line, +but fortunately, in 'gtroff''s intermediate output, every command with +at least one argument is followed by a line break, thus providing +excellent readability. + + The other commands--those for drawing and device controlling--have a +more complicated structure; some recognize long command names, and some +take a variable number of arguments. So all 'D' and 'x' commands were +designed to request a syntactical line break after their last argument. +Only one command, 'x X', has an argument that can span several input +lines; all other commands must have all of their arguments on the same +line as the command, i.e., the arguments may not be split by a line +break. + + Empty lines (these are lines containing only space and/or a comment), +can occur everywhere. They are just ignored. + + +File: groff.info, Node: Argument Units, Next: Document Parts, Prev: Separation, Up: Language Concepts + +6.1.1.2 Argument Units +...................... + +Some commands take integer arguments that are assumed to represent +values in a measurement unit, but the letter for the corresponding +scaling unit is not written with the output command arguments. Most +commands assume the scaling unit 'u', the basic unit of the device, some +use 'z', the scaled point unit of the device, while others, such as the +color commands, expect plain integers. + + Single characters can have the eighth bit set, as can the names of +fonts and special characters. The names of characters and fonts can be +of arbitrary length. A character that is to be printed is always in the +current font. + + A string argument is always terminated by the next whitespace +character (space, tab, or newline); an embedded '#' character is +regarded as part of the argument, not as the beginning of a comment +command. An integer argument is already terminated by the next +non-digit character, which then is regarded as the first character of +the next argument or command. + + +File: groff.info, Node: Document Parts, Prev: Argument Units, Up: Language Concepts + +6.1.1.3 Document Parts +...................... + +A correct intermediate output document consists of two parts, the +"prologue" and the "body". + + The task of the prologue is to set the general device parameters +using three exactly specified commands. 'gtroff''s prologue is +guaranteed to consist of the following three lines (in that order): + + x T DEVICE + x res N H V + x init + +with the arguments set as outlined in *note Device Control Commands::. +The parser for the intermediate output format is able to interpret +additional whitespace and comments as well even in the prologue. + + The body is the main section for processing the document data. +Syntactically, it is a sequence of any commands different from the ones +used in the prologue. Processing is terminated as soon as the first +'x stop' command is encountered; the last line of any 'gtroff' +intermediate output always contains such a command. + + Semantically, the body is page oriented. A new page is started by a +'p' command. Positioning, writing, and drawing commands are always done +within the current page, so they cannot occur before the first 'p' +command. Absolute positioning (by the 'H' and 'V' commands) is done +relative to the current page; all other positioning is done relative to +the current location within this page. + + +File: groff.info, Node: Command Reference, Next: Intermediate Output Examples, Prev: Language Concepts, Up: gtroff Output + +6.1.2 Command Reference +----------------------- + +This section describes all intermediate output commands, both from AT&T +'troff' as well as the 'gtroff' extensions. + +* Menu: + +* Comment Command:: +* Simple Commands:: +* Graphics Commands:: +* Device Control Commands:: +* Obsolete Command:: + + +File: groff.info, Node: Comment Command, Next: Simple Commands, Prev: Command Reference, Up: Command Reference + +6.1.2.1 Comment Command +....................... + +'#ANYTHING' + A comment. Ignore any characters from the '#' character up to the + next newline character. + + This command is the only possibility for commenting in the + intermediate output. Each comment can be preceded by arbitrary + syntactical space; every command can be terminated by a comment. + + +File: groff.info, Node: Simple Commands, Next: Graphics Commands, Prev: Comment Command, Up: Command Reference + +6.1.2.2 Simple Commands +....................... + +The commands in this subsection have a command code consisting of a +single character, taking a fixed number of arguments. Most of them are +commands for positioning and text writing. These commands are tolerant +of whitespace. Optionally, syntactical space can be inserted before, +after, and between the command letter and its arguments. All of these +commands are stackable; i.e., they can be preceded by other simple +commands or followed by arbitrary other commands on the same line. A +separating syntactical space is necessary only when two integer +arguments would clash or if the preceding argument ends with a string +argument. + +'C ID' + Typeset the glyph of the special character ID. Trailing + syntactical space is necessary to allow special character names of + arbitrary length. The drawing position is not advanced. + +'c G' + Typeset the glyph of the ordinary character C. The drawing + position is not advanced. + +'f N' + Select the font mounted at position N. N cannot be negative. + +'H N' + Horizontally move the drawing position to N basic units from the + left edge of the page. N cannot be negative. + +'h N' + Move the drawing position right N basic units. AT&T 'troff' + allowed negative N; GNU 'troff' does not produce such values, but + 'groff''s output driver library handles them. + +'m COLOR-SCHEME [COMPONENT ...]' + Select the stroke color using the COMPONENTs in the color space + SCHEME. Each COMPONENT is an integer between 0 and 65535. The + quantity of components and their meanings vary with each SCHEME. + This command is a 'groff' extension. + + 'mc CYAN MAGENTA YELLOW' + Use the CMY color scheme with components cyan, magenta, and + yellow. + + 'md' + Use the default color (no components; black in most cases). + + 'mg GRAY' + Use a grayscale color scheme with a component ranging between + 0 (black) and 65535 (white). + + 'mk CYAN MAGENTA YELLOW BLACK' + Use the CMYK color scheme with components cyan, magenta, + yellow, and black. + + 'mr RED GREEN BLUE' + Use the RGB color scheme with components red, green, and blue. + +'N N' + Typeset the glyph with index N in the current font. N is normally + a non-negative integer. The drawing position is not advanced. The + 'html' and 'xhtml' devices use this command with negative N to + produce unbreakable space; the absolute value of N is taken and + interpreted in basic units. + +'n B A' + Indicate a break. No action is performed; the command is present + to make the output more easily parsed. The integers B and A + describe the vertical space amounts before and after the break, + respectively. GNU 'troff' issues this command but 'groff''s output + driver library ignores it. See 'v' and 'V' below. + +'p N' + Begin a new page, setting its number to N. Each page is + independent, even from those using the same number. The vertical + drawing position is set to 0. All positioning, writing, and + drawing commands are interpreted in the context of a page, so a + 'p' command must precede them. + +'s N' + Set type size to N scaled points (unit 'z' in GNU 'troff'. AT&T + 'troff' used unscaled points 'p' instead; see *note Output Language + Compatibility::. + +'t XYZ' +'t XYZ DUMMY-ARG' + Typeset a word XYZ; that is, set a sequence of ordinary glyphs + named X, Y, Z, ..., terminated by a space character or a line + break; an optional second integer argument is ignored (this allows + the formatter to generate an even number of arguments). Each glyph + is set at the current drawing position, and the position is then + advanced horizontally by the glyph's width. A glyph's width is + read from its metrics in the font description file, scaled to the + current type size, and rounded to a multiple of the horizontal + motion quantum. Use the 'C' command to emplace glyphs of special + characters. The 't' command is a 'groff' extension and is output + only for devices whose 'DESC' file contains the 'tcommand' + directive; see *note DESC File Format::. + +'u N XYZ' + Typeset word XYZ with track kerning. As 't', but after placing + each glyph, the drawing position is further advanced horizontally + by N basic units ('u'). The 'u' command is a 'groff' extension and + is output only for devices whose 'DESC' file contains the + 'tcommand' directive; see *note DESC File Format::. + +'V N' + Vertically move the drawing position to N basic units from the top + edge of the page. N cannot be negative. + +'v N' + Move the drawing position down N basic units. AT&T 'troff' allowed + negative N; GNU 'troff' does not produce such values, but 'groff''s + output driver library handles them. + +'w' + Indicate an inter-word space. No action is performed; the command + is present to make the output more easily parsed. Only adjustable, + breakable inter-word spaces are thus described; those resulting + from '\~' or horizontal motion escape sequences are not. GNU + 'troff' issues this command but 'groff''s output driver library + ignores it. See 'h' and 'H' above. + + +File: groff.info, Node: Graphics Commands, Next: Device Control Commands, Prev: Simple Commands, Up: Command Reference + +6.1.2.3 Graphics Commands +......................... + +Each graphics or drawing command in the intermediate output starts with +the letter 'D', followed by one or two characters that specify a +subcommand; this is followed by a fixed or variable number of integer +arguments that are separated by a single space character. A 'D' command +may not be followed by another command on the same line (apart from a +comment), so each 'D' command is terminated by a syntactical line break. + + 'gtroff' output follows the classical spacing rules (no space between +command and subcommand, all arguments are preceded by a single space +character), but the parser allows optional space between the command +letters and makes the space before the first argument optional. As +usual, each space can be any sequence of tab and space characters. + + Some graphics commands can take a variable number of arguments. In +this case, they are integers representing a size measured in basic units +'u'. The arguments called H1, H2, ..., HN stand for horizontal +distances where positive means right, negative left. The arguments +called V1, V2, ..., VN stand for vertical distances where positive means +down, negative up. All these distances are offsets relative to the +current location. + + Each graphics command directly corresponds to a similar 'gtroff' '\D' +escape sequence. *Note Drawing Geometric Objects::. + + Unknown 'D' commands are assumed to be device-specific. Its +arguments are parsed as strings; the whole information is then sent to +the postprocessor. + + In the following command reference, the syntax element +means a syntactical line break as defined above. + +'D~ H1 V1 H2 V2 ... HN VN' + Draw B-spline from current position to offset (H1,V1), then to + offset (H2,V2), if given, etc., up to (HN,VN). This command takes + a variable number of argument pairs; the current position is moved + to the terminal point of the drawn curve. + +'Da H1 V1 H2 V2' + Draw arc from current position to (H1,V1)+(H2,V2) with center at + (H1,V1); then move the current position to the final point of the + arc. + +'DC D' +'DC D DUMMY-ARG' + Draw a solid circle using the current fill color with diameter D + (integer in basic units 'u') with leftmost point at the current + position; then move the current position to the rightmost point of + the circle. An optional second integer argument is ignored (this + allows the formatter to generate an even number of arguments). + This command is a 'gtroff' extension. + +'Dc D' + Draw circle line with diameter D (integer in basic units 'u') with + leftmost point at the current position; then move the current + position to the rightmost point of the circle. + +'DE H V' + Draw a solid ellipse in the current fill color with a horizontal + diameter of H and a vertical diameter of V (both integers in basic + units 'u') with the leftmost point at the current position; then + move to the rightmost point of the ellipse. This command is a + 'gtroff' extension. + +'De H V' + Draw an outlined ellipse with a horizontal diameter of H and a + vertical diameter of V (both integers in basic units 'u') with the + leftmost point at current position; then move to the rightmost + point of the ellipse. + +'DF COLOR-SCHEME [COMPONENT ...]' + Set fill color for solid drawing objects using different color + schemes; the analogous command for setting the color of text, line + graphics, and the outline of graphic objects is 'm'. The color + components are specified as integer arguments between 0 and 65535. + The number of color components and their meaning vary for the + different color schemes. These commands are generated by + 'gtroff''s escape sequences '\D'F ...'' and '\M' (with no other + corresponding graphics commands). No position changing. This + command is a 'gtroff' extension. + + 'DFc CYAN MAGENTA YELLOW' + Set fill color for solid drawing objects using the CMY color + scheme, having the 3 color components CYAN, MAGENTA, and + YELLOW. + + 'DFd' + Set fill color for solid drawing objects to the default fill + color value (black in most cases). No component arguments. + + 'DFg GRAY' + Set fill color for solid drawing objects to the shade of gray + given by the argument, an integer between 0 (black) and 65535 + (white). + + 'DFk CYAN MAGENTA YELLOW BLACK' + Set fill color for solid drawing objects using the CMYK color + scheme, having the 4 color components CYAN, MAGENTA, YELLOW, + and BLACK. + + 'DFr RED GREEN BLUE' + Set fill color for solid drawing objects using the RGB color + scheme, having the 3 color components RED, GREEN, and BLUE. + +'Df N' + The argument N must be an integer in the range -32767 to 32767. + + 0 <= N <= 1000 + Set the color for filling solid drawing objects to a shade of + gray, where 0 corresponds to solid white, 1000 (the default) + to solid black, and values in between to intermediate shades + of gray; this is obsoleted by command 'DFg'. + + N < 0 or N > 1000 + Set the filling color to the color that is currently being + used for the text and the outline, see command 'm'. For + example, the command sequence + + mg 0 0 65535 + Df -1 + + sets all colors to blue. + + No position changing. This command is a 'gtroff' extension. + +'Dl H V' + Draw line from current position to offset (H,V) (integers in basic + units 'u'); then set current position to the end of the drawn line. + +'Dp H1 V1 H2 V2 ... HN VN' + Draw a polygon line from current position to offset (H1,V1), from + there to offset (H2,V2), etc., up to offset (HN,VN), and from there + back to the starting position. For historical reasons, the + position is changed by adding the sum of all arguments with odd + index to the actual horizontal position and the even ones to the + vertical position. Although this doesn't make sense it is kept for + compatibility. This command is a 'gtroff' extension. + +'DP H1 V1 H2 V2 ... HN VN' + Draw a solid polygon in the current fill color rather than an + outlined polygon, using the same arguments and positioning as the + corresponding 'Dp' command. This command is a 'gtroff' extension. + +'Dt N' + Set the current line thickness to N (an integer in basic units 'u') + if N>0; if N=0 select the smallest available line thickness; if N<0 + set the line thickness proportional to the type size (this is the + default before the first 'Dt' command was specified). For + historical reasons, the horizontal position is changed by adding + the argument to the actual horizontal position, while the vertical + position is not changed. Although this doesn't make sense it is + kept for compatibility. This command is a 'gtroff' extension. + + +File: groff.info, Node: Device Control Commands, Next: Obsolete Command, Prev: Graphics Commands, Up: Command Reference + +6.1.2.4 Device Control Commands +............................... + +Each device control command starts with the letter 'x', followed by a +space character (optional or arbitrary space or tab in 'gtroff') and a +subcommand letter or word; each argument (if any) must be preceded by a +syntactical space. All 'x' commands are terminated by a syntactical +line break; no device control command can be followed by another command +on the same line (except a comment). + + The subcommand is basically a single letter, but to increase +readability, it can be written as a word, i.e., an arbitrary sequence of +characters terminated by the next tab, space, or newline character. All +characters of the subcommand word but the first are simply ignored. For +example, 'gtroff' outputs the initialization command 'x i' as 'x init' +and the resolution command 'x r' as 'x res'. + + In the following, the syntax element means a syntactical +line break (*note Separation::). + +'xF NAME' + The 'F' stands for FILENAME. + + Use NAME as the intended name for the current file in error + reports. This is useful for remembering the original file name + when 'gtroff' uses an internal piping mechanism. The input file is + not changed by this command. This command is a 'gtroff' extension. + +'xf N S' + The 'f' stands for FONT. + + Mount font position N (a non-negative integer) with font named S (a + text word). *Note Font Positions::. + +'xH N' + The 'H' stands for HEIGHT. + + Set glyph height to N (a positive integer in scaled points 'z'). + AT&T 'troff' uses the unit points ('p') instead. *Note Output + Language Compatibility::. + +'xi' + The 'i' stands for INIT. + + Initialize device. This is the third command of the prologue. + +'xp' + The 'p' stands for PAUSE. + + Parsed but ignored. The AT&T 'troff' manual documents this command + as + + pause device, can be restarted + + but GNU 'troff' output drivers do nothing with this command. + +'xr N H V' + The 'r' stands for RESOLUTION. + + Resolution is N, while H is the minimal horizontal motion, and V + the minimal vertical motion possible with this device; all + arguments are positive integers in basic units 'u' per inch. This + is the second command of the prologue. + +'xS N' + The 'S' stands for SLANT. + + Set slant to N (an integer in basic units 'u'). + +'xs' + The 's' stands for STOP. + + Terminates the processing of the current file; issued as the last + command of any intermediate 'troff' output. + +'xt' + The 't' stands for TRAILER. + + Generate trailer information, if any. In GNU 'troff', this is + ignored. + +'xT XXX' + The 'T' stands for TYPESETTER. + + Set the name of the output driver to XXX, a sequence of + non-whitespace characters terminated by whitespace. The possible + names correspond to those of 'groff''s '-T' option. This is the + first command of the prologue. + +'xu N' + The 'u' stands for UNDERLINE. + + Configure underlining of spaces. If N is 1, start underlining of + spaces; if N is 0, stop underlining of spaces. This is needed for + the 'cu' request in 'nroff' mode and is ignored otherwise. This + command is a 'gtroff' extension. + +'xX ANYTHING' + The 'x' stands for X-ESCAPE. + + Send string ANYTHING uninterpreted to the device. If the line + following this command starts with a '+' character this line is + interpreted as a continuation line in the following sense. The '+' + is ignored, but a newline character is sent instead to the device, + the rest of the line is sent uninterpreted. The same applies to + all following lines until the first character of a line is not a + '+' character. This command is generated by the 'gtroff' escape + sequence '\X'. The line-continuing feature is a 'gtroff' + extension. + + +File: groff.info, Node: Obsolete Command, Prev: Device Control Commands, Up: Command Reference + +6.1.2.5 Obsolete Command +........................ + +In AT&T 'troff' output, the writing of a single glyph is mostly done by +a very strange command that combines a horizontal move and a single +character giving the glyph name. It doesn't have a command code, but is +represented by a 3-character argument consisting of exactly 2 digits and +a character. + +DDG + Move right DD (exactly two decimal digits) basic units 'u', then + print glyph G (represented as a single character). + + In GNU 'troff', arbitrary syntactical space around and within this + command is allowed. Only when a preceding command on the same line + ends with an argument of variable length is a separating space + obligatory. In AT&T 'troff', large clusters of these and other + commands are used, mostly without spaces; this made such output + almost unreadable. + + For modern high-resolution devices, this command does not make sense +because the width of the glyphs can become much larger than two decimal +digits. In 'gtroff', this is only used for the devices 'X75', 'X75-12', +'X100', and 'X100-12'. For other devices, the commands 't' and 'u' +provide a better functionality. + + +File: groff.info, Node: Intermediate Output Examples, Next: Output Language Compatibility, Prev: Command Reference, Up: gtroff Output + +6.1.3 Intermediate Output Examples +---------------------------------- + +This section presents the intermediate output generated from the same +input for three different devices. The input is the sentence 'hell +world' fed into 'gtroff' on the command line. + +High-resolution device 'ps' + + This is the standard output of 'gtroff' if no '-T' option is given. + + shell> echo "hell world" | groff -Z -T ps + + x T ps + x res 72000 1 1 + x init + p1 + x font 5 TR + f5 + s10000 + V12000 + H72000 + thell + wh2500 + tw + H96620 + torld + n12000 0 + x trailer + V792000 + x stop + + This output can be fed into 'grops' to get its representation as a + PostScript file. + +Low-resolution device 'latin1' + + This is similar to the high-resolution device except that the + positioning is done at a minor scale. Some comments (lines + starting with '#') were added for clarification; they were not + generated by the formatter. + + shell> echo "hell world" | groff -Z -T latin1 + + # prologue + x T latin1 + x res 240 24 40 + x init + # begin a new page + p1 + # font setup + x font 1 R + f1 + s10 + # initial positioning on the page + V40 + H0 + # write text 'hell' + thell + # inform about space, and issue a horizontal jump + wh24 + # write text 'world' + tworld + # announce line break, but do nothing because... + n40 0 + # ...the end of the document has been reached + x trailer + V2640 + x stop + + This output can be fed into 'grotty' to get a formatted text + document. + +AT&T 'troff' output + Since a computer monitor has a much lower resolution than modern + printers, the intermediate output for X11 devices can use the + jump-and-write command with its 2-digit displacements. + + shell> echo "hell world" | groff -Z -T X100 + + x T X100 + x res 100 1 1 + x init + p1 + x font 5 TR + f5 + s10 + V16 + H100 + # write text with jump-and-write commands + ch07e07l03lw06w11o07r05l03dh7 + n16 0 + x trailer + V1100 + x stop + + This output can be fed into 'xditview' or 'gxditview' for + displaying in X. + + Due to the obsolete jump-and-write command, the text clusters in + the AT&T 'troff' output are almost unreadable. + + +File: groff.info, Node: Output Language Compatibility, Prev: Intermediate Output Examples, Up: gtroff Output + +6.1.4 Output Language Compatibility +----------------------------------- + +The intermediate output language of AT&T 'troff' was first documented in +'A Typesetter-independent TROFF', by Brian Kernighan, and by 1992 the +AT&T 'troff' manual was updated to incorprate a description of it. + + The GNU 'troff' intermediate output format is compatible with this +specification except for the following features. + + * The classical quasi-device independence is not yet implemented. + + * The old hardware was very different from what we use today. So the + 'groff' devices are also fundamentally different from the ones in + AT&T 'troff'. For example, the AT&T PostScript device is called + 'post' and has a resolution of only 720 units per inch, suitable + for printers 20 years ago, while 'groff''s 'ps' device has a + resolution of 72000 units per inch. Maybe, by implementing some + rescaling mechanism similar to the classical quasi-device + independence, 'groff' could emulate AT&T's 'post' device. + + * The B-spline command 'D~' is correctly handled by the intermediate + output parser, but the drawing routines aren't implemented in some + of the postprocessor programs. + + * The argument of the commands 's' and 'x H' has the implicit unit + scaled point 'z' in 'gtroff', while AT&T 'troff' has point ('p'). + This isn't an incompatibility but a compatible extension, for both + units coincide for all devices without a 'sizescale' parameter in + the 'DESC' file, including all postprocessors from AT&T and + 'groff''s text devices. The few 'groff' devices with a 'sizescale' + parameter either do not exist for AT&T 'troff', have a different + name, or seem to have a different resolution. So conflicts are + very unlikely. + + * The position changing after the commands 'Dp', 'DP', and 'Dt' is + illogical, but as old versions of 'gtroff' used this feature it is + kept for compatibility reasons. + + +File: groff.info, Node: Device and Font Description Files, Prev: gtroff Output, Up: File Formats + +6.2 Device and Font Description Files +===================================== + +The 'groff' font and output device description formats are slight +extensions of those used by AT&T device-independent 'troff'. In +distinction to the AT&T implementation, 'groff' lacks a binary format; +all files are text files.(1) (*note Device and Font Description +Files-Footnote-1::) The device and font description files for a device +NAME are stored in a 'devNAME' directory. The device description file +is called 'DESC', and, for each font supported by the device, a font +description file is called 'F', where F is usually an abbreviation of a +font's name and/or style. For example, the 'ps' (PostScript) device has +'groff' font description files for Times roman ('TR') and Zapf Chancery +Medium italic ('ZCMI'), among many others, while the 'utf8' device (for +terminal emulators) has only font descriptions for the roman, italic, +bold, and bold-italic styles ('R', 'I', 'B', and 'BI', respectively). + + Device and font description files are read both by the formatter, GNU +'troff', and by output drivers. The programs delegate these files' +processing to an internal library, 'libgroff', ensuring their consistent +interpretation. + +* Menu: + +* DESC File Format:: +* Font Description File Format:: + + +File: groff.info, Node: Device and Font Description Files-Footnotes, Up: Device and Font Description Files + + (1) Plan 9 'troff' has also abandoned the binary format. + + +File: groff.info, Node: DESC File Format, Next: Font Description File Format, Prev: Device and Font Description Files, Up: Device and Font Description Files + +6.2.1 'DESC' File Format +------------------------ + +The 'DESC' file contains a series of directives; each begins a line. +Their order is not important, with two exceptions: (1) the 'res' +directive must precede any 'papersize' directive; and (2) the 'charset' +directive must come last (if at all). If a directive name is repeated, +later entries in the file override previous ones (except that the paper +dimensions are computed based on the 'res' directive last seen when +'papersize' is encountered). Spaces and/or tabs separate words and are +ignored at line boundaries. Comments start with the '#' character and +extend to the end of a line. Empty lines are ignored. + +'family FAM' + The default font family is FAM. + +'fonts N F1 ... FN' + Fonts F1, ..., FN are mounted at font positions M+1, ..., M+N where + M is the number of 'styles' (see below). This directive may extend + over more than one line. A font name of '0' causes no font to be + mounted at the corresponding position. + +'hor N' + The horizontal motion quantum is N basic units. All horizontal + quantities are rounded to multiples of N. + +'image_generator PROGRAM' + Use PROGRAM to generate PNG images from PostScript input. Under + GNU/Linux, this is usually 'gs', but under other systems (notably + Cygwin) it might be set to another name. The 'grohtml' driver uses + this directive. + +'paperlength N' + The vertical dimension of the output medium is N basic units + (deprecated: use 'papersize' instead). + +'papersize FORMAT-OR-DIMENSION-PAIR-OR-FILE-NAME ...' + The dimensions of the output medium are as according to the + argument, which is either a standard paper format, a pair of + dimensions, or the name of a plain text file containing either of + the foregoing. + + Recognized paper formats are the ISO and DIN formats 'A0'-'A7', + 'B0'-'B7', 'C0'-'C7', 'D0'-'D7'; the U.S. paper types 'letter', + 'legal', 'tabloid', 'ledger', 'statement', and 'executive'; and the + envelope formats 'com10', 'monarch', and 'DL'. Matching is + performed without regard for lettercase. + + Alternatively, the argument can be a custom paper format in the + format 'LENGTH,WIDTH' (with no spaces before or after the comma). + Both LENGTH and WIDTH must have a unit appended; valid units are + 'i' for inches, 'c' for centimeters, 'p' for points, and 'P' for + picas. Example: '12c,235p'. An argument that starts with a digit + is always treated as a custom paper format. + + Finally, the argument can be a file name (e.g., '/etc/papersize'); + if the file can be opened, the first line is read and a match + attempted against each of the other forms. No comment syntax is + supported. + + More than one argument can be specified; each is scanned in turn + and the first valid paper specification used. + +'paperwidth N' + The horizontal dimension of the output medium is N basic units + (deprecated: use 'papersize' instead). + +'pass_filenames' + Direct GNU 'troff' to emit the name of the source file being + processed. This is achieved with the intermediate output command + 'x F', which 'grohtml' interprets. + +'postpro PROGRAM' + Use PROGRAM as the postprocessor. + +'prepro PROGRAM' + Use PROGRAM as a preprocessor. The 'html' and 'xhtml' output + devices use this directive. + +'print PROGRAM' + Use PROGRAM as a spooler program for printing. If omitted, the + '-l' and '-L' options of 'groff' are ignored. + +'res N' + The device resolution is N basic units per inch. + +'sizes S1 ... SN 0' + The device has fonts at S1, ..., SN scaled points (see below). The + list of sizes must be terminated by '0'. Each SI can also be a + range of sizes M-N. The list can extend over more than one line. + +'sizescale N' + A typographical point is subdivided into N scaled points. The + default is '1'. *Note Using Fractional Type Sizes::. + +'styles S1 ... SM' + The first M mounting positions are associated with styles S1, ..., + SM. + +'tcommand' + The postprocessor can handle the 't' and 'u' intermediate output + commands. + +'unicode' + The output device supports the complete Unicode repertoire. This + directive is useful only for devices that produce character + entities instead of glyphs. + + If 'unicode' is present, no 'charset' section is required in the + font description files since the Unicode handling built into + 'groff' is used. However, if there are entries in a font + description file's 'charset' section, they either override the + default mappings for those particular characters or add new + mappings (normally for composite characters). + + The 'utf8', 'html', and 'xhtml' output devices use this directive. + +'unitwidth N' + Quantities in the font description files are in basic units for + fonts whose type size is N scaled points. + +'unscaled_charwidths' + Make the font handling module always return unscaled character + widths. The 'grohtml' driver uses this directive. + +'use_charnames_in_special' + GNU 'troff' should encode special characters inside device control + commands; see *note Postprocessor Access::. The 'grohtml' driver + uses this directive. + +'vert N' + The vertical motion quantum is N basic units. All vertical + quantities are rounded to multiples of N. + +'charset' + This line and everything following it in the file are ignored. It + is recognized for compatibility with other 'troff' implementations. + In GNU 'troff', character set repertoire is described on a per-font + basis. + + GNU 'troff' recognizes but ignores the directives 'spare1', 'spare2', +and 'biggestfont'. + + The 'res', 'unitwidth', 'fonts', and 'sizes' lines are mandatory. +Directives not listed above are ignored by GNU 'troff' but may be used +by postprocessors to obtain further information about the device. + + +File: groff.info, Node: Font Description File Format, Prev: DESC File Format, Up: Device and Font Description Files + +6.2.2 Font Description File Format +---------------------------------- + +On typesetting output devices, each font is typically available at +multiple sizes. While paper measurements in the device description file +are in absolute units, measurements applicable to fonts must be +proportional to the type size. 'groff' achieves this using the +precedent set by AT&T device-independent 'troff': one font size is +chosen as a norm, and all others are scaled linearly relative to that +basis. The "unit width" is the number of basic units per point when the +font is rendered at this nominal size. + + For instance, 'groff''s 'lbp' device uses a 'unitwidth' of 800. Its +Times roman font 'TR' has a 'spacewidth' of 833; this is also the width +of its comma, period, centered period, and mathematical asterisk, while +its 'M' is 2,963 basic units. Thus, an 'M' on the 'lbp' device is 2,963 +basic units wide at a notional type size of 800 points.(1) (*note Font +Description File Format-Footnote-1::) + + A font description file has two sections. The first is a sequence of +directives, and is parsed similarly to the 'DESC' file described above. +Except for the directive names that begin the second section, their +ordering is immaterial. Later directives of the same name override +earlier ones, spaces and tabs are handled in the same way, and the same +comment syntax is supported. Empty lines are ignored throughout. + +'name F' + The name of the font is F. 'DESC' is an invalid font name. Simple + integers are valid, but their use is discouraged.(2) (*note Font + Description File Format-Footnote-2::) + +'spacewidth N' + The width of an unadjusted inter-word space is N basic units. + + The directives above must appear in the first section; those below +are optional. + +'slant N' + The font's glyphs have a slant of N degrees; a positive N slants in + the direction of text flow. + +'ligatures LIG1 ... LIGN [0]' + Glyphs LIG1, ..., LIGN are ligatures; possible ligatures are 'ff', + 'fi', 'fl', 'ffi' and 'ffl'. For compatibility with other 'troff' + implementations, the list of ligatures may be terminated with + a '0'. The list of ligatures must not extend over more than one + line. + +'special' + The font is "special": when a glyph is requested that is not + present in the current font, it is sought in any mounted fonts that + bear this property. + + Other directives in this section are ignored by GNU 'troff', but may +be used by postprocessors to obtain further information about the font. + + The second section contains one or two subsections. These can appear +in either order; the first one encountered commences the second section. +Each starts with a directive on a line by itself. A 'charset' +subsection is mandatory unless the associated 'DESC' file contains the +'unicode' directive. Another subsection, 'kernpairs', is optional. + + The directive 'charset' starts the character set subsection.(3) +(*note Font Description File Format-Footnote-3::) It precedes a series +of glyph descriptions, one per line. Each such glyph description +comprises a set of fields separated by spaces or tabs and organized as +follows. + + NAME METRICS TYPE CODE [ENTITY-NAME] ['--' COMMENT] + +NAME identifies the glyph: if NAME is a printable character C, it +corresponds to the 'troff' ordinary character C. If NAME is a +multi-character sequence not beginning with '\', it corresponds to the +GNU 'troff' special character escape sequence '\[NAME]'. A name +consisting of three minus signs, '---', is special and indicates that +the glyph is unnamed: such glyphs can be accessed only by the '\N' +escape sequence in 'troff'. A special character named '---' can still +be defined using 'char' and similar requests. The NAME '\-' defines the +minus sign glyph. Finally, NAME can be the unbreakable one-sixth and +one-twelfth space escape sequences, '\|' and '\^' ("thin" and "hair" +spaces, respectively), in which case only the width metric described +below is interpreted; a font can thus customize the widths of these +spaces. + + The form of the METRICS field is as follows. + + WIDTH[','[HEIGHT[','[DEPTH[','[ITALIC-CORRECTION + [','[LEFT-ITALIC-CORRECTION[','[SUBSCRIPT-CORRECTION]]]]]]]]]] + +There must not be any spaces, tabs, or newlines between these +"subfields" (which have been split here into two lines only for better +legibility). The subfields are in basic units expressed as decimal +integers. Unspecified subfields default to '0'. Since there is no +associated binary format, these values are not required to fit into the +C language data type 'char' as they are in AT&T device-independent +'troff'. + + The WIDTH subfield gives the width of the glyph. The HEIGHT subfield +gives the height of the glyph (upward is positive); if a glyph does not +extend above the baseline, it should be given a zero height, rather than +a negative height. The DEPTH subfield gives the depth of the glyph, +that is, the distance below the baseline to which the glyph extends +(downward is positive); if a glyph does not extend below the baseline, +it should be given a zero depth, rather than a negative depth. Italic +corrections are relevant to glyphs in italic or oblique styles. The +ITALIC-CORRECTION is the amount of space that should be added after an +oblique glyph to be followed immediately by an upright glyph. The +LEFT-ITALIC-CORRECTION is the amount of space that should be added +before an oblique glyph to be preceded immediately by an upright glyph. +The SUBSCRIPT-CORRECTION is the amount of space that should be added +after an oblique glyph to be followed by a subscript; it should be less +than the italic correction. + + For fonts used with typesetting devices, the TYPE field gives a +featural description of the glyph: it is a bit mask recording whether +the glyph is an ascender, descender, both, or neither. When a '\w' +escape sequence is interpolated, these values are bitwise or-ed together +for each glyph and stored in the 'nr' register. In font descriptions +for terminal devices, all glyphs might have a type of zero, regardless +of their appearance. + +'0' + means the glyph lies entirely between the baseline and a horizontal + line at the "x-height" of the font; typical examples are 'a', 'c', + and 'x'; + +'1' + means the glyph descends below the baseline, like 'p'; + +'2' + means the glyph ascends above the font's x-height, like 'A' or 'b'; + and + +'3' + means the glyph is both an ascender and a descender--this is true + of parentheses in some fonts. + + The CODE field gives a numeric identifier that the postprocessor uses +to render the glyph. The glyph can be specified to 'troff' using this +code by means of the '\N' escape sequence. CODE can be any integer.(4) +(*note Font Description File Format-Footnote-4::) + + The ENTITY-NAME field defines an identifier for the glyph that the +postprocessor uses to print the GNU 'troff' glyph NAME. This field is +optional; it was introduced so that the 'grohtml' output driver could +encode its character set. For example, the glyph '\[Po]' is represented +by '£' in HTML 4.0. For efficiency, these data are now compiled +directly into 'grohtml'. 'grops' uses the field to build sub-encoding +arrays for PostScript fonts containing more than 256 glyphs. Anything +on the line after the ENTITY-NAME field or '--' is ignored. + + A line in the 'charset' section can also have the form + + NAME " + +identifying NAME as another name for the glyph mentioned in the +preceding line. Such aliases can be chained. + + The directive 'kernpairs' starts a list of kerning adjustments to be +made to adjacent glyph pairs from this font. It contains a sequence of +lines formatted as follows. + + G1 G2 N + +The foregoing means that when glyph G1 is typeset immediately before G2, +the space between them should be increased by N. Most kerning pairs +should have a negative value for N. + + +File: groff.info, Node: Font Description File Format-Footnotes, Up: Font Description File Format + + (1) 800-point type is not practical for most purposes, but using it +enables the quantities in the font description files to be expressed as +integers. + + (2) 'groff' requests and escape sequences interpret non-negative font +names as mounting positions instead. Further, a font named '0' cannot +be automatically mounted by the 'fonts' directive of a 'DESC' file. + + (3) For typesetter devices, this directive is misnamed since it +starts a list of glyphs, not characters. + + (4) that is, any integer parsable by the C standard library's +'strtol(3)' function + + +File: groff.info, Node: Copying This Manual, Next: Request Index, Prev: Font Description File Format, Up: Top + +Appendix A Copying This Manual +****************************** + + Version 1.3, 3 November 2008 + + Copyright © 2000-2018 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + 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, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: groff.info, Node: Request Index, Next: Escape Sequence Index, Prev: Copying This Manual, Up: Top + +Appendix B Request Index +************************ + +Request names appear without a leading control character; the defaults +are '.' for the regular control character and ''' for the no-break +control character. + +[index] +* Menu: + +* ab: Debugging. (line 55) +* ad: Manipulating Filling and Adjustment. + (line 83) +* af: Assigning Register Formats. + (line 12) +* aln: Setting Registers. (line 110) +* als: Strings. (line 198) +* am: Writing Macros. (line 126) +* am1: Writing Macros. (line 127) +* ami: Writing Macros. (line 128) +* ami1: Writing Macros. (line 129) +* as: Strings. (line 114) +* as1: Strings. (line 115) +* asciify: Diversions. (line 208) +* backtrace: Debugging. (line 104) +* bd: Artificial Fonts. (line 95) +* blm: Blank Line Traps. (line 7) +* box: Diversions. (line 63) +* boxa: Diversions. (line 64) +* bp: Page Control. (line 11) +* br: Manipulating Filling and Adjustment. + (line 39) +* break: while. (line 72) +* brp: Manipulating Filling and Adjustment. + (line 156) +* c2: Control Characters. (line 29) +* cc: Control Characters. (line 23) +* ce: Manipulating Filling and Adjustment. + (line 208) +* cf: I/O. (line 58) +* cflags: Using Symbols. (line 252) +* ch: Page Location Traps. (line 114) +* char: Using Symbols. (line 351) +* chop: Strings. (line 145) +* class: Character Classes. (line 12) +* close: I/O. (line 240) +* color: Colors. (line 15) +* composite: Using Symbols. (line 208) +* continue: while. (line 76) +* cp: Compatibility Mode. (line 16) +* cs: Artificial Fonts. (line 125) +* cu: Artificial Fonts. (line 86) +* da: Diversions. (line 32) +* de: Writing Macros. (line 14) +* de1: Writing Macros. (line 86) +* defcolor: Colors. (line 27) +* dei: Writing Macros. (line 108) +* dei1: Writing Macros. (line 109) +* device: Postprocessor Access. + (line 15) +* devicem: Postprocessor Access. + (line 45) +* di: Diversions. (line 31) +* do: Compatibility Mode. (line 27) +* ds: ms Document Control Settings. + (line 15) +* ds <1>: Strings. (line 24) +* ds1: Strings. (line 25) +* dt: Diversion Traps. (line 11) +* ec: Using Escape Sequences. + (line 76) +* ecr: Using Escape Sequences. + (line 102) +* ecs: Using Escape Sequences. + (line 101) +* el: if-else. (line 8) +* em: End-of-input Traps. (line 7) +* eo: Using Escape Sequences. + (line 71) +* ev: Environments. (line 46) +* evc: Environments. (line 100) +* ex: Debugging. (line 60) +* fam: Font Families. (line 21) +* fc: Fields. (line 18) +* fchar: Using Symbols. (line 352) +* fcolor: Colors. (line 85) +* fi: Manipulating Filling and Adjustment. + (line 66) +* fl: Debugging. (line 95) +* fp: Font Positions. (line 16) +* fschar: Using Symbols. (line 353) +* fspecial: Special Fonts. (line 18) +* ft: Selecting Fonts. (line 11) +* ftr: Selecting Fonts. (line 69) +* fzoom: Selecting Fonts. (line 83) +* gcolor: Colors. (line 57) +* hc: Manipulating Hyphenation. + (line 88) +* hcode: Manipulating Hyphenation. + (line 293) +* hla: Manipulating Hyphenation. + (line 327) +* hlm: Manipulating Hyphenation. + (line 340) +* hpf: Manipulating Hyphenation. + (line 233) +* hpfa: Manipulating Hyphenation. + (line 234) +* hpfcode: Manipulating Hyphenation. + (line 235) +* hw: Manipulating Hyphenation. + (line 22) +* hy: Manipulating Hyphenation. + (line 120) +* hym: Manipulating Hyphenation. + (line 354) +* hys: Manipulating Hyphenation. + (line 369) +* ie: if-else. (line 7) +* if: if-then. (line 7) +* ig: Comments. (line 54) +* in: Line Layout. (line 86) +* it: Input Line Traps. (line 7) +* itc: Input Line Traps. (line 8) +* kern: Ligatures and Kerning. + (line 41) +* lc: Leaders. (line 22) +* length: Strings. (line 135) +* lf: Debugging. (line 31) +* lg: Ligatures and Kerning. + (line 23) +* linetabs: Tabs and Fields. (line 139) +* ll: Line Layout. (line 138) +* ls: Manipulating Spacing. + (line 57) +* lsm: Leading Space Traps. (line 7) +* lt: Page Layout. (line 53) +* mc: Miscellaneous. (line 110) +* mk: Page Motions. (line 10) +* mso: I/O. (line 49) +* msoquiet: I/O. (line 50) +* na: Manipulating Filling and Adjustment. + (line 150) +* ne: Page Control. (line 31) +* nf: Manipulating Filling and Adjustment. + (line 74) +* nh: Manipulating Hyphenation. + (line 228) +* nm: Miscellaneous. (line 9) +* nn: Miscellaneous. (line 74) +* nop: if-then. (line 26) +* nr: ms Document Control Settings. + (line 11) +* nr <1>: Setting Registers. (line 10) +* nr <2>: Setting Registers. (line 64) +* nr <3>: Auto-increment. (line 14) +* nroff: troff and nroff Modes. + (line 33) +* ns: Manipulating Spacing. + (line 116) +* nx: I/O. (line 90) +* open: I/O. (line 207) +* opena: I/O. (line 208) +* os: Page Control. (line 66) +* output: Diversions. (line 195) +* pc: Page Layout. (line 68) +* pev: Debugging. (line 78) +* pi: I/O. (line 149) +* pl: Page Layout. (line 9) +* pm: Debugging. (line 82) +* pn: Page Layout. (line 23) +* pnr: Debugging. (line 86) +* po: Line Layout. (line 60) +* ps: Changing the Type Size. + (line 7) +* psbb: Miscellaneous. (line 158) +* pso: I/O. (line 38) +* ptr: Debugging. (line 90) +* pvs: Changing the Vertical Spacing. + (line 48) +* rchar: Using Symbols. (line 410) +* rd: I/O. (line 95) +* return: Writing Macros. (line 163) +* rfschar: Using Symbols. (line 411) +* rj: Manipulating Filling and Adjustment. + (line 247) +* rm: Strings. (line 193) +* rn: Strings. (line 190) +* rnn: Setting Registers. (line 105) +* rr: Setting Registers. (line 99) +* rs: Manipulating Spacing. + (line 117) +* rt: Page Motions. (line 11) +* schar: Using Symbols. (line 354) +* shc: Manipulating Hyphenation. + (line 97) +* shift: Parameters. (line 30) +* sizes: Changing the Type Size. + (line 71) +* so: I/O. (line 9) +* soquiet: I/O. (line 10) +* sp: Manipulating Spacing. + (line 10) +* special: Special Fonts. (line 17) +* spreadwarn: Debugging. (line 135) +* ss: Manipulating Filling and Adjustment. + (line 267) +* stringdown: Strings. (line 170) +* stringup: Strings. (line 171) +* sty: Font Families. (line 62) +* substring: Strings. (line 153) +* sv: Page Control. (line 65) +* sy: I/O. (line 171) +* ta: Tabs and Fields. (line 13) +* tag: Postprocessor Access. + (line 58) +* taga: Postprocessor Access. + (line 59) +* tc: Tabs and Fields. (line 127) +* ti: Line Layout. (line 110) +* tkf: Ligatures and Kerning. + (line 60) +* tl: Page Layout. (line 39) +* tm: Debugging. (line 43) +* tm1: Debugging. (line 44) +* tmc: Debugging. (line 45) +* tr: Character Translations. + (line 13) +* trf: I/O. (line 57) +* trin: Character Translations. + (line 14) +* trnt: Character Translations. + (line 79) +* troff: troff and nroff Modes. + (line 25) +* uf: Artificial Fonts. (line 90) +* ul: Artificial Fonts. (line 64) +* unformat: Diversions. (line 233) +* vpt: Vertical Position Traps. + (line 13) +* vs: Changing the Vertical Spacing. + (line 7) +* warn: Debugging. (line 154) +* warnscale: Debugging. (line 131) +* wh: Page Location Traps. (line 11) +* while: while. (line 10) +* write: I/O. (line 219) +* writec: I/O. (line 220) +* writem: I/O. (line 231) + diff --git a/doc/groff.info-3 b/doc/groff.info-3 new file mode 100644 index 0000000..151c796 Binary files /dev/null and b/doc/groff.info-3 differ diff --git a/doc/groff.pdf b/doc/groff.pdf new file mode 100644 index 0000000..84e8422 Binary files /dev/null and b/doc/groff.pdf differ diff --git a/doc/groff.texi b/doc/groff.texi new file mode 100644 index 0000000..2a6635e --- /dev/null +++ b/doc/groff.texi @@ -0,0 +1,18927 @@ +\input texinfo + +@c +@c Please convert this manual with `texi2dvi -e groff.texi' due to +@c problems in texinfo regarding expansion of user-defined macros. +@c +@c You need texinfo 5.0 or newer to format this document! +@c + +@c %**start of header (This is for running Texinfo on a region.) +@setfilename groff.info +@settitle The GNU Troff Manual +@setchapternewpage odd +@footnotestyle separate +@c %**end of header (This is for running Texinfo on a region.) + +@documentlanguage en +@documentencoding ISO-8859-1 + + +@smallbook + +@finalout + + +@copying +This manual documents GNU @code{troff} version 1.23.0. + +Copyright @copyright{} 1994--2023 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +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, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled ``GNU Free +Documentation License''. +@end quotation +@end copying + + +@c We use the following indices: +@c +@c cindex: concepts +@c rqindex: requests +@c esindex: escape sequences +@c vindex: registers +@c kindex: commands in font files +@c pindex: programs and files +@c tindex: environment variables +@c maindex: macros +@c stindex: strings +@c opindex: operators +@c +@c tindex and cindex are merged. + +@defcodeindex rq +@defcodeindex es +@defcodeindex ma +@defcodeindex st +@defcodeindex op +@syncodeindex tp cp + + +@c To avoid uppercasing in @deffn while converting to info, we define +@c our special @Var{}. + +@macro Var{arg} +@r{@slanted{\arg\}} +@end macro + + +@c To assure correct HTML translation, some ugly hacks are necessary. +@c While processing a @def... request, the HTML translator looks at the +@c next line to decide whether to start indentation, and if the line +@c starts with @def... (e.g. @deffnx), indentation is started. We must +@c therefore ensure that a @def... is seen, during macro expansion. +@c +@c The following macros have to be used: +@c +@c One item: +@c +@c @Def... +@c +@c Two items: +@c +@c @Def...List +@c @Def...ListEnd +@c +@c More than two: +@c +@c @Def...List +@c @Def...Item +@c @Def...Item +@c ... +@c @Def...ListEnd +@c +@c The definition block must end with +@c +@c @endDef... +@c +@c The above is valid for texinfo 4.0f and above. +@c +@c By default, only the first item generates an index entry. To +@c override this, use a variant with a trailing `x' (like +@c `@DefmacItemx'). + + +@c a dummy macro to assure the `@def...' + +@macro defdummy +@c +@end macro + + +@c definition of requests + +@macro Defreq{name, arg} +@deffn Request @t{.\name\} \arg\ +@rqindex \name\ +@c +@end macro + +@macro DefreqList{name, arg} +@deffn Request @t{.\name\} \arg\ +@defdummy +@rqindex \name\ +@c +@end macro + +@macro DefreqItem{name, arg} +@deffnx Request @t{.\name\} \arg\ +@defdummy +@c +@end macro + +@macro DefreqItemx{name, arg} +@deffnx Request @t{.\name\} \arg\ +@defdummy +@rqindex \name\ +@c +@end macro + +@macro DefreqListEnd{name, arg} +@deffnx Request @t{.\name\} \arg\ +@c +@end macro + +@macro DefreqListEndx{name, arg} +@deffnx Request @t{.\name\} \arg\ +@rqindex \name\ +@c +@end macro + +@macro endDefreq +@end deffn +@end macro + + +@c definition of escape sequences + +@macro Defesc{name, delimI, arg, delimII} +@deffn Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} +@esindex \name\ +@c +@end macro + +@macro DefescList{name, delimI, arg, delimII} +@deffn Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} +@defdummy +@esindex \name\ +@c +@end macro + +@macro DefescItem{name, delimI, arg, delimII} +@deffnx Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} +@defdummy +@c +@end macro + +@macro DefescItemx{name, delimI, arg, delimII} +@deffnx Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} +@defdummy +@esindex \name\ +@c +@end macro + +@macro DefescListEnd{name, delimI, arg, delimII} +@deffnx Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} +@c +@end macro + +@macro DefescListEndx{name, delimI, arg, delimII} +@deffnx Escape@tie{}sequence @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} +@esindex \name\ +@c +@end macro + +@macro endDefesc +@end deffn +@end macro + + +@c definition of registers (built in to GNU troff) + +@macro Defreg{name} +@deffn Register @t{\\n[\name\]} +@vindex \name\ +@c +@end macro + +@macro DefregList{name} +@deffn Register @t{\\n[\name\]} +@defdummy +@vindex \name\ +@c +@end macro + +@macro DefregItem{name} +@deffnx Register @t{\\n[\name\]} +@defdummy +@c +@end macro + +@macro DefregItemx{name} +@deffnx Register @t{\\n[\name\]} +@defdummy +@vindex \name\ +@c +@end macro + +@macro DefregListEnd{name} +@deffnx Register @t{\\n[\name\]} +@c +@end macro + +@macro DefregListEndx{name} +@deffnx Register @t{\\n[\name\]} +@vindex \name\ +@c +@end macro + +@macro endDefreg +@end deffn +@end macro + + +@c string definitions (built in to GNU troff) + +@macro Defstr{name} +@deffn String @t{\\*[\name\]} +@stindex \name\ +@c +@end macro + +@macro DefstrList{name} +@deffn String @t{\\*[\name\]} +@defdummy +@stindex \name\ +@c +@end macro + +@macro DefstrItem{name} +@deffnx String @t{\\*[\name\]} +@defdummy +@c +@end macro + +@macro DefstrItemx{name} +@deffnx String @t{\\*[\name\]} +@defdummy +@stindex \name\ +@c +@end macro + +@macro DefstrListEnd{name} +@deffnx String @t{\\*[\name\]} +@c +@end macro + +@macro DefstrListEndx{name} +@deffnx String @t{\\*[\name\]} +@stindex \name\ +@c +@end macro + +@macro endDefstr +@end deffn +@end macro + + +@c register definitions specific to macro packages, preprocessors, ... + +@macro Defmpreg{name, package} +@deffn Register @t{\\n[\name\]} +@vindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro DefmpregList{name, package} +@deffn Register @t{\\n[\name\]} +@defdummy +@vindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro DefmpregItem{name, package} +@deffnx Register @t{\\n[\name\]} +@defdummy +@c +@end macro + +@macro DefmpregItemx{name, package} +@deffnx Register @t{\\n[\name\]} +@defdummy +@vindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro DefmpregListEnd{name, package} +@deffnx Register @t{\\n[\name\]} +@c +@end macro + +@macro DefmpregListEndx{name, package} +@deffnx Register @t{\\n[\name\]} +@vindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro endDefmpreg +@end deffn +@end macro + + +@c definition of macros + +@macro Defmac{name, arg, package} +@defmac @t{.\name\} \arg\ +@maindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro DefmacList{name, arg, package} +@defmac @t{.\name\} \arg\ +@defdummy +@maindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro DefmacItem{name, arg, package} +@defmacx @t{.\name\} \arg\ +@defdummy +@c +@end macro + +@macro DefmacItemx{name, arg, package} +@defmacx @t{.\name\} \arg\ +@defdummy +@maindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro DefmacListEnd{name, arg, package} +@defmacx @t{.\name\} \arg\ +@c +@end macro + +@macro DefmacListEndx{name, arg, package} +@defmacx @t{.\name\} \arg\ +@maindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro endDefmac +@end defmac +@end macro + + +@c string definitions specific to macro packages, preprocessors, ... + +@macro Defmpstr{name, package} +@deffn String @t{\\*[\name\]} +@stindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro DefmpstrList{name, package} +@deffn String @t{\\*[\name\]} +@defdummy +@stindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro DefmpstrItem{name, package} +@deffnx String @t{\\*[\name\]} +@defdummy +@c +@end macro + +@macro DefmpstrItemx{name, package} +@deffnx String @t{\\*[\name\]} +@defdummy +@stindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro DefmpstrListEnd{name, package} +@deffnx String @t{\\*[\name\]} +@c +@end macro + +@macro DefmpstrListEndx{name, package} +@deffnx String @t{\\*[\name\]} +@stindex \name\ @r{[}\package\@r{]} +@c +@end macro + +@macro endDefmpstr +@end deffn +@end macro + + +@c our example macros + +@macro Example +@example +@group +@end macro + +@macro endExample +@end group +@end example +@end macro + +@macro CartoucheExample +@cartouche +@example +@end macro + +@macro endCartoucheExample +@end example +@end cartouche +@end macro + + +@c Render text with angle brackets around it, as in . + +@macro angles{text} +@guilsinglleft{}@r{\text\}@guilsinglright{} +@end macro + + +@c Note: We say `Roman numerals' but `roman font'. + + +@dircategory Typesetting +@direntry +* Groff: (groff). The GNU roff document formatting system. +@end direntry + + +@titlepage +@title groff +@subtitle The GNU implementation of @code{troff} +@subtitle Edition 1.23.0 +@subtitle June 2023 +@author Trent@tie{}A.@: Fisher +@author Werner Lemberg +@author G.@tie{}Branden Robinson + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top GNU @code{troff} +@end ifnottex + +@menu +* Introduction:: +* Invoking groff:: +* Tutorial for Macro Users:: +* Major Macro Packages:: +* GNU troff Reference:: +* File Formats:: +* Copying This Manual:: +* Request Index:: +* Escape Sequence Index:: +* Operator Index:: +* Register Index:: +* Macro Index:: +* String Index:: +* File Keyword Index:: +* Program and File Index:: +* Concept Index:: +@end menu + +@ifnottex +@insertcopying +@end ifnottex + + + +@c ===================================================================== +@c ===================================================================== + +@codequotebacktick on +@codequoteundirected on + +@node Introduction, Invoking groff, Top, Top +@chapter Introduction +@cindex introduction + +GNU @code{roff} (or @code{groff}) is a programming system for +typesetting documents. It is highly flexible and has been used +extensively for over thirty years. + +@menu +* Background:: +* What Is @code{groff}?:: +* @code{groff} Capabilities:: +* Macro Package Intro:: +* Preprocessor Intro:: +* Output Device Intro:: +* Conventions Used in This Manual:: +* Installation:: +* Credits:: +@end menu + + +@c ===================================================================== + +@node Background, What Is @code{groff}?, Introduction, Introduction +@section Background +@cindex background + +M.@: Douglas McIlroy, formerly of AT&T Bell Laboratories and present at +the creation of the Unix operating system, offers an authoritative +historical summary. + +@quotation +The prime reason for Unix was the desire of Ken [Thompson], Dennis +[Ritchie], and Joe Ossanna to have a pleasant environment for software +development. The fig leaf that got the nod from @dots{} +management was that an early use would be to develop a ``stand-alone'' +word-processing system for use in typing pools and secretarial offices. +Perhaps they had in mind ``dedicated'', as distinct from +``stand-alone''; that's what eventuated in various cases, most notably +in the legal/patent department and in the AT&T CEO's office. + +Both those systems were targets of opportunity, not foreseen from the +start. When Unix was up and running on the PDP-11, Joe got wind of +the legal department having installed a commercial word processor. +He went to pitch Unix as an alternative and clinched a trial by +promising to make @code{roff} able to number lines by tomorrow in order +to fulfill a patent-office requirement that the commercial system did +not support. + +Modems were installed so legal-department secretaries could try the +Research machine. They liked it and Joe's superb customer service. +Soon the legal department got a system of their own. Joe went on to +create @code{nroff} and @code{troff}. Document preparation became a +widespread use of Unix, but no stand-alone word-processing system was +ever undertaken. +@end quotation +@c https://minnie.tuhs.org/pipermail/tuhs/2022-March/025535.html + +A history relating @code{groff} to its predecessors @code{roff}, +@code{nroff}, and @code{troff} is available in the @cite{roff@r{(7)}} +man page. + + +@c ===================================================================== + +@node What Is @code{groff}?, @code{groff} Capabilities, Introduction, Introduction +@section What Is @code{groff}? +@cindex what is @code{groff}? +@cindex @code{groff}---what is it? + +@c BEGIN Keep parallel with groff(1), section "Description" (after the +@c first sentence). +@c This language is slightly expanded from that in the "ANNOUNCE" file +@c and on the groff home page. +@code{groff} (GNU @code{roff}) is a typesetting system that reads plain +text input files that include formatting commands to produce output in +PostScript, PDF, HTML, DVI, or other formats, or for display to a +terminal. Formatting commands can be low-level typesetting primitives, +macros from a supplied package, or user-defined macros. All three +approaches can be combined. + +A reimplementation and extension of the typesetter from @acronym{AT&T} +Unix, @code{groff} is present on most @acronym{POSIX} systems owing to +its long association with Unix manuals (including man pages). It and +its predecessor are notable for their production of several best-selling +software engineering texts. @code{groff} is capable of producing +typographically sophisticated documents while consuming minimal system +resources. +@c END Keep parallel with groff(1), section "Description" (after the +@c first sentence). + + +@c ===================================================================== + +@node @code{groff} Capabilities, Macro Package Intro, What Is @code{groff}?, Introduction +@section @code{groff} Capabilities +@cindex @code{groff} capabilities +@cindex capabilities of @code{groff} + +GNU @code{troff} is a typesetting document formatter; it provides a wide +range of low-level text and page operations within the framework of a +programming language. These operations compose to generate footnotes, +tables of contents, mathematical equations, diagrams, multi-column text, +and other elements of typeset works. Here is a survey of formatter +features; all are under precise user control. + +@itemize @bullet +@item +text filling, breaking, alignment to the left or right margin; centering + +@item +adjustment of inter-word space size to justify text, and of +inter-sentence space size to suit local style conventions + +@item +automatic and manual determination of hyphenation break points + +@item +pagination + +@item +selection of any font available to the output device + +@item +adjustment of type size and vertical spacing (or ``leading'') + +@item +configuration of line length and indentation amounts; columnation + +@item +drawing of geometric primitives (lines, arcs, polygons, circles, +@dots{}) + +@item +setup of stroke and fill colors (where supported by the output +device) + +@item +embedding of hyperlinks, images, document metadata, and other inclusions +(where supported by the output device) +@end itemize + + +@c ===================================================================== + +@node Macro Package Intro, Preprocessor Intro, @code{groff} Capabilities, Introduction +@section Macro Packages +@cindex macro package, introduction +@cindex package, macro, introduction + +Elemental typesetting functions can be be challenging to use directly +with complex documents. A @dfn{macro} facility specifies how certain +routine operations, such as starting paragraphs, or printing headers and +footers, should be performed in terms of those low-level instructions. +Macros can be specific to one document or collected together into a +@dfn{macro package} for use by many. Several macro packages available; +the most widely used are provided with @code{groff}. They are +@file{man}, @file{mdoc}, @file{me}, @file{mm}, @file{mom}, and +@file{ms}. + + +@c ===================================================================== + +@node Preprocessor Intro, Output Device Intro, Macro Package Intro, Introduction +@section Preprocessors +@cindex preprocessors + +An alternative approach to complexity management, particularly when +constructing tables, setting mathematics, or drawing diagrams, lies in +preprocessing. A @dfn{preprocessor} employs a domian-specific language +to ease the generation of tables, equations, and so forth in terms that +are convenient for human entry. Each preprocessor reads a document and +translates the parts of it that apply to it into GNU @code{troff} input. +Command-line options to @command{groff} tell it which preprocessors to +use. + +@code{groff} provides preprocessors for laying out tables +(@command{gtbl}), typesetting equations (@command{geqn}), drawing +diagrams (@command{gpic} and @command{ggrn}), inserting bibliographic +references (@command{grefer}), and drawing chemical structures +(@command{gchem}). An associated program that is useful when dealing +with preprocessors is @command{gsoelim}.@footnote{The @samp{g} prefix is +not used on all systems; see @ref{Invoking groff}.} + +@code{groff} also supports @code{grap}, a preprocessor for drawing +graphs. A free implementation of it can be obtained separately. + +Unique to @code{groff} is the @code{preconv} preprocessor that enables +@code{groff} to handle documents in a variety of input encodings. + +Other preprocessors exist, but no free implementations +are known. An example is @command{ideal}, which draws diagrams using a +mathematical constraint language. + + +@c ===================================================================== + +@node Output Device Intro, Installation, Preprocessor Intro, Introduction +@section Output Devices +@cindex postprocessors +@cindex output devices +@cindex devices for output + +GNU @code{troff}'s output is in a device-independent page description +language, which is then read by an @dfn{output driver} that translates +this language into a file format or byte stream that a piece of +(possibly emulated) hardware understands. @code{groff} features output +drivers for PostScript devices, terminal emulators (and other simple +typewriter-like machines), X11 (for previewing), @TeX{} DVI, HP +LaserJet@tie{}4/PCL5 and Canon LBP printers (which use @acronym{CaPSL}), +@acronym{HTML}, @acronym{XHTML}, and @acronym{PDF}. + + +@c ===================================================================== + +@node Installation, Conventions Used in This Manual, Output Device Intro, Introduction +@section Installation +@cindex installation + +Locate installation instructions in the files @file{INSTALL}, +@file{INSTALL.extra}, and @file{INSTALL.REPO} in the @code{groff} source +distribution. Being a GNU project, @code{groff} supports the familiar +@samp{./configure && make} command sequence. + + +@c ===================================================================== + +@node Conventions Used in This Manual, Credits, Installation, Introduction +@section Conventions Used in This Manual + +We apply the term ``groff'' to the language documented here, the GNU +implementation of the overall system, the project that develops that +system, and the command of that name. In the first sense, @code{groff} +is an extended dialect of the @code{roff} language, for which many +similar implementations exist. + +The @code{roff} language features several major categories for which +many items are predefined. Presentations of these items feature the +form in which the item is most commonly used on the left, and, aligned +to the right margin, the name of the category in brackets. + +@deffn Register \n[example] +The register @samp{example} is one that that @code{groff} @emph{doesn't} +predefine. You can create it yourself, though; see @ref{Setting +Registers}. +@end deffn + +To make this document useful as a reference and not merely amiable +bedtime reading, we tend to present these syntax items in exhaustive +detail when they arise. References to topics discussed later in the +text are frequent; skip material you don't understand yet. + +We use Texinfo's ``result'' (@result{}) and @error{} notations to +present output written to the standard output and standard error +streams, respectively. Diagnostic messages from the GNU @code{troff} +formatter and other programs are examples of the latter, but the +formatter can also be directed to write user-specified messages to the +standard error stream. The notation then serves to identify the +output stream and does not necessarily mean that an error has +occurred.@footnote{Unix and related operating systems distinguish +standard output and standard error streams @emph{because} of +@code{troff}:@: +@uref{https://minnie.tuhs.org/pipermail/tuhs/2013-December/006113.html}.} + +@Example +$ echo "Twelve o'clock and" | groff -Tascii | sed '/^$/d' + @result{} Twelve o'clock and +$ echo '.tm all is well.' | groff > /dev/null + @error{} all is well. +@endExample + +Sometimes we use @result{} somewhat abstractly to represent formatted +text that you will need to use a PostScript or PDF viewer program (or a +printer) to observe. While arguably an abuse of notation, we think this +preferable to requiring the reader to understand the syntax of these +page description languages. + +We also present diagnostic messages in an abbreviated form, often +omitting the name of the program issuing them, the input file name, and +line number or other positional information when such data do not serve +to illuminate the topic under discussion. + +Most examples are of @code{roff} language input that would be placed in +a text file. Occasionally, we start an example with a @samp{$} +character to indicate a shell prompt, as seen above. + +You are encouraged to try the examples yourself, and to alter them to +better learn @code{groff}'s behavior. Our examples frequently need to +direct the formatter to set a line length (with @samp{.ll}) that will +fit within the page margins of this manual. We mention this so that you +know why it is there before we discuss the @code{ll} request +formally.@footnote{@xref{Line Layout}.} + + +@c ===================================================================== + +@node Credits, , Conventions Used in This Manual, Introduction +@section Credits +@cindex credits + +We adapted portions of this manual from existing documents. James +Clark's man pages were an essential resource; we have updated them in +parallel with the development of this manual. We based the tutorial for +macro users on Eric Allman's introduction to his @file{me} macro package +(which we also provide, little altered from 4.4BSD). Larry Kollar +contributed much of the material on the @file{ms} macro package. + + +@c ===================================================================== +@c ===================================================================== + +@node Invoking groff, Tutorial for Macro Users, Introduction, Top +@chapter Invoking @code{groff} +@cindex invoking @code{groff} +@cindex @code{groff} invocation + +This chapter focuses on how to invoke the @code{groff} front end. This +front end takes care of the details of constructing the pipeline among +the preprocessors, @code{gtroff} and the postprocessor. + +It has become a tradition that GNU programs get the prefix @samp{g} to +distinguish them from their original counterparts provided by the host +(@pxref{Environment}). Thus, for example, @code{geqn} is GNU +@code{eqn}. On operating systems like GNU/Linux or the Hurd, which +don't contain proprietary versions of @code{troff}, and on +MS-DOS/MS-Windows, where @code{troff} and associated programs are not +available at all, this prefix is omitted since GNU @code{troff} is the +only incarnation of @code{troff} used. Exception: @samp{groff} is never +replaced by @samp{roff}. + +In this document, we consequently say @samp{gtroff} when talking about +the GNU @code{troff} program. @c XXX: Not for much longer... -- GBR +All other implementations of @code{troff} are called @acronym{AT&T} +@code{troff}, which is the common origin of almost all @code{troff} +implementations@footnote{Besides @code{groff}, @code{neatroff} is an +exception.} (with more or less compatible changes). Similarly, we say +@samp{gpic}, @samp{geqn}, and so on. + +@menu +* Groff Options:: +* Environment:: +* Macro Directories:: +* Font Directories:: +* Paper Format:: +* Invocation Examples:: +@end menu + + +@c ===================================================================== + +@node Groff Options, Environment, Invoking groff, Invoking groff +@section Options +@cindex options + +@pindex groff +@pindex gtroff +@pindex gpic +@pindex geqn +@pindex ggrn +@pindex grap +@pindex gtbl +@pindex gchem +@pindex grefer +@pindex gsoelim +@pindex preconv +@code{groff} normally runs the @code{gtroff} program and a +postprocessor appropriate for the selected device. The default device +is @samp{ps} (but it can be changed when @code{groff} is configured and +built). It can optionally preprocess with any of @code{gpic}, +@code{geqn}, @code{gtbl}, @code{ggrn}, @code{grap}, @code{gchem}, +@code{grefer}, @code{gsoelim}, or @code{preconv}. + +This section documents only options to the @code{groff} front end. Many +of the arguments to @code{groff} are passed on to @code{gtroff}; +therefore, those are also included. Arguments to preprocessors and +output drivers can be found in the man pages @cite{gpic@r{(1)}}, +@cite{geqn@r{(1)}}, @cite{gtbl@r{(1)}}, @cite{ggrn@r{(1)}}, +@cite{grefer@r{(1)}}, @cite{gchem@r{(1)}}, @cite{gsoelim@r{(1)}}, +@cite{preconv@r{(1)}}, @cite{grotty@r{(1)}}, @cite{grops@r{(1)}}, +@cite{gropdf@r{(1)}}, @cite{grohtml@r{(1)}}, @cite{grodvi@r{(1)}}, +@cite{grolj4@r{(1)}}, @cite{grolbp@r{(1)}}, and @cite{gxditview@r{(1)}}. + +The command-line format for @code{groff} is: + +@Example +groff [ -abceghijklpstvzCEGNRSUVXZ ] [ -d@var{cs} ] [ -D@var{arg} ] + [ -f@var{fam} ] [ -F@var{dir} ] [ -I@var{dir} ] [ -K@var{arg} ] + [ -L@var{arg} ] [ -m@var{name} ] [ -M@var{dir} ] [ -n@var{num} ] + [ -o@var{list} ] [ -P@var{arg} ] [ -r@var{cn} ] [ -T@var{dev} ] + [ -w@var{name} ] [ -W@var{name} ] [ @var{files}@dots{} ] +@endExample + +The command-line format for @code{gtroff} is as follows. + +@Example +gtroff [ -abcivzCERU ] [ -d@var{cs} ] [ -f@var{fam} ] [ -F@var{dir} ] + [ -m@var{name} ] [ -M@var{dir} ] [ -n@var{num} ] [ -o@var{list} ] + [ -r@var{cn} ] [ -T@var{name} ] [ -w@var{name} ] [ -W@var{name} ] + [ @var{files}@dots{} ] +@endExample + +@noindent +Obviously, many of the options to @code{groff} are actually passed on to +@code{gtroff}. + +Options without an argument can be grouped behind a +single@tie{}@option{-}. A filename of@tie{}@file{-} denotes the +standard input. Whitespace is permitted between an option and its +argument. + +The @code{grog} command can be used to guess the correct @code{groff} +command to format a file. See its man page @cite{grog@r{(1)}}; type +@samp{man grog} at the command line to view it. + +@command{groff}'s command-line options are as follows. + +@cindex command-line options +@table @samp +@item -a +@cindex plain text approximation output register (@code{.A}) +Generate a plain text approximation of the typeset output. The +read-only register @code{.A} is set to@tie{}1. @xref{Built-in +Registers}. This option produces a sort of abstract preview of the +formatted output. + +@itemize @bullet +@item +Page breaks are marked by a phrase in angle brackets; for example, +@samp{}. + +@item +Lines are broken where they would be in the formatted output. + +@item +A horizontal motion of any size is represented as one space. Adjacent +horizontal motions are not combined. Inter-sentence space nodes (those +arising from the second argument to the @code{ss} request) are not +represented. + +@item +Vertical motions are not represented. + +@item +Special characters are rendered in angle brackets; for example, the +default soft hyphen character appears as @samp{}. +@end itemize + +The above description should not be considered a specification; the +details of @option{-a} output are subject to change. + +@item -b +Write a backtrace reporting the state of @command{gtroff}'s input parser +to the standard error stream with each diagnostic message. The line +numbers given in the backtrace might not always be correct, because +@command{gtroff}'s idea of line numbers can be confused by requests that +append to +@c XXX: strings or (??? strings never contain newlines) +macros. + +@item -c +Start with color output disabled. + +@item -C +Enable AT&T @command{troff} compatibility mode; implies @option{-c}. +@xref{Implementation Differences}, for the list of incompatibilities +between @command{groff} and @acronym{AT&T} @command{troff}. + +@item -d@var{c}@var{text} +@itemx -d@var{string}=@var{text} +Define @code{roff} string @var{c} or @var{string} as@tie{}@var{t} or +@var{text}. @var{c}@tie{}must be one character; @var{string} can be +of arbitrary length. Such string assignments happen before any macro +file is loaded, including the startup file. Due to @code{getopt_long} +limitations, @var{c}@tie{}cannot be, and @var{string} cannot contain, an +equals sign, even though that is a valid character in a @code{roff} +identifier. + +@item -D@var{enc} +Set fallback input encoding used by @command{preconv} to @var{enc}; +implies @option{-k}. + +@item -e +Run @command{geqn} preprocessor. + +@item -E +Inhibit @command{gtroff} error messages. This option does @emph{not} +suppress messages sent to the standard error stream by documents or +macro packages using @code{tm} or related requests. + +@item -f@var{fam} +Use @var{fam} as the default font family. @xref{Font Families}. + +@item -F@var{dir} +Search in directory @file{@var{dir}} for the selected output device's +directory of device and font description files. See the description of +@env{GROFF_FONT_PATH} in @ref{Environment} below for the default search +locations and ordering. + +@item -g +Run @command{ggrn} preprocessor. + +@item -G +Run @command{grap} preprocessor; implies @option{-p}. + +@item -h +Display a usage message and exit. + +@item -i +Read the standard input after all the named input files have been +processed. + +@item -I@var{dir} +Search the directory @var{dir} for files named in several contexts; +implies @option{-g} and @option{-s}. + +@itemize +@item +@command{gsoelim} replaces @code{so} requests with the contents of their +file name arguments. + +@item +@command{gtroff} searches for files named as operands in its command +line and as arguments to @code{psbb}, @code{so}, and @code{soquiet} +requests. + +@item +Output drivers may search for files; for instance, @command{grops} looks +for files named in @samp{\X'ps: import @r{@dots{}}'}, @samp{\X'ps: file +@r{@dots{}}'}, and @samp{\X'pdf: pdfpic @r{@dots{}}'} device control +escape sequences. +@end itemize + +This option may be specified more than once; the directories are +searched in the order specified. If you want to search the current +directory before others, add @samp{-I .} at the desired place. The +current working directory is otherwise searched last. @option{-I} works +similarly to, and is named for, the ``include'' option of Unix C +compilers. + +@option{-I} options are passed to @command{gsoelim}, @command{gtroff}, +and output drivers; with the flag letter changed to @option{-M}, they +are also passed to @command{ggrn}. + +@item -j +Run @command{gchem} preprocessor. Implies @option{-p}. + +@item -k +Run @command{preconv} preprocessor. Refer to its man page for its +behavior if neither of @command{groff}'s @option{-K} or @option{-D} +options is also specified. + +@item -K@var{enc} +Set input encoding used by @command{preconv} to @var{enc}; implies +@option{-k}. + +@item -l +Send the output to a spooler for printing. The @code{print} directive +in the device description file specifies the default command to be used; +see @ref{Device and Font Description Files}. +@c XXX: This document is not parameterized in configuration variables. +@c If no such directive is present for the output device, +@c .ie '@PSPRINT@'' \{\ +@c this option is ignored. +@c .\} +@c .el \{\ +@c output is piped to +@c .MR @PSPRINT@ 1 . +@c .\} +See options @option{-L} and @option{-X}. + +@item -L@var{arg} +Pass @var{arg} to the print spooler program. If multiple @var{arg}s are +required, pass each with a separate @option{-L} option. @command{groff} +does not prefix an option dash to @var{arg} before passing it to the +spooler program. + +@item -m@var{name} +Process the file @file{@var{name}.tmac} prior to any input files. +If not found, @file{tmac.@var{name}} is attempted. @var{name} +(in both arrangements) is presumed to be a macro file; see the +description of @env{GROFF_TMAC_PATH} in @ref{Environment} below for the +default search locations and ordering. This option and its argument are +also passed to @command{geqn}, @command{grap}, and @command{ggrn}. + +@item -M@var{dir} +Search directory @file{@var{dir}} for macro files; see the description +of @env{GROFF_TMAC_PATH} in @ref{Environment} below for the default +search locations and ordering. This option and its argument are also +passed to @command{geqn}, @command{grap}, and @command{ggrn}. + +@item -n@var{num} +Number the first page @var{num}. + +@item -N +Prohibit newlines between @code{eqn} delimiters:@: pass @option{-N} to +@command{geqn}. + +@item -o@var{list} +@cindex print current page register (@code{.P}) +Output only pages in @var{list}, which is a comma-separated list of page +ranges; @samp{@var{n}} means page@tie{}@var{n}, @samp{@var{m}-@var{n}} +means every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}} means +every page up to@tie{}@var{n}, @samp{@var{n}-} means every page from +@var{n}@tie{}on. @command{gtroff} stops processing and exits after +formatting the last page enumerated in @var{list}. + +@item -p +Run @command{gpic} preprocessor. + +@item -P@var{arg} +Pass @var{arg} to the postprocessor. If multiple @var{arg}s are +required, pass each with a separate @option{-P} option. @command{groff} +does not prefix an option dash to @var{arg} before passing it to the +postprocessor. + +@item -r@var{c}@var{numeric-expression} +@itemx -r@var{register}=@var{expr} +Set @code{roff} register@tie{}@var{c} or @var{register} to the value +@var{numeric-expression} (@pxref{Numeric Expressions}). +@var{c}@tie{}must be one character; @var{register} can be of arbitrary +length. Such register assignments happen before any macro file is +loaded, including the startup file. Due to @code{getopt_long} +limitations, @var{c}@tie{}cannot be, and @var{register} cannot contain, +an equals sign, even though that is a valid character in a @code{roff} +identifier. + +@item -R +Run @command{grefer} preprocessor. No mechanism is provided for passing +arguments to @command{grefer} because most @command{grefer} options have +equivalent language elements that can be specified within the document. + +@pindex troffrc +@pindex troffrc-end +@command{gtroff} also accepts a @option{-R} option, which is not +accessible via @command{groff}. This option prevents the loading of the +@file{troffrc} and @file{troffrc-end} files. + +@item -s +Run @command{gsoelim} preprocessor. + +@item -S +@cindex @code{open} request, and safer mode +@cindex @code{opena} request, and safer mode +@cindex @code{pso} request, and safer mode +@cindex @code{sy} request, and safer mode +@cindex @code{pi} request, and safer mode +@cindex safer mode +@cindex mode, safer +Operate in ``safer'' mode; see @option{-U} below for its opposite. For +security reasons, safer mode is enabled by default. + +@item -t +Run @command{gtbl} preprocessor. + +@item -T@var{dev} +Direct @command{gtroff} to format the input for the output device +@var{dev}. @command{groff} then calls an output driver to convert +@command{gtroff}'s output to a form appropriate for @var{dev}. The +following output devices are available. + +@table @code +@item ps +For PostScript printers and previewers. + +@item pdf +For @acronym{PDF} viewers or printers. + +@item dvi +For @TeX{} DVI format. + +@item X75 +For a 75@dmn{dpi} X11 previewer. + +@item X75-12 +For a 75@dmn{dpi} X11 previewer with a 12-point base font in the +document. + +@item X100 +For a 100@dmn{dpi} X11 previewer. + +@item X100-12 +For a 100@dmn{dpi} X11 previewer with a 12-point base font in the +document. + +@item ascii +@cindex encoding, output, @acronym{ASCII} +@cindex encoding, output, ISO@tie{}646 +@cindex @acronym{ASCII} output encoding +@cindex ISO@tie{}646 output encoding +@cindex output encoding, @acronym{ASCII} +@cindex output encoding, ISO@tie{}646 +For typewriter-like devices using the (7-bit) @acronym{ASCII} +(ISO@tie{}646) character set. + +@item latin1 +@cindex encoding, output, @w{Latin-1} (ISO @w{8859-1}) +@cindex @w{Latin-1} (ISO @w{8859-1}) output encoding +@cindex ISO @w{8859-1} (@w{Latin-1}) output encoding +@cindex output encoding, @w{Latin-1} (ISO @w{8859-1}) +For typewriter-like devices that support the @w{Latin-1} +(ISO@tie{}@w{8859-1}) character set. + +@item utf8 +@cindex encoding, output, @w{UTF-8} +@cindex @w{UTF-8} output encoding +@cindex output encoding, @w{UTF-8} +For typewriter-like devices that use the Unicode (ISO@tie{}10646) +character set with @w{UTF-8} encoding. + +@item cp1047 +@cindex encoding, output, @acronym{EBCDIC} +@cindex @acronym{EBCDIC} output encoding +@cindex output encoding, @acronym{EBCDIC} +@cindex encoding, output, code page 1047 +@cindex code page 1047 output encoding +@cindex output encoding, code page 1047 +@cindex IBM code page 1047 output encoding +@cindex CCSID 1047 output encoding (EBCDIC) +For typewriter-like devices that use the @acronym{EBCDIC} encoding IBM +code page 1047. + +@item lj4 +For HP LaserJet4-compatible (or other PCL5-compatible) printers. + +@item lbp +For Canon @acronym{CaPSL} printers (@w{LBP-4} and @w{LBP-8} series laser +printers). + +@pindex pre-grohtml +@pindex post-grohtml +@cindex @code{grohtml}, the program +@item html +@itemx xhtml +To produce @acronym{HTML} and @acronym{XHTML} output, respectively. +This driver consists of two parts, a preprocessor +(@command{pre-grohtml}) and a postprocessor (@command{post-grohtml}). +@end table + +@cindex output device name string (@code{.T}) +@cindex output device usage register (@code{.T}) +The predefined GNU @code{troff} string @code{.T} contains the name of +the output device; the read-only register @code{.T} is set to@tie{}1 if +this option is used (which is always true if @command{groff} is used to +call GNU @command{troff}). @xref{Built-in Registers}. + +The postprocessor to be used for a device is specified by the +@code{postpro} command in the device description file. (@xref{Device +and Font Description Files}.) This can be overridden with the +@option{-X} option. + +@item -U +@cindex mode, unsafe +@cindex unsafe mode +Operate in @dfn{unsafe mode}, which enables the @code{open}, +@code{opena}, @code{pi}, @code{pso}, and @code{sy} requests. These +requests are disabled by default because they allow an untrusted input +document to write to arbitrary file names and run arbitrary commands. +This option also adds the current directory to the macro package search +path; see the @option{-m} option above. @option{-U} is passed to +@command{gpic} and @command{gtroff}. + +@item -v +Write version information for @command{groff} and all programs run by it +to the standard output stream; that is, the given command line is +processed in the usual way, passing @option{-v} to the formatter and any +pre- or postprocessors invoked. + +@item -V +Output the pipeline that would be run by @command{groff} +(as a wrapper program) to the standard output stream, but do not execute +it. If given more than once, the pipeline is both written to the +standard error stream and run. + +@item -w@var{category} +Enable warnings in @var{category}. Categories are listed in +@ref{Warnings}. + +@item -W@var{category} +Inhibit warnings in @var{category}. Categories are listed in +@ref{Warnings}. + +@item -X +Use @command{gxditview} instead of the usual postprocessor to (pre)view +a document on an X11 display. Combining this option with +@option{-Tps} uses the font metrics of the PostScript device, whereas +the @option{-TX75} and @option{-TX100} options use the metrics of X11 +fonts. + +@item -z +Suppress formatted output from @command{gtroff}. + +@item -Z +Disable postprocessing. @command{gtroff} output will appear on the +standard output stream (unless suppressed with @option{-z}; see +@ref{gtroff Output} for a description of this format. +@end table + + +@c ===================================================================== + +@node Environment, Macro Directories, Groff Options, Invoking groff +@section Environment +@cindex environment variables +@cindex variables in environment + +There are also several environment variables (of the operating system, +not within @code{gtroff}) that can modify the behavior of @code{groff}. + +@table @code +@item GROFF_BIN_PATH +@tindex GROFF_BIN_PATH@r{, environment variable} +This search path, followed by @code{PATH}, is used for commands executed +by @code{groff}. + +@item GROFF_COMMAND_PREFIX +@tindex GROFF_COMMAND_PREFIX@r{, environment variable} +@cindex command prefix +@cindex prefix, for commands +If this is set to@tie{}@var{X}, then @command{groff} runs +@command{@var{X}troff} instead of @command{gtroff}. This also applies +to @command{tbl}, @command{pic}, @command{eqn}, @command{grn}, +@command{chem}, @command{refer}, and @command{soelim}. It does not +apply to @command{grops}, @command{grodvi}, @command{grotty}, +@command{pre-grohtml}, @command{post-grohtml}, @command{preconv}, +@command{grolj4}, @command{gropdf}, and @command{gxditview}. + +The default command prefix is determined during the installation +process. If a non-GNU @code{troff} system is found, prefix @samp{g} is +used, none otherwise. + +@item GROFF_ENCODING +@tindex GROFF_ENCODING@r{, environment variable} +The value of this variable is passed to the @code{preconv} +preprocessor's @option{-e} option to select the character encoding of +input files. This variable's existence implies the @code{groff} option +@option{-k}. If set but empty, @code{groff} calls @code{preconv} +without an @option{-e} option. @code{groff}'s @option{-K} option +overrides @env{GROFF_ENCODING}. See the @cite{preconv@r{(7)}} man page; +type @samp{man preconv} at the command line to view it. + +@item GROFF_FONT_PATH +@tindex GROFF_FONT_PATH@r{, environment variable} +A list of directories in which to seek the selected output device's +directory of device and font description files. GNU @code{troff} +will search directories given as arguments to any specified @option{-F} +options before these, and a built-in list of directories after them. +@xref{Font Directories} and the @cite{troff@r{(1)}} or +@cite{gtroff@r{(1)}} man pages. + +@item GROFF_TMAC_PATH +@tindex GROFF_TMAC_PATH@r{, environment variable} +A list of directories in which to seek macro files. GNU @code{troff} +will search directories given as arguments to any specified @option{-M} +options before these, and a built-in list of directories after them. +@xref{Macro Directories} and the @cite{troff@r{(1)}} or +@cite{gtroff@r{(1)}} man pages. + +@item GROFF_TMPDIR +@tindex GROFF_TMPDIR@r{, environment variable} +@tindex TMPDIR@r{, environment variable} +The directory in which @code{groff} creates temporary files. If this is +not set and @env{TMPDIR} is set, temporary files are created in that +directory. Otherwise temporary files are created in a system-dependent +default directory (on Unix and GNU/Linux systems, this is usually +@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and +@code{post-grohtml} can create temporary files in this directory. + +@item GROFF_TYPESETTER +@tindex GROFF_TYPESETTER@r{, environment variable} +Sets the default output device. If empty or not set, a build-time +default (often @code{ps}) is used. The @option{-T@var{dev}} option +overrides @env{GROFF_TYPESETTER}. + +@item SOURCE_DATE_EPOCH +@tindex SOURCE_DATE_EPOCH@r{, environment variable} +A timestamp (expressed as seconds since the Unix epoch) to use as the +output creation timestamp in place of the current time. The time is +converted to human-readable form using @cite{localtime@r{(3)}} when the +formatter starts up and stored in registers usable by documents and +macro packages (@pxref{Built-in Registers}). + +@item TZ +@tindex TZ@r{, environment variable} +The time zone to use when converting the current time (or value of +@env{SOURCE_DATE_EPOCH}) to human-readable form; see +@cite{tzset@r{(3)}}. +@end table + +MS-DOS and MS-Windows ports of @code{groff} use semicolons, rather than +colons, to separate the directories in the lists described above. + + +@c ===================================================================== + +@node Macro Directories, Font Directories, Environment, Invoking groff +@section Macro Directories +@cindex macro directories +@cindex directories for macros +@cindex searching macros +@cindex macros, searching + +A macro file must have a name in the form @code{@var{name}.tmac} or +@code{tmac.@var{name}} and be placed in a @dfn{tmac directory} to be +found by the @option{-m@var{name}} command-line option.@footnote{The +@code{mso} request does not have these limitations. @xref{I/O}.} +@cindex tmac, directory +@cindex directory, for tmac files +@cindex tmac, path +@cindex path, for tmac files +@cindex locating macro files +@cindex macro file search path +@cindex file, macro, search path +@cindex locating macro packages +@cindex macro package search path +@cindex package, macro, search path +Together, these directories constitute the @dfn{tmac path}. Each +directory is searched in the following order until the desired macro +file is found or the list is exhausted. + +@itemize @bullet +@item +Directories specified with GNU @code{troff}'s or @code{groff}'s +@option{-M} command-line option. + +@item +@tindex GROFF_TMAC_PATH@r{, environment variable} +Directories listed in the @env{GROFF_TMAC_PATH} environment variable. + +@item +@cindex safer mode +@cindex mode, safer +@cindex unsafe mode +@cindex mode, unsafe +@cindex current directory +@cindex directory, current +The current working directory (only if in unsafe mode using the +@option{-U} command-line option). + +@item +@cindex home directory +@cindex directory, home +The user's home directory, @env{HOME}. + +@item +@cindex site-local directory +@cindex directory, site-local +@cindex platform-specific directory +@cindex directory, platform-specific +A platform-dependent directory, a site-local (platform-independent) +directory, and the main @slanted{tmac} directory. The locations +corresponding to your installation are listed in section ``Environment'' +of @cite{gtroff@r{(1)}}. If not otherwise configured, they are as +follows. + +@Example +/usr/local/lib/groff/site-tmac +/usr/local/share/groff/site-tmac +/usr/local/share/groff/1.23.0/tmac +@endExample + +@noindent +The foregoing assumes that the version of @code{groff} is 1.23.0, and +that the installation prefix was @file{/usr/local}. It is possible to +fine-tune these locations during the source configuration process. +@end itemize + + +@c ===================================================================== + +@node Font Directories, Paper Format, Macro Directories, Invoking groff +@section Font Directories +@cindex font directories +@cindex directories for fonts +@cindex searching fonts +@cindex fonts, searching + +@code{groff} enforces few restrictions on how font description files are +named. For its family/style mechanism to work (@pxref{Font Families}), +the names of fonts within a family should start with the family name, +followed by the style. For example, the Times family uses @samp{T} for +the family name and @samp{R}, @samp{B}, @samp{I}, and @samp{BI} to +indicate the styles `roman', `bold', `italic', and `bold italic', +respectively. Thus the final font names are @samp{TR}, @samp{TB}, +@samp{TI}, and @samp{TBI}. + +@cindex font path +@cindex path, for font files +Font description files are kept in @dfn{font directories}, which +together constitute the @dfn{font path}. The search procedure +always appends the directory @code{dev}@var{name}, where @var{name} is +the name of the output device. Assuming @TeX{} DVI output, and +@file{/foo/bar} as a font directory, the font description files for +@command{grodvi} must be in @file{/foo/bar/devdvi}. +Each directory in the font path is searched in the following order until +the desired font description file is found or the list is exhausted. + +@itemize @bullet +@item +Directories specified with GNU @code{troff}'s or @code{groff}'s +@option{-f} command-line option. All output drivers (and some +preprocessors) support this option as well, because they require +information about the glyphs to be rendered in the document. + +@item +@tindex GROFF_FONT_PATH@r{, environment variable} +Directories listed in the @env{GROFF_FONT_PATH} environment variable. + +@item +@cindex site-local directory +@cindex directory, site-local +A site-local directory and the main font description directory. +The locations corresponding to your installation are listed in section +``Environment'' of @cite{gtroff@r{(1)}}. If not otherwise configured, +they are as follows. + +@Example +/usr/local/share/groff/site-font +/usr/local/share/groff/1.23.0/font +@endExample + +@noindent +The foregoing assumes that the version of @code{groff} is 1.23.0, and +that the installation prefix was @file{/usr/local}. It is possible to +fine-tune these locations during the source configuration process. +@end itemize + + +@c ===================================================================== + +@node Paper Format, Invocation Examples, Font Directories, Invoking groff +@section Paper Format +@cindex paper format +@cindex format, paper +@cindex paper size +@cindex size, paper +@cindex landscape page orientation +@cindex orientation, landscape +@cindex page orientation, landscape + +In @code{groff}, the page dimensions for the formatter GNU @code{troff} +and for output devices are handled separately. @xref{Page Layout}, for +vertical manipulation of the page size, and @xref{Line Layout}, for +horizontal changes. +@pindex papersize.tmac +@pindex troffrc +The @file{papersize} macro package, normally loaded by @file{troffrc} at +startup, provides an interface for configuring page dimensions by +convenient names, like @samp{letter} or @samp{a4}; see +@cite{groff_tmac@r{(5)}}. The default used by the formatter depends on +its build configuration, but is usually one of the foregoing, as +geographically appropriate. +@c groff(1), being generated, says what the default is. + +It is up to each macro package to respect the page dimensions configured +in this way. + +For each output device, the size of the output medium can be set in its +@file{DESC} file. Most output drivers also recognize a command-line +option @option{-p} to override the default dimensions and an option +@option{-l} to use landscape orientation. @xref{DESC File Format}, for +a description of the @code{papersize} keyword, which takes an argument +of the same form as @option{-p}. The output driver's man page, such as +@cite{grops@r{(1)}}, may also be helpful. + +@code{groff} uses the command-line option @option{-P} to pass options to +postprocessors; for example, use the following for PostScript output on +A4 paper in landscape orientation. + +@Example +groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps +@endExample + + +@c ===================================================================== + +@c BEGIN Keep parallel with groff(1), section "Examples". +@node Invocation Examples, , Paper Format, Invoking groff +@section Invocation Examples +@cindex invocation examples +@cindex examples of invocation + +@code{roff} systems are best known for formatting man pages. Once a +@command{man} librarian program has located a man page, it may execute +a @code{groff} command much like the following. + +@Example +groff -t -man -Tutf8 /usr/share/man/man1/groff.1 +@endExample + +The librarian will also pipe the output through a pager, which might not +interpret the SGR terminal escape sequences @command{groff} emits for +boldface, underlining, or italics; see the @cite{grotty@r{(1)}} man page +for a discussion. + +To process a @code{roff} input file using the preprocessors +@command{gtbl} and @command{gpic} and the @file{me} macro package in the +way to which AT&T @code{troff} users were accustomed, one would type (or +script) a pipeline. + +@Example +gpic foo.me | gtbl | gtroff -me -Tutf8 | grotty +@endExample + +Using @command{groff}, this pipe can be shortened to an equivalent +command. + +@Example +groff -p -t -me -T utf8 foo.me +@endExample + +An even easier way to do this is to use @command{grog} to guess the +preprocessor and macro options and execute the result by using the +command substitution feature of the shell. + +@Example +$(grog -Tutf8 foo.me) +@endExample + +Each command-line option to a postprocessor must be specified with any +required leading dashes @samp{-} +@c No GNU roff postprocessor uses long options for anything except +@c --help or --version. +@c or @samp{--} +@c XXX: grolbp does. +because @command{groff} passes the arguments as-is to the postprocessor; +this permits arbitrary arguments to be transmitted. For example, to +pass a title to the @command{gxditview} postprocessor, +the shell commands + +@Example +groff -X -P -title -P 'trial run' mydoc.t +@endExample + +@noindent +and + +@Example +groff -X -Z mydoc.t | gxditview -title 'trial run' - +@endExample + +@noindent +are equivalent. +@c END Keep parallel with groff(1), section "Examples". + + + +@c ===================================================================== +@c ===================================================================== + +@node Tutorial for Macro Users, Major Macro Packages, Invoking groff, Top +@chapter Tutorial for Macro Users +@cindex tutorial for macro users +@cindex macros, tutorial for users +@cindex user's tutorial for macros +@cindex user's macro tutorial + +Most users of the @code{roff} language employ a macro package to format +their documents. Successful macro packages ease the composition +process; their users need not have mastered the full formatting +language, nor understand features like diversions, traps, and +environments. This chapter aims to familiarize you with basic concepts +and mechanisms common to many macro packages (like ``displays''). If +you prefer a meticulous and comprehensive presentation, try @ref{GNU +troff Reference} instead. + +@menu +* Basics:: +* Common Features:: +@end menu + + +@c ===================================================================== + +@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users +@section Basics +@cindex basics of macro package usage +@cindex macro package usage, basics of + +Let us first survey some basic concepts necessary to use a macro package +fruitfully.@footnote{The remainder of this chapter is based on +@cite{Writing Papers with nroff using -me} by Eric@tie{}P.@: Allman, +which is distributed with @code{groff} as @file{meintro.me}.} +References are made throughout to more detailed information. + +GNU @code{troff} reads an input file prepared by the user and outputs a +formatted document suitable for publication or framing. The input +consists of text, or words to be printed, and embedded commands +(@slanted{requests} and @slanted{escape sequences}), which tell GNU +@code{troff} how to format the output. @xref{Formatter Instructions}. + +The word @slanted{argument} is used in this chapter to mean a word or +number that appears on the same line as a request, and which modifies +the meaning of that request. For example, the request + +@Example +.sp +@endExample + +@noindent +spaces one line, but + +@Example +.sp 4 +@endExample + +@noindent +spaces four lines. The number@tie{}4 is an argument to the @code{sp} +request, which says to space four lines instead of one. Arguments are +separated from the request and from each other by spaces (@emph{not} +tabs). @xref{Invoking Requests}. + +The primary function of GNU @code{troff} is to collect words from input +lines, fill output lines with those words, adjust the line to the +right-hand margin by widening spaces, and output the result. For +example, the input: + +@Example +Now is the time +for all good men +to come to the aid +of their party. +Four score and seven +years ago, etc. +@endExample + +@noindent +is read, packed onto output lines, and justified to produce: + +@Example + @result{} Now is the time for all good men to come to the aid of + @result{} their party. Four score and seven years ago, etc. +@endExample + +Sometimes a new output line should be started even though the current +line is not yet full---for example, at the end of a paragraph. To do +this it is possible to force a @slanted{break}, starting a new output +line. Some requests cause a break automatically, as do (normally) blank +input lines and input lines beginning with a space or tab. + +Not all input lines are @slanted{text lines}---words to be formatted. +Some are @slanted{control lines} that tell a macro package (or GNU +@code{troff} directly) how to format the text. Control lines start with +a dot (@samp{.}) or an apostrophe (@samp{'}) as the first character, and +can be followed by a @slanted{macro call}. + +The formatter also does more complex things, such as automatically +numbering pages, skipping over page boundaries, putting footnotes in the +correct place, and so forth. + +Here are a few hints for preparing text for input to GNU @code{troff}. + +@itemize @bullet +@item +First, keep the input lines short. Short input lines are easier to +edit, and GNU @code{troff} packs words onto longer lines anyhow. + +@item +In keeping with this, it is helpful to begin a new line after every +comma or phrase, since common corrections are to add or delete sentences +or phrases. + +@item +End each sentence with two spaces---or better, start each sentence on a +new line. GNU @code{troff} recognizes characters that usually end a +sentence, and inserts inter-sentence space accordingly. + +@item +Do not hyphenate words at the end of lines---GNU @code{troff} is smart +enough to hyphenate words as needed, but is not smart enough to take +hyphens out and join a word back together. Also, words such as +``mother-in-law'' should not be broken over a line, since then a space +can occur where not wanted, such as ``@w{mother- in}-law''. +@end itemize + +We offer further advice in @ref{Input Conventions}. + +@cindex vertical spacing (introduction) +@cindex spacing, vertical (introduction) +GNU @code{troff} permits alteration of the distance between lines of +text. This is termed @slanted{vertical spacing} and is expressed in the +same units as the type size---the point. The default is 10-point type +on 12-point spacing. To get @slanted{double-spaced} text you would set +the vertical spacing to 24 points. Some, but not all, macro packages +expose a macro or register to configure the vertical spacing. + +A number of requests allow you to change the way the output is arranged +on the page, sometimes called the @slanted{layout} of the output page. +Most macro packages don't supply macros for performing these (at least +not without performing other actions besides), as they are such basic +operations. The macro packages for writing man pages, @file{man} and +@file{mdoc}, don't encourage explicit use of these requests at all. + +@cindex spacing (introduction) +The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank +space. @var{N}@tie{}can be omitted (skipping a single line) or can +be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for +@var{N}@tie{}centimeters). For example, the input: + +@Example +.sp 1.5i +My thoughts on the subject +.sp +@endExample + +@noindent +leaves one and a half inches of space, followed by the line ``My +thoughts on the subject'', followed by a single blank line (more +measurement units are available; see @ref{Measurements}). + +If you seek precision in spacing, be advised when using a macro package +that it might not honor @code{sp} requests as you expect; it can use a +formatter feature called @slanted{no-space mode} to prevent excess space +from accumulating. Macro packages typically offer registers to control +spacing between paragraphs, before section headings, and around displays +(discussed below); use these facilities preferentially. +@xref{Manipulating Spacing}. + +@cindex centering lines (introduction) +@cindex lines, centering (introduction) +Text lines can be centered by using the @code{ce} request. The line +after @code{ce} is centered (horizontally) on the page. To center more +than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number +of lines to center), followed by the @var{N}@tie{}lines. To center many +lines without counting them, type: + +@Example +.ce 1000 +lines to center +.ce 0 +@endExample + +@noindent +The @w{@samp{.ce 0}} request tells GNU @code{troff} to center zero more +lines, in other words, stop centering. + +@cindex right-aligning lines (introduction) +@cindex lines, right-aligning (introduction) +@cindex right-justifying lines (introduction) +@cindex lines, right-justifying (introduction) +GNU @code{troff} also offers the @code{rj} request for right-aligning +text. It works analogously to @code{ce} and is convenient for setting +epigraphs. + +@cindex page break (introduction) +@cindex break, page (introduction) +The @code{bp} request starts a new page; this necessarily implies an +ordinary (line) break. + +@cindex break (introduction) +@cindex line break (introduction) +All of these requests cause a break; that is, they always start a new +line. To start a new line without performing any other action, use +@code{br}. If you invoke them with the apostrophe @samp{'}, the +@slanted{no-break control character}, the (initial) break they normally +perform is suppressed. @samp{'br} does nothing. + + +@c ===================================================================== + +@node Common Features, , Basics, Tutorial for Macro Users +@section Common Features +@cindex common features +@cindex features, common + +GNU @code{troff} provides low-level operations for formatting a +document. Many routine operations are undertaken in nearly all +documents that require a series of such primitive operations to be +performed. These common tasks are grouped into @slanted{macros}, which +are then collected into a @slanted{macro package}. + +Macro packages come in two varieties:@: ``major'' or ``full-service'' +ones that manage page layout, and ``minor'' or ``auxiliary'' ones that +do not, instead fulfilling narrow, specific tasks. Find a list in the +@cite{groff_tmac@r{(5)}} man page. Type @samp{man groff_tmac} at the +command line to view it. + +We survey several capabilities of full-service macro package below. +Each package employs its own macros to exercise them. For details, +consult its man page or, for @file{ms}, see @ref{ms}. + +@menu +* Paragraphs:: +* Sections and Chapters:: +* Headers and Footers:: +* Page Layout Adjustment:: +* Displays and Keeps:: +* Footnotes and Endnotes:: +* Table of Contents:: +* Indexing:: +* Document Formats:: +* Columnation:: +* Font and Size Changes:: +* Predefined Text:: +* Preprocessor Support:: +* Configuration and Customization:: +@end menu + +@c --------------------------------------------------------------------- + +@node Paragraphs, Sections and Chapters, Common Features, Common Features +@subsection Paragraphs +@cindex paragraphs + +Paragraphs can be separated and indented in various ways. Some start +with a blank line and have a first-line indentation, like most of the +ones in this manual. Block paragraphs omit the indentation. + +@Example + @result{} Some men look at constitutions with sanctimonious + @result{} reverence, and deem them like the ark of the + @result{} covenant, too sacred to be touched. +@endExample + +@cindex tags, paragraph +@cindex tagged paragraphs +@cindex lists +@noindent +We also frequently encounter @slanted{tagged} paragraphs, which begin +with a tag or label at the left margin and indent the remaining text. + +@Example + @result{} one This is the first paragraph. Notice how the + @result{} first line of the resulting paragraph lines + @result{} up with the other lines in the paragraph. +@endExample + +@noindent +If the tag is too wide for the indentation, the line is broken. + +@Example + @result{} longlabel + @result{} The label does not align with the subsequent + @result{} lines, but they align with each other. +@endExample + +@noindent +A variation of the tagged paragraph is the itemized or enumerated +paragraph, which might use punctuation or a digit for a tag, +respectively. These are frequently used to construct lists. + +@Example + @result{} o This list item starts with a bullet. When + @result{} producing output for a device using the ASCII + @result{} character set, an 'o' is formatted instead. +@endExample + +@noindent +Often, use of the same macro without a tag continues such a discussion. + +@Example + @result{} -xyz This option is recognized but ignored. + @result{} + @result{} It had a security hole that we don't discuss. +@endExample + +@c --------------------------------------------------------------------- + +@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features +@subsection Sections and Chapters + +The simplest kind of section heading is unnumbered, set in a bold or +italic style, and occupies a line by itself. Others possess +automatically numbered multi-level headings and/or different typeface +styles or sizes at different levels. More sophisticated macro packages +supply macros for designating chapters and appendices. + +@c --------------------------------------------------------------------- + +@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features +@subsection Headers and Footers + +@slanted{Headers} and @slanted{footers} occupy the top and bottom of +each page, respectively, and contain data like the page number and the +article or chapter title. Their appearance is not affected by the +running text. Some packages allow for different titles on even- and +odd-numbered pages (for printed, bound material). + +Headers and footers are together called @slanted{titles}, and comprise +three parts:@: left-aligned, centered, and right-aligned. A @samp{%} +character appearing anywhere in a title is automatically replaced by the +page number. @xref{Page Layout}. + +@c --------------------------------------------------------------------- + +@node Page Layout Adjustment, Displays and Keeps, Headers and Footers, Common Features +@subsection Page Layout + +Most macro packages let the user specify the size of the page margins. +The top and bottom margins are typically handled differently than the +left and right margins; the latter two are derived from the +@slanted{page offset}, @slanted{indentation}, and @slanted{line length}. +@xref{Line Layout}. Commonly, packages support registers to tune these +values. + +@c --------------------------------------------------------------------- + +@node Displays and Keeps, Footnotes and Endnotes, Page Layout Adjustment, Common Features +@subsection Displays and Keeps +@cindex displays + +@slanted{Displays} are sections of text set off from the surrounding +material (typically paragraphs), often differing in indentation, and/or +spacing. Tables, block quotations, and figures are displayed. +Equations and code examples, when not much shorter than an output line, +often are. Lists may or may not be. Packages for setting man pages +support example displays but not keeps. +@c XXX: man, mdoc keep support planned + +@cindex keeps (introduction) +A @slanted{keep} is a group of output lines, often a display, that is +formatted on a single page if possible; it causes a page break to happen +early so as to not interrupt the kept material. + +@cindex keep, floating +@cindex floating keep +@slanted{Floating keeps} can move, or ``float'', relative to the text +around them in the input. They are useful for displays that are +captioned and referred to by name, as with ``See figure@tie{}3''. +Depending on the package, a floating keep appears at the bottom of the +current page if it fits, and at the top of the next otherwise. +Alternatively, floating keeps might be deferred to the end of a section. +Using a floating keep can avoid the large vertical spaces that may +precede a tall keep of the ordinary sort when it won't fit on the page. + +@c --------------------------------------------------------------------- + +@node Footnotes and Endnotes, Table of Contents, Displays and Keeps, Common Features +@subsection Footnotes and Endnotes +@cindex footnotes +@cindex endnotes + +@slanted{Footnotes} and @slanted{endnotes} are forms of delayed +formatting. They are recorded at their points of relevance in +the input, but not formatted there. Instead, a @slanted{mark} cues the +reader to check the ``foot'', or bottom, of the current page, or in the +case of endnotes, an annotation list later in the document. Macro +packages that support these features also supply a means of +automatically numbering either type of annotation. + +@c --------------------------------------------------------------------- + +@node Table of Contents, Indexing, Footnotes and Endnotes, Common Features +@subsection Table of Contents +@cindex table of contents +@cindex contents, table of + +A package may handle a @slanted{table of contents} by directing section +heading macros to save section heading text and the page number where it +occurs for use in a later @slanted{entry} for a table of contents. It +writes the collected entries at the end of the document, once all are +known, upon request. A row of dots (a @slanted{leader}) bridges the +text on the left with its location on the right. Other collections +might work in this manner, providing lists of figures or tables. + +A table of contents is often found at the end of a GNU @code{troff} +document because the formatter processes the document in a single pass. +The @command{gropdf} output driver supports a PDF feature that relocates +pages at the time the document is rendered; see the @cite{gropdf@r{(1)}} +man page. Type @samp{man gropdf} at the command line to view it. + +@c --------------------------------------------------------------------- + +@node Indexing, Document Formats, Table of Contents, Common Features +@subsection Indexing +@cindex index, in macro package + +@pindex makeindex +An index is similar to a table of contents, in that entry labels and +locations must be collected, but poses a greater challenge because it +needs to be sorted before it is output. Here, processing the document +in multiple passes is inescapable, and tools like the @code{makeindex} +program are necessary. + +@c --------------------------------------------------------------------- + +@node Document Formats, Columnation, Indexing, Common Features +@subsection Document Formats +@cindex document formats + +Some macro packages supply stock configurations of certain documents, +like business letters and memoranda. These often also have provision +for a @slanted{cover sheet}, which may be rigid in its format. With +these features, it is even more important to use the package's macros in +preference to the formatter requests presented earlier, where possible. + +@c --------------------------------------------------------------------- + +@node Columnation, Font and Size Changes, Document Formats, Common Features +@subsection Columnation + +Macro packages apart from @file{man} and @file{mdoc} for man page +formatting offer a facility for setting multiple columns on the page. + +@c --------------------------------------------------------------------- + +@node Font and Size Changes, Predefined Text, Columnation, Common Features +@subsection Font and Size Changes + +The formatter's requests and escape sequences for setting the typeface +and size are not always intuitive, so all macro packages provide macros +to make these operations simpler. They also make it more convenient to +change typefaces in the middle of a word and can handle italic +corrections automatically. @xref{Italic Corrections}. + +@c --------------------------------------------------------------------- + +@node Predefined Text, Preprocessor Support, Font and Size Changes, Common Features +@subsection Predefined Text + +Most macro packages supply predefined strings to set prepared text like +the date, or to perform operations like super- and subscripting. + +@c --------------------------------------------------------------------- + +@node Preprocessor Support, Configuration and Customization, Predefined Text, Common Features +@subsection Preprocessor Support + +All macro packages provide support for various preprocessors and may +extend their functionality by defining macros to set their contents in +displays. Examples include @code{TS} and @code{TE} for @command{gtbl}, +@code{EQ} and @code{EN} for @command{geqn}, and @code{PS} and @code{PE} +for @command{gpic}. + +@c --------------------------------------------------------------------- + +@node Configuration and Customization, , Preprocessor Support, Common Features +@subsection Configuration and Customization + +Packages provide means of customizing many of the details of how the +package behaves. These range from setting the default type size to +changing the appearance of section headers. + +@codequotebacktick off +@codequoteundirected off + + + +@c ===================================================================== +@c ===================================================================== + +@node Major Macro Packages, GNU troff Reference, Tutorial for Macro Users, Top +@chapter Macro Packages +@cindex major macro package +@cindex package, macro, major +@cindex macro package, major + +This chapter surveys the ``major'' macro packages that come with +@code{groff}. One, @file{ms}, is presented in detail. + +@cindex full-service macro package +@cindex package, macro, full-service +@cindex macro package, full-service +Major macro packages are also sometimes described as @dfn{full-service} +due to the breadth of features they provide and because more than one +cannot be used by the same document; for example + +@Example +groff -m man foo.man -m ms bar.doc +@endExample + +@noindent +doesn't work. Option arguments are processed before non-option +arguments; the above (failing) sample is thus reordered to + +@Example +groff -m man -m ms foo.man bar.doc +@endExample + +@cindex minor macro package +@cindex package, macro, minor +@cindex macro package, minor +@cindex auxiliary macro package +@cindex package, macro, auxiliary +@cindex macro package, auxiliary +Many auxiliary, or ``minor'', macro packages are also available. They +may in general be used with any full-service macro package and handle a +variety of tasks from character encoding selection, to language +localization, to inlining of raster images. See the +@cite{groff_tmac@r{(5)}} man page for a list. Type @samp{man +groff_tmac} at the command line to view it. + +@menu +* man:: +* mdoc:: +* me:: +* mm:: +* mom:: +* ms:: +@end menu + + +@c ===================================================================== + +@node man, mdoc, Major Macro Packages, Major Macro Packages +@section @file{man} +@cindex manual pages +@cindex man pages +@pindex an.tmac +@pindex man.tmac + +The @code{man} macro package is the most widely used and probably the +most important ever developed for @code{troff}. It is easy to use, and +a vast majority of manual pages (``man pages'') are written in it. + +@code{groff}'s implementation is documented in the +@cite{groff_man@r{(7)}} man page. Type @samp{man groff_man} at the +command line to view it. + +@menu +* Optional man extensions:: +@end menu + +@c --------------------------------------------------------------------- + +@node Optional man extensions, , , man +@subsection Optional @file{man} extensions + +@pindex man.local +Use the file @file{man.local} for local extensions to the @code{man} +macros or for style changes. + +@unnumberedsubsubsec Custom headers and footers +@cindex @code{man} macros, custom headers and footers + +In @code{groff} versions 1.18.2 and later, you can specify custom +headers and footers by redefining the following macros in +@file{man.local}. + +@Defmac {PT, , man} +Control the content of the headers. Normally, the header prints the +command name and section number on either side, and the optional fifth +argument to @code{TH} in the center. +@endDefmac + +@Defmac {BT, , man} +Control the content of the footers. Normally, the footer prints the +page number and the third and fourth arguments to @code{TH}. + +Use the @code{FT} register to specify the footer position. The default +is @minus{}0.5@dmn{i}. +@endDefmac + +@unnumberedsubsubsec Ultrix-specific man macros +@cindex Ultrix-specific @code{man} macros +@cindex @code{man} macros, Ultrix-specific + +@pindex man.ultrix +The @code{groff} source distribution includes a file named +@file{man.ultrix}, containing macros compatible with the Ultrix variant +of @code{man}. Copy this file into @file{man.local} (or use the +@code{mso} request to load it) to enable the following macros. + +@Defmac {CT, @Var{key}, man} +Print @samp{}. +@endDefmac + +@Defmac {CW, , man} +Print subsequent text using a ``constant-width'' (monospaced) typeface +(Courier roman). +@endDefmac + +@Defmac {Ds, , man} +Begin a non-filled display. +@endDefmac + +@Defmac {De, , man} +End a non-filled display started with @code{Ds}. +@endDefmac + +@Defmac {EX, [@Var{indent}], man} +Begin a non-filled display using a monospaced typeface (Courier roman). +Use the optional @var{indent} argument to indent the display. +@endDefmac + +@Defmac {EE, , man} +End a non-filled display started with @code{EX}. +@endDefmac + +@Defmac {G, [@Var{text}], man} +Set @var{text} in Helvetica. If no text is present on the line where +the macro is called, then the text of the next line appears in +Helvetica. +@endDefmac + +@Defmac {GL, [@Var{text}], man} +Set @var{text} in Helvetica oblique. If no text is present on the line +where the macro is called, then the text of the next line appears in +Helvetica Oblique. +@endDefmac + +@Defmac {HB, [@Var{text}], man} +Set @var{text} in Helvetica bold. If no text is present on the line +where the macro is called, then all text up to the next @code{HB} +appears in Helvetica bold. +@endDefmac + +@Defmac {TB, [@Var{text}], man} +Identical to @code{HB}. +@endDefmac + +@Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man} +Set a man page reference in Ultrix format. The @var{title} is in +Courier instead of italic. Optional punctuation follows the section +number without an intervening space. +@endDefmac + +@Defmac {NT, [@code{C}] [@Var{title}], man} +Begin a note. Print the optional @Var{title}, or the word ``Note'', +centered on the page. Text following the macro makes up the body of the +note, and is indented on both sides. If the first argument is @code{C}, +the body of the note is printed centered (the second argument replaces +the word ``Note'' if specified). +@endDefmac + +@Defmac {NE, , man} +End a note begun with @code{NT}. +@endDefmac + +@Defmac {PN, @Var{path} [@Var{punct}], man} +Set the path name in a monospaced typeface (Courier roman), followed by +optional punctuation. +@endDefmac + +@Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man} +If called with two arguments, identical to @code{PN}. If called with +three arguments, set the second argument in a monospaced typeface +(Courier roman), bracketed by the first and third arguments in the +current font. +@endDefmac + +@Defmac {R, , man} +Switch to roman font and turn off any underlining in effect. +@endDefmac + +@Defmac {RN, , man} +Print the string @samp{}. +@endDefmac + +@Defmac {VS, [@code{4}], man} +Start printing a change bar in the margin if the number@tie{}@code{4} is +specified. Otherwise, this macro does nothing. +@endDefmac + +@Defmac {VE, , man} +End printing the change bar begun by @code{VS}. +@endDefmac + +@unnumberedsubsubsec Simple example + +The following example @file{man.local} file alters the @code{SH} macro +to add some extra vertical space before printing the heading. Headings +are printed in Helvetica bold. + +@Example +.\" Make the heading fonts Helvetica +.ds HF HB +. +.\" Put more space in front of headings. +.rn SH SH-orig +.de SH +. if t .sp (u;\\n[PD]*2) +. SH-orig \\$* +.. +@endExample + + +@c ===================================================================== + +@node mdoc, me, man, Major Macro Packages +@section @file{mdoc} +@cindex @code{mdoc} macros + +@code{groff}'s implementation of the BSD @file{doc} package for man +pages is documented in the @cite{groff_mdoc@r{(7)}} man page. Type +@samp{man groff_mdoc} at the command line to view it. + + +@c ===================================================================== + +@node me, mm, mdoc, Major Macro Packages +@section @file{me} +@cindex @code{me} macro package + +@code{groff}'s implementation of the BSD @file{me} macro package is +documented using itself. A tutorial, @file{meintro.me}, and reference, +@file{meref.me}, are available in @code{groff}'s documentation +directory. A @cite{groff_me@r{(7)}} man page is also available and +identifies the installation path for these documents. Type @samp{man +groff_me} at the command line to view it. + +A French translation of the tutorial is available as +@file{meintro_fr.me} and installed parallel to the English version. + + +@c ===================================================================== + +@node mm, mom, me, Major Macro Packages +@section @file{mm} +@cindex @code{mm} macro package + +@code{groff}'s implementation of the @acronym{AT&T} memorandum macro +package is documented in the @cite{groff_mm@r{(7)}} man page. Type +@samp{man groff_mm} at the command line) to view it. + +A Swedish localization of @file{mm} is also available; see +@cite{groff_mmse@r{(7)}}. + + +@c ===================================================================== + +@node mom, ms, mm, Major Macro Packages +@section @file{mom} +@cindex @code{mom} macro package + +The main documentation files for the @file{mom} macros are in +@acronym{HTML} format. Additional, useful documentation is in +@acronym{PDF} format. See the @cite{groff@r{(1)}} man page, section +``Installation Directories'', for their location. + +@itemize @bullet +@item +@file{toc.html} +@noindent +Entry point to the full mom manual. + +@item +@file{macrolist.html} +@noindent +Hyperlinked index of macros with brief descriptions, arranged by +category. + +@item +@file{mom-pdf.pdf} +@noindent +@acronym{PDF} features and usage. +@end itemize + +The mom macros are in active development between @code{groff} releases. +The most recent version, along with up-to-date documentation, is +available at @uref{http://www.schaffter.ca/mom/mom-05.html}. + +The @cite{groff_mom@r{(7)}} man page (type @samp{man groff_mom} at +the command line) contains a partial list of available macros, however +their usage is best understood by consulting the @acronym{HTML} +documentation. + + +@c ===================================================================== + +@codequotebacktick on +@codequoteundirected on + +@node ms, , mom, Major Macro Packages +@section @file{ms} +@cindex @file{ms} macros + +The @file{ms} (``manuscript'') package is suitable for the preparation +of letters, memoranda, reports, and books. These @code{groff} +macros feature cover page and table of contents generation, +automatically numbered headings, several paragraph styles, a variety of +text styling options, footnotes, and multi-column page layouts. +@file{ms} supports the @command{tbl}, @command{eqn}, @command{pic}, and +@command{refer} preprocessors for inclusion of tables, mathematical +equations, diagrams, and standardized bibliographic citations. This +implementation is mostly compatible with the documented interface and +behavior of AT&T Unix Version@tie{}7 @file{ms}. Many extensions from +4.2BSD (Berkeley) +@c Few changes were made in 4.3, Tahoe, Reno, or 4.4. +and Tenth Edition Research Unix have been recreated. + +@menu +* ms Introduction:: +* ms Document Structure:: +* ms Document Control Settings:: +* ms Document Description Macros:: +* ms Body Text:: +* ms Page Layout:: +* Differences from AT&T ms:: +* ms Legacy Features:: +* ms Naming Conventions:: +@end menu + +@c --------------------------------------------------------------------- + +@node ms Introduction, ms Document Structure, ms, ms +@subsection Introduction + +The @file{ms} macros are the oldest surviving package for @code{roff} +systems.@footnote{While manual @emph{pages} are older, early ones used +macros supplanted by the @file{man} package of Seventh Edition Unix +(1979). @file{ms} shipped with Sixth Edition (1975) and was documented +by Mike Lesk in a Bell Labs internal memorandum.} While the @file{man} +package was designed for brief reference documents, the @file{ms} macros +are also suitable for longer works intended for printing and possible +publication. + +@menu +* ms basic information:: +@end menu + +@c --------------------------------------------------------------------- + +@node ms basic information, ms Document Structure, ms Introduction, ms Introduction +@subsubsection Basic information + +@file{ms} documents are plain text files; prepare them with your +preferred text editor. If you're in a hurry to start, know that +@file{ms} needs one of its macros called at the beginning of a document +so that it can initialize. A @dfn{macro} is a formatting instruction to +@file{ms}. Put a macro call on a line by itself. Use @samp{.PP} if you +want your paragraph's first line to be indented, or @samp{.LP} if you +don't. + +After that, start typing normally. It is a good practice to start each +sentence on a new line, or to put two spaces after sentence-ending +punctuation, so that the formatter knows where the sentence boundaries +are. You can separate paragraphs with further paragraphing macros, or +with blank lines, and you can indent with tabs. When you need one of +the features mentioned earlier (@pxref{ms}), return to this part of the +manual. + +Format the document with the @command{groff} command. @command{nroff} +can be useful for previewing. + +@CartoucheExample +$ editor radical.ms +$ nroff -ww -z -ms radical.ms # check for errors +$ nroff -ms radical.ms | less -R +$ groff -T ps -ms radical.ms > radical.ps +$ see radical.ps +@endCartoucheExample + +Our @file{radical.ms} document might look like this. + +@CartoucheExample +.LP +Radical novelties are so disturbing that they tend to be +suppressed or ignored, to the extent that even the +possibility of their existence in general is more often +denied than admitted. + +@arrow{}That's what Dijkstra said, anyway. +@endCartoucheExample + +@file{ms} exposes many aspects of document layout to user control via +@code{groff}'s @dfn{registers} and @dfn{strings}, which store numbers +and text, respectively. Measurements in @code{groff} are expressed with +a suffix called a @dfn{scaling unit}. + +@table @code +@item i +inches + +@item c +centimeters + +@item p +points (1/72 inch) + +@item P +picas (1/6 inch) + +@item v +vees; current vertical spacing + +@item m +ems; width of an ``M'' in the current font + +@item n +ens; one-half em +@end table + +Set registers with the @code{nr} request and strings with the @code{ds} +request. @dfn{Requests} are like macro calls; they go on lines by +themselves and start with the @dfn{control character}, a dot (@code{.}). +The difference is that they directly instruct the formatter program, +rather than the macro package. We'll discuss a few as applicable. It +is wise to specify a scaling unit when setting any register that +represents a length, size, or distance. + +@CartoucheExample +.nr PS 10.5p \" Use 10.5-point type. +.ds FAM P \" Use Palatino font family. +@endCartoucheExample + +@noindent +In the foregoing, we see that @code{\"} begins a comment. This is an +example of an @dfn{escape sequence}, the other kind of formatting +instruction. Escape sequences can appear anywhere. They begin with the +escape character (@code{\}) and are followed by at least one more +character. @file{ms} documents +@c like this one +tend to use only a few of @code{groff}'s many requests and escape +sequences; see @ref{Request Index} and @ref{Escape Sequence Index} or +the @cite{groff@r{(7)}} man page for complete lists. + +@table @code +@item \" +Begin comment; ignore remainder of line. + +@item \n[@var{reg}] +Interpolate value of register @var{reg}. + +@item \*[@var{str}] +Interpolate contents of string @var{str}. + +@item \*@var{s} +abbreviation of @code{\*[@var{s}]}; the name @var{s} must be only one +character + +@item \[@var{char}] +Interpolate glyph of special character named @var{char}. + +@item \& +dummy character + +@item \~ +Insert an unbreakable space that is adjustable like a normal space. + +@item \| +Move horizontally by one-sixth em (``thin space''). +@end table + +Prefix any words that start with a dot @samp{.} or neutral apostrophe +@samp{'} with @code{\&} if they are at the beginning of an input line +(or might become that way in editing) to prevent them from being +interpreted as macro calls or requests. Suffix @samp{.}, @samp{?}, and +@samp{!} with @code{\&} when needed to cancel end-of-sentence detection. + +@CartoucheExample +My exposure was \&.5 to \&.6 Sv of neutrons, said Dr.\& +Wallace after the criticality incident. +@endCartoucheExample + +@c --------------------------------------------------------------------- + +@node ms Document Structure, ms Document Control Settings, ms Introduction, ms +@subsection Document Structure +@cindex @file{ms} macros, general structure + +The @file{ms} macro package expects a certain amount of structure: +a well-formed document contains at least one paragraphing or heading +macro call. Longer documents have a structure as follows. + +@table @strong +@item Document type +Calling the @code{RP} macro at the beginning of your document puts the +document description (see below) on a cover page. Otherwise, @file{ms} +places the information (if any) on the first page, followed immediately +by the body text. Some document types found in other @file{ms} +implementations are specific to @acronym{AT&T} or Berkeley, and are not +supported by @code{groff} @file{ms}. + +@item Format and layout +By setting registers and strings, you can configure your document's +typeface, margins, spacing, headers and footers, and footnote +arrangement. @xref{ms Document Control Settings}. + +@item Document description +A document description consists of any of: a title, one or more authors' +names and affiliated institutions, an abstract, and a date or other +identifier. @xref{ms Document Description Macros}. + +@item Body text +The main matter of your document follows its description (if any). +@file{ms} supports highly structured text consisting of paragraphs +interspersed with multi-level headings (chapters, sections, subsections, +and so forth) and augmented by lists, footnotes, tables, diagrams, and +similar material. @xref{ms Body Text}. + +@item Tables of contents +Macros enable the collection of entries for a table of contents (or +index) as the material they discuss appears in the document. You then +call a macro to emit the table of contents at the end of your document. +The table of contents must necessarily follow the rest of the text since +GNU @code{troff} is a single-pass formatter; it thus cannot determine +the page number of a division of the text until it has been set and +output. Since @file{ms} was designed for the production of hard copy, +the traditional procedure was to manually relocate the pages containing +the table of contents between the cover page and the body text. Today, +page resequencing is more often done in the digital domain. An index +works similarly, but because it typically needs to be sorted after +collection, its preparation requires separate processing. +@end table + +@c --------------------------------------------------------------------- + +@node ms Document Control Settings, ms Document Description Macros, ms Document Structure, ms +@subsection Document Control Settings +@cindex @file{ms} macros, document control settings + +@file{ms} exposes many aspects of document layout to user control via +@code{groff} requests. To use them, you must understand how to define +registers and strings. + +@Defreq {nr, reg value} +Set register @var{reg} to @var{value}. If @var{reg} doesn't exist, GNU +@code{troff} creates it. +@endDefreq + +@Defreq {ds, name contents} +Set string @var{name} to @var{contents}. +@endDefreq + +A list of document control registers and strings follows. For any +parameter whose default is unsatisfactory, define its register or string +before calling any @file{ms} macro other than @code{RP}. + +@unnumberedsubsubsec Margin settings + +@Defmpreg {PO, ms} +Defines the page offset (i.e., the left margin). +@c not in V6 + +Effective: next page. + +Default: Varies by output device and paper format; 1@dmn{i} is used for +typesetters using U.S.@: letter paper, and zero for terminals. +@xref{Paper Format}. +@endDefmpreg + +@Defmpreg {LL, ms} +Defines the line length (i.e., the width of the body text). + +Effective: next paragraph. + +Default: Varies by output device and paper format; 6.5@dmn{i} is used +for typesetters using U.S.@: letter paper (@pxref{Paper Format}) and +65@dmn{n} on terminals. +@endDefmpreg + +@Defmpreg {LT, ms} +Defines the title line length (i.e., the header and footer width). This +is usually the same as @code{LL}, but need not be. + +Effective: next paragraph. + +Default: Varies by output device and paper format; 6.5@dmn{i} is used +for typesetters using U.S.@: letter paper (@pxref{Paper Format}) and +65@dmn{n} on terminals. +@endDefmpreg + +@Defmpreg {HM, ms} +Defines the header margin height at the top of the page. +@c not in V6 + +Effective: next page. + +Default: 1@dmn{i}. +@endDefmpreg + +@Defmpreg {FM, ms} +Defines the footer margin height at the bottom of the page. +@c not in V6 + +Effective: next page. + +Default: 1@dmn{i}. +@endDefmpreg + +@unnumberedsubsubsec Titles (headers, footers) + +@Defmpstr {LH, ms} +Defines the text displayed in the left header position. + +Effective: next header. + +Default: empty. +@endDefmpstr + +@Defmpstr {CH, ms} +Defines the text displayed in the center header position. + +Effective: next header. + +Default: @samp{-\n[%]-}. +@endDefmpstr + +@Defmpstr {RH, ms} +Defines the text displayed in the right header position. + +Effective: next header. + +Default: empty. +@endDefmpstr + +@Defmpstr {LF, ms} +Defines the text displayed in the left footer position. + +Effective: next footer. + +Default: empty. +@endDefmpstr + +@Defmpstr {CF, ms} +Defines the text displayed in the center footer position. + +Effective: next footer. + +Default: empty. +@endDefmpstr + +@Defmpstr {RF, ms} +Defines the text displayed in the right footer position. + +Effective: next footer. + +Default: empty. +@endDefmpstr + +@unnumberedsubsubsec Text settings + +@Defmpreg {PS, ms} +Defines the type size of the body text. + +Effective: next paragraph. + +Default: 10@dmn{p}. +@endDefmpreg + +@Defmpreg {VS, ms} +Defines the vertical spacing (type size plus leading). + +Effective: next paragraph. + +Default: 12@dmn{p}. +@endDefmpreg + +@Defmpreg {HY, ms} +Defines the automatic hyphenation mode used with the @code{hy} request. +Setting @code{HY} to@tie{}0 is equivalent to using the @code{nh} +request. This is a Tenth Edition Research Unix extension. +@c possibly 9th, but definitely not Berkeley + +Effective: next paragraph. + +Default: 6. +@endDefmpreg + +@Defmpstr {FAM, ms} +Defines the font family used to typeset the document. This is a GNU +extension. + +Effective: next paragraph. + +Default: defined by the output device; often @samp{T} (@pxref{ms Body +Text}) +@endDefmpstr + +@unnumberedsubsubsec Paragraph settings + +@Defmpreg {PI, ms} +Defines the indentation amount used by the @code{PP}, @code{IP} (unless +overridden by an optional argument), @code{XP}, and @code{RS} macros. +@c not in V6 + +Effective: next paragraph. + +Default: 5@dmn{n}. +@endDefmpreg + +@Defmpreg {PD, ms} +Defines the space between paragraphs. +@c not in V6 + +Effective: next paragraph. + +Default: 0.3@dmn{v} (1@dmn{v} on low-resolution devices). +@endDefmpreg + +@Defmpreg {QI, ms} +Defines the indentation amount used on both sides of a paragraph set +with the @code{QP} or between the @code{QS} and @code{QE} macros. + +Effective: next paragraph. + +Default: 5@dmn{n}. +@endDefmpreg + +@Defmpreg {PORPHANS, ms} +Defines the minimum number of initial lines of any paragraph that must +be kept together to avoid isolated lines at the bottom of a page. If a +new paragraph is started close to the bottom of a page, and there is +insufficient space to accommodate @code{PORPHANS} lines before an +automatic page break, then a page break is forced before the start of +the paragraph. This is a GNU extension. + +Effective: next paragraph. + +Default: 1. +@endDefmpreg + +@unnumberedsubsubsec Heading settings + +@Defmpreg {PSINCR, ms} +Defines an increment in type size to be applied to a heading at a +lesser depth than that specified in @code{GROWPS}. The value of +@code{PSINCR} should be specified in points with the @dmn{p} scaling +unit and may include a fractional component; for example, @w{@samp{.nr +PSINCR 1.5p}} sets a type size increment of 1.5@dmn{p}. This is a GNU +extension. + +Effective: next heading. + +Default: 1@dmn{p}. +@endDefmpreg + +@Defmpreg {GROWPS, ms} +Defines the heading depth above which the type size increment set by +@code{PSINCR} becomes effective. For each heading depth less than the +value of @code{GROWPS}, the type size is increased by @code{PSINCR}. +Setting @code{GROWPS} to any value less than@tie{}2 disables the +incremental heading size feature. This is a GNU extension. + +Effective: next heading. + +Default: 0. +@endDefmpreg + +@Defmpreg {HORPHANS, ms} +Defines the minimum number of lines of an immediately succeeding +paragraph that should be kept together with any heading introduced by +the @code{NH} or @code{SH} macros. If a heading is placed close to the +bottom of a page, and there is insufficient space to accommodate both +the heading and at least @code{HORPHANS} lines of the following +paragraph, before an automatic page break, then the page break is forced +before the heading. This is a GNU extension. + +Effective: next paragraph. + +Default: 1. +@endDefmpreg + +@Defmpstr {SN-STYLE, ms} +Defines the style used to print numbered headings. @xref{Headings in +ms}. This is a GNU extension. + +Effective: next heading. + +Default: alias of @code{SN-DOT} +@endDefmpstr + +@unnumberedsubsubsec Footnote settings + +@Defmpreg {FI, ms} +Defines the footnote indentation. This is a Berkeley extension. + +Effective: next footnote. + +Default: 2@dmn{n}. +@endDefmpreg + +@Defmpreg {FF, ms} +Defines the format of automatically numbered footnotes, +and those for which the @code{FS} request is given a marker argument, at +the bottom of a column or page. This is a Berkeley extension. +@table @code +@item 0 +Set an automatic number@footnote{defined in @ref{ms Footnotes}} as a +superscript (on typesetter devices) or surrounded by square brackets (on +terminals). The footnote paragraph is indented as with @code{PP} if +there is an @code{FS} argument or an automatic number, and as with +@code{LP} otherwise. This is the default. + +@item 1 +As @code{0}, but set the marker as regular text and follow an +automatic number with a period. + +@item 2 +As @code{1}, but without indentation (like @code{LP}). + +@item 3 +As @code{1}, but set the footnote paragraph with the marker hanging +(like @code{IP}). +@end table + +Effective: next footnote. + +Default: 0. +@endDefmpreg + +@Defmpreg {FPS, ms} +Defines the footnote type size. + +Effective: next footnote. + +Default: @code{\n[PS] - 2p}. +@endDefmpreg + +@Defmpreg {FVS, ms} +Defines the footnote vertical spacing. + +Effective: next footnote. + +Default: @code{\n[FPS] + 2p}. +@endDefmpreg + +@Defmpreg {FPD, ms} +Defines the footnote paragraph spacing. This is a GNU extension. + +Effective: next footnote. + +Default: @code{\n[PD] / 2}. +@endDefmpreg + +@Defmpstr {FR, ms} +Defines the ratio of the footnote line length to the current line +length. This is a GNU extension. + +Effective: next footnote in single-column arrangements, next page +otherwise. + +Default: @code{11/12}. +@endDefmpstr + +@unnumberedsubsubsec Display settings + +@Defmpreg {DD, ms} +Sets the display distance---the vertical spacing before and after a +display, a @code{tbl} table, an @code{eqn} equation, or a @code{pic} +image. This is a Berkeley extension. + +Effective: next display boundary. + +Default: 0.5@dmn{v} (1@dmn{v} on low-resolution devices). +@endDefmpreg + +@Defmpreg {DI, ms} +Sets the default amount by which to indent a display started with +@code{DS} and @code{ID} without arguments, to @samp{.DS@tie{}I} without +an indentation argument, and to equations set with @samp{.EQ@tie{}I}. +This is a GNU extension. + +Effective: next indented display. + +Default: 0.5@dmn{i}. +@endDefmpreg + +@unnumberedsubsubsec Other settings + +@Defmpreg {MINGW, ms} +Defines the default minimum width between columns in a multi-column +document. This is a GNU extension. + +Effective: next page. + +Default: 2@dmn{n}. +@endDefmpreg + +@Defmpreg {TC-MARGIN, ms} +Defines the width of the field in which page numbers are set in a table +of contents entry; the right margin thus moves inboard by this amount. +This is a GNU extension. + +Effective: next @code{PX} call. + +Default: @code{\w'000'} +@endDefmpreg + +@c XXX: Normally we'd have an entry for TC-LEADER here, but it's a +@c special character and we have no custom Texinfo macros for defining +@c (and indexing) these. There would be little point in an index for +@c one item, and the plan is to drop this entire @section from this +@c manual once doc/ms.ms is ready. See Savannah #60061. + +@c --------------------------------------------------------------------- + +@node ms Document Description Macros, ms Body Text, ms Document Control Settings, ms +@subsection Document Description Macros +@cindex @file{ms} macros, document description +@cindex document description macros, [@file{ms}] + +Only the simplest document lacks a title.@footnote{Distinguish a +document title from ``titles'', which are what @code{roff} systems call +headers and footers collectively.} As its level of sophistication (or +complexity) increases, it tends to acquire a date of revision, +explicitly identified authors, sponsoring institutions for authors, and, +at the rarefied heights, an abstract of its content. Define these +data by calling the macros below in the order shown; @code{DA} or +@code{ND} can be called to set the document date (or other identifier) +at any time before (a) the abstract, if present, or (b) its information +is required in a header or footer. Use of these macros is optional, +except that @code{TL} is mandatory if any of @code{RP}, @code{AU}, +@code{AI}, or @code{AB} is called, and @code{AE} is mandatory if +@code{AB} is called. + +@Defmac {RP, [@code{no-repeat-info}] [@code{no-renumber}], ms} +Use the ``report'' (@acronym{AT&T}: ``released paper'') format for your +document, creating a separate cover page. The default arrangement is to +place most of the document description (title, author names and +institutions, and abstract, but not the date) at the top of the first +page. If the optional @code{no-repeat-info} argument is given, +@file{ms} produces a cover page but does not repeat any of its +information subsequently (but see the @code{DA} macro below regarding +the date). Normally, @code{RP} sets the page number following the cover +page to@tie{}1. Specifying the optional @code{no-renumber} argument +suppresses this alteration. Optional arguments can occur in any order. +@code{no} is recognized as a synonym of @code{no-repeat-info} for +@code{AT&T} compatibility. +@endDefmac + +@Defmac {TL, , ms} +Specify the document title. @file{ms} collects text on input lines +following this call into the title until reaching @code{AU}, @code{AB}, +or a heading or paragraphing macro call. +@endDefmac + +@Defmac {AU, , ms} +Specify an author's name. @file{ms} collects text on input lines +following this call into the author's name until reaching @code{AI}, +@code{AB}, another @code{AU}, or a heading or paragraphing macro call. +Call it repeatedly to specify multiple authors. +@endDefmac + +@Defmac {AI, , ms} +Specify the preceding author's institution. An @code{AU} call is +usefully followed by at most one @code{AI} call; if there are more, the +last @code{AI} call controls. @file{ms} collects text on input lines +following this call into the author's institution until reaching +@code{AU}, @code{AB}, or a heading or paragraphing macro call. +@endDefmac + +@Defmac {DA, [@Var{x} @dots{}], ms} +Typeset the current date, or any arguments @var{x}, in the center +footer, and, if @code{RP} is also called, left-aligned at the end of the +description information on the cover page. +@endDefmac + +@Defmac {ND, [@Var{x} @dots{}], ms} +Typeset the current date, or any arguments @var{x}, if @code{RP} is also +called, left-aligned at the end of the document description on the cover +page. This is @code{groff} @file{ms}'s default. +@endDefmac + +@Defmac {AB, [@code{no}], ms} +Begin the abstract. @file{ms} collects text on input lines following +this call into the abstract until reaching an @code{AE} call. By +default, @file{ms} places the word ``ABSTRACT'' centered and in italics +above the text of the abstract. The optional argument @code{no} +suppresses this heading. +@endDefmac + +@Defmac {AE, , ms} +End the abstract. +@endDefmac + +An example document description, using a cover page, follows. +@cindex cover page in [@file{ms}], example markup +@cindex example markup, cover page in [@file{ms}] + +@CartoucheExample +.RP +.TL +The Inevitability of Code Bloat +in Commercial and Free Software +.AU +J.\& Random Luser +.AI +University of West Bumblefuzz +.AB +This report examines the long-term growth of the code +bases in two large, +popular software packages; +the free Emacs and the commercial Microsoft Word. +While differences appear in the type or order of +features added, +due to the different methodologies used, +the results are the same in the end. +.PP +The free software approach is shown to be superior in +that while free software can become as bloated as +commercial offerings, +free software tends to have fewer serious bugs and the +added features are more in line with user demand. +.AE + +@r{@dots{}the rest of the paper@dots{}} +@endCartoucheExample + +@c --------------------------------------------------------------------- + +@node ms Body Text, ms Page Layout, ms Document Description Macros, ms +@subsection Body Text +@cindex @file{ms} macros, body text + +A variety of macros, registers, and strings can be used to structure and +style the body of your document. They organize your text into +paragraphs, headings, footnotes, and inclusions of material such as +tables and figures. + +@menu +* Text settings in ms:: +* Typographical symbols in ms:: +* Paragraphs in ms:: +* Headings in ms:: +* Typeface and decoration:: +* Lists in ms:: +* Indented regions in ms:: +* ms keeps and displays:: +* ms Insertions:: +* ms Footnotes:: +* ms language and localization:: +@end menu + +@c --------------------------------------------------------------------- + +@node Text settings in ms, Typographical symbols in ms, ms Body Text, ms Body Text +@subsubsection Text settings +@cindex @file{ms} macros, text settings + +The @code{FAM} string, a GNU extension, sets the font family for body +text; the default is @samp{T}. The @code{PS} and @code{VS} registers +set the type size and vertical spacing (distance between text +baselines), respectively. The font family and type size are ignored on +terminal devices. Setting these parameters before the first call of a +heading, paragraphing, or (non-date) document description macro also +applies them to headers, footers, and (for @code{FAM}) footnotes. + +Which font families are available depends on the output device; as a +convention, @code{T} selects a serif family (``Times''), @code{H} a +sans-serif family (``Helvetica''), and @code{C} a monospaced family +(``Courier''). The man page for the output driver documents its font +repertoire. Consult the @cite{groff@r{(1)}} man page for lists of +available output devices and their drivers. + +The hyphenation mode (as used by the @code{hy} request) is set from the +@code{HY} register. Setting @code{HY} to @samp{0} is equivalent to +using the @code{nh} request. This is a Tenth Edition Research Unix +extension. + +@c --------------------------------------------------------------------- + +@node Typographical symbols in ms, Paragraphs in ms, Text settings in ms, ms Body Text +@subsubsection Typographical symbols +@cindex @file{ms} macros, obtaining typographical symbols + +@file{ms} provides a few strings to obtain typographical symbols not +easily entered with the keyboard. These and many others are available +as special character escape sequences---see the @cite{groff_char@r{(7)}} +man page. + +@Defmpstr {-, ms} +Interpolate an em dash. +@endDefmpstr + +@DefmpstrList {Q, ms} +@DefmpstrListEndx {U, ms} +Interpolate typographer's quotation marks where available, and neutral +double quotes otherwise. @code{\*Q} is the left quote and @code{\*U} +the right. +@endDefmpstr + +@c --------------------------------------------------------------------- + +@node Paragraphs in ms, Headings in ms, Typographical symbols in ms, ms Body Text +@subsubsection Paragraphs +@cindex @file{ms} macros, paragraph handling + +Paragraphing macros @dfn{break}, or terminate, any pending output line +so that a new paragraph can begin. Several paragraph types are +available, differing in how indentation applies to them: to left, right, +or both margins; to the first output line of the paragraph, all output +lines, or all but the first. All paragraphing macro calls cause the +insertion of vertical space in the amount stored in the @code{PD} +register, except at page or column breaks. Alternatively, a blank input +line breaks the output line and vertically spaces by one vee. + +@Defmac {LP, , ms} +Set a paragraph without any (additional) indentation. +@endDefmac + +@Defmac {PP, , ms} +Set a paragraph with a first-line left indentation in the amount stored +in the @code{PI} register. +@endDefmac + +@Defmac {IP, [@Var{marker} [@Var{width}]], ms} +Set a paragraph with a left indentation. The optional @var{marker} is +not indented and is empty by default. It has several applications; +see @ref{Lists in ms}. @var{width} overrides the indentation amount +stored in the @code{PI} register; its default unit is @samp{n}. Once +specified, @var{width} applies to further @code{IP} calls until +specified again or a heading or different paragraphing macro is called. +@endDefmac + +@Defmac {QP, , ms} +Set a paragraph indented from both left and right margins by the amount +stored in the @code{QI} register. +@endDefmac + +@DefmacList {QS, , ms} +@DefmacListEndx {QE, , ms} +Begin (@code{QS}) and end (@code{QE}) a region where each paragraph is +indented from both margins by the amount stored in the @code{QI} +register. The text between @code{QS} and @code{QE} can be structured +further by use of other paragraphing macros. +@endDefmac + +@Defmac {XP, , ms} +Set an ``exdented'' paragraph---one with a left indentation in the +amount stored in the @code{PI} register on every line @emph{except} the +first (also known as a hanging indent). This is a Berkeley extension. +@endDefmac + +The following example illustrates the use of paragraphing macros. + +@CartoucheExample +.NH 2 +Cases used in the 2001 study +.LP +Two software releases were considered for this report. +.PP +The first is commercial software; +the second is free. +.IP \[bu] +Microsoft Word for Windows, +starting with version 1.0 through the current version +(Word 2000). +.IP \[bu] +GNU Emacs, +from its first appearance as a standalone editor through +the current version (v20). +See [Bloggs 2002] for details. +.QP +Franklin's Law applied to software: +software expands to outgrow both RAM and disk space over +time. +.SH +Bibliography +.XP +Bloggs, Joseph R., +.I "Everyone's a Critic" , +Underground Press, March 2002. +A definitive work that answers all questions and +criticisms about the quality and usability of free +software. +@endCartoucheExample + +@c --------------------------------------------------------------------- + +@node Headings in ms, Typeface and decoration, Paragraphs in ms, ms Body Text +@subsubsection Headings +@cindex @file{ms} macros, headings + +Use headings to create a sequential or hierarchical structure for your +document. The @file{ms} macros print headings in @strong{bold} using +the same font family and, by default, type size as the body text. +Headings are available with and without automatic numbering. Text on +input lines following the macro call becomes the heading's title. Call +a paragraphing macro to end the heading text and start the section's +content. + +@DefmacList {NH, [@Var{depth}], ms} +@DefmacListEnd {NH, @t{S} @Var{heading-depth-index} @dots{}, ms} +Set an automatically numbered heading. + +@file{ms} produces a numbered heading the form @var{a.b.c@dots{}}, to +any depth desired, with the numbering of each depth increasing +automatically and being reset to zero when a more significant level is +increased. ``1''@tie{}is the most significant or coarsest division of +the document. Only non-zero values are output. If @var{depth} is +omitted, it is taken to be @samp{1}. + +If you specify @var{depth} such that an ascending gap occurs relative to +the previous @code{NH} call---that is, you ``skip a depth'', as by +@samp{.NH 1} and then @samp{.NH 3}---@code{groff} @file{ms} emits a +warning on the standard error stream. + +Alternatively, you can give @code{NH} a first argument of@tie{}@code{S}, +followed by integers to number the heading depths explicitly. Further +automatic numbering, if used, resumes using the specified indices as +their predecessors. +@c Although undocumented in Tuthill's 4.2BSD ms.diffs paper... +This feature is a Berkeley extension. +@endDefmac + +An example may be illustrative. + +@CartoucheExample +.NH 1 +Animalia +.NH 2 +Arthropoda +.NH 3 +Crustacea +.NH 2 +Chordata +.NH S 6 6 6 +Daimonia +.NH 1 +Plantae +@endCartoucheExample + +The above results in numbering as follows; the vertical space that +normally precedes each heading is omitted. + +@Example +1. Animalia +1.1. Arthropoda +1.1.1. Crustacea +1.2. Chordata +6.6.6. Daimonia +7. Plantae +@endExample + +@DefmpstrList {SN-STYLE, ms} +@DefmpstrItemx {SN-DOT, ms} +@DefmpstrItemx {SN-NO-DOT, ms} +@DefmpstrListEndx {SN, ms} +After @code{NH} is called, the assigned number is made available in the +strings @code{SN-DOT} (as it appears in a printed heading with default +formatting, followed by a terminating period) and @code{SN-NO-DOT} (with +the terminating period omitted). These are GNU extensions. + +You can control the style used to print numbered headings by defining an +appropriate alias for the string @code{SN-STYLE}. By default, +@code{SN-STYLE} is aliased to @code{SN-DOT}. If you prefer to omit the +terminating period from numbers appearing in numbered headings, you may +define the alias as follows. + +@Example +.als SN-STYLE SN-NO-DOT +@endExample + +@noindent +Any such change in numbering style becomes effective from the next use +of @code{NH} following redefinition of the alias for @code{SN-STYLE}. +The formatted number of the current heading is available in the +@code{SN} string (a feature first documented by Berkeley), which +facilitates its inclusion in, for example, table captions, equation +labels, and @code{XS}/@code{XA}/@code{XE} table of contents entries. +@endDefmpstr + +@Defmac {SH, [@Var{depth}], ms} +Set an unnumbered heading. + +The optional @var{depth} argument is a GNU extension indicating the +heading depth corresponding to the @var{depth} argument of @code{NH}. +It matches the type size at which the heading is set to that of a +numbered heading at the same depth when the @code{GROWPS} and +@code{PSINCR} heading size adjustment mechanism is in effect. +@endDefmac + +If the @code{GROWPS} register is set to a value greater than the +@var{level} argument to @code{NH} or @code{SH}, the type size of a +heading produced by these macros increases by @code{PSINCR} units over +the size specified by @code{PS} multiplied by the difference of +@code{GROWPS} and @var{level}. The value stored in @code{PSINCR} is +interpreted in @code{groff} basic units; the @code{p} scaling unit +should be employed when assigning a value specified in points. For +example, the sequence + +@CartoucheExample +.nr PS 10 +.nr GROWPS 3 +.nr PSINCR 1.5p +.NH 1 +Carnivora +.NH 2 +Felinae +.NH 3 +Felis catus +.SH 2 +Machairodontinae +@endCartoucheExample + +@noindent +will cause ``1. Carnivora'' to be printed in 13-point text, followed by +``1.1. Felinae'' in 11.5-point text, while ``1.1.1. Felis catus'' and +all more deeply nested heading levels will remain in the 10-point text +specified by the @code{PS} register. ``Machairodontinae'' is printed at +11.5 points, since it corresponds to heading level@tie{}2. + +The @code{HORPHANS} register operates in conjunction with the @code{NH} +and @code{SH} macros to inhibit the printing of isolated headings at the +bottom of a page; it specifies the minimum number of lines of an +immediately subsequent paragraph that must be kept on the same page as +the heading. If insufficient space remains on the current page to +accommodate the heading and this number of lines of paragraph text, a +page break is forced before the heading is printed. Any display macro +call or @code{tbl}, @code{pic}, or @code{eqn} region between the heading +and the subsequent paragraph suppresses this grouping. @xref{ms keeps +and displays} and @ref{ms Insertions}. + +@c --------------------------------------------------------------------- + +@node Typeface and decoration, Lists in ms, Headings in ms, ms Body Text +@subsubsection Typeface and decoration + +The @file{ms} macros provide a variety of ways to style text. +Attend closely to the ordering of arguments labeled @var{pre} and +@var{post}, which is not intuitive. Support for @var{pre} +arguments is a GNU extension.@footnote{This idiosyncrasy arose through +feature accretion; for example, the @code{B} macro in Version@tie{}6 +Unix @file{ms} (1975) accepted only one argument, the text to be set in +boldface. By Version@tie{}7 (1979) it recognized a second argument; in +1990, @code{groff} @file{ms} added a ``pre'' argument, placing it third +to avoid breaking support for older documents.} + +@Defmac {B, [@Var{text} [@Var{post} [@Var{pre}]]], ms} +Style @var{text} in @b{bold}, followed by @var{post} in the previous +font style without intervening space, and preceded by @var{pre} +similarly. Without arguments, @file{ms} styles subsequent text in bold +until the next paragraphing, heading, or no-argument typeface macro +call. +@endDefmac + +@Defmac {R, [@Var{text} [@Var{post} [@Var{pre}]]], ms} +As @code{B}, but use the roman style (upright text of normal weight) +instead of bold. Argument recognition is a GNU extension. +@endDefmac + +@Defmac {I, [@Var{text} [@Var{post} [@Var{pre}]]], ms} +As @code{B}, but use an @i{italic} or oblique style instead of bold. +@endDefmac + +@Defmac {BI, [@Var{text} [@Var{post} [@Var{pre}]]], ms} +As @code{B}, but use a bold italic or bold oblique style instead of +upright bold. This is a Tenth Edition Research Unix extension. +@c possibly 9th, but definitely not Berkeley +@endDefmac + +@Defmac {CW, [@Var{text} [@Var{post} [@Var{pre}]]], ms} +As @code{B}, but use a @t{constant-width} (monospaced) roman typeface +instead of bold. This is a Tenth Edition Research Unix extension. +@c possibly 9th, but definitely not Berkeley +@endDefmac + +@Defmac {BX, [@Var{text}], ms} +Typeset @var{text} and draw a box around it. On terminal devices, +reverse video is used instead. If you want @var{text} to contain space, +use unbreakable space or horizontal motion escape sequences (@code{\~}, +@code{\@key{SP}}, @code{\^}, @code{\|}, @code{\0} or @code{\h}). +@endDefmac + +@Defmac {UL, [@Var{text} [@Var{post}]], ms} +Typeset @var{text} with an underline. @var{post}, if present, is set +after @var{text} with no intervening space. +@endDefmac + +@Defmac {LG, , ms} +Set subsequent text in larger type (two points larger than the +current size) until the next type size, paragraphing, or heading macro +call. You can specify this macro multiple times to enlarge the type +size as needed. +@endDefmac + +@Defmac {SM, , ms} +Set subsequent text in smaller type (two points smaller than the current +size) until the next type size, paragraphing, or heading macro call. +You can specify this macro multiple times to reduce the type size as +needed. +@endDefmac + +@Defmac {NL, , ms} +Set subsequent text at the normal type size (the amount in the @code{PS} +register). +@endDefmac + +@var{pre} and @var{post} arguments are typically used to simplify the +attachment of punctuation to styled words. When @var{pre} is used, +a hyphenation control escape sequence @code{\%} that would ordinarily +start @var{text} must start @var{pre} instead to have the desired +effect. + +@CartoucheExample +The CS course's students found one C language keyword +.CW static ) \%( +most troublesome. +@endCartoucheExample + +The foregoing example produces output as follows. + +@CartoucheExample +@r{The CS course's students found one C language keyword (@t{static}) +most troublesome.} +@endCartoucheExample + +You can use the output line continuation escape sequence @code{\c} to +achieve the same result (@pxref{Line Continuation}). It is also +portable to older @file{ms} implementations. + +@CartoucheExample +The CS course's students found one C language keyword +\%(\c +.CW \%static ) +most troublesome. +@endCartoucheExample + +@code{groff} @file{ms} also offers strings to begin and end super- and +subscripting. These are GNU extensions. + +@DefmpstrList {@lbracechar{}, ms} +@DefmpstrListEndx {@rbracechar{}, ms} +Begin and end superscripting, respectively. +@endDefmpstr + +@DefmpstrList {<, ms} +@DefmpstrListEndx {>, ms} +Begin and end subscripting, respectively. +@endDefmpstr + +Rather than calling the @code{CW} macro, in @code{groff} @file{ms} you +might prefer to change the font family to Courier by setting the +@code{FAM} string to @samp{C}. You can then use all four style macros +above, returning to the default family (Times) with @samp{.ds FAM T}. +Because changes to @code{FAM} take effect only at the next paragraph, +@code{CW} remains useful to ``inline'' a change to the font family, +similarly to the practice of this document in noting syntactical +elements of @file{ms} and @code{groff}. + +@c --------------------------------------------------------------------- + +@node Lists in ms, Indented regions in ms, Typeface and decoration, ms Body Text +@subsubsection Lists +@cindex @file{ms} macros, lists + +The @var{marker} argument to the @code{IP} macro can be employed to +present a variety of lists; for instance, you can use a bullet glyph +(@code{\[bu]}) for unordered lists, a number (or auto-incrementing +register) for numbered lists, or a word or phrase for glossary-style or +definition lists. If you set the paragraph indentation register +@code{PI} before calling @code{IP}, you can later reorder the items in +the list without having to ensure that a @var{width} argument remains +affixed to the first call. + +The following is an example of a bulleted list. +@cindex example markup, bulleted list [@file{ms}] +@cindex bulleted list, example markup [@file{ms}] + +@CartoucheExample +.nr PI 2n +A bulleted list: +.IP \[bu] +lawyers +.IP \[bu] +guns +.IP \[bu] +money +@endCartoucheExample + +@Example +A bulleted list: + +@bullet{} lawyers + +@bullet{} guns + +@bullet{} money +@endExample + +The following is an example of a numbered list. +@cindex example markup, numbered list [@file{ms}] +@cindex numbered list, example markup [@file{ms}] + +@CartoucheExample +.nr step 0 1 +.nr PI 3n +A numbered list: +.IP \n+[step] +lawyers +.IP \n+[step] +guns +.IP \n+[step] +money +@endCartoucheExample + +@Example +A numbered list: + +1. lawyers + +2. guns + +3. money +@endExample + +Here we have employed the @code{nr} request to create a register of our +own, @samp{step}. We initialized it to zero and assigned it an +auto-increment of 1. Each time we use the escape sequence +@samp{\n+[PI]} (note the plus sign), the formatter applies the increment +just before interpolating the register's value. Preparing the @code{PI} +register as well enables us to rearrange the list without the tedium of +updating macro calls. + +The next example illustrates a glossary-style list. +@cindex example markup, glossary-style list [@file{ms}] +@cindex glossary-style list, example markup [@file{ms}] + +@CartoucheExample +A glossary-style list: +.IP lawyers 0.4i +Two or more attorneys. +.IP guns +Firearms, +preferably large-caliber. +.IP money +Gotta pay for those +lawyers and guns! +@endCartoucheExample + +@Example +A glossary-style list: + +lawyers + Two or more attorneys. + +guns Firearms, preferably large-caliber. + +money + Gotta pay for those lawyers and guns! +@endExample + +In the previous example, observe how the @code{IP} macro places the +definition on the same line as the term if it has enough space. If this +is not what you want, there are a few workarounds we will illustrate by +modifying the example. First, you can use a @code{br} request to force +a break after printing the term or label. + +@CartoucheExample +.IP guns +.br +Firearms, +@endCartoucheExample + +Second, you could apply the @code{\p} escape sequence to force a break. +The space following the escape sequence is important; if you omit it, +@code{groff} prints the first word of the paragraph text on the same +line as the term or label (if it fits) @emph{then} breaks the line. + +@CartoucheExample +.IP guns +\p Firearms, +@endCartoucheExample + +Finally, you may append a horizontal motion to the marker with the +@code{\h} escape sequence; using the same amount as the indentation will +ensure that the marker is too wide for @code{groff} to treat it as +``fitting'' on the same line as the paragraph text. + +@CartoucheExample +.IP guns\h'0.4i' +Firearms, +@endCartoucheExample + +In each case, the result is the same. + +@Example +A glossary-style list: + +lawyers + Two or more attorneys. + +guns + Firearms, preferably large-caliber. + +money + Gotta pay for those lawyers and guns! +@endExample + +@c --------------------------------------------------------------------- + +@node Indented regions in ms, ms keeps and displays, Lists in ms, ms Body Text +@subsubsection Indented regions + +You may need to indent a region of text while otherwise formatting it +normally. Indented regions can be nested; you can change @code{\n[PI]} +before each call to vary the amount of inset. + +@Defmac {RS, , ms} +Begin a region where headings, paragraphs, and displays are indented +(further) by the amount stored in the @code{PI} register. +@endDefmac + +@Defmac {RE, , ms} +End the (next) most recent indented region. +@endDefmac + +This feature enables you to easily line up text under hanging and +indented paragraphs. +@cindex @file{ms} macros, nested lists +@cindex nested lists [@file{ms}] +For example, you may wish to structure lists hierarchically. + +@CartoucheExample +.IP \[bu] 2 +Lawyers: +.RS +.IP \[bu] +Dewey, +.IP \[bu] +Cheatham, +and +.IP \[bu] +and Howe. +.RE +.IP \[bu] +Guns +@endCartoucheExample + +@Example +@bullet{} Lawyers: + + @bullet{} Dewey, + + @bullet{} Cheatham, and + + @bullet{} Howe. + +@bullet{} Guns +@endExample + +@c --------------------------------------------------------------------- + +@node ms keeps and displays, ms Insertions, Indented regions in ms, ms Body Text +@subsubsection Keeps, boxed keeps, and displays +@cindex @file{ms} macros, displays +@cindex @file{ms} macros, keeps +@cindex keeps [@file{ms}] + +On occasion, you may want to @dfn{keep} several lines of text, or a +region of a document, together on a single page, preventing an automatic +page break within certain boundaries. This can cause a page break to +occur earlier than it normally would. For example, you may want to keep +two paragraphs together, or a paragraph that refers to a table, list, or +figure adjacent to the item it discusses. @file{ms} provides the +@code{KS} and @code{KE} macros for this purpose. + +You can alternatively specify a @dfn{floating keep}:@: if a keep cannot +fit on the current page, @file{ms} holds its contents and +allows material following the keep (in the source document) to fill the +remainder of the current page. When the page breaks, whether by +reaching the end or @code{bp} request, @file{ms} puts the floating keep +at the beginning of the next page. This is useful for placing large +graphics or tables that do not need to appear exactly where they occur +in the source document. + +@DefmacList {KS, , ms} +@DefmacItemx {KF, , ms} +@DefmacListEndx {KE, , ms} +@code{KS} begins a keep, @code{KF} a floating keep, and @code{KE} ends a +keep of either kind. +@endDefmac + +As an alternative to the keep mechanism, the @code{ne} request forces a +page break if there is not at least the amount of vertical space +specified in its argument remaining on the page (@pxref{Page Control}). +One application of @code{ne} is to reserve space on the page for a +figure or illustration to be included later. + +@cindex boxes [@file{ms}] +A @dfn{boxed keep} has a frame drawn around it. + +@DefmacList {B1, , ms} +@DefmacListEndx {B2, , ms} +@code{B1} begins a keep with a box drawn around it. @code{B2} ends a +boxed keep. +@endDefmac + +Boxed keep macros cause breaks; if you need to box a word or phrase +within a line, see the @code{BX} macro in @ref{Typeface and decoration}. +Box lines are drawn as close as possible to the text they enclose so +that they are usable within paragraphs. If you wish to box one or more +paragraphs, you may improve the appearance by calling @code{B1} after +the first paragraphing macro, and by adding a small amount of vertical +space before calling @code{B2}. + +@c Wrap example at 58 columns. +@CartoucheExample +.LP +.B1 +.I Warning: +Happy Fun Ball may suddenly accelerate to dangerous +speeds. +.sp \n[PD]/2 \" space by half the inter-paragraph distance +.B2 +@endCartoucheExample + +If you want a boxed keep to float, you will need to enclose the +@code{B1} and @code{B2} calls within a pair of @code{KF} and @code{KE} +calls. + +@cindex displays [@file{ms}] +@dfn{Displays} turn off filling; lines of verse or program code are +shown with their lines broken as in the source document without +requiring @code{br} requests between lines. Displays can be kept on a +single page or allowed to break across pages. The @code{DS} macro +begins a kept display of the layout specified in its first argument; +non-kept displays are begun with dedicated macros corresponding to their +layout. + +@DefmacList {DS, @t{L}, ms} +@DefmacListEndx {LD, , ms} +Begin (@code{DS}:@: kept) left-aligned display. +@endDefmac + +@DefmacList {DS, [@t{I} [@Var{indent}]], ms} +@DefmacListEndx {ID, [@Var{indent}], ms} +Begin (@code{DS}:@: kept) display indented by @var{indent} if specified, +and by the amount of the @code{DI} register otherwise. +@endDefmac + +@DefmacList {DS, @t{B}, ms} +@DefmacListEndx {BD, , ms} +Begin a (@code{DS}:@: kept) a block display:@: the entire display is +left-aligned, but indented such that the longest line in the display +is centered on the page. +@endDefmac + +@DefmacList {DS, @t{C}, ms} +@DefmacListEndx {CD, , ms} +Begin a (@code{DS}:@: kept) centered display:@: each line in the display +is centered. +@endDefmac + +@DefmacList {DS, @t{R}, ms} +@DefmacListEndx {RD, , ms} +Begin a (@code{DS}:@: kept) right-aligned display. This is a GNU +extension. +@endDefmac + +@Defmac {DE, , ms} +End any display. +@endDefmac + +The distance stored in the @code{DD} register is inserted before and +after each pair of display macros; this is a Berkeley extension. In +@code{groff} @file{ms}, this distance replaces any adjacent +inter-paragraph distance or subsequent spacing prior to a section +heading. The @code{DI} register is a GNU extension; its value is an +indentation applied to displays created with @samp{.DS} and @samp{.ID} +without arguments, to @samp{.DS I} without an indentation argument, and +to indented equations set with @samp{.EQ}. Changes to either register +take effect at the next display boundary. + +@c --------------------------------------------------------------------- + +@node ms Insertions, ms Footnotes, ms keeps and displays, ms Body Text +@subsubsection Tables, figures, equations, and references +@cindex @file{ms} macros, tables +@cindex @file{ms} macros, figures +@cindex @file{ms} macros, equations +@cindex @file{ms} macros, references +@cindex tables [@file{ms}] +@cindex figures [@file{ms}] +@cindex equations [@file{ms}] +@cindex references [@file{ms}] + +The @file{ms} package is often used with the @code{tbl}, @code{pic}, +@code{eqn}, and @code{refer} preprocessors. +@pindex tbl +@pindex pic +@pindex eqn +@pindex refer +Mark text meant for preprocessors by enclosing it in pairs of tokens +as follows, with nothing between the dot and the macro name. The +preprocessors match these tokens only at the start of an input line. + +@DefmacList {TS, [@code{H}], ms} +@DefmacListEndx {TE, , ms} +Demarcate a table to be processed by the @code{tbl} preprocessor. The +optional argument@tie{}@code{H} to @code{TS} instructs @file{ms} to +repeat table rows (often column headings) at the top of each new page +the table spans, if applicable; calling the @code{TH} macro marks the +end of such rows. The GNU @cite{tbl@r{(1)}} man page provides a +comprehensive reference to the preprocessor and offers examples of its +use. +@endDefmac + +@DefmacList {PS, , ms} +@DefmacItemx {PE, , ms} +@DefmacListEndx {PF, , ms} +@code{PS} begins a picture to be processed by the @command{gpic} +preprocessor; either of @code{PE} or @code{PF} ends it, the latter with +``flyback'' to the vertical position at its top. You can create +@code{pic} input manually or with a program such as @code{xfig}. +@endDefmac + +@DefmacList {EQ, [@Var{align} [@Var{label}]], ms} +@DefmacListEndx {EN, , ms} +Demarcate an equation to be processed by the @code{eqn} preprocessor. +The equation is centered by default; @var{align} can be @samp{C}, +@samp{L}, or @samp{I} to (explicitly) center, left-align, or indent it +by the amount stored in the @code{DI} register, respectively. If +specified, @var{label} is set right-aligned. +@endDefmac + +@DefmacList {[, , ms} +@DefmacListEndx {], , ms} +Demarcate a bibliographic citation to be processed by the @code{refer} +preprocessor. The GNU @cite{refer@r{(1)}} man page provides a +comprehensive reference to the preprocessor and the format of its +bibliographic database. Type @samp{man refer} at the command line to +view it. +@endDefmac + +When @code{refer} emits collected references (as might be done on a +``Works Cited'' page), it interpolates the @code{REFERENCES} string as +an unnumbered heading (@code{SH}). + +@cindex table, multi-page, example [@file{ms}] +@cindex multi-page table example [@file{ms}] +The following is an example of how to set up a table that may print +across two or more pages. + +@CartoucheExample +.TS H +allbox; +Cb | Cb . +Part@arrow{}Description +_ +.TH +.T& +GH-1978@arrow{}Fribulating gonkulator +@r{@dots{}the rest of the table follows@dots{}} +.TE +@endCartoucheExample + +@noindent +Attempting to place a multi-page table inside a keep can lead to +unpleasant results, particularly if the @code{tbl} @code{allbox} option +is used. + +@cindex equation example [@file{ms}] +Mathematics can be typeset using the language of the @code{eqn} +preprocessor. + +@CartoucheExample +.EQ C (\*[SN-NO-DOT]a) +p ~ = ~ q sqrt @{ ( 1 + ~ ( x / q sup 2 ) @} +.EN +@endCartoucheExample + +@noindent +This input formats a labelled equation. We used the @code{SN-NO-DOT} +string to base the equation label on the current heading number, giving +us more flexibility to reorganize the document. + +Use @command{groff} options to run preprocessors on the input:@: +@option{-e} for @command{geqn}, @option{-p} for @command{gpic}, +@option{-R} for @command{grefer}, and @option{-t} for @command{gtbl}. + +@c --------------------------------------------------------------------- + +@node ms Footnotes, , ms Insertions, ms Body Text +@subsubsection Footnotes +@cindex @file{ms} macros, footnotes +@cindex footnotes [@file{ms}] + +@cindex footnote marker [@file{ms}] +@cindex marker, footnote [@file{ms}] +A footnote is typically anchored to a place in the text with a +@dfn{marker}, which is a small integer, a symbol such as a dagger, or +arbitrary user-specified text. + +@Defmpstr {*, ms} +Place an @dfn{automatic number}, an automatically generated numeric +footnote marker, in the text. Each time this string is interpolated, +the number it produces increments by one. Automatic numbers start at 1. +This is a Berkeley extension. +@endDefesc + +Enclose the footnote text in @code{FS} and @code{FE} macro calls to set +it at the nearest available ``foot'', or bottom, of a text column or +page. + +@DefmacList {FS, [@Var{marker}], ms} +@DefmacListEndx {FE, , ms} +Begin (@code{FS}) and end (@code{FE}) a footnote. @code{FS} calls +@code{FS-MARK} with any supplied @var{marker} argument, which is then +also placed at the beginning of the footnote text. If @var{marker} is +omitted, the next pending automatic footnote number enqueued by +interpolation of the @code{*} string is used, and if none exists, +nothing is prefixed. +@endDefmac + +You may not desire automatically numbered footnotes in spite of their +convenience. You can indicate a footnote with a symbol or other text by +specifying its marker at the appropriate place (for example, by using +@code{\[dg]} for the dagger glyph) @emph{and} as an argument to the +@code{FS} macro. Such manual marks should be repeated as arguments to +@code{FS} or as part of the footnote text to disambiguate their +correspondence. You may wish to use @code{\*@{} and @code{\*@}} to +superscript the marker at the anchor point, in the footnote text, or +both. + +@code{groff} @file{ms} provides a hook macro, @code{FS-MARK}, for +user-determined operations to be performed when the @code{FS} macro is +called. It is passed the same arguments as @code{FS} itself. An +application of @code{FS-MARK} is anchor placement for a hyperlink +reference, so that a footnote can link back to its referential +context.@footnote{``Portable Document Format Publishing with GNU +Troff'', @file{pdfmark.ms} in the @code{groff} distribution, uses this +technique.} By default, this macro has an empty definition. +@code{FS-MARK} is a GNU extension. + +@cindex footnotes, and keeps [@file{ms}] +@cindex keeps, and footnotes [@file{ms}] +@cindex footnotes, and displays [@file{ms}] +@cindex displays, and footnotes [@file{ms}] +Footnotes can be safely used within keeps and displays, but you should +avoid using automatically numbered footnotes within floating keeps. You +can place a second @code{\**} interpolation between a @code{\**} and its +corresponding @code{FS} call as long as each @code{FS} call occurs +@emph{after} the corresponding @code{\**} and occurrences of @code{FS} +are in the same order as corresponding occurrences of @code{\**}. + +Footnote text is formatted as paragraphs are, using analogous +parameters. The registers @code{FI}, @code{FPD}, @code{FPS}, and +@code{FVS} correspond to @code{PI}, @code{PD}, @code{PS}, and @code{CS}, +respectively; @code{FPD}, @code{FPS}, and @code{FVS} are GNU extensions. + +The @code{FF} register controls the formatting of automatically numbered +footnote paragraphs and those for which @code{FS} is given a marker +argument. @xref{ms Document Control Settings}. + +The default footnote line length is 11/12ths of the normal line length +for compatibility with the expectations of historical @file{ms} +documents; you may wish to set the @code{FR} string to @samp{1} to align +with contemporary typesetting practices. In the +past,@footnote{Unix Version@tie{}7 @file{ms}, its descendants, and GNU +@file{ms} prior to @code{groff} version 1.23.0} an @code{FL} register +was used for the line length in footnotes; however, setting this +register at document initialization time had no effect on the footnote +line length in multi-column arrangements.@footnote{You could reset it +after each call to @code{.1C}, @code{.2C}, or @code{.MC}.} + +@code{FR} should be used in preference to the old @code{FL} register in +contemporary documents. The footnote line length is effectively +computed as @samp{@slanted{column-width} * \*[FR]}. If an absolute +footnote line length is required, recall that arithmetic expressions in +@code{roff} input are evaluated strictly from left to right, with no +operator precedence (parentheses are honored). + +@Example +.ds FR 0+3i \" Set footnote line length to 3 inches. +@endExample + +@c --------------------------------------------------------------------- + +@node ms language and localization, ms Page Layout, ms Footnotes, ms Body Text +@subsubsection Language and localization +@cindex @file{ms} macros, language +@cindex @file{ms} macros, localization +@cindex language [@file{ms}] +@cindex localization [@file{ms}] + +@code{groff} @file{ms} provides several strings that you can customize +for your own purposes, or redefine to adapt the macro package to +languages other than English. It is already localized for +@c cs, de, fr, it, sv +Czech, German, French, Italian, and Swedish. Load the desired +localization macro package after @file{ms}; see the +@cite{groff_tmac@r{(5)}} man page. + +@CartoucheExample +$ groff -ms -mfr bienvenue.ms +@endCartoucheExample + +The following strings are available. + +@Defmpstr {REFERENCES, ms} +Contains the string printed at the beginning of a references +(bibliography) page produced with GNU @cite{refer@r{(1)}}. The default +is @samp{References}. +@c XXX: Use of refer(1) with ms is insufficiently documented. +@endDefmpstr + +@Defmpstr {ABSTRACT, ms} +Contains the string printed at the beginning of the abstract. The +default is @samp{\f[I]ABSTRACT\f[]}; it includes font selection escape +sequences to set the word in italics. +@endDefmpstr + +@Defmpstr {TOC, ms} +Contains the string printed at the beginning of the table of contents. +The default is @samp{Table of Contents}. +@endDefmpstr + +@DefmpstrList {MONTH1, ms} +@DefmpstrItemx {MONTH2, ms} +@DefmpstrItemx {MONTH3, ms} +@DefmpstrItemx {MONTH4, ms} +@DefmpstrItemx {MONTH5, ms} +@DefmpstrItemx {MONTH6, ms} +@DefmpstrItemx {MONTH7, ms} +@DefmpstrItemx {MONTH8, ms} +@DefmpstrItemx {MONTH9, ms} +@DefmpstrItemx {MONTH10, ms} +@DefmpstrItemx {MONTH11, ms} +@DefmpstrListEndx {MONTH12, ms} +Contain the full names of the calendar months. The defaults are in +English: @samp{January}, @samp{February}, and so on. +@endDefmpstr + +@c --------------------------------------------------------------------- + +@node ms Page Layout, Differences from AT&T ms, ms Body Text, ms +@subsection Page layout +@cindex @file{ms} macros, page layout +@cindex page layout [@file{ms}] + +@file{ms}'s default page layout arranges text in a single column with +the page number between hyphens centered in a header on each page except +the first, and produces no footers. You can customize this arrangement. + +@menu +* ms Headers and Footers:: +* Tab Stops in ms:: +* ms Margins:: +* ms Multiple Columns:: +* ms TOC:: +@end menu + +@c --------------------------------------------------------------------- + +@node ms Headers and Footers, Tab Stops in ms, ms Page Layout, ms Page Layout +@subsubsection Headers and footers +@cindex @file{ms} macros, headers +@cindex @file{ms} macros, footers +@cindex headers [@file{ms}] +@cindex footers [@file{ms}] + +There are multiple ways to produce headers and footers. One is to +define the strings @code{LH}, @code{CH}, and @code{RH} to set the left, +center, and right headers, respectively; and @code{LF}, @code{CF}, and +@code{RF} to set the left, center, and right footers. This approach +suffices for documents that do not distinguish odd- and even-numbered +pages. + +Another method is to call macros that set headers or footers for odd- or +even-numbered pages. Each such macro takes a delimited argument +separating the left, center, and right header or footer texts from each +other. You can replace the neutral apostrophes (@code{'}) shown below +with any character not appearing in the header or footer text. These +macros are Berkeley extensions. + +@DefmacList {OH, @code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms} +@DefmacItemx {EH, @code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms} +@DefmacItemx {OF, @code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms} +@DefmacListEndx {EF, @code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}, ms} +The @code{OH} and @code{EH} macros define headers for odd- (recto) +and even-numbered (verso) pages, respectively; the @code{OF} and +@code{EF} macros define footers for them. +@endDefmac + +With either method, a percent sign @code{%} in header or footer text is +replaced by the current page number. By default, @file{ms} places no +header on a page numbered ``1'' (regardless of its number format). + +@Defmac {P1, , ms} +Typeset the header even on page@tie{}1. To be effective, this macro +must be called before the header trap is sprung on any page numbered +``1''; in practice, unless your page numbering is unusual, this means +that you should call it early, before @code{TL} or any heading or +paragraphing macro. This is a Berkeley extension. +@endDefmac + +For even greater flexibility, @file{ms} is designed to permit the +redefinition of the macros that are called when the @code{groff} traps +that ordinarily cause the headers and footers to be output are sprung. +@code{PT} (``page trap'') is called by @file{ms} when the header is to +be written, and @code{BT} (``bottom trap'') when the footer is to be. +The @code{groff} page location trap that @file{ms} sets up to format the +header also calls the (normally undefined) @code{HD} macro after +@code{PT}; you can define @code{HD} if you need additional processing +after setting the header (for example, to draw a line below it). +@c Although undocumented in Tuthill's 4.2BSD ms.diffs paper... +The @code{HD} hook is a Berkeley extension. Any such macros you +(re)define must implement any desired specialization for odd-, even-, or +first numbered pages. + +@c --------------------------------------------------------------------- + +@node Tab Stops in ms, ms Margins, ms Headers and Footers, ms Page Layout +@subsubsection Tab stops + +Use the @code{ta} request to define tab stops as needed. @xref{Tabs and +Fields}. + +@Defmac {TA, , ms} +Reset the tab stops to the @file{ms} default (every 5 ens). +Redefine this macro to create a different set of default tab stops. +@endDefmac + +@c --------------------------------------------------------------------- + +@node ms Margins, ms Multiple Columns, Tab Stops in ms, ms Page Layout +@subsubsection Margins +@cindex @file{ms} macros, margins + +Control margins using the registers summarized in ``Margin settings'' in +@ref{ms Document Control Settings} above. There is no setting for the +right margin; the combination of page offset @code{\n[PO]} and line +length @code{\n[LL]} determines it. + +@c --------------------------------------------------------------------- + +@node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout +@subsubsection Multiple columns +@cindex @file{ms} macros, multiple columns +@cindex multiple columns [@file{ms}] + +@file{ms} can set text in as many columns as reasonably fit on the page. +The following macros force a page break if a multi-column layout is +active when they are called. The @code{MINGW} register stores the +default minimum gutter width; it is a GNU extension. When multiple +columns are in use, keeps and the @code{HORPHANS} and @code{PORPHANS} +registers work with respect to column breaks instead of page breaks. + +@Defmac {1C, , ms} +Arrange page text in a single column (the default). +@endDefmac + +@Defmac {2C, , ms} +Arrange page text in two columns. +@endDefmac + +@Defmac {MC, [@Var{column-width} [@Var{gutter-width}]], ms} +Arrange page text in multiple columns. If you specify no arguments, it +is equivalent to the @code{2C} macro. Otherwise, @var{column-width} is +the width of each column and @var{gutter-width} is the minimum distance +between columns. +@endDefmac + +@c --------------------------------------------------------------------- + +@node ms TOC, Differences from AT&T ms, ms Multiple Columns, ms Page Layout +@subsubsection Creating a table of contents +@cindex @file{ms} macros, creating table of contents +@cindex table of contents, creating [@file{ms}] + +Because @code{roff} formatters process their input in a single pass, +material on page 50, for example, cannot influence what appears on +page@tie{}1---this poses a challenge for a table of contents at its +traditional location in front matter, if you wish to avoid manually +maintaining it. @file{ms} enables the collection of material to be +presented in the table of contents as it appears, saving its page number +along with it, and then emitting the collected contents on demand toward +the end of the document. The table of contents can then be resequenced +to its desired location by physically rearranging the pages of a printed +document, or as part of post-processing---with a @cite{sed@r{(1)}} +script to reorder the pages in @command{troff}'s output, with +@cite{pdfjam@r{(1)}}, or with @cite{gropdf@r{(1)}}'s +@samp{.pdfswitchtopage} feature, for example. + +Define an entry to appear in the table of contents by bracketing its +text between calls to the @code{XS} and @code{XE} macros. A typical +application is to call them immediately after @code{NH} or @code{SH} and +repeat the heading text within them. The @code{XA} macro, used within +@samp{.XS}/@samp{.XE} pairs, supplements an entry---for instance, when +it requires multiple output lines, whether because a heading is too long +to fit or because style dictates that page numbers not be repeated. You +may wish to indent the text thus wrapped to correspond to its heading +depth; this can be done in the entry text by prefixing it with tabs or +horizontal motion escape sequences, or by providing a second argument to +the @code{XA} macro. @code{XS} and @code{XA} automatically associate +the page number where they are called with the text following them, but +they accept arguments to override this behavior. At the end of the +document, call @code{TC} or @code{PX} to emit the table of contents; +@code{TC} resets the page number to @samp{i} (Roman numeral one), and +then calls @code{PX}. All of these macros are Berkeley extensions. + +@DefmacList {XS, [@Var{page-number}], ms} +@DefmacItemx {XA, [@Var{page-number} [@Var{indentation}]], ms} +@DefmacListEndx {XE, , ms} +Begin, supplement, and end a table of contents entry. Each entry is +associated with @var{page-number} (otherwise the current page number); a +@var{page-number} of @samp{no} prevents a leader and page number from +being emitted for that entry. Use of @code{XA} within +@code{XS}/@code{XE} is optional; it can be repeated. If +@var{indentation} is present, a supplemental entry is indented by that +amount; ens are assumed if no unit is indicated. Text on input lines +between @code{XS} and @code{XE} is stored for later recall by @code{PX}. +@endDefmac + +@Defmac {PX, [@code{no}], ms} +Switch to single-column layout. Unless @code{no} is specified, center +and interpolate the @code{TOC} string in bold and two points larger than +the body text. Emit the table of contents entries. +@endDefmac + +@Defmac {TC, [@code{no}], ms} +Set the page number to@tie{}1, the page number format to lowercase Roman +numerals, and call @code{PX} (with a @code{no} argument, if present). +@endDefmac + +Here's an example of typical @file{ms} table of contents preparation. +We employ horizontal escape sequences @code{\h} to indent the entries by +sectioning depth. + +@CartoucheExample +.NH 1 +Introduction +.XS +Introduction +.XE +@r{@dots{}} +.NH 2 +Methodology +.XS +\h'2n'Methodology +.XA +\h'4n'Fassbinder's Approach +\h'4n'Kahiu's Approach +.XE +@r{@dots{}} +.NH 1 +Findings +.XS +Findings +.XE +@r{@dots{}} +.TC +@endCartoucheExample + +The remaining features in this subsubsection are GNU extensions. +@code{groff} @file{ms} obviates the need to repeat heading text after +@code{XS} calls. Call @code{XN} and @code{XH} after @code{NH} and +@code{SH}, respectively. + +@DefmacList {XN, @Var{heading-text}, ms} +@DefmacListEndx {XH, @Var{depth} @Var{heading-text}, ms} +Format @var{heading-text} and create a corresponding table of contents +entry. @code{XN} computes the indentation from the depth of the +preceding @code{NH} call; @code{XH} requires a @var{depth} argument to +do so. +@endDefmac + +@code{groff} @file{ms} encourages customization of table of contents +entry production. + +@DefmacList {XN-REPLACEMENT, @Var{heading-text}, ms} +@DefmacListEndx {XH-REPLACEMENT, @Var{depth} @Var{heading-text}, ms} +These hook macros implement @code{XN} and @code{XH}, respectively. +They call @code{XN-INIT} and pass their @var{heading-text} arguments to +@code{XH-UPDATE-TOC}. +@endDefmac + +@DefmacList {XN-INIT, , ms} +@DefmacListEndx {XH-UPDATE-TOC, @Var{depth} @Var{heading-text}, ms} +The @code{XN-INIT} hook macro does nothing by default. +@code{XH-UPDATE-TOC} brackets @var{heading-text} with @code{XS} and +@code{XE} calls, indenting it by 2 ens per level of @var{depth} beyond +the first. +@endDefmac + +We could therefore produce a table of contents similar to that in the +previous example with fewer macro calls. (The difference is that this +input follows the ``Approach'' entries with leaders and page numbers.) + +@CartoucheExample +.NH 1 +.XN Introduction +@r{@dots{}} +.NH 2 +.XN Methodology +.XH 3 "Fassbinder's Approach" +.XH 3 "Kahiu's Approach" +@r{@dots{}} +.NH 1 +.XN Findings +@r{@dots{}} +@endCartoucheExample + +To get the section number of the numbered headings into the table of +contents entries, we might define @code{XN-REPLACEMENT} as follows. +(We obtain the heading depth from @code{groff} @file{ms}'s internal +register @code{nh*hl}.) + +@CartoucheExample +.de XN-REPLACEMENT +.XN-INIT +.XH-UPDATE-TOC \\n[nh*hl] \\$@@ +\&\\*[SN] \\$* +.. +@endCartoucheExample + +You can change the style of the leader that bridges each table of +contents entry with its page number; define the @code{TC-LEADER} special +character by using the @code{char} request. A typical leader combines +the dot glyph @samp{.} with a horizontal motion escape sequence to +spread the dots. The width of the page number field is stored in the +@code{TC-MARGIN} register. + +@c --------------------------------------------------------------------- + +@node Differences from AT&T ms, ms Naming Conventions, ms Page Layout, ms +@subsection Differences from @acronym{AT&T} @file{ms} +@cindex @file{ms} macros, @code{groff} differences from @acronym{AT&T} +@cindex @acronym{AT&T} @file{ms}, macro package differences + +The @code{groff} @file{ms} macros are an independent reimplementation, +using no @acronym{AT&T} code. Since they take advantage of the extended +features of @code{groff}, they cannot be used with @acronym{AT&T} +@code{troff}. @code{groff} @file{ms} supports features described above +as Berkeley and Tenth Edition Research Unix extensions, and adds several +of its own. + +@itemize @bullet +@item +The internals of @code{groff} @file{ms} differ from the internals of +@acronym{AT&T} @file{ms}. Documents that depend upon implementation +details of @acronym{AT&T} @file{ms} may not format properly with +@code{groff} @file{ms}. Such details include macros whose function was +not documented in the @acronym{AT&T} @file{ms} +manual.@footnote{@cite{Typing Documents on the UNIX System: Using the +-ms Macros with Troff and Nroff}, M.@tie{}E.@: Lesk, Bell Laboratories, +1978} +@c XXX: We support RT anyway; maybe we should stop? + +@item +The error-handling policy of @code{groff} @file{ms} is to detect and +report errors, rather than to ignore them silently. + +@item +Tenth Edition @c possibly 9th +Research Unix supported @code{P1}/@code{P2} macros to bracket code +examples; @code{groff} @file{ms} does not. + +@item +@code{groff} @file{ms} does not work in GNU @code{troff}'s +@acronym{AT&T} compatibility mode. If loaded when that mode is enabled, +it aborts processing with a diagnostic message. + +@item +Multiple line spacing is not supported. Use a larger vertical spacing +instead. + +@item +@code{groff} @file{ms} uses the same header and footer defaults in both +@code{nroff} and @code{troff} modes as @acronym{AT&T} @file{ms} does in +@code{troff} mode; @acronym{AT&T}'s default in @code{nroff} mode is to +put the date, in U.S.@: traditional format (e.g., ``January 1, 2021''), +in the center footer (the @code{CF} string). + +@item +Many @code{groff} @file{ms} macros, including those for paragraphs, +headings, and displays, cause a reset of paragraph rendering parameters, +and may change the indentation; they do so not by incrementing or +decrementing it, but by setting it absolutely. This can cause problems +for documents that define additional macros of their own that try to +manipulate indentation. Use the @file{ms} @code{RS} and @code{RE} +macros instead of the @code{in} request. + +@item +@cindex fractional type sizes in @file{ms} macros +@cindex @file{ms} macros, fractional type sizes in +@acronym{AT&T} @file{ms} interpreted the values of the registers +@code{PS} and @code{VS} in points, and did not support the use of +scaling units with them. @code{groff} @file{ms} interprets values of +the registers @code{PS}, @code{VS}, @code{FPS}, and @code{FVS} equal to +or larger than@tie{}1,000 (one thousand) as decimal fractions multiplied +by@tie{}1,000.@footnote{Register values are converted to and stored as +basic units. @xref{Measurements}.} This threshold makes use of a +scaling unit with these parameters practical for high-resolution +devices while preserving backward compatibility. It also permits +expression of non-integral type sizes. For example, @samp{groff +-rPS=10.5p} at the shell prompt is equivalent to placing @samp{.nr PS +10.5p} at the beginning of the document. + +@item +@acronym{AT&T} @file{ms}'s @code{AU} macro supported arguments used with +some document types; @code{groff} @file{ms} does not. + +@item +Right-aligned displays are available. The @acronym{AT&T} @file{ms} +manual observes that ``it is tempting to assume that @samp{.DS R} will +right adjust lines, but it doesn't work''. In @code{groff} @file{ms}, +it does. + +@item +To make @code{groff} @file{ms} use the default page offset (which also +specifies the left margin), the @code{PO} register must stay undefined +until the first @file{ms} macro is called. + +This implies that @samp{\n[PO]} should not be used early in the +document, unless it is changed also: accessing an undefined register +automatically defines it. + +@item +@code{groff} @file{ms} supports the @code{PN} register, but it is not +necessary; you can access the page number via the usual @code{%} +register and invoke the @code{af} request to assign a different format +to it if desired.@footnote{If you redefine the @file{ms} @code{PT} macro +@c I wouldn't mention that, but Lesk 1978 encourages doing so. :-/ +and desire special treatment of certain page numbers (like @samp{1}), +you may need to handle a non-Arabic page number format, as @code{groff} +@file{ms}'s @code{PT} does; see the macro package source. @code{groff} +@file{ms} aliases the @code{PN} register to @code{%}.} + +@item +The @acronym{AT&T} @file{ms} manual documents registers @code{CW} and +@code{GW} as setting the default column width and ``intercolumn gap'', +respectively, and which applied when @code{MC} was called with fewer +than two arguments. @code{groff} @file{ms} instead treats @code{MC} +without arguments as synonymous with @code{2C}; there is thus no +occasion for a default column width register. Further, the @code{MINGW} +register and the second argument to @code{MC} specify a @emph{minimum} +space between columns, not the fixed gutter width of @acronym{AT&T} +@file{ms}. + +@item +The @acronym{AT&T} @file{ms} manual did not document the @code{QI} +register; Berkeley and @code{groff} @file{ms} do. +@end itemize + +@Defmpreg {GS, ms} +The register @code{GS} is set to@tie{}1 by the @code{groff} @file{ms} +macros, but is not used by the @acronym{AT&T} @file{ms} package. +Documents that need to determine whether they are being formatted with +@code{groff} @file{ms} or another implementation should test this +register. +@endDefmpreg + +@menu +* Missing Unix Version 7 ms Macros:: +@end menu + +@c --------------------------------------------------------------------- + +@node Missing Unix Version 7 ms Macros, , Differences from AT&T ms, Differences from AT&T ms +@subsubsection Unix Version 7 @file{ms} macros not implemented by @code{groff} @file{ms} + +Several macros described in the Unix Version@tie{}7 @file{ms} +documentation are unimplemented by @code{groff} @file{ms} because they +are specific to the requirements of documents produced internally by +Bell Laboratories, some of which also require a glyph for the Bell +System logo that @code{groff} does not support. These macros +implemented several document type formats +(@code{EG}, @c engineer's notes +@code{IM}, @c internal memorandum +@code{MF}, @c memorandum for file +@code{MR}, @c memorandum for record +@code{TM}, @c technical memorandum +@code{TR}), @c technical report +were meaningful only in conjunction with the use of certain document +types +(@code{AT}, @c attachments +@code{CS}, @c cover sheet info for `TM` documents +@code{CT}, @c copies to +@code{OK}, @c "other keywords" for `TM` documents +@code{SG}), @c signatures for `TM` documents +stored the postal addresses of Bell Labs sites +(@code{HO}, @c Holmdel +@code{IH}, @c Naperville +@code{MH}, @c Murray Hill +@code{PY}, @c Piscataway +@code{WH}), @c Whippany +or lacked a stable definition over time +(@code{UX}). @c Unix; on 1st use, add footnote id'ing trademark owner +To compatibly render historical @file{ms} documents using these macros, +we advise your documents to invoke the @code{rm} request to remove any +such macros it uses and then define replacements with an authentically +typeset original at hand.@footnote{The removal beforehand is necessary +because @code{groff} @file{ms} aliases these macros to a diagnostic +macro, and you want to redefine the aliased name, not its target.} For +informal purposes, a simple definition of @code{UX} should maintain the +readability of the document's substance. + +@CartoucheExample +.rm UX +.ds UX Unix\" +@endCartoucheExample + +@c --------------------------------------------------------------------- + +@node ms Legacy Features, ms Naming Conventions, Differences from AT&T ms, ms +@subsection Legacy Features +@cindex @file{ms} macros, strings +@cindex @file{ms} macros, special characters +@cindex @file{ms} macros, accent marks +@cindex accent marks [@file{ms}] +@cindex special characters [@file{ms}] +@cindex strings [@file{ms}] + +@code{groff} @file{ms} retains some legacy features solely to support +formatting of historical documents; contemporary ones should not use +them because they can render poorly. See the @cite{groff_char@r{(7)}} +man page. + +@unnumberedsubsubsec AT&T accent mark strings + +AT&T @file{ms} defined accent mark strings as follows. + +@Defmpstr {@code{'}, ms} +Apply acute accent to subsequent glyph. +@endDefmpstr + +@Defmpstr {@code{`}, ms} +Apply grave accent to subsequent glyph. +@endDefmpstr + +@Defmpstr {:, ms} +Apply dieresis (umlaut) to subsequent glyph. +@endDefmpstr + +@Defmpstr {^, ms} +Apply circumflex accent to subsequent glyph. +@endDefmpstr + +@Defmpstr {~, ms} +Apply tilde accent to subsequent glyph. +@endDefmpstr + +@Defmpstr {C, ms} +Apply caron to subsequent glyph. +@endDefmpstr + +@Defmpstr {\,, ms} +Apply cedilla to subsequent glyph. +@endDefmpstr + +@unnumberedsubsubsec Berkeley accent mark and glyph strings + +Berkeley @file{ms} offered an @code{AM} macro; calling it redefined the +AT&T accent mark strings (except for @samp{\*C}), applied them to the +@emph{preceding} glyph, and defined additional strings, some for spacing +glyphs. + +@Defmac {AM, , ms} +Enable alternative accent mark and glyph-producing strings. +@endDefmac + +@Defmpstr {@code{'}, ms} +Apply acute accent to preceding glyph. +@endDefmpstr + +@Defmpstr {@code{`}, ms} +Apply grave accent to preceding glyph. +@endDefmpstr + +@Defmpstr {:, ms} +Apply dieresis (umlaut) to preceding glyph. +@endDefmpstr + +@Defmpstr {^, ms} +Apply circumflex accent to preceding glyph. +@endDefmpstr + +@Defmpstr {~, ms} +Apply tilde accent to preceding glyph. +@endDefmpstr + +@Defmpstr {\,, ms} +Apply cedilla to preceding glyph. +@endDefmpstr + +@Defmpstr {/, ms} +Apply stroke (slash) to preceding glyph. +@endDefmpstr + +@Defmpstr {v, ms} +Apply caron to preceding glyph. +@endDefmpstr + +@Defmpstr {_, ms} +Apply macron to preceding glyph. +@endDefmpstr + +@Defmpstr {., ms} +Apply underdot to preceding glyph. +@endDefmpstr + +@Defmpstr {o, ms} +Apply ring accent to preceding glyph. +@endDefmpstr + +@Defmpstr {?, ms} +Interpolate inverted question mark. +@endDefmpstr + +@Defmpstr {!, ms} +Interpolate inverted exclamation mark. +@endDefmpstr + +@Defmpstr {8, ms} +Interpolate small letter sharp s. +@endDefmpstr + +@Defmpstr {q, ms} +Interpolate small letter o with hook accent (ogonek). +@endDefmpstr + +@Defmpstr {3, ms} +Interpolate small letter yogh. +@endDefmpstr + +@Defmpstr {d-, ms} +Interpolate small letter eth. +@endDefmpstr + +@Defmpstr {D-, ms} +Interpolate capital letter eth. +@endDefmpstr + +@Defmpstr {th, ms} +Interpolate small letter thorn. +@endDefmpstr + +@Defmpstr {Th, ms} +Interpolate capital letter thorn. +@endDefmpstr + +@Defmpstr {ae, ms} +Interpolate small æ ligature. +@endDefmpstr + +@Defmpstr {Ae, ms} +Interpolate capital Æ ligature. +@endDefmpstr + +@Defmpstr {oe, ms} +Interpolate small oe ligature. +@endDefmpstr + +@Defmpstr {OE, ms} +Interpolate capital OE ligature. +@endDefmpstr + +@c --------------------------------------------------------------------- + +@node ms Naming Conventions, , ms Legacy Features, ms +@subsection Naming Conventions +@cindex @file{ms} macros, naming conventions +@cindex naming conventions, @file{ms} macros + +The following conventions are used for names of macros, strings, and +registers. External names available to documents that use the +@code{groff} @file{ms} macros contain only uppercase letters and digits. + +Internally, the macros are divided into modules. Conventions for +identifier names are as follows. + +@itemize @bullet +@item +Names used only within one module are of the form +@var{module}@code{*}@var{name}. + +@item +Names used outside the module in which they are defined are of the form +@var{module}@code{@@}@var{name}. + +@item +Names associated with a particular environment are of the form +@var{environment}@code{:}@var{name}; these are used only within the +@code{par} module. + +@item +@var{name} does not have a module prefix. + +@item +Constructed names used to implement arrays are of the form +@var{array}@code{!}@var{index}. +@end itemize + +Thus the @code{groff} @file{ms} macros reserve the following names. + +@itemize @bullet +@item +Names containing the characters @code{*}, @code{@@}, and@tie{}@code{:}. + +@item +Names containing only uppercase letters and digits. +@end itemize + + +@c ===================================================================== +@c ===================================================================== + +@node GNU troff Reference, File Formats, Major Macro Packages, Top +@chapter GNU @code{troff} Reference +@cindex reference, @code{gtroff} +@cindex @code{gtroff}, reference + +This chapter covers @emph{all} of the facilities of the GNU +@code{troff} formatting engine. Users of macro packages may skip it if +not interested in details. + + +@menu +* Text:: +* Page Geometry:: +* Measurements:: +* Numeric Expressions:: +* Identifiers:: +* Formatter Instructions:: +* Comments:: +* Registers:: +* Manipulating Filling and Adjustment:: +* Manipulating Hyphenation:: +* Manipulating Spacing:: +* Tabs and Fields:: +* Character Translations:: +* @code{troff} and @code{nroff} Modes:: +* Line Layout:: +* Line Continuation:: +* Page Layout:: +* Page Control:: +* Using Fonts:: +* Manipulating Type Size and Vertical Spacing:: +* Colors:: +* Strings:: +* Conditionals and Loops:: +* Writing Macros:: +* Page Motions:: +* Drawing Geometric Objects:: +* Deferring Output:: +* Traps:: +* Diversions:: +* Punning Names:: +* Environments:: +* Suppressing Output:: +* I/O:: +* Postprocessor Access:: +* Miscellaneous:: +* Gtroff Internals:: +* Debugging:: +* Implementation Differences:: +@end menu + + +@c ===================================================================== + +@c BEGIN Keep roughly parallel with roff(7) section "Concepts". +@node Text, Measurements, GNU troff Reference, GNU troff Reference +@section Text +@cindex text, GNU @code{troff} processing + +@acronym{AT&T} @code{troff} was designed to take input as it would be +composed on a typewriter, including the teletypewriters used as early +computer terminals, and relieve the user drafting a document of concern +with details like line length, hyphenation breaking, and the achievement +of straight margins. Early in its development, the program gained the +ability to prepare output for a phototypesetter; a document could then +be prepared for output to either a teletypewriter, a phototypesetter, or +both. GNU @code{troff} continues this tradition of permitting an author +to compose a single master version of a document which can then be +rendered for a variety of output formats or devices. + +@code{roff} input files contain text interspersed with instructions to +control the formatter. Even in the absence of such instructions, GNU +@code{troff} still processes its input in several ways, by filling, +hyphenating, breaking, and adjusting it, and supplementing it with +inter-sentence space. + +@menu +* Filling:: +* Hyphenation:: +* Sentences:: +* Breaking:: +* Adjustment:: +* Tabs and Leaders:: +* Requests and Macros:: +* Macro Packages:: +* Input Encodings:: +* Input Conventions:: +@end menu + +@c --------------------------------------------------------------------- + +@node Filling, Sentences, Text, Text +@subsection Filling + +When GNU @code{troff} starts up, it obtains information about the device +for which it is preparing output.@footnote{@xref{Device and Font +Description Files}.} An essential property is the length of the output +line, such as ``6.5 inches''. + +@cindex word, definition of +@cindex filling +GNU @code{troff} interprets plain text files employing the Unix +line-ending convention. It reads input a character at a time, +collecting words as it goes, and fits as many words together on an +output line as it can---this is known as @dfn{filling}. To GNU +@code{troff}, a @dfn{word} is any sequence of one or more characters +that aren't spaces or newlines. The exceptions separate +words.@footnote{@slanted{Tabs} and @slanted{leaders} also separate +words. @slanted{Escape sequences} can function as word characters, word +separators, or neither---the last simply have no effect on GNU +@code{troff}'s idea of whether an input character is within a word. +We'll discuss all of these in due course.} To disable filling, see +@ref{Manipulating Filling and Adjustment}. + +@Example +It is a truth universally acknowledged +that a single man in possession of a +good fortune must be in want of a wife. + @result{} It is a truth universally acknowledged that a + @result{} single man in possession of a good fortune must + @result{} be in want of a wife. +@endExample + +@c --------------------------------------------------------------------- + +@node Sentences, Hyphenation, Filling, Text +@subsection Sentences +@cindex sentences + +A passionate debate has raged for decades among writers of the English +language over whether more space should appear between adjacent +sentences than between words within a sentence, and if so, how much, and +what other circumstances should influence this spacing.@footnote{A +well-researched jeremiad appreciated by @code{groff} contributors on +both sides of the sentence-spacing debate can be found at +@uref{https://web.archive.org@//web@//20171217060354@//http://www.heracliteanriver.com@//?p=324}.} +GNU @code{troff} follows the example of @acronym{AT&T} @code{troff}; +it attempts to detect the boundaries between sentences, and supplies +additional inter-sentence space between them. + +@Example +Hello, world! +Welcome to groff. + @result{} Hello, world! Welcome to groff. +@endExample + +@cindex end-of-sentence characters +@cindex sentence space +@cindex space between sentences +@cindex French spacing +GNU @code{troff} flags certain characters (normally @samp{!}, @samp{?}, +and @samp{.}) as potentially ending a sentence. When GNU @code{troff} +encounters one of these @dfn{end-of-sentence characters} at the end of +an input line, or one of them is followed by two (unescaped) spaces on +the same input line, it appends an inter-word space followed by an +inter-sentence space in the output. + +@Example +R. Harper subscribes to a maxim of P. T. Barnum. + @result{} R. Harper subscribes to a maxim of P. T. Barnum. +@endExample + +In the above example, inter-sentence space is not added after @samp{P.} +or @samp{T.} because the periods do not occur at the end of an input +line, nor are they followed by two or more spaces. Let's imagine that +we've heard something about defamation from Mr.@: Harper's attorney, +recast the sentence, and reflowed it in our text editor. + +@Example +I submit that R. Harper subscribes to a maxim of P. T. +Barnum. + @result{} I submit that R. Harper subscribes to a maxim of + @result{} P. T. Barnum. +@endExample + +``Barnum'' doesn't begin a sentence! What to do? Let us meet our first +@dfn{escape sequence}, a series of input characters that give +instructions to GNU @code{troff} instead of being used to construct +output device glyphs.@footnote{This statement oversimplifies; there are +escape sequences whose purpose is precisely to produce glyphs on the +output device, and input characters that @emph{aren't} part of escape +sequences can undergo a great deal of processing before getting to the +output.} An escape sequence begins with the backslash character @code{\} +by default, an uncommon character in natural language text, and is +@emph{always} followed by at least one other character, hence the term +``sequence''. + +@cindex @code{\&}, at end of sentence +The dummy character escape sequence @code{\&} can be used after an +end-of-sentence character to defeat end-of-sentence detection on a +per-instance basis. We can therefore rewrite our input more +defensively. + +@Example +I submit that R.\& Harper subscribes to a maxim of P.\& +T.\& Barnum. + @result{} I submit that R. Harper subscribes to a maxim of + @result{} P. T. Barnum. +@endExample + +Adding text caused our input to wrap; now, we don't need @code{\&} after +@samp{T.} but we do after @samp{P.}. Consistent use of the escape +sequence ensures that potential sentence boundaries are robust to +editing activities. Further advice along these lines will follow in +@ref{Input Conventions}. + +@cindex end-of-sentence transparent characters +@cindex characters, end-of-sentence transparent +@cindex @code{dg} glyph, at end of sentence +@cindex @code{dd} glyph, at end of sentence +@cindex @code{rq} glyph, at end of sentence +@cindex @code{cq} glyph, at end of sentence +@cindex @code{"}, at end of sentence +@cindex @code{'}, at end of sentence +@cindex @code{)}, at end of sentence +@cindex @code{]}, at end of sentence +@cindex @code{*}, at end of sentence +@cindex special characters +@cindex characters, special +Normally, the occurrence of a visible non-end-of-sentence character (as +opposed to a space or tab) immediately after an end-of-sentence +character cancels detection of the end of a sentence. For example, it +would be incorrect for GNU @code{troff} to infer the end of a sentence +after the dot in @samp{3.14159}. However, several characters are +treated @emph{transparently} after the occurrence of an end-of-sentence +character. That is, GNU @code{troff} does not cancel end-of-sentence +detection when it processes them. This is because such characters are +often used as footnote markers or to close quotations and +parentheticals. The default set is @samp{"}, @samp{'}, @samp{)}, +@samp{]}, @samp{*}, @code{\[dg]}, @code{\[dd]}, @code{\[rq]}, and +@code{\[cq]}. The last four are examples of @dfn{special characters}, +escape sequences whose purpose is to obtain glyphs that are not easily +typed at the keyboard, or which have special meaning to GNU @code{troff} +(like @code{\} itself).@footnote{The mnemonics for the special +characters shown here are ``dagger'', ``double dagger'', ``right +(double) quote'', and ``closing (single) quote''. See the +@cite{groff_char@r{(7)}} man page.} + +@Example +\[lq]The idea that the poor should have leisure has always +been shocking to the rich.\[rq] +(Bertrand Russell, 1935) +@c XXX: @iftex puts a blank line on the output. This seems like a bug. +@c @newline works around it. But we need a weird inverse indent. +@iftex @ + @result{} @quotedblleft{}The idea that the poor should have + @result{} leisure has always been shocking to + @result{} the rich.@quotedblright{} (Bertrand Russell, 1935) +@end iftex +@ifnottex + @result{} "The idea that the poor should have + @result{} leisure has always been shocking to + @result{} the rich." (Bertrand Russell, 1935) +@end ifnottex +@endExample + +The sets of characters that potentially end sentences or are transparent +to sentence endings are configurable. See the @code{cflags} request in +@ref{Using Symbols}. To change the additional inter-sentence space +amount---even to remove it entirely---see @ref{Manipulating Filling and +Adjustment}. + +@c --------------------------------------------------------------------- + +@node Hyphenation, Breaking, Sentences, Text +@subsection Hyphenation +@cindex hyphenation + +When an output line is nearly full, it is uncommon for the next word +collected from the input to exactly fill it---typically, there is room +left over only for part of the next word. The process of splitting a +word so that it appears partially on one line (with a hyphen to indicate +to the reader that the word has been broken) with its remainder on the +next is @dfn{hyphenation}. Hyphenation points can be manually +specified; GNU @code{troff} also uses a hyphenation algorithm and +language-specific pattern files (based on those used in @TeX{}) to +decide which words can be hyphenated and where. + +Hyphenation does not always occur even when the hyphenation rules for a +word allow it; it can be disabled, and when not disabled there are +several parameters that can prevent it in certain circumstances. +@xref{Manipulating Hyphenation}. + +@c --------------------------------------------------------------------- + +@node Breaking, Adjustment, Hyphenation, Text +@subsection Breaking +@cindex break +@cindex implicit line break +@cindex line break, output +@cindex output line break + +Once an output line is full, the next word (or remainder of a hyphenated +one) is placed on a different output line; this is called a @dfn{break}. +In this manual and in @code{roff} discussions generally, a ``break'' if +not further qualified always refers to the termination of an output +line. When the formatter is filling text, it introduces breaks +automatically to keep output lines from exceeding the configured line +length. After an automatic break, GNU @code{troff} adjusts the line if +applicable (see below), and then resumes collecting and filling text on +the next output line. + +Sometimes, a line cannot be broken automatically. This usually does +not happen with natural language text unless the output line length has +been manipulated to be extremely short, but it can with specialized +text like program source code. We can use @code{perl} at the shell +prompt to contrive an example of failure to break the line. We also +employ the @option{-z} option to suppress normal output. + +@Example +$ perl -e 'print "#" x 80, "\n";' | nroff -z + @error{} warning: cannot break line +@endExample + +The remedy for these cases is to tell GNU @code{troff} where the line +may be broken without hyphens. This is done with the non-printing break +point escape sequence @samp{\:}; see @ref{Manipulating Hyphenation}. + +@cindex blank line +@cindex empty line +@cindex line, blank +@cindex blank line macro (@code{blm}) +What if the document author wants to stop filling lines temporarily, for +instance to start a new paragraph? There are several solutions. A +blank input line not only causes a break, but by default it also outputs +a one-line vertical space (effectively a blank output line). This +behavior can be modified; see @ref{Blank Line Traps}. Macro packages +may discourage or disable the blank line method of paragraphing in favor +of their own macros. + +@cindex leading spaces +@cindex spaces, leading and trailing +@cindex trailing spaces on text lines +@cindex leading space macro (@code{lsm}) +A line that begins with one or more spaces causes a break. The spaces +are output at the beginning of the next line without being +@emph{adjusted} (see below); however, this behavior can be modified +(@pxref{Leading Space Traps}). Again, macro packages may provide other +methods of producing indented paragraphs. Trailing spaces on text lines +are discarded.@footnote{``Text lines'' are defined in @ref{Requests and +Macros}.} + +What if the file ends before enough words have been collected to fill an +output line? Or the output line is exactly full but not yet broken, and +there is no more input? GNU @code{troff} interprets the end of input as +a break. Certain requests also cause breaks, implicitly or explicitly. +This is discussed in @ref{Manipulating Filling and Adjustment}. + +@c --------------------------------------------------------------------- + +@node Adjustment, Tabs and Leaders, Breaking, Text +@subsection Adjustment + +@cindex extra spaces between words +After GNU @code{troff} performs an automatic break, it may then +@dfn{adjust} the line, widening inter-word spaces until the text reaches +the right margin. Extra spaces between words are preserved. Leading +and trailing spaces are handled as noted above. Text can be aligned to +the left or right margin only, or centered; see @ref{Manipulating +Filling and Adjustment}. +@c END Keep roughly parallel with roff(7) section "Concepts". + +@c --------------------------------------------------------------------- + +@node Tabs and Leaders, Input Conventions, Adjustment, Text +@subsection Tabs and Leaders + +@cindex horizontal tab character +@cindex tab character +@cindex character, horizontal tab +@cindex leader character +@cindex character, leader +@cindex tab stops +@cindex stops, tab +GNU @code{troff} translates input horizontal tab characters (``tabs'') +and @key{Control+A} characters (``leaders'') into movements to the next +tab stop. Tabs simply move to the next tab stop; leaders place enough +periods to fill the space. Tab stops are by default located every half +inch measured from the drawing position corresponding to the beginning +of the input line; see @ref{Page Geometry}. Tabs and leaders do not +cause breaks and therefore do not interrupt filling. Below, we use +arrows @arrow{} and bullets @bullet{} to indicate input tabs and +leaders, respectively. + +@Example +1 +@arrow{} 2 @arrow{} 3 @bullet{} 4 +@arrow{} @bullet{} 5 +@result{} 1 2 3.......4 ........5 +@endExample + +Tabs and leaders lend themselves to table construction.@footnote{``Tab'' +is short for ``tabulation'', revealing the term's origin as a spacing +mechanism for table arrangement.} The tab and leader glyphs can be +configured, and further facilities for sophisticated table composition +are available; see @ref{Tabs and Fields}. There are many details to +track when using such low-level features, so most users turn to the +@cite{tbl@r{(1)}} preprocessor to lay out tables. + +@c --------------------------------------------------------------------- + +@node Requests and Macros, Macro Packages, Tabs and Leaders, Text +@subsection Requests and Macros + +We have now encountered almost all of the syntax there is in the +@code{roff} language, with an exception already noted in passing. +@cindex request +@cindex control character (@code{.}) +@cindex character, control (@code{.}) +@cindex no-break control character (@code{'}) +@cindex character, no-break control (@code{'}) +@cindex control character, no-break (@code{'}) +A @dfn{request} is an instruction to the formatter that occurs after a +@dfn{control character}, which is recognized at the beginning of an +input line. The regular control character is a dot (@code{.}). Its +counterpart, the @dfn{no-break control character}, a neutral apostrophe +(@code{'}), suppresses the break that is implied by some requests. +These characters were chosen because it is uncommon for lines of text in +natural languages to begin with them. +@cindex dummy character (@code{\&}), as control character suppressor +@cindex character, dummy (@code{\&}), as control character suppressor +If you require a formatted period or apostrophe (closing single +quotation mark) where GNU @code{troff} is expecting a control character, +prefix the dot or neutral apostrophe with the dummy character escape +sequence, @samp{\&}. + +@cindex control line +An input line beginning with a control character is called a +@dfn{control line}. +@cindex text line +Every line of input that is not a control line is a @dfn{text +line}.@footnote{The @code{\@key{RET}} escape sequence can alter how an +input line is classified; see @ref{Line Continuation}.} + +@cindex argument +Requests often take @dfn{arguments}, words (separated from the request +name and each other by spaces) that specify details of the action GNU +@code{troff} is expected to perform. If a request is meaningless +without arguments, it is typically ignored. + +GNU @code{troff}'s requests and escape sequences comprise the control +language of the formatter. Of key importance are the requests that +define macros. Macros are invoked like requests, enabling the request +repertoire to be extended or overridden.@footnote{Argument handling in +macros is more flexible but also more complex. @xref{Calling Macros}.} + +@cindex macro +@cindex calling a macro +@cindex interpolation +A @dfn{macro} can be thought of as an abbreviation you can define for a +collection of control and text lines. When the macro is @dfn{called} by +giving its name after a control character, it is replaced with what it +stands for. The process of textual replacement is known as +@dfn{interpolation}.@footnote{Some escape sequences undergo +interpolation as well.} Interpolations are handled as soon as they are +recognized, and once performed, a @code{roff} formatter scans the +replacement for further requests, macro calls, and escape sequences. + +In @code{roff} systems, the @code{de} request defines a +macro.@footnote{GNU @code{troff} offers additional ones. @xref{Writing +Macros}.} + +@Example +.de DATE +2020-11-14 +.. +@endExample + +@noindent +The foregoing input produces no output by itself; all we have done is +store some information. Observe the pair of dots that ends the macro +definition. This is a default; you can specify your own terminator for +the macro definition as the second argument to the @code{de} request. + +@Example +.de NAME ENDNAME +Heywood Jabuzzoff +.ENDNAME +@endExample + +In fact, the ending marker is itself the name of a macro to be +called, or a request to be invoked, if it is defined at the time its +control line is read. + +@Example +.de END +Big Rip +.. +.de START END +Big Bang +.END +.START + @result{} Big Rip Big Bang +@endExample + +@noindent +In the foregoing example, ``Big Rip'' printed before ``Big Bang'' +because its macro was @emph{called} first. Consider what would happen +if we dropped @code{END} from the @samp{.de START} line and added +@code{..} after @code{.END}. Would the order change? + +Let us consider a more elaborate example. + +@Example +.de DATE +2020-10-05 +.. +. +.de BOSS +D.\& Kruger, +J.\& Peterman +.. +. +.de NOTICE +Approved: +.DATE +by +.BOSS +.. +. +Insert tedious regulatory compliance paragraph here. + +.NOTICE + +Insert tedious liability disclaimer paragraph here. + +.NOTICE + @result{} Insert tedious regulatory compliance paragraph here. + @result{} + @result{} Approved: 2020-10-05 by D. Kruger, J. Peterman + @result{} + @result{} Insert tedious liability disclaimer paragraph here. + @result{} + @result{} Approved: 2020-10-05 by D. Kruger, J. Peterman +@endExample + +@noindent +The above document started with a series of control lines. Three macros +were defined, with a @code{de} request declaring each macro's name, and +the ``body'' of the macro starting on the next line and continuing until +a line with two dots @samp{@code{..}} marked its end. The text proper +began only after the macros were defined; this is a common pattern. +Only the @code{NOTICE} macro was called ``directly'' by the document; +@code{DATE} and @code{BOSS} were called only by @code{NOTICE} itself. +Escape sequences were used in @code{BOSS}, two levels of macro +interpolation deep. + +The advantage in typing and maintenance economy may not be obvious from +such a short example, but imagine a much longer document with dozens of +such paragraphs, each requiring a notice of managerial approval. +Consider what must happen if you are in charge of generating a new +version of such a document with a different date, for a different boss. +With well-chosen macros, you only have to change each datum in one +place. + +In practice, we would probably use strings (@pxref{Strings}) instead of +macros for such simple interpolations; what is important here is to +glimpse the potential of macros and the power of recursive +interpolation. + +We could have defined @code{DATE} and @code{BOSS} in the opposite order; +perhaps less obviously, we could also have defined them @emph{after} +@code{NOTICE}. ``Forward references'' like this are acceptable because +the body of a macro definition is not (completely) interpreted, but +stored instead (@pxref{Copy Mode}). While a macro is being defined (or +appended to), requests are not interpreted and macros not interpolated, +whereas some commonly used escape sequences @emph{are} interpreted. +@code{roff} systems also support recursive macro calls, as long as you +have a way to break the recursion (@pxref{Conditionals and Loops}). +Maintainable @code{roff} documents tend to arrange macro definitions to +minimize forward references. + +@c --------------------------------------------------------------------- + +@node Macro Packages, Input Encodings, Requests and Macros, Text +@subsection Macro Packages +@cindex macro package +@cindex package, macro + +@c TODO: Consider parallelizing with groff_tmac(5) "Description". +Macro definitions can be collected into @dfn{macro files}, @code{roff} +input files designed to produce no output themselves but instead ease +the preparation of other @code{roff} documents. There is no syntactical +difference between a macro file and any other @code{roff} document; only +its purpose distinguishes it. When a macro file is installed at a +standard location and suitable for use by a general audience, it is +often termed a @dfn{macro package}.@footnote{Macro files and packages +frequently define registers and strings as well.} Macro packages can be +loaded by supplying the @option{-m} option to GNU @command{troff} or a +@code{groff} front end. Alternatively, a document requiring a macro +package can load it with the @code{mso} (``macro source'') request. + +@c --------------------------------------------------------------------- + +@c TODO: Move a lot of this node to the "Invoking groff" chapter. Some +@c of the discussion is better placed in discussion of output drivers +@c (e.g., what character encodings _they_ support for output and their +@c responsibility for converting to them) as well. + +@node Input Encodings, Input Conventions, Macro Packages, Text +@subsection Input Encodings + +The @command{groff} command's @option{-k} option calls the +@command{preconv} preprocessor to perform input character encoding +conversions. Input to the GNU @code{troff} formatter itself, on the +other hand, must be in one of two encodings it can recognize. + +@table @code +@item cp1047 +@cindex encoding, input, @acronym{EBCDIC} +@cindex @acronym{EBCDIC}, input encoding +@cindex input encoding, @acronym{EBCDIC} +@cindex encoding, input, code page 1047 +@cindex code page 1047, input encoding +@cindex input encoding, code page 1047 +@cindex IBM code page 1047 input encoding +@pindex cp1047.tmac +The code page 1047 input encoding works only on @acronym{EBCDIC} +platforms (and conversely, the other input encodings don't work with +@acronym{EBCDIC}); the file @file{cp1047.tmac} is loaded at startup. + +@item latin1 +@cindex encoding, input, @w{Latin-1} (ISO @w{8859-1}) +@cindex @w{Latin-1} (ISO @w{8859-1}), input encoding +@cindex ISO @w{8859-1} (@w{Latin-1}), input encoding +@cindex input encoding, @w{Latin-1} (ISO @w{8859-1}) +@pindex latin1.tmac +ISO @w{Latin-1}, an encoding for Western European languages, is the +default input encoding on non-@acronym{EBCDIC} platforms; the file +@file{latin1.tmac} is loaded at startup. +@end table + +@noindent +Any document that is encoded in ISO 646:1991 (a descendant of USAS +@w{X3.4-1968} or ``US-ASCII''), or, equivalently, uses only code points +from the ``C0 Controls'' and ``Basic Latin'' parts of the Unicode +character set is also a valid ISO @w{Latin-1} document; the standards +are interchangeable in their first 128 code points.@footnote{The +@emph{semantics} of certain punctuation code points have gotten stricter +with the successive standards, a cause of some frustration among man +page writers; see the @cite{groff_char@r{(7)}} man page.} + +Other encodings are supported by means of macro packages. + +@table @code +@item latin2 +@cindex encoding, input, @w{Latin-2} (ISO @w{8859-2}) +@cindex @w{Latin-2} (ISO @w{8859-2}), input encoding +@cindex ISO @w{8859-2} (@w{Latin-2}), input encoding +@cindex input encoding, @w{Latin-2} (ISO @w{8859-2}) +@pindex latin2.tmac +To use ISO @w{Latin-2}, an encoding for Central and Eastern European +languages, invoke @w{@samp{.mso latin2.tmac}} at the beginning of your +document or supply @samp{-mlatin2} as a command-line argument to +@code{groff}. + +@item latin5 +@cindex encoding, input, @w{Latin-5} (ISO @w{8859-9}) +@cindex @w{Latin-5} (ISO @w{8859-9}), input encoding +@cindex ISO @w{8859-9} (@w{Latin-5}), input encoding +@cindex input encoding, @w{Latin-5} (ISO @w{8859-9}) +@pindex latin5.tmac +To use ISO @w{Latin-5}, an encoding for the Turkish language, invoke +@w{@samp{.mso latin5.tmac}} at the beginning of your document or +supply @samp{-mlatin5} as a command-line argument to @code{groff}. + +@item latin9 +@cindex encoding, input, @w{Latin-9} (ISO @w{8859-15}) +@cindex @w{Latin-9} (ISO @w{8859-15}), input encoding +@cindex ISO @w{8859-15} (@w{Latin-9}), input encoding +@cindex input encoding, @w{Latin-9} (ISO @w{8859-15}) +@pindex latin9.tmac +ISO @w{Latin-9} succeeds @w{Latin-1}; it includes a Euro sign and better +glyph coverage for French. To use this encoding, invoke @w{@samp{.mso +latin9.tmac}} at the beginning of your document or supply +@samp{-mlatin9} as a command-line argument to @code{groff}. +@end table + +Some characters from an input encoding may not be available with a +particular output driver, or their glyphs may not have representation in +the font used. For terminal devices, fallbacks are defined, like +@samp{EUR} for the Euro sign and @samp{(C)} for the copyright sign. For +typesetter devices, you may need to ``mount'' fonts that support glyphs +required by the document. @xref{Font Positions}. + +@pindex freeeuro.pfa +@pindex ec.tmac +Because a Euro glyph was not historically defined in PostScript fonts, +@code{groff} comes with a font called @file{freeeuro.pfa} that provides +the Euro in several styles. Standard PostScript fonts contain the +glyphs from @w{Latin-5} and @w{Latin-9} that @w{Latin-1} lacks, so these +encodings are supported for the @option{ps} and @option{pdf} output +devices as @code{groff} ships, while @w{Latin-2} is not. + +Unicode supports characters from all other input encodings; the +@option{utf8} output driver for terminals therefore does as well. The +DVI output driver supports the @w{Latin-2} and @w{Latin-9} encodings if +the command-line option @option{-mec} is used as well. @footnote{The +DVI output device defaults to using the Computer Modern (CM) fonts; +@file{ec.tmac} loads the EC fonts instead, which provide Euro +@samp{\[Eu]} and per mille @samp{\[%0]} glyphs.} + +@c --------------------------------------------------------------------- + +@node Input Conventions, , Input Encodings, Text +@subsection Input Conventions +@cindex input conventions +@cindex conventions for input + +Since GNU @code{troff} fills text automatically, it is common practice +in the @code{roff} language to avoid visual composition of text in input +files: the esthetic appeal of the formatted output is what matters. +Therefore, @code{roff} input should be arranged such that it is easy for +authors and maintainers to compose and develop the document, understand +the syntax of @code{roff} requests, macro calls, and preprocessor +languages used, and predict the behavior of the formatter. Several +traditions have accrued in service of these goals. + +@itemize @bullet +@item +Follow sentence endings in the input with newlines to ease their +recognition (@pxref{Sentences}). It is frequently convenient to end +text lines after colons and semicolons as well, as these typically +precede independent clauses. Consider doing so after commas; they often +occur in lists that become easy to scan when itemized by line, or +constitute supplements to the sentence that are added, deleted, or +updated to clarify it. Parenthetical and quoted phrases are also good +candidates for placement on text lines by themselves. + +@item +Set your text editor's line length to 72 characters or +fewer.@footnote{Emacs: @code{fill-column: 72}; Vim: @code{textwidth=72}} +This limit, combined with the previous item of advice, makes it less +common that an input line will wrap in your text editor, and thus will +help you perceive excessively long constructions in your text. Recall +that natural languages originate in speech, not writing, and that +punctuation is correlated with pauses for breathing and changes in +prosody. + +@item +Use @code{\&} after @samp{!}, @samp{?}, and @samp{.} if they are +followed by space, tab, or newline characters and don't end a sentence. + +@item +In filled text lines, use @code{\&} before @samp{.} and @samp{'} if they +are preceded by space, so that reflowing the input doesn't turn them +into control lines. + +@item +Do not use spaces to perform indentation or align columns of a table. +Leading spaces are reliable when text is not being filled. + +@item +Comment your document. It is never too soon to apply comments to +record information of use to future document maintainers (including your +future self). We thus introduce another escape sequence, @code{\"}, +which causes GNU @code{troff} to ignore the remainder of the input line. + +@item +Use the empty request---a control character followed immediately by a +newline---to visually manage separation of material in input files. +Many of the @code{groff} project's own documents use an empty request +between sentences, after macro definitions, and where a break is +expected, and two empty requests between paragraphs or other requests or +macro calls that will introduce vertical space into the document. + +You can combine the empty request with the comment escape sequence to +include whole-line comments in your document, and even ``comment out'' +sections of it. +@end itemize + +We conclude this section with an example sufficiently long to illustrate +most of the above suggestions in practice. For the purpose of fitting +the example between the margins of this manual with the font used for +its typeset version, we have shortened the input line length to 56 +columns. As before, an arrow @arrow{} indicates a tab character. + +@c Wrap example at 56 columns (not counting @arrow{}). +@CartoucheExample +.\" nroff this_file.roff | less +.\" groff -T ps this_file.roff > this_file.ps +@arrow{}The theory of relativity is intimately connected with +the theory of space and time. +. +I shall therefore begin with a brief investigation of +the origin of our ideas of space and time, +although in doing so I know that I introduce a +controversial subject. \" remainder of paragraph elided +. +. + +@arrow{}The experiences of an individual appear to us arranged +in a series of events; +in this series the single events which we remember +appear to be ordered according to the criterion of +\[lq]earlier\[rq] and \[lq]later\[rq], \" punct swapped +which cannot be analysed further. +. +There exists, +therefore, +for the individual, +an I-time, +or subjective time. +. +This itself is not measurable. +. +I can, +indeed, +associate numbers with the events, +in such a way that the greater number is associated with +the later event than with an earlier one; +but the nature of this association may be quite +arbitrary. +. +This association I can define by means of a clock by +comparing the order of events furnished by the clock +with the order of a given series of events. +. +We understand by a clock something which provides a +series of events which can be counted, +and which has other properties of which we shall speak +later. +.\" Albert Einstein, _The Meaning of Relativity_, 1922 +@endCartoucheExample + +@node Page Geometry, Measurements, Text, GNU troff Reference +@section Page Geometry +@cindex page, geometry of +@cindex geometry, page + +@code{roff} systems format text under certain assumptions about the size +of the output medium, or page. For the formatter to correctly break a +line it is filling, it must know the line length, which it derives from +the page width (@pxref{Line Layout}). For it to decide whether to write +an output line to the current page or wait until the next one, it must +know the page length (@pxref{Page Layout}). + +@cindex device resolution +@cindex resolution, device +@cindex basic units +@cindex units, basic +@cindex machine units +@cindex units, machine +A device's @dfn{resolution} converts practical units like inches or +centimeters to @dfn{basic units}, a convenient length measure for the +output device or file format. The formatter and output driver use basic +units to reckon page measurements. The device description file defines +its resolution and page dimensions (@pxref{DESC File Format}). + +@cindex page +A @dfn{page} is a two-dimensional structure upon which a @code{roff} +system imposes a rectangular coordinate system with its upper left +corner as the origin. Coordinate values are in basic units and increase +down and to the right. Useful ones are therefore always positive and +within numeric ranges corresponding to the page boundaries. + +@cindex drawing position +@cindex position, drawing +While the formatter (and, later, output driver) is processing a page, it +keeps track of its @dfn{drawing position}, which is the location at +which the next glyph will be written, from which the next motion will be +measured, or where a geometric object will commence rendering. +@cindex text baseline +@cindex baseline, text +Notionally, glyphs are drawn from the text baseline upward and to the +right.@footnote{@code{groff} does not yet support right-to-left +scripts.} The @dfn{text baseline} is a (usually invisible) line upon +which the glyphs of a typeface are aligned. A glyph therefore +``starts'' at its bottom-left corner. If drawn at the origin, a typical +letter glyph would lie partially or wholly off the page, depending on +whether, like ``g'', it features a descender below the baseline. + +@cindex page offset +@cindex offset, page +Such a situation is nearly always undesirable. It is furthermore +conventional not to write or draw at the extreme edges of the page. +Therefore the initial drawing position of a @code{roff} formatter is not +at the origin, but below and to the right of it. This rightward shift +from the left edge is known as the @dfn{page +offset}.@footnote{@code{groff}'s terminal output devices have page +offsets of zero.} The downward shift leaves room for a text output +line. + +Text is arranged on a one-dimensional lattice of text baselines from the +top to the bottom of the page. +@cindex vertical spacing +@cindex spacing, vertical +@cindex vee +@dfn{Vertical spacing} is the distance between adjacent text baselines. +Typographic tradition sets this quantity to 120% of the type size. The +initial drawing position is one unit of vertical spacing below the page +top. Typographers term this unit a @slanted{vee}. + +@cindex page break +@cindex break, page +@cindex page ejection +@cindex ejection, page +Vertical spacing has an impact on page-breaking decisions. Generally, +when a break occurs, the formatter moves the drawing position to the +next text baseline automatically. If the formatter were already writing +to the last line that would fit on the page, advancing by one vee would +place the next text baseline off the page. Rather than let that happen, +@code{roff} formatters instruct the output driver to eject the page, +start a new one, and again set the drawing position to one vee below the +page top; this is a @dfn{page break}. + +When the last line of input text corresponds to the last output line +that fits on the page, the break caused by the end of input will also +break the page, producing a useless blank one. Macro packages keep +users from having to confront this difficulty by setting ``traps'' +(@pxref{Traps}); moreover, all but the simplest page layouts tend to +have headers and footers, or at least bear vertical margins larger than +one vee. + + +@c ===================================================================== +@c TODO: Add a section here about interpolations and input processing. +@c +@c We need to level up the reader's macro brain from reasoning about +@c interpolation at the scope of input lines to interpolations _within_ +@c lines. It is also a good time to introduce the \n and \* escape +@c sequences to avoid painful, "WTF"-producing forward references later. +@c Some materal from groff_mm(7) might be adaptable to this purpose. +@c +@c Earlier material from @Defesc{\\n}: +@c "This means that the value of the register is expanded in place while +@c GNU @code{troff} is parsing the input line. Nested assignments (also +@c called indirect assignments) are possible." +@c +@c We can probably drop the term "indirect assignments"; there's nothing +@c special about these--they are a consequence of *roffs' left-to-right +@c parsing and they apply to escape sequences in general. +@c ===================================================================== + +@c BEGIN Keep (roughly) parallel with section "Measurements" of +@c groff(7). +@node Measurements, Numeric Expressions, Text, GNU troff Reference +@section Measurements +@cindex measurements +@cindex scaling indicator +@cindex indicator, scaling + +@cindex units of measurement +@cindex measurement units +The formatter sometimes requires the input of numeric parameters to +specify measurements. These are specified as integers or decimal +fractions with an optional @dfn{scaling unit} suffixed. A scaling unit +is a letter that immediately follows the last digit of a number. Digits +after the decimal point are optional. Measurement expressions include +@samp{10.5p}, @samp{11i}, and @samp{3.c}. + +@cindex basic units, conversion to +@cindex units, basic, conversion to +@cindex conversion to basic units +Measurements are scaled by the scaling unit and stored internally (with +any fractional part discarded) in basic units. +@cindex device resolution, obtaining in the formatter +@cindex resolution, device, obtaining in the formatter +The device resolution can therefore be obtained by storing a value of +@samp{1i} to a register. The only constraint on the basic unit is that +it is at least as small as any other unit. +@c That's a fib. A device resolution of around 2^31 would surely also +@c cause problems. But nobody does that. + +@table @code +@cindex basic scaling unit (@code{u}) +@cindex @code{u} scaling unit +@cindex unit, scaling, @code{u} +@cindex scaling unit @code{u} +@item u +Basic unit. + +@item i +@cindex inch scaling unit (@code{i}) +@cindex @code{i} scaling unit +@cindex unit, scaling, @code{i} +@cindex scaling unit @code{i} +Inch; defined as 2.54@tie{}centimeters. + +@item c +@cindex centimeter scaling unit (@code{c}) +@cindex @code{c} scaling unit +@cindex unit, scaling, @code{c} +@cindex scaling unit @code{c} +Centimeter; a centimeter is about 0.3937@tie{}inches. + +@item p +@cindex point scaling unit (@code{p}) +@cindex @code{p} scaling unit +@cindex unit, scaling, @code{p} +@cindex scaling unit @code{p} +Point; a typesetter's unit used for measuring type size. +There are 72@tie{}points to an inch. + +@item P +@cindex pica scaling unit (@code{P}) +@cindex @code{P} scaling unit +@cindex unit, scaling, @code{P} +@cindex scaling unit @code{P} +Pica; another typesetter's unit. There are 6@tie{}picas to an inch and +12@tie{}points to a pica. + +@item s +@itemx z +@xref{Using Fractional Type Sizes}, for a discussion of these units. + +@item f +GNU @code{troff} defines this unit to scale decimal fractions in the +interval [0, 1] to 16-bit unsigned integers. It multiplies a quantity +by 65,536. @xref{Colors}, for usage. +@end table + +The magnitudes of other scaling units depend on the text formatting +parameters in effect. These are useful when specifying measurements +that need to scale with the typeface or vertical spacing. + +@table @code +@item m +@cindex em scaling unit (@code{m}) +@cindex @code{m} scaling unit +@cindex unit, scaling, @code{m} +@cindex scaling unit @code{m} +Em; an em is equal to the current type size in points. It is named thus +because it is approximately the width of the letter@tie{}@samp{M}. + +@item n +@cindex en scaling unit (@code{n}) +@cindex @code{n} scaling unit +@cindex unit, scaling, @code{n} +@cindex scaling unit @code{n} +En; an en is one-half em. + +@item v +@cindex vertical space unit (@code{v}) +@cindex space, vertical, unit (@code{v}) +@cindex vee scaling unit (@code{v}) +@cindex @code{v} scaling unit +@cindex unit, scaling, @code{v} +@cindex scaling unit @code{v} +Vee; recall @ref{Page Geometry}. + +@item M +@cindex @code{M} scaling unit +@cindex unit, scaling, @code{M} +@cindex scaling unit @code{M} +Hundredth of an em. +@end table + +@menu +* Motion Quanta:: +* Default Units:: +@end menu +@c END Keep (roughly) parallel with section "Measurements" of groff(7). + +@c --------------------------------------------------------------------- + +@node Motion Quanta, Default Units, Measurements, Measurements +@subsection Motion Quanta +@cindex motion quanta +@cindex quanta, motion + +@c BEGIN Keep (roughly) parallel with subsection "Motion quanta" of +@c groff(7). +An output device's basic unit @code{u} is not necessarily its smallest +addressable length; @code{u} can be smaller to avoid problems with +integer roundoff. The minimum distances that a device can work with in +the horizontal and vertical directions are termed its @dfn{motion +quanta}. Measurements are rounded to applicable motion quanta. +Half-quantum fractions round toward zero. + +@cindex horizontal motion quantum register (@code{.H}) +@cindex motion quantum, horizontal, register (@code{.H}) +@cindex horizontal resolution register (@code{.H}) +@cindex resolution, horizontal, register (@code{.H}) +@DefregList {.H} +@DefregListEndx {.V} +These read-only registers interpolate the horizontal and vertical motion +quanta, respectively, of the output device in basic units. +@endDefreg + +For example, we might draw short baseline rules on a terminal device as +follows. @xref{Drawing Geometric Objects}. + +@Example +.tm \n[.H] + @error{} 24 +.nf +\l'36u' 36u +\l'37u' 37u + @result{} _ 36u + @result{} __ 37u +@endExample +@c END Keep (roughly) parallel with subsection "Motion quanta" of +@c groff(7). + +@c --------------------------------------------------------------------- + +@node Default Units, , Motion Quanta, Measurements +@subsection Default Units +@cindex default units +@cindex units, default + +@c BEGIN Keep (roughly) parallel with subsection "Default units" of +@c groff(7). +A general-purpose register (one created or updated with the @code{nr} +request; see @pxref{Registers}) is implicitly dimensionless, or reckoned +in basic units if interpreted in a measurement context. But it is +convenient for many requests and escape sequences to infer a scaling +unit for an argument if none is specified. An explicit scaling unit +(not after a closing parenthesis) can override an undesirable default. +Effectively, the default unit is suffixed to the expression if a scaling +unit is not already present. GNU @code{troff}'s use of integer +arithmetic should also be kept in mind (@pxref{Numeric Expressions}). + +The @code{ll} request interprets its argument in ems by default. +Consider several attempts to set a line length of 3.5@tie{}inches when +the type size is 10@tie{}points on a terminal device with a resolution +of 240 basic units and horizontal motion quantum of 24. Some +expressions become zero; the request clamps them to that quantum. + +@Example +.ll 3.5i \" 3.5i (= 840u) +.ll 7/2 \" 7u/2u -> 3u -> 3m -> 0, clamped to 24u +.ll (7 / 2)u \" 7u/2u -> as above +.ll 7/2i \" 7u/2i -> 7u/480u -> 0 -> as above +.ll 7i/2 \" 7i/2u -> 1680u/2m -> 1680u/24u -> 35u +.ll 7i/2u \" 3.5i (= 840u) +@endExample + +@noindent +@cindex measurements, specifying safely +The safest way to specify measurements is to attach a scaling unit. To +multiply or divide by a dimensionless quantity, use @samp{u} as its +scaling unit. +@c END Keep (roughly) parallel with subsection "Default units" of +@c groff(7). + + +@c ===================================================================== + +@c BEGIN Keep (roughly) parallel with section "Numeric expressions" of +@c groff(7). +@node Numeric Expressions, Identifiers, Measurements, GNU troff Reference +@section Numeric Expressions +@cindex numeric expressions +@cindex expressions, numeric + +A @dfn{numeric expression} evaluates to an integer:@: it can be as +simple as a literal @samp{0} or it can be a complex sequence of register +and string interpolations interleaved with measurements and operators. + +GNU @code{troff} provides a set of mathematical and logical operators +familiar to programmers---as well as some unusual ones---but supports +only integer arithmetic.@footnote{Provision is made for interpreting and +reporting decimal fractions in certain cases.} The internal data type +used for computing results is usually a 32-bit signed integer, which +suffices to represent magnitudes within a range of ±2 +billion.@footnote{If that's not enough, see the @cite{groff_tmac@r{(5)}} +man page for the @file{62bit.tmac} macro package.} + +@cindex arithmetic operators +@cindex operators, arithmetic +@cindex truncating division +@cindex addition +@cindex subtraction +@cindex multiplication +@cindex division, truncating +@cindex modulus +@opindex + +@opindex - +@opindex * +@opindex / +@opindex % +Arithmetic infix operators perform a function on the numeric expressions +to their left and right; they are @code{+} (addition), @code{-} +(subtraction), @code{*} (multiplication), @code{/} (truncating +division), and @code{%} (modulus). @dfn{Truncating division} rounds to +the integer nearer to zero, no matter how large the fractional portion. +Overflow and division (or modulus) by zero are errors and abort +evaluation of a numeric expression. +@cindex unary arithmetic operators +@cindex operators, unary arithmetic +@cindex negation +@cindex assertion (arithmetic operator) +@opindex - +@opindex + +@cindex @code{if} request, and the @samp{!} operator +@cindex @code{while} request, and the @samp{!} operator + +Arithmetic unary operators operate on the numeric expression to their +right; they are @code{-} (negation) and @code{+} (assertion---for +completeness; it does nothing). The unary minus must often be used +with parentheses to avoid confusion with the decrementation operator, +discussed below. + +Observe the rounding behavior and effect of negative operands on the +modulus and truncating division operators. + +@Example +.nr T 199/100 +.nr U 5/2 +.nr V (-5)/2 +.nr W 5/-2 +.nr X 5%2 +.nr Y (-5)%2 +.nr Z 5%-2 +T=\n[T] U=\n[U] V=\n[V] W=\n[W] X=\n[X] Y=\n[Y] Z=\n[Z] + @result{} T=1 U=2 V=-2 W=-2 X=1 Y=-1 Z=1 +@endExample + +@noindent +The sign of the modulus of operands of mixed signs is determined by the +sign of the first. Division and modulus operators satisfy the following +property:@: given a dividend@tie{}@var{a} and a divisor@tie{}@var{b}, a +quotient@tie{}@var{q} formed by @samp{(a / b)} and a +remainder@tie{}@var{r} by @samp{(a % b)}, then @math{qb + r = a}. + +@cindex scaling operator +@cindex operator, scaling +@opindex ; +GNU @code{troff}'s scaling operator, used with parentheses as +@code{(@var{c};@var{e})}, evaluates a numeric expression@tie{}@var{e} +using@tie{}@var{c} as the default scaling unit. If @var{c} is omitted, +scaling units are ignored in the evaluation of@tie{}@var{e}. This +operator can save typing by avoiding the attachment of scaling units to +every operand out of caution. Your macros can select a sensible default +unit in case the user neglects to supply one. + +@Example +.\" Indent by amount given in first argument; assume ens. +.de Indent +. in (n;\\$1) +.. +@endExample + +@noindent +Without the scaling operator, the foregoing macro would, if called with +a unitless argument, cause indentation by the @code{in} request's +default scaling unit (ems). The result would be twice as much +indentation as expected. + +@cindex extremum operators (@code{>?}, @code{?}, @code{? +@opindex ?} (maximum) and @code{ +@opindex >= +@opindex <= +@opindex = +@opindex == +Comparison operators comprise @code{<} (less than), @code{>} (greater +than), @code{<=} (less than or equal), @code{>=} (greater than or +equal), and @code{=} (equal). @code{==} is a synonym for @code{=}. +When evaluated, a comparison is replaced with @samp{0} if it is false +and @samp{1} if true. In the @code{roff} language, positive values are +true, others false. + +@cindex logical operators +@cindex operators, logical +@cindex logical ``and'' operator +@cindex logical conjunction operator +@cindex logical ``or'' operator +@cindex logical disjunction operator +@opindex & +@ifnotinfo +@opindex : +@end ifnotinfo +@ifinfo +@opindex @r{} +@end ifinfo +We can operate on truth values with the logical operators @code{&} +(logical conjunction or ``and'') and @code{:} (logical disjunction or +``or''). They evaluate as comparison operators do. + +@opindex ! +@cindex complementation, logical +@cindex logical complementation operator +@cindex logical not, limitation in expression +@cindex expression, limitation of logical not in +A logical complementation (``not'') operator, @code{!}, works only +within @code{if}, @code{ie}, and @code{while} requests. +@c This is worded to avoid implying that the operator doesn't apply +@c to conditional expressions in general, albeit without mentioning them +@c because they're out of scope. +Furthermore, @code{!} is recognized only at the beginning of a numeric +expression not contained by another numeric expression. In other words, +it must be the ``outermost'' operator. Including it elsewhere in the +expression produces a warning in the @samp{number} category +(@pxref{Warnings}), and its expression evaluates false. This +unfortunate limitation maintains compatibility with @acronym{AT&T} +@code{troff}. Test a numeric expression for falsity by +comparing it to a false value.@footnote{@xref{Conditionals and Loops}.} + +@Example +.nr X 1 +.nr Y 0 +.\" This does not work as expected. +.if (\n[X])&(!\n[Y]) .nop A: X is true, Y is false +. +.\" Use this construct instead. +.if (\n[X])&(\n[Y]<=0) .nop B: X is true, Y is false + @error{} warning: expected numeric expression, got '!' + @result{} B: X is true, Y is false +@endExample + +@cindex parentheses +@cindex order of evaluation in expressions +@cindex expression, order of evaluation +@opindex ( +@opindex ) +The @code{roff} language has no operator precedence:@: expressions are +evaluated strictly from left to right, in contrast to schoolhouse +arithmetic. Use parentheses @code{(} @code{)} to impose a desired +precedence upon subexpressions. + +@Example +.nr X 3+5*4 +.nr Y (3+5)*4 +.nr Z 3+(5*4) +X=\n[X] Y=\n[Y] Z=\n[Z] + @result{} X=32 Y=32 Z=23 +@endExample + +@cindex @code{+}, and page motion +@cindex @code{-}, and page motion +@cindex motion operators +@cindex operators, motion +@opindex + @r{(unary)} +@opindex - @r{(unary)} +For many requests and escape sequences that cause motion on the page, +the unary operators @code{+} and @code{-} work differently when leading +a numeric expression. They then indicate a motion relative to the +drawing position:@: positive is down in vertical contexts, right in +horizontal ones. + +@cindex @code{bp} request, using @code{+} and@tie{}@code{-} with +@cindex @code{in} request, using @code{+} and@tie{}@code{-} with +@cindex @code{ll} request, using @code{+} and@tie{}@code{-} with +@cindex @code{lt} request, using @code{+} and@tie{}@code{-} with +@cindex @code{nm} request, using @code{+} and@tie{}@code{-} with +@cindex @code{nr} request, using @code{+} and@tie{}@code{-} with +@cindex @code{pl} request, using @code{+} and@tie{}@code{-} with +@cindex @code{pn} request, using @code{+} and@tie{}@code{-} with +@cindex @code{po} request, using @code{+} and@tie{}@code{-} with +@cindex @code{ps} request, using @code{+} and@tie{}@code{-} with +@cindex @code{pvs} request, using @code{+} and@tie{}@code{-} with +@cindex @code{rt} request, using @code{+} and@tie{}@code{-} with +@cindex @code{ti} request, using @code{+} and@tie{}@code{-} with +@cindex @code{\H}, using @code{+} and@tie{}@code{-} with +@cindex @code{\R}, using @code{+} and@tie{}@code{-} with +@cindex @code{\s}, using @code{+} and@tie{}@code{-} with +@code{+} and @code{-} are also treated differently by the following +requests and escape sequences:@: @code{bp}, @code{in}, @code{ll}, +@code{lt}, @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, +@code{ps}, @code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and +@code{\s}. Here, leading plus and minus signs serve as incrementation +and decrementation operators, respectively. To negate an expression, +subtract it from zero or include the unary minus in parentheses with its +argument. @xref{Setting Registers}, for examples. + +@opindex | +@cindex @code{|}, and page motion +@cindex absolute @slanted{(sic)} position operator (@code{|}) +@cindex position, absolute @slanted{(sic)} operator (@code{|}) +@cindex boundary-relative motion operator (@code{|}) +@c "motion" and "operators" already indexed above +A leading @code{|} operator indicates a motion relative not to the +drawing position but to a boundary. For horizontal motions, the +measurement specifies a distance relative to a drawing position +corresponding to the beginning of the @emph{input} line. By default, +tab stops reckon movements in this way. Most escape sequences do not; +@c XXX: Which ones do? +@code{|} tells them to do so. + +@Example +Mind the \h'1.2i'gap. +.br +Mind the \h'|1.2i'gap. +.br +Mind the +\h'|1.2i'gap. +@c 13 spaces, 4 spaces, 13 spaces + @result{} Mind the gap. + @result{} Mind the gap. + @result{} Mind the gap. +@endExample + +One use of this feature is to define macros whose scope is limited to +the output they format. + +@Example +.\" underline word $1 with trailing punctuation $2 +.de Underline +. nop \\$1\l'|0\[ul]'\\$2 +.. +Typographical emphasis is best used +.Underline sparingly . +@endExample + +@noindent +In the above example, @samp{|0} specifies a negative motion from the +current position (at the end of the argument just emitted, @code{\$1}) +to the beginning of the input line. Thus, the @code{\l} escape sequence +in this case draws a line from right to left. A macro call occurs at +the beginning of an input line;@footnote{Control structure syntax +creates an exception to this rule, but is designed to remain useful:@: +recalling our example, @samp{.if 1 .Underline this} would underline only +``this'', precisely. @xref{Conditionals and Loops}.} if the @code{|} +operator were omitted, then the underline would be drawn at zero +distance from the current position, producing device-dependent, and +likely undesirable, results. On the @samp{ps} output device, it +underlines the period. + +For vertical motions, the @code{|} operator specifies a distance from +the first text baseline on the page or in the current +diversion,@footnote{@xref{Diversions}.} using the current vertical +spacing. + +@Example +A +.br +B \Z'C'\v'|0'D + @result{} A D + @result{} B C +@endExample + +In the foregoing example, we've used the @code{\Z} escape sequence +(@pxref{Page Motions}) to restore the drawing position after formatting +@samp{C}, then moved vertically to the first text baseline on the page. + +@Defesc {\\B, @code{'}, anything, @code{'}} +@cindex numeric expression, valid +@cindex valid numeric expression +Interpolate@tie{}1 if @var{anything} is a valid numeric expression, +and@tie{}0 otherwise. The delimiter need not be a neutral apostrophe; +see @ref{Delimiters}. +@endDefesc + +You might use @code{\B} along with the @code{if} request to filter out +invalid macro or string arguments. @xref{Conditionals and Loops}. + +@Example +.\" Indent by amount given in first argument; assume ens. +.de Indent +. if \B'\\$1' .in (n;\\$1) +.. +@endExample + +A register interpolated as an operand in a numeric expression must have +an Arabic format; luckily, this is the default. @xref{Assigning +Register Formats}. + +@cindex space characters, in expressions +@cindex expressions, and space characters +Because spaces separate arguments to requests, spaces are not allowed in +numeric expressions unless the (sub)expression containing them is +surrounded by parentheses. @xref{Invoking Requests}, and +@ref{Conditionals and Loops}. + +@Example +.nf +.nr a 1+2 + 2+1 +\na + @error{} expected numeric expression, got a space + @result{} 3 +.nr a 1+(2 + 2)+1 +\na + @result{} 6 +@endExample + +The @code{nr} request (@pxref{Setting Registers}) expects its second and +optional third arguments to be numeric expressions; a bare @code{+} does +not qualify, so our first attempt got a warning. +@c END Keep (roughly) parallel with section "Numeric expressions" of +@c groff(7). + + +@c ===================================================================== + +@c BEGIN Keep (roughly) parallel with section "Identifiers" of groff(7). +@node Identifiers, Formatter Instructions, Numeric Expressions, GNU troff Reference +@section Identifiers +@cindex identifiers + +An @dfn{identifier} labels a GNU @code{troff} datum such as a register, +name (macro, string, or diversion), typeface, color, special character, +character class, environment, or stream. Valid identifiers consist of +one or more ordinary characters. +@cindex ordinary character +@cindex character, ordinary +An @slanted{ordinary character} is an input character that is not the +escape character, a leader, tab, newline, or invalid as GNU @code{troff} +input. + +@c XXX: We might move this discussion earlier since it is applicable to +@c troff input in general, and include a reference to the `trin` +@c request. +@cindex invalid input characters +@cindex input characters, invalid +@cindex characters, invalid input +@cindex Unicode +Invalid input characters are a subset of control characters (from the +sets ``C0 Controls'' and ``C1 Controls'' as Unicode describes them). +When GNU @code{troff} encounters one in an identifier, it produces a +warning in category @samp{input} (@pxref{Warnings}). They are removed +during interpretation: an identifier @samp{foo}, followed by an invalid +character and then @samp{bar}, is processed as @samp{foobar}. + +On a machine using the ISO 646, 8859, or 10646 character encodings, +invalid input characters are @code{0x00}, @code{0x08}, @code{0x0B}, +@code{0x0D}--@code{0x1F}, and @code{0x80}--@code{0x9F}. On an +@acronym{EBCDIC} host, they are @code{0x00}--@code{0x01}, @code{0x08}, +@code{0x09}, @code{0x0B}, @code{0x0D}--@code{0x14}, +@code{0x17}--@code{0x1F}, and +@code{0x30}--@code{0x3F}.@footnote{Historically, control characters like +ASCII STX, ETX, and BEL (@key{Control+B}, @key{Control+C}, and +@key{Control+G}) have been observed in @code{roff} documents, +particularly in macro packages employing them as delimiters with the +output comparison operator to try to avoid collisions with the content +of arbitrary user-supplied parameters (@pxref{Operators in +Conditionals}). We discourage this expedient; in GNU @code{troff} it is +unnecessary (outside of compatibility mode) because delimited arguments +are parsed at a different input level than the surrounding context. +@xref{Implementation Differences}.} Some of these code points are used +by GNU @code{troff} internally, making it non-trivial to extend the +program to accept UTF-8 or other encodings that use characters from +these ranges.@footnote{Consider what happens when a C1 control +@code{0x80}--@code{0x9F} is necessary as a continuation byte in a UTF-8 +sequence.} + +Thus, the identifiers @samp{br}, @samp{PP}, @samp{end-list}, +@samp{ref*normal-print}, @samp{|}, @samp{@@_}, and @samp{!"#$%'()*+,-./} +are all valid. Discretion should be exercised to prevent confusion. +Identifiers starting with @samp{(} or @samp{[} require care. + +@Example +.nr x 9 +.nr y 1 +.nr (x 2 +.nr [y 3 +.nr sum1 (\n(x + \n[y]) + @error{} a space character is not allowed in an escape + @error{} sequence parameter +A:2+3=\n[sum1] +.nr sum2 (\n((x + \n[[y]) +B:2+3=\n[sum2] +.nr sum3 (\n[(x] + \n([y) +C:2+3=\n[sum3] + @result{} A:2+3=1 B:2+3=5 C:2+3=5 +@endExample + +@cindex @code{]}, as part of an identifier +@noindent +An identifier with a closing bracket (@samp{]}) in its name can't be +accessed with bracket-form escape sequences that expect an identifier as +a parameter. For example, @samp{\[foo]]} accesses the glyph @samp{foo}, +followed by @samp{]} in whatever the surrounding context is, whereas +@samp{\C'foo]'} formats a glyph named @samp{foo]}. Similarly, the +identifier @samp{(} can't be interpolated @emph{except} with bracket +forms. + +@cindex @code{refer}, and macro names starting with @code{[} or @code{]} +@cindex @code{[}, macro names starting with, and @code{refer} +@cindex @code{]}, macro names starting with, and @code{refer} +@cindex macro names, starting with @code{[} or @code{]}, and @code{refer} +If you begin a macro, string, or diversion name with either of the +characters @samp{[} or @samp{]}, you foreclose use of the @code{grefer} +preprocessor, which recognizes @samp{.[} and @samp{.]} as bibliographic +reference delimiters. + +@Defesc {\\A, @code{'}, anything, @code{'}} +Interpolate@tie{}1 if @var{anything} is a valid identifier, and@tie{}0 +otherwise. The delimiter need not be a neutral apostrophe; see +@ref{Delimiters}. Because invalid input characters are removed (see +above), invalid identifiers are empty or contain spaces, tabs, or +newlines. + +You can employ @code{\A} to validate a macro argument before using it to +construct another escape sequence or identifier. + +@Example +.\" usage: .init-coordinate-pair name val1 val2 +.\" Create a coordinate pair where name!x=val1 and +.\" name!y=val2. +.de init-coordinate-pair +. if \A'\\$1' \@{\ +. if \B'\\$2' .nr \\$1!x \\$2 +. if \B'\\$3' .nr \\$1!y \\$3 +. \@} +.. +.init-coordinate-pair center 5 10 +The center is at (\n[center!x], \n[center!y]). +.init-coordinate-pair "poi@arrow{}nt" trash garbage \" ignored +.init-coordinate-pair point trash garbage \" ignored + @result{} The center is at (5, 10). +@endExample + +@noindent +In this example, we also validated the numeric arguments; the registers +@samp{point!x} and @samp{point!y} remain undefined. @xref{Numeric +Expressions} for the @code{\B} escape sequence. +@endDefesc + +@cindex undefined identifiers +@cindex identifiers, undefined +How GNU @code{troff} handles the interpretation of an undefined +identifier depends on the context. There is no way to invoke an +undefined request; such syntax is interpreted as a macro call instead. +If the identifier is interpreted as a string, macro, or diversion, GNU +@code{troff} emits a warning in category @samp{mac}, defines it as +empty, and interpolates nothing. If the identifier is interpreted as a +register, GNU @code{troff} emits a warning in category @samp{reg}, +initializes it to zero, and interpolates that value. @xref{Warnings}, +@ref{Interpolating Registers}, and @ref{Strings}. Attempting to use an +undefined typeface, special character, color, character class, +environment, or stream generally provokes an error diagnostic. + +@need 1000 +@cindex name space, common, of macros, diversions, and strings +@cindex common name space of macros, diversions, and strings +@cindex macros, shared name space with strings and diversions +@cindex strings, shared name space with macros and diversions +@cindex diversions, shared name space with macros and strings +Identifiers for requests, macros, strings, and diversions share one name +space; special characters and character classes another. No other +object types do. + +@Example +.de xxx +. nop foo +.. +@c . slack line for pagination management +.di xxx +bar +.br +.di +. +.xxx + @result{} bar +@endExample + +@noindent +The foregoing example shows that GNU @code{troff} reuses the identifier +@samp{xxx}, changing it from a macro to a diversion. No warning is +emitted, and the previous contents of @samp{xxx} are lost. +@c END Keep (roughly) parallel with section "Identifiers" of groff(7). + + +@c ===================================================================== + +@node Formatter Instructions, Registers, Identifiers, GNU troff Reference +@section Formatter Instructions +@cindex formatter instructions +@cindex instructing the formatter + +To support documents that require more than filling, automatic line +breaking and hyphenation, adjustment, and supplemental inter-sentence +space, the @code{roff} language offers two means of embedding +instructions to the formatter. + +@cindex request +One is a @dfn{request}, which begins with a control character and takes +up the remainder of the input line. Requests often perform relatively +large-scale operations such as setting the page length, breaking the +line, or starting a new page. They also conduct internal operations +like defining macros. + +@cindex escape sequence +@cindex sequence, escape +The other is an @dfn{escape sequence}, which begins with the escape +character and can be embedded anywhere in the input, even in arguments +to requests and other escape sequences. Escape sequences interpolate +special characters, strings, or registers, and handle comparatively +minor formatting tasks like sub- and superscripting. + +Some operations, such as font selection and type size alteration, are +available via both requests and escape sequences. + +@menu +* Control Characters:: +* Invoking Requests:: +* Calling Macros:: +* Using Escape Sequences:: +* Delimiters:: +@end menu + +@c --------------------------------------------------------------------- + +@node Control Characters, Invoking Requests, Formatter Instructions, Formatter Instructions +@subsection Control Characters +@cindex control characters +@cindex configuring control characters +@cindex changing control characters + +The mechanism of using @code{roff}'s control characters to invoke +requests and call macros was introduced in @ref{Requests and Macros}. +Control characters are recognized only at the beginning of an input +line, or at the beginning of the branch of a control structure request; +see @ref{Conditionals and Loops}. + +A few requests cause a break implicitly; use the no-break control +character to prevent the break. Break suppression is its sole +behavioral distinction. Employing the no-break control character to +invoke requests that don't cause breaks is harmless but poor style. +@xref{Manipulating Filling and Adjustment}. + +@cindex control character, changing (@code{cc}) +@cindex character, control, changing (@code{cc}) +@cindex no-break control character, changing (@code{c2}) +@cindex character, no-break control, changing (@code{c2}) +@cindex control character, no-break, changing (@code{c2}) +The control @samp{.} and no-break control @samp{'} characters can each +be changed to any ordinary character@footnote{Recall @ref{Identifiers}.} +with the @code{cc} and @code{c2} requests, respectively. + +@Defreq {cc, [@Var{o}]} +Recognize the ordinary character@tie{}@var{o} as the control character. +If@tie{}@var{o} is absent or invalid, the default control character +@samp{.} is selected. The identity of the control character is +associated with the environment (@pxref{Environments}). +@endDefreq + +@Defreq {c2, [@Var{o}]} +Recognize the ordinary character@tie{}@var{o} as the no-break control +character. If@tie{}@var{o} is absent or invalid, the default no-break +control character @samp{'} is selected. The identity of the no-break +control character is associated with the environment +(@pxref{Environments}). +@endDefreq + +When writing a macro, you might wish to know which control character was +used to call it. + +@Defreg {.br} +This read-only register interpolates@tie{}1 if the currently executing +macro was called using the normal control character and@tie{}0 +otherwise. If a macro is interpolated as a string, the @code{.br} +register's value is inherited from the context of the string +interpolation. @xref{Strings}. + +@cindex intercepting requests +@cindex requests, intercepting +@cindex modifying requests +@cindex requests, modifying +Use this register to reliably intercept requests that imply breaks. + +@Example +.als bp*orig bp +.de bp +. ie \\n[.br] .bp*orig +. el 'bp*orig +.. +@endExample + +Testing the @code{.br} register outside of a macro definition makes no +sense. +@endDefreg + +@c --------------------------------------------------------------------- + +@c BEGIN Keep (roughly) parallel with section "Requests" of groff(7). +@node Invoking Requests, Calling Macros, Control Characters, Formatter Instructions +@subsection Invoking Requests +@cindex invoking requests +@cindex requests, invoking + +A control character is optionally followed by tabs and/or spaces and +then an identifier naming a request or macro. The invocation of an +unrecognized request is interpreted as a macro call. Defining a macro +with the same name as a request replaces the request. Deleting a +request name with the @code{rm} request makes it unavailable. The +@code{als} request can alias requests, permitting them to be wrapped or +non-destructively replaced. @xref{Strings}. + +@cindex request arguments +@cindex arguments to requests +@cindex tabs, and macro arguments +@cindex macro arguments, and tabs +@cindex arguments to macros, and tabs +@cindex tabs, and request arguments +@cindex request arguments, and tabs +@cindex arguments to requests, and tabs +There is no inherent limit on argument length or quantity. Most +requests take one or more arguments, and ignore any they do not expect. +A request may be separated from its arguments by tabs or spaces, but +only spaces can separate an argument from its successor. Only one +between arguments is necessary; any excess is ignored. GNU @code{troff} +does not allow tabs for argument separation.@footnote{In compatibility +mode, a space is not necessary after a request or macro name of two +characters' length. Also, Plan@tie{}9 @code{troff} allows tabs to +separate arguments.} + +Generally, a space @emph{within} a request argument is not relevant, not +meaningful, or is supported by bespoke provisions, as with the @code{tl} +request's delimiters (@pxref{Page Layout}). Some requests, like +@code{ds}, interpret the remainder of the control line as a single +argument. @xref{Strings}. + +@need 1000 +@cindex structuring source code of documents or macro packages +@cindex documents, structuring the source of +@cindex macro package, structuring the source of +@cindex package, package, structuring the source of +@cindex indentation, of @code{roff} source code +Spaces and tabs immediately after a control character are ignored. +Commonly, authors structure the source of documents or macro files with +them. + +@Example +.de center +. if \\n[.br] \ +. br +. ce \\$1 +.. +. +. +.de right-align +.@arrow{}if \\n[.br] \ +.@arrow{}@arrow{}br +.@arrow{}rj \\$1 +.. +@endExample + +@cindex blank line trap (@code{blm}) +@cindex blank line macro (@code{blm}) +If you assign an empty blank line trap, you can separate macro +definitions (or any input lines) with blank lines. + +@Example +.de do-nothing +.. +.blm do-nothing \" activate blank line trap + +.de center +. if \\n[.br] \ +. br +. ce \\$1 +.. + + +.de right-align +.@arrow{}if \\n[.br] \ +.@arrow{}@arrow{}br +.@arrow{}rj \\$1 +.. + +.blm \" deactivate blank line trap +@endExample + +@xref{Blank Line Traps}. +@c END Keep (roughly) parallel with section "Requests" of groff(7). + +@c --------------------------------------------------------------------- + +@need 1000 +@node Calling Macros, Using Escape Sequences, Invoking Requests, Formatter Instructions +@subsection Calling Macros +@cindex calling macros +@cindex macro arguments +@cindex arguments to macros + +If a macro of the desired name does not exist when called, it is +created, assigned an empty definition, and a warning in category +@samp{mac} is emitted. Calling an undefined macro @emph{does} end a +macro definition naming it as its end macro (@pxref{Writing Macros}). + +@cindex spaces, in a macro argument +To embed spaces @emph{within} a macro argument, enclose the argument in +neutral double quotes @code{"}. Horizontal motion escape sequences are +sometimes a better choice for arguments to be formatted as text. + +Consider calls to a hypothetical section heading macro @samp{uh}. + +@Example +.uh The Mouse Problem +.uh "The Mouse Problem" +.uh The\~Mouse\~Problem +.uh The\ Mouse\ Problem +@endExample + +@cindex @code{\~}, difference from @code{\@key{SP}} +@cindex @code{\@key{SP}}, difference from @code{\~} +@noindent +The first line calls @code{uh} with three arguments: @samp{The}, +@samp{Mouse}, and @samp{Problem}. The remainder call the @code{uh} +macro with one argument, @samp{The Mouse Problem}. The last solution, +using escaped spaces, can be found in documents prepared for +@acronym{AT&T} @code{troff}. It can cause surprise when text is +adjusted, because @code{\@key{SP}} inserts a @emph{fixed-width}, +non-breaking space. GNU @code{troff}'s @code{\~} escape sequence +inserts an adjustable, non-breaking space.@footnote{@code{\~} is fairly +portable; see @ref{Other Differences}.} + +@cindex @code{"}, embedding in a macro argument +@cindex double quote, embedding in a macro argument +@cindex @code{\}, embedding in a macro argument +@cindex backslash, embedding in a macro argument +The foregoing raises the question of how to embed neutral double quotes +or backslashes in macro arguments when @emph{those} characters are +desired as literals. In GNU @code{troff}, the special character escape +sequence @code{\[rs]} produces a backslash and @code{\[dq]} a neutral +double quote. + +In GNU @code{troff}'s @acronym{AT&T} compatibility mode, these +characters remain available as @code{\(rs} and @code{\(dq}, +respectively. @acronym{AT&T} @code{troff} did not consistently define +these special characters, +@c It seems that AT&T troff never recognized \(rs, though DWB 3.3 +@c defined \(bs as an alias of "\" on its "Latin1" device, in +@c deliberate(?) collision with the Bell System logo identifier. It +@c also defined \(dq for several devices (pcl, Latin1, nroff, ...) along +@c with \(aq. +but its descendants can be made to support them. @xref{Device and Font +Description Files}. + +If even that is not feasible, options remain. To obtain a literal +escape character in a macro argument, you can simply type it if you +change or disable the escape character first. @xref{Using Escape +Sequences}. Otherwise, you must escape the escape character repeatedly +to a context-dependent extent. @xref{Copy Mode}. + +For the (neutral) double quote, you have recourse to an obscure +syntactical feature of @acronym{AT&T} @code{troff}. Because a double +quote can begin a macro argument, the formatter keeps track of whether +the current argument was started thus, and doesn't require a space after +the double quote that ends it.@footnote{Strictly, you can neglect to +close the last quoted macro argument, relying on the end of the control +line to do so. We consider this lethargic practice poor style.} In +the argument list to a macro, a double quote that @emph{isn't} preceded +by a space @emph{doesn't} start a macro argument. If not preceded by a +double quote that began an argument, this double quote becomes part of +the argument. Furthermore, within a quoted argument, a pair of adjacent +double quotes becomes a literal double quote. + +@Example +.de eq +. tm arg1:\\$1 arg2:\\$2 arg3:\\$3 +. tm arg4:\\$4 arg5:\\$5 arg6:\\$6 +.. \" 4 backslashes on the next line +.eq a" "b c" "de"f\\\\g" h""i "j""k" + @error{} arg1:a" arg2:b c arg3:de + @error{} arg4:f\g" arg5:h""i arg6:j"k +@endExample + +Apart from the complexity of the rules, this traditional solution has +the disadvantage that double quotes don't survive repeated argument +expansion in @acronym{AT&T} @code{troff} or GNU @code{troff}'s +compatibility mode. This can frustrate efforts to pass such arguments +intact through multiple macro calls. + +@Example +.cp 1 +.de eq +. tm arg1:\\$1 arg2:\\$2 arg3:\\$3 +. tm arg4:\\$4 arg5:\\$5 arg6:\\$6 +.. +.de xe +. eq \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 +.. \" 8 backslashes on the next line +.xe a" "b c" "de"f\\\\\\\\g" h""i "j""k" + @error{} arg1:a" arg2:b arg3:c + @error{} arg4:de arg5:f\g" arg6:h""i +@endExample + +@cindex input level +@cindex level, input +@cindex interpolation depth +@cindex depth, interpolation +Outside of compatibility mode, GNU @code{troff} doesn't exhibit this +problem because it tracks the nesting depth of interpolations. +@xref{Implementation Differences}. + +@c --------------------------------------------------------------------- + +@c BEGIN Keep (roughly) parallel with section "Using escape sequences" +@c of groff(7). +@node Using Escape Sequences, Delimiters, Calling Macros, Formatter Instructions +@subsection Using Escape Sequences +@cindex using escape sequences +@cindex escape sequences + +Whereas requests must occur on control lines, escape sequences can occur +intermixed with text and may appear in arguments to requests, macros, +and other escape sequences. +@esindex \ +An escape sequence is introduced by the escape character, a backslash +@code{\} (but see the @code{ec} request below). The next character +selects the escape's function. + +Escape sequences vary in length. Some take an argument, and of those, +some have different syntactical forms for a one-character, +two-character, or arbitrary-length argument. Others accept @emph{only} +an arbitrary-length argument. In the former scheme, a one-character +argument follows the function character immediately, an opening +parenthesis @samp{(} introduces a two-character argument (no closing +parenthesis is used), and an argument of arbitrary length is enclosed in +brackets @samp{[]}. In the latter scheme, the user selects a delimiter +character. A few escape sequences are idiosyncratic, and support both +of the foregoing conventions (@code{\s}), designate their own +termination sequence (@code{\?}), consume input until the next newline +(@code{\!}, @code{\"}, @code{\#}), or support an additional modifier +character (@code{\s} again, and @code{\n}). As with requests, use of +some escape sequences in source documents may interact poorly with a +macro package you use; consult its documentation to learn of ``safe'' +sequences or alternative facilities it provides to achieve the desired +result. + +If an escape character is followed by a character that does not +identify a defined operation, the escape character is ignored (producing +a diagnostic of the @samp{escape} warning category, which is not enabled +by default) and the following character is processed normally. + +@Example +$ groff -Tps -ww +.nr N 12 +.ds co white +.ds animal elephant +I have \fI\nN \*(co \*[animal]s,\f[] +said \P.\&\~Pseudo Pachyderm. + @error{} warning: escape character ignored before 'P' + @result{} I have @slanted{12 white elephants,} said P. Pseudo Pachyderm. +@endExample + +Escape sequence interpolation is of higher precedence than escape +sequence argument interpretation. This rule affords flexibility in +using escape sequences to construct parameters to other escape +sequences. +@c END Keep (roughly) parallel with section "Escape sequences" of +@c groff(7). + +@Example +.ds family C\" Courier +.ds style I\" oblique +Choice a typeface \f(\*[family]\*[style]wisely. + @result{} Choose a typeface @slanted{wisely.} +@endExample + +@noindent +In the above, the syntax form @samp{\f(} accepts only two characters for +an argument; the example works because the subsequent escape sequences +are interpolated before the selection escape sequence argument is +processed, and strings @code{family} and @code{style} interpolate one +character each.@footnote{The omission of spaces before the comment +escape sequences is necessary; see @ref{Strings}.} + +@c @need 1000 +The escape character is nearly always interpreted when encountered; it +is therefore desirable to have a way to interpolate it, disable it, or +change it. + +@cindex formatting the escape character (@code{\e}) +@cindex escape character, formatting (@code{\e}) +@Defesc {\\e, , , } +Interpolate the escape character. +@endDefesc + +@cindex formatting a backslash glyph (@code{\[rs]}) +@cindex backslash glyph, formatting (@code{\[rs]}) +The @code{\[rs]} special character escape sequence formats a backslash +glyph. In macro and string definitions, the input sequences @code{\\} +and @code{\E} defer interpretation of escape sequences. @xref{Copy +Mode}. + +@Defreq {eo, } +@cindex disabling @code{\} (@code{eo}) +@cindex @code{\}, disabling (@code{eo}) +Disable the escape mechanism except in copy mode. Once this request is +invoked, no input character is recognized as starting an escape +sequence in interpretation mode. +@endDefreq + +@Defreq {ec, [@Var{o}]} +@cindex escape character, changing (@code{ec}) +@cindex character, escape, changing (@code{ec}) +Recognize the ordinary character@tie{}@var{o} as the escape character. +If@tie{}@var{o} is absent or invalid, the default escape character +@samp{\} is selected. +@endDefreq + +Switching escape sequence interpretation off to define a macro and back +on afterward can obviate the need to double the escape character within +the definition. @xref{Writing Macros}. This technique is not available +if your macro needs to interpolate values at the time it is +@emph{defined}---but many do not. + +@Example +.\" simplified `BR` macro from the man(7) macro package +.eo +.de BR +. ds result \& +. while (\n[.$] >= 2) \@{\ +. as result \fB\$1\fR\$2\" +. shift 2 +. \@} +. if \n[.$] .as result \fB\$1\" +\*[result] +. rm result +. ft R +.. +.ec +@endExample + +@DefreqList {ecs, } +@DefreqListEndx {ecr, } +The @code{ecs} request stores the escape character for recall with +@code{ecr}. @code{ecr} sets the escape character to @samp{\} if none +has been saved. + +Use these requests together to temporarily change the escape character. +@endDefreq + +Using a different escape character, or disabling it, when calling macros +not under your control will likely cause errors, since GNU @code{troff} +has no mechanism to ``intern'' macros---that is, to convert a macro +definition into a form independent of its +representation.@footnote{@TeX{} does have such a mechanism.} When a +macro is called, its contents are interpreted literally. +@c XXX: all that stuff mapped into the C0 and C1 controls seems pretty +@c close to an interning mechanism to me, though... --GBR + +@c XXX: Motivation? Why are we directing the reader to these? +@c @xref{Diversions}, and @ref{Identifiers}. + +@c BEGIN Keep (roughly) parallel with subsection "Delimiters" of +@c groff(7). +@node Delimiters, , Using Escape Sequences, Formatter Instructions +@subsection Delimiters +@cindex delimiting escape sequence arguments +@cindex escape sequence argument delimiters +@cindex delimiters, for escape sequence arguments +@cindex arguments, to escape sequences, delimiting + +@cindex @code{'}, as delimiter +@cindex @code{"}, as delimiter +Some escape sequences that require parameters use delimiters. The +neutral apostrophe @code{'} is a popular choice and shown in this +document. The neutral double quote @code{"} is also commonly seen. +Letters, numerals, and leaders can be used. Punctuation characters +are likely better choices, except for those defined as infix operators +in numeric expressions; see below. + +@Example +\l'1.5i\[bu]' \" draw 1.5 inches of bullet glyphs +@endExample + +@cindex @code{\%}, as delimiter +@cindex @code{\@key{SP}}, as delimiter +@cindex @code{\|}, as delimiter +@cindex @code{\^}, as delimiter +@cindex @code{\@{}, as delimiter +@cindex @code{\@}}, as delimiter +@cindex @code{\'}, as delimiter +@cindex @code{\`}, as delimiter +@cindex @code{\-}, as delimiter +@cindex @code{\_}, as delimiter +@cindex @code{\!}, as delimiter +@cindex @code{\?}, as delimiter +@cindex @code{\)}, as delimiter +@cindex @code{\/}, as delimiter +@cindex @code{\,}, as delimiter +@cindex @code{\&}, as delimiter +@cindex @code{\:}, as delimiter +@cindex @code{\~}, as delimiter +@cindex @code{\0}, as delimiter +@cindex @code{\a}, as delimiter +@cindex @code{\c}, as delimiter +@cindex @code{\d}, as delimiter +@cindex @code{\e}, as delimiter +@cindex @code{\E}, as delimiter +@cindex @code{\p}, as delimiter +@cindex @code{\r}, as delimiter +@cindex @code{\t}, as delimiter +@cindex @code{\u}, as delimiter +The following escape sequences don't take arguments and thus are allowed +as delimiters: +@code{\@key{SP}}, @code{\%}, @code{\|}, @code{\^}, @code{\@{}, +@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, +@code{\?}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, @code{\:}, +@code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e}, +@code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. However, +using them this way is discouraged; they can make the input confusing to +read. + +@cindex @code{\A}, delimiters allowed by +@cindex @code{\b}, delimiters allowed by +@cindex @code{\o}, delimiters allowed by +@cindex @code{\w}, delimiters allowed by +@cindex @code{\X}, delimiters allowed by +@cindex @code{\Z}, delimiters allowed by +@cindex newline, as delimiter +A few escape sequences, +@code{\A}, +@code{\b}, +@code{\o}, +@code{\w}, +@code{\X}, +and @code{\Z}, accept a newline as a delimiter. Newlines that serve +as delimiters continue to be recognized as input line terminators. + +@Example +A caf\o +e\(aa +in Paris + @result{} A café in Paris +@endExample + +@noindent +Use of newlines as delimiters in escape sequences is also discouraged. + +@cindex @code{\D}, delimiters allowed by +@cindex @code{\h}, delimiters allowed by +@cindex @code{\H}, delimiters allowed by +@cindex @code{\l}, delimiters allowed by +@cindex @code{\L}, delimiters allowed by +@cindex @code{\N}, delimiters allowed by +@cindex @code{\R}, delimiters allowed by +@cindex @code{\s}, delimiters allowed by +@cindex @code{\S}, delimiters allowed by +@cindex @code{\v}, delimiters allowed by +@cindex @code{\x}, delimiters allowed by +Finally, the escape sequences @code{\D}, @code{\h}, @code{\H}, +@code{\l}, @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, +@code{\v}, and @code{\x} prohibit many delimiters. + +@itemize @bullet +@item +@cindex numerals, as delimiters +@cindex digits, as delimiters +@cindex @code{.}, as delimiter +@cindex decimal point, as delimiter +@cindex dot, as delimiter +the numerals @code{0}-@code{9} and the decimal point @code{.} + +@item +@cindex operators, as delimiters +@cindex @code{+}, as delimiter +@cindex @code{-}, as delimiter +@cindex @code{/}, as delimiter +@cindex @code{*}, as delimiter +@cindex @code{%}, as delimiter +@cindex @code{<}, as delimiter +@cindex @code{>}, as delimiter +@cindex @code{=}, as delimiter +@cindex @code{&}, as delimiter +@ifnotinfo +@cindex @code{:}, as delimiter +@end ifnotinfo +@ifinfo +@cindex , as delimiter +@end ifinfo +@cindex @code{(}, as delimiter +@cindex @code{)}, as delimiter +the (single-character) operators @samp{+-/*%<>=&:()} + +@item +@cindex space character, as delimiter +@cindex tab character, as delimiter +the space and tab characters + +@item +@cindex @code{\%}, as delimiter +@cindex @code{\:}, as delimiter +@cindex @code{\@{}, as delimiter +@cindex @code{\@}}, as delimiter +@cindex @code{\'}, as delimiter +@cindex @code{\`}, as delimiter +@cindex @code{\-}, as delimiter +@cindex @code{\_}, as delimiter +@cindex @code{\!}, as delimiter +@cindex @code{\/}, as delimiter +@cindex @code{\c}, as delimiter +@cindex @code{\e}, as delimiter +@cindex @code{\p}, as delimiter +any escape sequences other than @code{\%}, @code{\:}, @code{\@{}, +@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, +@code{\/}, @code{\c}, @code{\e}, and @code{\p} +@end itemize + +Delimiter syntax is complex and flexible primarily for historical +reasons; the foregoing restrictions need be kept in mind mainly when +using @code{groff} in @acronym{AT&T} compatibility mode. GNU +@code{troff} keeps track of the nesting depth of escape sequence +interpolations, so the only characters you need to avoid using as +delimiters are those that appear in the arguments you input, not any +that result from interpolation. Typically, @code{'} works fine. +@xref{Implementation Differences}. + +@Example +$ groff -Tps +.de Mw +. nr wd \w'\\$1' +. tm "\\$1" is \\n(wd units wide. +.. +.Mw Wet'suwet'en +.Mw Wet+200i +.cp 1 \" turn on compatibility mode +.Mw Wet'suwet'en +.Mw Wet' +.Mw Wet+200i + @error{} "Wet'suwet'en" is 54740 units wide. + @error{} "Wet'+200i" is 42610 units wide. + @error{} "Wet'suwet'en" is 15860 units wide. + @error{} "Wet'" is 15860 units wide. + @error{} "Wet'+200i" is 14415860 units wide. +@endExample + +We see here that in compatibility mode, the part of the argument after +the @code{'} delimiter escapes from its context and, if nefariously +crafted, influences the computation of the @var{wd} register's value in +a surprising way. +@c END Keep (roughly) parallel with subsection " Delimiters" of +@c groff(7). + +@node Comments, Registers, Formatter Instructions, GNU troff Reference +@section Comments +@cindex comments + +One of the most common forms of escape sequence is the +comment.@footnote{This claim may be more aspirational than descriptive.} + +@Defesc {\\", , , } +Start a comment. Everything up to the next newline is ignored. + +This may sound simple, but it can be tricky to keep the comments from +interfering with the appearance of the output. +@cindex @code{ds}, @code{ds1} requests, and comments +@cindex @code{as}, @code{as1} requests, and comments +If the escape sequence is to the right of some text or a request, that +portion of the line is ignored, but spaces preceding it are processed +normally by GNU @code{troff}. This affects only the @code{ds} and +@code{as} requests and their variants. + +@cindex tabs, before comments +@cindex comments, lining up with tabs +One possibly irritating idiosyncrasy is that tabs should not be used to +vertically align comments in the source document. Tab characters are +not treated as separators between a request name and its first argument, +nor between arguments. + +@cindex undefined request +@cindex request, undefined +A comment on a line by itself is treated as a blank line, because after +eliminating the comment, that is all that remains. + +@Example +Test +\" comment +Test + @result{} Test + @result{} + @result{} Test +@endExample + +To avoid this, it is common to combine the empty request with the +comment escape sequence as @samp{.\"}, causing the input line to be +ignored. + +@cindex @code{'}, as a comment +Another commenting scheme sometimes seen is three consecutive single +quotes (@code{'''}) at the beginning of a line. This works, but GNU +@code{troff} emits a warning diagnostic (if enabled) about an undefined +macro (namely @samp{''}). +@endDefesc + +@Defesc {\\#, , , } +Start a comment; everything up to and including the next newline is +ignored. This @code{groff} extension was introduced to avoid the +problems described above. + +@Example +Test +\# comment +Test + @result{} Test Test +@endExample +@endDefesc + +@Defreq {ig, [@Var{end}]} +Ignore input until, in the current conditional block (if +any),@footnote{@xref{Conditional Blocks}.} the macro @var{end} is called +at the start of a control line, or the control line @samp{..} is +encountered if @var{end} is not specified. @code{ig} is parsed as if it +were a macro definition, but its contents are discarded, not +stored.@footnote{Exception: auto-incrementing registers defined outside +the ignored region @emph{will} be modified if interpolated with +@code{\n±} inside it. @xref{Auto-increment}.} + +@c Wrap example at 56 columns. +@Example +hand\c +.de TX +fasting +.. +.ig TX +This is part of a large block of input that has been +temporarily(?) commented out. +We can restore it simply by removing the .ig request and +the call of its end macro. +.TX +@endExample +@Example + @result{} handfasting +@endExample +@endDefreq + + +@c ===================================================================== + +@c BEGIN Keep (roughly) parallel with subsection "Registers" of +@c groff(7). +@node Registers, Manipulating Filling and Adjustment, Formatter Instructions, GNU troff Reference +@section Registers +@cindex registers + +In the @code{roff} language, numbers can be stored in @dfn{registers}. +Many built-in registers exist, supplying anything from the date to +details of formatting parameters. You can also define your own. +@xref{Identifiers}, for information on constructing a valid name for a +register. + +@menu +* Setting Registers:: +* Interpolating Registers:: +* Auto-increment:: +* Assigning Register Formats:: +* Built-in Registers:: +@end menu + +@c --------------------------------------------------------------------- + +@node Setting Registers, Interpolating Registers, Registers, Registers +@subsection Setting Registers +@cindex setting registers (@code{nr}, @code{\R}) +@cindex registers, setting (@code{nr}, @code{\R}) + +Define registers and update their values with the @code{nr} request or +the @code{\R} escape sequence. + +@DefreqList {nr, ident value} +@DefescListEndx {\\R, @code{'}, ident value, @code{'}} +Set register @var{ident} to @var{value}. If @var{ident} doesn't exist, +GNU @code{troff} creates it. In the @code{\R} escape sequence, the +delimiter need not be a neutral apostrophe; see @ref{Delimiters}. It +also does not produce an input token in GNU @code{troff}. @xref{Gtroff +Internals}. + +@Example +.nr a (((17 + (3 * 4))) % 4) +\n[a] +.\R'a (((17 + (3 * 4))) % 4)' +\n[a] + @result{} 1 1 +@endExample + +(Later, we will discuss additional forms of @code{nr} and @code{\R} that +can change a register's value after it is dereferenced but before it is +interpolated. @xref{Auto-increment}.) + +The complete transparency of @code{\R} can cause surprising effects if +you use registers like @code{.k}, which get evaluated at the time they +are accessed. + +@Example +.ll 1.6i +. +aaa bbb ccc ddd eee fff ggg hhh\R':k \n[.k]' +.tm :k == \n[:k] + @result{} :k == 126950 +. +.br +. +aaa bbb ccc ddd eee fff ggg hhh\h'0'\R':k \n[.k]' +.tm :k == \n[:k] + @result{} :k == 15000 +@endExample + +If you process this with the PostScript device (@code{-Tps}), there will +be a line break eventually after @code{ggg} in both input lines. +However, after processing the space after @code{ggg}, the partially +collected line is not overfull yet, so GNU @code{troff} continues to +collect input until it sees the space (or in this case, the newline) +after @code{hhh}. At this point, the line is longer than the line +length, and the line gets broken. + +In the first input line, since the @code{\R} escape sequence leaves no +traces, the check for the overfull line hasn't been done yet at the +point where @code{\R} gets handled, and you get a value for the +@code{.k} register that is even greater than the current line length. + +In the second input line, the insertion of @code{\h'0'} to cause a +zero-width motion forces GNU @code{troff} to check the line length, +which in turn causes the start of a new output line. Now @code{.k} +returns the expected value. +@endDefreq + +@code{nr} and @code{\R} each have two additional special forms to +increment or decrement a register. + +@DefreqList {nr, ident @t{+}@Var{value}} +@DefreqItem {nr, ident @t{-}@Var{value}} +@DefescItemx {\\R, @code{'}, ident @t{+}value, @code{'}} +@DefescListEnd {\\R, @code{'}, ident @t{-}value, @code{'}} +Increment (decrement) register @var{ident} by @var{value}. In the +@code{\R} escape sequence, the delimiter need not be a neutral +apostrophe; see @ref{Delimiters}. + +@Example +.nr a 1 +.nr a +1 +\na + @result{} 2 +@endExample + +@cindex negating register values +A leading minus sign in @var{value} is always interpreted as a +decrementation operator, not an algebraic sign. To assign a register a +negative value or the negated value of another register, you can +force GNU @code{troff} to interpret @samp{-} as a negation or minus, +rather than decrementation, operator: enclose it with its operand in +parentheses or subtract it from zero. + +@Example +.nr a 7 +.nr b 3 +.nr a -\nb +\na + @result{} 4 +.nr a (-\nb) +\na + @result{} -3 +.nr a 0-\nb +\na + @result{} -3 +@endExample + +If a register's prior value does not exist (the register was undefined), +an increment or decrement is applied as if to@tie{}0. +@endDefreq + +@Defreq {rr, ident} +@cindex removing a register (@code{rr}) +@cindex register, removing (@code{rr}) +Remove register @var{ident}. If @var{ident} doesn't exist, the request +is ignored. Technically, only the name is removed; the register's +contents are still accessible under aliases created with @code{aln}, if +any. +@endDefreq + +@Defreq {rnn, ident1 ident2} +@cindex renaming a register (@code{rnn}) +@cindex register, renaming (@code{rnn}) +Rename register @var{ident1} to @var{ident2}. If @var{ident1} doesn't +exist, the request is ignored. Renaming a built-in register does not +otherwise alter its properties. +@endDefreq + +@Defreq {aln, new old} +@cindex alias, register, creating (@code{aln}) +@cindex creating alias for register (@code{aln}) +@cindex register, creating alias for (@code{aln}) +Create an alias @var{new} for an existing register @var{old}, causing +the names to refer to the same stored object. If @var{old} is +undefined, a warning in category @samp{reg} is produced and the request +is ignored. @xref{Warnings}, for information about the enablement and +suppression of warnings. + +@cindex alias, register, removing (@code{rr}) +@cindex removing alias for register (@code{rr}) +@cindex register, removing alias for (@code{rr}) +To remove a register alias, invoke @code{rr} on its name. A register's +contents do not become inaccessible until it has no more names. +@endDefreq +@c END Keep (roughly) parallel with subsection "Registers" of groff(7). + +@c --------------------------------------------------------------------- + +@node Interpolating Registers, Auto-increment, Setting Registers, Registers +@subsection Interpolating Registers +@cindex interpolating registers (@code{\n}) +@cindex registers, interpolating (@code{\n}) + +Register contents are interpolated with the @code{\n} escape sequence. + +@DefescList {\\n, , i, } +@DefescItem {\\n, (, id, } +@DefescListEnd {\\n, [, ident, ]} +@cindex nested assignments +@cindex assignments, nested +@cindex indirect assignments +@cindex assignments, indirect +Interpolate register with name @var{ident} (one-character +name@tie{}@var{i}, two-character name @var{id}). @code{\n} is +interpreted even in copy mode (@pxref{Copy Mode}). If the register is +undefined, it is created and assigned a value of@tie{}@samp{0}, that +value is interpolated, and a warning in category @samp{reg} is emitted. +@xref{Warnings}, for information about the enablement and suppression of +warnings. + +@Example +.nr a 5 +.nr as \na+\na +\n(as + @result{} 10 +@endExample + +@Example +.nr a1 5 +.nr ab 6 +.ds str b +.ds num 1 +\n[a\n[num]] + @result{} 5 +\n[a\*[str]] + @result{} 6 +@endExample +@endDefesc + +@c --------------------------------------------------------------------- + +@node Auto-increment, Assigning Register Formats, Interpolating Registers, Registers +@subsection Auto-increment +@cindex auto-incrementation of a register +@cindex incrementation, automatic, of a register +@cindex decrementation, automatic, of a register + +Registers can also be incremented or decremented by a configured amount +at the time they are interpolated. The value of the increment is +specified with a third argument to the @code{nr} request, and a special +interpolation syntax is used to alter and then retrieve the register's +value. Together, these features are called +@dfn{auto-increment}.@footnote{A negative auto-increment can be +considered an ``auto-decrement''.} + +@Defreq {nr, ident value incr} +@cindex @code{\R}, difference from @code{nr} +Set register @var{ident} to @var{value} and its auto-incrementation +amount to to @var{incr}. The @code{\R} escape sequence doesn't support +an @var{incr} argument. +@endDefreq + +Auto-incrementation is not @emph{completely} automatic; the @code{\n} +escape sequence in its basic form never alters the value of a register. +To apply auto-incrementation to a register, interpolate it with +@samp{\n±}. + +@DefescList {\\n, +, i, } +@DefescItem {\\n, -, i, } +@DefescItem {\\n, +(, id, } +@DefescItem {\\n, -(, id, } +@DefescItem {\\n, +[, ident, ]} +@DefescListEnd {\\n, -[, ident, ]} +Increment or decrement @var{ident} (one-character +name@tie{}@var{i}, two-character name @var{id}) by the register's +auto-incrementation value and then interpolate the new register value. +If @var{ident} has no auto-incrementation value, interpolate as with +@code{\n}. +@endDefesc + +@need 1000 +@Example +.nr a 0 1 +.nr xx 0 5 +.nr foo 0 -2 +\n+a, \n+a, \n+a, \n+a, \n+a +.br +\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx +.br +\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] + @result{} 1, 2, 3, 4, 5 + @result{} -5, -10, -15, -20, -25 + @result{} -2, -4, -6, -8, -10 +@endExample + +@cindex increment value without changing the register +@cindex value, incrementing without changing the register +To change the increment value without changing the value of a register, +assign the register's value to itself by interpolating it, and specify +the desired increment normally. Apply an increment of @samp{0} to +disable auto-incrementation of the register. + +@c --------------------------------------------------------------------- + +@node Assigning Register Formats, Built-in Registers, Auto-increment, Registers +@subsection Assigning Register Formats +@cindex assign number format to register (@code{af}) +@cindex number formats, assigning to register (@code{af}) +@cindex register, assigning number format to (@code{af}) + +A writable register's value can be interpolated in several number +formats. By default, conventional Arabic numerals are used. +Other formats see use in sectioning and outlining schemes and +alternative page numbering arrangements. + +@Defreq {af, reg fmt} +Use number format @var{fmt} when interpolating register @var{reg}. +Valid number formats are as follows. + +@table @code +@item 0@r{@dots{}} +Arabic numerals 0, 1, 2, and so on. +Any decimal digit is equivalent to @samp{0}; the formatter merely counts +the digits specified. Multiple Arabic numerals in @var{fmt} cause +interpolations to be zero-padded on the left if necessary to at least as +many digits as specified (interpolations never truncate a register +value). A register with format @samp{00} interpolates values 1, 2, 3 as +@samp{01}, @samp{02}, @samp{03}. The default format for all writable +registers is @samp{0}. + +@item I +@cindex Roman numerals +@cindex numerals, Roman +Uppercase Roman numerals: 0, I, II, III, IV,@tie{}@enddots{} + +@item i +Lowercase Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{} + +@item A +Uppercase letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{} + +@item a +Lowercase letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{} +@end table + +Omitting @var{fmt} causes a warning in category @samp{missing}. +@xref{Warnings}, for information about the enablement and suppression of +warnings. Specifying an unrecognized format is an error. + +Zero values are interpolated as @samp{0} in non-Arabic formats. +Negative quantities are prefixed with @samp{-} irrespective of format. +In Arabic formats, the sign supplements the field width. If @var{reg} +doesn't exist, it is created with a zero value. + +@Example +.nr a 10 +.af a 0 \" the default format +\na, +.af a I +\na, +.af a 321 +.nr a (-\na) +\na, +.af a a +\na + @result{} 10, X, -010, -j +@endExample + +@cindex Roman numerals, extrema (maximum and minimum) +@cindex extreme values representable with Roman numerals +@cindex maximum value representable with Roman numerals +@cindex minimum value representable with Roman numerals +The representable extrema in the @samp{i} and @samp{I} formats +correspond to Arabic ±39,999. GNU @code{troff} uses @samp{w} and +@samp{z} to represent 5,000 and 10,000 in Roman numerals, respectively, +following the convention of @acronym{AT&T} @code{troff}---currently, the +correct glyphs for Roman numerals five thousand (@code{U+2181}) and ten +thousand (@code{U+2182}) are not used. + +@cindex read-only register, changing format +@cindex changing format, and read-only registers +Assigning the format of a read-only register is an error. Instead, copy +the read-only register's value to, and assign the format of, a writable +register. +@endDefreq + +@DefescList {\\g, , r, } +@DefescItem {\\g, (, rg, } +@DefescListEnd {\\g, [, reg, ]} +@cindex format of register (@code{\g}) +@cindex register, format (@code{\g}) +Interpolate the format of the register @var{reg} (one-character +name@tie{}@var{r}, two-character name @var{rg}). Zeroes represent +Arabic formats. If @var{reg} is not defined, @var{reg} is not created +and nothing is interpolated. @code{\g} is interpreted even in copy mode +(@pxref{Copy Mode}). +@endDefesc + +@cindex register format, in expressions +@cindex expressions, and register format +GNU @code{troff} interprets only Arabic numerals. The Roman numeral or +alphabetic formats cannot be used as operands to arithmetic operators in +expressions (@pxref{Numeric Expressions}). For instance, it may be +desirable to test the page number independently of its format. + +@Example +.af % i \" front matter +.de header-trap +. \" To test the page number, we need it in Arabic. +. ds saved-page-number-format \\g%\" +. af % 0 +. nr page-number-in-decimal \\n% +. af % \\*[saved-page-number-format] +. ie \\n[page-number-in-decimal]=1 .do-first-page-stuff +. el \@{\ +. ie o .do-odd-numbered-page-stuff +. el .do-even-numbered-page-stuff +. \@} +. rm saved-page-number-format +.. +.wh 0 header-trap +@endExample + +@c --------------------------------------------------------------------- + +@node Built-in Registers, , Assigning Register Formats, Registers +@subsection Built-in Registers +@cindex built-in registers +@cindex registers, built-in + +Predefined registers whose identifiers start with a dot are read-only. +Many are Boolean-valued, interpolating a true or false value testable +with the @code{if}, @code{ie}, or @code{while} requests. Some read-only +registers are string-valued, meaning that they interpolate text. + +@cindex removing a built-in register +@cindex register, built-in, removing +@cindex built-in register, removing +@strong{Caution:@:} Built-in registers are subject to removal like +others; once removed, they can be recreated only as normal writable +registers and will not reflect formatter state. + +A register name (without the dot) is often associated with a request of +the same name. A complete listing of all built-in registers can be +found in @ref{Register Index}. + +We present here a few built-in registers that are not described +elsewhere in this manual; they have to do with invariant properties of +GNU @code{troff}, or obtain information about the formatter's +command-line options, processing progress, or the operating environment. + +@table @code +@item \n[.A] +@vindex .A +@cindex approximation output register (@code{.A}) +@cindex plain text approximation output register (@code{.A}) +Approximate output is being formatted (Boolean-valued); see +@command{groff} @option{-a} option (@ref{Groff Options}). + +@item \n[.c] +@vindex .c +@itemx \n[c.] +@vindex c. +@cindex input line number register (@code{.c}, @code{c.}) +@cindex line number, input, register (@code{.c}, @code{c.}) +Input line number. @samp{c.} is a writable synonym, +@c introduced in AT&T device-independent troff (CSTR #54, 1981-01) +affecting subsequent interpolations of both @samp{.c} and @samp{c.}. + +@item \n[.F] +@cindex current input file name register (@code{.F}) +@cindex input file name, current, register (@code{.F}) +@vindex .F +Name of input file (string-valued). + +@item \n[.g] +@vindex .g +@cindex GNU @code{troff}, identification register (@code{.g}) +@cindex GNU-specific register (@code{.g}) +Always true in GNU @code{troff} (Boolean-valued). Documents can use +this to ask the formatter if it claims @code{groff} compatibility. + +@item \n[.P] +@vindex .P +Output page selection status (Boolean-valued); see @command{groff} +@option{-o} option (@ref{Groff Options}). + +@item \n[.R] +@cindex number of registers register (@code{.R}) +@cindex registers, number of, register (@code{.R}) +@vindex .R +Count of available unused registers; always 10,000 in GNU +@code{troff}.@footnote{GNU @code{troff} dynamically allocates memory for +as many registers as required.} + +@item \n[.T] +@vindex .T +Indicator of output device selection (Boolean-valued); see +@command{groff} @option{-T} option (@ref{Groff Options}). + +@item \n[.U] +@cindex safer mode +@cindex mode, safer +@cindex unsafe mode +@cindex mode, unsafe +@vindex .U +Unsafe mode enablement status (Boolean-valued); see @command{groff} +@option{-U} option (@ref{Groff Options}). + +@item \n[.x] +@vindex .x +@cindex major version number register (@code{.x}) +@cindex version number, major, register (@code{.x}) +Major version number of the running GNU @code{troff} formatter. For +example, if the version number is 1.23.0, then @code{.x} +contains@tie{}@samp{1}. + +@item \n[.y] +@vindex .y +@cindex minor version number register (@code{.y}) +@cindex version number, minor, register (@code{.y}) +Minor version number of the running GNU @code{troff} formatter. For +example, if the version number is 1.23.0, then @code{.y} +contains@tie{}@samp{23}. + +@item \n[.Y] +@vindex .Y +@cindex revision number register (@code{.Y}) +Revision number of the running GNU @code{troff} formatter. For example, +if the version number is 1.23.0, then @code{.Y} contains@tie{}@samp{0}. + +@item \n[$$] +@vindex $$ +@cindex process ID of GNU @code{troff} register (@code{$$}) +@cindex PID of GNU @code{troff} register (@code{$$}) +@cindex GNU @code{troff}, process ID register (@code{$$}) +@cindex GNU @code{troff}, PID register (@code{$$}) +Process identifier (PID) of the GNU @code{troff} program in its +operating environment. +@end table + +Date- and time-related registers are set per the local time as +determined by @cite{localtime@r{(3)}} when the formatter launches. This +initialization can be overridden by @env{SOURCE_DATE_EPOCH} and +@env{TZ}; see @ref{Environment}. + +@table @code +@item \n[seconds] +@cindex seconds, current time (@code{seconds}) +@cindex time, current, seconds (@code{seconds}) +@cindex current time, seconds (@code{seconds}) +@vindex seconds +Count of seconds elapsed in the minute (0--60). @c not 59; see POSIX + +@item \n[minutes] +@cindex minutes, current time (@code{minutes}) +@cindex time, current, minutes (@code{minutes}) +@cindex current time, minutes (@code{minutes}) +@vindex minutes +Count of minutes elapsed in the hour (0--59). + +@item \n[hours] +@cindex hours, current time (@code{hours}) +@cindex time, current, hours (@code{hours}) +@cindex current time, hours (@code{hours}) +@vindex hours +Count of hours elapsed since midnight (0--23). + +@item \n[dw] +@cindex day of the week register (@code{dw}) +@cindex date, day of the week register (@code{dw}) +@vindex dw +Day of the week (1--7; 1 is Sunday). + +@item \n[dy] +@cindex day of the month register (@code{dy}) +@cindex date, day of the month register (@code{dy}) +@vindex dy +Day of the month (1--31). + +@item \n[mo] +@cindex month of the year register (@code{mo}) +@cindex date, month of the year register (@code{mo}) +@vindex mo +Month of the year (1--12). + +@item \n[year] +@cindex date, year register (@code{year}, @code{yr}) +@cindex year, current, register (@code{year}, @code{yr}) +@vindex year +Gregorian year. + +@cindex CSTR@tie{}#54 errata +@cindex CSTR@tie{}#54 erratum, @code{yr} register +@item \n[yr] +@vindex yr +Gregorian year minus@tie{}1900. This register is incorrectly documented +in the @acronym{AT&T} @code{troff} manual as storing the last two digits +of the current year. That claim stopped being true in 2000. Old +@code{troff} input that looks like: + +@Example +'\" The year number is a surprise after 1999. +This document was formatted in 19\n(yr. +@endExample + +@noindent +can be corrected to: + +@Example +This document was formatted in \n[year]. +@endExample + +@noindent +or, for portability across many @code{roff} programs, to the following. + +@Example +.nr y4 1900+\n(yr +This document was formatted in \n(y4. +@endExample +@end table + + +@c ===================================================================== + +@node Manipulating Filling and Adjustment, Manipulating Hyphenation, Registers, GNU troff Reference +@section Manipulating Filling and Adjustment +@cindex manipulating filling and adjustment +@cindex filling and adjustment, manipulating +@cindex adjustment and filling, manipulating +@cindex justifying text +@cindex text, justifying + +@cindex break +@cindex line break +@cindex @code{bp} request, causing implicit break +@cindex @code{ce} request, causing implicit break +@cindex @code{cf} request, causing implicit break +@cindex @code{fi} request, causing implicit break +@cindex @code{fl} request, causing implicit break +@cindex @code{in} request, causing implicit break +@cindex @code{nf} request, causing implicit break +@cindex @code{rj} request, causing implicit break +@cindex @code{sp} request, causing implicit break +@cindex @code{ti} request, causing implicit break +@cindex @code{trf} request, causing implicit break +When an output line is pending (see below), a break moves the drawing +position to the beginning of the next text baseline, interrupting +filling. Various ways of causing breaks were shown in @ref{Breaking}. +The @code{br} request likewise causes a break. Several other requests +imply breaks:@: @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, +@code{in}, @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}. +If the no-break control character is used with any of these requests, +GNU @code{troff} suppresses the break; instead the requested operation +takes effect at the next break. @samp{'br} does nothing. + +@Example +.ll 55n +This line is normally filled and adjusted. +.br +A line's alignment is decided +'ce \" Center the next input line (no break). +when it is output. +This line returns to normal filling and adjustment. + @result{} This line is normally filled and adjusted. + @result{} A line's alignment is decided when it is output. + @result{} This line returns to normal filling and adjustment. +@endExample + +@noindent +@cindex pending output line +@cindex partially collected line +@cindex output line properties +@cindex properties of output lines +Output line properties like page offset, indentation, adjustment, and +even the location of its text baseline, are not determined until the +line has been broken. An output line is said to be @dfn{pending} if +some input has been collected but an output line corresponding to it has +not yet been written; such an output line is also termed @dfn{partially +collected}. If no output line is pending, it is as if a break has +already happened; additional breaks, whether explicit or implicit, have +no effect. If the vertical drawing position is negative---as it is when +the formatter starts up---a break starts a new page (even if no output +line is pending) unless an end-of-input macro is being interpreted. +@xref{End-of-input Traps}. + +@Defreq {br, } +Break the line: emit any pending output line without adjustment. + +@Example +foo bar +.br +baz +'br +qux + @result{} foo bar + @result{} baz qux +@endExample +@endDefreq + +Sometimes you want to prevent a break within a phrase or between a +quantity and its units. + +@Defesc {\\~, , , } +@cindex unbreakable space (@code{\~}) +@cindex space, unbreakable (@code{\~}) +Insert an unbreakable space that is adjustable like an ordinary space. +It is discarded from the end of an output line if a break is forced. + +@Example +Set the output speed to\~1. +There are 1,024\~bytes in 1\~KiB. +J.\~F.\~Ossanna wrote the original CSTR\~#54. +@endExample +@endDefesc + +By default, GNU @code{troff} fills text and adjusts it to reach the +output line length. The @code{nf} request disables filling; the +@code{fi} request reënables it. + +@DefreqList {fi, } +@DefregListEndx {.u} +@cindex filling of output, enabling (@code{fi}) +@cindex output, filling, enablement of (@code{fi}) +@cindex fill mode (@code{fi}), enabling +@cindex mode, fill (@code{fi}), enabling +Enable filling of output lines; a pending output line is broken. The +read-only register @code{.u} is set to@tie{}1. The filling enablement +status, sometimes called @dfn{fill mode}, is associated with the +environment (@pxref{Environments}). @xref{Line Continuation}, for +interaction with the @code{\c} escape sequence. +@endDefreq + +@Defreq {nf, } +@cindex filling of output, disabling (@code{nf}) +@cindex output, filling, disablement of (@code{nf}) +@cindex no-fill mode +@cindex mode, no-fill +@cindex fill mode, disabling +@cindex mode, fill, disabling +Disable filling of output lines: the output line length (@pxref{Line +Layout}) is ignored and output lines are broken where the input lines +are. A pending output line is broken and adjustment is suppressed. The +read-only register @code{.u} is set to@tie{}0. The filling enablement +status is associated with the environment (@pxref{Environments}). See +@ref{Line Continuation}, for interaction with the @code{\c} escape +sequence. +@endDefreq + +@DefreqList {ad, [@Var{mode}]} +@DefregListEndx {.j} +Enable output line adjustment in @var{mode}, taking effect when the +pending (or next) output line is broken. Adjustment is suppressed when +filling is. @var{mode} can have one of the following values. + +@table @code +@item b +@itemx n +Adjust ``normally'':@: if the output line does not consume the distance +between the indentation and the configured output line length, GNU +@code{troff} stretches adjustable spaces within the line until that +length is reached. When the indentation is zero, this mode spreads the +line to both the left and right margins. This is the GNU @code{troff} +default. + +@item c +@cindex centered text (filled) +Center filled text. Contrast with the @code{ce} request, which centers +text @emph{without} filling it. + +@item l +@cindex ragged-right text +Align text to the left without adjusting it. + +@item r +@cindex ragged-left text +Align text to the right without adjusting it. +@end table + +@var{mode} can also be a value previously stored in the @code{.j} +register. Using @code{ad} without an argument is the same as @samp{.ad +\n[.j]}; unless filling is disabled, GNU @code{troff} resumes adjusting +lines in the same way it did before adjustment was disabled by +invocation of the @code{na} request. + +@cindex adjustment mode register (@code{.j}) +The adjustment mode and enablement status are encoded in the read-only +register @code{.j}. These parameters are associated with the +environment (@pxref{Environments}). + +The value of @code{.j} for any adjustment mode is an implementation +detail and should not be relied upon as a programmer's interface. Do +not write logic to interpret or perform arithmetic on it. + +@Example +.ll 48n +.de AD +. br +. ad \\$1 +.. +@c . @c XXX: Restore this line when the page has room for it. +.de NA +. br +. na +.. +@c . @c XXX: Restore this line when the page has room for it. +left +.AD r +.nr ad \n(.j +right +.AD c +center +.NA +left +.AD +center +.AD \n(ad +right +@endExample +@Example + @result{} left + @result{} right + @result{} center + @result{} left + @result{} center + @result{} right +@endExample +@endDefreq + +@Defreq {na, } +Disable output line adjustment. This produces the same output as +left-alignment, but the value of the adjustment mode register @code{.j} +is altered differently. The adjustment mode and enablement status are +associated with the environment (@pxref{Environments}). +@endDefreq + +@DefreqList {brp, } +@DefescListEndx {\\p, , , } +Break, adjusting the line per the current adjustment mode. @code{\p} +schedules a break with adjustment at the next word boundary. The escape +sequence is itself neither a break nor a space of any kind; it can thus +be placed in the middle of a word to cause a break at the end of that +word. + +Breaking with immediate adjustment can produce ugly results since GNU +@code{troff} doesn't have a sophisticated paragraph-building algorithm, +as @TeX{} has, for example. Instead, GNU @code{troff} fills and adjusts +a paragraph line by line. + +@Example +.ll 4.5i +This is an uninteresting sentence. +This is an uninteresting sentence.\p +This is an uninteresting sentence. +@endExample + +@noindent +is formatted as follows. + +@Example +This is an uninteresting sentence. This is +an uninteresting sentence. +This is an uninteresting sentence. +@endExample +@endDefreq + +@cindex productive input line +@cindex input line, productive +@cindex line, productive input +To clearly present the next couple of requests, we must introduce the +concept of ``productive'' input lines. A @dfn{productive input line} is +one that directly produces formatted output. Text lines produce +output,@footnote{unless diverted; see @ref{Diversions}} as do control +lines containing requests like @code{tl} or escape sequences like +@code{\D}. Macro calls are not @emph{directly} productive, and thus not +counted, but their interpolated contents can be. Empty requests, and +requests and escape sequences that define registers or strings or alter +the formatting environment (as with changes to the size, face, height, +slant, or color of the type) are not productive. We will also preview +the output line continuation escape sequence, @code{\c}, which +``connects'' two input lines that would otherwise be counted separately. +@footnote{@xref{Line Continuation}.} + +@Example +@c .ll 56n +.de hello +Hello, world! +.. +.ce \" center output of next productive input line +. +.nr junk-reg 1 +.ft I +Chorus: \c +.ft +.hello +Went the day well? + @result{} @slanted{Chorus:} Hello, world! + @result{} Went the day well? +@endExample + +@DefreqList {ce, [@Var{n}]} +@DefregListEndx {.ce} +@cindex centered text (unfilled) +@cindex centering lines (@code{ce}) +@cindex lines, centering (@code{ce}) +Break (unless the no-break control character is used), center the output +of the next @var{n} productive input lines with respect to the line +length and indentation without filling, then break again regardless of +the invoking control character. +@c Temporary indentation is ignored. +If the argument is not positive, centering is disabled. Omitting the +argument implies an @var{n} of @samp{1}. The count of lines remaining +to be centered is stored in the read-only register @code{.ce} and is +associated with the environment (@pxref{Environments}). + +@cindex @code{ce} request, difference from @w{@samp{.ad c}} +While the @w{@samp{.ad c}} request also centers text, it fills the text +as well. + +@c Wrap example at 56 columns. +@Example +.de FR +This is a small text fragment that shows the differences +between the `.ce' and the `.ad c' requests. +.. +.ll 4i +.ce 1000 +.FR +.ce 0 + +.ad c +.FR + @result{} This is a small text fragment that shows + @result{} the differences + @result{} between the @quoteleft{}.ce@quoteright{} and the @quoteleft{}.ad c@quoteright{} requests. + @result{} + @result{} This is a small text fragment that shows + @result{} the differences between the @quoteleft{}.ce@quoteright{} and + @result{} the @quoteleft{}.ad c@quoteright{} requests. +@endExample + +The previous example illustrates a common idiom of turning centering on +for a quantity of lines far in excess of what is required, and off again +after the text to be centered. This technique relieves humans of +counting lines for requests that take a count of input lines as an +argument. +@endDefreq + +@DefreqList {rj, [@Var{n}]} +@DefregListEndx {.rj} +@cindex justifying text (@code{rj}) +@cindex text, justifying (@code{rj}) +@cindex right-justifying (@code{rj}) +Break (unless the no-break control character is used), align the output +of the next @var{n} productive input lines to the right margin without +filling, then break again regardless of the control character. +@c Temporary indentation is ignored. +If the argument is not positive, right-alignment is disabled. Omitting +the argument implies an @var{n} of @samp{1}. The count of lines +remaining to be right-aligned is stored in the read-only register +@code{.rj} and is associated with the environment +(@pxref{Environments}). + +@Example +.ll 49n +.rj 3 +At first I hoped that such a technically unsound +project would collapse but I soon realized it was +doomed to success. \[em] C. A. R. Hoare + @result{} At first I hoped that such a technically unsound + @result{} project would collapse but I soon realized it was + @result{} doomed to success. -- C. A. R. Hoare +@endExample +@endDefreq + +@need 2000 +@DefreqList {ss, word-space-size [@Var{additional-sentence-space-size}]} +@DefregItemx {.ss} +@DefregListEndx {.sss} +@cindex word space size register (@code{.ss}) +@cindex size of word space register (@code{.ss}) +@cindex space between words register (@code{.ss}) +@cindex inter-sentence space size register (@code{.sss}) +@cindex sentence space size register (@code{.sss}) +@cindex size of sentence space register (@code{.sss}) +@cindex space between sentences register (@code{.sss}) +Set the sizes of spaces between words and +sentences@footnote{Recall @ref{Filling} and @ref{Sentences} for the +definitions of word and sentence boundaries, respectively.} in twelfths +of font's space width (typically one-fourth to one-third em for Western +scripts). The default for both parameters is@tie{}12. Negative values +are erroneous. +@cindex inter-word spacing, minimal +@cindex minimal inter-word spacing +@cindex space, between words +The first argument is a minimum; if an output line undergoes adjustment, +such spaces may increase in width. +@cindex inter-sentence space, additional +@cindex additional inter-sentence space +@cindex space, between sentences +The optional second argument sets the amount of additional space +separating sentences on the same output line. If omitted, this amount +is set to @var{word-space-size}. The request is ignored if there are no +parameters. + +@cindex filling, and inter-sentence space +@cindex mode, fill, and inter-sentence space +Additional inter-sentence space is used only if the output line is not +full when the end of a sentence occurs in the input. If a sentence ends +at the end of an input line, then both an inter-word space and an +inter-sentence space are added to the output; if two spaces follow the +end of a sentence in the middle of an input line, then the second space +becomes an inter-sentence space in the output. Additional +inter-sentence space is not adjusted, but the inter-word space that +always precedes it may be. Further input spaces after the second, if +present, are adjusted as normal. + +The read-only registers @code{.ss} and @code{.sss} hold the minimal +inter-word space and additional inter-sentence space amounts, +respectively. These parameters are part of the environment +(@pxref{Environments}), and rounded down to the nearest multiple +of@tie{}12 on terminals. + +@cindex discardable horizontal space +@cindex space, discardable, horizontal +@cindex horizontal discardable space +The @code{ss} request can insert discardable horizontal space; that is, +space that is discarded at a break. For example, some footnote styles +collect the notes into a single paragraph with large gaps between +each note. + +@Example +.ll 48n +1.\~J. Fict. Ch. Soc. 6 (2020), 3\[en]14. +.ss 12 48 \" applies to next sentence ending +Reprints no longer available through FCS. +.ss 12 \" go back to normal +2.\~Better known for other work. + @result{} 1. J. Fict. Ch. Soc. 6 (2020), 3-14. Reprints + @result{} no longer available through FCS. 2. Better + @result{} known for other work. +@endExample + +@noindent +If @emph{undiscardable} space is required, use the @code{\h} escape +sequence. +@endDefreq + + +@c ===================================================================== + +@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjustment, GNU troff Reference +@section Manipulating Hyphenation +@cindex manipulating hyphenation +@cindex hyphenation, manipulating + +@cindex hyphenation, automatic +@cindex automatic hyphenation +When filling, GNU @code{troff} hyphenates words as needed at +user-specified and automatically determined hyphenation points. The +machine-driven determination of hyphenation points in words requires +algorithms and data, and is susceptible to conventions and preferences. +Before tackling such @dfn{automatic hyphenation}, let us consider how +hyphenation points can be set explicitly. + +@cindex hyphenation, explicit +@cindex explicit hyphenation +@cindex hyphenation, manual +@cindex manual hyphenation +Explicitly hyphenated words such as ``mother-in-law'' are eligible for +breaking after each of their hyphens. Relatively few words in a +language offer such obvious break points, however, and automatic +detection of syllabic (or phonetic) boundaries for hyphenation is not +perfect,@footnote{Whether a perfect algorithm for this application is +even possible is an unsolved problem in computer science:@: +@url{https://tug.org/docs/liang/liang-thesis.pdf}.} particularly for +unusual words found in technical literature. We can instruct GNU +@code{troff} how to hyphenate specific words if the need arises. + +@cindex hyphenation exceptions +@Defreq {hw, word @dots{}} +Define each @dfn{hyphenation exception} @var{word} with each hyphen `-' +in the word indicating a hyphenation point. For example, the request + +@Example +.hw in-sa-lub-rious alpha +@endExample + +@c Serendipitously, in PDF output, the "alpha" below gets hyphenated. +@c Try to preserve this felicity in future edits. +marks potential hyphenation points in ``insalubrious'', and prevents +``alpha'' from being hyphenated at all. + +Besides the space character, any character whose hyphenation code is +zero can be used to separate the arguments of @code{hw} (see the +@code{hcode} request below). In addition, this request can be used more +than once. + +@cindex @code{hw} request, and @code{hy} restrictions +Hyphenation points specified with @code{hw} are not subject to the +within-word placement restrictions imposed by the @code{hy} request (see +below). + +Hyphenation exceptions specified with the @code{hw} request are +associated with the hyphenation language (see the @code{hla} request +below) and environment (@pxref{Environments}); invoking the @code{hw} +request in the absence of a hyphenation language is an error. + +The request is ignored if there are no parameters. +@endDefreq + +These are known as hyphenation @slanted{exceptions} in the expectation +that most users will avail themselves of automatic hyphenation; these +exceptions override any rules that would normally apply to a word +matching a hyphenation exception defined with @code{hw}. + +Situations also arise when only a specific occurrence of a word needs +its hyphenation altered or suppressed, or when a URL or similar string +needs to be breakable in sensible places without hyphenation. + +@DefescList {\\%, , , } +@DefescListEndx {\:, , , } +@cindex hyphenation character (@code{\%}) +@cindex character, hyphenation (@code{\%}) +@cindex disabling hyphenation (@code{\%}) +@cindex hyphenation, disabling (@code{\%}) +To tell GNU @code{troff} how to hyphenate words as they occur in input, +use the @code{\%} escape sequence; it is the default @dfn{hyphenation +character}. Each instance within a word indicates to GNU @code{troff} +that the word may be hyphenated at that point, while prefixing a word +with this escape sequence prevents it from being otherwise hyphenated. +This mechanism affects only that occurrence of the word; to change the +hyphenation of a word for the remainder of input processing, use the +@code{hw} request. + +@cindex @code{\X}, followed by @code{\%} +@cindex @code{\Y}, followed by @code{\%} +@cindex @code{\%}, following @code{\X} or @code{\Y} +GNU @code{troff} regards the escape sequences @code{\X} and @code{\Y} as +starting a word; that is, the @code{\%} escape sequence in, say, +@w{@samp{\X'...'\%foobar}} or @w{@samp{\Y'...'\%foobar}} no longer +prevents hyphenation of @samp{foobar} but inserts a hyphenation point +just prior to it; most likely this isn't what you want. +@xref{Postprocessor Access}. + +@cindex non-printing break point (@code{\:}) +@cindex breaking without hyphens (@code{\:}) +@cindex file names, breaking (@code{\:}) +@cindex breaking file names (@code{\:}) +@cindex URLs, breaking (@code{\:}) +@cindex breaking URLs (@code{\:}) +@code{\:} inserts a non-printing break point; that is, a word can break +there, but the soft hyphen glyph (see below) is not written to the +output if it does. This escape sequence is an input word boundary, so +the remainder of the word is subject to hyphenation as normal. + +You can combine @code{\:} and @code{\%} to control breaking of a file +name or URL, or to permit hyphenation only after certain explicit +hyphens within a word. + +@Example +@c Wrap example at 56 columns. +The \%Lethbridge-Stewart-\:\%Sackville-Baggins divorce +was, in retrospect, inevitable once the contents of +\%/var/log/\:\%httpd/\:\%access_log on the family web +server came to light, revealing visitors from Hogwarts. +@endExample +@endDefesc + +@Defreq {hc, [@Var{char}]} +Change the hyphenation character to @var{char}. This character then +works as the @code{\%} escape sequence normally does, and thus no longer +appears in the output.@footnote{@code{\%} itself stops marking +hyphenation points but still produces no output glyph.} Without an +argument, @code{hc} resets the hyphenation character to @code{\%} (the +default). The hyphenation character is associated with the environment +(@pxref{Environments}). +@endDefreq + +@Defreq {shc, [@Var{c}]} +@cindex soft hyphen character, setting (@code{shc}) +@cindex character, soft hyphen, setting (@code{shc}) +@cindex glyph, soft hyphen (@code{hy}) +@cindex soft hyphen glyph (@code{hy}) +@cindex @code{char} request, and soft hyphen character +@cindex @code{tr} request, and soft hyphen character +Set the @dfn{soft hyphen character}, inserted when a word is hyphenated +automatically or at a hyphenation character, to the ordinary or special +character@tie{}@var{c}.@footnote{``Soft'' because it appears in output +only where a hyphenation break is performed; a ``hard'' hyphen, as in +``long-term'', always appears.} If the argument is omitted, the soft +hyphen character is set to the default, @code{\[hy]}. If no glyph for +@var{c} exists in the font in use at a potential hyphenation point, then +the line is not broken there. Neither character definitions (specified +with the @code{char} and similar requests) nor translations (specified +with the @code{tr} request) are applied to @var{c}. +@endDefreq + +@cindex hyphenation parameters, automatic +@cindex automatic hyphenation parameters +Several requests influence automatic hyphenation. Because conventions +vary, a variety of hyphenation modes is available to the @code{hy} +request; these determine whether hyphenation will apply to a +word prior to breaking a line at the end of a page (more or less; see +below for details), and at which positions within that word +automatically determined hyphenation points are permissible. The places +within a word that are eligible for hyphenation are determined by +language-specific data and lettercase relationships. Furthermore, +hyphenation of a word might be suppressed due to a limit on +consecutive hyphenated lines (@code{hlm}), a minimum line length +threshold (@code{hym}), or because the line can instead be adjusted with +additional inter-word space (@code{hys}). + +@cindex hyphenation mode register (@code{.hy}) +@DefreqList {hy, [@Var{mode}]} +@DefregListEndx {.hy} +Set automatic hyphenation mode to @var{mode}, an integer encoding +conditions for hyphenation; if omitted, @samp{1} is implied. The +hyphenation mode is available in the read-only register @samp{.hy}; it +is associated with the environment (@pxref{Environments}). The default +hyphenation mode depends on the localization file loaded when GNU +@code{troff} starts up; see the @code{hpf} request below. + +Typesetting practice generally does not avail itself of every +opportunity for hyphenation, but the details differ by language and site +mandates. The hyphenation modes of @acronym{AT&T} @code{troff} were +implemented with English-language publishing practices of the 1970s in +mind, not a scrupulous enumeration of conceivable parameters. GNU +@code{troff} extends those modes such that finer-grained control is +possible, favoring compatibility with older implementations over a more +intuitive arrangement. The means of hyphenation mode control is a set +of numbers that can be added up to encode the behavior +sought.@footnote{The mode is a vector of Booleans encoded as an integer. +To a programmer, this fact is easily deduced from the exclusive use of +powers of two for the configuration parameters; they are computationally +easy to ``mask off'' and compare to zero. To almost everyone else, the +arrangement seems recondite and unfriendly.} The entries in the +following table are termed @dfn{values}; the sum of the desired +values is the @dfn{mode}. + +@table @code +@item 0 +disables hyphenation. + +@item 1 +enables hyphenation except after the first and before the last character +of a word. +@end table + +The remaining values ``imply'' 1; that is, they enable hyphenation +under the same conditions as @samp{.hy 1}, and then apply or lift +restrictions relative to that basis. + +@table @code +@item 2 +disables hyphenation of the last word on a page,@footnote{Hyphenation is +prevented if the next page location trap is closer to the vertical +drawing position than the next text baseline would be. @xref{Page +Location Traps}.} even for explicitly hyphenated words. + +@item 4 +disables hyphenation before the last two characters of a word. + +@item 8 +disables hyphenation after the first two characters of a word. + +@item 16 +enables hyphenation before the last character of a word. + +@item 32 +enables hyphenation after the first character of a word. +@end table + +Apart from value@tie{}2, restrictions imposed by the hyphenation mode +are @emph{not} respected for words whose hyphenations have been +specified with the hyphenation character (@samp{\%} by default) or the +@code{hw} request. + +Nonzero values in the previous table are additive. For example, +mode@tie{}12 causes GNU @code{troff} to hyphenate neither the last two +nor the first two characters of a word. Some values cannot be used +together because they contradict; for instance, values 4 and@tie{}16, +and values 8 and@tie{}32. As noted, it is superfluous to add 1 to any +non-zero even mode. + +@cindex hyphenation pattern files +@cindex pattern files, for hyphenation +The automatic placement of hyphens in words is determined by +@dfn{pattern files}, which are derived from @TeX{} and available for +several languages. The number of characters at the beginning of a word +after which the first hyphenation point should be inserted is determined +by the patterns themselves; it can't be reduced further without +introducing additional, invalid hyphenation points (unfortunately, this +information is not part of a pattern file---you have to know it in +advance). The same is true for the number of characters at the end of +a word before the last hyphenation point should be inserted. For +example, you can supply the following input to @samp{echo $(nroff)}. + +@Example +.ll 1 +.hy 48 +splitting +@endExample + +@noindent +You will get + +@Example +s- plit- t- in- g +@endExample + +@noindent +instead of the correct `split- ting'. English patterns as distributed +with GNU @code{troff} need two characters at the beginning and three +characters at the end; this means that value@tie{}4 of @code{hy} is +mandatory. Value@tie{}8 is possible as an additional restriction, but +values@tie{}16 and@tie{}32 should be avoided, as should mode@tie{}1. +Modes@tie{}4 and@tie{}6 are typical. + +A table of left and right minimum character counts for hyphenation as +needed by the patterns distributed with GNU @code{troff} follows; see +the @cite{groff_tmac@r{(5)}} man page for more information on GNU +@code{troff}'s language macro files. + +@multitable {German traditional} {pattern name} {left min} {right min} +@headitem language @tab pattern name @tab left min @tab right min +@item Czech @tab cs @tab 2 @tab 2 +@item English @tab en @tab 2 @tab 3 +@item French @tab fr @tab 2 @tab 3 +@item German traditional @tab det @tab 2 @tab 2 +@item German reformed @tab den @tab 2 @tab 2 +@item Italian @tab it @tab 2 @tab 2 +@item Swedish @tab sv @tab 1 @tab 2 +@end multitable + +Hyphenation exceptions within pattern files (i.e., the words within a +@TeX{} @code{\hyphenation} group) obey the hyphenation restrictions +given by @code{hy}. +@endDefreq + +@Defreq {nh, } +Disable automatic hyphenation; i.e., set the hyphenation mode to@tie{}0 +(see above). The hyphenation mode of the last call to @code{hy} is not +remembered. +@endDefreq + +@need 200 +@DefreqList {hpf, pattern-file} +@DefreqItemx {hpfa, pattern-file} +@DefreqListEndx {hpfcode, a b [c d] @dots{}} +@cindex hyphenation patterns (@code{hpf}) +@cindex patterns for hyphenation (@code{hpf}) +Read hyphenation patterns from @var{pattern-file}, which is sought +in the same way that macro files are with the @code{mso} request or the +@option{-m@var{name}} command-line option to @code{groff}. The +@var{pattern-file} should have the same format as (simple) @TeX{} +pattern files. More specifically, the following scanning rules are +implemented. + +@itemize @bullet +@item +A percent sign starts a comment (up to the end of the line) even if +preceded by a backslash. + +@item +``Digraphs'' like @code{\$} are not supported. + +@item +@code{^^@var{xx}} (where each @var{x} is 0--9 or a--f) and +@code{^^@var{c}} (character @var{c} in the code point range 0--127 +decimal) are recognized; other uses of @code{^} cause an error. + +@item +No macro expansion is performed. + +@item +@code{hpf} checks for the expression @code{\patterns@{@dots{}@}} +(possibly with whitespace before or after the braces). Everything +between the braces is taken as hyphenation patterns. Consequently, +@code{@{} and @code{@}} are not allowed in patterns. + +@item +Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation +exceptions. + +@item +@code{\endinput} is recognized also. + +@item +For backward compatibility, if @code{\patterns} is missing, the whole +file is treated as a list of hyphenation patterns (except that the +@code{%} character is recognized as the start of a comment). +@end itemize + +The @code{hpfa} request appends a file of patterns to the current list. + +The @code{hpfcode} request defines mapping values for character codes in +pattern files. It is an older mechanism no longer used by GNU +@code{troff}'s own macro files; for its successor, see @code{hcode} +below. @code{hpf} or @code{hpfa} apply the mapping after reading the +patterns but before replacing or appending to the active list of +patterns. Its arguments are pairs of character codes---integers from 0 +to@tie{}255. The request maps character code@tie{}@var{a} to +code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. +Character codes that would otherwise be invalid in GNU @code{troff} can +be used. By default, every code maps to itself except those for letters +`A' to `Z', which map to those for `a' to `z'. + +@cindex localization +@pindex troffrc +@pindex cs.tmac +@pindex de.tmac +@pindex en.tmac +@pindex fr.tmac +@pindex it.tmac +@pindex ja.tmac +@pindex sv.tmac +@pindex zh.tmac +The set of hyphenation patterns is associated with the language set by +the @code{hla} request (see below). The @code{hpf} request is usually +invoked by a localization file loaded by the @file{troffrc} +file.@footnote{For more on localization, see the +@cite{groff_tmac@r{(5)}} man page.} + +A second call to @code{hpf} (for the same language) replaces the +hyphenation patterns with the new ones. Invoking @code{hpf} or +@code{hpfa} causes an error if there is no hyphenation language. If no +@code{hpf} request is specified (either in the document, in a file +loaded at startup, or in a macro package), GNU @code{troff} won't +automatically hyphenate at all. +@endDefreq + +@Defreq {hcode, c1 code1 [c2 code2] @dots{}} +@cindex hyphenation code (@code{hcode}) +@cindex code, hyphenation (@code{hcode}) +Set the hyphenation code of character @var{c1} to @var{code1}, that of +@var{c2} to @var{code2}, and so on. A hyphenation code must be an +ordinary character (not a special character escape sequence) other than +a digit or a space. The request is ignored if given no arguments. + +For hyphenation to work, hyphenation codes must be set up. At +startup, GNU @code{troff} assigns hyphenation codes to the letters +@samp{a}--@samp{z} (mapped to themselves), to the letters +@samp{A}--@samp{Z} (mapped to @samp{a}--@samp{z}), and zero to all other +characters. Normally, hyphenation patterns contain only lowercase +letters which should be applied regardless of case. In other words, +they assume that the words `FOO' and `Foo' should be hyphenated exactly +as `foo' is. The @code{hcode} request extends this principle to letters +outside the Unicode basic Latin alphabet; without it, words containing +such letters won't be hyphenated properly even if the corresponding +hyphenation patterns contain them. + +For example, the following @code{hcode} requests are necessary to assign +hyphenation codes to the letters @samp{ÄäÖöÜüß}, needed for German. + +@Example +.hcode ä ä Ä ä +.hcode ö ö Ö ö +.hcode ü ü Ü ü +.hcode ß ß +@endExample + +Without these assignments, GNU @code{troff} treats the German word +@w{`Kindergärten'} (the plural form of `kindergarten') as two words +@w{`kinderg'} and @w{`rten'} because the hyphenation code of the +umlaut@tie{}a is zero by default, just like a space. There is a German +hyphenation pattern that covers @w{`kinder'}, so GNU @code{troff} finds +the hyphenation `kin-der'. The other two hyphenation points +(`kin-der-gär-ten') are missed. +@endDefreq + +@DefreqList {hla, lang} +@DefregListEndx {.hla} +@cindex @code{hpf} request, and hyphenation language +@cindex @code{hw} request, and hyphenation language +@pindex troffrc +@pindex troffrc-end +Set the hyphenation language to @var{lang}. Hyphenation exceptions +specified with the @code{hw} request and hyphenation patterns and +exceptions specified with the @code{hpf} and @code{hpfa} requests are +associated with the hyphenation language. The @code{hla} request is +usually invoked by a localization file, which is turn loaded by the +@file{troffrc} or @file{troffrc-end} file; see the @code{hpf} request +above. + +@cindex hyphenation language register (@code{.hla}) +The hyphenation language is available in the read-only string-valued +register @samp{.hla}; it is associated with the environment +(@pxref{Environments}). +@endDefreq + +@DefreqList {hlm, [@Var{n}]} +@DefregItemx {.hlm} +@DefregListEndx {.hlc} +@cindex explicit hyphen (@code{\%}) +@cindex hyphen, explicit (@code{\%}) +@cindex consecutive hyphenated lines (@code{hlm}) +@cindex lines, consecutive hyphenated (@code{hlm}) +@cindex hyphenated lines, consecutive (@code{hlm}) +Set the maximum quantity of consecutive hyphenated lines to @var{n}. If +@var{n} is negative, there is no maximum. If omitted, @var{n} +is@tie{}@minus{}1. This value is associated with the environment +(@pxref{Environments}). Only lines output from a given environment +count toward the maximum associated with that environment. Hyphens +resulting from @code{\%} are counted; explicit hyphens are not. + +@cindex hyphenation consecutive line limit register (@code{.hlm}) +@cindex hyphenation consecutive line count register (@code{.hlc}) +The @code{.hlm} read-only register stores this maximum. The count of +immediately preceding consecutive hyphenated lines is available in the +read-only register @code{.hlc}. +@endDefreq + +@DefreqList {hym, [@Var{length}]} +@DefregListEndx {.hym} +@cindex hyphenation margin (@code{hym}) +@cindex margin for hyphenation (@code{hym}) +@cindex @code{ad} request, and hyphenation margin +Set the (right) hyphenation margin to @var{length}. If the adjustment +mode is not @samp{b} or @samp{n}, the line is not hyphenated if it is +shorter than @var{length}. Without an argument, the hyphenation margin +is reset to its default value, 0. The default scaling unit is @samp{m}. +The hyphenation margin is associated with the environment +(@pxref{Environments}). + +A negative argument resets the hyphenation margin to zero, emitting a +warning in category @samp{range}. + +@cindex hyphenation margin register (@code{.hym}) +The hyphenation margin is available in the @code{.hym} read-only +register. +@endDefreq + +@DefreqList {hys, [@Var{hyphenation-space}]} +@DefregListEndx {.hys} +@cindex hyphenation space (@code{hys}) +@cindex hyphenation space adjustment threshold +@cindex @code{ad} request, and hyphenation space +Suppress hyphenation of the line in adjustment modes @samp{b} or +@samp{n} if it can be justified by adding no more than +@var{hyphenation-space} extra space to each inter-word space. Without +an argument, the hyphenation space adjustment threshold is set to its +default value, 0. The default scaling unit is @samp{m}. The +hyphenation space adjustment threshold is associated with the +environment (@pxref{Environments}). + +A negative argument resets the hyphenation space adjustment threshold to +zero, emitting a warning in category @samp{range}. + +@cindex hyphenation space adjustment threshold register (@code{.hys}) +The hyphenation space adjustment threshold is available in the +@code{.hys} read-only register. +@endDefreq + + +@c ===================================================================== + +@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, GNU troff Reference +@section Manipulating Spacing +@cindex manipulating spacing +@cindex spacing, manipulating + +A break causes the formatter to update the vertical drawing position at +which the new text baseline is aligned. You can alter this location. + +@Defreq {sp, [@Var{distance}]} +Break and move the next text baseline down by @var{distance}, or until +springing a page location trap.@footnote{@xref{Page Location Traps}.} +If invoked with the no-break control character, @code{sp} moves the +pending output line's text baseline by @var{distance}. A negative +@var{distance} will not reduce the position of the text baseline below +zero. Inside a diversion, any @var{distance} argument is ignored. The +default scaling unit is @samp{v}. If @var{distance} is not specified, +@samp{1v} is assumed. + +@Example +.pl 5v \" Set page length to 5 vees. +.de xx +\-\-\- +. br +.. +.wh 0 xx \" Set a trap at the top of the page. +foo on page \n% +.sp 2v +bar on page \n% +.sp 50v \" This will cause a page break. +baz on page \n% +.pl \n(nlu \" Truncate page to current position. + @result{} --- + @result{} foo on page 1 + @result{} + @result{} + @result{} bar on page 1 + @result{} --- + @result{} baz on page 2 +@endExample + +You might use the following macros to set the baseline of the next +output text at a given distance from the top or the bottom of the page. +We subtract one line height (@code{\n[.v]}) because the @code{|} +operator moves to one vee below the page top (recall @ref{Numeric +Expressions}). + +@Example +.de y-from-top-down +. sp |\\$1-\\n[.v]u +.. +. +.de y-from-bot-up +. sp |\\n[.p]u-\\$1-\\n[.v]u +.. +@endExample + +@noindent +A call to @samp{.y-from-bot-up 10c} means that the next text baseline +will be 10@tie{}cm from the bottom edge of the paper. +@endDefreq + +@DefreqList {ls, [@Var{count}]} +@DefregListEndx {.L} +@cindex double-spacing (@code{ls}) +Set the line spacing; add @w{@var{count}@minus{}1} blank lines after each +line of text. With no argument, GNU @code{troff} uses the previous +value before the last @code{ls} call. The default is @code{1}. + +@c This example is fairly obvious, doesn't realistically reflect the +@c fact that formatted text would occur between each of these requests, +@c and doesn't fit well on the (PDF) page as of this writing. +@c @Example +@c .ls 2 \" begin double-spaced output +@c .ls 3 \" begin triple-spaced output +@c .ls \" return to double-spaced output +@c @endExample + +@cindex line spacing register (@code{.L}) +The read-only register @code{.L} contains the current line spacing; it +is associated with the environment (@pxref{Environments}). +@endDefreq + +The @code{ls} request is a coarse mechanism. @xref{Changing the Type +Size}, for the requests @code{vs} and @code{pvs} as alternatives to +@code{ls}. + +@DefescList {\\x, @code{'}, spacing, @code{'}} +@DefregListEndx {.a} +Sometimes, an output line requires additional vertical spacing, for +instance to allow room for a tall construct like an inline equation with +exponents or subscripts (particularly if they are iterated). The +@code{\x} escape sequence takes a delimited measurement (like +@samp{\x'3p'}) to increase the vertical spacing of the pending output +line. The default scaling unit is @samp{v}. If the measurement is +positive, extra vertical space is inserted below the current line; a +negative measurement adds space above. If @code{\x} is applied to the +pending output line multiple times, the maxima of the positive and +negative adjustments are separately applied. The delimiter need not be +a neutral apostrophe; see @ref{Delimiters}. + +@cindex extra post-vertical line space register (@code{.a}) +The @code{.a} read-only register contains the extra vertical spacing +@emph{after} the text baseline of the most recently emitted output line. +(In other words, it is the largest positive argument to @code{\x} +encountered on that line.) This quantity is exposed via a register +because if an output line requires this ``extra post-vertical line +spacing'', and the subsequent output line requires ``extra pre-vertical +line spacing'' (a negative argument to @code{\x}), then applying both +can lead to excessive spacing between the output lines. Text that is +piling high on line @var{n} might not require (as much) extra +pre-vertical line spacing if line @var{n}@minus{}1 carries extra +post-vertical line spacing. + +Use of @code{\x} can be necessary in combination with the +bracket-building escape sequence @code{\b},@footnote{@xref{Drawing +Geometric Objects}.} as the following example shows. + +@Example +.nf +This is a test of \[rs]b (1). +This is a test of \[rs]b (2). +This is a test of \b'xyz'\x'-1m'\x'1m' (3). +This is a test of \[rs]b (4). +This is a test of \[rs]b (5). + @result{} This is a test of \b (1). + @result{} This is a test of \b (2). + @result{} x + @result{} This is a test of y (3). + @result{} z + @result{} This is a test of \b (4). + @result{} This is a test of \b (5). +@endExample +@endDefesc + +@noindent +Without @code{\x}, the backslashes on the lines marked @samp{(2)} and +@samp{(4)} would be overprinted. + +@need 1000 +@DefreqList {ns, } +@DefreqItemx {rs, } +@DefregListEndx {.ns} +@cindex @code{sp} request, and no-space mode +@cindex no-space mode (@code{ns}) +@cindex mode, no-space (@code{ns}) +@cindex blank lines, disabling +@cindex lines, blank, disabling +Enable @dfn{no-space mode}. Vertical spacing, whether by @code{sp} +requests or blank input lines, is disabled. The @code{bp} request to +advance to the next page is also disabled, unless it is accompanied by a +page number (@pxref{Page Control}). No-space mode ends automatically +when text@footnote{or geometric objects; see @ref{Drawing Geometric +Objects}} is formatted for output @footnote{to the top-level diversion; +see @ref{Diversions}} or the @code{rs} request is invoked, which ends +no-space mode. The read-only register @code{.ns} interpolates a Boolean +value indicating the enablement of no-space mode. + +A paragraphing macro might ordinarily insert vertical space to separate +paragraphs. A section heading macro could invoke @code{ns} to suppress +this spacing for the first paragraph in a section. +@endDefreq + + +@c ===================================================================== + +@node Tabs and Fields, Character Translations, Manipulating Spacing, GNU troff Reference +@section Tabs and Fields +@cindex tabs, and fields +@cindex fields, and tabs + +@cindex tab character encoding +A tab character (@acronym{ISO} code point@tie{}9, @acronym{EBCDIC} +code point@tie{}5) causes a horizontal movement to the next tab stop, if +any. + +@Defesc {\\t, , , } +@cindex tab character, non-interpreted (@code{\t}) +@cindex character, tab, non-interpreted (@code{\t}) +@cindex @code{\t}, and copy mode +@cindex copy mode, and @code{\t} +@cindex mode, copy, and @code{\t} +Interpolate a tab in copy mode; see @ref{Copy Mode}. +@endDefesc + +@DefreqList {ta, [[@Var{n1} @Var{n2} @dots{} @Var{nn} ]@t{T} @Var{r1} @ + @Var{r2} @dots{} @Var{rn}]} +@DefregListEndx {.tabs} +Change tab stop positions. This request takes a series of tab +specifiers as arguments (optionally divided into two groups with the +letter @samp{T}) that indicate where each tab stop is to be, overriding +any previous settings. The default scaling unit is @samp{m}. Invoking +@code{ta} without an argument removes all tab stops. +@cindex default tab stops +@cindex tab stops, default +GNU @code{troff}'s startup value is @w{@samp{T 0.5i}}. + +Tab stops can be specified absolutely---as distances from the left +margin. The following example sets six tab stops, one every inch. + +@Example +.ta 1i 2i 3i 4i 5i 6i +@endExample + +Tab stops can also be specified using a leading @samp{+}, which means +that the specified tab stop is set relative to the previous tab stop. +For example, the following is equivalent to the previous example. + +@Example +.ta 1i +1i +1i +1i +1i +1i +@endExample + +GNU @code{troff} supports an extended syntax to specify repeating tab +stops. These stops appear after a @samp{T} argument. Their values are +always taken as distances relative to the previous tab stop. This is +the idiomatic way to specify tab stops at equal intervals in +@code{groff}. The following is, yet again, the same as the previous +examples. It does more, in fact, since it defines an infinite number of +tab stops at one-inch intervals. + +@Example +.ta T 1i +@endExample + +Now we are ready to interpret the full syntax given above. The +@code{ta} request sets tabs at positions @var{n1}, @var{n2}, @dots{}, +@var{nn}, then at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, +@var{nn}+@var{rn}, then at @var{nn}+@var{rn}+@var{r1}, +@var{nn}+@var{rn}+@var{r2}, @dots{}, @var{nn}+@var{rn}+@var{rn}, and so +on. + +For example, @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c +18c 20c 23c 28c 30c @dots{}}. + +Text written to a tab column (i.e., between two tab stops, or between a +tab stop and an output line boundary) may be aligned to the right or +left, or centered in the column. This alignment is determined by +appending @samp{R}, @samp{L}, or @samp{C} to the tab specifier. The +default is @samp{L}. + +@Example +.ta 1i 2iC 3iR +@endExample + +The beginning of an output line is not a tab stop; the text that begins +an output line is placed according to the configured alignment and +indentation; see @ref{Manipulating Filling and Adjustment} and @ref{Line +Layout}. + +A tab stop is converted into a non-breakable horizontal movement that +cannot be adjusted. + +@Example +.ll 2i +.ds foo a\tb\tc +.ta T 1i +\*[foo] + @error{} warning: cannot break line + @result{} a b c +@endExample + +@noindent +The above creates a single output line that is a bit longer than two +inches (we use a string to show exactly where the tab stops are). +Now consider the following. + +@Example +.ll 2i +.ds bar a\tb c\td +.ta T 1i +\*[bar] + @error{} warning: cannot adjust line + @result{} a b + @result{} c d +@endExample + +@noindent +GNU @code{troff} first converts the line's tab stops into unbreakable +horizontal movements, then breaks after @samp{b}. This usually isn't +what you want. + +Superfluous tab characters---those that do not correspond to a tab +stop---are ignored except for the first, which delimits the characters +belonging to the last tab stop for right-alignment or centering. + +@Example +.ds Z foo\tbar\tbaz +.ds ZZ foo\tbar\tbazqux +.ds ZZZ foo\tbar\tbaz\tqux +.ta 2i 4iR +\*[Z] +.br +\*[ZZ] +.br +\*[ZZZ] +.br + @result{} foo bar baz + @result{} foo bar bazqux + @result{} foo bar bazqux +@endExample + +@noindent +The first line right-aligns ``baz'' within the second tab stop. The +second line right-aligns ``bazqux'' within it. The third line +right-aligns only ``baz'' because of the additional tab character, which +marks the end of the text occupying the last tab stop defined. + +Tab stops are associated with the environment (@pxref{Environments}). + +@cindex tab stop settings register (@code{.tabs}) +@cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs} +@cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S}) +The read-only register @code{.tabs} contains a string +representation of the current tab settings suitable for use as an +argument to the @code{ta} request.@footnote{Plan@tie{}9 @code{troff} +uses the register @code{.S} for this purpose.} + +@Example +.ds tab-string \n[.tabs] +\*[tab-string] + @result{} T120u +@endExample +@endDefreq + +@Defreq {tc, [@Var{c}]} +@cindex tab repetition character (@code{tc}) +@cindex character, tab repetition (@code{tc}) +@cindex glyph, tab repetition (@code{tc}) +Set the tab repetition character to the ordinary or special character +@var{c}; normally, no glyph is written when moving to a tab stop (and +some output devices may output space characters to achieve this motion). +A @dfn{tab repetition character} causes the formatter to write as many +instances of @var{c} as are necessary to occupy the interval from the +horizontal drawing position to the next tab stop. With no argument, GNU +@code{troff} reverts to the default behavior. The tab repetition +character is associated with the environment (@pxref{Environments}). +Only a single character of @var{c} is recognized; any excess is ignored. +@endDefreq + +@DefreqList {linetabs, n} +@DefregListEndx {.linetabs} +@cindex tab, line-tabs mode +@cindex line-tabs mode +@cindex mode, line-tabs +If @var{n} is missing or non-zero, activate @dfn{line-tabs}; deactivate +it otherwise (the default). Active line-tabs cause GNU @code{troff} +to compute tab distances relative to the start of the output line +instead of the input line. + +@Example +.de Tabs +. ds x a\t\c +. ds y b\t\c +. ds z c +. ta 1i 3i +\\*x +\\*y +\\*z +.. +.Tabs +.br +.linetabs +.Tabs + @result{} a b c + @result{} a b c +@endExample + +Line-tabs activation is associated with the environment +(@pxref{Environments}). The read-only register @code{.linetabs} +interpolates@tie{}1 if line-tabs are active, and 0 otherwise. +@endDefreq + +@menu +* Leaders:: +* Fields:: +@end menu + +@c --------------------------------------------------------------------- + +@node Leaders, Fields, Tabs and Fields, Tabs and Fields +@subsection Leaders +@cindex leaders + +Sometimes it is desirable to fill a tab stop with a given glyph, +but also use tab stops normally on the same output line. An example is +a table of contents entry that uses dots to bridge the entry name with +its page number, which is itself aligned between tab stops. The +@code{roff} language provides @dfn{leaders} for this +purpose.@footnote{This is pronounced to rhyme with ``feeder'', and +refers to how the glyphs ``lead'' the eye across the page to the +corresponding page number or other datum.} + +@cindex leader character +A leader character (@acronym{ISO} and @acronym{EBCDIC} code +point@tie{}1, also known as @acronym{SOH} or ``start of heading''), +behaves similarly to a tab character:@: it moves to the next tab stop. +The difference is that for this movement, the default fill character is +a period @samp{.}. + +@Defesc {\\a, , , } +@cindex leader character, non-interpreted (@code{\a}) +@cindex character, leader, non-interpreted (@code{\a}) +@cindex @code{\a}, and copy mode +@cindex copy mode, and @code{\a} +@cindex mode, copy, and @code{\a} +Interpolate a leader in copy mode; see @ref{Copy Mode}. +@endDefesc + +@Defreq {lc, [@Var{c}]} +@cindex leader repetition character (@code{lc}) +@cindex character, leader repetition (@code{lc}) +@cindex glyph, leader repetition (@code{lc}) +Set the leader repetition character to the ordinary or special character +@var{c}. Recall @ref{Tabs and Leaders}:@: when encountering a leader +character in the input, the formatter writes as many dots @samp{.} as +are necessary until +reaching the next tab stop; this is the @dfn{leader definition +character}. Omitting @var{c} unsets the leader +character. With no argument, GNU @code{troff} treats leaders the same +as tabs. The leader repetition character is associated with the +environment (@pxref{Environments}). Only a single @var{c} is +recognized; any excess is ignored. +@endDefreq + +@cindex table of contents +@cindex contents, table of +A table of contents, for example, may define tab stops after a section +number, a title, and a gap to be filled with leader dots. The page +number follows the leader, after a right-aligned final tab stop wide +enough to house the largest page number occurring in the document. + +@Example +.ds entry1 19.\tThe Prophet\a\t98 +.ds entry2 20.\tAll Astir\a\t101 +.ta .5i 4.5i +.5iR +.nf +\*[entry1] +\*[entry2] + @result{} 19. The Prophet............................. 98 + @result{} 20. All Astir............................... 101 +@endExample + +@c --------------------------------------------------------------------- + +@node Fields, , Leaders, Tabs and Fields +@subsection Fields +@cindex fields + +@cindex field delimiting character (@code{fc}) +@cindex delimiting character, for fields (@code{fc}) +@cindex character, field delimiting (@code{fc}) +@cindex field padding character (@code{fc}) +@cindex padding character, for fields (@code{fc}) +@cindex character, field padding (@code{fc}) +@dfn{Fields} are a more general way of laying out tabular data. A field +is defined as the data between a pair of @dfn{delimiting characters}. +It contains substrings that are separated by @dfn{padding characters}. +The width of a field is the distance on the @emph{input} line from the +position where the field starts to the next tab stop. A padding +character inserts an adjustable space similar to @TeX{}'s @code{\hss} +command (thus it can even be negative) to make the sum of all substring +lengths plus the adjustable space equal to the field width. If more +than one padding character is inserted, the available space is evenly +distributed among them. + +@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]} +Define a delimiting and a padding character for fields. If the latter +is missing, the padding character defaults to a space character. If +there is no argument at all, the field mechanism is disabled (which is +the default). In contrast to, e.g., the tab repetition character, +delimiting and padding characters are @emph{not} associated with the +environment (@pxref{Environments}). + +@Example +.fc # ^ +.ta T 3i +#foo^bar^smurf# +.br +#foo^^bar^smurf# + @result{} foo bar smurf + @result{} foo bar smurf +@endExample +@endDefreq + + +@c ===================================================================== + +@node Character Translations, @code{troff} and @code{nroff} Modes, Tabs and Fields, GNU troff Reference +@section Character Translations +@cindex character translations +@cindex translations of characters + +A @dfn{translation} is a mapping of an input character to an output +glyph. The mapping occurs at output time, i.e., the input character +gets assigned the metric information of the mapped output character +right before input tokens are converted to nodes (@pxref{Gtroff +Internals}, for more on this process). + +@DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} +@DefreqListEndx {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} +Translate character @var{a} to glyph@tie{}@var{b}, character @var{c} to +glyph@tie{}@var{d}, and so on. If there is an odd number of characters +in the argument, the last one is translated to a fixed-width space (the +same one obtained by the @code{\@key{SP}} escape sequence). + +The @code{trin} request is identical to @code{tr}, but when you unformat +a diversion with @code{asciify} it ignores the translation. +@xref{Diversions}, for details about the @code{asciify} request. + +Some notes: + +@itemize @bullet +@item +@cindex @code{\(}, and translations +@cindex @code{\[}, and translations +@cindex @code{\'}, and translations +@cindex @code{\`}, and translations +@cindex @code{\-}, and translations +@cindex @code{\_}, and translations +@cindex @code{\C}, and translations +@cindex @code{\N}, and translations +@cindex @code{char} request, and translations +@cindex special characters +@cindex character, special +@cindex numbered glyph (@code{\N}) +@cindex glyph, numbered (@code{\N}) +Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]}, +@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}), +glyphs defined with the @code{char} request, and numbered glyphs +(@code{\N'@var{xxx}'}) can be translated also. + +@item +@cindex @code{\e}, and translations +The @code{\e} escape can be translated also. + +@item +@cindex @code{\%}, and translations +@cindex @code{\~}, and translations +Characters can be mapped onto the @code{\%} and @code{\~} escape +sequences (but @code{\%} and @code{\~} can't be mapped onto another +glyph). + +@item +@cindex backspace character, and translations +@cindex character, backspace, and translations +@cindex leader character, and translations +@cindex character, leader, and translations +@cindex newline character, and translations +@cindex character, newline, and translations +@cindex tab character, and translations +@cindex character, tab, and translations +@cindex @code{\a}, and translations +@cindex @code{\t}, and translations +The following characters can't be translated: space (with one exception, +see below), backspace, newline, leader (and @code{\a}), tab (and +@code{\t}). + +@item +@cindex @code{shc} request, and translations +Translations are not considered for finding the soft hyphen character +set with the @code{shc} request. + +@item +@cindex @code{\&}, and translations +The pair @samp{@var{c}\&} (an arbitrary character@tie{}@var{c} followed +by the dummy character) maps this character to ``nothing''. + +@Example +.tr a\& +foo bar + @result{} foo br +@endExample + +@noindent +Even the space character can be mapped to the dummy character. + +@Example +.tr aa \& +foo bar + @result{} foobar +@endExample + +@noindent +As shown in the example, the space character can't be the first +character/glyph pair as an argument of @code{tr}. Additionally, it is +not possible to map the space character to any other glyph; requests +like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead. + +If justification is active, lines are justified in spite of the `empty' +space character (but there is no minimal distance, i.e., the space +character, between words). + +@item +After an output glyph has been constructed (this happens at the moment +immediately before the glyph is appended to an output glyph list, either +by direct output, in a macro, diversion, or string), it is no longer +affected by @code{tr}. + +@item +Translating character to glyphs where one of them or both are undefined +is possible also; @code{tr} does not check whether the elements of its +argument exist. + +@xref{Gtroff Internals}. + +@item +Without an argument, the @code{tr} request is ignored. +@end itemize +@endDefreq + +@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} +@cindex @code{\!}, and @code{trnt} +@code{trnt} is the same as the @code{tr} request except that the +translations do not apply to text that is transparently throughput into +a diversion with @code{\!}. @xref{Diversions}. + +For example, + +@Example +.tr ab +.di x +\!.tm a +.di +.x +@endExample + +@noindent +prints @samp{b} to the standard error stream; if @code{trnt} is used +instead of @code{tr} it prints @samp{a}. +@endDefreq + + +@c ===================================================================== + +@node @code{troff} and @code{nroff} Modes, Line Layout, Character Translations, GNU troff Reference +@section @code{troff} and @code{nroff} Modes +@cindex @code{troff} mode +@cindex mode, @code{troff} +@cindex @code{nroff} mode +@cindex mode, @code{nroff} + +Historically, @code{nroff} and @code{troff} were two separate programs; +the former for terminal output, the latter for typesetters. GNU +@code{troff} merges both functions into one executable@footnote{A +GNU @command{nroff} program is available for convenience; it calls GNU +@code{troff} to perform the formatting.} that sends its output to a +device driver (@code{grotty} for terminal devices, @code{grops} for +PostScript, and so on) which interprets this intermediate output format. +When discussing @acronym{AT&T} @code{troff}, it makes sense to talk +about @dfn{@code{nroff} mode} and @dfn{@code{troff} mode} since the +differences are hard-coded. GNU @code{troff} takes information from +device and font description files without handling requests specially if +a terminal output device is used, so such a strong distinction is +unnecessary. + +Usually, a macro package can be used with all output devices. +Nevertheless, it is sometimes necessary to make a distinction between +terminal and non-terminal devices: GNU @code{troff} provides two +built-in conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, +and @code{while} requests to decide whether GNU @code{troff} shall +behave like @code{nroff} or like @code{troff}. + +@Defreq {troff, } +@pindex troffrc +@pindex troffrc-end +Make the @samp{t} built-in condition true (and the @samp{n} built-in +condition false) for @code{if}, @code{ie}, and @code{while} conditional +requests. This is the default if GNU @code{troff} (@emph{not} +@code{groff}) is started with the @option{-R} switch to avoid loading of +the startup files @file{troffrc} and @file{troffrc-end}. Without +@option{-R}, GNU @code{troff} stays in @code{troff} mode if the output +device is not a terminal (e.g., `ps'). +@endDefreq + +@Defreq {nroff, } +@pindex tty.tmac +Make the @samp{n} built-in condition true (and the @samp{t} built-in +condition false) for @code{if}, @code{ie}, and @code{while} conditional +requests. This is the default if GNU @code{troff} uses a terminal +output device; the code for switching to @code{nroff} mode is in the +file @file{tty.tmac}, which is loaded by the startup file +@code{troffrc}. +@endDefreq + +@xref{Conditionals and Loops}, for more details on built-in conditions. + + +@c ===================================================================== + +@node Line Layout, Line Continuation, @code{troff} and @code{nroff} Modes, GNU troff Reference +@section Line Layout +@cindex line layout +@cindex layout, line + +@cindex dimensions, line +@cindex line dimensions +The following drawing shows the dimensions that @code{gtroff} uses for +placing a line of output onto the page. They are labeled with the +request that manipulates each dimension. + +@Example + -->| in |<-- + |<-----------ll------------>| + +----+----+----------------------+----+ + | : : : | + +----+----+----------------------+----+ +-->| po |<-- + |<--------paper width---------------->| +@endExample + +@noindent +These dimensions are: + +@ftable @code +@item po +@cindex left margin (@code{po}) +@cindex margin, left (@code{po}) +@cindex page offset (@code{po}) +@cindex offset, page (@code{po}) +@dfn{Page offset}---this is the leftmost position of text on the final +output, defining the @dfn{left margin}. + +@item in +@cindex indentation (@code{in}) +@cindex line indentation (@code{in}) +@dfn{Indentation}---this is the distance from the left margin where +text is printed. + +@item ll +@cindex line length (@code{ll}) +@cindex length of line (@code{ll}) +@dfn{Line length}---this is the distance from the left margin to right +margin. +@end ftable + +@cindex margin, right +@cindex right margin +The right margin is not explicitly configured; the combination of page +offset and line length provides the information necessary to derive it. + +A simple demonstration: + +@Example +.ll 3i +This is text without indentation. +The line length has been set to 3\~inches. +.in +.5i +.ll -.5i +Now the left and right margins are both increased. +.in +.ll +Calling .in and .ll without parameters restores +the previous values. +@endExample + +@Example + @result{} This is text without indenta- + @result{} tion. The line length has + @result{} been set to 3 inches. + @result{} Now the left and + @result{} right margins are + @result{} both increased. + @result{} Calling .in and .ll without + @result{} parameters restores the previ- + @result{} ous values. +@endExample + +@DefreqList {po, [@Var{offset}]} +@DefreqItem {po, @t{+}@Var{offset}} +@DefreqItem {po, @t{-}@Var{offset}} +@DefregListEndx {.o} +@pindex tty.tmac +Set page offset to @var{offset} (or increment or decrement its current +value by @var{offset}). If invoked without an argument, the page offset +is restored to the value before the previous @code{po} request. +This request does not cause a break; the page offset in effect when an +output line is broken prevails (@pxref{Manipulating Filling and +Adjustment}). The initial value is 1@dmn{i} and the default scaling +unit is @samp{m}. On terminal devices, the page offset is set to zero +by a driver-specific macro file, @file{tty.tmac}. The current page +offset can be found in the read-only register @samp{.o}. +@cindex CSTR@tie{}#54 errata +@cindex CSTR@tie{}#54 erratum, @code{po} request +This request is incorrectly documented in the @acronym{AT&T} +@code{troff} manual as using a default scaling unit of @samp{v}. + +@Example +.po 3i +\n[.o] + @result{} 720 +.po -1i +\n[.o] + @result{} 480 +.po +\n[.o] + @result{} 720 +@endExample +@endDefreq + +@DefreqList {in, [@Var{indent}]} +@DefreqItem {in, @t{+}@Var{indent}} +@DefreqItem {in, @t{-}@Var{indent}} +@DefregListEndx {.i} +Set indentation to @var{indent} (or increment or decrement the current +value by @var{indent}). This request causes a break. Initially, there +is no indentation. + +If @code{in} is called without an argument, the indentation is reset to +the previous value before the last call to @code{in}. The default +scaling unit is @samp{m}. + +If a negative indentation value is specified (which is not allowed), +@code{gtroff} emits a warning in category @samp{range} and sets the +indentation to zero. + +The effect of @code{in} is delayed until a partially collected line (if +it exists) is output. A temporary indentation value is reset to zero +also. + +The current indentation (as set by @code{in}) can be found in the +read-only register @samp{.i}. The indentation is associated with the +environment (@pxref{Environments}). +@endDefreq + +@DefreqList {ti, offset} +@DefreqItem {ti, @t{+}@Var{offset}} +@DefreqItem {ti, @t{-}@Var{offset}} +@DefregListEndx {.in} +Temporarily indent the next output line by @var{offset}. If an +increment or decrement value is specified, adjust the temporary +indentation relative to the value set by the @code{in} request. + +This request causes a break; its value is associated with the +environment (@pxref{Environments}). The default scaling unit is +@samp{m}. A call of @code{ti} without an argument is ignored. + +If the total indentation value is negative (which is not allowed), +@code{gtroff} emits a warning in category @samp{range} and sets the +temporary indentation to zero. `Total indentation' is either +@var{offset} if specified as an absolute value, or the temporary plus +normal indentation, if @var{offset} is given as a relative value. + +The effect of @code{ti} is delayed until a partially collected line (if +it exists) is output. + +The read-only register @code{.in} is the indentation that applies to the +current output line. + +The difference between @code{.i} and @code{.in} is that the latter takes +into account whether a partially collected line still uses the old +indentation value or a temporary indentation value is active. +@endDefreq + +@DefreqList {ll, [@Var{length}]} +@DefreqItem {ll, @t{+}@Var{length}} +@DefreqItem {ll, @t{-}@Var{length}} +@DefregItemx {.l} +@DefregListEndx {.ll} +Set the line length to @var{length} (or increment or decrement the +current value by @var{length}). Initially, the line length is set to +6.5@dmn{i}. The effect of @code{ll} is delayed until a partially +collected line (if it exists) is output. The default scaling unit is +@samp{m}. + +If @code{ll} is called without an argument, the line length is reset to +the previous value before the last call to @code{ll}. If a negative +line length is specified (which is not allowed), @code{gtroff} emits a +warning in category @samp{range} and sets the line length to zero. The +line length is associated with the environment (@pxref{Environments}). + +@cindex line length register (@code{.l}) +The current line length (as set by @code{ll}) can be found in the +read-only register @samp{.l}. The read-only register @code{.ll} is the +line length that applies to the current output line. + +Similar to @code{.i} and @code{.in}, the difference between @code{.l} +and @code{.ll} is that the latter takes into account whether a partially +collected line still uses the old line length value. +@endDefreq + + +@c ===================================================================== + +@node Line Continuation, Page Layout, Line Layout, GNU troff Reference +@section Line Continuation +@cindex line control +@cindex control, line + +When filling is enabled, input and output line breaks generally do not +correspond. The @code{roff} language therefore distinguishes input and +output line continuation. + +@Defesc {\\@key{RET}, , ,} +@cindex input line continuation (@code{\@key{RET}}) +@cindex line, input, continuation (@code{\@key{RET}}) +@cindex continuation, input line (@code{\@key{RET}}) +@c We use the following notation in our man pages; Texinfo is bound to +@c the GNU Emacs dialect. +@esindex \@slanted{newline} +@code{\@key{RET}} (a backslash immediately followed by a newline) +suppresses the effects of that newline in the input. The next input +line thus retains the classification of its predecessor as a control or +text line. @code{\@key{RET}} is useful for managing line lengths in the +input during document maintenance; you can break an input line in the +middle of a request invocation, macro call, or escape sequence. Input +line continuation is invisible to the formatter, with two exceptions: +the @code{|} operator recognizes the new input line +(@pxref{Numeric Expressions}), and the input line counter register +@code{.c} is incremented. + +@c Wrap example at 56 columns (on the _output_). We use 50n in the +@c groff input to avoid line adjustment. +@Example +.ll 50n +.de I +. ft I +. nop \\$* +. ft +.. +Our film class watched +.I The Effect of Gamma Rays on Man-in-the-Moon +Marigolds. \" whoops, the input line wrapped +.br +.I My own opus begins on line \n[.c] \ +and ends on line \n[.c]. +@endExample +@Example + @result{} Our film class watched @i{The Effect of Gamma Rays on} + @result{} @i{Man-in-the-Moon} Marigolds. + @result{} @i{My own opus begins on line 11 and ends on line 12.} +@endExample +@endDefesc + +@DefescList {\\c, , ,} +@DefregListEndx {.int} +@cindex output line, continuation (@code{\c}) +@cindex line, output, continuation (@code{\c}) +@cindex continuation, output line (@code{\c}) +@cindex interrupted line +@cindex line, interrupted +@cindex @code{\R}, after @code{\c} +@code{\c} continues an output line. Nothing after it on the input line +is formatted. In contrast to @code{\@key{RET}}, a line after @code{\c} +remains a new input line, so a control character is recognized at its +beginning. The visual results depend on whether filling is enabled; see +@ref{Manipulating Filling and Adjustment}. + +@itemize @bullet +@item +@cindex @code{\c}, when filling enabled +@cindex fill mode, and @code{\c} +@cindex mode, fill, and @code{\c} +If filling is enabled, a word interrupted with @code{\c} is continued +with the text on the next input text line, without an intervening space. + +@Example +This is a te\c +st. + @result{} This is a test. +@endExample + +@item +@cindex @code{\c}, when filling disabled +@cindex no-fill mode, and @code{\c} +@cindex mode, no-fill, and @code{\c} +If filling is disabled, the next input text line after @code{\c} is +handled as a continuation of the same input text line. + +@Example +.nf +This is a \c +test. + @result{} This is a test. +@endExample +@end itemize + +An intervening control line that causes a break overrides @code{\c}, +flushing out the pending output line in the usual way. + +@cindex interrupted line register (@code{.int}) +@cindex continued output line register (@code{.int}) +The @code{.int} register contains a positive value if the last output +line was continued with @code{\c}; this datum is associated with the +environment (@pxref{Environments}).@footnote{Historically, the @code{\c} +escape sequence has proven challenging to characterize. Some sources +say it ``connects the next input text'' (to the input line on which it +appears); others describe it as ``interrupting'' text, on the grounds +that a text line is interrupted without breaking, perhaps to inject a +request invocation or macro call.} +@endDefesc + + +@c ===================================================================== + +@node Page Layout, Page Control, Line Continuation, GNU troff Reference +@section Page Layout +@cindex page layout +@cindex layout, page + +The formatter permits configuration of the page length and page number. + +@DefreqList {pl, [@Var{length}]} +@DefreqItem {pl, @t{+}@Var{length}} +@DefreqItem {pl, @t{-}@Var{length}} +@DefregListEndx {.p} +@cindex page length, configuring (@code{pl}) +@cindex length of the page, configuring (@code{pl}) +@cindex configuring the page length (@code{pl}) +@cindex setting the page length (@code{pl}) +Change (increase or decrease) the page length per the numeric expression +@var{length}. The default scaling unit is @samp{v}. A negative +@var{length} is valid, but an uncommon application:@: it prevents page +location traps from being sprung,@footnote{@xref{Traps}.} and each +output line is placed on a new page. If @var{length} is invalid, GNU +@code{troff} emits a warning in category @samp{number}. If @var{length} +is absent or invalid, @samp{11i} is assumed. + +@cindex page length register (@code{.p}) +The read-only register @samp{.p} interpolates the current page length. +@endDefreq + +@DefreqList {pn, num} +@DefreqItem {pn, @t{+}@Var{num}} +@DefreqItem {pn, @t{-}@Var{num}} +@DefregListEndx {.pn} +@cindex page number, configuring next (@code{pn}) +@cindex next page number, configuring (@code{pn}) +@cindex number, page, next, configuring (@code{pn}) +Change (increase or decrease) the page number of the @emph{next} page +per the numeric expression @var{num}. If @var{num} is invalid, GNU +@code{troff} emits a warning in category @samp{number} and ignores the +request. Without an argument, @code{pn} is ignored. + +@cindex next page number register (@code{.pn}) +@cindex page number, next, register (@code{.pn}) +The read-only register @code{.pn} interpolates @var{num} if set by +@code{pn} on the current page, or the current page number plus@tie{}1. +@endDefreq + +@cindex headers +@cindex footers +@cindex titles +The formatter offers special support for typesetting headers and +footers, collectively termed @dfn{titles}. Titles have an independent +line length, and their placement on the page is not restricted. + +@Defreq {tl, @code{'}@Var{left}@code{'}@Var{center}@code{'}@Var{right}@code{'}} +@cindex title line, formatting (@code{tl}) +@cindex formatting a title line (@code{tl}) +@cindex three-part title (@code{tl}) +@cindex page number character (@code{%}) +Format an output line as a title consisting of @var{left}, @var{center}, +and @var{right}, each aligned accordingly. The delimiter need not be a +neutral apostrophe: @code{tl} accepts the same delimiters as most escape +sequences; see @ref{Delimiters}. If not used as the delimiter, any +@dfn{page number character} character is replaced with the current page +number; the default is @samp{%}; see the the @code{pc} request below. +Without an argument, @code{tl} is ignored. @code{tl} writes the title +line immediately, ignoring any partially collected line. + +It is not an error to omit delimiters after the first. For example, +@w{@samp{.tl /Thesis}} is interpreted as @w{@samp{.tl /Thesis///}}:@: it +sets a title line comprising only the left-aligned word @samp{Thesis}. +@endDefreq + +@DefreqList {lt, [@Var{length}]} +@DefreqItem {lt, @t{+}@Var{length}} +@DefreqItem {lt, @t{-}@Var{length}} +@DefregListEndx {.lt} +@cindex length of title line, configuring (@code{lt}) +@cindex title length, configuring (@code{lt}) +Change (increase or decrease) the line length used by titles per the +numeric expression @var{length}. The default scaling unit is @samp{m}. +If @var{length} is negative, GNU emits a warning in category +@samp{range} and treats @var{length} as @samp{0}. If @var{length} is +invalid, GNU @code{troff} emits a warning in category @samp{number} and +ignores the request. The formatter's default title length is +@samp{6.5i}. With no argument, the title length is restored to the +previous value. The title length is is associated with the environment +(@pxref{Environments}). + +@cindex title line length register (@code{.lt}) +The read-only register @samp{.lt} interpolates the title line length. +@endDefreq + +@Defreq {pc, [@Var{char}]} +@cindex changing the page number character (@code{pc}) +@cindex page number character, changing (@code{pc}) +@vindex % +Set the page number character to @var{char}. With no argument, the page +number character is disabled. @code{pc} does not affect the +register@tie{}@code{%}. +@endDefreq + +The following example exercises title features. + +@Example +.lt 50n +This is my partially collected +.tl 'Isomers 2023'%'Dextrose Edition' +line. + @result{} Isomers 2023 1 Dextrose Edition + @result{} This is my partially collected line. +@endExample + +We most often see titles used in page header and footer traps. +@xref{Traps}. + +@c ===================================================================== + +@node Page Control, Using Fonts, Page Layout, GNU troff Reference +@section Page Control +@cindex page control +@cindex control, page + +@cindex page break +@cindex break, page +@cindex page ejection +@cindex ejection, page +Discretionary page breaks can prevent the unwanted separation of +content. A new page number takes effect during page ejection; see +@ref{The Implicit Page Trap}. + +@DefreqList {bp, [@Var{page-number}]} +@DefreqItem {bp, @t{+}@Var{page-number}} +@DefreqItem {bp, @t{-}@Var{page-number}} +@DefregListEndx {%} +@cindex new page (@code{bp}) +@cindex page, new (@code{bp}) +Break the page and change (increase or decrease) the next page number +per the numeric expression @var{page-number}. If @var{page-number} is +invalid, GNU @code{troff} emits a warning in category @samp{number} and +ignores the argument. This request causes a break. A page break +advances the vertical drawing position to the bottom of the page, +springing traps. @xref{Page Location Traps}. +@cindex @code{bp} request, and top-level diversion +@cindex top-level diversion, and @code{bp} +@cindex diversion, top-level, and @code{bp} +@code{bp} has effect only if invoked within the top-level +diversion.@footnote{@xref{Diversions}.} +@cindex CSTR@tie{}#54 errata +@cindex CSTR@tie{}#54 erratum, @code{bp} request +This request is incorrectly documented in the @acronym{AT&T} +@code{troff} manual as having a default scaling unit of @samp{v}. + +@cindex page number register (@code{%}) +@cindex current page number (@code{%}) +The register @code{%} interpolates the current page number. + +@Example +.de BP +' bp \" schedule page break once current line is output +.. +@endExample +@endDefreq + +@Defreq {ne, [@Var{space}]} +@cindex orphan lines, preventing with @code{ne} +@cindex conditional page break (@code{ne}) +@cindex page break, conditional (@code{ne}) +Force a page break if insufficient vertical space is available (assert +``needed'' space). @code{ne} tests the distance to the next page +location trap; see @ref{Page Location Traps}, and breaks the page if +that amount is less than @var{space}. The default scaling unit is +@samp{v}. If @var{space} is invalid, GNU @code{troff} emits a warning +in category @samp{number} and ignores the argument. If @var{space} is +not specified, @samp{1v} is assumed. + +@cindex widow +We can require space for at least the first two output lines of a +paragraph, preventing its first line from being @slanted{widowed} at the +page bottom. + +@Example +.ne 2v +Considering how common illness is, +how tremendous the spiritual change that it brings, +how astonishing, +when the lights of health go down, +the undiscovered countries that are then disclosed, +what wastes and deserts of the soul a slight attack +of influenza brings to view, +@c -- Virgina Woolf, "On Being Ill", 1926 +@endExample + +@c XXX: Some of this might be better placed in a revised Chapter 3. +This method is reliable only if no output line is pending when @code{ne} +is invoked. When macro packages are used, this is often not the case:@: +their paragraphing macros perform the break. You may need to experiment +with placing the @code{ne} after the paragraphing macro, or @code{br} +and @code{ne} before it. + +@cindex orphan +@cindex widow +@code{ne} is also useful to force grouping of section headings with +their subsequent paragraphs, or tables with their captions and/or +explanations. Macro packages often use @code{ne} with diversions to +implement keeps and displays; see @ref{Diversions}. They may also offer +parameters for widow and orphan management. +@endDefreq + +@DefreqList {sv, [@Var{space}]} +@DefreqListEndx {os, } +@cindex @code{ne} request, comparison with @code{sv} +Require vertical space as @code{ne} does, but also @slanted{save} it for +later output by the @code{os} request. If @var{space} is available +before the next page location trap, it is output immediately. Both +requests ignore a partially collected line, taking effect at the next +break. +@cindex @code{sv} request, and no-space mode +@cindex @code{os} request, and no-space mode +@code{sv} and @code{os} ignore no-space mode (recall @ref{Manipulating +Spacing}). While the @code{sv} request allows negative values for +@var{space}, @code{os} ignores them. The default scaling unit is +@samp{v}. If @var{space} is not specified, @samp{1v} is assumed. +@endDefreq + +@Defreg {nl} +@cindex vertical drawing position (@code{nl}) +@cindex vertical position, drawing (@code{nl}) +@cindex drawing position, vertical (@code{nl}) +@c TODO: We should talk somewhere prior to this point about how the +@c formatter doesn't start a page until it has to. +@code{nl} interpolates or sets the vertical drawing position. When the +formatter starts, the first page transition hasn't happened yet, and +@code{nl} is negative. If a header trap has been planted on the page +(typically at vertical position @code{0}), you can assign a negative +value to @code{nl} to spring it if that page has already started +(@pxref{Page Location Traps}). + +@Example +.de HD +. sp +. tl ''Goldbach Solution'' +. sp +.. +. +First page. +.bp +.wh 0 HD \" plant header trap at top of page +.nr nl (-1) +Second page. + @result{} First page. + @result{} + @result{} @r{@i{(blank lines elided)}} + @result{} + @result{} Goldbach Solution + @result{} + @result{} @r{@i{(blank lines elided)}} + @result{} + @result{} Second page. +@endExample + +@noindent +Without resetting @code{nl} to a negative value, the trap just planted +would be active beginning with the @emph{next} page, not the current +one. + +@xref{Diversions}, for a comparison of @code{nl} with the @code{.h} and +@code{.d} registers. +@endDefreg + + +@c ===================================================================== + +@c BEGIN Keep (roughly) parallel with section "Using fonts" of groff(7). +@node Using Fonts, Manipulating Type Size and Vertical Spacing, Page Control, GNU troff Reference +@section Using Fonts +@cindex font + +@cindex typeface +@cindex font family +@cindex font style +@cindex style, font +@cindex family, font +@cindex text font +@cindex special font +@cindex unstyled font +@cindex font, text +@cindex font, special +@cindex font, unstyled +In digital typography, a @dfn{font} is a collection of characters in a +specific typeface that a device can render as glyphs at a desired +size.@footnote{Terminals and some output devices have fonts that render +at only one or two sizes. As examples of the latter, take the +@code{groff} @code{lj4} device's Lineprinter, and @code{lbp}'s Courier +and Elite faces.} A @code{roff} formatter can change typefaces at any +point in the text. The basic faces are a set of @dfn{styles} combining +upright and slanted shapes with normal and heavy stroke weights: +@samp{R}, @samp{I}, @samp{B}, and @samp{BI}---these stand for +@slanted{roman}, @slanted{italic}, @slanted{bold}, and +@slanted{bold-italic}. For linguistic text, GNU @code{troff} groups +typefaces into @dfn{families} containing each of these +styles.@footnote{Font designers prepare families such that the styles +share esthetic properties.} A @dfn{text font} is thus often a family +combined with a style, but it need not be:@: consider the @code{ps} and +@code{pdf} devices' @code{ZCMI} (Zapf Chancery Medium italic)---often, +no other style of Zapf Chancery Medium is provided. On typesetting +devices, at least one @dfn{special font} is available, comprising +@dfn{unstyled} glyphs for mathematical operators and other purposes. + +@cindex font description file +@cindex description file, font +@cindex file, font description +@cindex font metrics +@cindex metrics, font +@cindex mounting position +@cindex mounting position +@cindex position, mounting +Like @acronym{AT&T} @code{troff}, GNU @code{troff} does not itself load +or manipulate a digital font file;@footnote{Historically, the fonts +@code{troff}s dealt with were not Free Software or, as with the Graphic +Systems C/A/T, did not even exist in the digital domain.} instead it +works with a @dfn{font description file} that characterizes it, +including its glyph repertoire and the @dfn{metrics} (dimensions) of +each glyph.@footnote{@xref{Font Description File Format}.} This +information permits the formatter to accurately place glyphs with +respect to each other. Before using a font description, the formatter +associates it with a @dfn{mounting position}, a place in an ordered list +of available typefaces. +@cindex abstract font style +@cindex font style, abstract +@cindex style, font, abstract +So that a document need not be strongly coupled to a specific font +family, in GNU @code{troff} an output device can associate a style in +the abstract sense with a mounting position. Thus the default family +can be combined with a style dynamically, producing a @dfn{resolved font +name}. + +Fonts often have trademarked names, and even Free Software fonts can +require renaming upon modification. @code{groff} maintains a +convention that a device's serif font family is given the name @samp{T} +(``Times''), its sans-serif family @samp{H} (``Helvetica''), and its +monospaced family @samp{C} (``Courier''). Historical inertia has driven +@code{groff}'s font identifiers to short uppercase abbreviations of font +names, as with @samp{TR}, @samp{TI}, @samp{TB}, @samp{TBI}, and a +special font @samp{S}. + +The default family used with abstract styles can be changed at any time; +initially, it is @samp{T}. Typically, abstract styles are arranged in +the first four mounting positions in the order shown above. The default +mounting position, and therefore style, is always @samp{1} (@samp{R}). +By issuing appropriate formatter instructions, you can override these +defaults before your document writes its first glyph. + +@cindex graphic renditions +@cindex renditions, graphic +@cindex character cell attributes +@cindex attributes, character cell +@cindex cell, character, attributes +Terminal output devices cannot change font families and lack special +fonts. They support style changes by overstriking, or by altering +ISO@tie{}6429/ECMA-48 @dfn{graphic renditions} (character cell +attributes). +@c END Keep (roughly) parallel with section "Using fonts" of groff(7). + +@menu +* Selecting Fonts:: +* Font Families:: +* Font Positions:: +* Using Symbols:: +* Character Classes:: +* Special Fonts:: +* Artificial Fonts:: +* Ligatures and Kerning:: +* Italic Corrections:: +* Dummy Characters:: +@end menu + +@c --------------------------------------------------------------------- + +@node Selecting Fonts, Font Families, Using Fonts, Using Fonts +@subsection Selecting Fonts +@cindex font, selection + +We use @dfn{font} to refer to any of several means of identifying a +font: by mounting position (@samp{3}), by abstract style (@samp{B}), or +by its identifier (@samp{TB}). + +@DefreqList {ft, [@Var{font}]} +@DefescItemx {\\f, , f, } +@DefescItem {\\f, (, fn, } +@DefescItem {\\f, [, font, ]} +@DefregListEndx {.fn} +@cindex changing fonts (@code{ft}, @code{\f}) +@cindex fonts, changing (@code{ft}, @code{\f}) +@cindex @code{sty} request, and changing fonts +@cindex @code{fam} request, and changing fonts +@cindex @code{\F}, and changing fonts +@kindex styles +@kindex family +@pindex DESC +@cindex selecting the previous font (@code{ft}) +@cindex previous font, selecting (@code{ft}) +@cindex font, previous, slecting (@code{ft}) +The @code{ft} request selects the typeface @var{font}. If the argument +is absent or @samp{P}, it selects the previously chosen font. If +@var{font} is a non-negative integer, it is interpreted as mounting +position; the font mounted there is selected. If that position refers +to an abstract style, it is combined with the default family (see +@code{fam} and @code{\F} below) to make a resolved font name. If the +mounting position is not a style and no font is mounted there, GNU +@code{troff} emits a warning in category @samp{font} and ignores the +request. + +If @var{font} matches a style name, it is combined with the current +family to make a resolved font name. Otherwise, @var{font} is assumed +to already be a resolved font name. + +@cindex automatic font mounting +@cindex font mounting, automatic +@cindex mounting, font, automatic +The resolved font name is subject to translation (see request @code{ftr} +below). Next, the (possibly translated) font name's mounting position +is looked up; if not mounted, @var{font} is sought on the file system as +a font description file and, if located, automatically mounted at the +next available position (see register @code{.fp} below). If the font +was mounted using an identifier different from its font description file +name (see request @code{fp} below), that file name is then looked up. +If a font description file for the resolved font name is not found, GNU +@code{troff} emits a warning in category @samp{font} and ignores the +request. + +The @code{\f} escape sequence is similar, using one-character name (or +mounting position) @var{f}, two-character name @var{fn}, or a name +@var{font} of arbitrary length. +@cindex previous font, selecting (@code{\f[]}, @code{\fP}) +@cindex font, previous, selecting (@code{\f[]}, @code{\fP}) +@samp{\f[]} selects the previous font. The syntax form @samp{\fP} is +supported for backward compatibility, and @samp{\f[P]} for consistency. + +@Example +eggs, bacon, +.ft I +spam, +.ft +and sausage. +.br +eggs, bacon, \fIspam,\fP and sausage. + @result{} eggs, bacon, @slanted{spam,} and sausage + @result{} eggs, bacon, @slanted{spam,} and sausage +@endExample + +The current and previously selected fonts are properties of the +environment (@pxref{Environments}). + +The read-only string-valued register @code{.fn} contains the resolved +font name of the selected font. + +@code{\f} doesn't produce an input token in GNU @code{troff}; it thus +can be used in requests that expect a single-character argument. We can +assign a font to a margin character as follows (@pxref{Miscellaneous}). + +@Example +.mc \f[I]x\f[] +@endExample +@endDefreq + +@Defreq {ftr, f [@Var{g}]} +@cindex font translation (@code{ftr}) +@cindex @code{ft} request, and font translations +@cindex @code{ul} request, and font translations +@cindex @code{bd} request, and font translations +@cindex @code{\f}, and font translations +@cindex @code{cs} request, and font translations +@cindex @code{tkf} request, and font translations +@cindex @code{special} request, and font translations +@cindex @code{fspecial} request, and font translations +@cindex @code{fp} request, and font translations +@cindex @code{sty} request, and font translations +@cindex @code{if} request, and font translations +@cindex @code{ie} request, and font translations +@cindex @code{while} request, and font translations +Translate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font +named@tie{}@var{f} is referred to in a @code{\f} escape sequence, in the +@code{F} and @code{S} conditional operators, or in the @code{ft}, +@code{ul}, @code{bd}, @code{cs}, @code{tkf}, @code{special}, +@code{fspecial}, @code{fp}, or @code{sty} requests, font@tie{}@var{g} is +used. If @var{g} is missing or equal to@tie{}@var{f} the translation is +undone. +@c XXX: Do font translations work on mounting positions? Abstract +@c styles? + +Font translations cannot be chained. + +@Example +.ftr XXX TR +.ftr XXX YYY +.ft XXX + @error{} warning: can't find font 'XXX' +@endExample +@endDefreq + +@DefreqList {fzoom, f [@Var{zoom}]} +@DefregListEndx {.zoom} +@cindex magnification of a font (@code{fzoom}) +@cindex font, magnification (@code{fzoom}) +@cindex zoom factor of a font (@code{fzoom}) +@cindex factor, zoom, of a font (@code{fzoom}) +@cindex font, zoom factor (@code{fzoom}) +@cindex optical size of a font +@cindex font, optical size +@cindex size, optical, of a font +Set magnification of font@tie{}@var{f} to factor @var{zoom}, which must +be a non-negative integer multiple of 1/1000th. This request is useful +to adjust the optical size of a font in relation to the others. In the +example below, font @code{CR} is magnified by 10% (the zoom factor is +thus 1.1). + +@Example +.fam P +.fzoom CR 1100 +.ps 12 +Palatino and \f[CR]Courier\f[] +@endExample + +A missing or zero value of @var{zoom} is the same as a value of 1000, +which means no magnification. @var{f}@tie{}must be a resolved font +name, not an abstract style. +@c XXX: What about a mounting position? It's not rejected... + +The magnification of a font is completely transparent to GNU +@code{troff}; a change of the zoom factor doesn't cause any effect +except that the dimensions of glyphs, (word) spaces, kerns, etc., of the +affected font are adjusted accordingly. + +The zoom factor of the current font is available in the read-only +register @samp{.zoom}, in multiples of 1/1000th. It returns zero if +there is no magnification. +@endDefreq + +@c --------------------------------------------------------------------- + +@node Font Families, Font Positions, Selecting Fonts, Using Fonts +@subsection Font Families +@cindex font families +@cindex families, font +@cindex font styles +@cindex styles, font + +To accommodate the wide variety of fonts available, GNU @code{troff} +distinguishes @dfn{font families} and @dfn{font styles}. A resolved +font name is the catenation of a font family and a style. Selecting an +abstract style causes GNU @code{troff} to combine it with the default +font family. + +You can thus compose a document using abstract styles exclusively for +its body or running text, selecting a specific family only for titles or +examples, for instance, and change the default family on the command +line (recall @ref{Groff Options}). + +Fonts for the devices @code{ps}, @code{pdf}, @code{dvi}, @code{lj4}, +@code{lbp}, and the X11 devices support this mechanism. By default, +GNU @code{troff} uses the Times family with the four styles @samp{R}, +@samp{I}, @samp{B}, and @samp{BI}. + +@DefreqList {fam, [@Var{family}]} +@DefregItemx {.fam} +@DefescItemx {\\F, , f, } +@DefescItem {\\F, (, fm, } +@DefescListEnd {\\F, [, family, ]} +@cindex changing font family (@code{fam}, @code{\F}) +@cindex font family, changing (@code{fam}, @code{\F}) +Set the default font family, used in combination with abstract styles to +construct a resolved font name, to @var{family} (one-character +name@tie{}@var{f}, two-character name @var{fm}). If no argument is +given, GNU @code{troff} selects the previous font family; if there none, +is it falls back to the device's default@footnote{@xref{DESC File +Format}.} or its own (@samp{T}). + +The @code{\F} escape sequence works similarly. In disanalogy to +@code{\f}, @samp{\FP} makes @samp{P} the default family. Use +@samp{\F[]} to select the previous default family. The default font +family is available in the read-only string-valued register @code{.fam}; +it is associated with the environment (@pxref{Environments}). + +@Example +spam, \" startup defaults are T (Times) R (roman) +.fam H \" make Helvetica the default family +spam, \" family H + style R = HR +.ft B \" family H + style B = HB +spam, +.ft CR \" Courier roman (default family not changed) +spam, +.ft \" back to Helvetica bold +spam, +.fam T \" make Times the default family +spam, \" family T + style B = TB +.ft AR \" font AR (not a style) +baked beans, +.ft R \" family T + style R = TR +and spam. +@endExample + +@code{\F} doesn't produce an input token in GNU @code{troff}. As a +consequence, it can be used in requests like @code{mc} (which expects +a single character as an argument) to change the font family on the fly. + +@Example +.mc \F[P]x\F[] +@endExample +@endDefreq + +@need 1000 +@DefreqList {sty, n style} +@DefregListEndx {.sty} +@cindex setting up an abstract font style (@code{sty}) +@cindex abstract font style, setting up (@code{sty}) +@cindex font style, abstract, setting up (@code{sty}) +@cindex style, font, abstract, setting up (@code{sty}) +@cindex @code{cs} request, and font styles +@cindex @code{bd} request, and font styles +@cindex @code{tkf} request, and font styles +@cindex @code{uf} request, and font styles +@cindex @code{fspecial} request, and font styles +Associate an abstract style @var{style} with mounting +position@tie{}@var{n}, which must be a non-negative integer. If the +requests @code{cs}, @code{bd}, @code{tkf}, @code{uf}, or @code{fspecial} +are applied to an abstract style, they are instead applied to the member +of the current family corresponding to that style. + +@pindex DESC +@kindex styles +The default family can be set with the @option{-f} option (@pxref{Groff +Options}). The @code{styles} command in the @file{DESC} file controls +which font positions (if any) are initially associated with abstract +styles rather than fonts. + +@strong{Caution:@:} The @var{style} argument is not validated. +@c XXX: This would be a really good thing to fix. +Errors may occur later, when the formatter attempts to construct a +resolved font name, or format a character for output. + +@Example +.nr BarPos \n[.fp] +.sty \n[.fp] Bar +.fam Foo +.ft \n[BarPos] +.tm .f=\n[.f] +A + @error{} error: no font family named 'Foo' exists + @error{} .f=41 + @error{} error: cannot format glyph: no current font +@endExample + +When an abstract style has been selected, the read-only string-valued +register @samp{.sty} interpolates its name; this datum is associated +with the environment (@pxref{Environments}). Otherwise, @samp{.sty} +interpolates nothing. +@endDefreq + +@c --------------------------------------------------------------------- + +@node Font Positions, Using Symbols, Font Families, Using Fonts +@subsection Font Positions +@cindex font positions +@cindex positions, font + +To support typeface indirection through abstract styles, and for +compatibility with @acronym{AT&T} @code{troff}, the formatter maintains +a list of font @dfn{positions} at which fonts required by a document are +@dfn{mounted}. An output device's description file @file{DESC} +typically configures a set of pre-mounted fonts; see @ref{Device and +Font Description Files}. A font need not be explicitly mounted before +it is selected; GNU @code{troff} will search @env{GROFF_FONT_PATH} for +it by name and mount it at the first free mounting position on demand. + +@need 500 +@DefreqList {fp, pos id [@Var{font-description-file-name}]} +@DefregItemx {.f} +@DefregListEndx {.fp} +@cindex mounting a font (@code{fp}) +@cindex font, mounting (@code{fp}) +Mount a font under the name @var{id} at mounting position @var{pos}, a +non-negative integer. When the formatter starts up, it reads the output +device's description to mount an initial set of faces, and selects font +position@tie{}1. Position@tie{}0 is unused by default. Unless the +@var{font-description-file-name} argument is given, @var{id} should be +the name of a font description file stored in a directory corresponding +to the selected output device. GNU @code{troff} does not traverse +directories to locate the font description file. + +@c The third argument was a late revision to device-independent troff. +@c It wasn't in the "Unix 4.0" version of CSTR #54 (January 1981), which +@c featured Kernighan's device-independent rewrite, but appeared by the +@c time of its 1992 revision. +@cindex font aliasing with third argument to @code{fp} request +@cindex aliasing fonts with third argument to @code{fp} request +The optional third argument enables font names to be aliased, which can +be necessary in compatibility mode since AT&T @code{troff} syntax +affords no means of identifying fonts with names longer than two +characters, like @samp{TBI} or @samp{ZCMI}, in a font selection escape +sequence. @xref{Compatibility Mode}. You can also alias fonts on +mounting for convenience or abstraction. (See below regarding the +@code{.fp} register.) + +@Example +.fp \n[.fp] SC ZCMI +Send a \f(SChand-written\fP thank-you note. +.fp \n[.fp] Emph TI +.fp \n[.fp] Strong TB +Are \f[Emph]these names\f[] \f[Strong]comfortable\f[]? +@endExample + +@samp{DESC}, @samp{P}, and non-negative integers are not usable as font +identifiers. +@c XXX: TODO: Catch the DESC case earlier and throw an error for it. +@c XXX: This identifier could be used as a style name, but no one's +@c exercised this freedom in 30+ years, and we should consider +@c prohibiting it. --GBR + +@cindex font position register (@code{.f}) +The position of the currently selected font (or abstract style) is +available in the read-only register @samp{.f}. It is associated with +the environment (@pxref{Environments}). + +You can copy the value of @code{.f} to another register to save it for +later use. + +@Example +.nr saved-font \n[.f] +@r{@dots{} @i{text involving many font changes} @dots{}} +.ft \n[saved-font] +@endExample + +@cindex next free font position register (@code{.fp}) +The index of the next (non-zero) free font position is available in the +read-only register @samp{.fp}. +@cindex @file{DESC} file, and font mounting +Fonts not listed in the @file{DESC} file are automatically mounted at +position @samp{\n[.fp]} when selected with the @code{ft} request or +@code{\f} escape sequence. When mounting a font at a position +explicitly with the @code{fp} request, this same practice should be +followed, although GNU @code{troff} does not enforce this strictly. +@endDefreq + +@c --------------------------------------------------------------------- + +@node Using Symbols, Character Classes, Font Positions, Using Fonts +@subsection Using Symbols +@cindex using symbols +@cindex symbols, using + +@cindex glyph +@cindex character +@cindex glyph, distinguished from character +@cindex character, distinguished from glyph +@cindex ligature +A @dfn{glyph} is a graphical representation of a @dfn{character}. While +a character is an abstraction of semantic information, a glyph is +something that can be seen on screen or paper. A character has many +possible representation forms (for example, the character `A' can be +written in an upright or slanted typeface, producing distinct +glyphs). Sometimes, a sequence of characters map to a single glyph:@: +this is a @dfn{ligature}---the most common is `fi'. + +Space characters never become glyphs in GNU @code{troff}. If not +discarded (as when trailing on text lines), they are represented by +horizontal motions in the output. + +@cindex symbol +@cindex special fonts +@kindex fonts +@pindex DESC +@cindex @code{special} request, and glyph search order +@cindex @code{fspecial} request, and glyph search order +A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all glyph +names of a particular font are defined in its font file. If the user +requests a glyph not available in this font, @code{gtroff} looks up an +ordered list of @dfn{special fonts}. By default, the PostScript output +device supports the two special fonts @samp{SS} (slanted symbols) and +@samp{S} (symbols) (the former is looked up before the latter). Other +output devices use different names for special fonts. Fonts mounted +with the @code{fonts} keyword in the @file{DESC} file are globally +available. To install additional special fonts locally (i.e., for a +particular font), use the @code{fspecial} request. + +Here are the exact rules how @code{gtroff} searches a given symbol: + +@itemize @bullet +@item +If the symbol has been defined with the @code{char} request, use it. +This hides a symbol with the same name in the current font. + +@item +Check the current font. + +@item +If the symbol has been defined with the @code{fchar} request, use it. + +@item +Check whether the current font has a font-specific list of special +fonts; test all fonts in the order of appearance in the last +@code{fspecial} call if appropriate. + +@item +If the symbol has been defined with the @code{fschar} request for the +current font, use it. + +@item +Check all fonts in the order of appearance in the last @code{special} +call. + +@item +If the symbol has been defined with the @code{schar} request, use it. + +@item +As a last resort, consult all fonts loaded up to now for special fonts +and check them, starting with the lowest font number. This can +sometimes lead to surprising results since the @code{fonts} line in +the @file{DESC} file often contains empty positions, which are filled +later on. For example, consider the following: + +@Example +fonts 3 0 0 FOO +@endExample + +@noindent +This mounts font @code{foo} at font position@tie{}3. We assume that +@code{FOO} is a special font, containing glyph @code{foo}, and that no +font has been loaded yet. The line + +@Example +.fspecial BAR BAZ +@endExample + +@noindent +makes font @code{BAZ} special only if font @code{BAR} is active. We +further assume that @code{BAZ} is really a special font, i.e., the font +description file contains the @code{special} keyword, and that it also +contains glyph @code{foo} with a special shape fitting to font +@code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded +at font position@tie{}1, and @code{BAZ} at position@tie{}2. + +We now switch to a new font @code{XXX}, trying to access glyph +@code{foo} that is assumed to be missing. There are neither +font-specific special fonts for @code{XXX} nor any other fonts made +special with the @code{special} request, so @code{gtroff} starts the +search for special fonts in the list of already mounted fonts, with +increasing font positions. Consequently, it finds @code{BAZ} before +@code{FOO} even for @code{XXX}, which is not the intended behaviour. +@end itemize + +@xref{Device and Font Description Files}, and @ref{Special Fonts}, for +more details. + +@cindex list of special characters (@cite{groff_char@r{(7)}} man page) +@cindex special characters, list of (@cite{groff_char@r{(7)}} man page) +@cindex characters, special, list of (@cite{groff_char@r{(7)}} man page) +@cindex available glyphs, list of (@cite{groff_char@r{(7)}} man page) +@cindex glyphs, available, list of (@cite{groff_char@r{(7)}} man page) +The @cite{groff_char@r{(7)}} man page houses a complete list of +predefined special character names, but the availability of any as a +glyph is device- and font-dependent. For example, say + +@Example +man -Tdvi groff_char > groff_char.dvi +@endExample + +@noindent +to obtain those available with the DVI device and default font +configuration.@footnote{Not all versions of the @code{man} program +support the @option{-T} option; use the subsequent example for an +alternative.} If you want to use an additional macro package to change +the fonts used, @code{groff} (or @code{gtroff}) must be run directly. + +@Example +groff -Tdvi -mec -man groff_char.7 > groff_char.dvi +@endExample + +@cindex composite glyph names +@cindex glyph names, composite +@cindex @code{groff} glyph list (GGL) +@cindex GGL (@code{groff} glyph list) +@cindex Adobe Glyph List (AGL) +Special character names not listed in @cite{groff_char@r{(7)}} are +derived algorithmically, using a simplified version of the Adobe Glyph +List (AGL) algorithm, which is described in +@uref{https://github.com@//adobe-type-tools@//agl-aglfn}. The (frozen) +set of names that can't be derived algorithmically is called the +@dfn{@code{groff} glyph list (GGL)}. + +@itemize @bullet +@item +A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]], which is +not a composite character is named +@code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an +uppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E}, +@code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at +least four @code{X} digits; if necessary, add leading zeroes (after the +@samp{u}). No zero padding is allowed for character codes greater than +0xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF +represented with character codes from the surrogate area U+D800-U+DFFF) +are not allowed either. + +@item +A glyph representing more than a single input character is named + +@display +@samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{} +@end display + +@noindent +Example: @code{u0045_0302_0301}. + +For simplicity, all Unicode characters that are composites must be +maximally decomposed to NFD;@footnote{This is ``Normalization Form D'' +as documented in Unicode Standard Annex #15 +(@uref{https://unicode.org@//reports@//tr15/}).} for example, +@code{u00CA_0301} is not a valid glyph name since U+00CA (@sc{latin +capital letter e with circumflex}) can be further decomposed into U+0045 +(@sc{latin capital letter e}) and U+0302 (@sc{combining circumflex +accent}). @code{u0045_0302_0301} is thus the glyph name for U+1EBE, +@sc{latin capital letter e with circumflex and acute}. + +@item +groff maintains a table to decompose all algorithmically derived glyph +names that are composites itself. For example, @code{u0100} (@sc{latin +letter a with macron}) is automatically decomposed into +@code{u0041_0304}. Additionally, a glyph name of the GGL is preferred +to an algorithmically derived glyph name; @code{groff} also +automatically does the mapping. Example: The glyph @code{u0045_0302} is +mapped to @code{^E}. + +@item +glyph names of the GGL can't be used in composite glyph names; for +example, @code{^E_u0301} is invalid. +@end itemize + +@DefescList {\\, (, nm, } +@DefescItem {\\, [, name, ]} +@DefescListEnd {\\, [, base-glyph combining-component @dots{}, ]} +@esindex \( +@esindex \[ +Typeset a special character @var{name} (two-character name @var{nm}) or +a composite glyph consisting of @var{base-glyph} overlaid with one or +more @var{combining-component}s. For example, @samp{\[A ho]} is a +capital letter ``A'' with a ``hook accent'' (ogonek). + +There is no special syntax for one-character names---the analogous form +@samp{\@var{n}} would collide with other escape sequences. However, the +four escape sequences @code{\'}, @code{\-}, @code{\_}, and @code{\`}, +are translated on input to the special character escape sequences +@code{\[aa]}, @code{\[-]}, @code{\[ul]}, and @code{\[ga]}, respectively. + +A special character name of length one is not the same thing as an +ordinary character: that is, the character @code{a} is not the same as +@code{\[a]}. + +If @var{name} is undefined, a warning in category @samp{char} is +produced and the escape is ignored. @xref{Warnings}, for information +about the enablement and suppression of warnings. + +GNU @code{troff} resolves @code{\[@r{@dots{}}]} with more than a single +component as follows: + +@itemize @bullet +@item +Any component that is found in the GGL is converted to the +@code{u@var{XXXX}} form. + +@item +Any component @code{u@var{XXXX}} that is found in the list of +decomposable glyphs is decomposed. + +@item +The resulting elements are then concatenated with @samp{_} in between, +dropping the leading @samp{u} in all elements but the first. +@end itemize + +No check for the existence of any component (similar to @code{tr} +request) is done. + +Examples: + +@table @code +@item \[A ho] +@samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the +final glyph name would be @code{u0041_02DB}. This is not the expected +result:@: the ogonek glyph @samp{ho} is a spacing ogonek, but for a +proper composite a non-spacing ogonek (U+0328) is necessary. Looking +into the file @file{composite.tmac}, one can find @w{@samp{.composite ho +u0328}}, which changes the mapping of @samp{ho} while a composite glyph +name is constructed, causing the final glyph name to be +@code{u0041_0328}. + +@item \[^E u0301] +@itemx \[^E aa] +@itemx \[E a^ aa] +@itemx \[E ^ @code{'}] +@samp{^E} maps to @code{u0045_0302}, thus the final glyph name is +@code{u0045_0302_0301} in all forms (assuming proper calls of the +@code{composite} request). +@end table + +It is not possible to define glyphs with names like @w{@samp{A ho}} +within a @code{groff} font file. This is not really a limitation; +instead, you have to define @code{u0041_0328}. +@endDefesc + +@Defesc {\\C, @code{'}, xxx, @code{'}} +@cindex named character (@code{\C}) +@cindex character, named (@code{\C}) +Typeset the glyph of the special character @var{xxx}. Normally, it is +more convenient to use @code{\[@var{xxx}]}, but @code{\C} has some +advantages: it is compatible with @acronym{AT&T} device-independent +@code{troff} (and therefore available in compatibility +mode@footnote{@xref{Compatibility Mode}.}) and can interpolate special +characters with @samp{]} in their names. The delimiter need not be +a neutral apostrophe; see @ref{Delimiters}. +@endDefesc + +@Defreq {composite, id1 id2} +@pindex composite.tmac +Map special character name @var{id1} to @var{id2} if @var{id1} is used +in @code{\[...]} with more than one component. See above for examples. +This is a strict rewriting of the special character name; no check is +performed for the existence of a glyph for either. A set of default +mappings for many accents can be found in the file +@file{composite.tmac}, loaded by the default @file{troffrc} at startup. +@endDefreq + +@Defesc {\\N, @code{'}, n, @code{'}} +@cindex numbered glyph (@code{\N}) +@cindex glyph, numbered (@code{\N}) +@cindex @code{char} request, used with @code{\N} +@cindex Unicode +Typeset the glyph with code@tie{}@var{n} in the current font +(@code{n}@tie{}is @emph{not} the input character code). The number +@var{n}@tie{}can be any non-negative decimal integer. Most devices only +have glyphs with codes between 0 and@tie{}255; the Unicode output device +uses codes in the range 0--65535. If the current font does not contain +a glyph with that code, special fonts are @emph{not} searched. The +@code{\N} escape sequence can be conveniently used in conjunction with +the @code{char} request: + +@Example +.char \[phone] \f[ZD]\N'37' +@endExample + +@noindent +@pindex DESC +@cindex unnamed glyphs +@cindex glyphs, unnamed +The code of each glyph is given in the fourth column in the font +description file after the @code{charset} command. It is possible to +include unnamed glyphs in the font description file by using a name of +@samp{---}; the @code{\N} escape sequence is the only way to use these. + +No kerning is applied to glyphs accessed with @code{\N}. The delimiter +need not be a neutral apostrophe; see @ref{Delimiters}. +@endDefesc + +A few escape sequences are also special characters. + +@Defesc {\@code{'}, , , } +An escaped neutral apostrophe is a synonym for @code{\[aa]} (acute +accent). +@endDefesc + +@Defesc {\@code{`}, , , } +An escaped grave accent is a synonym for @code{\[ga]} (grave accent). +@endDefesc + +@Defesc {\\-, , , } +An escaped hyphen-minus is a synonym for @code{\[-]} (minus sign). +@endDefesc + +@Defesc {\\_, , , } +An escaped underscore (``low line'') is a synonym for @code{\[ul]} +(underrule). On typesetting devices, the underrule is font-invariant +and drawn lower than the underscore @samp{_}. +@endDefesc + +@Defreq {cflags, n c1 c2 @dots{}} +@cindex glyph properties (@code{cflags}) +@cindex character properties (@code{cflags}) +@cindex properties of glyphs (@code{cflags}) +@cindex properties of characters (@code{cflags}) +Assign properties encoded by the number @var{n} to characters @var{c1}, +@var{c2}, and so on. + +Input characters, including special characters introduced by an escape, +have certain properties associated with them.@footnote{Output glyphs +don't---to GNU @code{troff}, a glyph is simply a box with an index into +a font, a given height above and depth below the baseline, and a width.} +These properties can be modified with this request. The first argument +is the sum of the desired flags and the remaining arguments are the +characters to be assigned those properties. Spaces between the @var{cn} +arguments are optional. Any argument @var{cn} can be a character class +defined with the @code{class} request rather than an individual +character. @xref{Character Classes}. + +The non-negative integer @var{n} is the sum of any of the following. +Some combinations are nonsensical, such as @samp{33} (1 + 32). + +@table @code +@item 1 +@cindex end-of-sentence characters +@cindex characters, end-of-sentence +Recognize the character as ending a sentence if followed by a newline +or two spaces. Initially, characters @samp{.?!} have this property. + +@item 2 +@cindex hyphenating characters +@cindex characters, hyphenation +Enable breaks before the character. A line is not broken at a character +with this property unless the characters on each side both have non-zero +hyphenation codes. This exception can be overridden by adding 64. +Initially, no characters have this property. + +@item 4 +@cindex @code{\-} glyph, and @code{cflags} +@cindex @code{hy} glyph, and @code{cflags} +@cindex @code{em} glyph, and @code{cflags} +Enable breaks after the character. A line is not broken at a character +with this property unless the characters on each side both have non-zero +hyphenation codes. This exception can be overridden by adding 64. +Initially, characters @samp{\-\[hy]\[em]} have this property. + +@item 8 +@cindex overlapping characters +@cindex characters, overlapping +@cindex @code{ul} glyph, and @code{cflags} +@cindex @code{rn} glyph, and @code{cflags} +@cindex @code{ru} glyph, and @code{cflags} +@cindex @code{radicalex} glyph, and @code{cflags} +@cindex @code{sqrtex} glyph, and @code{cflags} +Mark the glyph associated with this character as overlapping other +instances of itself horizontally. Initially, characters +@samp{\[ul]\[rn]\[ru]\[radicalex]\[sqrtex]} have this property. + +@item 16 +@cindex @code{br} glyph, and @code{cflags} +Mark the glyph associated with this character as overlapping other +instances of itself vertically. Initially, the character @samp{\[br]} +has this property. + +@item 32 +@cindex transparent characters +@cindex character, transparent +@cindex @code{"}, at end of sentence +@cindex @code{'}, at end of sentence +@cindex @code{)}, at end of sentence +@cindex @code{]}, at end of sentence +@cindex @code{*}, at end of sentence +@cindex @code{dg} glyph, at end of sentence +@cindex @code{dd} glyph, at end of sentence +@cindex @code{rq} glyph, at end of sentence +@cindex @code{cq} glyph, at end of sentence +Mark the character as transparent for the purpose of end-of-sentence +recognition. In other words, an end-of-sentence character followed by +any number of characters with this property is treated as the end of a +sentence if followed by a newline or two spaces. This is the same as +having a zero space factor in @TeX{}. Initially, characters +@samp{"')]*\[dg]\[dd]\[rq]\[cq]} have this property. + +@item 64 +Ignore hyphenation codes of the surrounding characters. Use this in +combination with values 2 and@tie{}4 (initially, no characters have this +property). + +For example, if you need an automatic break point after the en-dash in +numeric ranges like ``3000--5000'', insert + +@Example +.cflags 68 \[en] +@endExample + +@noindent +into your document. However, this practice can lead to bad layout if +done thoughtlessly; in most situations, a better solution instead of +changing the @code{cflags} value is to insert @code{\:} right after the +hyphen at the places that really need a break point. +@end table + +The remaining values were implemented for East Asian language support; +those who use alphabetic scripts exclusively can disregard them. + +@table @code +@item 128 +Prohibit a line break before the character, but allow a line break after +the character. This works only in combination with flags 256 and 512 +and has no effect otherwise. Initially, no characters have this +property. + +@item 256 +Prohibit a line break after the character, but allow a line break before +the character. This works only in combination with flags 128 and 512 +and has no effect otherwise. Initially, no characters have this +property. + +@item 512 +Allow line break before or after the character. This works only in +combination with flags 128 and 256 and has no effect otherwise. +Initially, no characters have this property. +@end table + +In contrast to values 2 and@tie{}4, the values 128, 256, and 512 work +pairwise. If, for example, the left character has value 512, and the +right character 128, no break will be automatically inserted between +them. If we use value@tie{}6 instead for the left character, a break +after the character can't be suppressed since the neighboring character +on the right doesn't get examined. +@endDefreq + +@DefreqList {char, c [@Var{contents}]} +@DefreqItemx {fchar, c [@Var{contents}]} +@DefreqItemx {fschar, f c [@Var{contents}]} +@DefreqListEndx {schar, c [@Var{contents}]} +@cindex defining character (@code{char}) +@cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar}) +@cindex character, defining (@code{char}) +@cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar}) +@cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar}) +@cindex creating new characters (@code{char}) +@cindex defining symbol (@code{char}) +@cindex symbol, defining (@code{char}) +@cindex defining glyph (@code{char}) +@cindex glyph, defining (@code{char}) +@cindex escape character, while defining glyph +@cindex character, escape, while defining glyph +@cindex @code{tr} request, and glyph definitions +@cindex @code{cp} request, and glyph definitions +@cindex @code{rc} request, and glyph definitions +@cindex @code{lc} request, and glyph definitions +@cindex @code{\l}, and glyph definitions +@cindex @code{\L}, and glyph definitions +@cindex @code{\&}, and glyph definitions +@cindex @code{\e}, and glyph definitions +@cindex @code{hcode} request, and glyph definitions +Define a new character or glyph@tie{}@var{c} to be @var{contents}, which +can be empty. More precisely, @code{char} defines a @code{groff} object +(or redefines an existing one) that is accessed with the +name@tie{}@var{c} on input, and produces @var{contents} on output. +Every time glyph@tie{}@var{c} needs to be printed, @var{contents} is +processed in a temporary environment and the result is wrapped up into a +single object. Compatibility mode is turned off and the escape +character is set to@tie{}@code{\} while @var{contents} is processed. +Any emboldening, constant spacing, or track kerning is applied to this +object rather than to individual glyphs in @var{contents}. + +An object defined by these requests can be used just like a normal glyph +provided by the output device. In particular, other characters can be +translated to it with the @code{tr} or @code{trin} requests; it can be +made the leader character with the @code{lc} request; repeated patterns +can be drawn with it using the @code{\l} and @code{\L} escape sequences; +and words containing@tie{}@var{c} can be hyphenated correctly if the +@code{hcode} request is used to give the object a hyphenation code. + +There is a special anti-recursion feature: use of the object within its +own definition is handled like a normal character (not +defined with @code{char}). + +The @code{tr} and @code{trin} requests take precedence if @code{char} +accesses the same symbol. + +@Example +.tr XY +X + @result{} Y +.char X Z +X + @result{} Y +.tr XX +X + @result{} Z +@endExample + +The @code{fchar} request defines a fallback glyph: @code{gtroff} only +checks for glyphs defined with @code{fchar} if it cannot find the glyph +in the current font. @code{gtroff} carries out this test before +checking special fonts. + +@code{fschar} defines a fallback glyph for font@tie{}@var{f}: +@code{gtroff} checks for glyphs defined with @code{fschar} after the +list of fonts declared as font-specific special fonts with the +@code{fspecial} request, but before the list of fonts declared as global +special fonts with the @code{special} request. + +Finally, the @code{schar} request defines a global fallback glyph: +@code{gtroff} checks for glyphs defined with @code{schar} after the list +of fonts declared as global special fonts with the @code{special} +request, but before the already mounted special fonts. + +@xref{Character Classes}. +@endDefreq + +@DefreqList {rchar, c @dots{}} +@DefreqListEndx {rfschar, f c @dots{}} +@cindex removing glyph definition (@code{rchar}, @code{rfschar}) +@cindex glyph, removing definition (@code{rchar}, @code{rfschar}) +@cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar}) +Remove definition of each ordinary or special character @var{c}, +undoing the effect of a @code{char}, @code{fchar}, or @code{schar} +request. Those supplied by font description files cannot be removed. +Spaces and tabs may separate @var{c}@tie{}arguments. + +The request @code{rfschar} removes glyph definitions defined with +@code{fschar} for font@tie{}@var{f}. +@endDefreq + +@c --------------------------------------------------------------------- + +@node Character Classes, Special Fonts, Using Symbols, Using Fonts +@subsection Character Classes +@cindex character classes +@cindex classes, character + +Classes are particularly useful for East Asian languages such as +Chinese, Japanese, and Korean, where the number of needed characters is +much larger than in European languages, and where large sets of +characters share the same properties. + +@Defreq {class, name c1 c2 @dots{}} +@cindex character class (@code{class}) +@cindex defining character class (@code{class}) +@cindex class of characters (@code{class}) +Define a character class (or simply ``class'') @var{name} comprising +the characters @var{c1}, @var{c2}, and so on. + +A class thus defined can then be referred to in lieu of listing all the +characters within it. Currently, only the @code{cflags} request can +handle references to character classes. + +In the request's simplest form, each @var{cn} is a character (or special +character). + +@Example +.class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq] +@endExample + +Since class and glyph names share the same name space, it is recommended +to start and end the class name with @code{[} and @code{]}, +respectively, to avoid collisions with existing character names defined +by GNU @code{troff} or the user (with @code{char} and related requests). +This practice applies the presence of @code{]} in the class name to +prevent the use of the special character escape form +@code{\[@r{@dots{}}]}, thus you must use the @code{\C} escape to access +a class with such a name. + +@cindex GGL (@code{groff} glyph list) +@cindex @code{groff} glyph list (GGL) +You can also use a character range notation consisting of a +start character followed by @samp{-} and then an end character. +Internally, GNU @code{troff} converts these two symbol names to +Unicode code points (according to the @code{groff} glyph list [GGL]), +which then give the start and end value of the range. If that fails, +the class definition is skipped. + +Furthermore, classes can be nested. + +@Example +.class [prepunct] , : ; > @} +.class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016] +@endExample + +@noindent +The class @samp{[prepunctx]} thus contains the contents of the class +@code{[prepunct]} as defined above (the set @samp{, : ; > @}}), and +characters in the range between @code{U+2013} and @code{U+2016}. + +If you want to include @samp{-} in a class, it must be the first +character value in the argument list, otherwise it gets misinterpreted +as part of the range syntax. + +It is not possible to use class names as end points of range +definitions. + +A typical use of the @code{class} request is to control line-breaking +and hyphenation rules as defined by the @code{cflags} request. For +example, to inhibit line breaks before the characters belonging to the +@code{prepunctx} class defined in the previous example, you can write +the following. + +@Example +.cflags 2 \C'[prepunctx]' +@endExample + +@noindent +See the @code{cflags} request in @ref{Using Symbols}, for more details. +@endDefreq + +@c --------------------------------------------------------------------- + +@node Special Fonts, Artificial Fonts, Character Classes, Using Fonts +@subsection Special Fonts +@cindex special fonts +@cindex fonts, special + +Special fonts are those that @code{gtroff} searches when it cannot find +the requested glyph in the current font. The Symbol font is usually a +special font. + +@code{gtroff} provides the following two requests to add more special +fonts. @xref{Using Symbols}, for a detailed description of the glyph +searching mechanism in @code{gtroff}. + +Usually, only non-TTY devices have special fonts. + +@DefreqList {special, [@Var{s1} @Var{s2} @dots{}]} +@DefreqListEndx {fspecial, f [@Var{s1} @Var{s2} @dots{}]} +@kindex fonts +@pindex DESC +Use the @code{special} request to define special fonts. Initially, this +list is empty. + +Use the @code{fspecial} request to designate special fonts only when +font@tie{}@var{f} is active. Initially, this list is empty. + +Previous calls to @code{special} or @code{fspecial} are overwritten; +without arguments, the particular list of special fonts is set to empty. +Special fonts are searched in the order they appear as arguments. + +All fonts that appear in a call to @code{special} or @code{fspecial} +are loaded. + +@xref{Using Symbols}, for the exact search order of glyphs. +@endDefreq + +@c --------------------------------------------------------------------- + +@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Using Fonts +@subsection Artificial Fonts +@cindex artificial fonts +@cindex fonts, artificial + +There are a number of requests and escape sequences for artificially +creating fonts. These are largely vestiges of the days when output +devices did not have a wide variety of fonts, and when @code{nroff} and +@code{troff} were separate programs. Most of them are no longer +necessary in GNU @code{troff}. Nevertheless, they are supported. + +@DefescList {\\H, @code{'}, height, @code{'}} +@DefescItem {\\H, @code{'}, @t{+}height, @code{'}} +@DefescItem {\\H, @code{'}, @t{-}height, @code{'}} +@DefregListEndx {.height} +@cindex changing the font height (@code{\H}) +@cindex font height, changing (@code{\H}) +@cindex height, font, changing (@code{\H}) +Change (increment, decrement) the height of the current font, but not +the width. If @var{height} is zero, restore the original height. +Default scaling unit is @samp{z}. + +The read-only register @code{.height} contains the font height as set by +@code{\H}. + +Currently, only the @option{-Tps} and @option{-Tpdf} devices support +this feature. + +@code{\H} doesn't produce an input token in GNU @code{troff}. As a +consequence, it can be used in requests like @code{mc} (which expects +a single character as an argument) to change the font on the fly: + +@Example +.mc \H'+5z'x\H'0' +@endExample + +In compatibility mode, @code{gtroff} behaves differently: If an +increment or decrement is used, it is always taken relative to the +current type size and not relative to the previously selected font +height. Thus, + +@Example +.cp 1 +\H'+5'test \H'+5'test +@endExample + +@noindent +prints the word @samp{test} twice with the same font height (five points +larger than the current font size). +@endDefesc + +@DefescList {\\S, @code{'}, slant, @code{'}} +@DefregListEndx {.slant} +@cindex changing the font slant (@code{\S}) +@cindex font slant, changing (@code{\S}) +@cindex slant, font, changing (@code{\S}) +Slant the current font by @var{slant} degrees. Positive values slant to +the right. Only integer values are possible. + +The read-only register @code{.slant} contains the font slant as set by +@code{\S}. + +Currently, only the @option{-Tps} and @option{-Tpdf} devices support +this feature. + +@code{\S} doesn't produce an input token in GNU @code{troff}. As a +consequence, it can be used in requests like @code{mc} (which expects +a single character as an argument) to change the font on the fly: + +@Example +.mc \S'20'x\S'0' +@endExample + +@cindex CSTR@tie{}#54 errata +@cindex CSTR@tie{}#54 erratum, @code{\S} escape +This escape is incorrectly documented in the @acronym{AT&T} +@code{troff} manual; the slant is always set to an absolute value. +@endDefesc + +@Defreq {ul, [@Var{lines}]} +@cindex underlining (@code{ul}) +The @code{ul} request normally underlines subsequent lines if a TTY +output device is used. Otherwise, the lines are printed in italics +(only the term `underlined' is used in the following). The single +argument is the quantity of input lines to be underlined; with no +argument, the next line is underlined. If @var{lines} is zero or +negative, stop the effects of @code{ul} (if it was active). Requests +and empty lines do not count for computing the number of underlined +input lines, even if they produce some output like @code{tl}. Lines +inserted by macros (e.g., invoked by a trap) do count. + +At the beginning of @code{ul}, the current font is stored and the +underline font is activated. Within the span of a @code{ul} request, it +is possible to change fonts, but after the last line affected by +@code{ul} the saved font is restored. + +This number of lines still to be underlined is associated with the +environment (@pxref{Environments}). The underline font can be changed +with the @code{uf} request. + +@c XXX @xref should be changed to grotty + +@c @xref{@code{troff} and @code{nroff} Modes}, for a discussion of how +@c underlining is implemented for terminal output devices, and what +@c problems can arise. + +The @code{ul} request does not underline spaces. +@endDefreq + +@Defreq {cu, [@Var{lines}]} +@cindex continuous underlining (@code{cu}) +@cindex underlining, continuous (@code{cu}) +The @code{cu} request is similar to @code{ul} but underlines spaces as +well (if a TTY output device is used). +@endDefreq + +@Defreq {uf, font} +@cindex underline font (@code{uf}) +@cindex font for underlining (@code{uf}) +Set the underline font (globally) used by @code{ul} and @code{cu}. By +default, this is the font at position@tie{}2. @var{font} can be either +a non-negative font position or the name of a font. +@endDefreq + +@DefreqList {bd, font [@Var{offset}]} +@DefreqItem {bd, font1 font2 [@Var{offset}]} +@DefregListEndx {.b} +@cindex imitating boldface (@code{bd}) +@cindex boldface, imitating (@code{bd}) +Embolden @var{font} by overstriking its glyphs offset by @var{offset} +units minus one. + +Two syntax forms are available. + +@itemize @bullet +@item +Imitate a bold font unconditionally. The first argument specifies the +font to embolden, and the second is the number of basic units, minus +one, by which the two glyphs are offset. If the second argument is +missing, emboldening is turned off. + +@var{font} can be either a non-negative font position or the name of a +font. + +@var{offset} is available in the @code{.b} read-only register if a +special font is active; in the @code{bd} request, its default unit is +@samp{u}. + +@cindex @code{fspecial} request, and imitating bold +@kindex special +@cindex embolding of special fonts +@cindex special fonts, emboldening +@item +Imitate a bold form conditionally. Embolden @var{font1} by @var{offset} +only if font @var{font2} is the current font. This request can be +issued repeatedly to set up different emboldening values for different +current fonts. If the second argument is missing, emboldening is turned +off for this particular current font. + +This affects special fonts only (either set up with the @code{special} +command in font files or with the @code{fspecial} request). +@end itemize +@endDefreq + +@Defreq {cs, font [@Var{width} [@Var{em-size}]]} +@cindex constant glyph space mode (@code{cs}) +@cindex mode for constant glyph space (@code{cs}) +@cindex glyph, constant space +@cindex @code{ps} request, and constant glyph space mode +Switch to and from @dfn{constant glyph space mode}. If activated, the +width of every glyph is @math{@var{width}/36} ems. The em size is given +absolutely by @var{em-size}; if this argument is missing, the em value +is taken from the current font size (as set with the @code{ps} request) +when the font is effectively in use. Without second and third argument, +constant glyph space mode is deactivated. + +Default scaling unit for @var{em-size} is @samp{z}; @var{width} is an +integer. +@endDefreq + +@c --------------------------------------------------------------------- + +@node Ligatures and Kerning, Dummy Characters, Artificial Fonts, Using Fonts +@subsection Ligatures and Kerning +@cindex ligatures and kerning +@cindex kerning and ligatures + +Ligatures are groups of characters that are run together, i.e, producing +a single glyph. For example, the letters `f' and `i' can form a +ligature `fi' as in the word `file'. This produces a cleaner look +(albeit subtle) to the printed output. Usually, ligatures are not +available in fonts for TTY output devices. + +Most PostScript fonts support the fi and fl ligatures. The C/A/T +typesetter that was the target of @acronym{AT&T} @code{troff} also +supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or +`expert' fonts may include ligatures for `ft' and `ct', although GNU +@code{troff} does not support these (yet). + +Only the current font is checked for ligatures and kerns; neither +special fonts nor special charcters defined with the @code{char} request +(and its siblings) are taken into account. + +@DefreqList {lg, [@Var{flag}]} +@DefregListEndx {.lg} +@cindex activating ligatures (@code{lg}) +@cindex ligatures, activating (@code{lg}) +@cindex ligatures enabled register (@code{.lg}) +Switch the ligature mechanism on or off; if the parameter is non-zero or +missing, ligatures are enabled, otherwise disabled. Default is on. The +current ligature mode can be found in the read-only register @code{.lg} +(set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise). + +Setting the ligature mode to@tie{}2 enables the two-character ligatures +(fi, fl, and ff) and disables the three-character ligatures (ffi and +ffl). +@endDefreq + +@dfn{Pairwise kerning} is another subtle typesetting mechanism that +modifies the distance between a glyph pair to improve readability. In +most cases (but not always) the distance is decreased. +@iftex +For example, compare the combination of the letters `V' and `A'. With +kerning, `VA' is printed. Without kerning it appears as `V@w{}A'. +@end iftex +Typewriter-like fonts and fonts for terminals where all glyphs have the +same width don't use kerning. + +@DefreqList {kern, [@Var{flag}]} +@DefregListEndx {.kern} +@cindex activating kerning (@code{kern}) +@cindex kerning, activating (@code{kern}) +@cindex kerning enabled register (@code{.kern}) +Switch kerning on or off. If the parameter is non-zero or missing, +enable pairwise kerning, otherwise disable it. The read-only register +@code{.kern} is set to@tie{}1 if pairwise kerning is enabled, +0@tie{}otherwise. + +@cindex dummy character (@code{\&}), effect on kerning +@cindex character, dummy (@code{\&}), effect on kerning +If the font description file contains pairwise kerning information, +glyphs from that font are kerned. Kerning between two glyphs can be +inhibited by placing @code{\&} between them: @samp{V\&A}. + +@xref{Font Description File Format}. +@endDefreq + +@cindex track kerning +@cindex kerning, track +@dfn{Track kerning} expands or reduces the space between glyphs. This +can be handy, for example, if you need to squeeze a long word onto a +single line or spread some text to fill a narrow column. It must be +used with great care since it is usually considered bad typography if +the reader notices the effect. + +@Defreq {tkf, f s1 n1 s2 n2} +@cindex activating track kerning (@code{tkf}) +@cindex track kerning, activating (@code{tkf}) +Enable track kerning for font@tie{}@var{f}. If the current font +is@tie{}@var{f} the width of every glyph is increased by an amount +between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if +the current type size is less than or equal to @var{s1} the width is +increased by @var{n1}; if it is greater than or equal to @var{s2} the +width is increased by @var{n2}; if the type size is greater than or +equal to @var{s1} and less than or equal to @var{s2} the increase in +width is a linear function of the type size. + +The default scaling unit is @samp{z} for @var{s1} and @var{s2}, @samp{p} +for @var{n1} and @var{n2}. + +The track kerning amount is added even to the rightmost glyph in a line; +for large values it is thus recommended to increase the line length by +the same amount to compensate. +@endDefreq + +@c --------------------------------------------------------------------- + +@node Italic Corrections, Dummy Characters, Ligatures and Kerning, Using Fonts +@subsection Italic Corrections + +When typesetting adjacent glyphs from typefaces of different slants, the +space between them may require adjustment. + +@Defesc {\\/, , , } +@cindex italic correction (@code{\/}) +@cindex correction, italic (@code{\/}) +@cindex correction between oblique and upright glyph (@code{\/}, @code{\,}) +@cindex roman glyph, correction after italic glyph (@code{\/}) +@cindex upright glyph, correction after oblique glyph (@code{\/}) +Apply an @dfn{italic correction}:@: modify the spacing of the preceding +glyph so that the distance between it and the following glyph is correct +if the latter is of upright shape. For example, if an +italic@tie{}@samp{f} is followed immediately by a roman right +parenthesis, then in many fonts the top right portion of +the@tie{}@samp{f} overlaps the top left of the right parenthesis, which +is ugly. Use this escape sequence whenever an oblique glyph is +immediately followed by an upright glyph without any intervening space. +@endDefesc + +@Defesc {\\\,, , , } +@cindex left italic correction (@code{\,}) +@cindex correction, left italic (@code{\,}) +@cindex correction between upright and oblique glyph (@code{\/}, @code{\,}) +@cindex roman glyph, correction before italic glyph (@code{\,}) +@cindex upright glyph, correction before oblique glyph (@code{\,}) +Apply a @dfn{left italic correction}:@: modify the spacing of the +following glyph so that the distance between it and the preceding +glyph is correct if the latter is of upright shape. For example, +if a roman left parenthesis is immediately followed by an +italic@tie{}@samp{f}, then in many fonts the bottom left portion of +the@tie{}@samp{f} overlaps the bottom of the left parenthesis, which is +ugly. Use this escape sequence whenever an upright glyph is followed +immediately by an oblique glyph without any intervening space. +@endDefesc + +@c XXX: Can we move this node earlier in the text? Should it come +@c before some of the dummy character's multifarious effects? +@need 1000 +@node Dummy Characters, , Italic Corrections, Using Fonts +@subsection Dummy Characters + +As discussed in @ref{Requests and Macros}, the first character on an +input line is treated specially. Further, formatting a glyph has many +consequences on formatter state (@pxref{Environments}). Occasionally, +we want to escape this context or embrace some of those consequences +without actually rendering a glyph to the output. + +@Defesc {\\&, , , } +@cindex dummy character (@code{\&}) +@cindex character, dummy (@code{\&}) +Interpolate a dummy character, which is constitutive of output but +invisible.@footnote{Opinions of this escape sequence's name abound. +``Zero-width space'' is a popular misnomer:@: @code{roff} formatters do +not treat it like a space. Ossanna called it a ``non-printing, +zero-width character'', but the character causes @emph{output} even +though it does not ``print''. If no output line is pending, the dummy +character starts one. Contrast an empty input document with one +containing only @code{\&}. The former produces no output; the latter, a +blank page.} Its presence alters the interpretation context of a +subsequent input character, and enjoys several applications. + +@itemize @bullet +@item +Prevent insertion of extra space after an end-of-sentence character. + +@Example +Test. +Test. + @result{} Test. Test. +Test.\& +Test. + @result{} Test. Test. +@endExample + +@item +Prevent recognition of a control character. + +@Example +.Test + @error{} warning: macro 'Test' not defined +\&.Test + @result{} .Test +@endExample + +@item +Prevent kerning between two glyphs. + +@iftex +@c can't use @Example...@endExample here +@example +@group +VA + @result{} @r{VA} +V\&A + @result{} @r{V@w{}A} +@end group +@end example +@end iftex + +@item +Translate a character to ``nothing''. + +@Example +.tr JIjiK\&k\&UVuv +@c XXX: I might have the wrong noun declension in "university" here. +Post universitum, alea jacta est, OK? + @result{} Post vniversitvm, alea iacta est, O? +@endExample +@end itemize + +The dummy character escape sequence sees use in macro definitions as a +means of ensuring that arguments are treated as text even if they begin +with spaces or control characters. + +@Example +.de HD \" typeset a simple bold heading +. sp +. ft B +\&\\$1 \" exercise: remove the \& +. ft +. sp +.. +.HD .\|.\|.\|surprised? +@endExample +@endDefesc + +One way to think about the dummy character is to imagine placing the +symbol @samp{&} in the input at a certain location; if doing so has all +the side effects on formatting that you desire except for sticking an +ugly ampersand in the midst of your text, the dummy character is what +you want in its place. + +@c XXX: This feature seems nearly impossible to motivate. The _only_ +@c use of it in the groff source tree is for the mdoc package, for which +@c it seems to be special pleading for that package's unique approach to +@c macro argument reprocessing, which also involves an idiosyncratic +@c approach to punctuation characters in macro argument lists. +@Defesc {\\), , , } +@cindex transparent dummy character (@code{\)}) +@cindex character, transparent dummy (@code{\)}) +@cindex dummy character, transparent (@code{\)}) +Interpolate a @slanted{transparent} dummy character---one that is +transparent to end-of-sentence detection. It behaves as @code{\&}, +except that @code{\&} is treated as letters and numerals normally are +after @samp{.}, @samp{?} and @samp{!}; @code{\&} cancels end-of-sentence +detection, and @code{\)} does not. +@c This feature seems too weak to me; see Savannah #60571. -- GBR + +@Example +.de Suffix-& +. nop \&\\$1 +.. +. +.de Suffix-) +. nop \)\\$1 +.. +. +Here's a sentence.\c +.Suffix-& ' +Another one.\c +.Suffix-) ' +And a third. + @result{} Here's a sentence.' Another one.' And a third. +@endExample +@endDefesc + + +@c ===================================================================== + +@c TODO: Move the troff and nroff mode stuff here. Try to keep stuff +@c that isn't ignored in nroff above this point, and stuff for +@c typesetters below, until we hit the programming/advanced concepts. +@c XXX: Thorny issue: nroff/terminal devices ignore type size but +@c _honor_ vertical spacing (to within their crude vertical motion +@c quanta). + +@need 2000 +@node Manipulating Type Size and Vertical Spacing, Colors, Using Fonts, GNU troff Reference +@section Manipulating Type Size and Vertical Spacing +@cindex manipulating type size and vertical spacing + +@cindex text baseline +@cindex baseline, text +@cindex type size +@cindex size, size +@cindex vertical spacing +@cindex spacing, vertical +These concepts were introduced in @ref{Page Geometry}. The height of a +font's tallest glyph is one em, which is equal to the type size in +points.@footnote{In text fonts, the tallest glyphs are typically +parentheses. Unfortunately, in many cases the actual dimensions of the +glyphs in a font do not closely match its declared type size! For +example, in the standard PostScript font families, 10-point Times sets +better with 9-point Helvetica and 11-point Courier than if all three +were used at 10@tie{}points.} A vertical spacing of less than 120% of +the type size can make a document hard to read. Larger proportions can +be useful to spread the text for annotations or proofreader's marks. By +default, GNU @code{troff} uses 10@tie{}point type on 12@tie{}point +spacing. +@cindex leading +Typographers call the difference between type size and vertical spacing +@dfn{leading}.@footnote{Rhyme with ``sledding''; mechanical typography +used lead metal (Latin @emph{plumbum}).} + +@menu +* Changing the Type Size:: +* Changing the Vertical Spacing:: +* Using Fractional Type Sizes:: +@end menu + +@c --------------------------------------------------------------------- + +@node Changing the Type Size, Changing the Vertical Spacing, Manipulating Type Size and Vertical Spacing, Manipulating Type Size and Vertical Spacing +@subsection Changing the Type Size + +@DefreqList {ps, [@Var{size}]} +@DefreqItem {ps, @t{+}@Var{size}} +@DefreqItem {ps, @t{-}@Var{size}} +@DefescItemx {\\s, , size, } +@DefregListEndx {.s} +@cindex changing type sizes (@code{ps}, @code{\s}) +@cindex type sizes, changing (@code{ps}, @code{\s}) +@cindex point sizes, changing (@code{ps}, @code{\s}) +Use the @code{ps} request or the @code{\s} escape sequence to change +(increase, decrease) the type size (in scaled points). Specify +@var{size} as either an absolute type size, or as a relative change from +the current size. @code{ps} with no argument restores the previous +size. The @code{ps} request's default scaling unit is @samp{z}. The +requested size is rounded to the nearest valid size (with ties rounding +down) within the limits supported by the device. If the requested size +is non-positive, it is treated as 1@dmn{u}. + +@cindex CSTR@tie{}#54 errata +@cindex CSTR@tie{}#54 erratum, @code{ps} request +@cindex CSTR@tie{}#54 erratum, @code{\s} escape sequence +Type size alteration is incorrectly documented in the @acronym{AT&T} +@code{troff} manual, which claims ``if [the requested size] is invalid, +the next larger valid size will result, with a maximum of +36''.@footnote{The claim appears to have been true of Ossanna +@code{troff} for the C/A/T device; Kernighan made device-independent +@code{troff} more flexible.} + +@cindex type size registers (@code{.s}, @code{.ps}) +@cindex point size registers (@code{.s}, @code{.ps}) +The read-only string-valued register @code{.s} interpolates the type +size in points as a decimal fraction; it is associated with the +environment (@pxref{Environments}). To obtain the type size in scaled +points, interpolate the @code{.ps} register instead (@pxref{Using +Fractional Type Sizes}). + +The @code{\s} escape sequence supports a variety of syntax forms. + +@table @code +@item \s@var{n} +Set the type size to @var{n}@tie{}points. @var{n}@tie{}must be a single +digit. If @var{n}@tie{}is 0, restore the previous size. + +@item \s+@var{n} +@itemx \s-@var{n} +Increase or decrease the type size by @var{n}@tie{}points. +@var{n}@tie{}must be exactly one digit. + +@item \s(@var{nn} +Set the type size to @var{nn}@tie{}points. @var{nn} must be exactly two +digits. + +@item \s+(@var{nn} +@itemx \s-(@var{nn} +@itemx \s(+@var{nn} +@itemx \s(-@var{nn} +Alter the type size in points by the two-digit value @var{nn}. +@end table + +@xref{Using Fractional Type Sizes}, for further syntactical forms of the +@code{\s} escape sequence that additionally accept decimal fractions. + +@Example +snap, snap, +.ps +2 +grin, grin, +.ps +2 +wink, wink, \s+2nudge, nudge,\s+8 say no more! +.ps 10 +@endExample +@endDefreq + +The @code{\s} escape sequence affects the environment immediately and +doesn't produce an input token. Consequently, it can be used in +requests like @code{mc}, which expects a single character as an +argument, to change the type size on the fly. + +@Example +.mc \s[20]x\s[0] +@endExample + +@Defreq {sizes, s1 s2 @dots{} sn [@t{0}]} +The @file{DESC} file specifies which type sizes are allowed by the +output device; see @ref{DESC File Format}. Use the @code{sizes} request +to change this set of permissible sizes. Arguments are in scaled +points; see @ref{Using Fractional Type Sizes}. Each can be a single +type size (such as @samp{12000}), or a range of sizes (such as +@samp{4000-72000}). You can optionally end the list with a @samp{0}. +@endDefreq + +@need 1000 +@node Changing the Vertical Spacing, Using Fractional Type Sizes, Changing the Type Size, Manipulating Type Size and Vertical Spacing +@subsection Changing the Vertical Spacing + +@DefreqList {vs, [@Var{space}]} +@DefreqItem {vs, @t{+}@Var{space}} +@DefreqItem {vs, @t{-}@Var{space}} +@DefregListEndx {.v} +@cindex changing vertical line spacing (@code{vs}) +@cindex vertical line spacing, changing (@code{vs}) +@cindex vertical line spacing register (@code{.v}) +Set the vertical spacing to, or alter it by, @var{space}. The default +scaling unit is @samp{p}. If @code{vs} is called without an argument, +the vertical spacing is reset to the previous value before the last call +to @code{vs}. +@cindex @code{.V} register, and @code{vs} +GNU @code{troff} emits a warning in category @samp{range} if @var{space} +is negative; the vertical spacing is then set to the smallest possible +positive value, the vertical motion quantum (as found in the @code{.V} +register). + +@w{@samp{.vs 0}} isn't saved in a diversion since it doesn't result in +a vertical motion. You must explicitly issue this request before +interpolating the diversion. + +The read-only register @code{.v} contains the vertical spacing; it is +associated with the environment (@pxref{Environments}). +@endDefreq + +@cindex vertical line spacing, effective value +@noindent +When a break occurs, GNU @code{troff} performs the following procedure. + +@itemize @bullet +@item +@cindex extra pre-vertical line space (@code{\x}) +@cindex line space, extra pre-vertical (@code{\x}) +Move the drawing position vertically by the @dfn{extra pre-vertical line +space}, the minimum of all negative @code{\x} escape sequence arguments +in the pending output line. + +@item +Move the drawing position vertically by the vertical line spacing. + +@item +Write out the pending output line. + +@item +@cindex extra post-vertical line space (@code{\x}) +@cindex line space, extra post-vertical (@code{\x}) +Move the drawing position vertically by the @dfn{extra post-vertical line +space}, the maximum of all positive @code{\x} escape sequence arguments +in the line that has just been output. + +@item +@cindex post-vertical line spacing +@cindex line spacing, post-vertical (@code{pvs}) +Move the drawing position vertically by the @dfn{post-vertical line +spacing} (see below). +@end itemize + +@cindex double-spacing (@code{vs}, @code{pvs}) +Prefer @code{vs} or @code{pvs} over @code{ls} to produce double-spaced +documents. @code{vs} and @code{pvs} have finer granularity than +@code{ls}; moreover, some preprocessors assume single spacing. +@xref{Manipulating Spacing}, regarding the @code{\x} escape sequence and +the @code{ls} request. + +@DefreqList {pvs, [@Var{space}]} +@DefreqItem {pvs, @t{+}@Var{space}} +@DefreqItem {pvs, @t{-}@Var{space}} +@DefregListEndx {.pvs} +@cindex @code{ls} request, alternative to (@code{pvs}) +@cindex post-vertical line spacing, changing (@code{pvs}) +@cindex post-vertical line spacing register (@code{.pvs}) +Set the post-vertical spacing to, or alter it by, @var{space}. The +default scaling unit is @samp{p}. If @code{pvs} is called without an +argument, the post-vertical spacing is reset to the previous value +before the last call to @code{pvs}. GNU @code{troff} emits a warning in +category @samp{range} if @var{space} is negative; the post-vertical +spacing is then set to zero. + +The read-only register @code{.pvs} contains the post-vertical spacing; +it is associated with the environment (@pxref{Environments}). +@endDefreq + +@c --------------------------------------------------------------------- + +@c BEGIN Keep (roughly) parallel with subsection "Fractional type sizes +@c and new scaling units" of groff_diff(7). +@node Using Fractional Type Sizes, , Changing the Type Size, Manipulating Type Size and Vertical Spacing +@subsection Using Fractional Type Sizes +@cindex fractional type sizes +@cindex fractional point sizes +@cindex type sizes, fractional +@cindex point sizes, fractional +@cindex sizes, fractional type + +AT&T @code{troff} interpreted all type size measurements in points. +Combined with integer arithmetic, this design choice made it impossible +to support, for instance, ten and a half-point type. In GNU +@code{troff}, an output device can select a scaling factor that +subdivides a point into ``scaled points''. A type size expressed in +scaled points can thus represent a non-integral type size. + +@cindex @code{s} scaling unit +@cindex unit, scaling, @code{s} +@cindex scaling unit @code{s} +@cindex @code{z} scaling unit +@cindex unit, scaling, @code{z} +@cindex scaling unit @code{z} +@cindex @code{ps} request, with fractional type sizes +@cindex @code{cs} request, with fractional type sizes +@cindex @code{tkf} request, with fractional type sizes +@cindex @code{\H}, with fractional type sizes +@cindex @code{\s}, with fractional type sizes +A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, where +@var{sizescale} is specified in the device description file @file{DESC}, +and defaults to@tie{}1.@footnote{@xref{Device and Font Description +Files}.} Requests and escape sequences in GNU @code{troff} interpret +arguments that represent a type size in scaled points, which the +formatter multiplies by @var{sizescale} and converts to an integer. +Arguments treated in this way comprise those to the escape sequences +@code{\H} and @code{\s}, to the request @code{ps}, the third argument to +the @code{cs} request, and the second and fourth arguments to the +@code{tkf} request. Scaled points may be specified explicitly with the +@code{z} scaling unit. + +For example, if @var{sizescale} is@tie{}1000, then a scaled point is one +thousandth of a point. The request @samp{.ps 10.5} is synonymous with +@samp{.ps 10.5z} and sets the type size to 10,500@tie{}scaled points, or +10.5@tie{}points. Consequently, in GNU @code{troff}, the register +@code{.s} can interpolate a non-integral type size. + +@Defreg {.ps} +This read-only register interpolates the type size in scaled points; it +is associated with the environment (@pxref{Environments}). +@endDefreg + +It makes no sense to use the @samp{z} scaling unit in a numeric +expression whose default scaling unit is neither @samp{u} nor @samp{z}, +so GNU @code{troff} disallows this. Similarly, it is nonsensical to use +a scaling unit other than @samp{z} or @samp{u} in a numeric expression +whose default scaling unit is @samp{z}, and so GNU @code{troff} +disallows this as well. + +Another GNU @code{troff} scaling unit, @samp{s}, multiplies by the +number of basic units in a scaled point. Thus, @samp{\n[.ps]s} is equal +to @samp{1m} by definition. Do not confuse the @samp{s} and @samp{z} +scaling units. +@c END Keep (roughly) parallel with subsection "Fractional type sizes +@c and new scaling units" of groff_diff(7). + +@DefregList {.psr} +@DefregListEndx {.sr} +@cindex last-requested type size registers (@code{.psr}, @code{.sr}) +@cindex type size registers, last-requested (@code{.psr}, @code{.sr}) +@cindex last-requested point size registers (@code{.psr}, @code{.sr}) +@cindex point size registers, last-requested (@code{.psr}, @code{.sr}) +@cindex @code{.ps} register, in comparison with @code{.psr} +@cindex @code{.s} register, in comparison with @code{.sr} +Output devices may be limited in the type sizes they can employ. The +@code{.s} and @code{.ps} registers represent the type size selected by +the output driver as it understands a device's capability. The last +@emph{requested} type size is interpolated in scaled points by the +read-only register @code{.psr} and in points as a decimal fraction by +the read-only string-valued register @code{.sr}. Both are associated +with the environment (@pxref{Environments}). + +For example, if a type size of 10.95 points is requested, and the +nearest size permitted by a @code{sizes} request (or by the @code{sizes} +or @code{sizescale} directives in the device's @file{DESC} file) is 11 +points, the output driver uses the latter value. +@endDefreg + +The @code{\s} escape sequence offers the following syntax forms that +work with fractional type sizes and accept scaling units. You may of +course give them integral arguments. The delimited forms need not use +the neutral apostrophe; see @ref{Delimiters}. + +@table @code +@item \s[@var{n}] +@itemx \s'@var{n}' +Set the type size to @var{n}@tie{}scaled points; @var{n}@tie{}is a +numeric expression with a default scaling unit of @samp{z}. + +@item \s[+@var{n}] +@itemx \s[-@var{n}] +@itemx \s+[@var{n}] +@itemx \s-[@var{n}] +@itemx \s'+@var{n}' +@itemx \s'-@var{n}' +@itemx \s+'@var{n}' +@itemx \s-'@var{n}' +Increase or decrease the type size by @var{n}@tie{}scaled points; +@var{n}@tie{}is a numeric expression (which may start with a minus sign) +with a default scaling unit of @samp{z}. +@end table + + +@c ===================================================================== + +@c BEGIN Keep (roughly) parallel with section "Colors" of groff(7). +@node Colors, Strings, Manipulating Type Size and Vertical Spacing, GNU troff Reference +@section Colors +@cindex colors + +@cindex stroke color +@cindex color, stroke +@cindex fill color +@cindex color, fill +GNU @code{troff} supports color output with a variety of color spaces +and up to 16 bits per channel. Some devices, particularly terminals, +may be more limited. When color support is enabled, two colors are +current at any given time: the @dfn{stroke color}, with which glyphs, +rules (lines), and geometric objects like circles and polygons are +drawn, and the @dfn{fill color}, which can be used to paint the interior +of a closed geometric figure. + +@DefreqList {color, [@Var{n}]} +@DefregListEndx {.color} +If @var{n} is missing or non-zero, enable the output of color-related +device-independent output commands (this is the default); otherwise, +disable them. This request sets a global flag; it does not produce an +input token (@pxref{Gtroff Internals}). + +The read-only register @code{.color} is@tie{}1 if colors are enabled, +0@tie{}otherwise. + +Color can also be disabled with the @option{-c} command-line option. +@endDefreq + +@Defreq {defcolor, ident scheme color-component @dots{}} +Define a color named @var{ident}. @var{scheme} selects a color space +and determines the quantity of required @var{color-component}s; it must +be one of @samp{rgb} (three components), @samp{cmy} (three), @samp{cmyk} +(four), or @samp{gray} (one). @samp{grey} is accepted as a synonym of +@samp{gray}. The color components can be encoded as a single +hexadecimal value starting with @samp{#} or @samp{##}. The former +indicates that each component is in the range 0--255 (0--FF), the latter +the range 0--65,535 (0--FFFF). + +@Example +.defcolor half gray #7f +.defcolor pink rgb #FFC0CB +.defcolor magenta rgb ##ffff0000ffff +@endExample + +@cindex @code{f} scaling unit +@cindex unit, scaling, @code{f} +@cindex scaling unit @code{f} +Alternatively, each color component can be specified as a decimal +fraction in the range 0--1, interpreted using a default scaling +unit of@tie{}@code{f}, which multiplies its value by 65,536 (but +clamps it at 65,535). + +@Example +.defcolor gray50 rgb 0.5 0.5 0.5 +.defcolor darkgreen rgb 0.1f 0.5f 0.2f +@endExample +@endDefreq + +@cindex default color +@cindex color, default +Each output device has a color named @samp{default}, which cannot be +redefined. A device's default stroke and fill colors are not +necessarily the same. For the @code{dvi}, @code{html}, @code{pdf}, +@code{ps}, and @code{xhtml} output devices, GNU @code{troff} +automatically loads a macro file defining many color names at startup. +By the same mechanism, the devices supported by @code{grotty} recognize +the eight standard ISO@tie{}6429/EMCA-48 color names.@footnote{also +known vulgarly as ``ANSI colors''} + +@DefreqList {gcolor, [@Var{color}]} +@DefescItemx {\\m, , c, } +@DefescItem {\\m, (, co, } +@DefescItem {\\m, [, color, ]} +@DefregListEndx {.m} +Set the stroke color to @var{color}. + +@Example +.gcolor red +The next words +.gcolor +\m[red]are in red\m[] +and these words are in the previous color. +@endExample + +The escape sequence @code{\m[]} restores the previous stroke color, as +does a @code{gcolor} request without an argument. + +@cindex stroke color name register (@code{.m}) +@cindex name, stroke color, register (@code{.m}) +@cindex color name, stroke, register (@code{.m}) +The name of the current stroke color is available in the read-only +string-valued register @samp{.m}; it is associated with the environment +(@pxref{Environments}). It interpolates nothing when the stroke color +is the default. + +@code{\m} doesn't produce an input token in GNU @code{troff} +(@pxref{Gtroff Internals}). It therefore can be used in requests like +@code{mc} (which expects a single character as an argument) to change +the color on the fly: + +@Example +.mc \m[red]x\m[] +@endExample +@endDefesc + +@DefreqList {fcolor, [@Var{color}]} +@DefescItemx {\\M, , c, } +@DefescItem {\\M, (, co, } +@DefescItem {\\M, [, color, ]} +@DefregListEndx {.M} +Set the fill color for objects drawn with @code{\D'@dots{}'} escape +sequences. The escape sequence @code{\M[]} restores the previous fill +color, as does an @code{fcolor} request without an argument. + +@cindex background color name register (@code{.M}) +@cindex name, background color, register (@code{.M}) +@cindex color name, background, register (@code{.M}) +@cindex fill color name register (@code{.M}) +@cindex name, fill color, register (@code{.M}) +@cindex color name, fill, register (@code{.M}) +The name of the current fill color is available in the read-only +string-valued register @samp{.M}; it is associated with the environment +(@pxref{Environments}). It interpolates nothing when the fill color +is the default. @code{\M} doesn't produce an input token in GNU +@code{troff}. + +Create an ellipse with a red interior as follows. + +@Example +\M[red]\h'0.5i'\D'E 2i 1i'\M[] +@endExample +@endDefesc +@c END Keep (roughly) parallel with section "Colors" of groff(7). + + +@c ===================================================================== + +@c BEGIN Keep (roughly) parallel with section "Strings" of groff(7). +@node Strings, Conditionals and Loops, Colors, GNU troff Reference +@section Strings +@cindex strings + +GNU @code{troff} supports strings primarily for user convenience. +Conventionally, if one would define a macro only to interpolate a small +amount of text, without invoking requests or calling any other macros, +one defines a string instead. Only one string is predefined by the +language. + +@Defstr {.T} +@stindex .T +@cindex output device name string (@code{.T}) +Contains the name of the output device (for example, @samp{utf8} or +@samp{pdf}). +@endDefmpstr + +The @code{ds} request creates a string with a specified name and +contents and the @code{\*} escape sequence dereferences its name, +interpolating its contents. If the string named by the @code{\*} escape +sequence does not exist, it is defined as empty, nothing is +interpolated, and a warning in category @samp{mac} is emitted. +@xref{Warnings}, for information about the enablement and suppression of +warnings. + +@DefreqList {ds, name [@Var{contents}]} +@DefreqItemx {ds1, name [@Var{contents}]} +@DefescItemx {\\*, , n, } +@DefescItem {\\*, (, nm, } +@c XXX: Can't mark the parameters with @Var because @Var gets called +@c recursively if we do. +@c @DefescListEnd {\\*, [, name [@Var{arg1} @Var{arg2} @dots{}], ]} +@DefescListEnd {\\*, [, name @sansserif{[}arg1 arg2 @dots{}@sansserif{]}, ]} +@cindex string interpolation (@code{\*}) +@cindex string expansion (@code{\*}) +@cindex interpolation of strings (@code{\*}) +@cindex expansion of strings (@code{\*}) +@cindex string arguments +@cindex arguments, to strings +Define a string called @var{name} with contents @var{contents}. If +@var{name} already exists as an alias, the target of the alias is +redefined; see @code{als} and @code{rm} below. If @code{ds} is called +with only one argument, @var{name} is defined as an empty string. +Otherwise, GNU @code{troff} stores @var{contents} in copy +mode.@footnote{@xref{Copy Mode}.} + +The @code{\*} escape sequence interpolates a previously defined string +variable @var{name} (one-character name@tie{}@var{n}, two-character name +@var{nm}). The bracketed interpolation form accepts arguments that are +handled as macro arguments are; recall @ref{Calling Macros}. In +contrast to macro calls, however, if a closing bracket @samp{]} occurs +in a string argument, that argument must be enclosed in double quotes. +@code{\*} is interpreted even in copy mode. When defining strings, +argument interpolations must be escaped if they are to reference +parameters from the calling context; @xref{Parameters}. + +@Example +.ds cite (\\$1, \\$2) +Gray codes are explored in \*[cite Morgan 1998]. + @result{} Gray codes are explored in (Morgan, 1998). +@endExample + +@c TODO: Consider examples of recursive string calls, particularly where +@c one interpolation is constructed from the argument of an enclosing +@c macro, to illustrate ".ds a \$1 \\$1". +@c +@c @Example +@c .ds a \\$1 wildebeest +@c .ds b big, \*[a hairy] +@c I see a \*[b]. +@c @result{} I see a big, hairy wildebeest. +@c @endExample + +@cindex trailing spaces in string definitions and appendments +@cindex comments, with @code{ds} +@cindex @code{ds} request, and comments +@strong{Caution:@:} Unlike other requests, the second argument to the +@code{ds} request consumes the remainder of the input line, including +trailing spaces. This means that comments on a line with such a request +can introduce unwanted space into a string when they are set off from +the material they annotate, as is conventional. + +@Example +.ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O \" water +@endExample + +@noindent +Instead, place the comment on another line or put the comment escape +sequence immediately adjacent to the last character of the string. + +@Example +.ds H2O H\v'+.3m'\s'-2'2\v'-.3m'\s0O\" water +@endExample + +Ending string definitions (and appendments) with a comment, even an +empty one, prevents unwanted space from creeping into them during source +document maintenance. + +@Example +.ds author Alice Pleasance Liddell\" +.ds empty \" might be appended to later with .as +@endExample + +@cindex trailing double quotes in strings +@cindex double quotes, trailing, in strings +@cindex @code{ds} request, and double quotes +@cindex leading spaces with @code{ds} +@cindex spaces with @code{ds} +@cindex @code{ds} request, and leading spaces +An initial neutral double quote @code{"} in @var{contents} is stripped +to allow embedding of leading spaces. Any other @code{"} is interpreted +literally, but it is wise to use the special character escape sequence +@code{\[dq]} instead if the string might be interpolated as part of a +macro argument; see @ref{Calling Macros}. + +@c Examples should be more accessible than Unix nerd stuff like this, +@c but in general document authors shouldn't want to use "straight" +@c double quotes for ordinary prose anyway. Also, 56 chars is as fat +@c as these examples can get and not overrun the right margin in PDF. +@Example +.ds salutation " Yours in a white wine sauce,\" +.ds c-var-defn " char mydate[]=\[dq]2020-07-29\[dq];\" +@endExample + +@cindex multi-line strings +@cindex strings, multi-line +@cindex newline character, in strings, escaping +@cindex escaping newline characters, in strings +Strings are not limited to a single input line of text. +@code{\@key{RET}} works just as it does elsewhere. The resulting string +is stored @emph{without} the newlines. Care is therefore required when +interpolating strings while filling is disabled. + +@Example +.ds foo This string contains \ +text on multiple lines \ +of input. +@endExample + +It is not possible to embed a newline in a string that will be +interpreted as such when the string is interpolated. To achieve that +effect, use @code{\*} to interpolate a macro instead; see @ref{Punning +Names}. + +Because strings are similar to macros, they too can be defined so as to +suppress AT&T @code{troff} compatibility mode when used; see +@ref{Writing Macros} and @ref{Compatibility Mode}. The @code{ds1} +request defines a string such that compatibility mode is off when the +string is later interpolated. To be more precise, a @dfn{compatibility +save} input token is inserted at the beginning of the string, and a +@dfn{compatibility restore} input token at the end. + +@Example +.nr xxx 12345 +.ds aa The value of xxx is \\n[xxx]. +.ds1 bb The value of xxx is \\n[xxx]. +. +.cp 1 +. +\*(aa + @error{} warning: register '[' not defined + @result{} The value of xxx is 0xxx]. +\*(bb + @result{} The value of xxx is 12345. +@endExample +@endDefreq + +@DefreqList {as, name [@Var{contents}]} +@DefreqListEndx {as1, name [@Var{contents}]} +@cindex appending to a string (@code{as}) +@cindex string, appending (@code{as}) +The @code{as} request is similar to @code{ds} but appends @var{contents} +to the string stored as @var{name} instead of redefining it. If +@var{name} doesn't exist yet, it is created. If @code{as} is called +with only one argument, no operation is performed (beyond dereferencing +the string). + +@Example +.as salutation " with shallots, onions and garlic,\" +@endExample + +The @code{as1} request is similar to @code{as}, but compatibility mode +is switched off when the appended portion of the string is later +interpolated. To be more precise, a @dfn{compatibility save} input +token is inserted at the beginning of the appended string, and a +@dfn{compatibility restore} input token at the end. +@endDefreq + +Several requests exist to perform rudimentary string operations. +Strings can be queried (@code{length}) and modified (@code{chop}, +@code{substring}, @code{stringup}, @code{stringdown}), and their names +can be manipulated through renaming, removal, and aliasing (@code{rn}, +@code{rm}, @code{als}). + +@Defreq {length, reg anything} +@cindex length of a string (@code{length}) +@cindex string, length of (@code{length}) +@cindex @code{length} request, and copy mode +@cindex copy mode, and @code{length} request +@cindex mode, copy, and @code{length} request +Compute the number of characters of @var{anything} and store the count +in the register @var{reg}. If @var{reg} doesn't exist, it is created. +@var{anything} is read in copy mode. + +@Example +.ds xxx abcd\h'3i'efgh +.length yyy \*[xxx] +\n[yyy] + @result{} 14 +@endExample +@endDefreq + +@Defreq {chop, object} +Remove the last character from the macro, string, or diversion named +@var{object}. This is useful for removing the newline from the end of a +diversion that is to be interpolated as a string. This request can be +used repeatedly on the same @var{object}; see @ref{Gtroff Internals}, +for details on nodes inserted additionally by GNU @code{troff}. +@endDefreq + +@Defreq {substring, str start [@Var{end}]} +@cindex substring (@code{substring}) +Replace the string named @var{str} with its substring bounded by the +indices @var{start} and @var{end}, inclusively. The first character in +the string has index@tie{}0. If @var{end} is omitted, it is implicitly +set to the largest valid value (the string length minus one). Negative +indices count backward from the end of the string:@: the last character +has index@tie{}@minus{}1, the character before the last has +index@tie{}@minus{}2, and so on. + +@Example +.ds xxx abcdefgh +.substring xxx 1 -4 +\*[xxx] + @result{} bcde +.substring xxx 2 +\*[xxx] + @result{} de +@endExample +@endDefreq + +@DefreqList {stringdown, str} +@DefreqListEndx {stringup, str} +@cindex case-transforming a string (@code{stringdown}, @code{stringup}) +@cindex uppercasing a string (@code{stringup}) +@cindex lowercasing a string (@code{stringdown}) +@cindex up-casing a string (@code{stringup}) +@cindex down-casing a string (@code{stringdown}) +Alter the string named @var{str} by replacing each of its bytes with its +lowercase (@code{stringdown}) or uppercase (@code{stringup}) version (if +one exists). Special characters in the string will often transform in +the expected way due to the regular naming convention for accented +characters. When they do not, use substrings and/or catenation. + +@Example +.ds resume R\['e]sum\['e] +\*[resume] +.stringdown resume +\*[resume] +.stringup resume +\*[resume] + @result{} Résumé résumé RÉSUMÉ +@endExample +@endDefreq + +(In practice, we would end the @code{ds} request with a comment escape +@code{\"} to prevent space from creeping into the definition during +source document maintenance.) + +@Defreq {rn, old new} +@cindex renaming request (@code{rn}) +@cindex request, renaming (@code{rn}) +@cindex renaming macro (@code{rn}) +@cindex macro, renaming (@code{rn}) +@cindex renaming string (@code{rn}) +@cindex string, renaming (@code{rn}) +@cindex renaming diversion (@code{rn}) +@cindex diversion, renaming (@code{rn}) +Rename the request, macro, diversion, or string @var{old} to @var{new}. +@endDefreq + +@Defreq {rm, name} +@cindex removing request (@code{rm}) +@cindex request, removing (@code{rm}) +@cindex removing macro (@code{rm}) +@cindex macro, removing (@code{rm}) +@cindex removing string (@code{rm}) +@cindex string, removing (@code{rm}) +@cindex removing diversion (@code{rm}) +@cindex diversion, removing (@code{rm}) +Remove the request, macro, diversion, or string @var{name}. GNU +@code{troff} treats subsequent invocations as if the name had never +been defined. +@endDefreq + +@anchor{als} +@Defreq {als, new old} +@cindex alias, string, creating (@code{als}) +@cindex alias, macro, creating (@code{als}) +@cindex alias, diversion, creating (@code{als}) +@cindex creating alias, for string (@code{als}) +@cindex creating alias, for macro (@code{als}) +@cindex creating alias, for diversion (@code{als}) +@cindex string, creating alias for (@code{als}) +@cindex macro, creating alias for (@code{als}) +@cindex diversion, creating alias for (@code{als}) +Create an alias @var{new} for the existing request, string, macro, or +diversion object named @var{old}, causing the names to refer to the same +stored object. If @var{old} is undefined, a warning in category +@samp{mac} is produced, and the request is ignored. @xref{Warnings}, +for information about the enablement and suppression of warnings. + +To understand how the @code{als} request works, consider two different +storage pools:@: one for objects (macros, strings, etc.), and another +for names. As soon as an object is defined, GNU @code{troff} adds it to +the object pool, adds its name to the name pool, and creates a link +between them. When @code{als} creates an alias, it adds a new name to +the name pool that gets linked to the same object as the old name. + +Now consider this example. + +@Example +.de foo +.. +. +.als bar foo +. +.de bar +. foo +.. +. +.bar + @error{} input stack limit exceeded (probable infinite + @error{} loop) +@endExample + +@noindent +In the above, @code{bar} remains an @emph{alias}---another name +for---the object referred to by @code{foo}, which the second @code{de} +request replaces. Alternatively, imagine that the @code{de} request +@emph{dereferences} its argument before replacing it. Either way, the +result of calling @code{bar} is a recursive loop that finally leads to +an error. @xref{Writing Macros}. + +@cindex alias, string, removing (@code{rm}) +@cindex alias, macro, removing (@code{rm}) +@cindex alias, diversion, removing (@code{rm}) +@cindex removing alias, for string (@code{rm}) +@cindex removing alias, for macro (@code{rm}) +@cindex removing alias, for diversion (@code{rm}) +@cindex string, removing alias for (@code{rm}) +@cindex macro, removing alias for (@code{rm}) +@cindex diversion, removing alias for (@code{rm}) +To remove an alias, call @code{rm} on its name. The object itself is +not destroyed until it has no more names. + +When a request, macro, string, or diversion is aliased, redefinitions +and appendments ``write through'' alias names. To replace an alias with +a separately defined object, you must use the @code{rm} request on its +name first. +@endDefreq +@c END Keep (roughly) parallel with section "Strings" of groff(7). + + +@c ===================================================================== + +@node Conditionals and Loops, Writing Macros, Strings, GNU troff Reference +@section Conditionals and Loops +@cindex conditionals and loops +@cindex loops and conditionals + +@code{groff} has @code{if} and @code{while} control structures like +other languages. However, the syntax for grouping multiple input lines +in the branches or bodies of these structures is unusual. + +@menu +* Operators in Conditionals:: +* if-then:: +* if-else:: +* Conditional Blocks:: +* while:: +@end menu + +@c --------------------------------------------------------------------- + +@c BEGIN Keep (roughly) parallel with subsection "Conditional +@c expressions" of groff(7). +@node Operators in Conditionals, if-then, Conditionals and Loops, Conditionals and Loops +@subsection Operators in Conditionals + +@cindex @code{if} request, operators to use with +@cindex @code{ie} request, operators to use with +@cindex @code{while} request, operators to use with +@cindex conditional expressions +@cindex expressions, conditional +In @code{if}, @code{ie}, and @code{while} requests, in addition to the +numeric expressions described in @ref{Numeric Expressions}, several +Boolean operators are available; the members of this expanded class are +termed @dfn{conditional expressions}. + +@table @code +@item c @var{glyph} +True if @var{glyph} is available, where @var{glyph} is an ordinary +character, a special character @samp{\(@var{xx}} or @samp{\[@var{xxx}]}, +@samp{\N'@var{xxx}'}, or has been defined by any of the @code{char}, +@code{fchar}, @code{fschar}, or @code{schar} requests. + +@item d @var{name} +True if a string, macro, diversion, or request called @var{name} exists. + +@item e +True if the current page is even-numbered. + +@item F @var{font} +True if @var{font} exists. @var{font} is handled as if it were opened +with the @code{ft} request (that is, font translation and styles are +applied), without actually mounting it. + +@item m @var{color} +True if @var{color} is defined. + +@item n +@cindex conditional output for terminal (TTY) +@cindex TTY, conditional output for +@cindex terminal, conditional output for +True if the document is being processed in @code{nroff} mode. +@xref{@code{troff} and @code{nroff} Modes}. + +@item o +True if the current page is odd-numbered. + +@item r @var{register} +True if @var{register} exists. + +@item S @var{style} +True if @var{style} is available for the current font family. Font +translation is applied. + +@item t +True if the document is being processed in @code{troff} mode. +@xref{@code{troff} and @code{nroff} Modes}. + +@pindex vtroff +@item v +Always false. This condition is recognized only for compatibility with +certain other @code{troff} implementations.@footnote{This refers to +@code{vtroff}, a translator that would convert the C/A/T output from +early-vintage @acronym{AT&T} @code{troff} to a form suitable for +Versatec and Benson-Varian plotters.} +@end table + +If the first argument to an @code{if}, @code{ie}, or @code{while} +request begins with a non-alphanumeric character apart from @code{!} +(see below); it performs an @slanted{output comparison test}. +@footnote{Strictly, letters not otherwise recognized @emph{are} treated +as output comparison delimiters. For portability, it is wise to avoid +using letters not in the list above; for example, Plan@tie{}9 +@code{troff} uses @samp{h} to test a mode it calls @code{htmlroff}, and +GNU @code{troff} may provide additional operators in the future.} + +@cindex output comparison operator +@table @code +@item @code{'}@var{xxx}@code{'}@var{yyy}@code{'} +True if formatting the comparands @var{xxx} and @var{yyy} produces the +same output commands. The delimiter need not be a neutral apostrophe: +the output comparison operator accepts the same delimiters as most +escape sequences; see @ref{Delimiters}. This @dfn{output comparison +operator} formats @var{xxx} and @var{yyy} in separate environments; +after the comparison, the resulting data are discarded. + +@Example +.ie "|"\fR|\fP" true +.el false + @result{} true +@endExample + +@noindent +The resulting glyph properties, including font family, style, size, and +slant, must match, but not necessarily the requests and/or escape +sequences used to obtain them. In the previous example, @samp{|} and +@samp{\fR|\fP} result in @samp{|} glyphs in the same typefaces at the +same positions, so the comparands are equal. If @samp{.ft@tie{}I} had +been added before the @samp{.ie}, they would differ: the first @samp{|} +would produce an italic @samp{|}, not a roman one. Motions must match +in orientation and magnitude to within the applicable horizontal and +vertical motion quanta of the device, after rounding. @samp{.if +"\u\d"\v'0'"} is false even though both comparands result in zero net +motion, because motions are not interpreted or optimized but sent as-is +to the output.@footnote{Because formatting of the comparands takes place +in a dummy environment, vertical motions within them cannot spring +traps.} On the other hand, @samp{.if "\d"\v'0.5m'"} is true, because +@code{\d} is defined as a downward motion of one-half em.@footnote{All +of this is to say that the lists of output nodes created by formatting +@var{xxx} and @var{yyy} must be identical. @xref{Gtroff Internals}.} + +@cindex string comparison +@cindex comparison of strings +Surround the comparands with @code{\?} to avoid formatting them; this +causes them to be compared character by character, as with string +comparisons in other programming languages. + +@Example +.ie "\?|\?"\?\fR|\fP\?" true +.el false + @result{} false +@endExample + +@cindex @code{\?}, and copy mode +@cindex copy mode, and @code{\?} +@cindex mode, copy, and @code{\?} +@noindent +Since comparands protected with @code{\?} are read in copy mode +(@pxref{Copy Mode}), they need not even be valid @code{groff} syntax. +The escape character is still lexically recognized, however, and +consumes the next character. + +@Example +.ds a \[ +.ds b \[ +.if '\?\*a\?'\?\*b\?' a and b equivalent +.if '\?\\?'\?\\?' backslashes equivalent + @result{} a and b equivalent +@c slack lines for pagination control +@c @error{} warning: missing closing delimiter in +@c @error{} conditional expression (got newline) +@endExample +@end table + +The above operators can't be combined with most others, but a leading +@samp{!}, not followed immediately by spaces or tabs, complements an +expression. + +@Example +.nr x 1 +.ie !r x register x is not defined +.el register x is defined + @result{} register x is defined +@endExample + +Spaces and tabs are optional immediately after the @samp{c}, @samp{d}, +@samp{F}, @samp{m}, @samp{r}, and @samp{S} operators, but right after +@samp{!}, they end the predicate and the conditional evaluates +true.@footnote{This bizarre behavior maintains compatibility with +@acronym{AT&T} @code{troff}.} + +@Example +.nr x 1 +.ie ! r x register x is not defined +.el register x is defined + @result{} r x register x is not defined +@endExample + +@noindent +The unexpected @samp{r x} in the output is a clue that our conditional +was not interpreted as we planned, but matters may not always be so +obvious. +@c END Keep (roughly) parallel with subsection "Conditional expressions" +@c of groff(7). + +@c --------------------------------------------------------------------- + +@node if-then, if-else, Operators in Conditionals, Conditionals and Loops +@subsection if-then +@cindex if-then + +@Defreq {if, cond-expr anything} +Evaluate the conditional expression @var{cond-expr}, and if it evaluates +true (or to a positive value), interpret the remainder of the line +@var{anything} as if it were an input line. Recall from @ref{Invoking +Requests} that any quantity of spaces between arguments to requests +serves only to separate them; leading spaces in @var{anything} are thus +not seen. @var{anything} effectively @emph{cannot} be omitted; if +@var{cond-expr} is true and @var{anything} is empty, the newline at the +end of the control line is interpreted as a blank input line (and +therefore a blank text line). + +@Example +super\c +tanker +.nr force-word-break 1 +super\c +.if ((\n[force-word-break] = 1) & \n[.int]) +tanker + @result{} supertanker super tanker +@endExample +@endDefreq + +@Defreq {nop, anything} +Interpret @var{anything} as if it were an input line. This is similar +to @samp{.if@tie{}1}. @code{nop} is not really ``no operation''; its +argument @emph{is} processed---unconditionally. It can be used to cause +text lines to share indentation with surrounding control lines. + +@Example +.als real-MAC MAC +.de wrapped-MAC +. tm MAC: called with arguments \\$@@ +. nop \\*[real-MAC]\\ +.. +.als MAC wrapped-MAC +\# Later... +.als MAC real-MAC +@endExample + +In the above, we've used aliasing, @code{nop}, and the interpolation of +a macro as a string to interpose a wrapper around the macro @samp{MAC} +(perhaps to debug it). +@endDefreq + +@c --------------------------------------------------------------------- + +@node if-else, while, Operators in Conditionals, Conditionals and Loops +@subsection if-else +@cindex if-else + +@DefreqList {ie, cond-expr anything} +@DefreqListEndx {el, anything} +Use the @code{ie} and @code{el} requests to write an if-then-else. The +first request is the ``if'' part and the latter is the ``else'' part. +Unusually among programming languages, any number of non-conditional +requests may be interposed between the @code{ie} branch and the +@code{el} branch. + +@Example +.nr a 0 +.ie \na a is non-zero. +.nr a +1 +.el a was not positive but is now \na. + @result{} a was not positive but is now 1. +@endExample + +Another way in which @code{el} is an ordinary request is that it does +not lexically ``bind'' more tightly to its @code{ie} counterpart than it +does to any other request. This fact can surprise C programmers. + +@Example +.nr a 1 +.nr z 0 +.ie \nz \ +. ie \na a is true +. el a is false +.el z is false + @error{} warning: unbalanced 'el' request + @result{} a is false +@endExample + +@c Turn the following into a proper @{x,}ref if the conditional blocks +@c node is relocated elsewhere--but consider if it is wise to do so. +To conveniently nest conditionals, keep reading. + +@endDefreq + +@c --------------------------------------------------------------------- + +@node Conditional Blocks, while, Operators in Conditionals, Conditionals and Loops +@subsection Conditional Blocks +@cindex conditional blocks +@cindex blocks, conditional + +It is frequently desirable for a control structure to govern more than +one request, macro call, text line, or a combination of the foregoing. +The opening and closing brace escape sequences @code{\@{} and @code{\@}} +define such groups. These @dfn{conditional blocks} can furthermore be +nested. + +@DefescList {\@\{, , , } +@DefescListEnd {\@\}, , , } +@esindex \@{ +@esindex \@} +@cindex beginning of conditional block (@code{\@{}) +@cindex end of conditional block (@code{\@}}) +@cindex conditional block, beginning (@code{\@{}) +@cindex conditional block, end (@code{\@}}) +@cindex block, conditional, beginning (@code{\@{}) +@cindex block, conditional, end (@code{\@}}) +@cindex brace escape sequences (@code{\@{}, @code{\@}}) +@cindex escape sequences, brace (@code{\@{}, @code{\@}}) +@cindex opening brace escape sequence (@code{\@}}) +@cindex closing brace escape sequence (@code{\@})} +@cindex brace escape sequence, opening (@code{\@})} +@cindex brace escape sequence, closing (@code{\@})} +@code{\@{} begins a conditional block; it must appear (after optional +spaces and tabs) immediately subsequent to the conditional expression of +an @code{if}, @code{ie}, or @code{while} +request,@footnote{@xref{while}.} or as the argument to an @code{el} +request. + +@code{\@}} ends a condition block and should appear on a line with other +occurrences of itself as necessary to match @code{\@{} sequences. It +can be preceded by a control character, spaces, and tabs. Input after +any quantity of @code{\@}} sequences on the same line is processed only +if all of the preceding conditions to which they correspond are true. +Furthermore, a @code{\@}} closing the body of a @code{while} request +must be the last such escape sequence on an input line. + +Brace escape sequences outside of control structures have no meaning and +produce no output. + +@strong{Caution:@:} Input lines using @code{\@{} often end with +@code{\RET}, especially in macros that consist primarily of control +lines. Forgetting to use @code{\RET} on an input line after @code{\@{} +is a common source of error. +@endDefesc + +@need 1000 +We might write the following in a page header macro. If we delete +@code{\RET}, the header will carry an unwanted extra empty line (except +on page@tie{}1). + +@Example +.if (\\n[%] != 1) \@{\ +. ie ((\\n[%] % 2) = 0) .tl \\*[even-numbered-page-title] +. el .tl \\*[odd-numbered-page-title] +.\@} +@endExample + +Let us take a closer look at how conditional blocks nest. + +@Example +A +.if 0 \@{ B +C +D +\@}E +F + @result{} A F +@endExample + +@Example +N +.if 1 \@{ O +. if 0 \@{ P +Q +R\@} S\@} T +U + @result{} N O U +@endExample + +The above behavior may challenge the intuition; it was implemented to +retain compatibility with @acronym{AT&T} @code{troff}. For clarity, it +is idiomatic to end input lines with @code{\@{} (followed by +@code{\@key{RET}} if appropriate), and to precede @code{\@}} on an input +line with nothing more than a control character, spaces, tabs, and other +instances of itself. + +We can use @code{ie}, @code{el}, and conditional blocks to simulate the +multi-way ``switch'' or ``case'' control structures of other languages. +The following example is adapted from the @code{groff} @file{man} +package. Indentation is used to clarify the logic. + +@Example +.\" Simulate switch/case in roff. +. ie '\\$2'1' .ds title General Commands\" +.el \@{.ie '\\$2'2' .ds title System Calls\" +.el \@{.ie '\\$2'3' .ds title Library Functions\" +.el \@{.ie '\\$2'4' .ds title Kernel Interfaces\" +.el \@{.ie '\\$2'5' .ds title File Formats\" +.el \@{.ie '\\$2'6' .ds title Games\" +.el \@{.ie '\\$2'7' .ds title Miscellaneous Information\" +.el \@{.ie '\\$2'8' .ds title System Management\" +.el \@{.ie '\\$2'9' .ds title Kernel Development\" +.el .ds title \" empty +.\@}\@}\@}\@}\@}\@}\@}\@} +@endExample + +@c --------------------------------------------------------------------- + +@node while, , if-else, Conditionals and Loops +@subsection while +@cindex while + +@code{groff} provides a looping construct:@: the @code{while} request. +Its syntax matches the @code{if} request. + +@cindex body, of a while request +@Defreq {while, cond-expr anything} +Evaluate the conditional expression @var{cond-expr}, and repeatedly +execute @var{anything} unless and until @var{cond-expr} evaluates false. +@var{anything}, which is often a conditional block, is referred to as +the @code{while} request's @dfn{body}. + +@Example +.nr a 0 1 +.while (\na < 9) \@{\ +\n+a, +.\@} +\n+a + @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 +@endExample + +@cindex @code{de} request, and @code{while} +GNU @code{troff} treats the body of a @code{while} request similarly to +that of a @code{de} request (albeit one not read in copy +mode@footnote{@xref{Copy Mode}.}), but stores it under an internal name +and deletes it when the loop finishes. The operation of a macro +containing a @code{while} request can slow significantly if the +@code{while} body is large. Each time the macro is executed, the +@code{while} body is parsed and stored again. + +@Example +.de xxx +. nr num 10 +. while (\\n[num] > 0) \@{\ +. \" many lines of code +. nr num -1 +. \@} +.. +@endExample + +@cindex recursive macros +@cindex macros, recursive +@noindent +An often better solution---and one that is more portable, since +@acronym{AT&T} @code{troff} lacked the @code{while} request---is to +instead write a recursive macro. It will be parsed only +once.@footnote{unless you redefine it} + +@Example +.de yyy +. if (\\n[num] > 0) \@{\ +. \" many lines of code +. nr num -1 +. yyy +. \@} +.. +. +.de xxx +. nr num 10 +. yyy +.. +@endExample + +@noindent +To prevent infinite loops, the default number of available recursion +levels is 1,000 or somewhat less.@footnote{``somewhat less'' because +things other than macro calls can be on the input stack} You can +disable this protective measure, or raise the limit, by setting the +@code{slimit} register. @xref{Debugging}. + +As noted above, if a @code{while} body begins with a conditional block, +its closing brace must end an input line. + +@Example +.if 1 \@{\ +. nr a 0 1 +. while (\n[a] < 10) \@{\ +. nop \n+[a] +.\@}\@} + @error{} unbalanced brace escape sequences +@endExample +@endDefreq + +@Defreq {break, } +@cindex @code{while} request, confusing with @code{br} +@cindex @code{break} request, in a @code{while} loop +@cindex @code{continue} request, in a @code{while} loop +Exit a @code{while} loop. Do not confuse this request with a +typographical break or the @code{br} request. +@endDefreq + +@Defreq {continue, } +Skip the remainder of a @code{while} loop's body, immediately starting +the next iteration. +@endDefreq + + +@c ===================================================================== + +@node Writing Macros, Page Motions, Conditionals and Loops, GNU troff Reference +@section Writing Macros +@cindex writing macros +@cindex macros, writing + +A @dfn{macro} is a stored collection of text and control lines that can +be interpolated multiple times. Use macros to define common operations. +Macros are called in the same way that requests are invoked. While +requests exist for the purpose of creating macros, simply calling an +undefined macro, or interpolating it as a string, will cause it to be +defined as empty. @xref{Identifiers}. + +@Defreq {de, name [@Var{end}]} +Define a macro @var{name}, replacing the definition of any existing +request, macro, string, or diversion called @var{name}. If +@var{name} already exists as an alias, the target of the alias is +redefined; recall @ref{Strings}. GNU @code{troff} enters copy +mode,@footnote{@xref{Copy Mode}.} storing subsequent input lines as the +macro definition. If the optional second argument is not specified, the +definition ends with the control line @samp{..} (two dots). +Alternatively, @var{end} identifies a macro whose call syntax at the +start of a control line ends the definition of @var{name}; @var{end} is +then called normally. A macro definition must end in the same +conditional block (if any) in which it began (@pxref{Conditional +Blocks}). Spaces or tabs are permitted after the control character in +the line containing this ending token (either @samp{.} or +@samp{@var{end}}), but a tab immediately after the token prevents its +recognition as the end of a macro definition. The macro @var{end} can +be called with arguments.@footnote{While it is possible to define and +call a macro @samp{.}, you can't use it as an end macro: during a macro +definition, @samp{..} is never handled as calling @samp{.}, even if +@samp{.de @var{name} .} explicitly precedes it.} +@c +@c @Example +@c .de . +@c (dot macro) +@c .. +@c . +@c .. \" This calls macro '.'! +@c .de m1 . +@c (m1 macro) +@c .. \" This does not. +@c .m1 +@c @result{} (dot macro) (m1 macro) +@c @endExample + +Here is a small example macro called @samp{P} that causes a break and +inserts some vertical space. It could be used to separate paragraphs. + +@Example +.de P +. br +. sp .8v +.. +@endExample + +We can define one macro within another. Attempting to nest @samp{..} +naïvely will end the outer definition because the inner definition +isn't interpreted as such until the outer macro is later interpolated. +We can use an end macro instead. Each level of nesting should use a +unique end macro. + +An end macro need not be defined until it is called. This fact enables +a nested macro definition to begin inside one macro and end inside +another. Consider the following example.@footnote{Its structure is +adapted from, and isomorphic to, part of a solution by Tadziu Hoffman to +the problem of reflowing text multiple times to find an optimal +configuration for it. +@uref{https://lists.gnu.org/archive/html/groff/2008-12/msg00006.html}} + +@Example +.de m1 +. de m2 m3 +you +.. +.de m3 +Hello, +Joe. +.. +.de m4 +do +.. +.m1 +know? +. m3 +What +.m4 +.m2 + @result{} Hello, Joe. What do you know? +@endExample + +@noindent +A nested macro definition @emph{can} be terminated with @samp{..} and +nested macros @emph{can} reuse end macros, but these control lines must +be escaped multiple times for each level of nesting. The necessity of +this escaping and the utility of nested macro definitions will become +clearer when we employ macro parameters and consider the behavior of +copy mode in detail. +@endDefreq + +@code{de} defines a macro that inherits the compatibility mode +enablement status of its context (@pxref{Implementation Differences}). +Often it is desirable to make a macro that uses @code{groff} features +callable from contexts where compatibility mode is on; for instance, +when writing extensions to a historical macro package. To achieve this, +compatibility mode needs to be switched off while such a macro is +interpreted---without disturbing that state when it is finished. + +@Defreq {de1, name [@Var{end}]} +The @code{de1} request defines a macro to be interpreted with +compatibility mode disabled. When @var{name} is called, compatibility +mode enablement status is saved; it is restored when the call completes. +Observe the extra backlash before the interpolation of register +@samp{xxx}; we'll explore this subject in @ref{Copy Mode}. + +@Example +.nr xxx 12345 +.de aa +The value of xxx is \\n[xxx]. +. br +.. +.de1 bb +The value of xxx is \\n[xxx]. +.. +.cp 1 +.aa + @error{} warning: register '[' not defined + @result{} The value of xxx is 0xxx]. +.bb + @result{} The value of xxx is 12345. +@endExample +@endDefreq + +@DefreqList {dei, name [@Var{end}]} +@DefreqListEndx {dei1, name [@Var{end}]} +The @code{dei} request defines a macro with its name and end +macro indirected through strings. That is, it interpolates strings +named @var{name} and @var{end} before performing the definition. + +The following examples are equivalent. + +@Example +.ds xx aa +.ds yy bb +.dei xx yy +@endExample + +@Example +.de aa bb +@endExample + +The @code{dei1} request bears the same relationship to @code{dei} as +@code{de1} does to @code{de}; it temporarily turns compatibility mode +off when @var{name} is called. +@endDefreq + +@DefreqList {am, name [@Var{end}]} +@DefreqItemx {am1, name [@Var{end}]} +@DefreqItemx {ami, name [@Var{end}]} +@DefreqListEndx {ami1, name [@Var{end}]} +@cindex appending to a macro (@code{am}) +@cindex macro, appending to (@code{am}) +@code{am} appends subsequent input lines to macro @var{name}, extending +its definition, and otherwise working as @code{de} does. + +To make the previously defined @samp{P} macro set indented instead of +block paragraphs, add the necessary code to the existing macro. + +@Example +.am P +.ti +5n +.. +@endExample + +The other requests are analogous to their @samp{de} counterparts. The +@code{am1} request turns off compatibility mode during interpretation of +the appendment. The @code{ami} request appends indirectly, meaning that +strings @var{name} and @var{end} are interpolated with the resulting +names used before appending. The @code{ami1} request is similar to +@code{ami}, disabling compatibility mode during interpretation of the +appended lines. +@endDefreq + +@pindex trace.tmac +Using @file{trace.tmac}, you can trace calls to @code{de}, +@code{de1}, @code{am}, and @code{am1}. You can also use the +@code{backtrace} request at any point desired to troubleshoot tricky +spots (@pxref{Debugging}). + +@xref{Strings}, for the @code{als}, @code{rm}, and @code{rn} requests to +create an alias of, remove, and rename a macro, respectively. + +@cindex object creation +Macro identifiers share their name space with requests, strings, and +diversions; see @ref{Identifiers}. The @code{am}, @code{as}, @code{da}, +@code{de}, @code{di}, and @code{ds} requests (together with their +variants) create a new object only if the name of the macro, diversion, +or string is currently undefined or if it is defined as a request; +normally, they modify the value of an existing object. @xref{als,,the +description of the @code{als} request}, for pitfalls when redefining a +macro that is aliased. + +@Defreq {return, [@Var{anything}]} +Exit a macro, immediately returning to the caller. If called with an +argument @var{anything}, exit twice---the current macro and the macro +one level higher. This is used to define a wrapper macro for +@code{return} in @file{trace.tmac}. +@endDefreq + +@menu +* Parameters:: +* Copy Mode:: +@end menu + +@c --------------------------------------------------------------------- + +@node Parameters, Copy Mode, Writing Macros, Writing Macros +@subsection Parameters +@cindex parameters + +Macro calls and string interpolations optionally accept a list of +arguments; recall @ref{Calling Macros}. At the time such an +interpolation takes place, these @dfn{parameters} can be examined using +a register and a variety of escape sequences starting with @samp{\$}. +All such escape sequences are interpreted even in copy mode, a fact we +shall motivate and explain below (@pxref{Copy Mode}). + +@Defreg {.$} +@cindex parameter count register (@code{.$}) +The count of parameters available to a macro or string is kept in this +read-only register. The @code{shift} request can change its value. +@endDefreg + +Any individual parameter can be accessed by its position in the list of +arguments to the macro call, numbered from left to right starting at 1, +with one of the following escape sequences. + +@DefescList {\\$, , n, } +@DefescItem {\\$, (, nn, } +@DefescListEnd {\\$, [, nnn, ]} +Interpolate the @var{n}th, @var{nn}th, or @var{nnn}th parameter. The +first form expects only a single digit (1@leq{}@var{n}@leq{}9)), the +second two digits (01@leq{}@var{nn}@leq{}99)), and the third any +positive integer @var{nnn}. Macros and strings accept an unlimited +number of parameters. +@endDefesc + +@Defreq {shift, [@Var{n}]} +Shift the parameters @var{n} places (1@tie{}by default). This is a +``left shift'': what was parameter@tie{}@var{i} becomes parameter +@math{@var{i}-@var{n}}. The parameters formerly in positions 1 +to@tie{}@var{n} are no longer available. Shifting by a non-positive +amount performs no operation. The register @code{.$} is adjusted +accordingly. +@endDefreq + +@cindex copy mode, and macro parameters +@cindex mode, copy, and macro parameters +@cindex macro, parameters (@code{\$}) +@cindex parameters, macro (@code{\$}) +In practice, parameter interpolations are usually seen prefixed with an +extra escape character. This is because the @code{\$} family of escape +sequences is interpreted even in copy mode.@footnote{If they were not, +parameter interpolations would be similar to command-line +parameters---fixed for the entire duration of a @code{roff} program's +run. The advantage of interpolating @code{\$} escape sequences even in +copy mode is that they can interpolate different contents from one call +to the next, like function parameters in a procedural language. The +additional escape character is the price of this power.} + +@DefescList {\\$*, , , } +@DefescItemx {\\$@@, , , } +@DefescListEndx {\\$^, , , } +In some cases it is convenient to interpolate all of the parameters at +once (to pass them to a request, for instance). The @code{\$*} escape +concatenates the parameters, separating them with spaces. @code{\$@@} +is similar, concatenating the parameters, surrounding each with double +quotes and separating them with spaces. If not in compatibility mode, +the interpolation depth of double quotes is preserved (@pxref{Calling +Macros}). @code{\$^} interpolates all parameters as if they were +arguments to the @code{ds} request. + +@Example +.de foo +. tm $1='\\$1' +. tm $2='\\$2' +. tm $*='\\$*' +. tm $@@='\\$@@' +. tm $^='\\$^' +.. +.foo " This is a "test" + @error{} $1=' This is a ' + @error{} $2='test"' + @error{} $*=' This is a test"' + @error{} $@@='" This is a " "test""' + @error{} $^='" This is a "test"' +@endExample + +@code{\$*} is useful when writing a macro that doesn't need to +distinguish its arguments, or even to not interpret them; examples +include macros that produce diagnostic messages by wrapping the +@code{tm} or @code{ab} requests. Use @code{\$@@} when writing a macro +that may need to shift its parameters and/or wrap a macro or request +that finds the count significant. If in doubt, prefer @code{\$@@} to +@code{\$*}. An application of @code{\$^} is seen in @file{trace.tmac}, +which redefines some requests and macros for debugging purposes. +@endDefesc + +@Defesc {\\$0, , , } +@cindex macro name register (@code{\$0}) +@cindex @code{als} request, and @code{\$0} +Interpolate the name by which the macro being interpreted was called. +The @code{als} request can cause a macro to have more than one name. +Applying string interpolation to a macro does not change this name. + +@Example +.de foo +. tm \\$0 +.. +.als bar foo +. +.de aaa +. foo +.. +.de bbb +. bar +.. +.de ccc +\\*[foo]\\ +.. +.de ddd +\\*[bar]\\ +.. +. +.aaa + @error{} foo +.bbb + @error{} bar +.ccc + @error{} ccc +.ddd + @error{} ddd +@endExample +@endDefesc + +@c --------------------------------------------------------------------- + +@node Copy Mode, , Parameters, Writing Macros +@subsection Copy Mode +@cindex copy mode +@cindex copy mode +@cindex mode, copy +@cindex mode, copy + +@cindex @code{\n}, when reading text for a macro +@cindex @code{\$}, when reading text for a macro +@cindex @code{\*}, when reading text for a macro +@cindex \@key{RET}, when reading text for a macro +When GNU @code{troff} processes certain requests, most importantly those +which define or append to a macro or string, it does so in @dfn{copy +mode}: it copies the characters of the definition into a dedicated +storage region, interpolating the escape sequences @code{\n}, @code{\g}, +@code{\$}, @code{\*}, @code{\V}, and @code{\?} normally; interpreting +@code{\@key{RET}} immediately; discarding comments @code{\"} and +@code{\#}; interpolating the current leader, escape, or tab character +with @code{\a}, @code{\e}, and @code{\t}, respectively; and storing all +other escape sequences in an encoded form. + +@cindex interpretation mode +@cindex mode, interpretation +The complement of copy mode---a @code{roff} formatter's behavior when +not defining or appending to a macro, string, or diversion---where all +macros are interpolated, requests invoked, and valid escape sequences +processed immediately upon recognition, can be termed +@dfn{interpretation mode}. + +@Defesc {\\\\, , , } +The escape character, @code{\} by default, can escape itself. This +enables you to control whether a given @code{\n}, @code{\g}, @code{\$}, +@code{\*}, @code{\V}, or @code{\?} escape sequence is interpreted at the +time the macro containing it is defined, or later when the macro is +called.@footnote{Compare this to the @code{\def} and @code{\edef} +commands in @TeX{}.} + +@Example +.nr x 20 +.de y +.nr x 10 +\&\nx +\&\\nx +.. +.y + @result{} 20 10 +@endExample + +You can think of @code{\\} as a ``delayed'' backslash; it is the escape +character followed by a backslash from which the escape character has +removed its special meaning. Consequently, @samp{\\} is not an escape +sequence in the usual sense. In any escape sequence @samp{\@var{X}} +that GNU @code{troff} does not recognize, the escape character is +ignored and @var{X} is output. An unrecognized escape sequence causes +a warning in category @samp{escape}, with two exceptions---@samp{\\} is +the first. +@endDefesc + +@cindex @code{\\}, when reading text for a macro +@Defesc {\\., , , } +@code{\.} escapes the control character. It is similar to @code{\\} in +that it isn't a true escape sequence. It is used to permit nested macro +definitions to end without a named macro call to conclude them. Without +a syntax for escaping the control character, this would not be possible. + +@Example +.de m1 +foo +. +. de m2 +bar +\\.. +. +.. +.m1 +.m2 + @result{} foo bar +@endExample + +@noindent +The first backslash is consumed while the macro is read, and the second +is interpreted when macro @code{m1} is called. +@endDefesc + +@code{roff} documents should not use the @code{\\} or @code{\.} +character sequences outside of copy mode; they serve only to obfuscate +the input. Use @code{\e} to represent the escape character, +@code{\[rs]} to obtain a backslash glyph, and @code{\&} before @samp{.} +and @samp{'} where GNU @code{troff} expects them as control characters +if you mean to use them literally (recall @ref{Requests and Macros}). + +Macro definitions can be nested to arbitrary depth. The mechanics of +parsing the escape character have significant consequences for this +practice. + +@Example +.de M1 +\\$1 +. de M2 +\\\\$1 +. de M3 +\\\\\\\\$1 +\\\\.. +. M3 hand. +\\.. +. M2 of +.. +This understeer is getting +.M1 out + @result{} This understeer is getting out of hand. +@endExample + +Each escape character is interpreted twice---once in copy mode, when the +macro is defined, and once in interpretation mode, when the macro is +called. As seen above, this fact leads to exponential growth in the +quantity of escape characters required to delay interpolation of +@code{\n}, @code{\g}, @code{\$}, @code{\*}, @code{\V}, and @code{\?} at +each nesting level, which can be daunting. GNU @code{troff} offers a +solution. + +@Defesc {\\E, , , } +@code{\E} represents an escape character that is not interpreted in copy +mode. You can use it to ease the writing of nested macro definitions. + +@Example +.de M1 +. nop \E$1 +. de M2 +. nop \E$1 +. de M3 +. nop \E$1 +\\\\.. +. M3 better. +\\.. +. M2 bit +.. +This vehicle handles +.M1 a + @result{} This vehicle handles a bit better. +@endExample + +Observe that because @code{\.} is not a true escape sequence, we can't +use @code{\E} to keep @samp{..} from ending a macro definition +prematurely. If the multiplicity of backslashes complicates +maintenance, use end macros. + +@code{\E} is also convenient to define strings containing escape +sequences that need to work when used in copy mode (for example, as +macro arguments), or which will be interpolated at varying macro nesting +depths. We might define strings to begin and end superscripting +as follows.@footnote{These are lightly adapted from the @code{groff} +implementation of the @file{ms} macros.} + +@Example +.ds @{ \v'-.9m\s'\En[.s]*7u/10u'+.7m' +.ds @} \v'-.7m\s0+.9m' +@endExample + +When the @code{ec} request is used to redefine the escape character, +@code{\E} also makes it easier to distinguish the semantics of an escape +character from the other meaning(s) its character might have. Consider +the use of an unusual escape character, @samp{-}. + +@Example +.nr a 1 +.ec - +.de xx +--na +.. +.xx + @result{} -na +@endExample + +@noindent +This result may surprise you; some people expect @samp{1} to be output +since register @samp{a} has clearly been defined with that value. What +has happened? The robotic replacement of @samp{\} with @samp{-} has led +us astray. You might recognize the sequence @samp{--} more readily with +the default escape character as @samp{\-}, the special character escape +sequence for the minus sign glyph. + +@Example +.nr a 1 +.ec - +.de xx +-Ena +.. +.xx + @result{} 1 +@endExample +@endDefesc + + +@c ===================================================================== + +@node Page Motions, Drawing Geometric Objects, Writing Macros, GNU troff Reference +@section Page Motions +@cindex page motions +@cindex motions, page + +@xref{Manipulating Spacing}, for a discussion of the most commonly used +request for vertical motion, @code{sp}, which spaces downward by one +vee. + +@DefreqList {mk, [@Var{reg}]} +@DefreqListEndx {rt, [@Var{dist}]} +@cindex marking vertical page location (@code{mk}) +@cindex page location, vertical, marking (@code{mk}) +@cindex location, vertical, page, marking (@code{mk}) +@cindex vertical page location, marking (@code{mk}) +@cindex returning to marked vertical page location (@code{rt}) +@cindex page location, vertical, returning to marked (@code{rt}) +@cindex location, vertical, page, returning to marked (@code{rt}) +@cindex vertical page location, returning to marked (@code{rt}) +You can @dfn{mark} a location on a page for subsequent @dfn{return}. +@code{mk} takes an argument, a register name in which to store the +current page location. If given no argument, it stores the location in +an internal register. This location can be used later by the @code{rt} +or the @code{sp} requests (or the @code{\v} escape). + +The @code{rt} request returns @emph{upward} to the location marked with +the last @code{mk} request. If used with an argument, it returns to a +vertical position@tie{}@var{dist} from the top of the page (no previous +call to @code{mk} is necessary in this case). The default scaling +unit is @samp{v}. + +If a page break occurs between a @code{mk} request and its matching +@code{rt} request, the @code{rt} request is silently ignored. + +A simple implementation of a macro to set text in two columns follows. + +@Example +.nr column-length 1.5i +.nr column-gap 4m +.nr bottom-margin 1m +. +.de 2c +. br +. mk +. ll \\n[column-length]u +. wh -\\n[bottom-margin]u 2c-trap +. nr right-side 0 +.. +. +.de 2c-trap +. ie \\n[right-side] \@{\ +. nr right-side 0 +. po -(\\n[column-length]u + \\n[column-gap]u) +. \" remove trap +. wh -\\n[bottom-margin]u +. \@} +. el \@{\ +. \" switch to right side +. nr right-side 1 +. po +(\\n[column-length]u + \\n[column-gap]u) +. rt +. \@} +.. +@endExample + +Now let us apply our two-column macro. + +@Example +.pl 1.5i +.ll 4i +This is a small test that shows how the +rt request works in combination with mk. + +.2c +Starting here, text is typeset in two columns. +Note that this implementation isn't robust +and thus not suited for a real two-column +macro. + @result{} This is a small test that shows how the + @result{} rt request works in combination with mk. + @result{} + @result{} Starting here, isn't robust + @result{} text is typeset and thus not + @result{} in two columns. suited for a + @result{} Note that this real two-column + @result{} implementation macro. +@endExample +@endDefreq + +Several escape sequences enable fine control of movement about the page. + +@Defesc {\\v, @code{'}, expr, @code{'}} +@cindex vertical motion (@code{\v}) +@cindex motion, vertical (@code{\v}) +Vertically move the drawing position. @var{expr} indicates the +magnitude of motion: positive is downward and and negative upward. The +default scaling unit is @samp{v}. The motion is relative to the current +drawing position unless @var{expr} begins with the boundary-relative +motion operator @samp{|}. @xref{Numeric Expressions}. + +Text processing continues at the new drawing position; usually, vertical +motions should be in balanced pairs to avoid a confusing page layout. + +@code{\v} will not spring a vertical position trap. This can be useful; +for example, consider a page bottom trap macro that prints a marker in +the margin to indicate continuation of a footnote. @xref{Traps}. +@endDefesc + +A few escape sequences that produce vertical motion are unusual. They +are thought to originate early in AT&T @code{nroff} history to achieve +super- and subscripting by half-line motions on line printers and +teletypewriters before the phototypesetter made more precise positioning +available. They are reckoned in ems---not vees---to maintain continuity +with their original purpose of moving relative to the size of the type +rather than the distance between text baselines (vees).@footnote{At the +@code{grops} defaults of 10-point type on 12-point vertical spacing, the +difference between half a vee and half an em can be subtle:@: large +spacings like @samp{.vs .5i} make it obvious.} + +@DefescList {\\r, , , } +@DefescItemx {\\u, , , } +@DefescListEndx {\\d, , , } +Move upward@tie{}1@dmn{m}, upward@tie{}.5@dmn{m}, and +downward@tie{}.5@dmn{m}, respectively. +@endDefesc + +@noindent +Let us see these escape sequences in use. + +@Example +Obtain 100 cm\u3\d of \ka\d\092\h'|\nau'\r233\dU. +@endExample + +In the foregoing we have paired @code{\u} and @code{\d} to typeset a +superscript, and later a full em negative (``reverse'') motion to place +a superscript above a subscript. A numeral-width horizontal motion +escape sequence aligns the proton and nucleon numbers, while @code{\k} +marks a horizontal position to which @code{\h} returns so that we could +stack them. (We shall discuss these horizontal motion escape sequences +presently.) In serious applications, we often want to alter the type +size of the -scripts and to fine-tune the vertical motions, as the +@code{groff} @file{ms} package does with its super- and subscripting +string definitions. + +@Defesc {\\h, @code{'}, expr, @code{'}} +@cindex inserting horizontal space (@code{\h}) +@cindex horizontal space (@code{\h}) +@cindex space, horizontal (@code{\h}) +@cindex horizontal motion (@code{\h}) +@cindex motion, horizontal (@code{\h}) +Horizontally move the drawing position. @var{expr} indicates the +magnitude of motion: positive is rightward and negative leftward. The +default scaling unit is @samp{m}. The motion is relative to the current +drawing position unless @var{expr} begins with the boundary-relative +motion operator @samp{|}. @xref{Numeric Expressions}. +@endDefesc + +The following string definition sets the @TeX{} +logo.@footnote{@xref{Strings}, for an explanation of the trailing +@samp{\"}.} + +@Example +.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\" +@endExample + +There are a number of special-case escape sequences for horizontal +motion. + +@Defesc {\\@key{SP}, , , } +@cindex space, unbreakable and unadjustable (@code{\@key{SP}}) +@cindex unbreakable and unadjustable space (@code{\@key{SP}}) +@cindex unadjustable and unbreakable space (@code{\@key{SP}}) +@c We use the following notation in our man pages; Texinfo is bound to +@c the GNU Emacs dialect. +@esindex \@slanted{space} +Move right one word space. (The input is a backslash followed by a +space.) This escape sequence can be thought of as a non-adjustable, +unbreakable space. Usually you want @code{\~} instead; see +@ref{Manipulating Filling and Adjustment}. +@endDefesc + +@cindex thin space (@code{\|}) +@cindex space, thin (@code{\|}) +@Defesc {\\|, , , } +Move one-sixth @dmn{em} to the right on typesetting output devices. If +a glyph named @samp{\|} is defined in the current font, its width is +used instead, even on terminal output devices. +@endDefesc + +@cindex hair space (@code{\^}) +@cindex space, hair (@code{\^}) +@Defesc {\\^, , , } +Move one-twelfth @dmn{em} to the right on typesetting output devices. +If a glyph named @samp{\^} is defined in the current font, its width is +used instead, even on terminal output devices. +@endDefesc + +@Defesc {\\0, , , } +@cindex space, width of a digit (numeral) (@code{\0}) +@cindex digit-width space (@code{\0}) +@cindex figure space (@code{\0}) +@cindex numeral-width space (@code{\0}) +Move right by the width of a numeral in the current font. +@endDefesc + +Horizontal motions are not discarded at the end of an output line as +word spaces are. @xref{Breaking}. + +@DefescList {\\w, @code{'}, anything, @code{'}} +@DefregItemx {st} +@DefregItemx {sb} +@DefregItemx {rst} +@DefregItemx {rsb} +@DefregItemx {ct} +@DefregItemx {ssc} +@DefregListEndx {skw} +@cindex width escape (@code{\w}) +Interpolate the width of @var{anything} in basic units. This escape +sequence allows several properties of formatted output to be measured +without writing it out. + +@Example +The length of the string 'abc' is \w'abc'u. + @result{} The length of the string 'abc' is 72u. +@endExample + +@cindex dummy environment, used by @code{\w} escape sequence +@cindex environment, dummy, used by @code{\w} escape sequence +@var{anything} is processed in a dummy environment:@: this means that +font and type size changes, for example, may occur within it without +affecting subsequent output. + +@need 500 +After each use, @code{\w} sets several registers. + +@cindex CSTR@tie{}#54 errata +@cindex CSTR@tie{}#54 erratum, @code{sb} register +@cindex CSTR@tie{}#54 erratum, @code{st} register +@table @code +@item st +@itemx sb +The maximum vertical displacements of the text baseline above and below, +respectively. The sign convention is opposite that of relative vertical +motions; that is, depth below the (original) baseline is negative. +These registers are incorrectly documented in the @acronym{AT&T} +@code{troff} manual as ``the highest and lowest extent of [the argument +to @code{\w}] relative to the baseline''. + +@item rst +@itemx rsb +Like @code{st} and @code{sb}, but taking account of the heights and +depths of glyphs. In other words, these registers store the highest and +lowest vertical positions attained by @var{anything}, doing what +@acronym{AT&T} @code{troff} documented @code{st} and @code{sb} as doing. + +@item ct +Characterizes the geometry of glyphs occurring in @var{anything}. + +@table @asis +@item 0 +only short glyphs, no descenders or tall glyphs + +@item 1 +at least one descender + +@item 2 +at least one tall glyph + +@item 3 +at least one each of a descender and a tall glyph +@end table + +@item ssc +The amount of horizontal space (possibly negative) that should be added +to the last glyph before a subscript. + +@item skw +How far to right of the center of the last glyph in the @code{\w} +argument, the center of an accent from a roman font should be placed +over that glyph. +@end table +@endDefesc + +@DefescList {\\k, , p, } +@DefescItem {\\k, (, ps, } +@DefescListEnd {\\k, [, position, ]} +@cindex saving horizontal input line position (@code{\k}) +@cindex horizontal input line position, saving (@code{\k}) +@cindex input line position, horizontal, saving (@code{\k}) +@cindex position, horizontal input line, saving (@code{\k}) +@cindex line, input, horizontal position, saving (@code{\k}) +Store the current horizontal position in the @emph{input} line in a +register with the name @var{position} (one-character name@tie{}@var{p}, +two-character name @var{ps}). Use this, for example, to return to the +beginning of a string for highlighting or other decoration. +@endDefesc + +@Defreg {hp} +@cindex horizontal input line position register (@code{hp}) +@cindex input line, horizontal position, register (@code{hp}) +@cindex position, horizontal, in input line, register (@code{hp}) +@cindex line, input, horizontal position, register (@code{hp}) +The current horizontal position at the input line. +@endDefreg + +@Defreg {.k} +@cindex horizontal output line position register (@code{.k}) +@cindex output line, horizontal position, register (@code{.k}) +@cindex position, horizontal, in output line, register (@code{.k}) +@cindex line, output, horizontal position, register (@code{.k}) +A read-only register containing the current horizontal output position +(relative to the current indentation). +@endDefreg + +@Defesc {\\o, @code{'}, abc@dots{}, @code{'}} +@cindex overstriking glyphs (@code{\o}) +@cindex glyphs, overstriking (@code{\o}) +Overstrike the glyphs of characters @var{a}, @var{b}, @var{c}, @dots{}; +the glyphs are centered, written, and the drawing position advanced by +the widest of the glyphs. +@endDefesc + +@Defesc {\\z, , c, } +@cindex zero-width printing (@code{\z}, @code{\Z}) +@cindex printing, zero-width (@code{\z}, @code{\Z}) +Format the character @var{c} with zero width; that is, without advancing +the drawing position. Use @code{\z} to overstrike glyphs aligned to +their left edges, in contrast to @code{\o}'s centering. +@endDefesc + +@Defesc {\\Z, @code{'}, anything, @code{'}} +@cindex zero-width printing (@code{\z}, @code{\Z}) +@cindex printing, zero-width (@code{\z}, @code{\Z}) +Save the drawing position, format @var{anything}, then restore it. Tabs +and leaders in the argument are ignored with an error diagnostic. + +We might implement a strike-through macro thus. + +@Example +.de ST +.nr width \w'\\$1' +\Z@@\v'-.25m'\l'\\n[width]u'@@\\$1 +.. +. +This is +.ST "a test" +an actual emergency! +@endExample +@endDefesc + + +@c ===================================================================== + +@node Drawing Geometric Objects, Traps, Page Motions, GNU troff Reference +@section Drawing Geometric Objects +@cindex drawing requests +@cindex requests for drawing + +A few of the formatter's escape sequences draw lines and other geometric +objects. Combined with each other and with page motion commands +(@pxref{Page Motions}), a wide variety of figures is possible. For +complex drawings, these operations can be cumbersome; the preprocessors +@code{gpic} or @code{ggrn} are typically used instead. + +The @code{\l} and @code{\L} escape sequences draw horizontal and +vertical sequences of glyphs, respectively. Even the simplest of +output devices supports them. + +@DefescList {\\l, @code{'}, l, @code{'}} +@DefescListEnd {\\l, @code{'}, lc, @code{'}} +@cindex drawing horizontal lines (@code{\l}) +@cindex horizontal line, drawing (@code{\l}) +@cindex line, horizontal, drawing (@code{\l}) +Draw a horizontal line of length @var{l} from the drawing position. +Rightward motion is positive. Afterward, the drawing position is at the +right end of the line. The default scaling unit is @samp{m}. + +@cindex baseline rule special character(@code{\[ru]}) +@cindex glyph, underscore (@code{\[ru]}) +@cindex line drawing glyph +@cindex glyph, for line drawing +The optional second parameter@tie{}@var{c} is a character with which to +draw the line. The default is the baseline rule special character, +@code{\[ru]}. + +@cindex dummy character (@code{\&}), effect on @code{\l} escape sequence +@cindex character, dummy (@code{\&}), effect on @code{\l} escape sequence +If @var{c} is a valid scaling unit, put @code{\&} after @var{l} to +disambiguate the input. + +@Example +.de textbox +\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' +.. +@endExample + +@noindent +The foregoing outputs a box rule (a vertical line), the text +argument(s), and another box rule. We employ the boundary-relative +motion operator @samp{|}. Finally, the line-drawing escape sequences +draw a radical extender (a form of overline) and an underline from the +drawing position to the position coresponding to beginning of the +@emph{input} line. The drawing position returns to just after the +right-hand box rule because the lengths of the drawn lines are negative, +as noted above. +@endDefesc + +@DefescList {\\L, @code{'}, l, @code{'}} +@DefescListEnd {\\L, @code{'}, lc, @code{'}} +@cindex drawing vertical lines (@code{\L}) +@cindex vertical line drawing (@code{\L}) +@cindex line, vertical, drawing (@code{\L}) +@cindex line drawing glyph +@cindex glyph for line drawing +@cindex box rule glyph (@code{\[br]}) +@cindex glyph, box rule (@code{\[br]}) +Draw a vertical line of length @var{l} from the drawing position. +Downward motion is positive. The default scaling unit is @samp{v}. The +default character is the box rule, @code{\[br]}. As with vertical +motion escape sequences, text processing continues where the line ends. +@code{\L} is otherwise similar to @code{\l}. + +@Example +$ nroff <