contrib/groff/contrib/mom/momdoc/appendices.html

   1 <html>
   2 <head>
   3 <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
   4 <title>Mom -- Appendices</title>
   5 </head>
   6 <body bgcolor="#dfdfdf">
   7
   8 <!====================================================================>
   9
  10 <a href="typemacdoc.html#TOP">Prev</a>&nbsp;&nbsp;
  11 <a href="toc.html">Back to Table of Contents</a>
  12
  13 <a name="TOP"></a>
  14 <a name="APPENDICES">
  15         <h2 align="center"><u>APPENDICES</u></h2>
  16 </a>
  17
  18 <ul>
  19         <li><a href="#MOREDOC">Further notes on this documentation</a>
  20         <li><a href="#CODENOTES">Some reflections on mom, with an apology</a>
  21         <li><a href="reserved.html">List of reserved words</a>
  22         <li><a href="#CONTACT">Contact the author</a>
  23 </ul>
  24
  25 <a name="MOREDOC">
  26     <h2><u>Further notes on this documentation</u></h2>
  27 </a>
  28
  29 Some <strong>mom</strong> users are sure to ask: &quot;Why is this
  30 documentation in html?  If <strong>mom</strong>'s so great, why not
  31 typeset the whole thing to show her off?  And if groff's so great,
  32 why not write a man page?&quot;
  33 <p>
  34 Valid questions, to be sure, and <strong>mom</strong> has
  35 answers.  (Okay -- I have answers, but I speak for
  36 <strong>mom</strong>.)
  37 <p>
  38 The documentation is in html because I still find it the best tool
  39 for navigating lengthy manuals.  Html, with its anchors and links,
  40 came into being precisely so people could do something they'd never
  41 been able to with the printed word: instantly track down internal
  42 and external references in a document.
  43 <p>
  44 To me, it's essential that people reading <strong>mom</strong>'s
  45 documentation never have difficulty finding precisely the macro
  46 they need for a particular task.  Equally, when reading up on
  47 a macro, they should never be presented with terms or other
  48 macro names for which they cannot instantly find accurate explanations.
  49 Short of having written the documentation in TeX for the info browser
  50 (and TeX bloat is one of the reasons I prefer to typeset with groff),
  51 I can think of no better way to achieve the kind of truly useful
  52 documentation I wanted than html.
  53 <p>
  54 Another reason for html is that working with <strong>mom</strong>
  55 necessarily involves creating files inside a text editor.  I use
  56 elvis, a truly fabulous vi clone that does a terrific job of rendering
  57 basic (text only) html.  I may have written <strong>mom</strong>,
  58 but I still regularly call on her documentation.  Elvis, with its
  59 html capabilities, lets me write and format <strong>mom</strong>
  60 documents AND peruse her documentation, clicking on links as
  61 necessary, without ever leaveing the comfy confines of my
  62 text editor.
  63 <p>
  64 Not everyone, of course, uses an editor with html capabilities.
  65 For them, firing up a browser is obviously necessary for reading
  66 <strong>mom</strong>'s documentation.  Browsers being what they are,
  67 and not everyone on the globe having the cash for muscle machines
  68 to run Galeon, or Konqueror, or Mozilla, or Netscape, their browser
  69 needs to be one that's fast and light -- Lynx, in other words.
  70 <p>
  71 Some <strong>mom</strong> users may notice the absence of graphics,
  72 frames, and (for the most part) tables in this documentation.
  73 The reason is simple: Lynx.  People who, for whatever reason (choice
  74 or necessity), use Lynx to read the documentation must be able to make
  75 sense of it.  All of it.  Graphical examples of <strong>mom</strong>
  76 in action might have made some parts of the documenation easier to
  77 write, but would have excluded Lynx-only users.  And it goes
  78 without saying that the documentation looks fine if you're
  79 reading it in a graphical browser.
  80 <br>
  81 <hr>
  82
  83 <!=====================================================================>
  84
  85 <a name="CODENOTES">
  86         <h2><u>Some reflections on mom</u></h2>
  87 </a>
  88
  89 <p>
  90 <strong>Mom</strong>, as a complete macro set, had her origins
  91 in a &quot;library&quot; of groff routines I wrote over the
  92 years to handle various aspects of typesetting and document
  93 processing that weren't adequately covered by ms, me, mm, and so
  94 on.  Typically, I'd use the library to cobble together macro
  95 sets for new challenges as they came my way.
  96 <p>
  97 If, as Eric Raymond asserts, open source begins with a programmer
  98 scratching a personal itch, then <strong>mom</strong> can truly be
  99 called open source, even if, a mere humble set of macros standing on
 100 the shoulders of a giant named troff, she isn't programming at all.
 101 <p>
 102 As a writer living in a perpeptual state of penury, all the computers
 103 I've ever owned have been hand-me-downs -- several generations
 104 out-of-date and &quot;resource challenged&quot;.  Disk space has
 105 always been an issue, as has processor speed and available RAM.
 106 One of the reasons I run Linux is that it has helped enormously to
 107 get the most out of my poor little boxes.
 108 <p>
 109 In Linux-land, the choice of typesetting systems basically comes down
 110 to groff or TeX.  Both are wonderful -- monumental achievements if you
 111 ask me -- and both have their own particular strengths.  However, for
 112 people in my financial position (and there are millions of us around
 113 the globe, in both developed and developing countries), TeX and groff
 114 have one big difference: size.  TeX is huge.  Even its most ardent
 115 supporters agree it suffers from bloat, on top of being complex and
 116 unwieldy to manage.  Groff is tiny by comparison, occupying minimal
 117 disk space and having only a small memory footprint while at the same
 118 time being flexible and powerful, typographically speaking.  I've run
 119 it successfully on a 386 with 8 megs of RAM and a 250 meg hard disk.
 120 <p>
 121 However, groff has always had a liability: it's incredibly geeky.
 122 Owing to its very long history, it -- and its &quot;power users&quot;
 123 -- have remained stuck in a time warp.  Most common macro packages
 124 still look as they did in those decades when memory was exorbitantly
 125 expensive, and every byte mattered.  Documentation -- not always
 126 easy to find -- is written as if all readers are computer whizzes,
 127 or at least have a university degree in one of the higher sciences.
 128 <p>
 129 By no means a stupid man, nor unfamiliar with the precepts of
 130 programming, I've more than once torn my hair out over the terseness and
 131 ambiguity of groff's documentation.  Making sense of certain primitives
 132 has often involved days of testing, interpreting the documentation
 133 instead of just using the primitive.
 134 <p>
 135 For some time now, groff users and macro writers have had the
 136 option to use &quot;long&quot; names, yet have mostly chosen not to.
 137 With long names, it's possible to create macro sets that are humanly
 138 readable and easy to interpret, encouraging development and evolution.
 139 What's more, the macros themselves need not be terse, intimidating,
 140 and easily forgotten 1- or 2-letter commands inserted in the body
 141 of a document.  They can be sensible and helpful to everyone, groff
 142 newbies and old hands alike.
 143 <p>
 144 <strong>Mom</strong>'s macro file, om.tmac, uses long names, aliases,
 145 and a host of other groff goodies that have become part of the
 146 whole groff picture under the unflagging guidance of groff's current
 147 maintainer, Werner Lemberg.  Nearly every macro, number register and
 148 string is &quot;recognisable&quot; simply by its name.  The file is
 149 heavily commented.  A consistent, if idiosyncratic, indenting style
 150 is used as well, significantly improving readability.  Anyone
 151 wanting to futz around with <strong>mom</strong>'s macros should be
 152 able to do so with a minimum of head scratching.
 153 <p>
 154 To all you groff-jocks out there who love the aracana of
 155 groff-as-it-used-to-be, I apologise.  To everyone else, I simply say:
 156 Welcome, and enjoy.
 157 <br>
 158 <hr>
 159
 160 <!=====================================================================>
 161
 162 <a name="CONTACT">
 163         <h2><u>Contact the author</u></h2>
 164 </a>
 165
 166 <p>
 167 If you have any questions or comments about <strong>mom</strong>,
 168 suggestions to make, criticisms to offer, or bugs to report, use the
 169 groff mailing list at
 170 <a href="mailto:groff@ffii.org">groff@ffii.org</a>
 171 (subscription information available
 172 <a href="http://ffii.org/mailman/listinfo/groff/">here</a>)
 173 or contact me, Peter Schaffter,  directly at
 174 <p>
 175 <address align="center">
 176         <a href="mailto:df191@ncf.ca">df191@ncf.ca</a>
 177 </address>
 178
 179 <p>
 180 <hr>
 181 <a href="typemacdoc.html#TOP">Prev</a>&nbsp;&nbsp;
 182 <a href="#TOP">Top</a>&nbsp;&nbsp;
 183 <a href="toc.html">Back to Table of Contents</a>
 184 </body>
 185 </html>