contrib/mom/momdoc/letters.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3 This file is part of groff, the GNU roff type-setting system.
   4
   5 Copyright (C) 2004-2014 Free Software Foundation, Inc.
   6 Written by Peter Schaffter (peter@schaffter.ca).
   7
   8 Permission is granted to copy, distribute and/or modify this document
   9 under the terms of the GNU Free Documentation License, Version 1.3 or
  10 any later version published by the Free Software Foundation; with the
  11 Invariant Sections being this comment section, with no Front-Cover
  12 Texts, and with no Back-Cover Texts.
  13
  14 A copy of the Free Documentation License is included as a file called
  15 FDL in the main directory of the groff source package.
  16 -->
  17
  18 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  19 <html xmlns="http://www.w3.org/1999/xhtml">
  20
  21 <head>
  22   <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
  23   <title>Mom -- Writing letters</title>
  24   <link rel="stylesheet" type="text/css" href="stylesheet.css" />
  25 </head>
  26
  27 <body style="background-color: #f5faff;">
  28
  29 <!-- ==================================================================== -->
  30
  31 <div id="top" class="page">
  32
  33 <!-- Navigation links -->
  34 <table style="width: 100%;">
  35 <tr>
  36   <td><a href="toc.html">Back to Table of Contents</a></td>
  37   <td style="text-align: right;"><a href="macrolist.html#top">Next: Quick reference guide</a></td>
  38 </tr>
  39 </table>
  40
  41 <h1 class="docs">Writing letters</h1>
  42
  43 <div style="width: 33%; margin: auto;">
  44 <ul class="no-enumerator">
  45   <li><a href="#letters-intro">Introduction</a>
  46   <li><a href="#letters-tutorial">Tutorial</a></li>
  47   <li><a href="#letters-defaults">Mom&#8217;s default letter style</a>
  48   <li><a href="#index-letters-macros">The letter macros</a>
  49 </ul>
  50 </div>
  51
  52 <div class="rule-medium"><hr/></div>
  53
  54 <h2 id="letters-intro" class="docs">Introduction</h2>
  55
  56 <p>
  57 Mom&#8217;s simple but effective letter-writing macros are a subset
  58 of the
  59 <a href="docprocessing.html#docprocessing">document processing macros</a>,
  60 designed to ease the creation of correspondence.
  61 </p>
  62
  63 <p>
  64 Because the letter macros are a subset of the document processing
  65 macros, you can use
  66 <a href="definitions.html#controlmacro">control macros</a>
  67 to design correspondence to your own specifications.  However,
  68 mom makes no pretence of providing complete design flexibility in
  69 the matter of letters, which are, after all, simple communicative
  70 documents whose only real style requirements are that they be neat
  71 and professional-looking.
  72 </p>
  73
  74 <div class="examples-container" style="margin-top: 1.5em; margin-bottom: 1.5em;">
  75 <h3 id="letters-tutorial" class="docs">Tutorial &ndash; writing letters</h3>
  76
  77 <p>
  78 Mom letters begin, like all mom-processed documents, with
  79 <a href="docprocessing.html#reference-macros">reference macros</a>
  80 (in this case,
  81 <a href="docprocessing.html#author">AUTHOR</a>),
  82 a
  83 <a href="docprocessing.html#doctype">DOCTYPE</a>
  84 (LETTER, obviously), the essential
  85 <a href="docprocessing.html#printstyle">PRINTSTYLE</a>
  86 macro, and
  87 <a href="docprocessing.html#start">START</a>,
  88 like this:
  89 <br/>
  90 <span class="pre-in-pp">
  91   .AUTHOR    "Yannick P. Guique"
  92   .DOCTYPE    LETTER
  93   .PRINTSTYLE TYPESET
  94   .START
  95 </span>
  96 PRINTSTYLE, above, could also be <kbd>TYPEWRITE</kbd>. Mom has no
  97 objection to creating letters that look like they were typed on an
  98 Underwood by a shapely secretary with 1940s gams.
  99 </p>
 100
 101 <p>
 102 Please note that if you choose <kbd>PRINTSTYLE TYPEWRITE</kbd>,
 103 there's no need to give the <kbd>SINGLESPACE</kbd> option, as this
 104 is the unalterable default for letters.
 105 </p>
 106
 107 <p>
 108 After the START macro, you enter headers pertinent to your letter:
 109 the date, the addressee (in business correspondence, typically both
 110 name and address), the addresser (that&#8217;s you; in business
 111 correspondence, typically both name and address), and a greeting
 112 (in full, eg &#8220;Dear Mr. Smith,&#8221; or &#8220;Dear
 113 Mr. Smith:&#8221;).
 114 </p>
 115
 116 <p>
 117 The macros for entering the headers are simple (they&#8217;re not even
 118 <a href="definitions.html#toggle">toggles</a>):
 119 <br/>
 120 <span class="pre-in-pp">
 121   .DATE
 122   .TO
 123   .FROM
 124   .GREETING
 125 </span>
 126 You may enter them in any order you like, except for GREETING, which
 127 must come last.  Mom ignores any headers you omit and spaces the
 128 letter&#8217;s opening according to what you do include.  See
 129 <a href="#letters-defaults">Default for letters</a>
 130 to find out how mom formats the headers.
 131 </p>
 132
 133 <p>
 134 Once you&#8217;ve filled in what you need to get a letter started,
 135 simply type the letter, introducing each and every paragraph,
 136 including the first, with the
 137 <a href="docelement.html#pp">PP</a>
 138 macro.
 139 </p>
 140
 141 <p>
 142 At the end of the letter, should you wish a closing (&#8220;Yours
 143 truly,&#8221; &#8220;Sincerely,&#8221; &#8220;Hugs and
 144 kisses&#8221;), invoke the macro, <kbd>.CLOSING</kbd>, on a line
 145 by itself, and follow it with the text of the closing. <b>N.B.</b>
 146 Don&#8217;t put your name here; mom supplies it automatically from
 147 <a href="docprocessing.html#author">AUTHOR</a>),
 148 with enough space to leave room for your signature.  If you omit the
 149 closing, mom simply adds your name (from AUTHOR), again with enough
 150 space for your signature.
 151 </p>
 152
 153 <p>
 154 Assuming our tutorial letter is for business correspondence,
 155 here&#8217;s what the complete letter looks like.
 156 <br/>
 157 <span class="pre-in-pp">
 158   .AUTHOR    "Yannick P. Guique"
 159   .DOCTYPE    LETTER
 160   .PRINTSTYLE TYPESET
 161   .START
 162   .DATE
 163   August 25, 2010
 164   .TO
 165   GUILLAUME BARRIÈRES
 166   Minidoux Corporation
 167   5000 Pannes Drive
 168   Redmond, Virginia
 169   .FROM
 170   Y.P. GUIQUE
 171   022 Umask Road
 172   St-Sauveur-en-dehors-de-la-mappe, Québec
 173   .GREETING
 174   Dear Mr. Barrières,
 175   .PP
 176   It has come to my attention that you have once again been
 177   lobbying the US government to prohibit the use of open source
 178   software by endeavouring to outlaw so-called "warranty
 179   free" applications.
 180   .PP
 181   I feel it is my duty to inform you that the success of your
 182   operating system relies heavily on open source programs and
 183   protocols, notably TCP/IP.
 184   .PP
 185   Therefore, in the interests of your corporation&#8217;s fiscal health,
 186   I strongly advise that you withdraw support for any US
 187   legislation that would cripple or render illegal open source
 188   development.
 189   .CLOSING
 190   Sincerely,
 191 </span>
 192 This produces a letter with headers that follow the North American
 193 standard for business correspondence.  If you&#8217;d prefer another style
 194 of correspondence, for example, British, you&#8217;d set up the same
 195 letter like this:
 196 <br/>
 197 <span class="pre-in-pp">
 198   .AUTHOR    "Yannick P. Guique"
 199   .DOCTYPE    LETTER
 200   .PRINTSTYLE TYPESET
 201   .START
 202   .FROM
 203   .RIGHT
 204   Y.P. GUIQUE
 205   022 Umask Road
 206   St-Sauveur-en-dehors-de-la-mappe, Québec
 207   .TO
 208   GUILLAUME BARRIÈRES
 209   Minidoux Corporation
 210   5000 Pannes Drive
 211   Redmond, Virginia
 212   .DATE
 213   .RIGHT
 214   August 25, 2004
 215   .GREETING
 216   Dear Mr. Barrières,
 217 </span>
 218 Notice the use of <kbd>.RIGHT</kbd> after <kbd>.FROM</kbd> and
 219 <kbd>.DATE</kbd> in this example, used to change the default quad
 220 for these macros.
 221 </p>
 222 </div>
 223
 224 <h2 id="letters-defaults" class="docs">Default letter style</h2>
 225
 226 <p>
 227 In letters, if the order of header macros is
 228 </p>
 229 <ol style="margin-top: -.5em;">
 230   <li><kbd>.DATE</kbd></li>
 231   <li><kbd>.TO</kbd>&nbsp;&nbsp;(the addressee)</li>
 232   <li><kbd>.FROM</kbd>&nbsp;&nbsp;(the addresser)</li>
 233   <li><kbd>.GREETING</kbd>&nbsp;&nbsp;(&#8220;Dear Whoever,&#8221; &#8220;To Whom It May Concern,&#8221; etc.)</li>
 234 </ol>
 235 <p style="margin-top: -.5em;">
 236 mom sets
 237 </p>
 238 <ul style="margin-top: -.5em;">
 239   <li>the date flush right, page right, at the top of page one,
 240       with a gap of two linespaces underneath
 241   </li>
 242   <li>the addressee (<kbd>.TO</kbd>) in a block flush left, page
 243       left, with a gap of one linespace underneath
 244   </li>
 245   <li>the addresser (<kbd>.FROM</kbd>) in a block flush left, page
 246       left, with a gap of one linespace underneath
 247   </li>
 248   <li>the greeting flush left, with a gap of one linespace
 249       underneath
 250   </li>
 251 </ul>
 252 <p style="margin-top: -.5em;">
 253 which is the standard for North American business correspondence.
 254 </p>
 255
 256 <p>
 257 If you switch the order of <kbd>.DATE</kbd>, <kbd>.TO</kbd> and/or
 258 <kbd>.FROM</kbd>, mom sets all the headers
 259 flush left, with a gap of one linespace underneath each.  (The
 260 default left quad of any header can be changed by invoking the
 261 <kbd>.RIGHT</kbd> macro, on a line by itself, immediately before
 262 inputting the text of the header.)
 263 </p>
 264
 265 <p>
 266 Following the headers, mom sets
 267 </p>
 268 <ul style="margin-top: -.5em;">
 269   <li>the body of the letter justified</li>
 270   <li>in multi-page letters:
 271   <ul style="margin-left: -.5em;">
 272     <li>a footer indicating there&#8217;s a next page (of the form <kbd>.../#</kbd>)</li>
 273     <li>the page number at the top of every page after page one</li>
 274   </ul></li>
 275   <li>the closing/signature lines flush left, indented halfway across the page</li>
 276 </ul>
 277
 278 <p>
 279 Other important style defaults are listed below, and may be changed
 280 via the
 281 <a href="typesetting.html#top">typesetting macros</a>
 282 or the document processing
 283 <a href="definitions.html#controlmacro">control macros</a>
 284 prior to
 285 <a href="docprocessing.html#start">START</a>.
 286 Assume that any style parameter not listed below is the same as for
 287 any document processed with
 288 <a href="docprocessing.html#typeset-defaults">PRINTSTYLE <kbd>TYPESET</kbd></a>
 289 or
 290 <a href="docprocessing.html#typewrite-defaults">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>.
 291 </p>
 292
 293 <div class="defaults-container" style="padding-bottom: 8px;">
 294 <span class="pre defaults">
 295   PARAMETER                 PRINTSTYLE TYPESET         PRINTSTYLE TYPEWRITE
 296
 297   Paper size                8.5 x 11 inches            8.5 x 11 inches
 298   Left/right margins        1.125 inches               1.125 inches
 299   Header margin             3.5 picas                  3.5 picas
 300    (for page numbers)
 301   Header gap                3 picas                    3 picas
 302    (for page numbers)
 303   Family                    Times Roman                Courier
 304   Font                      roman                      roman
 305   Point size                12                         12
 306   Line space                13.5                       12 (ie singlespaced)
 307   Paragraph indent          3 ems                      3 picas
 308   Spaced paragraphs         yes                        no
 309   Footers*                  yes                        yes
 310   Footer margin             3 picas                    3 picas
 311   Footer gap                3 picas                    3 picas
 312   Page numbers              top, centred               top, centred
 313
 314   *Footers contain a &quot;next page&quot; number of the form .../#
 315 </span>
 316 </div>
 317
 318 <div class="rule-medium"><hr/></div>
 319
 320
 321 <div class="macro-list-container">
 322 <h3 id="index-letters-macros" class="macro-list">The letter macros</h3>
 323 <p style="margin-left: 9px; margin-top: -1.5em;">
 324 All letter macros must come after
 325 <a href="docprocessing.html#start">START</a>,
 326 except NO_SUITE, which must come after
 327 <a href="docprocessin.html#start">PRINTSTYLE</a>
 328 and before
 329 <a href="docprocessing.html#start">START</a>.
 330 </p>
 331
 332 <ul class="macro-list" style="margin-top: -.75em;">
 333   <li><a href="#date">DATE</a></li>
 334   <li><a href="#to">TO</a></li>
 335   <li><a href="#from">FROM</a></li>
 336   <li><a href="#greeting">GREETING</a></li>
 337   <li><a href="#closing">CLOSING</a>
 338   <ul style="margin-left: -.5em;">
 339     <li><a href="#closing-indent">CLOSING_INDENT</a></li>
 340     <li><a href="#signature-indent">SIGNATURE_INDENT</a></li>
 341   </ul></li>
 342   <li><a href="#no-suite">NO_SUITE</a> &ndash; turn the &#8220;next page&#8221; footer off</li>
 343 </ul>
 344 </div>
 345
 346 <!-- -DATE- -->
 347
 348 <div id="date" class="box-macro-args">
 349 Macro: <b>DATE</b>
 350 </div>
 351
 352 <p>
 353 Invoke <kbd>.DATE</kbd> on a line by itself, with the date
 354 underneath, like this:
 355 <br/>
 356 <span class="pre-in-pp">
 357   .DATE
 358   October 31, 2012
 359 </span>
 360 If you wish to change the default quad direction for the date,
 361 enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself,
 362 immediately after <kbd>.DATE</kbd>.
 363 </p>
 364
 365 <p>
 366 If you wish to insert additional space between the date and any
 367 letter header that comes after it, do so after inputting the date,
 368 not at the top of the next header macro, like this:
 369 <br/>
 370 <span class="pre-in-pp">
 371   .DATE
 372   October 31, 2012
 373   .SPACE  \"Or, more simply, .SP
 374 </span>
 375 If you wish to remove the default space,
 376 <br/>
 377 <span class="pre-in-pp">
 378   .SPACE -1v  \"Or, more simply, .SP -1v
 379 </span>
 380 will do the trick.
 381 </p>
 382
 383 <!-- -TO- -->
 384
 385 <div id="to" class="box-macro-args">
 386 Macro: <b>TO</b>
 387 </div>
 388
 389 <p>
 390 Invoke <kbd>.TO</kbd> on a line by itself, with the name and address
 391 of the addressee underneath, like this:
 392 <br/>
 393 <span class="pre-in-pp">
 394   .TO
 395   JOHN SMITH
 396   10 Roberts Crescent
 397   Bramladesh, Ont.
 398 </span>
 399 If you wish to change the default quad direction for the address,
 400 enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself,
 401 immediately after <kbd>.TO</kbd>.
 402 </p>
 403
 404 <p>
 405 If you wish to insert additional space between the address and
 406 any letter header that comes after it, do so after inputting the
 407 address, not at the top of the next header macro, like this:
 408 <br/>
 409 <span class="pre-in-pp">
 410   .TO
 411   JOHN SMITH
 412   10 Roberts Crescent
 413   Bramladesh, Ont.
 414   .SPACE  \"Or, more simply, .SP
 415 </span>
 416 If you wish to remove the default space,
 417 <br/>
 418 <span class="pre-in-pp">
 419   .SPACE -1v  \"Or, more simply, .SP -1v
 420 </span>
 421 will do the trick.
 422 </p>
 423
 424 <!-- -FROM- -->
 425
 426 <div id="from" class="box-macro-args">
 427 Macro: <b>FROM</b>
 428 </div>
 429
 430 <p>
 431 Invoke <kbd>.FROM</kbd> on a line by itself, with the name and
 432 address of the addresser underneath, like this:
 433 <br/>
 434 <span class="pre-in-pp">
 435   .FROM
 436   JOE BLOW
 437   15 Brunette Road
 438   Ste-Vieille-Andouille, Québec
 439 </span>
 440 If you wish to change the default quad direction for the address,
 441 enter <kbd>.LEFT</kbd> or <kbd>.RIGHT</kbd>, on a line by itself,
 442 immediately after <kbd>.FROM</kbd>.
 443 </p>
 444
 445 <p>
 446 If you wish to insert additional space between the address and
 447 any letter header that comes after it, do so after inputting the
 448 address, not at the top of the next header macro, like this:
 449 <br/>
 450 <span class="pre-in-pp">
 451   .FROM
 452   JOE BLOW
 453   15 Brunette Road
 454   Ste-Vieille-Andouille, Québec
 455   .SPACE  \"Or, more simply, .SP
 456 </span>
 457 If you wish to remove the default space,
 458 <br/>
 459 <span class="pre-in-pp">
 460   .SPACE -1v  \"Or, more simply, .SP -1v
 461 </span>
 462 will do the trick.
 463 </p>
 464
 465 <!-- -GREETING- -->
 466
 467 <div id="greeting" class="box-macro-args">
 468 Macro: <b>GREETING</b>
 469 </div>
 470
 471 <p>
 472 Invoke <kbd>.GREETING</kbd> on a line by itself, with the full
 473 salutation you want for the letter underneath, like this:
 474 <br/>
 475 <span class="pre-in-pp">
 476   .GREETING
 477   Dear Mr. Smith,
 478 </span>
 479 </p>
 480
 481 <!-- -CLOSING- -->
 482
 483 <div id="closing" class="box-macro-args">
 484 Macro: <b>CLOSING</b>
 485 </div>
 486
 487 <p>
 488 Invoke <kbd>.CLOSING</kbd> on a line by itself after the body of
 489 the letter, with the closing you&#8217;d like (eg &#8220;Yours
 490 truly,&#8221;) underneath, like this:
 491 <br/>
 492 <span class="pre-in-pp">
 493   .CLOSING
 494   Yours truly,
 495 </span>
 496 </p>
 497
 498 <div class="box-tip" style="background-color: #E3D2B1;">
 499 <p class="tip">
 500 <span class="tip" style="display: inline-block; padding-bottom: .5em; color: #000056;">CLOSING control macros and defaults</span>
 501 <br/>
 502 Two macros control the behaviour of <kbd>.CLOSING</kbd>:
 503 </p>
 504 <ul style="margin-top: -1.25em;">
 505   <li>CLOSING_INDENT</li>
 506   <li>SIGNATURE_SPACE</li>
 507 </ul>
 508
 509 <p id="closing-indent" style="margin-top: -.25em;">
 510 The first, CLOSING_INDENT, indicates the distance from the left
 511 margin you&#8217;d like to have your closing indented.  It takes a
 512 single
 513 <a href="definitions.html#numericargument">numeric argument</a>
 514 and must have a
 515 <a href="definitions.html#unitofmeasure">unit of measure</a>
 516 appended to it, unless you want an indent of 0 (zero).  Mom&#8217;s
 517 default is one half the width of the letter&#8217;s line length
 518 (ie halfway across the page).  If you wanted, instead, an indent of
 519 6
 520 <a href="definitions.html#picaspoints">picas</a>,
 521 you&#8217;d do it like this:
 522 <br/>
 523 <span class="pre-in-pp">
 524   .CLOSING_INDENT 6P
 525 </span>
 526 Or, if you wanted to have no indent at all:
 527 <br/>
 528 <span class="pre-in-pp">
 529   .CLOSING_INDENT 0
 530 </span>
 531 </p>
 532
 533 <p id="signature-space" style="margin-top: -1.25em;">
 534 The second, SIGNATURE_SPACE, controls how much room to leave for the
 535 signature.  It takes a single
 536 <a href="definitions.html#numericargument">numeric argument</a>
 537 and must have a
 538 <a href="definitions.html#unitofmeasure">unit of measure</a>
 539 appended to it.  Mom&#8217;s default is 3 line spaces, but if you
 540 wanted to change that to, say, 2 line spaces, you&#8217;d do:
 541 <br/>
 542 <span class="pre-in-pp">
 543   .SIGNATURE_SPACE 2v
 544 </span>
 545 </p>
 546 </div>
 547
 548 <!-- -NO_SUITE- -->
 549
 550 <div id="no-suite" class="box-macro-args" style="margin-top: 2em;">
 551 Macro: <b>NO_SUITE</b>
 552 </div>
 553
 554 <p>
 555 If you don&#8217;t want mom to print a &#8220;next page&#8221;
 556 number at the bottom of multi-page letters, invoke
 557 <kbd>.NO_SUITE</kbd>, on a line by itself, prior to
 558 <a href="docprocessing.html#start">START</a>.
 559 </p>
 560
 561 <div class="rule-long"><hr/></div>
 562
 563 <!-- Navigation links -->
 564 <table style="width: 100%; margin-top: 12px;">
 565 <tr>
 566   <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
 567   <td style="width: 33%; text-align: center;"><a href="#top">Top</a></td>
 568   <td style="width: 33%; text-align: right;"><a href="macrolist.html">Next: Quick reference guide</a></td>
 569 </tr>
 570 </table>
 571
 572 </div>
 573
 574 <div class="bottom-spacer"><br/></div>
 575
 576 </body>
 577 </html>
 578 <!-- vim: fileencoding=utf-8: nomodified: -->