home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource3 / 183_01 / letter.doc < prev    next >
Encoding:
Text File  |  1986-02-04  |  9.6 KB  |  241 lines
  1.                                 Letter: A Letter Processor
  2.  
  3.  
  4. Raison d'Etre
  5.  
  6.   I don't know about everyone else, but I write about ten to twenty one page
  7.   letters a week.
  8.  
  9.   Although I have several word processors (Microsoft Word, WordStar, and
  10.   Unix's nroff, plus a MacIntosh just to hit the high spots), none are
  11.   adequate for what should be a very simple task, namely writing a letter!
  12.   This is not a design fault in them; rather it is one of the drawbacks of
  13.   applying general purpose tools to a specific problem.
  14.  
  15.   I have several requirements for a letter formatting program. They are:
  16.  
  17.   o  The body of the letter must be vertically centered on the page.
  18.  
  19.   o  The address should be extracted and redirected to a file for later
  20.      printing on an envelope or label.
  21.  
  22.   o  Itegral parts of a letter (such as dates, salutations, etc.) should be
  23.      supported by the program.
  24.  
  25.   
  26.   All of the above mentioned processors (even nroff!) gagged at this list.
  27.   After making do with various kludges, I finally took a day off and wrote
  28.   letter, which seems an adequate solution to the problem.
  29.  
  30. What Letter Does
  31.  
  32.   Letter is a very specific program, but it excels at formatting one page
  33.   documents, especially letters. It automatically performs vertical centering
  34.   and supports enough rudimentary text processing features to allow
  35.   considerable format flexibility. It dates a letter, supports address
  36.   redirection, and provides a shorthand for filling in the closing salutation
  37.   (or whatever the 'Sincerely yours' stuff is called!). It will justify,
  38.   center, underline, and doublestrike just like a real word processor.
  39.  
  40.   It will not number the page, format two page letters, or do anything
  41.   fancier than the above list. It is very precisely defined to do one thing
  42.   (and only one thing) fairly well.
  43.  
  44. Using Letter
  45.  
  46.   Letter is distributed as the following files:
  47.  
  48.   letter.c     The actual  letter formatting/printing  program.  The  current
  49.                version has been tested using the Wizard C compiler and MS-DOS
  50.                3.1. The  only nonportable function that I can think of is the
  51.                one that gets the date from the operating system.
  52.   letter.exe   Executable version of same.
  53.   address.c    Address printing program
  54.   address.exe  Executable version.
  55.  
  56.  
  57.                                             1
  58.  
  59.  
  60.  
  61.                                 Letter: A Letter Processor
  62.  
  63.  
  64.   example?.ltr Some example letters.
  65.   letter.doc   This file.
  66.   
  67.   Letter is invoked with the name of an input document. Output is printed on
  68.   the terminal unless the command line switch '-p' is placed before the
  69.   filename, in which case output is sent to the printer. The input document
  70.   contains text and letter commands, which take the form of two character
  71.   mnemonics preceded by a '.' (in the style of WordStar or nroff, etc.). The
  72.   format of the document is straight ASCII text, and it can be created by any
  73.   editor.
  74.  
  75.   All commands must begin in the leftmost column. The general form of a
  76.   command is:
  77.  
  78.        blah blah blah blah
  79.        .rm 75
  80.        more blah more blah
  81.        
  82.   which in this case sets the right margin to 75 spaces.
  83.  
  84.   In general, letter operates by processing an input file a line at a time. A
  85.   line can either be a command or text. Assuming it;s text, letter adds it a
  86.   word at a time to the current print line (assuming fill mode is enabled).
  87.   When the line threatens to grow larger than the current page width, it is
  88.   justified (if justification is enabled) and stored in a page array.
  89.   Paragraphs are ended by almost any of the commands or a blank line. After
  90.   all lines have been read, letter calculates the length and prints the
  91.   letter properly centered on the page.
  92.  
  93.   Here's a list of all letter commands. Wherever <xx> is given, a number may
  94.   be specified. The number can be absolute, eg: '5', '30', or it can be
  95.   relative to a current value, eg: '+5', '-3'. Some commands require one of
  96.   'on' or 'off' be given, and some accept text. Hopefully, the context and
  97.   explanation of the command will make the situation sufficiently clear.
  98.   Don't worry about the expression 'line break' for now.
  99.  
  100.   ..           Comment. The  rest of  this line  is ignored.  This line might
  101.                contain notes to yourself regarding the letter. No line break.
  102.   .in <xx>     Indent. This sets the number of spaces between the left margin
  103.                and the  first character printed. If a relative value is given
  104.                (eg: '.in  +5') then the new indent is set relative to the old
  105.                indent. Defaults to 0. Causes a line break.
  106.   .po <xx>     Page offset.  The number of characters to skip before printing
  107.                the first  character. Similar  to '.in'  above. Default  is 5,
  108.                causes a line break.
  109.   .ju on|off   Justification. Enables/disables  right  justification  between
  110.                the current  left and right margins. Defaults to off, causes a
  111.                line break.
  112.   .rm <xx>     Right margin.  Same idea  as '.in' but for the obvious differ-
  113.                ence. Default is 65, causes a line break.
  114.  
  115.  
  116.  
  117.                                             2
  118.  
  119.  
  120.  
  121.                                 Letter: A Letter Processor
  122.  
  123.  
  124.   .ti <xx>     Temporary indent.  Sets the  indent for  the next  line  only.
  125.                Handy for  bullet lists  and paragraph  indentation. Causes  a
  126.                line break, no default.
  127.   .br          Break. Causes a line break.
  128.   .as          Address start.  Marks the  beginning of the address and begins
  129.                redirection to  the file 'address'. Fill and justification are
  130.                automatically disabled. Causes a line break.
  131.   .ae          Address end.  Marks the end of the address and closes the file
  132.                'address'. Fill  and justification  are restored to the values
  133.                they had prior to address redirection. Causes a line break.
  134.   .sp <xx>     Space. Leaves  <xx> blank lines. If <xx> is omitted, one blank
  135.                line is left. Causes a line break.
  136.   .dt          Date. Prints  the current  system date  in the form 'Wednesday
  137.                November 6, 1999' right justified. Causes a line break.
  138.   .sg <text>   Signature. Inserts  'Sincerely yours,',  two blank  lines  and
  139.                <text>. Causes a line break.
  140.   .ce <xx>     Center. Centers  the following  <xx> lines between the current
  141.                left and right margins.
  142.   .rj <xx>     Right justify. Right justifies the following <xx> lines at the
  143.                current right margin.
  144.   .fi on|off   Fill. Invokes/suppresses  the rearranging  of input lines into
  145.                lines of  text as  close to the current margin width as possi-
  146.                ble. Default is on, causes a line break.
  147.   
  148.   The are also three special characters that can be inserted anywhere within
  149.   the text of a letter.
  150.  
  151.   ^  Begin/end doublestrike.
  152.  
  153.   _  Begin/end underlining.
  154.  
  155.   ~  Replaced with a single space after any line justification has been
  156.      performed ('hard space').
  157.  
  158.   
  159.   Letter is (hopefully) distributed with several example letters that demon-
  160.   strate all these commands at work. Hopefully, reading and printing them
  161.   will answer most questions. By default, the output will be sent to the
  162.   screen. Output can be sent to the current 'LPT1:" device by the command
  163.   line:
  164.  
  165.        letter -p example1.ltr
  166.        
  167.        
  168. Address
  169.  
  170.   Address is a simple program to print the file 'address' centered on a stan-
  171.   dard envelope. Do I need to say anything more?
  172.  
  173. Technical Details & Weaknesses
  174.  
  175.  
  176.  
  177.                                             3
  178.  
  179.  
  180.  
  181.                                 Letter: A Letter Processor
  182.  
  183.  
  184.   Letter is written in C. This version has been written using the Wizard C
  185.   compiler and MS-DOS 3.1, but the code should be easily portable to any
  186.   other C compiler. There are no esoteric tricks or witticisms contained
  187.   therein. The function which returns the current system date is fairly
  188.   compiler specific, but still commonly available.
  189.  
  190.   Letter has been quickly written (eight hours). It seems satisfactory for my
  191.   purposes and I don't have any more time to play with it! I know of the fol-
  192.   lowing shortcomings.
  193.  
  194.   o  The justification algorithm is not especially bright. Should sentences
  195.      contain a high proportion of lengthy words, it might not look too
  196.      pretty. If an unbroken word is entered that is wider than the current
  197.      margins, it might hang up! Realistically, there should be no problems,
  198.      however.
  199.  
  200.   o  Tabs are not tolerated. Use '~'s, which will be replaced with spaces.
  201.  
  202.   o  Speaking of '~'s (and '^'s and '_'s), there is currently no way to print
  203.      them as text in your document. Sorry!
  204.  
  205.   o  Underline and boldface are performed by printing a character and
  206.      backspacing; if your printer doesn't backspace, don't use them! If
  207.      you're printer supports auto underlining and backspace, read the
  208.      sections of code near the beginning of the program regarding printer
  209.      controls.
  210.  
  211.   
  212. Last Words
  213.  
  214.   Letter was written by Jon Simkins of Softfocus. It is freely tossed into
  215.   the public domain for good or ill. I would appreciate it if no money is
  216.   charged for it (beyond any nominal media charges) and that the original
  217.   credits are left intact.
  218.  
  219.   If you find any real show stoppers in it, I can be contacted at:
  220.  
  221.        SoftFocus
  222.        1343 Stanbury Dr.,
  223.        Oakville, Ontario, Canada
  224.        L6L 2J5
  225.        (416)825-0903
  226.        
  227.        Compuserve  76566, 1172
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.                                             4
  238.  
  239.  
  240.  
  241.