contrib/mom/momdoc/appendices.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3 This file is part of groff, the GNU roff type-setting system.
   4
   5 Copyright (C) 2004-2014  Free Software Foundation, Inc.
   6 Written by Peter Schaffter (peter@schaffter.ca).
   7
   8 Permission is granted to copy, distribute and/or modify this document
   9 under the terms of the GNU Free Documentation License, Version 1.3 or
  10 any later version published by the Free Software Foundation; with the
  11 Invariant Sections being this comment section, with no Front-Cover
  12 Texts, and with no Back-Cover Texts.
  13
  14 A copy of the Free Documentation License is included as a file called
  15 FDL in the main directory of the groff source package.
  16 -->
  17
  18 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  19 <html xmlns="http://www.w3.org/1999/xhtml">
  20
  21 <head>
  22   <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
  23   <title>Mom -- Appendices</title>
  24   <link rel="stylesheet" type="text/css" href="stylesheet.css" />
  25 </head>
  26
  27 <body style="background-color: #f5faff;">
  28
  29 <!-- ==================================================================== -->
  30
  31 <div id="top" class="page">
  32
  33 <!-- Navigation links -->
  34 <table style="width: 100%;">
  35 <tr>
  36   <td><a href="toc.html">Back to Table of Contents</a></td>
  37 </tr>
  38 </table>
  39
  40 <h1 id="appendices" class="docs">Appendices</h1>
  41
  42 <div style="width: 68%; margin: auto;">
  43 <ul class="no-enumerator">
  44   <li><a href="#fonts">Adding fonts to groff</a>
  45   <ul style="margin-left: -.5em; list-style-type: disc">
  46     <li><a href="#extending">Extending groff families / adding new families and fonts</a>
  47     <ul style="margin-left: -.5em; list-style-type: circle">
  48       <li><a href="#traditional">The traditional approach</a></li>
  49       <li><a href="#simpler">The simpler way with mom</a></li>
  50     </ul></li>
  51     <li><a href="#steps">Step-by-step instructions</a></li>
  52     <li><a href="#install-font">Automate the whole process &ndash; the install-font script</a></li>
  53   </ul></li>
  54   <li><a href="#codenotes">Some reflections on mom</a></li>
  55   <li><a href="#contact">Contact the author</a></li>
  56 </ul>
  57 </div>
  58
  59 <div class="rule-medium"><hr/></div>
  60
  61 <h2 id="fonts" class="docs">Adding fonts to groff</h2>
  62
  63 <div id="small-note" class="box-tip">
  64 <p class="tip-top">
  65 <kbd>&lt;prefix&gt;</kbd>, in this section, refers
  66 to the directory in which groff is installed, typically
  67 <br/>
  68 <span class="pre-in-pp">
  69   /usr/share/groff/
  70 </span>
  71 (for distro-specific, pre-compiled groff packages) or
  72 <br/>
  73 <span class="pre-in-pp">
  74   /usr/local/share/groff/
  75 </span>
  76 (if you&#8217;ve built groff from source).
  77 <p class="tip-bottom">
  78 <kbd>&lt;version&gt;</kbd> refers to the groff version number, which
  79 can be found, if necessary, by typing
  80 <br/>
  81 <span class="pre-in-pp">
  82   groff -v
  83 </span>
  84 at the command line.
  85 </p>
  86 </div>
  87
  88 <p>
  89 Groff comes with a small library of
  90 <a href="definitions.html#family">families</a>
  91 (see the
  92 <a href="typesetting.html#family">FAMILY</a>
  93 macro for a list).  The families have four
  94 <a href="definitions.html#font">fonts</a>
  95 associated with them.  These fonts are a combination of
  96 <a href="definitions.html#weight">weight</a>
  97 and
  98 <a href="definitions.html#shape">shape</a>:
  99 <br/>
 100 <span class="pre-in-pp">
 101   R  (Roman, usually Medium weight),
 102   I  (Italic, usually Medium weight),
 103   B  (Bold, usually Roman shape) and
 104   BI (Bold Italic)
 105 </span>
 106 If you work with mom a lot, sooner or later you&#8217;ll find that these
 107 families and their associated fonts aren&#8217;t sufficient.  You&#8217;ll
 108 want to supplement them, either with more fonts for the families
 109 already provided&mdash;<i>Damn!  I need Helvetica Bold Condensed
 110 Italic</i>&mdash;or with entire new families.
 111 </p>
 112
 113 <h3 id="extending" class="docs">Extending groff families / adding new families and fonts</h3>
 114
 115 <h4 id="traditional" class="docs">The traditional approach</h4>
 116
 117 <p>
 118 The traditional approach to extending groff families has been
 119 to create new families for non-default weights and shapes (e.g.
 120 <b>Light</b>, which is a
 121 <a href="definitions.html#weight">weight</a>,
 122 or <b>Condensed</b>, which is a
 123 <a href="definitions.html#shape">shape</a>),
 124 then to associate them with groff&#8217;s predefined <b>R,
 125 I, B</b> and <b>BI</b> font styles.  An example of this
 126 can be seen in the groff PostScript font library itself, which is
 127 found in
 128 </br>
 129 <span class="pre-in-pp">
 130   &lt;prefix&gt;/&lt;version&gt;/font/devps/
 131 </span>
 132 There&#8217;s one &#8220;family&#8221; for Helvetica (<b>HR</b>,
 133 <b>HI</b>, <b>HB</b>, <b>HBI</b>) and another for Helvetica Narrow
 134 (<b>HNR</b>, <b>HNI</b>, <b>HNB</b>, <b>HNBI</b>).
 135 </p>
 136
 137 <p>
 138 The difficulty with this approach is that typographers tend to
 139 think of families as referring to the entire set of font weights
 140 and shapes associated with a family name.  For example, when
 141 a typesetter says &#8220;the Helvetica family&#8221;, s/he is
 142 including the weights Helvetica Thin, Helvetica Light, Helvetica
 143 Regular, Helvetica Bold, Helvetica Heavy, etc, and all their
 144 associated shapes (Roman, Italic, Condensed, Narrow, Extended,
 145 Outline, etc).
 146 </p>
 147
 148 <p>
 149 Thus, intuitively, when a typesetter gives mom a
 150 <kbd>.FAMILY&nbsp;H</kbd> directive, s/he reasonably expects that
 151 any subsequent <kbd>.FT</kbd> directive will access the desired font
 152 from the Helvetica family&mdash;without the need to state explicitly
 153 both family and font to <kbd>.FT</kbd>, as it is explained one can
 154 do in the
 155 <a href="typesetting.html#family">FAMILY</a>
 156 and
 157 <a href="typesetting.html#font">FT</a>
 158 sections of these documents.
 159 </p>
 160
 161 <p>
 162 If one had, say, Helvetica Light Roman and Helvetica Light Italic
 163 as well as Helvetica Light Condensed Roman and Helvetica Light
 164 Condensed Italic, the established groff approach would require two
 165 &#8220;partial&#8221; families, <b>HL</b> (for Helvetica Light)
 166 and <b>HLCD</b> (for Helvetica Light Condensed), with <b>R</b> and
 167 <b>I</b> fonts for both:
 168 </br>
 169 <span class="pre-in-pp">
 170   HLR
 171   HLI
 172   HLCDR
 173   HLCDI
 174 </span>
 175 Accessing these family/font combos routinely
 176 throughout a document would then require changing the family
 177 (with <kbd>.FAMILY</kbd>) and selecting the desired font
 178 (with <kbd>.FT&nbsp;R</kbd> or <kbd>.FT&nbsp;I</kbd>), or
 179 passing <kbd>.FT</kbd> the lengthy family+fontname (.e.g.
 180 <kbd>.FT&nbsp;HLCDI</kbd>).
 181 </p>
 182
 183 <h4 id="simpler" class="docs">The simpler way with mom</h4>
 184
 185 <p>
 186 Fortunately, groff provides a mechanism whereby it&#8217;s possible
 187 to extend the basic <b>R</b>, <b>I</b>, <b>B</b> and <b>BI</b> fonts
 188 (&#8220;styles&#8221; in groff-speak) so that one can, in fact,
 189 create extensive type families, and access all the fonts in them
 190 with <kbd>.ft</kbd> (groff) or <kbd>.FT</kbd> (mom).
 191 </p>
 192
 193 <p>
 194 Mom uses this mechanism to offer, in addition to groff&#8217;s
 195 default font styles, the following:
 196 </p>
 197
 198 <div class="examples-container" style="padding-bottom: 1em;">
 199 <div id="style-extensions" style="width: 50%; float: left;">
 200 <span class="pre" style="font-size: 85%">
 201 UL     =  Ultra Light
 202 ULI    =  Ultra Light Italic
 203 ULCD   =  Ultra Light Condensed
 204 ULCDI  =  Ultra Light Condensed Italic
 205 ULEX   =  Ultra Light Extended
 206 ULEXI  =  Ultra Light Extended Italic
 207
 208 XL     =  Extra Light
 209 XLI    =  Extra Light Italic
 210 XLCD   =  Extra Light Condensed
 211 XLCDI  =  Extra Light Condensed Italic
 212 XLEX   =  Extra Light Extended
 213 XLEXI  =  Extra Light Extended Italic
 214
 215 TH     =  Thin
 216 THI    =  Thin Italic
 217 THCD   =  Thin Condensed
 218 THCDI  =  Thin Condensed Italic
 219 THEX   =  Thin Extended
 220 THEXI  =  Thin Extended Italic
 221
 222 L      =  Light Roman
 223 LI     =  Light Italic
 224 LCD    =  Light Condensed
 225 LCDI   =  Light Condensed Italic
 226 LEX    =  Light Extended
 227 LEXI   =  Light Extended Italic
 228
 229 BK     =  Book Roman
 230 BKI    =  Book Italic
 231 BKCD   =  Book Condensed
 232 BKCDI  =  Book Condensed Italic
 233 BKEX   =  Book Extended
 234 BKEXI  =  Book Extended Italic
 235
 236 CD     =  Medium Condensed
 237 CDI    =  Medium Condensed Italic
 238 EX     =  Medium Extended
 239 EXI    =  Medium Extended Italic
 240
 241 DB     =  DemiBold Roman
 242 DBI    =  DemiBold Italic
 243 DBCD   =  DemiBold Condensed
 244 DBCDI  =  DemiBold Condensed Italic
 245 DBEX   =  DemiBold Extended
 246 DBEXI  =  DemiBold Extended Italic
 247
 248 SB     =  SemiBold Roman
 249 SBI    =  SemiBold Italic
 250 SBCD   =  SemiBold Condensed
 251 SBCDI  =  SemiBold Condensed Italic
 252 SBEX   =  SemiBold Extended
 253 SBEXI  =  SemiBold Extended Italic
 254 </span>
 255 </div>
 256 <span class="pre" style="font-size: 85%">
 257 BCD    =  Bold Condensed
 258 BCDI   =  Bold Condensed Italic
 259 BEX    =  Bold Extended
 260 BEXI   =  Bold Extended Italic
 261 BO     =  Bold Outline
 262
 263 XB     =  Extra Bold
 264 XBI    =  Extra Bold Italic
 265 XBCD   =  Extra Bold Condensed
 266 XBCDI  =  Extra Bold Condensed Italic
 267 XBEX   =  Extra Bold Extended
 268 XBEXI  =  Extra Bold Extended Italic
 269
 270 UB     =  Ultra Bold
 271 UBI    =  Ultra Bold Italic
 272 UBCD   =  Ultra Bold Condensed
 273 UBCDI  =  Ultra Bold Condensed Italic
 274 UBEX   =  Ultra Bold Extended
 275 UBEXI  =  Ultra Bold Extended Italic
 276
 277 HV     =  Heavy
 278 HVI    =  Heavy Italic
 279 HVCD   =  Heavy Condensed
 280 HVCDI  =  Heavy Condensed Italic
 281 HVEX   =  Heavy Extended
 282 HVEXI  =  Heavy Extended Italic
 283
 284 BL     =  Black
 285 BLI    =  Black Italic
 286 BLCD   =  Black Condensed
 287 BLCDI  =  Black Condensed Italic
 288 BLEX   =  Black Extended
 289 BLEXI  =  Black Extended Italic
 290 BLO    =  Black Outline
 291
 292 XBL    =  Extra Black
 293 XBLI   =  Extra Black Italic
 294 XBLCD  =  Extra Black
 295 XBLCDI =  Extra Black
 296 XBLEX  =  Extra Black Italic
 297 XBLEXI =  Extra Black Italic
 298
 299 UBL    =  Ultra Black
 300 UBLI   =  Ultra Black Italic
 301 UBLCD  =  Ultra Black Condensed
 302 UBLCDI =  Ultra Black Condensed Italic
 303 UBLEX  =  Ultra Black Exteneded
 304 UBLEXI =  Ultra Black Extended Italic
 305
 306 SC     =  Small Caps Roman
 307 SCI    =  Small Caps Italic
 308 SCDB   =  Small Caps Demibold
 309 SCDBI  =  Small Caps Demibold Italic
 310 SCSB   =  Small Caps Semibold
 311 SCSBI  =  Small Caps Semibold Italic
 312 </span>
 313 </div>
 314
 315 <p style="clear: both;">
 316 Thus, with mom, if you&#8217;ve installed some extra
 317 Helvetica fonts and named them according to the convention
 318 <kbd>&lt;F&gt;&lt;S&gt;</kbd> (where <kbd>&lt;F&gt;</kbd> means
 319 family and <kbd>&lt;S&gt;</kbd> means font style), once having
 320 entered
 321 <br/>
 322 <span class="pre-in-pp" style="margin-bottom: -1em;">
 323   .FAMILY H
 324 </span>
 325 you can access any of the extra Helvetica fonts simply by passing
 326 the correct argument to
 327 <a href="typesetting.html#font">FT</a>
 328 from the list, above.  For example, if you were working in Medium
 329 Roman (<kbd>.FT&nbsp;R</kbd>) and you needed Medium Condensed Italic
 330 for a while (assuming it&#8217;s installed), you&#8217;d just type
 331 <br/>
 332 <span class="pre-in-pp" style="margin-bottom: -1em;">
 333   .FT CDI
 334 </span>
 335 to access the Medium Condensed Italic font from the Helvetica
 336 family.
 337 </p>
 338
 339 <p>
 340 Mom&#8217;s list of font styles doesn&#8217;t pretend to be
 341 exhaustive.  The extension names are arbitrary and can be used in a
 342 flexible manner.  For example, if you create a family that has a
 343 Demibold font (<b>DB</b>) but no Bold font (<b>B</b>), you might
 344 find it more convenient to give the Demibold font the extension
 345 &#8220;<b>B</b>&#8221;.
 346 </p>
 347
 348 <p id="register-style">
 349 You may, at needs, want to add to mom&#8217;s list of font styles.
 350 You can do this by editing the file, om.tmac (typical location:
 351 <kbd>&lt;prefix&gt;/&lt;version&gt;/tmac/om.tmac</kbd>).  Near the
 352 top, you&#8217;ll see lines of the form
 353 <br/>
 354 <span class="pre-in-pp">
 355   .sty \n[.fp] XL      \" Extra Light
 356   .sty \n[.fp] L       \" Light Roman
 357   .sty \n[.fp] LI      \" Light Italic
 358   .sty \n[.fp] LCD     \" Light Condensed Roman
 359 </span>
 360 Simply add your new font style by imitating what you see, above,
 361 and plugging in your new font style (having, of course,
 362 added the font to groff, correctly named).
 363 directory; see
 364 <a href="#steps">Step-by-step instructions</a>).
 365 </p>
 366
 367 <p>
 368 For example, if you already have some fonts from the Univers family
 369 installed and have called the family <b>Univers</b>, you might decide at
 370 some point to add the Bold Outline font (<b>UniversBO</b>).  In which
 371 case, you&#8217;d add
 372 <br/>
 373 <span class="pre-in-pp">
 374   .sty \n[.fp] BO      \" Bold Outline
 375 </span>
 376 to the <kbd>.sty&nbsp;\n[.fp]&nbsp; &lt;font style&gt;</kbd> list
 377 in om.tmac.
 378 </p>
 379
 380 <div class="box-tip">
 381 <p class="tip">
 382 <span class="note">Note:</span>
 383 Mom&#8217;s font extensions are not &#8220;user-space&#8221;
 384 controllable via a macro.  If you&#8217;ve been using groff for
 385 a long time, and have already rolled your own solution to adding
 386 families and fonts to groff, you may find that mom&#8217;s font
 387 extensions conflict with your own scheme.  Should that be the case,
 388 comment out the <kbd>.sty&nbsp;\n[.fp] &lt;font style&gt;</kbd>
 389 lines found near the top of the <kbd>om.tmac</kbd> file.
 390 </p>
 391 </div>
 392
 393 <div class="box-important">
 394 <p class="tip">
 395 <span class="important">Important:</span>
 396 Be careful that any styles you add do not conflict with
 397 <i>family</i> names that already exist.  &#8220;<b>C</b>&#8221;,
 398 for example, conflicts with the Courier family (<b>CR</b>,
 399 <b>CI</b>, <b>CB</b>, <b>CI</b>).  Were you to create a font
 400 style &#8220;<b>C</b>&#8221;, thinking that <kbd>.FT&nbsp;C</kbd>
 401 would give you access to font style once you&#8217;d given a
 402 <kbd>.FAMILY</kbd> directive, you&#8217;d get a nasty surprise:
 403 your type would come out in Courier Roman!
 404 </p>
 405 </div>
 406
 407 <div class="rule-medium"><hr/></div>
 408
 409 <h2 id="steps" class="docs">Step-by-step instructions</h2>
 410
 411 <div>
 412 <ul class="no-enumerator" style="margin-left: -1.5em;">
 413   <li><a href="#need">What you need before you start</a></li>
 414   <li><a href="#preparation">Initial preparation</a></li>
 415   <li><a href="#step-1">1. Acquire the font</a></li>
 416   <li><a href="#step-2">2. Prepare to convert the font to the correct format</a>
 417   <ul style="margin-left: -.5em">
 418     <li><a href="#ttf">TTF fonts</a></li>
 419     <li><a href="#type1">Type 1 fonts</a></li>
 420   </ul></li>
 421   <li><a href="#step-3">3. Convert the font and put it in the right place</a></li>
 422   <li><a href="#step-4">4. Update the download file</a>
 423   <ul style="margin-left: -.5em">
 424     <li><a href="#internal">Get the internal font name</a></li>
 425     <li><a href="#add">Add the font to the download file</a></li>
 426     <li><a href="#gropdf-download">Updating the gropdf download file</a></li>
 427   </ul></li>
 428   <li><a href="#groff-font-names">Naming groff fonts</a>
 429   <li><a href="#install-font">Automate the whole process &ndash; the install-font script</a>
 430   </ul></li>
 431 </ul>
 432 </div>
 433
 434
 435 <p>
 436 There are a number of ways to approach making fonts available
 437 to groff.  These instructions aren&#8217;t meant to cover all
 438 possibilities, merely one.
 439 </p>
 440
 441 <p>
 442 GNU/Linux distributions being what they are, directory locations
 443 may differ and the presence of some executables can&#8217;t be
 444 guaranteed.  I run a Debian-based system.  The instructions reflect
 445 that.  Users of other distros may have to interpret them according
 446 to the way their distro operates.
 447 </p>
 448
 449 <h3 id="need" class="docs appendices">What you need before you start</h3>
 450
 451 <ul style="margin-top: 1em; margin-left: -.5em;">
 452   <li>groff, version 1.18 or higher<br/>
 453       (Debian package: groff)
 454   </li>
 455   <li>ghostscript<br/>
 456       (Debian package: ghostscript or ghostscript-x)
 457   </li>
 458   <li>fontforge<br/>
 459       (Debian package: fontforge)
 460   </li>
 461 </ul>
 462
 463 <h3 id="preparation" class="docs appendices">Initial preparation (you only need do this once)</h3>
 464
 465 <ol id="site-font" style="margin-left: -1em;">
 466   <li>
 467     Locate the groff directory,
 468     <kbd>site-font</kbd>.  The exact location is
 469     difficult to predict, owing to differences between distros and
 470     whether you&#8217;re using a pre-packaged groff or have built
 471     it from source.  Some typical locations are:
 472     <br/>
 473     <span class="pre-in-pp" style="margin-bottom: -2em;">
 474       /usr/share/groff/
 475       /usr/local/share/groff/
 476       /etc/groff/
 477     </span>
 478     If you can&#8217;t find the site-font directory, locate
 479     groff&#8217;s <kbd>site-tmac</kbd> directory, and, as root,
 480     create site-font in the same directory.  Eg, if you find
 481     site-tmac in <kbd>/usr/share/groff/</kbd>, create site-font in
 482     <kbd>/usr/share/groff/</kbd>
 483     <br/>
 484     <span class="pre-in-pp" style="margin-bottom: -2em;">
 485       sudo mkdir site-font
 486     </span>
 487   </li>
 488   <li>
 489     Create two files, generate-t42.pe and generate-pfa.pe,
 490     as you see them below.  Place them in a convenient and
 491     easily-remembered location, like your home directory.
 492     <br/>
 493     <span class="examples" style="font-size: 95%; display: block; margin-top: .5em;">generate-t42.pe</span>
 494
 495     <div class="examples-container" style="margin-top: 0; margin-bottom: -1em; padding-bottom: 1em;">
 496 <span class="pre">
 497 # generate-t42.pe
 498
 499 Open($1);
 500 Generate($fontname + ".pfa");
 501 Generate($fontname + ".t42");
 502 </span>
 503     </div>
 504     <br/>
 505     <span class="examples" style="font-size: 95%; display: block; margin-top: .5em;">generate-pfa.pe</span>
 506     <div class="examples-container" style="margin-top: 0; padding-bottom: 1em;">
 507 <span class="pre">
 508 # generate-pfa.pe
 509
 510 Open($1);
 511 Generate($fontname + ".pfa");
 512 </span>
 513     </div>
 514   </li>
 515 </ol>
 516
 517 <h3 id="step-1" class="docs appendices">Step 1: Acquire the font</h3>
 518
 519 <p class="top">
 520 The two most commonly available types of fonts are PostScript Type1
 521 (extension .pfb) and TrueType (extension .ttf).  Either can be made
 522 available to groff.  There are many websites holding collections of
 523 both.
 524 </p>
 525
 526 <h3 id="step-2" class="docs appendices">Step 2: Prepare to convert the font to the correct format</h3>
 527
 528 <p class="top">
 529 Change into the directory holding the new font.
 530 </p>
 531
 532 <p>
 533 For convenience in the next step, make a symbolic link to
 534 the file 'textmap':
 535 <br/>
 536 <span class="pre-in-pp">
 537   ln -s &lt;prefix&gt;/&lt;version&gt;/font/devps/generate/textmap .
 538 </span>
 539 See
 540 <a href="#small-note">here</a>
 541 for an explanation of &lt;prefix&gt;
 542 and &lt;version&gt;.
 543 </p>
 544
 545 <p>
 546 In addition, unless you're installing fonts from your home
 547 directory, make links to the files 'generate-t42.pe' and
 548 'generate-pfa.pe'.
 549 <br/>
 550 <span class="pre-in-pp">
 551   ln -s $HOME/generate-t42.pe .
 552   ln -s $HOME/generate-pfa.pe .
 553 </p>
 554
 555 <h3 id="step-3" class="docs appendices">Step 3: Convert the font and put it in the right place</h3>
 556
 557 <p class="top">
 558 TrueType fonts (.ttf) need to be converted to .t42.  Type 1 fonts
 559 (.pfb) need to be converted to .pfa.
 560 </p>
 561
 562 <h4 id="ttf" class="docs" style="font-size: 90%; text-transform: uppercase;">&nbsp;&bullet;&nbsp;TTF Fonts</h4>
 563
 564 <p class="top" style="margin-top: .5em;">
 565 For .ttf fonts, run
 566 <br/>
 567 <span class="pre-in-pp">
 568   fontforge -script generate-t42.pe &lt;file&gt;.ttf
 569 </span>
 570 This will create three new files with the extensions .t42, .pfa, and
 571 .afm.  Next, run
 572 <br/>
 573 <span class="pre-in-pp">
 574   afmtodit &lt;afm file&gt; textmap &lt;groff font&gt;
 575 </span>
 576 This will create a groff font with the name you give.  (See
 577 <a href="#groff-font-names">here</a>
 578 for advice on naming groff fonts.)
 579 </p>
 580
 581 <p>
 582 Move the .t42 and groff font files to
 583 <kbd>&lt;prefix&gt;/site-font/devps/</kbd>.
 584 </p>
 585
 586 <p>
 587 If you're running a recent version of groff that includes
 588 the native pdf device (gropdf), move the .pfa file to
 589 <kbd>&lt;prefix&gt;/&lt;version&gt;/font/devpdf/</kbd>.  If not, you
 590 may safely remove it.  You may also safely remove the .afm file.
 591 </p>
 592
 593 <h4 id="type1" class="docs" style="font-size: 90%; text-transform: uppercase;">&nbsp;&bullet;&nbsp;Type1 Fonts</h4>
 594
 595 <p class="top" style="margin-top: .5em;">
 596 For .pfb fonts, run
 597 <br/>
 598 <span class="pre-in-pp">
 599   fontforge -script generate-pfa.pe &lt;file&gt;.ttf
 600 </span>
 601 This will create two new files with the extensions .pfa, and .afm.
 602 Next, run
 603 <br/>
 604 <span class="pre-in-pp">
 605   afmtodit &lt;afm file&gt; textmap &lt;groff font&gt;
 606 </span>
 607 Move the .pfa and groff font files to
 608 <kbd>&lt;prefix&gt;/&lt;site-font&gt;/devps/</kbd>.
 609 (See
 610 <a href="#groff-font-names">here</a>
 611 for advice on naming groff fonts.)
 612 </p>
 613
 614 <p>
 615 If you're running a recent version of groff that includes the
 616 native pdf device (gropdf), link the .pfa and groff font files,
 617 now in <kbd>&lt;prefix&gt;/&lt;site-font&gt;/devps/</kbd>,
 618 to the devpdf directory</kbd>.  Start by changing into the
 619 <kbd>&lt;prefix&gt;/&lt;version&gt;/font/devpdf/</kbd> directory,
 620 then:
 621 <br/>
 622 <span class="pre-in-pp">
 623   ln -s &lt;prefix&gt;/&lt;version&gt;/font/devps/&lt;file&gt;.pfa .
 624   ln -s &lt;prefix&gt;/&lt;version&gt;/font/devps/&lt;groff font&gt; .
 625 </span>
 626 You may safely remove the .afm file.
 627 </p>
 628
 629 <h3 id="step-4" class="docs appendices">Step 4: Update the download file</h3>
 630
 631 <h4 id="internal" class="docs" style="font-size: 90%; text-transform: uppercase;">&nbsp;&bullet;&nbsp;Get the internal font name</h4>
 632
 633 <p class="top" style="margin-top: .5em;">
 634 Inspect your new groff font file.  Near the top, you will see a line
 635 of the form
 636 <br/>
 637 <span class="pre-in-pp">
 638   internalname &lt;name&gt;
 639 </span>
 640 Usually, the internal name is helpfully descriptive, eg,
 641 <br/>
 642 <span class="pre-in-pp">
 643   internalname Optima-Bold
 644 </span>
 645 Make a note of the internal name.
 646 </p>
 647
 648 <h4 id="add" class="docs" style="font-size: 90%; text-transform: uppercase;">&nbsp;&bullet;&nbsp;Add the font to the download file</h4>
 649
 650 <p class="top" style="margin-top: .5em;">
 651 Open the file <kbd>&lt;prefix&gt;/&lt;version&gt;/font/devps/download</kbd>.
 652 In it you will see lines of the form
 653 <br/>
 654 <span class="pre-in-pp">
 655   Symbol-Slanted       symbolsl.pfa
 656   ZapfDingbats-Reverse zapfdr.pfa
 657   FreeEuro             freeeuro.pfa
 658 </span>
 659 where the spaces are the tab character from the keyboard, not
 660 literal spaces.  Thus,
 661 <br/>
 662 <span class="pre-in-pp">
 663   Symbol-Slanted       symbolsl.pfa
 664 </span>
 665 is really
 666 <br/>
 667 <span class="pre-in-pp">
 668   Symbol-Slanted&lt;tab&gt;symbolsl.pfa
 669 </span>
 670 </p>
 671
 672 <p>
 673 The download file maps the internal names used by groff to the
 674 actual fonts.  To add your new font to the download file, append a
 675 line containing the internal name, followed by a tab (make sure your
 676 text editor is inserting the tab character, not spaces), followed by
 677 the .t42 or .pfa font to which the internal name refers.
 678 </p>
 679
 680 <p>
 681 For example, if the internal name is Optima-Bold and the font is a
 682 .pfa file called Optima-Bold.pfa, your updated download file will
 683 contain
 684 <br/>
 685 <span class="pre-in-pp">
 686   Optima-Bold&lt;tab&gt;Optima-Bold.pfa
 687 </span>
 688 </p>
 689
 690 <h4 id="gropdf-download" class="docs" style="font-size: 90%; text-transform: uppercase;">&nbsp;&bullet;&nbsp;Updating the gropdf download file</h4>
 691
 692 <p class="top" style="margin-top: .5em;">
 693 If you're running a recent version of groff that includes the
 694 native pdf device (gropdf), you must update its download file as
 695 well, which is found in <kbd>&lt;prefix&gt;/&lt;version&gt;/font/devpdf/</kbd>.
 696 The instructions are identical to those above, but with one important
 697 difference: all lines must begin with a tab character.  Thus, using
 698 our Optima example, your devpdf download line for the same font is
 699 <br/>
 700 <span class="pre-in-pp">
 701   &lt;tab&gt;Optima-Bold&lt;tab&gt;Optima-Bold.pfa
 702 </span>
 703 </p>
 704
 705 <h3 id="groff-font-names" class="docs appendices">Naming groff fonts</h3>
 706
 707 <p class="top">
 708 For convenience when using mom, and to keep your font collection
 709 organized, choose meaningful groff font names following the scheme
 710 &lt;Family&gt;&lt;FONT&gt;, where Family is something
 711 like Optima or Univers or Clarendon, and FONT is either
 712 <br/>
 713 <span style="display: block; margin-left: 2em;">
 714 <kbd>R&nbsp;&nbsp;</kbd>(roman/regular)
 715 <br/>
 716 <kbd>I&nbsp;&nbsp;</kbd>(italic)
 717 <br/>
 718 <kbd>B&nbsp;&nbsp;</kbd>(bold)
 719 <br/>
 720 <kbd>BI&nbsp;</kbd>(bold italic)
 721 </span>
 722 or one of the 1&ndash;5 character fontstyles listed
 723 <a href="#style-extensions">here</a>.
 724 Thus, for the fonts Optima Light Italic and Optima Extra Black, your font names would be
 725 <br/>
 726 <span class="pre-in-pp">
 727   OptimaLI
 728   OptimaXBL
 729 </span>
 730 This scheme allows you to enter <kbd>.FAMILY&nbsp;Optima</kbd> to make
 731 Optima the current family, and <kbd>.FT&nbsp;LI</kbd> or <kbd>.FT&nbsp;XBL</kbd>
 732 when you need the fonts Light Italic or Extra Black.
 733 </p>
 734
 735 <p>
 736 Groff font names are, in fact, arbitrary; you can call your fonts
 737 anything you like, provided the
 738 <a href="#internal">internal name</a>
 739 in the
 740 <a href="#add">download file</a>
 741 matches the internal name found in the groff font file.  When
 742 calling a font that does not follow the recommended naming convention,
 743 you must pass the full font name to <kbd>.FT</kbd> whenever you wish
 744 to use it.
 745 </p>
 746
 747 <p>
 748 For example, the font, Goudy Stout, isn't really part of the
 749 Goudy family, and while "stout" describes it, Stout is not a
 750 recognized font style.  Therefore, its groff name could simply be
 751 GoudyStout, and whenever you needed it, you could call it with
 752 <kbd>.FT&nbsp;GoudyStout</kbd>.
 753 </p>
 754
 755 <h3 id="install-font" class="docs appendices">Automate the whole process &ndash; the install-font script</h3>
 756
 757 <p>
 758 A bash script to make the entire process of installing fonts a
 759 painless no-brainer has been posted online at
 760 <a href="http://www.schaffter.ca/mom/install-font">http://www.schaffter.ca/mom/install-font</a>.
 761 Be sure to make the script executable
 762 (<kbd>chmod 755 install-font</kbd>)
 763 after you download it, then type <kbd>./install-font -H</kbd> for
 764 usage.
 765 </p>
 766
 767 <div class="rule-medium" style="margin-top: 2em;"><hr/></div>
 768
 769 <!-- ===================================================================== -->
 770
 771 <h2 id="codenotes" class="docs">Some reflections on mom</h2>
 772
 773 <p>
 774 If, as Eric Raymond asserts, open source begins with a programmer
 775 scratching a personal itch, then mom can truly be called open
 776 source.
 777 </p>
 778
 779 <p>
 780 Mom had her origins in a library of groff routines I wrote over
 781 the years to handle various aspects of typesetting and document
 782 processing that weren&#8217;t adequately covered by ms, me, mm, and
 783 friends.  Typically, I&#8217;d use the library to cobble together
 784 macro sets for new challenges as they came my way.
 785 </p>
 786
 787 <p>
 788 As a writer living in a perpetual state of penury, all the computers
 789 I&#8217;ve ever owned have been hand-me-downs&mdash;several
 790 generations out-of-date and resource challenged.  Disk space has
 791 always been an issue, as has processor speed and available RAM.  One
 792 of the reasons I run GNU/Linux rather than the offering from Redmond
 793 is that it has helped enormously to get the most out of my poor
 794 little boxes.
 795 </p>
 796
 797 <p>
 798 In Linux-land (all Unix variants, in fact), the choice of
 799 typesetting systems basically comes down to groff or TeX.  Both are
 800 wonderful&mdash;monumental achievements if you ask me&mdash;and both
 801 have their own particular strengths.  However, for people in my
 802 financial position (and there are millions of us around the globe,
 803 in both developed and developing countries), TeX and groff have one
 804 big difference: size.  TeX is huge.  Even its most ardent supporters
 805 agree it suffers from bloat, on top of being complex and unwieldy to
 806 manage.  Groff is tiny by comparison, occupying minimal disk space
 807 and having only a small memory footprint while at the same time
 808 being flexible and powerful, typographically speaking.  Back in the
 809 Jurassic Period, I ran it successfully on a 386 with 8 megs of RAM
 810 and a 250 meg hard disk.
 811 </p>
 812
 813 <p>
 814 However, groff has always had a liability: it&#8217;s incredibly geeky.
 815 Owing to its very long history, it&mdash;and its power users
 816 &mdash;seem to have remained stuck in a time warp.  The canonical  macro packages
 817 still look as they did back in those decades when memory was exorbitantly
 818 expensive and every byte mattered.
 819 </p>
 820
 821 <p>
 822 For some time now, groff users and macro writers have had the option
 823 to use &#8220;long&#8221; names for macros (i.e. longer than two
 824 letters, the original limit), yet have mostly chosen not to.  With
 825 long names, it&#8217;s possible to create macro sets that are
 826 humanly readable and easy to interpret, encouraging development and
 827 evolution.  What&#8217;s more, the macros themselves need not be
 828 terse, intimidating, and easily forgotten 1- or 2-letter commands
 829 inserted in the body of a document.  They can be sensible and
 830 helpful to everyone, groff newbies and old hands alike.
 831 </p>
 832
 833 <p>
 834 Mom&#8217;s macro file, om.tmac, uses long names, aliases, and a
 835 host of other groff goodies that have become part of the whole
 836 groff picture under the unflagging guidance of groff&#8217;s
 837 current maintainer, Werner Lemberg.  The function of nearly
 838 every macro, number register and string can be infered simply
 839 from its name.  The file is heavily commented.  A consistent, if
 840 idiosyncratic, indenting style is used as well, significantly
 841 improving readability.  Anyone wanting to futz around with
 842 mom&#8217;s macros should be able to do so with a minimum of head
 843 scratching.
 844 </p>
 845
 846 <div class="box-tip">
 847 <p class="tip">
 848 <span class="note">Note:</span>
 849 The main macro file, <strong>om.tmac</strong>, is stripped of
 850 comments when groff is built from sources. <strong>om.tmac</strong>,
 851 in the sources themselves, still contains the comments, as do the
 852 tarballs posted on mom&#8217;s homepage.
 853 </p>
 854 </div>
 855
 856 <div class="rule-medium"><hr/></div>
 857
 858 <!-- ===================================================================== -->
 859
 860 <h2 id="contact" class="docs">Contact the author</h2>
 861
 862 <p>
 863 If you have any questions or comments about mom, suggestions to
 864 make, criticisms to offer, or bugs to report, use the groff mailing
 865 list (subscription information available
 866 <a href="http://www.gnu.org/software/groff/groff.html">here</a>)
 867 or contact me, Peter Schaffter,  directly at the following
 868 address:
 869 <br/>
 870 <span class="pre-in-pp">
 871   &#112;&#101;&#116;&#101;&#114;&#64;&#115;&#99;&#104;&#97;&#102;&#102;&#116;&#101;&#114;&#46;&#99;&#97;
 872 </span>
 873 Please include the word &#8220;mom&#8221; or &#8220;groff&#8221; in
 874 the Subject line of any message sent to my personal address or you
 875 risk the wrath of my implacable spam filters.
 876 </p>
 877
 878 <p>
 879 If you want to visit mom&#8217;s website, you&#8217;ll find a link
 880 to it at
 881 <br/>
 882 <span class="pre-in-pp">
 883   http://www.schaffter.ca
 884 </span>
 885 The site contains links to some of my fiction, all of which was
 886 typeset with mom and groff.
 887 </p>
 888
 889 <div class="rule-long"><hr/></div>
 890
 891 <!-- Navigation links -->
 892 <table style="width: 100%; margin-top: 12px;">
 893 <tr>
 894   <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
 895   <td style="width: 100%; text-align: right;"><a href="#top">Top</a></td>
 896 </tr>
 897 </table>
 898
 899 </div>
 900
 901 <div class="bottom-spacer"><br/></div>
 902
 903 </body>
 904 </html>
 905 <!-- vim: fileencoding=utf-8: nomodified: -->