home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #1 / monster.zip / monster / PROG_PAS / SNAPPD21.ZIP / SNAP-P.DOC < prev    next >
Text File  |  1994-01-04  |  22KB  |  716 lines
  1. @
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                   SNAP-P (TM)
  16.                           StaNdArd Printer for Pascal
  17.  
  18.          COPYRIGHT (C) 1992, 1993 JAMES L. ALLISON ALL RIGHTS RESERVED
  19.  
  20.  
  21.  
  22.                                James L. Allison
  23.  
  24.                                 Neptune Systems
  25.                                1703 Neptune Lane
  26.                                Houston, TX 77062
  27.  
  28.                              (713) 488-5722 Voice
  29.                               (713) 486-0375 FAX
  30.                             CompuServe (71565,303)
  31.  
  32.  
  33.  
  34.  
  35.  
  36.                            ┌─────────┐
  37.                      ┌─────┴───┐     │              (R)
  38.                    ──│         │o    │──────────────────
  39.                      │   ┌─────┴╨──┐ │  Association of
  40.                      │   │         │─┘  Shareware
  41.                      └───│    o    │    Professionals
  42.                    ──────│    ║    │────────────────────
  43.                          └────╨────┘    MEMBER
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.                               About This Document
  72.  
  73.      This file (SNAP-P.DOC) is meant to be read on screen and contains
  74.      graphic characters that are difficult to print.  If you want a hard
  75.      copy of this document and have trouble printing it, print SNAP-P.PRN,
  76.      which contains no graphics.  SNAP-P.PRN can be generated by the Make
  77.      Printable Copy menu option described later.
  78.  
  79.                                 Why Use SNAP-P
  80.  
  81.      Rapid evaluation, cost savings and debugging ease are the main reasons
  82.      for using a standard printer.  If you are working with a group of
  83.      programmers, a standard source code format makes reading, managing,
  84.      integrating and maintaining your product far less expensive and more
  85.      reliable.  Everyone can read everyone else's code.  Turnover becomes
  86.      less of a headache.  If you import code from outside ( another
  87.      department, a technical journal or a BBS ) the ability to snap that
  88.      code into your own format is critical for evaluation.  If you are
  89.      working alone a standard printer gets all of your source into a format
  90.      that you will be able to read months after you forgot why you wrote it
  91.      in the first place.  If you are in school a standard printer will give
  92.      your reports the professional look that instructors respect.
  93.  
  94.      The biggest advantage is that structural errors in a program appear
  95.      instantly in a listing that has uniform indentation and
  96.      capitalization.  It is far easier to write error-free code when you
  97.      can see what you are doing.  The best debugger is a standard printer.
  98.  
  99.                                  About SNAP-P
  100.  
  101.      For safety, SNAP-P will not change the original source file unless
  102.      told to.  Even then, a backup copy will be made first.  The newly
  103.      structured source text will be placed in a file with the same name as
  104.      the original and the default extension '.SNP'.  The Resulting
  105.      formatted code is shown beside the original on your screen for easy
  106.      comparison.  If you like the results and you have not told SNAP-P to
  107.      change the source, you can replace the original '.PAS' file with the
  108.      new file yourself.
  109.  
  110.      SNAP-P reformats a Pascal program by adjusting margins and internal
  111.      spacing, and using standard capitalization for all keywords and
  112.      identifiers.  You may specify capitalization by either rules or by
  113.      table lookup.  If you choose "rules" (rather than "table") the
  114.      standard capitalization is used.  You can specify which standards and
  115.      use different rules for keywords and identifiers.  If you choose table
  116.      lookup an optional dictionary of standard capitalization is maintained
  117.      by SNAP-P.  String literals and comments are never changed.
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.                                    Page 2
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.                                  Installation
  138.  
  139.      Copy the SNAP-P.EXE and SNAP-P.DOC files to the same directory on
  140.      your hard disk.  If you want to execute from anywhere in the
  141.      system you need to make sure it is in the PATH.
  142.  
  143.      If you want to use SNAP-P as a tool in a Borland(R) product, do
  144.      the following:
  145.  
  146.           1    Start the Borland product
  147.  
  148.           2    Under the Options|Tools menu select New
  149.  
  150.           3    On the resulting form enter:
  151.  
  152.                Title        : ~S~NAP-P
  153.                Program Path : Enter the full path name of SNAP-P.EXE
  154.                Command Line : $EDNAME $SAVE ALL
  155.                Hot Keys     : Pick an available Hot Key (optional).
  156.  
  157.           4    Click OK
  158.  
  159.                                     Removal
  160.  
  161.      If you decide that you don't want to keep SNAP-P on your system,
  162.      delete SNAP-P.* from the directory where you placed SNAP-P.EXE.
  163.      If you have changed your PATH or modified any tools menus these
  164.      will also need to be returned to their original state.
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.                                    Page 3
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.                                  Using SNAP-P
  201.  
  202.      The command line syntax is:
  203.                SNAP-P [[path]filename.ext]
  204.                Example: SNAP-P myprog.pas
  205.  
  206.      SNAP-P is a Turbo Vision(R) application, so if you are familiar
  207.      with the Borland interface you should have no problems.
  208.  
  209.      If you use a mouse the interface is standard with pull down
  210.      menus, check boxes, radio buttons and text entry boxes.
  211.  
  212.      If you prefer a keyboard, press F10 to highlight the menu bar and
  213.      use the arrow and tab keys to move around.  Use the space bar to
  214.      toggle check boxes.  You may also use Alt-?, where ? is the
  215.      highlighted letter on the menu bar.  The status bar at the bottom
  216.      of the screen gives some helpful keystrokes to get you started.
  217.      This manual is available from within SNAP-P by pressing F1.
  218.  
  219.      The number in the lower right corner of the screen is the
  220.      available memory.  Keep an eye on this, especially when working
  221.      with large files.
  222.  
  223.  
  224.        1. Install SNAP-P and start it as described above.
  225.  
  226.        2. Open a file using the Open option on the File pull-down
  227.           menu.  (You may need to use the Change dir... option to
  228.           locate the desired file.)
  229.  
  230.        3. Set capitalization rules.  The rules stay in effect for each
  231.           file you reformat until explicitly changed.
  232.  
  233.        4. Set options to use.  The options stay in effect for each
  234.           file you reformat until explicitly changed.
  235.  
  236.        5. Re-format the code.
  237.  
  238.  
  239.      You may repeat these steps as needed to achieve the desired
  240.      results.
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.                                    Page 4
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.                           Explanation of Menu Options
  267.  
  268.      The menu bar has four pull-down items.  These are:
  269.  
  270.      File  Window  Control  About
  271.  
  272.      Under File:
  273.           Open:           Open a file (directory menu provided)
  274.  
  275.           Change Dir:     Change working directory (directory tree
  276.                           traversal)
  277.  
  278.           Exit:           Exit SNAP-P
  279.  
  280.      Under Window:
  281.           Tile:           Tile open windows
  282.  
  283.           Cascade:        Cascade open windows
  284.  
  285.           Next:           Make next window active
  286.  
  287.           Zoom:           Zoom in or out on active window
  288.  
  289.      Under Control:
  290.           Punctuation:    Set space before and after punctuation
  291.  
  292.           Capitalization Rules:
  293.                           Set capitalization rules.
  294.  
  295.           Options:        Set options
  296.  
  297.           SNAP-P Source:  Re-format source in active window
  298.  
  299.           Replace Original File
  300.                           Replace original file with new text.
  301.                           A backup copy will be made of the original.
  302.  
  303.      Under About:
  304.           Registration:   Create a registration form.
  305.  
  306.           Product Support:
  307.                           Where to get support.
  308.  
  309.           Ombudsman:      ASP contact for help
  310.  
  311.           Copyright:      Copyright notice
  312.  
  313.           View Manual:    Display this manual in a window
  314.  
  315.           Make Printable Copy:
  316.                           Create a file with this manual in an all
  317.                           text format (no graphics characters)
  318.  
  319.  
  320.  
  321.                                    Page 5
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.      The Punctuation dialog box is used to control spacing around
  331.      certain punctuation marks.  The default settings are shown.
  332.  
  333.                  ╔═[■]══════════ Punctuation ═══════════════╗
  334.                  ║         Insert Space (if needed)         ║
  335.                  ║   Before    After     Before    After    ║
  336.                  ║      [X] =  [X]          [X] +  [X]      ║
  337.                  ║      [X] <  [X]          [X] -  [X]      ║
  338.                  ║      [X] >  [X]          [X] /  [X]      ║
  339.                  ║      [X] <> [X]          [X] *  [X]      ║
  340.                  ║      [X] <= [X]                          ║
  341.                  ║      [X] >= [X]          [ ] (  [ ]      ║
  342.                  ║                          [ ] )  [ ]      ║
  343.                  ║      [X] := [X]          [ ] (. [ ]      ║
  344.                  ║      [ ] ;  [X]          [ ] .) [ ]      ║
  345.                  ║      [ ] :  [ ]          [ ] [  [ ]      ║
  346.                  ║      [ ] ,  [X]          [ ] ]  [ ]      ║
  347.                  ║      [X] .. [X]                          ║
  348.                  ║                      Ok   ▄   Cancel ▄   ║
  349.                  ║                    ▀▀▀▀▀▀▀▀   ▀▀▀▀▀▀▀▀   ║
  350.                  ╚══════════════════════════════════════════╝
  351.  
  352.  
  353.      For example, the above selection causes a space to be inserted
  354.      after a semicolon if there isn't one there already.  Spaces will
  355.      only be inserted if necessary, and spaces will never be deleted.
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.                                    Page 6
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.      There are two blocks under Capitalization Rules, one for reserved
  396.      words and one for identifiers.  Each of these blocks contains
  397.      four radio buttons, or mutually exclusive choices.  The default
  398.      settings are shown.  These are:
  399.  
  400.                    ╔═[■]═════════ Cap Rules ══════════════╗
  401.                    ║                                      ║
  402.                    ║  Reserved Word      Identifier       ║
  403.                    ║   ( ) Upper          ( ) Upper       ║
  404.                    ║   () Lower          ( ) Lower       ║
  405.                    ║   ( ) Cap            () Cap         ║
  406.                    ║   ( ) Ignore         ( ) Ignore      ║
  407.                    ║                                      ║
  408.                    ║   [X] Treat directives as reserved   ║
  409.                    ║                                      ║
  410.                    ║                  Ok   ▄     Cancel ▄ ║
  411.                    ║                ▀▀▀▀▀▀▀▀     ▀▀▀▀▀▀▀▀ ║
  412.                    ╚══════════════════════════════════════╝
  413.  
  414.           Upper          All upper case  (example: MY_VARIABLE).
  415.  
  416.           Lower          All lower case  (example: my_variable).
  417.  
  418.           Cap            First letter and all letters following
  419.                          an underscore are upper case, others
  420.                          in lower case   (example: My_Variable).
  421.  
  422.           Ignore         Do not change.
  423.  
  424.      Directives (virtual, forward, etc.) are not reserved words, but many
  425.      programmers treat them as such.  Check the box if you want to treat
  426.      directives as reserved words.  If you do not check the box they will
  427.      be treated as identifiers.
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.                                    Page 7
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.      The default settings for the choices under Options are:
  461.  
  462.                    ╔═[■]══════════ Options ═══════════════╗
  463.                    ║                                      ║
  464.                    ║  Adjust             Capitals         ║
  465.                    ║   [X] Spacing        ( ) Table       ║
  466.                    ║   [X] Capitals       () Rules       ║
  467.                    ║                                      ║
  468.                    ║  Save File Extension    .SNP         ║
  469.                    ║  Backup Extension       .SBU         ║
  470.                    ║                                      ║
  471.                    ║  Indent Spaces          3            ║
  472.                    ║                                      ║
  473.                    ║   [X] Break Line  Length  72         ║
  474.                    ║                                      ║
  475.                    ║                   Filler  *          ║
  476.                    ║                                      ║
  477.                    ║                  Ok   ▄     Cancel ▄ ║
  478.                    ║                ▀▀▀▀▀▀▀▀     ▀▀▀▀▀▀▀▀ ║
  479.                    ╚══════════════════════════════════════╝
  480.  
  481.           Adjust:                    Select whether to adjust spacing
  482.                                      and capitalization
  483.  
  484.           Capitals:                  Select whether capitalization is
  485.                                      performed using a dictionary or
  486.                                      using the rules specified in the
  487.                                      Capitalization Rules dialog.
  488.                                      (Rules are easier to use, but the
  489.                                      table gives you more control.)
  490.  
  491.           Save File Extension:       Used to form the name of the
  492.                                      output file.
  493.  
  494.           Backup Extension           Used to form the name of the
  495.                                      source backup file.  This is used
  496.                                      only in the "Replace Original File"
  497.                                      operation.
  498.  
  499.           Indent Spaces:             The number of spaces to indent for
  500.                                      each level of block nesting.
  501.  
  502.           Break Line:                The break line is a highly visible
  503.                                      comment that separates procedures
  504.                                      and functions.  Turn this off if
  505.                                      you don't like the looks.
  506.  
  507.           Length                     Total length of break line.
  508.  
  509.           Filler                     Fill character used to form
  510.                                      break line.
  511.  
  512.  
  513.  
  514.  
  515.  
  516.                                    Page 8
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.                              About the Dictionary
  528.  
  529.      You may want to use table lookup instead of rules for
  530.      capitalization.  For most applications the rules will suffice,
  531.      but there are cases where you need more control.  For example,
  532.      'ReadLn', 'cmCancel', 'FileName' and so on follow no particular
  533.      rules, but you want a standard appearance.  This is what the
  534.      dictionary is for.  Each word in the source file is capitalized
  535.      according to the dictionary.  When a new word is found, you will
  536.      be prompted for the capitalization.  You cannot change the
  537.      spelling, only the looks of the word.  If you enter just a
  538.      return, the name will be used as is.  The dictionary is kept as a
  539.      text file named SNAP-P.CAP, so you can edit it whenever you like.
  540.      The words must be kept in alphabetical order.  The order in the
  541.      dictionary is not case sensitive.  If you need to change the
  542.      looks of a word in the dictionary use any editor to do so, but do
  543.      not change its location.  Do not use a word processor that might
  544.      introduce extra characters into the file.  Use a simple text editor
  545.      instead.
  546.  
  547.                                Protecting Blocks
  548.  
  549.      There are times when you want to protect a block of code from any
  550.      reorganization.  This is especially true for tabular layout.  A block
  551.      can be protected from spacing adjustment by placing {-s} alone on one
  552.      line. Spacing adjustment is turned back on by placing {+s} alone on a
  553.      line. Similarly, {-c} and {+c} control capitalization.  Echo mode
  554.      turns SNAP-P off entirely.  A {+e} starts echo mode.  From that point
  555.      on the text is simply copied to the output.  It is not even scanned,
  556.      except to look for a line containing only {-e}, which turns echo mode
  557.      off. Since echo mode turns off all parsing, echo mode must respect the
  558.      Pascal block structure.  If, for example echo mode includes a "begin"
  559.      but not the matching "end" the indent structure will be incorrect.
  560.  
  561.      All of these must appear by themselves on a line.  These are not case
  562.      sensitive.
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.                                    Page 9
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.                             Definition of Shareware
  593.  
  594.      Shareware distribution gives users a chance to try software before
  595.      buying it. If you try a Shareware program and continue using it, you
  596.      are expected to register.
  597.  
  598.      Copyright laws apply to both Shareware and commercial software, and
  599.      the copyright holder retains all rights, with a few specific
  600.      exceptions as stated below. Shareware authors are accomplished
  601.      programmers, just like commercial authors, and the programs are of
  602.      comparable quality. (In both cases, there are good programs and bad
  603.      ones!) The main difference is in the method of distribution. The
  604.      author specifically grants the right to copy and distribute the
  605.      software, either to all and sundry or to a specific group. For
  606.      example, some authors require written permission before a commercial
  607.      disk vendor may copy their Shareware.
  608.  
  609.      Shareware is a distribution method, not a type of software. You should
  610.      find software that suits your needs and pocketbook, whether it's
  611.      commercial or Shareware. The Shareware system makes fitting your needs
  612.      easier, because you can try before you buy. And because the overhead
  613.      is low, prices are low also. Shareware has the ultimate money-back
  614.      guarantee -- if you don't use the product, you don't pay for it.
  615.  
  616.                             Disclaimer - Agreement
  617.  
  618.      Users of SNAP-P must accept this disclaimer of warranty: "SNAP-P is
  619.      supplied as is.  The author disclaims all warranties, expressed or
  620.      implied, including, without limitation, the warranties of
  621.      merchantability and of fitness for any purpose. The author assumes no
  622.      liability for damages, direct or consequential, which may result
  623.      from the use of SNAP-P."
  624.  
  625.      SNAP-P is a "shareware program" and is provided at no charge to the
  626.      user for evaluation.  Feel free to share it with your friends, but
  627.      please do not give it away altered or as part of another system.  The
  628.      essence of "user-supported" software is to provide personal computer
  629.      users with quality software without high prices, and yet to provide
  630.      incentive for programmers to continue to develop new products.  If you
  631.      find this program useful and find that you are using SNAP-P and
  632.      continue to use SNAP-P after a reasonable trial period, you must make
  633.      a registration payment of $27.00 to Neptune Systems.  The $27.00
  634.      registration fee will license one copy for use on any one computer at
  635.      any one time.  You must treat this software just like a book.  An
  636.      example is that this software may be used by any number of people and
  637.      may be freely moved from one computer location to another, so long as
  638.      there is no possibility of it being used at one location while it's
  639.      being used at another. Just as a book cannot be read by two different
  640.      persons at the same time.
  641.  
  642.      Commercial users of SNAP-P must register and pay for their copies of
  643.      SNAP-P within 30 days of first use or their license is withdrawn.
  644.      Site-License arrangements may be made by contacting Neptune Systems.
  645.  
  646.                                    Page 10
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.      Anyone distributing SNAP-P for any kind of remuneration must first
  657.      contact Neptune Systems at the address above for authorization. This
  658.      authorization will be automatically granted to distributors recognized
  659.      by the (ASP) as adhering to its guidelines for shareware distributors,
  660.      and such distributors may begin offering SNAP-P immediately (However
  661.      Neptune Systems must still be advised so that the distributor can be
  662.      kept up-to-date with the latest version of SNAP-P.)
  663.  
  664.      You are encouraged to pass a copy of SNAP-P along to your friends for
  665.      evaluation.  Please encourage them to register their copy if they find
  666.      that they can use it.  All registered users will receive a copy of the
  667.      latest version of the SNAP-P system without the registration reminder
  668.      at the beginning and end. They will also receive a utility that
  669.      provides a visual map of available hard disk space on their system and
  670.      a 'LostFile' program with better pattern matching facility than the
  671.      DOS wildcard scheme. They will also receive free technical support via
  672.      U.S. mail, CompuServe electronic mail or telephone for a period of six
  673.      months after registration.
  674.  
  675.                                    Ombudsman
  676.  
  677.      This program is produced by a member of the Association of
  678.      Shareware Professionals (ASP).  ASP wants to make sure that the
  679.      shareware principle works for you. If you are unable to resolve a
  680.      shareware-related problem with an ASP member by contacting the
  681.      member directly, ASP may be able to help. The ASP Ombudsman can
  682.      help you resolve a dispute or problem with an ASP member, but
  683.      does not provide technical support for members' products.  Please
  684.      write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI
  685.      49442-9427 USA, FAX 616-788-2765 or send a CompuServe message via
  686.      CompuServe Mail to ASP Ombudsman 70007,3536.
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.                                    Page 11
  712.                                     (End)
  713.  
  714.  
  715.  
  716. @