home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d528 / simsmart.lha / SimSmart / SimSmart.doc < prev    next >
Text File  |  1991-08-05  |  13KB  |  511 lines
  1. =============================================================================
  2.  
  3.         SIMSMART version 2.10  for the Amiga
  4.  
  5.               c 1989  D A Simon
  6.  
  7. =============================================================================
  8.  
  9.  
  10.             -----------------
  11.              1 - INTRODUCTION
  12.             -----------------
  13.  
  14.  WHAT IS SIMSMART ?
  15.  ------------------
  16.  
  17.     SIMSMART is a general-purpose utility that will allow you to print
  18.  the program source code of almost any language, so that (for example) the
  19.  keywords are emboldened and underlined, and the comments are italicized.
  20.  These features are adjustable by the user, to suit individual taste.
  21.  Tabbing is also adjustable, to harmonize with the nesting depth of a 
  22.  particular program.  Output may be either on the printer, the screen, or
  23.  to another file.
  24.  
  25.     SIMSMART may easily be extended by the user to deal with extra
  26.  languages.  In this release, it comes already configured for .....
  27.  
  28.         C
  29.         C++
  30.         Modula-2
  31.         Pascal
  32.         68000 Assembler
  33.         PostScript
  34.         Ada
  35.         Amiga BASIC
  36.  
  37.  
  38.     SIMSMART is ShareWare!  If you actually like it, find it of
  39.  positive value, and use it regularly, you are asked to send a small 
  40.  contribution to promote the development of ShareWare (by helping the
  41.  author to purchase more tools for his trade) ....  But enough of that for
  42.  the moment ... please see Section 6 at the end of this file, later on.
  43.  
  44.  
  45.  
  46.  HOW DOES IT WORK ?
  47.  ------------------
  48.  
  49.     SIMSMART is intended to be installed on a WorkBench version 1.3
  50.  or later, as it makes extensive use of the ALIASing mechanism of the
  51.  AmigaDos Shell.  This allows for a very simple way of printing your program 
  52.  code, for (almost) ANY source language.  For example, you may print your
  53.  C program on the printer simply by saying ....
  54.  
  55.         CPRT  MYPROG.C
  56.  
  57.  or perhaps just examine the neat output on the screen with ....
  58.  
  59.         CSHOW  MYPROG.C
  60.  
  61.  
  62.  
  63.     The SIMSMART program itself should be placed in the C: directory
  64.  of your boot-up disk.  The accompanying  ..keys  and  ..com  files
  65.  should be copied to the S: directory of that disk.
  66.     
  67.     The AmigaDos SHELL is the successor to the old CLI ( Command Line
  68.  Interface ).  Whenever you call a shell-window, the file S:SHELL-STARTUP
  69.  is examined, in order to set up aliases, and so on.
  70.  
  71.      The file S:SHELL-STARTUP should be amended to include suitable
  72.  aliases.  These aliases will then be ready to use whenever you wish to
  73.  print a C or C++ or Modula-2 or Pascal or Ada or PostScript or ... file.
  74.  
  75.  
  76.  
  77.  THE PRINTER ( IMPORTANT ! )
  78.  ---------------------------
  79.  
  80.     Note that your printer should be capable of printing BOLD, ITALIC
  81.     and UNDERLINE.
  82.  
  83.  
  84.     Your WorkBench disk should be correctly configured to use your
  85.     printer ...
  86.  
  87.     -- the correct printer driver should be in devs:printers/
  88.  
  89.     -- Preferences should be set correctly for your printer
  90.  
  91.     ( If you do not know how to do this, you should read the
  92.       Amiga Manual and other Amiga literature ... ).
  93.  
  94.  
  95. =============================================================================
  96.  
  97.  
  98.             -------------------
  99.              2 - USING SIMSMART
  100.             -------------------
  101.  
  102.  GETTING STARTED
  103.  ---------------
  104.  
  105.  1)  Call a Shell-Window.
  106.  
  107.  
  108.  2)  Change to the directory containing the program file that you wish to
  109.      print.
  110.  
  111.  
  112.  3)  EXAMPLE: printing a C program file
  113.  
  114.      ( The defaults used here will print your program with EMBOLDENED
  115.        RESERVED WORDS  and ITALICIZED COMMENTS.
  116.        We will consider how to modify these defaults a little later. )
  117.  
  118.  
  119.  
  120.     To examine myprog.c on the SCREEN ...
  121.                         CSHOW  myprog.c
  122.  
  123.     To send myprog.c to the PRINTER ...
  124.                         CPRT  myprog.c
  125.  
  126.     To save the neat output in the file  NEATPROG.C ...
  127.  
  128.                         CSHOW  >NEATPROG.C  myprog.c
  129.  
  130.  
  131.  4) ALIASES for OTHER LANGUAGES
  132.  
  133.     In a similar fashion .....
  134.  
  135.  
  136.    C++PRT/C++SHOW   are used for C++ files
  137.  
  138.  
  139.    MODPRT/MODSHOW   are used for Modula-2 files
  140.  
  141.  
  142.    PASPRT/PASSHOW   are used for Pascal files whose COMMENTS are delimited
  143.                     either by  {  and  }  or  by  (*  and  *)
  144.  
  145.  
  146.    AMBPRT/AMBSHOW   are used for AmigaBASIC files
  147.  
  148.  
  149.    ASSEMPRT/ASSEMSHOW   are used for 68000-Assembler files
  150.  
  151.  
  152.    PSPRT/PSSHOW   are used for PostScript files
  153.  
  154.  
  155.    ADAPRT/ADASHOW   are used for Ada files
  156.  
  157.  
  158.  
  159.  FILES NEEDED TO DESCRIBE A LANGUAGE
  160.  -----------------------------------
  161.  
  162.     For SimSmart to be able to handle a particular language, TWO files
  163.  must be present to describe the characteristics of the particular language.
  164.  These two files are named as  ..KEYS  and  ..COM  files; they are usually
  165.  placed in the S: directory of the boot-up disk.  The SimSmart program itself
  166.  should be in the C: directory of the boot-up disk.
  167.  
  168.     The ..KEYS file contains a list of the RESERVED WORDS for the 
  169.  language.  The ..COM file describes the nature of COMMENTS in the
  170.  language.  The exact format of these files will be considered later.
  171.  
  172.     Each language has a distinct pair of such files.  You CAN (if you
  173.  wish) make a raw call to SimSmart with the specific command line options to
  174.  be described later on.   However, the most usual ( and simplest ) way
  175.  of calling SimSmart for a particular language will be by means of an ALIAS
  176.  that has been set up for that language.  This can be effected by editing
  177.  the file Shell-Startup (found in the S: directory).
  178.  
  179.     This release already contains files for eight languages.  These
  180.  aliases should appear in the S:shell-startup file  ...
  181.  
  182.  
  183.     alias cprt        SimSmart >prt: -Ks:ckeys -Cs:ccom  []
  184.     alias cshow        SimSmart  -Ks:ckeys -Cs:ccom  []
  185.  
  186.     alias c++prt        SimSmart >prt: -Ks:c++keys -Cs:c++com  []
  187.     alias c++show        SimSmart  -Ks:c++keys -Cs:c++com  []
  188.  
  189.     alias modprt        SimSmart >prt: -Ks:modkeys -Cs:modcom  []
  190.     alias modshow        SimSmart  -Ks:modkeys -Cs:modcom  []
  191.  
  192.     alias ambprt        SimSmart >prt: -Ks:ambkeys -Cs:ambcom  []
  193.     alias ambshow        SimSmart  -Ks:ambkeys -Cs:ambcom      []
  194.  
  195.     alias pasprt        SimSmart >prt: -Ks:paskeys -Cs:pascom  []
  196.     alias passhow        SimSmart  -Ks:paskeys -Cs:pascom  []
  197.  
  198.     alias psprt        SimSmart >prt: -Ks:pskeys -Cs:pscom  []
  199.     alias psshow        SimSmart  -Ks:pskeys -Cs:pscom  []
  200.  
  201.     alias assemprt        SimSmart >prt: -Ks:assemkeys -Cs:assemcom  []
  202.     alias assemshow        SimSmart  -Ks:assemkeys -Cs:assemcom  []
  203.  
  204.     alias adaprt        SimSmart >prt: -Ks:adakeys -Cs:adacom  []
  205.     alias adashow        SimSmart  -Ks:adakeys -Cs:adacom  []
  206.  
  207.  
  208.     The defaults used here will print your program with EMBOLDENED
  209.     Reserved Words  and ITALICIZED Comments.
  210.  
  211.  
  212.  
  213.  ARGUMENTS USED when calling SimSmart
  214.  ------------------------------------
  215.  
  216.  
  217.     SIMSMART  [ >prt: ]  -K<keywordfile>  -C<commentfile> 
  218.  
  219.        [-tnn]  [ -r[b][i][u] ]   [ -q[s][d][b][i][u] ]  <filename>
  220.  
  221.  
  222.  
  223.  
  224.  (A) The ESSENTIAL Command-Line Arguments 
  225.  
  226.     The minimum call is as follows ...
  227.  
  228.         SimSmart  -K<keywordfile>  -C<commentfile>  <filename>
  229.  
  230.  
  231.  
  232.     <keywordfile>    is the FULL PATH to the name of the keyword file.
  233.  
  234.  
  235.     <commentfile>    is the FULL PATH to the name of the comment file.
  236.  
  237.             This comment file contains three lines of text
  238.             only -- these three lines describe the
  239.             comment-start-string,  the comment-end-string,
  240.             and how comments are to be displayed
  241.             ( viz  BOLD | ITALIC | UNDERLINE ) .
  242.  
  243.  
  244.     <filename>    is the name of the file to be printed.
  245.  
  246.  
  247.  
  248.  
  249.  (B) The OPTIONAL Command-Line Arguments 
  250.  
  251.     -tnn        set tabstops to  nn  spaces.
  252.             The default setting is  -t4.
  253.             A setting of  -t0  will switch off detabbing.
  254.  
  255.  
  256.  
  257.     -r[b][i][u]    set the style of the RESERVED WORDS of this
  258.             language ( viz  those listed in <keywordfile> )
  259.             The default is BOLD.
  260.  
  261.             For example,        -rbui
  262.             will display Reserved Words in BOLD and ITALIC
  263.             and UNDERLINE.
  264.  
  265.  
  266.             -r  ALONE will switch off special treatment of
  267.                 Reserved Words.
  268.  
  269.  
  270.  
  271.     -q        Anything enclosed in quotes (either single or
  272.             double ) is NORMALLY NOT emboldened or italicized
  273.             or underlined.
  274.             The  -q  flag, however, gives you the choice of
  275.             highlighting anything enclosed in quotes. This
  276.             might be useful perhaps during debugging.
  277.  
  278.             For example ...
  279.  
  280.             -qsbu    will highlight with BOLD UNDERLINE everything
  281.                 that is enclosed in SINGLE quotes
  282.  
  283.             -qdi    will ITALICIZE everything that is enclosed
  284.                 in DOUBLE quotes
  285.  
  286.             -qbiu    will highlight with BOLD ITALIC UNDERLINE
  287.                 everything in SINGLE and DOUBLE quotes
  288.  
  289.             -qsdbiu        ... same as  -qbiu
  290.  
  291.  
  292.  
  293.     >prt:        Send output to the printer ( assuming that you have
  294.             used Preferences to install the correct printer-
  295.             driver for your particular printer  -- see Amiga
  296.             Manuals )
  297.  
  298.  
  299. =============================================================================
  300.  
  301.  
  302.             -------------------
  303.              3 - FILE FORMATS
  304.             -------------------
  305.  
  306.  
  307.  1) The Format of the ..KEYS  files
  308.  ----------------------------------
  309.  
  310.     These files are found in the S: directory.  There is one for EACH
  311.  LANGUAGE.  The file contains a list of Reserved Words for that language,
  312.  ONE PER LINE.
  313.  
  314.     If the language can accept either lower case or upper case Reserved
  315.  Words, then each word must have TWO entries in the ..KEYS file ( one for
  316.  each case ) ... see the file  PASKEYS  for an example.
  317.  
  318.     Each word should be on a SEPARATE line, with NO LEADING OR TRAILING
  319.  WHITE SPACE.
  320.  
  321.  
  322.  
  323.  2) The Format of the ..COM  files
  324.  ---------------------------------
  325.  
  326.     These files are found in the S: directory.  There is one for EACH
  327.  LANGUAGE.  The file describes the nature of COMMENTS in that language.
  328.  
  329.  
  330.  Most  ..COM files consists of  THREE LINES  only.
  331.  
  332.     LINE 1    shows the COMMENT-START string
  333.  
  334.     LINE 2  shows the COMMENT-END string
  335.         ( or the string  "newline"  if the comment extends only
  336.           to the end-of-line in this particular language )
  337.  
  338.     LINE 3  shows any combination of  b|i|u
  339.         This line determines the APPEARANCE OF COMMENTS for the
  340.         language.
  341.  
  342.  
  343.     Examples
  344.     --------
  345.  
  346.         The file  CCOM  consists of these three lines ...
  347.  
  348.             /*
  349.             */
  350.             i
  351.  
  352.         The file  MODCOM  consists of these three lines ...
  353.  
  354.             (*
  355.             *)
  356.             i
  357.  
  358.         The file  ASSEMCOM  consists of these three lines ...
  359.  
  360.             ;
  361.             newline
  362.             i
  363.  
  364.  
  365.  
  366.  
  367.     HOWEVER -- some languages ( such as Pascal and C++ ) allow MORE THAN
  368.     ONE COMMENT STYLE.  For these languages the format of the ..COM file
  369.     allows for this in the following way ...
  370.  
  371.  
  372.     LINE 1    consists of  ~~  followed by the NUMBER OF DISTINCT
  373.         COMMENT STYLES N
  374.         ( For both Pascal and C++, line 1 is   ~~2 )
  375.  
  376.  
  377.     N PAIRS OF LINES  -- where each pair shows the COMMENT-START string
  378.                 and the COMMENT-END string, as previously.
  379.  
  380.  
  381.     LAST LINE   shows any combination of  b|i|u
  382.         This line determines the APPEARANCE OF COMMENTS for the
  383.         language.
  384.  
  385.  
  386.     Examples
  387.     --------
  388.  
  389.         The file  PASCOM  consists of these six lines ...
  390.  
  391.             ~~2
  392.             {
  393.             }
  394.             (*
  395.             *)
  396.             i
  397.  
  398.  
  399.         The file  C++COM  consists of these six lines ...
  400.  
  401.             ~~2
  402.             //
  403.             newline
  404.             /*
  405.             */
  406.             i
  407.  
  408.  
  409. =============================================================================
  410.  
  411.  
  412.         ----------------------------------
  413.         4 - ALTERING THE DEFAULT SETTINGS
  414.         ----------------------------------
  415.  
  416.  
  417.  The default settings are for
  418.  
  419.         *  ITALICIZED COMMENTS
  420.  
  421.         *  EMBOLDENED RESERVED WORDS
  422.  
  423.  
  424.  
  425.  The two following examples show how to change the defaults for  CPRT.
  426.  
  427.  You can do this by editing the files   S:shell-startup  and  S:ccom
  428.  with any ordinary text editor ( such as ED or STEVIE ).
  429.  
  430.  Obviously, you can change the defaults for ANY OTHER ALIAS in the same way.
  431.  
  432.  
  433.  
  434.  EXAMPLE 1 : to print C files with EMBOLDENED ITALICIZED Comments
  435.          and EMBOLDENED UNDERLINED Reserved Words
  436.  
  437.     First edit the file s:ccom, and change the LAST LINE only,
  438.     so that the file will now appear thus ...
  439.  
  440.         /*
  441.         */
  442.         bi
  443.  
  444.  
  445.     Now edit the file s:shell-startup.  Change the alias for CPRT
  446.     so that it will now appear as follows ...
  447.  
  448.       alias cprt  SimSmart >prt: -Ks:ckeys  -Cs:ccom  -rbu  []
  449.  
  450.  
  451.  
  452.  
  453.  EXAMPLE 2 : to print C files with EMBOLDENED UNDERLINED Comments
  454.          and ITALICIZED Reserved Words, and with
  455.          TWO spaces per tab
  456.  
  457.     First edit the file s:ccom, and change the LAST LINE only,
  458.     so that the file will now appear thus ...
  459.  
  460.         /*
  461.         */
  462.         bu
  463.  
  464.  
  465.     Now edit the file s:shell-startup.  Change the alias for CPRT
  466.     so that it will now appear as follows ...
  467.  
  468.       alias cprt  SimSmart >prt: -Ks:ckeys  -Cs:ccom  -ri  -t2  []
  469.  
  470.  
  471.  
  472. =============================================================================
  473.  
  474.    
  475.         ------------------------------------------
  476.         5 - EXTENDING SIMSMART FOR OTHER LANGUAGES
  477.         ------------------------------------------
  478.  
  479.     The manner of setting up the correct  ..KEYS and  ..COM files
  480.  should be obvious from the previous information.
  481.  
  482.     Then merely set up the required aliases in S:shell-startup.
  483.  
  484.  
  485. =============================================================================
  486.  
  487.    
  488.             -------------
  489.             6 - SHAREWARE
  490.             -------------
  491.  
  492.     This program is ShareWare.
  493.  
  494.     If you use it regularly and find it useful, please send a small
  495.  contribution to the author at the address given below.
  496.  
  497. =============================================================================
  498.  
  499.  Please send any reports, complaints, or manifestations of your munificence
  500.  to ...
  501.  
  502.  David Simon
  503.  Department of Computer Science
  504.  University College of Swansea
  505.  SWANSEA  SA2 8PP
  506.  United Kingdom
  507.  
  508.  Electronic Mail:    csdavid@uk.ac.swan.pyr
  509.  
  510. =============================================================================
  511.