diff options
Diffstat (limited to 'contrib/mom/momdoc/using.html')
| -rw-r--r-- | contrib/mom/momdoc/using.html | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/using.html b/contrib/mom/momdoc/using.html new file mode 100644 index 00000000..d8a87ce0 --- /dev/null +++ b/contrib/mom/momdoc/using.html @@ -0,0 +1,207 @@ +<html> +<head> +<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> +<title>Using mom</title> +</head> +<body bgcolor="#dfdfdf"> + +<!====================================================================> + +<a href="toc.html">Back to Table of Contents</a> + +<a name="TOP"></a> +<a name="USING"> + <h1 align="center"><u>USING MOM</u></h1> +</a> + +<a href="#USING_INTRO">Introduction</a> +<br> +<a href="#USING_MACROS">Inputting macros</a> +<br> +<a href="#USING_INVOKING">Invoking groff</a> +<br> +<a href="#USING_PREVIEWING">Previewing documents</a> +<br> +<hr> +<h2><a name="USING_INTRO"><u>Introduction</u></a></h2> + +As explained in the section +<a href="intro.html#INTRO">What is mom?</a>, +<strong>mom</strong> can be used in two ways: for straight typesetting +or for document processing. The difference between the two is +that in straight typesetting, every macro is a literal +typesetting instruction that determines precisely how text +following it will look. Document processing, on the other hand, +uses markup "tags" (e.g. <kbd>.PP</kbd> for +paragraphs, <kbd>.HEAD</kbd> for heads, <kbd>.FOOTNOTE</kbd> +for footnotes, etc.) that make a lot of typesetting decisions +automatically. +<p> +You tell <strong>mom</strong> that you want to use the document +processing macros with the +<a href="docprocessing.html#START">START</a> +macro, explained below. After <strong>START</strong>, +<strong>mom</strong> determines the appearance of text following +the markup tags automatically, although you, the user, can easily +change how <strong>mom</strong> interprets the tags. This gives you +nearly complete control over the look and feel of your documents. +In addition, the typesetting macros, in combination with document +processing, let you meet all sorts of typesetting needs that just +can't be covered by "one macro fits all" markup tags. + +<a name="USING_MACROS"> + <h2><u>How to input mom's macros</u></h2> +</a> + +Regardless of which way you use <strong>mom</strong>, the +following apply. +<br> +<ol> + <li>You need a good text editor for inputting + <strong>mom</strong> files. + <p> + I cannot recommend highly enough that you use an + editor that lets you write syntax highlighting + rules for <strong>mom</strong>'s macros and + <a href="definitions.html#TERMS_INLINES">inline escapes</a>. + I use the vi clone called elvis, and find it a pure + joy in this regard. Simply colorizing macros and + inlines to half-intensity is enough to make text stand + out clearly from formattting commands. + <li>All <strong>mom</strong>'s macros begin with a period + (dot) and must be entered in upper case (capital) + letters. + <li>Macro + <a href="definitions.html#TERMS_ARGUMENTS">arguments</a> + are separated from the macro itself by spaces. Multiple + arguments to the same macro are separated from each + other by spaces. Any number of spaces may be used. All + arguments to a macro must appear on the same line as the + macro. + <li>Any argument (except a + <a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a>) + that is not a digit must be entered in upper case + (capital) letters. + <li>Any argument that requires a plus or minus sign must + have the plus or minus sign prepended to the argument + with no intervening space (e.g. +2, -4). + <li>Any argument that requires a + <a href="definitions.html#TERMS_UNITOFMEASURE">unit of measure</a> + must have the unit appended directly to the argument, + with no intervening space (e.g. 4P, .5i, 2v). + <li><a href="definitions.html#TERMS_STRINGARGUMENT">String arguments</a>, + in the sense that the term is used in this manual, must + be surrounded by double-quotes ("text of + string"). Multiple string arguments are separated + from each other by spaces (each argument surrounded by + double-quotes, of course). + <li>If a string argument, as entered in your text editor, + becomes uncomfortably long (i.e. runs longer than the + visible portion of your screen or window), you may break + it into two or more lines by placing the backslash + character (<kbd>\</kbd>) at the ends of lines to break + them up, like this: + <p> + <pre> + .SUBTITLE "An In-Depth Consideration of the \ + Implications of Forty-Two as the Meaning of Life, \ + The Universe, and Everything" + </pre> +</ol> + +It's important that formatted documents be easy to read/interpret +when you're looking at them in a text editor. One way to achieve +this is to group macros that serve a similar purpose together, and +separate them from other groups of macros with a blank comment line. +In groff, that's done with <kbd>\#</kbd> on a line by itself. +Consider the following, which is a template for starting the +chapter of a book. +<p> +<pre> + .TITLE "My Pulizter Novel" + .AUTHOR "Joe Blow" + .CHAPTER 1 + \# + .DOCTYPE CHAPTER + .PRINTSTYPE TYPESET + \# + .FAM P + .PS 10 + .LS 12 + \# + .START +</pre> + +<a name="USING_INVOKING"> + <h2><u>Printing -- invoking groff with mom</u></h2> +</a> + +After you've finished your document, naturally you will want to +print it. This involves invoking groff from the command line. +In all likelihood, you already know how to do this, but in case +you don't, here are two common ways to do it. +<p> +<pre> + groff -mom -l <filename> + groff -mom <filename> | lpr +</pre> + +In the first, the <strong>-l</strong> option to groff tells +groff to send the output to your printer. In the second, you're +doing the same thing, except you're telling groff to pipe the +output to your printer. Basically, they're the same thing. The +only advantage to the second is that your system may be set up +to use something other than <strong>lpr</strong> as your print +command, in which case, you can replace <strong>lpr</strong> +with whatever is appropriate to your box. +<p> +Sadly, it is well beyond the scope of this manual to tell you +how to set up a printing system. See the README file for +minimum requirements to run groff with <strong>mom</strong>. + +<a name="USING_PREVIEWING"> + <h2><u>How to preview documents</u></h2> +</a> + +Other than printing out hard copy, there are two well-established +methods for previewing your work. Both assume you have a working +X server. +<p> +Groff itself comes with a quick and dirty previewer called +gxditview. Invoke it with +<p> +<pre> + groff -X -mom <filename> +</pre> + +It's not particularly pretty, doesn't have many navigation +options, requires a lot of work if you want to use other than +the "standard" groff PostScript fonts, and occasionally +has difficulty accurately reproducing some of +<strong>mom</strong>'s macro effects +(<a href="goodies.html#SMARTQUOTES">smartquotes</a> +and +<a href="goodies.html#LEADER">leaders</a> +come to mind). What it does have going for it is that it's fast and +doesn't gobble up system resources. +<p> +A surer way to preview documents is with <strong>gv</strong> +(ghostview). This involves processing documents with groff, +directing the output to a temporary (PostScript) file, then opening +the temporary file in <strong>gv</strong>. While that may sound +like a lot of work, I've set up my editor (elvis) to do it for me. +Whenever I'm working on a document that needs previewing/checking, +I fire up <strong>gv</strong> with the "Watch File" +option turned on. To look at the file, I tell elvis to process +it (with groff) and send it to the temporary file (<kbd>groff +-mom filename > filename.ps</kbd>), then open the file inside +<strong>gv</strong>. Ever after, when I want to look at any changes +I make, I simply tell elvis to work his magic again. The Watch File +option in <strong>gv</strong> registers that the file has changed, +and automatically loads the new version. Voilą! -- instant previewing. + +<p> +<hr> +<a href="toc.html">Back to Table of Contents</a> +</body> +</html> |