diff options
Diffstat (limited to 'contrib/mom/momdoc/using.html')
| -rw-r--r-- | contrib/mom/momdoc/using.html | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/using.html b/contrib/mom/momdoc/using.html new file mode 100644 index 0000000..c93e385 --- /dev/null +++ b/contrib/mom/momdoc/using.html @@ -0,0 +1,319 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004-2020 Free Software Foundation, Inc. +Written by Peter Schaffter (peter@schaffter.ca). + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Using mom</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> + <tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="typesetting.html#top">Next: The typesetting macros</a></td> + </tr> + </table> + +<h1 id="using" class="docs">Using mom</h1> + +<div style="text-align: left; margin-left: 33%"> +<ul class="no-enumerator" style="margin-left: -2.5em;"> + <li><a href="#using-intro">Introduction</a></li> + <li><a href="#using-macros">How to input mom’s macros</a></li> + <li><a href="#viewing">Processing and viewing documents</a> + <ul> + <li class="item"><a href="#pdf">Mom and PDF</a></li> + <li class="item"><a href="#pdfmom">pdfmom</a></li> + </ul></li> + <li><a href="#previewing">Automatic previewing of documents</a></li> +</ul> +</div> + +<div class="rule-short" style="margin-top: 18px;"><hr/></div> + +<h2 id="using-intro" class="docs">Introduction</h2> + +<p> +As explained in the section +<a href="intro.html#top">What is mom?</a>, +mom can be used in two ways: for straightforward typesetting or for +document processing. The difference between the two is that in +straightforward typesetting, every macro is a literal 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>.HEADING</kbd> for different levels of heads, +<kbd>.FOOTNOTE</kbd> for footnotes, etc.) that perform typesetting +operations automatically. +</p> + +<p> +You tell mom that you want to use the document processing macros +with the +<a href="docprocessing.html#start">START</a> +macro. After START, mom determines the appearance of +text following the markup tags automatically, although you, the +user, can easily change how the tags are interpreted. +</p> + +<h2 id="using-macros" class="docs">How to input mom’s macros</h2> + +<p> +Regardless of whether you’re preparing a term paper or making a +flyer for your lost dog, the following apply. +</p> + +<ol style="margin-top: -.5em; margin-bottom: -.5em;"> + <li> + You need a good text editor for inputting mom files. + <br/> + <span style="display: block; margin-top: .25em; margin-bottom: .5em;"> + I cannot recommend highly enough that you use an editor that + lets you write syntax highlighting rules for mom’s + macros and + <a href="definitions.html#inlines">inline escapes</a>. + Simply colourizing macros and inlines to half-intensity can be + enough to make text stand out clearly from formatting commands. + Mom herself comes with a complete set of syntax highlighting + rules for the vim editor. A number of freely available editors + come with groff syntax highlighting rules, which are sufficient + for mom files, though not as colourful or complete as the vim + rules that ship with mom. + </span> + </li> + <li> + Macros begin with a period (dot) at the left margin of your text + editor’s screen, and must be entered in upper case (capital) + letters. + </li> + <li> + Macro + <a href="definitions.html#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. + </li> + <li> + Arguments to a macro must appear on the same line as the + macro. + <br/> + <span style="display: block; margin-top: .25em; margin-bottom: .5em;"> + If the argument list is very long, you may use the + backslash character (<kbd>\</kbd>) to break the line visually. + From groff’s point of view, the backslash and newline are + invisible. Thus, for example, + <span class="pre" style="margin-bottom: -2.25em"> + .HEADING_STYLE 1 FAMILY Garamond FONT B SIZE +2 + </span> + and + <span class="pre" style="margin-bottom: -2.25em"> + .HEADING_STYLE 1 \ + FAMILY Garamond \ + FONT B \ + SIZE +2 + </span> + </span> + are exactly equivalent. + </li> + <li> + Any argument (except a + <a href="definitions.html#stringargument">string argument</a>) + that is not a digit must be entered in upper case + (capital) letters. + </li> + <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. <kbd>+2</kbd>). + </li> + <li> + Any argument that requires a + <a href="definitions.html#unitofmeasure">unit of measure</a> + must have the unit appended directly to the argument, with no + intervening space (e.g. <kbd>.5i</kbd>). + </li> + <li> + <a href="definitions.html#stringargument">String arguments</a>, + in the sense of this manual, must be surrounded by double-quotes + (e.g. <kbd>"text"</kbd>). Multiple + string arguments are separated from each other by spaces (with + each argument surrounded by double-quotes). + <br/> + <span style="display: block; margin-top: .25em; margin-bottom: .5em;"> + If a string argument becomes + uncomfortably long, you may break it into two or more lines + with the backslash character. + <span class="pre"> + .SUBTITLE "An In-Depth Consideration of the \ + Implications of Forty-Two as the Answer to Life, \ + The Universe, and Everything" + </span> + </span> + </li> +</ol> + +<div class="box-tip"> +<p class="tip"> +<span class="tip">Tip:</span> +It’s important that your documents be easy to read and +understand 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 comment line. In groff, that’s +done with <kbd>\#</kbd> (backslash-pound) or <kbd>.\"</kbd> +(period-backslash-doublequote) on a line by itself. Either +instructs groff to ignore the remainder of the line, which may or +may not contain text. Consider the following, which is a template +for starting the chapter of a book. +<br/> +<span class="pre-in-pp"> + \# Reference/meta-data + .TITLE "My Pulitzer Novel" + .AUTHOR "Joe Blow" + .CHAPTER 1 + \# Template + .DOCTYPE CHAPTER + .PRINTSTYLE TYPESET + \# Type style + .FAM P + .PT_SIZE 10 + .LS 12 + \# + .START +</span> +You may also, if you wish, add a comment to the end of a line with +<kbd>\"</kbd> (no period), like this: +<br/> +<span class="pre-in-pp"> + .FAMILY P \" Maybe Garamond instead? +</span> +</p> +</div> + +<h2 id="viewing" class="docs">Processing and viewing documents</h2> + +<p> +The most basic command-line usage for processing a file formatted +with the mom macros is +<br/> +<span class="pre-in-pp"> + groff -mom filename.mom > filename.ps +</span> +which processes the .mom file and dumps the output into a +viewable/printable PostScript file. +</p> + +<h3 id="pdf" class="docs">Mom and PDF</h3> + +<p> +Adobe’s Portable Document Format (PDF) has largely supplanted +PostScript, of which it is a subset, as the standard for typeset +documents. While printed versions of documents in either format +will be identical, PDF documents, when viewed at the screen, may +also contain clickable links and a number of other special features. +</p> + +<p> +As of version 2.0, mom supports full PDF integration. The creation +and processing of mom files into PostScript documents remains +unchanged from 1.x, but the expected and recommended format of final +documents is now PDF. +</p> + +<p> +The manual, +<a href="http://www.schaffter.ca/mom/pdf/mom-pdf.pdf"><span class="book-title">Producing PDFs with groff and mom</span></a>, +explains and demonstrates the PDF-specific macros that are available +in mom, as well as the use of <strong>pdfmom</strong>, the +recommended way to process mom files. +</p> + +<h4 id="pdfmom" class="docs">pdfmom</h4> + +<p> +Groff provides more than one way to generate PDF documents, +but when processing files formatted with the mom macros, +<strong>pdfmom</strong> is the recommended and most robust way to do +it: +<br/> +<span class="pre-in-pp"> + pdfmom filename.mom > filename.pdf +</span> +<strong>pdfmom</strong> is a wrapper around groff, and accepts all +groff’s command-line options as listed in the groff manpage. +Full usage is explained in the manual, +<a href="http://www.schaffter.ca/mom/pdf/mom-pdf.pdf"><span class="book-title">Producing PDFs with groff and mom</span></a>. +</p> + +<p> +PDF links in a document, including linked entries in the +Table of Contents, are identified by colour. When printing +documents with links, you will most likely not want the link +text coloured. The groff option, <kbd>-c</kbd>, disables colour +throughout a document; thus, when preparing a document for printing, +you should use: +<br/> +<span class="pre-in-pp"> + pdfmom -c filename.mom > filename.pdf +</span> +<strong>pdfmom</strong> tends to produce large files. You may +reduce their size by piping them through ps2pdf: +<br/> +<span class="pre-in-pp"> + pdfmom -c filename.mom | ps2pdf - filename.pdf +</span> +Be aware, though, that files piped through ps2pdf will lose some pdf +metadata, notably the document window title set with PDF_TITLE. +</p> + +<h2 id="previewing" class="docs">Automatic previewing of documents</h2> + +<p> +Most PDF viewers have a “Watch File” option, which +automatically updates a displayed document whenever there’s +a change. This is useful when preparing documents that require +judgment calls. I recommend creating a keymapping in your +text editor that both saves the mom file and processes it with +<strong>pdfmom</strong>. The displayed PDF then automatically +reflects whatever changes you save to the mom file. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> + <tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 33%; text-align: right;"><a href="typesetting.html#top">Next: The typesetting macros</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> |