home *** CD-ROM | disk | FTP | other *** search
/ Shareware Supreme Volume 6 #1 / swsii.zip / swsii / 199 / 4FC12.ZIP / 4COMMENT.DOC < prev    next >
Encoding:
Text File  |  1992-09-01  |  14.4 KB  |  314 lines
  1.  
  2.                              4COMMENT     V 1.2
  3.                                  9/01/92
  4.                 (c)Copyright Saturn Software & John Bintz
  5.  
  6.      4COMMENT  extracts file descriptions from a bbs list or a formatted
  7.      capture file, matches them to existing files, and installs the
  8.      descriptions:
  9.  
  10.      1. As comments into an achieved file (zip, arj, pak, zoo).
  11.      2. As a description in the 4dos file "descript.ion."
  12.      3. Or into a separate text file.
  13.  
  14.      Alternatively, it will extract the comments from a archive file and
  15.      make a file list. A variety of formats are possible for both the
  16.      comment and text files.
  17.  
  18.  
  19.      LIMIT OF LIABILITY
  20.         4COMMENT is distributed as is.  The author makes  no representation
  21.      with respect to the fitness of the software for any particular purpose
  22.      and disclaims all warranties, expressed  or implied.  The  author will
  23.      assume no liability for  damages either  from the  direct use  of this
  24.      product or as a consequence of the use of this software.
  25.      
  26.      SHAREWARE
  27.         4COMMENT is distributed as shareware. This  means you  can evaluate
  28.      the product before  you decide  to register  it. If  you are  using it
  29.      after a couple of weeks, you should register it. You can copy 4COMMENT
  30.      or any shareware program and distributed to anyone else, provided that
  31.      neither the program nor the documentation is altered  and that  you do
  32.      not charge a fee. Because  there is  no advertising,  distribution, or
  33.      packaging cost, the price of a shareware program is often less than an
  34.      equivalent package sold through retail channels.
  35.  
  36.         The registration form is provided in a separate file.
  37.      
  38.     SYNTAX:
  39.  
  40.     4COMMENT     Displays help file
  41.  
  42.     4COMMENT DIRN FILEMASK [-c] [-4] [-t]  ...
  43.  
  44.        -c  :Installs file description as zip/arj/pak/zoo comment
  45.        -4  :Installs short description in 4dos descript.ion
  46.        -t  :Installs file description in text file named "dir" in
  47.             the current subdirectory. If such a file already exists,
  48.             any new material will be appended to it.
  49.             Consequently, 4COMMENT can be run multiple times.
  50.        -g  :Gets file description from comment in zip/arj/pak/zoo
  51.             and appends to DIRN.
  52.        -m  :Mark file so that it won't be processed on a subsequent
  53.             pass through the subdirectory
  54.        -pN :Get description which starts at column N. If this option is
  55.             used with -t or -c, the file date and size comes from the
  56.             filestamp rather than the file description.
  57.  
  58.  
  59.       DIRN:  Must be a qualified filename such as J:\DIRS\DIR4 or just
  60.               the filename if it resides in the current subdirectory. It
  61.               contains the descriptions of the files to be processed. The
  62.               file can be a BBS filelist, a captured session file, or most
  63.               any file which is formatted consistently.
  64.  
  65.        FILEMASK
  66.               Can be a qualified filename or any set of ambiguous characters
  67.               that DOS permits, such as "j:\dl\myfile?.*". The '-t' and '-4'
  68.               options will work regardless of extensions; the '-c' option
  69.               will not because 4COMMENT uses the text of the extension to decide
  70.               what program to shell to. For example, the extension "zip" would
  71.               cause 4COMMENT to shell to pkzip if the '-c' option were in effect.
  72.               If the zipped file was named "myfile.zi1", no shelling would
  73.               take place and no comments would be installed.
  74.  
  75.     Any compression program (PKZIP, ARJ, PAK, ZOO) used must be located
  76.     somewhere on the DOS path for the -c option to operate correctly.
  77.  
  78.  
  79.     Input description file
  80.  
  81.     A fair amount of latitude is permitted on the formatting of the input
  82.     file most of which will be invisible to the user.
  83.        1. If the input file is a captured file, much of the line noise will
  84.           be eliminated during processing.
  85.        2. If the list is produced by PCB, Opus, Auntie, Wildcat in either the
  86.           one or two-line formats, dbbs, or Remote Access, the format will be
  87.           read correctly and converted to PCB (or something else) before it
  88.           is output in text or archive comment.
  89.        3. Any listing which is formatted in the order of filename, size, date,
  90.           description should be processed correctly.
  91.        4. Any listing which is formatted in the order of file stem, file ext,
  92.           size, date, description should be processed correctly.
  93.        5. Any listing which is formatted filename, file description should be
  94.           processed correctly. Whenever the size and date is not found in the
  95.           listing, it is obtained from the file stamp.
  96.        6. With the -p option, any listing in which the file description starts
  97.           at a consistent column should be processed correctly.
  98.  
  99.  
  100.     4DOS
  101.  
  102.     4COMMENT processes the "descript.ion" found in the subdirectory specified
  103.     in the filemask, or creates one if none exists.
  104.  
  105.     4COMMENT is compatible with either the 40 character descriptions of V3
  106.     or the 4096 character descriptions of V4. It handles a maximum of
  107.     500 files per directory. However, if there were many files approaching
  108.     the 4096 character comment limit, memory would become a problem before
  109.     the file limit was reached.
  110.  
  111.     In 4DOS, the text of the comment is limited to 40 characters. 4COMMENT takes
  112.     the comment to be the first 40 characters of the description which is
  113.     roughly the equivalents of the first line of a PCB description. However,
  114.     PCB allows 43 characters so there may be some truncation if the text
  115.     file is a PCB dir file or any other file that exceeds the 4DOS limits.
  116.  
  117.     If there is a "descript.ion" file, new entries are added corresponding
  118.     to the files processed. If an entry for a file already exists, it is
  119.     replaced by the new description.
  120.  
  121.     4DOS V3 and V4 differ in their handling of entries to "descript.ion". In
  122.     version 3, the entire entry is text and it can be 40 characters long.
  123.     In version 4, extended descriptions are permitted and the entire
  124.     description can be up to 4096 characters long. Only 40 characters
  125.     (by default) are displayed and the remainder can be used by other
  126.     programs for whatever purpose. A control 'd', demarks the beginning of
  127.     each area used by another program.
  128.  
  129.     4COMMENT takes this into account whenever there is a new description to a
  130.     file that already exists simply by appending the extended section to the
  131.     new description.
  132.  
  133.     If the monitor on which 4comment is used displays more than 80 characters
  134.     per line (or less than), the maximum length of the description can be
  135.     altered with the 4len option in the configuration file as discussed
  136.     later. If the input file contains multiline file descriptions, words will
  137.     be wrapped around until there is no more space at the width specified
  138.     for "descript.ion."
  139.  
  140.  
  141.     Compressed files
  142.  
  143.     Regardless of the original form of the description, 4COMMENT converts it
  144.     to a PCB type of description by default and installs the description in
  145.     that format as a comment. All compressed filetypes (zip, arj, pak, zoo)
  146.     will allow multiline comments.
  147.  
  148.     When extracting comments with the -g command to make a filelist, just
  149.     the portion of the comment that describes the file is extracted.
  150.     Extraneous messages, bbs identification etc. are not added to the
  151.     filelist. The demands are specific enough that a file description
  152.     installed by some means other than 4comment might not be extracted.
  153.  
  154.     The compressor version worked with are pkzip110, arj222, zoo210, and
  155.     pak210. While I looked at arc601 and lha113, either they didn't allow
  156.     for comments or I didn't discover how to make them work.
  157.  
  158.     If an error is reported back from one of the compression programs, a
  159.     message is displayed on the screen to the effect that an error occurred
  160.     during the run. A file ("4COMMENT.ERR") is created which specifies the
  161.     file(s) in which there an error occurred.
  162.  
  163.     The default comment format is identical to a PCB dir listing. The default
  164.     can be varied in a variety of ways as discussed in the section on
  165.     configuration files.
  166.  
  167.  
  168.     Text file
  169.  
  170.     If the text file option is chosen, file entries will be formatted in
  171.     a PCB format (unless otherwise directed) and installed in a text file
  172.     called "dir." That file will be located in the subdirectory that 4COMMENT
  173.     is initiated from, rather than in the subdirectory being operated on.
  174.  
  175.     Another filename or path for the text file can be forced by entering its
  176.     name directly following the "-t" option, e.g. "k:\robo\dl.txt".
  177.  
  178.     The file is compatible with pcbfiler and should be compatible with any
  179.     other utility that you use to process dir files.
  180.  
  181.     The default text file format is PCB dir listing. The default can be
  182.     varied in a variety of ways as discussed in the second on configuration
  183.     files.
  184.  
  185.  
  186.     File Marking
  187.  
  188.     File marking is intended for BBS sysops or others who repeatedly process
  189.     the same subdirectory because of new files being added. When marking is
  190.     enabled by the "-m" switch, the time stamp of the file is converted to
  191.     a predefined time. When the subdirectory is processed again with the "-m"
  192.     switch, those files time stamped with the predefined time are skipped.
  193.  
  194.     The time is defined in the environment with a set statement in the
  195.     autoexec.bat or with a set statement (from the command line or in a
  196.     batch file) prior to the running of 4COMMENT. For example,
  197.  
  198.                 set 4COMMENT=01:02:12    (no spaces)
  199.  
  200.     Any portion of the time can be omitted from the predefinition. E.g. the
  201.     statement:
  202.  
  203.                 set 4COMMENT=::12
  204.  
  205.     would result in processing all files except those stamped with a 12 in
  206.     the "seconds" location. The advantage of doing this is that the altered
  207.     time stamp would not be displayed with a "dir" command. The disadvantage
  208.     is that one file in 30, on the average, would not be processed correctly.
  209.     (One in thirty, because DOS allows only 30 unique numbers and the unit
  210.     is really double-seconds rather than seconds). If minutes are also stamped,
  211.     the probability of a false positive is reduced to 1 in (60x30).
  212.  
  213.  
  214.     Configuration file:
  215.  
  216.     Normally a configuration file is not required. However, it can be used
  217.     to:
  218.        (1) Alter the format of the textfile or comment.
  219.        (2) In lieu of setting an option on the command line.
  220.        (3) Alter the default 4dos description length.
  221.  
  222.     The configuration file, if it exists, must be named "4comment.cfg" and
  223.     must be located in the current subdirectory or the subdirectory from which
  224.     4comment is invoked.
  225.  
  226.     An example of a configuration file:
  227.  
  228.      ;pcb_ind        32             ;output indent of pcb DIR secondary lines
  229.      ;pcb_ll         79             ;output line length of pcb DIR lines
  230.      ;textfile       dir
  231.      ;mask           c:\t6\*.zip
  232.      ;infile         r:\dirs\dir6
  233.      ;4len           40
  234.      ;bbsout         pcb
  235.      ;bbsout         dbbs
  236.      ;bbsout         auntie
  237.      ;bbsout         opus
  238.      ;bbsout         wildcat1
  239.      ;bbsout         wildcat2
  240.      ;bbsout         files.bbs
  241.      ;bbsout         filename.ext
  242.      ;-4
  243.      ;-t
  244.      ;-m
  245.      ;-g
  246.  
  247.  
  248.        The format of a configuration file line is either a switch defined
  249.    identically to a command line switch or a keyword followed by at least
  250.    one space and a value. Anything which follows a semicolon is assumed
  251.    to be a comment and not an operative statement.
  252.  
  253.    The operative keywords and switches are:
  254.  
  255.    bbsout      Sets the archive file comment and textfile to a bbs format
  256.                other than PCBoard. Options are auntie, dbbs, filebbs,
  257.                wildcat1 for 1 line, wildcat2 for 2 lines, opus, files.bbs,
  258.                and filename.ext.
  259.  
  260.                This is independent of the format of the filelist. 4comment
  261.                should sense whatever format and convert it to the output
  262.                specified by bbsout.
  263.  
  264.     pcb_ind    Sets the indent of PCB extended description to something other
  265.                than the PCB default. This statement is not operative if
  266.                bbsout has be set to something other than PCB.
  267.  
  268.     pcb_ll     Sets the length of PCB lines to something other than the PCB
  269.                default. Setting this option will probably gum up PCBFiler
  270.                and shouldn't be altered normally.
  271.  
  272.     -4         These switches set 4command options in the same manner as they
  273.     -m         are set from the command line. If one of these switches is set
  274.     -c         in the configuration file, they are reversed if the switch
  275.     -g         is also specified in the command line. E.g. 4dos comments will
  276.                be installed if "-4" is specified in either the configuration
  277.                file or on the command line. They will not be installed if "-4"
  278.                is specified in neither or both.
  279.  
  280.     -t[file]   Specifies a textfile with an optional name as it does on
  281.                the command line. If a textfile is specified in the conf
  282.                file, "-t" on the command line turns off the textfile if
  283.                no name is specified. If a name is specified, the command
  284.                line name takes precedence.
  285.  
  286.     textfile   Changes name of textfile produced when the -t option is
  287.                specified from the default filename "dir" to something
  288.                else.
  289.  
  290.     mask       Specifies path and mask for files to be checked, eg
  291.                c:\t6\*.zip
  292.  
  293.     infile     Specifies file in which the file descriptions are specified,
  294.                e.g. r:\dirs\dir6
  295.  
  296.     4len       Changes the maximum length of a 4dos description entry from
  297.                40 to whatever is specified.
  298.  
  299.  
  300.  
  301.     History
  302.  
  303.     V 1.0    11/22/91      Introduction
  304.     V 1.1    11/30/91
  305.              Added command line switches -g, -m
  306.              Optional textfile filename
  307.     V 1.2    09/01/92
  308.              Added command line switch -pN
  309.              Altered file input routines so that more file formats can be
  310.                detected and process correctly.
  311.              Output routines changed to increase the number of output
  312.                formats for the textfile and comments within archives.
  313.              4dos description length configurable.
  314.