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