1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2<html> 3<head> 4<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> 5<title>Mom -- Appendices</title> 6</head> 7<body bgcolor="#dfdfdf"> 8 9<!====================================================================> 10 11<a href="reserved.html#TOP">Next</a> 12<a href="macrolist.html#TOP">Prev</a> 13<a href="toc.html">Back to Table of Contents</a> 14<p> 15 16<a name="TOP"></a> 17<a name="APPENDICES"> 18 <h2 align="center"><u>APPENDICES</u></h2> 19</a> 20 21<ul> 22 <li><a href="#MOREDOC">Further notes on this documentation</a> 23 <li><a href="#FONTS">Adding PostScript fonts to groff</a> 24 <ul> 25 <li><a href="#HOWTO">How to create a PostScript font for use with groff</a> 26 </ul> 27 <li><a href="#CODENOTES">Some reflections on mom, with an apology</a> 28 <li><a href="#CONTACT">Contact the author</a> 29 <li><a href="reserved.html">List of reserved words</a> 30</ul> 31 32<a name="MOREDOC"> 33 <h2><u>Further notes on this documentation</u></h2> 34</a> 35 36Some <strong>mom</strong> users are sure to ask: "Why is this 37documentation in html? If <strong>mom</strong>'s so great, why not 38typeset the whole thing to show her off? And if groff's so great, 39why not write a man page?" 40<p> 41Valid questions, to be sure, and <strong>mom</strong> has 42answers. (Okay -- I have answers, but I speak for 43<strong>mom</strong>.) 44<p> 45The documentation is in html because I still find it the best tool 46for navigating lengthy manuals. Html, with its anchors and links, 47came into being precisely so people could do something they'd never 48been able to with the printed word: instantly track down internal 49and external references in a document. 50<p> 51To me, it's essential that people reading <strong>mom</strong>'s 52documentation never have difficulty finding precisely the macro 53they need for a particular task. Equally, when reading up on 54a macro, they should never be presented with terms or other 55macro names for which they cannot instantly find accurate explanations. 56Short of having written the documentation in TeX for the info browser 57(and TeX bloat is one of the reasons I prefer to typeset with groff), 58I can think of no better way to achieve the kind of truly useful 59documentation I wanted than html. 60<p> 61Another reason for html is that working with <strong>mom</strong> 62necessarily involves creating files inside a text editor. I use 63elvis, a truly fabulous vi clone that does a terrific job of rendering 64basic (text only) html. I may have written <strong>mom</strong>, 65but I still regularly call on her documentation. Elvis, with its 66html capabilities, lets me write and format <strong>mom</strong> 67documents AND peruse her documentation, clicking on links as 68necessary, without ever leaving the comfy confines of my 69text editor. 70<p> 71Not everyone, of course, uses an editor with html capabilities. 72For them, firing up a browser is obviously necessary for reading 73<strong>mom</strong>'s documentation. Browsers being what they are, 74and not everyone on the globe having the cash for muscle machines 75to run Galeon, or Konqueror or Mozilla, their browser 76needs to be fast and light--and probably "text-only". 77<p> 78Some <strong>mom</strong> users may notice the absence of graphics, 79frames, and (for the most part) tables in this documentation. The 80reason is simple: text-only browsers. People who, for whatever 81reason (choice or necessity), use lynx, or links or w3m to read 82the documentation must be able to make sense of it. All of it. 83Graphical examples of <strong>mom</strong> in action might have made 84some parts of the documentation easier to write, but would have 85excluded text-only browser users. And it goes without saying that 86the documentation looks fine if you're reading it in a graphical 87browser. 88<br> 89<hr> 90 91<!=====================================================================> 92 93<a name="FONTS"> 94 <h2><u>Adding PostScript fonts to groff</u></h2> 95</a> 96 97<a name="SMALL_NOTE"></a> 98<em><strong>Small note:</strong> the term <prefix> in this 99section refers to the directory in which groff is installed, 100typically something like /usr/share/groff/<version#> 101(for distro-specific, pre-compiled groff packages) or 102/usr/local/share/groff/<version#> (if you've built groff 103from source).</em> 104<p> 105Groff comes with a small library of PostScript 106<a href="definitions.html#TERMS_FAMILY">families</a> 107(see the 108<a href="typesetting.html#FAMILY">FAMILY</a> 109macro for a list). The families have four 110<a href="definitions.html#TERMS_FONT">fonts</a> 111associated with them. These fonts are a combination of 112<a href="definitions.html#TERMS_WEIGHT">weight</a> 113and 114<a href="definitions.html#TERMS_SHAPE">shape</a>: 115<br> 116<ul> 117 <li><strong>R</strong> (Roman, usually Medium weight), 118 <li><strong>I</strong> (Italic, usually Medium weight), 119 <li><strong>B</strong> (Bold, usually Roman shape) and 120 <li><strong>BI</strong> (Bold Italic). 121</ul> 122<p> 123If you do a lot of document processing or typesetting with 124<strong>mom</strong>, you'll find, sooner or later, that these 125families and their associated fonts aren't sufficient. You'll want 126to supplement them, either with more fonts for the families already 127provided--"Damn! I need Helvetica Bold Condensed Italic!"--or with 128entire new families. 129<p> 130Without going into the gory details (yet), while it's true that 131adding fonts to groff is a relatively straightforward 132process, extending existing families or adding new ones requires 133some planning. 134<p> 135The traditional approach to extending groff families has been 136to create new families for non-default weights and 137shapes (e.g. Light, which is a weight; Condensed, which is a 138shape), then to associate them with groff's predefined <strong>R, 139I, B</strong> and <strong>BI</strong> font styles. An example 140of this can be seen in the groff PostScript font library itself 141(<prefix>/font/devps/): there's one "family" for 142Helvetica (HR, HI, HB, HBI) and another for Helvetica Narrow (HNR, 143HNI, HNB, HNBI). 144<p> 145The difficulty with this approach is that typographers 146tend to think of "families" as referring to the 147entire set of font weights and shapes associated with a 148particular family name. For example, when a typesetter says 149"the Helvetica family", s/he is including the <a 150href="definitions.html#TERMS_WEIGHT">weights</a> Helvetica Thin, 151Helvetic Light, Helvetica Regular, Helvetica Bold, Helvetica Heavy, 152etc, and all their associated 153<a href="definitions.html#TERMS_SHAPE">shapes</a> 154(Roman, 155Italic, Condensed, Narrow, Extended, Outline, etc). 156<p> 157Thus, intuitively, when a typesetter gives <strong>mom</strong> a 158<kbd>.FAM(ILY)</kbd> directive, s/he reasonably expects that any 159subsequent <kbd>.FT</kbd> directive will access the desired font 160from the Helvetica family--without the need to state explicitly both 161family and font to <kbd>.FT</kbd>, as it is explained one can do in 162the 163<a href="typesetting.html#FAMILY">FAMILY</a> 164and 165<a href="typesetting.html#FONT">FT</a> 166sections of these documents. 167<p> 168If one had, say, the fonts, Helvetica Light Roman 169and Helvetica Light Italic as well as Helvetica Light Condensed 170Roman and Helvetica Light Condensed Italic, the traditional 171approach would require two "partial" families: HLR/HLI and 172HLCDR/HLCDI. Accessing these family/font combos 173routinely throughout a document would then require 174changing family (with <kbd>.FAM(ILY)</kbd>) and selecting the 175desired font (with <kbd>.FT R</kbd> or <kbd>.FT I</kbd>), or 176passing <kbd>.FT</kbd> the lengthy family+fontname (.e.g. <kbd>.FT 177HLCDI</kbd>). 178<p> 179Fortunately, groff provides a mechanism whereby it's possible to 180extend the basic <strong>R, I, B</strong> and <strong>BI</strong> 181fonts ("styles" in groff-speak) so that one can, in 182fact, create extensive type families, and access all the fonts 183in them with <kbd>.ft</kbd> (groff) or <kbd>.FT</kbd> (mom). 184<p> 185<strong>mom</strong> uses this mechanism to offer, in addition to 186groff's default PostScript font styles, the following: 187<p> 188<a name="STYLE_EXTENSIONS"></a> 189<pre> 190Mom's extensions to groff's basic font styles 191============================================= 192 193 L = Light Roman 194 LI = Light Italic 195 LCD = Light Condensed Roman 196 LCDI = Light Condensed Italic 197 LEX = Light Extended Roman 198 LEXI = Light Extended Italic 199 CD = Medium/Book Condensed Roman 200 CDI = Medium/Book Condensed Italic 201 EX = Medium/Book Extended Roman 202 EXI = Medium/Book Extended Italic 203 DB = DemiBold Roman 204 DBI = DemiBold Italic 205 BCD = Bold Condensed Roman 206 BCDI = Bold Condensed Italic 207 BEX = Bold Extended Roman 208 BEXI = Bold Extended Italic 209 HV = Heavy Roman 210 HVI = Heavy Italic 211 HVCD = Heavy Condensed Roman 212 HVCDI = Heavy Condensed Italic 213 HVEX = Heavy Extended Roman 214 HVEXI = Heavy Extended Italic 215 BL = Black Roman 216 BLI = Black Italic 217 BLCD = Black Condensed Roman 218 BLCDI = Black Condensed Italic 219 BLEX = Black Extended Roman 220 BLEXI = Black Extended Italic 221 UBL = Ultra-Black Roman 222 UBLI = Ultra-Black Italic 223</pre> 224 225Thus, with <strong>mom</strong>, if you've installed, say, some 226extra Helvetica fonts and named them according to the convention FS 227(where "F" means family and "S" means font 228style), once having entered 229<p> 230<pre> 231 .FAMILY H 232 or 233 .FAM H 234</pre> 235 236you can access any of those Helvetica fonts simply by 237passing the correct argument from the list above to 238<a href="typesetting.html#FONT">FT</a>. 239<p> 240For example, if you were working in Medium Roman (<kbd>.FT R</kbd>) 241and you needed Medium Condensed Italic for a while (assuming it's 242installed), you'd just type 243<p> 244<pre> 245 .FT CDI 246</pre> 247 248to access the Medium Condensed Italic font from the Helvetica 249family. 250<p> 251<strong>Mom</strong>'s list of font styles doesn't pretend to 252be exhaustive, but rather tries to cover the basic weight/shape 253combinations likely to be found in any reasonably complete type 254family. 255<p> 256The actual extension names are arbitrary and can be used in a 257flexible manner. For example, if you create a family that has a 258DemiBold font (DB) but no Bold font (B), you might find it more 259convenient to give the DemiBold font the extension "B". 260Equally, if the family has an ExtraBold font, you might find it more 261convenient to use the extension "HV" (Heavy). 262<a name="REGISTER_STYLE"></a> 263<p> 264However, you may, at needs, want to add to <strong>mom</strong>'s 265list of font styles. You can do this by editing the file, om.tmac. 266Near the top, you'll see lines of the form 267<p> 268<pre> 269 .sty \n[.fp] L \" Light Roman 270 .sty \n[.fp] LI \" Light Italic 271 .sty \n[.fp] LCD \" Light Condensed Roman 272</pre> 273 274Simply add your new font style by imitating what you see and 275plugging in your new font style (having, of course, first created the 276font, correctly named, in groff's PostScript font directory; see 277<a href="#HOWTO">How to create a PostScript font for use with groff</a>). 278<p> 279For example, if you already have some fonts from the Univers 280family installed and have called the family UN, you might decide at 281some point to add the Bold Outline font (UNBO). In which case, 282you'd add 283<p> 284<pre> 285 .sty \n[.fp] BO \" Bold Outline 286</pre> 287 288to the <kbd>.sty \n[.fp] <font style></kbd> list in om.tmac. 289<p> 290Be careful, though, that any styles you add do not conflict 291with <strong><u>family</u></strong> names that already exist. 292"C", for example, conflicts with the Courier family 293(CR, CI, CB, CI). Were you to create a font style "C", 294thinking that <kbd>.FT C</kbd> would give you access to font style 295once you'd given a <kbd>.FAM(ILY)</kbd> directive, you'd get a nasty 296surprise: your type would come out in Courier Roman! 297<p> 298<strong>VERY IMPORTANT NOTE: mom</strong>'s font extensions are 299not "user-space" controllable via a macro. If you've 300been using groff for a long time, and have already rolled your own 301solution to adding PostScript families, fonts, weights, shapes, etc. to 302groff, you may find that <strong>mom</strong>'s font extensions 303conflict with your own scheme. Should that be the case, comment out 304the <kbd>.sty \n[.fp] <font style></kbd> lines found near the 305top of the om.tmac file. 306 307<a name="HOWTO"><h3><u>How to create a PostScript font for use with groff</u></h3></a> 308These instructions aren't meant to cover all possibilities, merely 309to present one way of making PostScript families/fonts available to 310groff and <strong>mom</strong>. 311<p> 312GNU/Linux distributions being what they are, directory locations may 313differ and the presence of some executables can't be guaranteed. 314I run a Debian system. The instructions reflect that. Users of 315other distros will have to interpret them according to the way their 316distro operates. 317<p> 318What you need before you start: 319<br> 320<ul> 321 <li>groff, version 1.18 or higher 322 <br> 323 (Debian package: groff) 324 <li>a full installation of gs and associated tools 325 <br> 326 (Debian package: gs or gs-gpl) 327 <li>a library of gs fonts 328 <br> 329 (Debian package: gsfonts) 330 <li>a utility for converting TrueType fonts to Type1 fonts 331 <br> 332 (Debian package: ttf2pt1) 333 <li>a font manager 334 <br> 335 (Debian packages: defoma, psfontmgr, dfontmgr) 336 <li>perl 337 <br> 338 (Debian package: perl) 339</ul> 340<br> 341A reasonably complete installation of any major GNU/Linux distro 342should already have these on your system, except perhaps for the 343utility to convert TrueType fonts to Type1 fonts. 344<p> 345Initial preparation (you only have to do this once): 346<br> 347<ol> 348 <li>If you don't already have one, create a directory in your 349 home directory to hold new fonts. Any directory name will do. 350 I use ~/Fonts, with subdirectories for Type1, TrueType and Groff 351 fonts. 352<a name="SITE-FONT"></a> 353 <li>Locate the groff directory, site-font. The exact location is 354 difficult to predict, owing to differences between distros 355 and whether you're using a pre-packaged groff or have built 356 it from source. Some typical locations are 357 <br> 358 <ul> 359 <li>/usr/share/groff, 360 <li>/usr/local/share/groff 361 <li>/etc/groff 362 </ul> 363 <p> 364 If you can't find the site-font directory, locate 365 groff's site-tmac directory, and, as root, create site-font 366 in the same directory as the one that holds site-tmac. 367 E.g., if you find site-tmac in /usr/share/groff, create 368 site-font in /usr/share/groff. 369 <li>Locate the file <kbd><prefix>/font/devps/generate/textmap</kbd> 370 and symlink it to <kbd>textmap</kbd> in the directory that 371 contains your personal collection of PostScript fonts. (See the 372 <a href="#SMALL_NOTE">Small Note</a>, 373 above, for the meaning of <prefix>). On my system, 374 at the time of writing, <prefix> is 375 /usr/local/share/groff/1.19.2/, therefore, I symlink it in 376 ~/Fonts/Type1 with 377 <br> 378 <pre> 379ln -s /usr/local/share/groff/1.19.2/font/devps/generate/textmap textmap 380 </pre> 381 <li>Locate the file <prefix>/font/devps/text.enc and 382 symlink it to <kbd>text.enc</kbd> in your personal font 383 directory. On my system, in ~/Fonts/Type1 384 <pre> 385ln -s /usr/local/share/groff/1.19.2/font/devps/text.enc text.enc 386 </pre> 387 <li>Make sure you know which directory/ies holds your gs fonts. 388 You'll need the information later. On a Debian box, some 389 typical locations are 390 <br> 391 <ul> 392 <li>/usr/lib/ghostscript/fonts 393 <li>/usr/share/ghostscript/fonts 394 <li>/usr/share/fonts/type1/gsfonts 395 </ul> 396</ol> 397<br> 398Font creation/installation: 399<br> 400<ol> 401 <li>Acquire the font in either Type1 (.pfb) or TrueType 402 (.ttf) format. 403 <li>Place the font in your personal font directory; for me, 404 that's ~/Fonts/Type1 or ~/Fonts/TrueType. 405 <li>In your personal font directory, run one of the following: 406 <br> 407 <ul> 408 <li>For Type1 fonts 409 <br> 410 <ul> 411 <li><kbd>getafm fontfilename.pfb | gsnd - > fontfilename.afm</kbd> 412 <br> 413 For Type1 fonts, this will generate something called 414 an .afm (Adobe Font Metrics) file, which is 415 required to create PostScript fonts for groff. 416 </ul> 417 <li>For TrueType fonts 418 <br> 419 <ul> 420 <li><kbd>ttf2pt1 \-b fontfilename.ttf</kbd> 421 <br> 422 For TrueType fonts, this will generate a PostScript 423 .pfb file as well as an .afm file. 424 </ul> 425 </ul> 426 <li>Still in your personal font directory, run 427 <br> 428 <ul> 429 <li><kbd>afmtodit -e text.enc fontfilename.afm textmap GROFF_FONTNAME</kbd> 430 </ul> 431 <p> 432 Q: <em>How do I choose a GROFF_FONTNAME?</em> 433 <p> 434 A: Start by considering the 435 <a href="definitions.html#TERMS_FAMILY">family</a> 436 to which the font belongs. If you're adding to a family that 437 already exists in groff's <prefix>/font/devps 438 directory, that will be the first part of the font name. 439 (See 440 <a href="typesetting.html#FAMILY">here</a> 441 for a list of families already installed, along with their groff 442 names.) Add to that name the appropriate weight/style extension, 443 listed 444 <a href="#STYLE_EXTENSIONS">here</a>. 445 <p> 446 For example, if you're adding Helvetica Light Roman, your 447 GROFF_FONTNAME would be <strong>HL</strong>. If you're 448 adding Helvetica Light Italic, your GROFF_FONTNAME would be 449 <strong>HLI</strong>. 450 <p> 451 If you're adding a font not already in groff's PostScript 452 families, first choose a meaningful name for the 453 <a name="definitions.html#TERMS_FAMILY">family</a> 454 to which the font belongs. The name can be anything you like. If, 455 for example, the family is Garamond, you could choose GARAMOND, 456 GARA, GD, or even just plain G as the family name. Then tack on the 457 appropriate style/weight extension. Thus, if you were installing 458 Garamond Bold Condensed Italic and had chosen <strong>GD</strong> 459 as the family name for Garamond, your GROFF_FONTNAME would be 460 <strong>GDBCDI</strong>. 461 <p> 462 In <strong>mom</strong>, you can then access the Garamond 463 family with <kbd>.FAM GD</kbd>, and the Bold Condensed 464 Italic font wth <kbd>.FT BCDI</kbd>. 465 <p> 466 <strong>Note:</strong> The family name need not be in upper 467 case, and there's no limit to the length of the name. 468 "Garamond", for example, could be the name you 469 give the Garamond family. In fact, you might find it 470 preferable, since a) you wouldn't have to remember how 471 you'd named the family, and b) should you be scanning 472 your 473 <a href="#SITE-FONT">site-font directory</a>, 474 something like GaramondBCDI will be more meaningful than, 475 say, GDBCDI. 476 <li>Copy or move GROFF_FONTNAME to your 477 <a href="#SITE-FONT">site-font directory</a>, 478 or change to the site-font directory and make a symlink to 479 GROFF_FONTNAME in your personal directory. 480 <li>Copy or move the .pfb file to the directory that 481 holds your gs fonts, or change to that directory and make a 482 symlink to the .pfb file in your personal directory. 483 <li>Do whatever your system or distro requires in order to 484 register the new PostScript font (the .pfb file). On a 485 Debian system, as root, you can run dfontmgr for a 486 graphical interface that will take care of registering the 487 font. 488</ol> 489<p> 490Written out in full, adding fonts looks like a lot of work. It 491isn't. Basically, it's just: 492<br> 493<ul> 494 <li>acquire the font 495 <li>generate an .afm file for the font 496 <li>create the groff font 497 <li>put the groff font in <prefix>/font/devps 498 <li>make sure gs knows about the font 499</ul> 500<br> 501After you've done it a couple of times, it all makes sense, and is 502really quite easy. Not to mention that once you understand the 503process, you can write a bash script to automate the process. 504Here's an example, which you can adapt to your own needs. The 505script requires an argument (the .pfb filename), then prompts for 506the GROFF_FONTNAME. 507<p> 508<pre> 509#! /bin/bash 510 511# A script for installing Type1 fonts. 512# 513# Builds .afm files from .pfb files, generates a groff font from the 514# .afm file, makes a symlink in /usr/lib/ghostscript/font/ to the 515# .pfb file, and a symlink in site-font to the groff font 516 517# .pfb filename, stripped of .pfb extension 518FONT=`basename $1 .pfb` 519 520# Directory holding my personal collection of type1 fonts 521FONTDIR="$HOME/Fonts/Type1" 522 523# Directory holding system ghostscript fonts 524GS_FONTDIR="/usr/lib/ghostscript/fonts" 525 526# Location of site-font/devps 527GROFF_SITE_FONTDIR="/usr/local/share/groff/site-font/devps" 528 529# Personal groff fonts directory 530GROFF_FONTS="$HOME/Fonts/Groff" 531 532# Symlinks to textmap and text.enc 533TEXTMAP="$FONTDIR/textmap" 534TEXTENC="$FONTDIR/text.enc" 535 536if [ ! `pwd` = "$FONTDIR" ] ; then 537 echo "Changing into $FONTDIR directory.." 538 cd $FONTDIR 539 sleep 1 540else 541 sleep 1 542fi 543 544echo -n "Groff name for this font: " 545read FONTNAME 546sleep 1 547 548echo "Getting .afm.." 549getafm $FONT.pfb | gsnd - > $FONT.afm 550sleep 1 551 552echo "Creating $FONTNAME.." 553afmtodit -e $TEXTENC $FONTDIR/$FONT.afm $TEXTMAP $FONTNAME 554mv -i $FONTNAME $GROFF_FONTS 555sudo ln -s $GROFF_FONTS/$FONTNAME $GROFF_SITE_FONTDIR/$FONTNAME 556sleep 1 557 558echo "Linking $FONT in $GS_FONTDIR.." 559cd $GS_FONTDIR 560sudo ln -s $FONTDIR/$FONT.afm $FONT.afm 561sudo ln -s $FONTDIR/$FONT.pfb $FONT.pfb 562sleep 1 563 564# This next bit is Debian specific. If you're not running a 565# Debian system, replace it with whatever your distro requires 566# in order to register Type1 fonts. 567 568if [ !`pidof -x /usr/bin/dfontmgr` ] ; then 569 echo "I will now run dfontmgr so you can register the font." 570 exec sudo dfontmgr & 571else 572 echo "You may now register the font with dfontmgr." 573fi 574</pre> 575<hr> 576 577<!=====================================================================> 578 579<a name="CODENOTES"> 580 <h2><u>Some reflections on mom</u></h2> 581</a> 582 583<p> 584<strong>Mom</strong>, as a complete macro set, had her origins 585in a "library" of groff routines I wrote over the 586years to handle various aspects of typesetting and document 587processing that weren't adequately covered by ms, me, mm, and so 588on. Typically, I'd use the library to cobble together macro 589sets for new challenges as they came my way. 590<p> 591If, as Eric Raymond asserts, open source begins with a programmer 592scratching a personal itch, then <strong>mom</strong> can truly be 593called open source, even if, a mere humble set of macros standing on 594the shoulders of a giant named troff, she isn't programming at all. 595<p> 596As a writer living in a perpetual state of penury, all the computers 597I've ever owned have been hand-me-downs -- several generations 598out-of-date and "resource challenged". Disk space has 599always been an issue, as has processor speed and available RAM. 600One of the reasons I run GNU/Linux is that it has helped enormously 601to get the most out of my poor little boxes. (It has been pointed 602out to me that NetBSD might be an even better choice of operating 603systems for computers with limited resources.) 604<p> 605In Linux-land, the choice of typesetting systems basically comes down 606to groff or TeX. Both are wonderful -- monumental achievements if you 607ask me -- and both have their own particular strengths. However, for 608people in my financial position (and there are millions of us around 609the globe, in both developed and developing countries), TeX and groff 610have one big difference: size. TeX is huge. Even its most ardent 611supporters agree it suffers from bloat, on top of being complex and 612unwieldy to manage. Groff is tiny by comparison, occupying minimal 613disk space and having only a small memory footprint while at the same 614time being flexible and powerful, typographically speaking. I've run 615it successfully on a 386 with 8 megs of RAM and a 250 meg hard disk. 616<p> 617However, groff has always had a liability: it's incredibly geeky. 618Owing to its very long history, it -- and its "power users" 619-- have remained stuck in a time warp. Most common macro packages 620still look as they did in those decades when memory was exorbitantly 621expensive and every byte mattered. Documentation -- not always 622easy to find -- is written as if all readers are computer whizzes, 623or at least have a university degree in one of the higher sciences. 624<p> 625By no means a stupid man, nor unfamiliar with the precepts of 626programming, I've more than once torn my hair out over the terseness and 627ambiguity of groff's documentation. Making sense of certain primitives 628has often involved days of testing, interpreting the documentation 629instead of just using the primitive. 630<p> 631(ADDENDUM to the previous two paragraphs: A tremendous amount of 632effort has gone into creating a groff manual that can be read with 633"info," as well as creating truly useful man pages. The info 634manual is clear and well-written, so my comments are actually out 635of date. I leave them in for the benefit of groff newbies, who may 636still find the documents a bit intimidating.) 637<p> 638For some time now, groff users and macro writers have had the 639option to use "long" names, yet have mostly chosen not to. 640With long names, it's possible to create macro sets that are humanly 641readable and easy to interpret, encouraging development and evolution. 642What's more, the macros themselves need not be terse, intimidating, 643and easily forgotten 1- or 2-letter commands inserted in the body 644of a document. They can be sensible and helpful to everyone, groff 645newbies and old hands alike. 646<p> 647<strong>Mom</strong>'s macro file, om.tmac, uses long names, aliases, 648and a host of other groff goodies that have become part of the 649whole groff picture under the unflagging guidance of groff's current 650maintainer, Werner Lemberg. Nearly every macro, number register and 651string is "recognizable" simply by its name. The file is 652heavily commented. A consistent, if idiosyncratic, indenting style 653is used as well, significantly improving readability. Anyone 654wanting to futz around with <strong>mom</strong>'s macros should be 655able to do so with a minimum of head scratching. 656<br> 657<hr> 658 659<!=====================================================================> 660 661<a name="CONTACT"> 662 <h2><u>Contact the author</u></h2> 663</a> 664 665<p> 666If you have any questions or comments about <strong>mom</strong>, 667suggestions to make, criticisms to offer, or bugs to report, use the 668groff mailing list at 669<a href="mailto:groff@ffii.org">groff@ffii.org</a> 670(subscription information available 671<a href="http://ffii.org/mailman/listinfo/groff/">here</a>) 672or contact me, Peter Schaffter, directly at 673<i>peter@faustus.dyn.ca</i> 674or 675<i>ptpi@golden.net</i>. 676 677<p> 678Please include the word "mom" or "groff" in the 679Subject: line of any message sent to my personal address, or you 680risk the wrath of my implacable spam filters. :) 681<p> 682If you want to visit <strong>mom</strong>'s homepage, you'll find 683it 684<a href="http://faustus.dyn.ca/mom/mom.html">here</a>. 685<p> 686<hr> 687<a href="reserved.html#TOP">Next</a> 688<a href="macrolist.html#TOP">Prev</a> 689<a href="#TOP">Top</a> 690<a href="toc.html">Back to Table of Contents</a> 691</body> 692</html> 693