diff options
Diffstat (limited to 'contrib/mom/momdoc/using.html')
| -rw-r--r-- | contrib/mom/momdoc/using.html | 298 |
1 files changed, 0 insertions, 298 deletions
diff --git a/contrib/mom/momdoc/using.html b/contrib/mom/momdoc/using.html deleted file mode 100644 index 287b0ee9..00000000 --- a/contrib/mom/momdoc/using.html +++ /dev/null @@ -1,298 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- -This file is part of groff, the GNU roff type-setting system. - -Copyright (C) 2004, 2005, 2006, 2009 Free Software Foundation, Inc. -Written by Peter Schaffter. - -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 the -Invariant Sections being this comment section, 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=iso-8859-1"/> -<title>Using mom</title> -</head> -<body bgcolor="#dfdfdf"> - -<!-- ==================================================================== --> - -<a name="TOP"></a> - -<p> -<a href="typesetting.html#TOP">Next</a> -<a href="definitions.html#TOP">Prev</a> -<a href="toc.html">Back to Table of Contents</a> -</p> - -<a name="USING"><h1 align="center"><u>Using mom</u></h1></a> - -<p> -<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> -</p> - -<hr/> - -<h2><a name="USING_INTRO"><u>Introduction</u></a></h2> - -<p> -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> - -<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 document design. 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. -</p> - -<a name="USING_MACROS"><h2><u>How to input mom's macros</u></h2></a> - -<p> -Regardless of which way you use <strong>mom</strong>, the -following apply. -</p> - -<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 colourizing macros and - inlines to half-intensity can be enough to make text stand - out clearly from formatting commands. - </p> - - </li> - - <li> - All <strong>mom</strong>'s macros begin with a period - (dot) and must be entered in upper case (capital) - letters. - </li> - - <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> - - <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> - - <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, -4</kbd>). - </li> - - <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. <kbd>4P, .5i, 2v</kbd>). - </li> - - <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> - - <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: - - <pre> - .SUBTITLE "An In-Depth Consideration of the \ - Implications of Forty-Two as the Meaning of Life, \ - The Universe, and Everything" - </pre> - </li> -</ol> - -<p> -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. - -<pre> - .TITLE "My Pulitzer Novel" - .AUTHOR "Joe Blow" - .CHAPTER 1 - \# - .DOCTYPE CHAPTER - .PRINTSTYLE TYPESET - \# - .FAM P - .PT_SIZE 10 - .LS 12 - \# - .START -</pre> -</p> - -<a name="USING_INVOKING"><h2><u>Printing — invoking groff with mom</u></h2></a> - -<p> -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. - -<pre> - groff -mom -l <filename> - groff -mom <filename> | lpr -</pre> -</p> - -<p> -In the first, the <kbd>-l</kbd> 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 <kbd>lpr</kbd> with whatever is appropriate to your box. -</p> - -<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>. -</p> - -<p> -<strong>NOTE FOR ADVANCED USERS:</strong> I've sporadically -had groff choke on perfectly innocent sourced files within -<strong>mom</strong> documents. You'll know you have this problem -when groff complains that it can't find the sourced file even when -you can plainly see that the file exists, and that you've given -<kbd>.so</kbd> the right path and name. Should this happen, pass -groff the <kbd>-U</kbd> (unsafe mode) option along with the other -options you require. Theoretically, you only need <kbd>-U</kbd> -with <kbd>.open, .opena, .pso, .sy,</kbd> and <kbd>.pi</kbd>, -however reality seems, at times, to dictate otherwise. -</p> - -<a name="USING_PREVIEWING"><h2><u>How to preview documents</u></h2></a> - -<p> -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> - -<p> -Groff itself comes with a quick and dirty previewer called -gxditview. Invoke it with - -<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> - -<p> -A surer way to preview documents is with <strong>gv</strong> -(ghostview). This involves processing documents with groff, -and directing the output to a PostScript file, like this, - -<pre> - groff -mom filename > filename.ps -</pre> - -then opening the .ps file in <strong>gv</strong>. -</p> - -<p> -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 a 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/> - -<p> -<a href="typesetting.html#TOP">Next</a> -<a href="definitions.html#TOP">Prev</a> -<a href="#TOP">Top</a> -<a href="toc.html">Back to Table of Contents</a> -</p> - -</body> -</html> -<!-- vim: fileencoding=latin1: nomodified: ---> |