home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / waffle / allfil62.zip / ALLFILES.DOC < prev    next >
Text File  |  1993-04-06  |  16KB  |  389 lines
  1. A L L F I L E S  --  a utility for Waffle BBS 1.65 (MS-DOS)
  2.  
  3. Scan a Waffle 1.65 dirs file and associated directory information files,
  4. creating a set of directory /info files and summary listings.  Produce
  5. extra information on some special file types (gif, jpg, bin).
  6.  
  7. This is a program that has been in the making for ages (at least from 1987),
  8. that's why this first non-beta public release comes up as version 6.2.
  9. However, the version I've used up 'till now for myself was very rigid and
  10. only produced listings the way I wanted them, to reconfigure it you had to
  11. recompile it (and it was a mess I didn't want anyone to see on the inside).
  12. This new version is (hopefully) configurable to all your needs, and most of
  13. this document will handle just *how* to configure this beast.
  14.  
  15. Some basic assumptions that are made in allfiles.  Your file areas are
  16. hierarchially ordered (for example you have all PC files under /download/pc,
  17. all graphics under /download/graphics and so forth).  Your /info files are
  18. in a good order, with all files accounted for and no descriptions missing
  19. (see the chkfiles program also written by me for help on getting them neatly
  20. arranged).  You only allow uploads to a directory of which no file listings
  21. are required.
  22.  
  23. You should have FILES set in your config.sys to an appropriately large value
  24. when using allfiles (the five DOS filehandles, dirs, summarys, rawinfo, info
  25. and special files make a total of thirteen files open at the same time when
  26. using the sample allfiles.cnf file).
  27.  
  28.  
  29. QUICK INSTALL
  30. -------------
  31.  
  32. Unzip the archive in a appropriate place (I use /waffle/allfiles).
  33.  
  34. Edit your Waffle dirs file (default location /waffle/system/dirs), adding
  35. a /name label (with a possible symbolic name for the directory) to those
  36. directories you want included in the summary listing.
  37.  
  38. Edit allfiles.cnf.  You can remove the comment from the /noinfo line to
  39. disable rawinfo/info rewriting.  Check that the lines following the comment
  40. "The file listings, one per line" agree with your directory setup.
  41.  
  42. Edit update.bat to reflect the same changes, and also make sure the other
  43. values are appropriate to your directory structure.
  44.  
  45. If you did not enable /noinfo mode in the configuration file, in each of
  46. your download directories, rename the @files file to @files.raw (allfiles
  47. will create new @files files from these) *or* see below under "Rawinfo
  48. files" on changing the name of the info files.
  49.  
  50. Copy update.bat to your path.  Ready to fly!
  51.  
  52.  
  53. INPUT FILES
  54. -----------
  55.  
  56. First, there is the configuration file for the program (see the sample
  57. allfiles.cnf provided with the package).  As you will notice, the file
  58. syntax is identical with the Waffle dirs file (no accident).
  59.  
  60. Second, there is the standard Waffle dirs file.  Allfiles adds some special
  61. fields to the file, which are ignored by Waffle.
  62.  
  63. Third (optional), there are the /rawinfo files (by default named @files.raw)
  64. in each download directory.
  65.  
  66.  
  67. OUTPUT FILES
  68. ------------
  69.  
  70. Output is done to several summary and the /info files (by default named
  71. @files) simultaneously.  There are as many summary files as you specify in
  72. the configuration file, and one /info file per download directory.
  73.  
  74. Directories which have lines in the /rawinfo files will only be written
  75. to the /info file, not the summary files.  If /zeros is set, also zero-
  76. length files will have descriptions written to the /info files.
  77.  
  78.  
  79. CONFIGURATION FILE
  80. ------------------
  81.  
  82. Here are the settable parameters in the configuration file [defaults used
  83. by allfiles if not given shown in brackets], see under "output conversions"
  84. for explanation of the escape sequences used:
  85.  
  86.     /dirs        Where your Waffle dirs file is located
  87.             [/waffle/system/dirs]
  88.  
  89.     /noinfo        Disable the rawinfo/info rewriting mechanism [0]
  90.  
  91.     /zeros        Rewrite also zero length file's names [0]
  92.  
  93.     /info        The default info file name [@files]
  94.     /rawinfo    The default raw info file name [@files.raw]
  95.     /infoformat    Format for output to info files [%f\t%T\n]
  96.  
  97.     /masterformat    Format for output to summary files
  98.             [%-12f%6L%3d/%02m/%02y %T\n]
  99.     /plusformat    Format for output of lines starting with plus in the
  100.             rawinfo files [              Size  Updated %t\n]
  101.  
  102.     /begin        Summary listing beginning header, where
  103.                 %t will give the listing /name
  104.                 %f the listing /dir
  105.                 time-related %'s will give the current time
  106.             [List of %t files on SomeBBS, Somewhere\n
  107.             %A, %2d %B %02y %H:%M\n]
  108.     /header        Header used at the beginning of a new directory, if
  109.             no value for /name is given in the dirs file where
  110.                 %f will give the current directory
  111.             [\n*** %f ***\n\n]
  112.     /nameheader    Header used at the beginning of a new directory
  113.             if a /name is specified in dirs where
  114.                 %f will give the current directory
  115.                 %t will give the specified /name
  116.             [\n*** %f (%t) ***\n\n]
  117.     /footer        Footer used at the end of a directory listing
  118.                 %L and %l give space usage for this directory
  119.                 %n will give number of files in this directory
  120.             [\nTotal %L in %n files\n]
  121.     /end        Epilogue placed at the end of a summary listing, where
  122.                 %L and %l give the total file space usage
  123.                 %N will give the total number of directories
  124.                 %n will give the total number of files
  125.                 %t will give the listing /name
  126.                 %f the /dir
  127.             [\nGrand total %L in %n files in %N directories\n
  128.             *** End of %t files listing ***\n]
  129.  
  130.     /rom        Allfiles should also scan /rom entries in the dirs
  131.             files; see below for the gory details of these
  132.  
  133. The following three parameters should appear on the same line, once per
  134. each summary file wanted:
  135.  
  136.     /list        A file where a summary listing is output
  137.     /dir        What subdirectories are placed in the listing (%f)
  138.     /name        The name of the listing (%t)
  139.  
  140. A sample configuration file for producing a listing of the Simtel20 CD-ROM
  141. is also included in the package (December'93 version, expect directory name
  142. changes on the newer versions).
  143.  
  144.  
  145. DIRS FILE
  146. ---------
  147.  
  148. Allfiles parses the basic Waffle dirs file for its own purposes, but it also
  149. recognizes some extra fields which Waffle will ignore:
  150.     /name        The name of the directory for human consumption;
  151.             even if you do not wish to give your directories names,
  152.             you must specify /name for all directories you want
  153.             listings generated from; thus, you would not place
  154.             /name on directories which only contain subdirectories
  155.  
  156.     /ínfo        Overrides the default /info set in the config file
  157.     /rawinfo    Overrides the default /rawinfo set in the config file
  158.  
  159.     /column        File descriptions start from the specified column on
  160.             
  161.     /skip        Skip the specified amount of lines from the beginning
  162.             of the info/rawinfo file before starting to match files
  163.  
  164.     /rom        The directory is on CD-ROM (or other readonly device)
  165.             and will not be listed unless /rom is given in the
  166.             allfiles configuration file; in this case, allfiles
  167.             will *read* the info file directly without attempting
  168.             to create it
  169.  
  170. Here are some lines from my dirs file, specifying a few normal directories
  171. on the hard disk, and then some CD-ROM directories (lines are wrapped for
  172. ease of reading with \ -- I think Waffle doesn't support this):
  173.  
  174. 1   /access=0 /name="Download Section, general information" \
  175.         /dir="c:/download" /free
  176. 5   /access=2 /name="Ye Olde Hacker's phonenumbers" \
  177.         /dir="c:/download/hackers"
  178. -   /access=2 /dir="c:/download/graphics" /hide
  179. 7   /access=2 /name="Graphics, GIF pictures" \
  180.         /dir="c:/download/graphics/gif"
  181. 8   /access=2 /name="Graphics, JPEG/JFIF pictures" \
  182.         /dir="c:/download/graphics/jpeg"
  183. 9   /access=2 /name="Graphics, X-rated animations" \
  184.         /dir="c:/download/graphics/x-anim"
  185.  
  186. 101 /access=2 /hide /rom /name="Simtel20 CD-ROM, June 1992" \
  187.         /info="c:/download/@msdos" /dir="e:/msdos"
  188. 102 /access=2 /hide /rom /name /info=00_index.txt /column=33 \
  189.         /skip=4 /dir="e:/msdos/4dos"
  190. 103 /access=2 /hide /rom /name /info=00_index.txt /column=33 \
  191.         /skip=4 /dir="e:/msdos/abc"
  192.  
  193.  
  194. RAWINFO FILES
  195. -------------
  196.  
  197. By default, allfiles rewrites the rawinfo (by default named @files.raw)
  198. files to the info files used by Waffle (default @files).  At the simplest,
  199. the original Waffle @files can be re-used as rawinfo files.
  200.  
  201. You have two alternatives for this.  You can do
  202.     ren @files @files.raw
  203. (if you are using the default filenames) in each directory on your system
  204. for which you wish to generate a listing for.
  205.  
  206. The other alternative is to change the /info and /rawinfo parameters and
  207. FILEINFO in the Waffle static file to have Waffle use generated files for
  208. reading the info:
  209.     FILEINFO:    @listing
  210. and
  211.     /info="@listing" /rawinfo="@files"
  212. (This will also allow you to edit @files, as you probably are used to do).
  213. Verify that you do not override these settings in the dirs with /info.
  214.  
  215. The rawinfo file may contain wildcards as the first field.  In this case one
  216. line is created into the info file and the listings per matched filename and
  217. an error is generated if no files match the wildcard.  This is a nice way to
  218. keep multi-part file listings' version info etc. always up to date, as the
  219. %t strings are also interpreted for \ escapes.  One should note that the
  220. files are output into the listing in the order the MS-DOS pattern matcher
  221. returns them, which is the same order they appear in the directory.  I find
  222. a directory sorting utility (like Norton's "ds") very useful.
  223.  
  224. Rawinfo may also contain lines starting with a plus '+' (which is illegal in
  225. MS-DOS filenames).  In this case, the special /plusformat output format is
  226. used for that line to the summary files, but no output is produced to the
  227. info file.  I use this to produce subheaders with column titles.
  228.  
  229. Lines which start with whitespace (or are empty) are copied as-is to the
  230. summary files, no output to the info file.  This is useful for comments on
  231. packages and file formats in general.
  232.  
  233. The following examples are produced with the default formats:
  234.  
  235. --the source @files.raw--
  236. +TeleMate 3.10
  237. tm310-?.zip    TeleMate 3.10, part \7 of 3
  238.     TeleMate is a nice terminal program, I use it myself.
  239.  
  240. --generated @files--
  241. tm310-1.zip    TeleMate 3.10, part 1 of 3
  242. tm310-2.zip    TeleMate 3.10, part 2 of 3
  243. tm310-3.zip    TeleMate 3.10, part 3 of 3
  244. --generated summary listing--
  245.               Size  Updated TeleMate 3.10
  246. tm310-1.zip   209k 12/08/92 TeleMate 3.10, part 1 of 3
  247. tm310-2.zip   201k 12/08/92 TeleMate 3.10, part 2 of 3
  248. tm310-3.zip   172k 12/08/92 TeleMate 3.10, part 3 of 3
  249.     TeleMate is a nice terminal program, I use it myself.
  250.  
  251. --
  252.  
  253. OUTPUT CONVERSIONS
  254. ------------------
  255.  
  256. The strings specified in the allfiles configuration file may contain special
  257. output conversions.  First of all, as in C, the character \ precedes certain
  258. one-character escapes:
  259.  
  260.     \a \b \f \n \r \t \v    As in C: BEL, BS, FF, NL, CR, HT, VT
  261.                 Notice that NL is translated to CR-LF on output
  262.  
  263.     \1 \2 \3 \4 \5 \6 \7 \8    The 1st thru 8th character of the filename
  264.                 handled or space if the filename is shorter
  265.  
  266.     \x \y \z        The 1st thru 3rd character of the extension
  267.                 of the filename handled, or space if shorter
  268.  
  269. Note that these \-escapes are also interpreted in the file descriptions
  270. in the rawinfo files, as opposed to the following % conversions.
  271.  
  272. The % conversions are reminiscent to the ones used in the strftime() function:
  273.  
  274.     %a    Abbreviated three-letter english weekday name
  275.     %A    Full english weekday name
  276.     %b    Abbreviated three-letter english month name
  277.     %B    Full english month name
  278.     %d    Day of month
  279.     %f    Tail part of filename being handled (without directory)
  280.     %F    Full filename being handled (with directory)
  281.     %H    Hour in 24-hour clock
  282.     %I    Hour in 12-hour clock
  283.     %L    File length either in bytes or kilobytes; if file is longer
  284.         than 99999 bytes, the length is given in k's (with a trailing
  285.         'k' character), else output is bytes
  286.     %l    File length in bytes
  287.     %M    Minute
  288.     %m    Month number
  289.     %N    Number of directories matched in current summary
  290.     %n    Amount of files matched in current directory
  291.     %p    "am" or "pm" depending on hour
  292.     %S    Second
  293.     %T    File description preceded by extra info for special files
  294.     %t    Basic file description text
  295.     %w    Week day number, 0=Sunday
  296.     %Y    Year with century
  297.     %y    Year without century
  298.  
  299. The conversion character may also be preceded by digits specifying a minimum
  300. field width, a leading zero specifying zero fill (for numeric fields) or a
  301. hyphen '-' to specify right justification within the specified field width.
  302.  
  303. Special information of %T is given for the following file extensions:
  304.     bin    MacBinary file is assumed, and the four-character creator
  305.         information is extracted from the header
  306.     gif    The x and y dimensions and bitmap plane count is extracted
  307.     jpg    The x and y dimensions and bitmap plane count (usually 24)
  308.         is extracted
  309.  
  310. Thus, the allfiles default format string "%-12f%6L%3d/%02m/%02y %T\n"
  311. specifies the following conversions:
  312.     %-12f    Twelve-character right-justified field of the tail filename
  313.     %6L    Six-character file length in either bytes or kilobytes
  314.     %3d    Three-character field of day of month
  315.     %02m    Two-character zero-filled field of month
  316.     %02y    Two-character zero-filled field of year without century
  317.     %T    The file description, with special information
  318.     \n    Output newline
  319.  
  320. To produce output similar to the normal Waffle master listing, one would
  321. use the format "-12f%8l  %02d-%b-%02y  %t\n".
  322.  
  323. Here are some files (as shown by DIR without US settings), and the allfiles
  324. information produced using the default format and the descriptions from a
  325. /rawinfo file:
  326.  
  327. --DIR listing--
  328. ALLFILES DOC    151613 08-16-92   1:21a
  329. GLVIEWER BIN     88064 07-25-92   2:14a
  330. JYBOX    JPG     59682 11-02-91   4:59p
  331. JRGN2910 ZIP    505474 07-25-92   2:14a
  332. HAREMTIG GIF     91729 04-11-91  12:39a
  333. --summary file--
  334. allfiles.doc  149k 16/08/92 All BBS files
  335. glviewer.bin 88064 25/07/92 SIT! GL animation file viewer for Macintosh
  336. jybox.jpg    59682  2/11/91 554x829x24 Our mascot: the steel Venus
  337. jrgn2910.zip  494k 25/07/92 Hacker's Dictionary 2.9.10  ESSENTIAL!
  338. haremtig.gif 91729 11/04/91 496x528x8 'Toon Harem Tiger
  339. --
  340.  
  341.  
  342. UPDATE.BAT
  343. ----------
  344.  
  345. The update.bat batch file that accompanies this package is the frontend
  346. I normally use to generate the file listings and their zipped versions.
  347.  
  348. Edit the parameters in the batch file to match your system settings.
  349.  
  350. Update is normally used without parameters, but it can take up to nine
  351. parameters which will be evaluated after reading in the configuration file,
  352. thus for example overriding the summary file starter in the config file.
  353.     update /begin:"\"List of %t files on MyBBS (at home)\n\""
  354. or
  355.     update /begin:"'List of %t files on MyBBS (at home)\n'"
  356.  
  357. The colon has to be used instead of the usual equals sign '=' because of
  358. command batch file parser syntax limitations, and the double quotes have
  359. to be escaped or the MicroS*t C c0 argument parser will strip them.  The
  360. allfiles parser will also understand single apostrophes as quotes.
  361.  
  362. Unfortunately, this method suffers from the usual command batch parser
  363. limitations and is not really usable (for example, to use it from another
  364. batch file you need to double the percent signs).  Some characters seem
  365. to be impossible in batch file arguments, like commas and equal signs.
  366.  
  367.  
  368. BUGS
  369. ----
  370.  
  371. /begin and /end can be BUFSIZ characters long, others only 80 characters.
  372. The formats of the summary files should be controllable listing-by-listing.
  373. The output should (optionally) be paged.  Something should be done to @banner
  374. files.  I'd like to see an option in Waffle to not "log in" to directories,
  375. and just use the /info files, as they are sure to be correct when produced
  376. with this program.  This would speed logging into a directory quite a lot,
  377. specially on CD-ROM (where Waffle won't be able to rewrite @files, anyway).
  378. A maximum of total 4 gigabytes of files in less than 4 billion files can be
  379. handled (due to 32-bit word length).
  380.  
  381.  
  382.  
  383. Version 6.2 by Otto J. Makela (BBS V.32bis/HST +358 41 211 562)
  384. Distributed under the GNU General Public Licence: see file COPYING for details
  385.  
  386. Otto J. Makela <otto@jyu.fi>
  387. Kauppakatu 1 B 18
  388. SF-40100 Jyvaskyla, Finland
  389.