diff options
Diffstat (limited to 'contrib/mom/momdoc/appendices.html')
| -rw-r--r-- | contrib/mom/momdoc/appendices.html | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/appendices.html b/contrib/mom/momdoc/appendices.html new file mode 100644 index 00000000..932995b2 --- /dev/null +++ b/contrib/mom/momdoc/appendices.html @@ -0,0 +1,185 @@ +<html> +<head> +<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> +<title>Mom -- Appendices</title> +</head> +<body bgcolor="#dfdfdf"> + +<!====================================================================> + +<a href="typemacdoc.html#TOP">Prev</a> +<a href="toc.html">Back to Table of Contents</a> + +<a name="TOP"></a> +<a name="APPENDICES"> + <h2 align="center"><u>APPENDICES</u></h2> +</a> + +<ul> + <li><a href="#MOREDOC">Further notes on this documentation</a> + <li><a href="#CODENOTES">Some reflections on mom, with an apology</a> + <li><a href="reserved.html">List of reserved words</a> + <li><a href="#CONTACT">Contact the author</a> +</ul> + +<a name="MOREDOC"> + <h2><u>Further notes on this documentation</u></h2> +</a> + +Some <strong>mom</strong> users are sure to ask: "Why is this +documentation in html? If <strong>mom</strong>'s so great, why not +typeset the whole thing to show her off? And if groff's so great, +why not write a man page?" +<p> +Valid questions, to be sure, and <strong>mom</strong> has +answers. (Okay -- I have answers, but I speak for +<strong>mom</strong>.) +<p> +The documentation is in html because I still find it the best tool +for navigating lengthy manuals. Html, with its anchors and links, +came into being precisely so people could do something they'd never +been able to with the printed word: instantly track down internal +and external references in a document. +<p> +To me, it's essential that people reading <strong>mom</strong>'s +documentation never have difficulty finding precisely the macro +they need for a particular task. Equally, when reading up on +a macro, they should never be presented with terms or other +macro names for which they cannot instantly find accurate explanations. +Short of having written the documentation in TeX for the info browser +(and TeX bloat is one of the reasons I prefer to typeset with groff), +I can think of no better way to achieve the kind of truly useful +documentation I wanted than html. +<p> +Another reason for html is that working with <strong>mom</strong> +necessarily involves creating files inside a text editor. I use +elvis, a truly fabulous vi clone that does a terrific job of rendering +basic (text only) html. I may have written <strong>mom</strong>, +but I still regularly call on her documentation. Elvis, with its +html capabilities, lets me write and format <strong>mom</strong> +documents AND peruse her documentation, clicking on links as +necessary, without ever leaveing the comfy confines of my +text editor. +<p> +Not everyone, of course, uses an editor with html capabilities. +For them, firing up a browser is obviously necessary for reading +<strong>mom</strong>'s documentation. Browsers being what they are, +and not everyone on the globe having the cash for muscle machines +to run Galeon, or Konqueror, or Mozilla, or Netscape, their browser +needs to be one that's fast and light -- Lynx, in other words. +<p> +Some <strong>mom</strong> users may notice the absence of graphics, +frames, and (for the most part) tables in this documentation. +The reason is simple: Lynx. People who, for whatever reason (choice +or necessity), use Lynx to read the documentation must be able to make +sense of it. All of it. Graphical examples of <strong>mom</strong> +in action might have made some parts of the documenation easier to +write, but would have excluded Lynx-only users. And it goes +without saying that the documentation looks fine if you're +reading it in a graphical browser. +<br> +<hr> + +<!=====================================================================> + +<a name="CODENOTES"> + <h2><u>Some reflections on mom</u></h2> +</a> + +<p> +<strong>Mom</strong>, as a complete macro set, had her origins +in a "library" of groff routines I wrote over the +years to handle various aspects of typesetting and document +processing that weren't adequately covered by ms, me, mm, and so +on. Typically, I'd use the library to cobble together macro +sets for new challenges as they came my way. +<p> +If, as Eric Raymond asserts, open source begins with a programmer +scratching a personal itch, then <strong>mom</strong> can truly be +called open source, even if, a mere humble set of macros standing on +the shoulders of a giant named troff, she isn't programming at all. +<p> +As a writer living in a perpeptual state of penury, all the computers +I've ever owned have been hand-me-downs -- several generations +out-of-date and "resource challenged". Disk space has +always been an issue, as has processor speed and available RAM. +One of the reasons I run Linux is that it has helped enormously to +get the most out of my poor little boxes. +<p> +In Linux-land, the choice of typesetting systems basically comes down +to groff or TeX. Both are wonderful -- monumental achievements if you +ask me -- and both have their own particular strengths. However, for +people in my financial position (and there are millions of us around +the globe, in both developed and developing countries), TeX and groff +have one big difference: size. TeX is huge. Even its most ardent +supporters agree it suffers from bloat, on top of being complex and +unwieldy to manage. Groff is tiny by comparison, occupying minimal +disk space and having only a small memory footprint while at the same +time being flexible and powerful, typographically speaking. I've run +it successfully on a 386 with 8 megs of RAM and a 250 meg hard disk. +<p> +However, groff has always had a liability: it's incredibly geeky. +Owing to its very long history, it -- and its "power users" +-- have remained stuck in a time warp. Most common macro packages +still look as they did in those decades when memory was exorbitantly +expensive, and every byte mattered. Documentation -- not always +easy to find -- is written as if all readers are computer whizzes, +or at least have a university degree in one of the higher sciences. +<p> +By no means a stupid man, nor unfamiliar with the precepts of +programming, I've more than once torn my hair out over the terseness +ambiguity of groff's documentation. Making sense of certain primitives +has often involved days of testing, interpreting the documentation +instead of just using the primitive. +<p> +For some time now, groff users and macro writers have had the +option to use "long" names, yet have mostly chosen not to. +With long names, it's possible to create macro sets that are humanly +readable and easy to interpret, encouraging development and evolution. +What's more, the macros themselves need not be terse, intimidating, +and easily forgotten 1- or 2-letter commands inserted in the body +of a document. They can be sensible and helpful to everyone, groff +newbies and old hands alike. +<p> +<strong>Mom</strong>'s macro file, om.tmac, uses long names, aliases, +and a host of other groff goodies that have become part of the +whole groff picture under the unflagging guidance of groff's current +maintainer, Werner Lemberg. Nearly every macro, number register and +string is "recognisable" simply by its name. The file is +heavily commented. A consistent, if idiosyncratic, indenting style +is used as well, significantly improving readability. Anyone +wanting to futz around with <strong>mom</strong>'s macros should be +able to do so with a minimum of head scratching. +<p> +To all you groff-jocks out there who love the aracana of +groff-as-it-used-to-be, I apologise. To everyone else, I simply say: +Welcome, and enjoy. +<br> +<hr> + +<!=====================================================================> + +<a name="CONTACT"> + <h2><u>Contact the author</u></h2> +</a> + +<p> +If you have any questions or comments about <strong>mom</strong>, +suggestions to make, criticisms to offer, or bugs to report, use the +groff mailing list at +<a href="mailto:groff@ffii.org">groff@ffii.org</a> +(subscription information available +<a href="http://ffii.org/mailman/listinfo/groff/">here</a>) +or contact me, Peter Schaffter, directly at +<p> +<address align="center"> + <a href="mailto:df191@ncf.ca">df191@ncf.ca</a> +</address> + +<p> +<hr> +<a href="typemacdoc.html#TOP">Prev</a> +<a href="#TOP">Top</a> +<a href="toc.html">Back to Table of Contents</a> +</body> +</html> |