Beijing Paradise BBS Backup

home *** CD-ROM | disk | FTP | other *** search

/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / LSTGN450.ZIP / LISTGEN.DOC < prev next >

Wrap

Text File | 1991-12-20 | 49.8 KB | 1,519 lines

****************************** * LISTGEN * Files List Generator for use with TBBS Versions 2.0 Through 2.2 Ver 4.50S (ShareWare/Demo) December, 1991 ****************************** The entire LISTGEN package including LISTGEN.EXE and LISTGEN.DOC are Copyright 1991 by Girard M. Westerberg. All rights are reserved. Girard M. Westerberg distributes the LISTGEN software package as ShareWare. You may freely copy and share unmodified copies of the LISTGEN package with others. LISTGEN may be freely distributed via your BBS. This is a demonstration version of LISTGEN. It is NOT being given to you, and you do NOT own it. Instead, you are being given permission to use this demonstration version to evaluate LISTGEN's operation and decide for yourself whether or not you wish to register it. Users who register LISTGEN do not own it either. Instead, they own the right to use the version of LISTGEN they registered for an unlimited period of time. If you like LISTGEN and plan on using it, we encourage you to register your copy of LISTGEN. You'll find a registration form (REGFORM.TXT) included with this package to aid in you with the registration of LISTGEN. We hope you find LISTGEN to be a valuable tool for both you and your BBS system users, and we sincerely thank those of you who have registered previous versions of LISTGEN. It's because of you that LISTGEN continues to be developed. LEGAL STUFF While LISTGEN has been through extensive testing, and has been in regular usage for several years on a large number of BBS systems, Girard M. Westerberg will assume no responsibility for anything that LISTGEN may or may not do on or to your computer system. The user of LISTGEN assumes full responsibility for any and all damages that may result from the use of LISTGEN. LISTGEN Version 4.50 - Page 1 OVERVIEW LISTGEN's primary function is the generation of human-readable lists of files available for download on your BBS system. At Microlink B (our own BBS), we've found that by making files listings available to our users, they tend to spend less time on line searching for the files they want. Instead, they make their file selections off-line by reviewing the master files list. NOTE: LISTGEN does NOT in any way alter the contents of your DIR, FAR, or any other file it uses for input. When building the master files listing, LISTGEN does NOT open or alter any of the files referenced in the DIR file it is processing. Rather, LISTGEN simply LOOKS at the directory entries for these files. ALL input files LISTGEN uses are opened in READ ONLY mode. LISTGEN 4.50 LISTGEN version 4.50, with only a few minor exceptions, is fully compatible with the previous version (4.12). However, this version is not backwards compatible with LISTGEN versions earlier than 4.00. If you are using a version older than 4.00, be sure to real ALL of this manual or you will be missing out on many important features, things won't work properly, and you are likely to get hopelessly confused. NEW FEATURES LISTGEN version 4.50 includes several new features not found in previous releases. Some of the highlights include: - LISTGEN 4.50 is now fully compatibility with TBBS 2.2's various download directory formats. LISTGEN 4.50 will now process both TBBS and PC-Board style DIR files. - Like TBBS 2.2, LISTGEN 4.50 will now allow file descriptions up to 45 characters in length. The old limit was 40 characters. - LISTGEN 4.50 allows the sysop to change many LISTGEN configuration items "on the fly" through the use of "Runtime Directives" which can be placed in the FILES.DIR as hidden comments. - LISTGEN 4.50 now includes a special operating mode for creating a "new files" listing. In this mode LISTGEN will produce a listing of files posted within a specified number of days. - LISTGEN 4.50 allows the sysop to select from a number of international date formats. LISTGEN Version 4.50 - Page 2 GETTING STARTED Before LISTGEN can be used, you must have already constructed and hopefully tested the various FILES.DIRs your particular TBBS needs. If you use FAR files in your TBBS environment, LISTGEN can use them as its "input" files. It will certainly help if you have a decent understanding of TBBS DIR files and FAR files. We suggest you review these topics before bringing up LISTGEN for the first time. LISTGEN can be started from the DOS command line or from a batch file by using the following syntax: LISTGEN [filename] Where [filename] is name of the configuration file LISTGEN will use for processing. You may give the configuration file any name you like, and it may include a full drive and path specification. Use of the configuration filename is optional. If no configuration filename is present on the command line, LISTGEN will look in the default directory (the directory where LISTGEN is started) for a configuration file named LISTGEN.CFG. If it's not found, LISTGEN will revert to its internal configuration defaults. THE LISTGEN CONFIGURATION FILE The basic structure for each active line of the configuration file is as follows: KEYWORD [;comments] or KEYWORD [information and/or command] [;comments] Most of LISTGEN's power and flexibility comes from the use of a configuration file which contains various keywords and commands to direct its processing operations. The configuration file is fairly freeform in structure, and can be created on any text editor capable of producing a standard pure ASCII text file. Comments can be placed anywhere in the LISTGEN configuration file. A comment is always preceded by the ';' character. When using comments, it is important to realize that all text appearing on a line after the ';' character is treated as a comment, and will not be processed by LISTGEN. Here's a very brief sample of what a configuration file might look like (see next page)... LISTGEN Version 4.50 - Page 3 THE LISTGEN CONFIGURATION FILE (continued) Sample configuration file... ; QUIET ; Don't display file processing activity REAL ; Use the real (DOS) filename instead of pseudo name INFILE FILE1.FAR ; This is our "input" filename OUTFILE FILES.TXT ; This is the file LISTGEN will produce IBM ; Strip and/or convert IBM graphics characters ; And so on... There are two basic sets of configuration keywords; those which can make use of an additional command or information, and those which do not. The following keywords do not require additional commands or information: ANSI FF IBM PCB QUIET REAL SUMMARY WRAP If you do place additional information after any of these particular keywords, LISTGEN will ignore it. The following are keywords which can make use of additional commands or information: DATE [date type, 1 - 12] FOOTER [footer text filename] FORMAT [1 or 2] HEADER [header text filename] INFILE [input filename] PAGE [page length] NEW [days] NODESC [missing description text] OUTFILE [output filename] TITLE [title text] NOTE: While these keywords can and will make use of additional commands or information, in most cases the additional information is optional. In most cases, if the additional information is not present, LISTGEN will use its internal defaults. LISTGEN Version 4.50 - Page 4 THE LISTGEN CONFIGURATION FILE (continued) Let's take a detailed look at each keyword and its function. First, the "standalone" keywords (in alphabetical order): ANSI - The ANSI keywords tells LISTGEN to filter out any ANSI sequences it encounters in an input file before placing the associated text in the output listing file. It is important to realize that in this mode, LISTGEN simply filters out the ANSI sequences it encounters. It does NOT take any action based on any ANSI sequences. In other words, if you are using an ANSI cursor positioning sequence for some reason, LISTGEN will filter the ANSI sequence out of the files listing, but will not attempt to figure out where you wanted the cursor to be. Most LISTGEN users will have no use for this feature, since they don't put ANSI sequences in their FILES.DIR, FAR files, or other files LISTGEN uses for input. If you don't make use of ANSI sequences in any of the input files, you should NOT use the ANSI keyword in the configuration file. If the ANSI keyword is present, LISTGEN's processing overhead is increased slightly, and the speed performance of LISTGEN will suffer slightly (but only slightly). LISTGEN's internal default is to NOT perform any ANSI sequence filtering. FF - If the FF keyword is found in the configuration file, LISTGEN will use form feeds instead of multiple line feed/carriage returns to advance to a new page. NOTE: The use of the FF keyword implies that you wish to produce a page formatted report. As such, if the FF keyword is used in the configuration file you do NOT need to include the PAGE statement in the configuration file. In other words, if the FF keyword is used, PAGE is assumed. IBM - If the IBM keyword is found in the configuration file, LISTGEN will convert and/or filter out any IBM graphics characters encountered in any of the input files before placing those characters in the output listing file. This feature comes in handy is you use IBM graphics characters for special effects in any of the input files LISTGEN processes, and you wish to produce a listing that a non-graphics printer can handle. For example (sorry if your printer can't handle this), here is a sample FILES.DIR containing IBM graphics (see next page)... LISTGEN Version 4.50 - Page 5 THE LISTGEN CONFIGURATION FILE (continued) ; ;┌──────────────────────────────────────────────────────────┐ ;│ Microlink B - Word Processor Files │ ;└──────────────────────────────────────────────────────────┘ ; STUFF.ZIP STUFF.ZIP 'JOE BLOW' Stuff for Your Word Processor FILES.ZIP FILES.ZIP 'SYSOP' Some Interesting Word Processor Files ; If the IBM keyword is present in the configuration file, LISTGEN will convert the graphics (in the files listing) to... +----------------------------------------------------------+ | Microlink B - Word Processor Files | +----------------------------------------------------------+ In other words, graphic characters used for drawing boxes and such are converted to their ASCII equivalents when it makes sense to do so. Any IBM graphic characters not converted to an ASCII equivalent are replaced by a space in the output listing file. Use of this feature adds some additional processing overhead, and will slow LISTGEN's processing slightly. As such, you should NOT use this feature unless you really need to convert/strip IBM graphics characters from the output listing file. LISTGEN's internal default is to NOT convert or strip IBM graphics characters. PCB - This keyword tells LISTGEN that it will be processing one or more PC-Board style file directories as opposed to TBBS style file directories. LISTGEN's input file is identical in structure to the TBBS FAR file. As such, it's convenient to use existing FAR files as LISTGEN input files when producing files listings. However, in a TBBS FAR file there is presently no way to select either TBBS or PC-Board DIR file formats. This selection is made in the menu command which calls the FAR file (that we know of). Because of this, in both the TBBS and LISTGEN operating environments, you can NOT mix TBBS style DIR files with PC-BOARD style DIR files in a FAR file. It's an "all or nothing" proposition. We don't know what happens in the TBBS environment if the two formats are improperly interchanged or mixed. In the LISTGEN operating environment, improperly mixing the two formats is likely to cause LISTGEN to crash and burn. Use caution! LISTGEN Version 4.50 - Page 6 THE LISTGEN CONFIGURATION FILE (continued) LISTGEN's default is to operate in "TBBS" mode. That is, it expects to find and process TBBS style DIR files. QUIET - If the QUIET keyword is included in the configuration file, LISTGEN will not display much of what it is doing. Depending on your hardware, operating in quiet mode can drastically reduce LISTGEN's processing time, anywhere from approximately 30 to 70 percent. Since LISTGEN is most often called from a batch file in the middle of the night, there is often nobody present to watch what it's doing. In these cases, use of the QUIET keyword makes good sense. LISTGEN's internal default is to NOT operate in quiet mode. In other words, LISTGEN internal default is to display all of its activity. SUMMARY - The SUMMARY keyword tells LISTGEN to prepare a summary of files processed in each of the file areas it scanned, and to provide total statistics for all file areas scanned. The summary is included at the end of the files listing, just before the footer file text if a footer file is used. LISTGEN's internal default is to NOT prepare a summary. NOTE: If LISTGEN is operating in the "New Files" mode (preparing a "New Files" listing), a summary will NOT be included in the listing regardless of whether or not the SUMMARY keyword is present. Review the information on the NEW keyword for more details. REAL - If the REAL keyword is used in the configuration file, LISTGEN will use the real filename in the DIR file in the output listing instead of the pseudo filename. This feature allows a list to be created that is more suitable for use by persons who do file requests from your system. Instead of the pseudo filename being used in the listing, the actual or real DOS filename is used instead. In cases where these file names are different, a file request will fail if the requester bases his request on a list generated with pseudo filenames. LISTGEN's internal default is to use the pseudo filename in the output listing. NOTE: You may include the full path for the real filename in your DIR file. LISTGEN will filter out everything except the actual file name before placing the information in the output listing. PC-BOARD style file DIRs do not have pseudo filenames. As such, LISTGEN will default to using "real" filenames if you are processing PC-Board style DIRs. LISTGEN Version 4.50 - Page 7 THE LISTGEN CONFIGURATION FILE (continued) WRAP - The WRAP keyword tells LISTGEN to perform word wrap while processing long displaying comment lines which may be found in the FILES.DIR files. With TBBS it is possible to have a displaying comment line in your FILES.DIR up to 255 characters in length. Such a line will be displayed correctly to on-line callers because of TBBS's internal word wrap system. However, if WRAP is not enabled, LISTGEN will place any FILES.DIR displaying comment line "as is" in the output listing file. This can result in a somewhat funny looking listing if the line is longer than approximately 78 characters. If you use the WRAP feature, LISTGEN will format long displaying comment lines in a manner consistent with the rest of the output listing format. While LISTGEN's WRAP feature doesn't significantly increase processing time, you shouldn't use it unless you need to. NOTE: LISTGEN will not attempt to word wrap the header, footer or included text files (if used). It is assumed that you will have already formatted the text in these files to the way you want it to look in the output listing file. LISTGEN's internal default is to NOT perform any word wrapping. LISTGEN Version 4.50 - Page 8 THE LISTGEN CONFIGURATION FILE (continued) The rest of LISTGEN's configuration keywords can make use of an additional command or additional information. In alphabetical order here's a detailed listing of these keywords (we'll discuss the archiving commands as a separate issue later): DATE ## - If the DATE keyword AND format ## selection is present in the configuration file, LISTGEN will format the dates in the output listing according to the selected format. There are 12 possible date formats. To illustrate these, we'll use the date January 15, 1992 as an example. Format # Date Display in File Listing ======== ============================ 1 01/15/92 2 01-15-92 3 01.15.92 4 01 15 92 5 92/01/15 6 92-01-15 7 92.01.15 8 92 01 15 9 15/01/92 10 15-01-92 11 15.01.92 12 15 01 92 Date format #1 is LISTGEN's internal default for date display. FOOTER [filename] - If the FOOTER keyword is present in the configuration file, LISTGEN will place the text found in [filename] at the END of the files listing. [filename] may include a full drive and path designation. If you are using the ANSI or IBM keywords in the configuration file, LISTGEN will take the appropriate action while processing the footer text file. Otherwise, text from the footer file is passed "as is" to the output listing file. If the FOOTER keyword is present, but no [filename] information is present, LISTGEN will attempt to open and use a file called FOOTER.TXT in the default directory (the directory where LISTGEN was started). LISTGEN Version 4.50 - Page 9 THE LISTGEN CONFIGURATION FILE (continued) Some examples of using the FOOTER keyword include... FOOTER LISTGEN will attempt to open a file called FOOTER.TXT in the default directory. Text in this file will be appended to the end of the output listing file. FOOTER /STUFF/FOOTER.ASC LISTGEN will attempt to open and process a file called FOOTER.ASC in the /STUFF directory on the default drive. FOOTER E:\TEXT\FOOT.TXT LISTGEN will attempt to open and process a file called FOOT.TXT in the \TEXT directory on drive E:. FORMAT [1 or 2] - The FORMAT keyword and command [1 or 2] tell LISTGEN which listing format to use. If the command is '1' LISTGEN will produce a listing using the TBBS type 1 format (the same as the listing format for the older TBBS 2.0), where the file creation date appears after the file description. If the command is '2' LISTGEN will produce a listing using the type 2 format (available in TBBS 2.1 and 2.2), where the file creation date appears before the file description. In both cases, LISTGEN will produce a listing that closely matches that which TBBS displays to on-line users. This means that extended file descriptions (available in TBBS 2.1) will appear in the output listing file the same as they appear to on-line callers. NOTE: Even though you may have an older version of TBBS, you can still use the type 2 listing format. This command only establishes the format for the master files listing that LISTGEN produces. In no way does it affect your FILES.DIRs or the operation of TBBS. LISTGEN's internal default is to produce a files listing using format type ONE (file date after the description). Including the FORMAT keyword in the configuration file WITHOUT supplying a format type causes LISTGEN to revert to its internal default, and is functionally the same as not using the FORMAT keyword at all. LISTGEN Version 4.50 - Page 10 THE LISTGEN CONFIGURATION FILE (continued) HEADER [filename] - If the HEADER keyword is present, LISTGEN will place the text found in [filename] at the START of the output listing file. If you are using the ANSI or IBM keywords in the configuration file, LISTGEN will take the appropriate action while processing input from the header text file. Otherwise, text from the header file is passed "as is" to the output listing file. If the HEADER keyword is present, but no [filename] information is present, LISTGEN will attempt to open and use a file called HEADER.TXT in the default directory (the directory where LISTGEN was started). This command functions the same as the FOOTER command, except that HEADER text is placed at the START of the files listing. INFILE [filename] - The INFILE keyword and associated [filename] tell LISTGEN which input file to use for processing. [filename] can include a full drive and path designation. The input file contains a list of DIR files LISTGEN will process. LISTGEN uses an INFILE compatible in structure to the TBBS FAR file structure. As such, you can use your TBBS FAR file(s) as LISTGEN input file(s). If you do not include the INFILE statement in the configuration file, or do not provide the [filename], LISTGEN will attempt to open and use a default file named FILES.FAR in the directory from which LISTGEN was started. (This is slightly different than the default in previous versions.) If LISTGEN can NOT open the specified input file or the default input file, LISTGEN will abort and let you know what caused the problem. NEW [days] - The NEW keyword and associated number of days causes LISTGEN to operate in the special "new files listing" mode. In this mode LISTGEN will create a files listing which includes only those files which are as new as or newer than the number of days specified. For example... NEW 30 This will cause LISTGEN to produce a listing of files which have been posted within the last 30 days. LISTGEN bases its date calculations on the current system date and the file date. If a file date is provided in the DIR file, LISTGEN will use the supplied date. Otherwise, LISTGEN will look up the actual DOS file creation date. Since LISTGEN bases its date calculations upon the internal system date, make sure it's set properly. While debugging the software, I thought this feature was broken until I discovered I had the system date set one year in the future! LISTGEN Version 4.50 - Page 11 THE LISTGEN CONFIGURATION FILE (continued) NOTE: When operating in the "new files listing" mode, LISTGEN will not produce a summary, regardless of whether or not the SUMMARY keyword is included in the configuration file. Likewise, LISTGEN will not include titles which may have been designated with the TITLE keyword. Further, LISTGEN "runtime directives" (described later) are NOT active when operating in this mode. In the "new files listing" mode of operation, LISTGEN produces a fairly basic files listing. This mode DOES work with either TBBS or PC-Board style DIR files. LISTGEN will place a special title in the output listing for each DIR area being processed. This title will indicate the "newness" of the files being listed, as well as the area description (taken from the FAR file). Any file which was posted within the specified number of days will be listed. If an extended description is included with the file, it will also be included in the output listing. You may include HEADER and FOOTER files in a new files listing. Again, keep in mind that LISTGEN's runtime directives are not active in this mode. This is a very new feature of LISTGEN, and could probably be a little more elegant. However, we felt it was better to release LISTGEN now instead of holding it up for further development of this particular feature. We expect this feature to be better developed in future releases. NODESC [text] - The NODESC keyword and associated text tell LISTGEN to insert the text in the description field when it encounters a file which has no description. For example, you might use something like this in the configuration file... NODESC No description given at time of upload In this case, every time LISTGEN encounters a DIR file entry without a description, it will include our 'No description was given at time of upload' text in the output file listing description field. NOTE: The text you provide with the NODESC keyword is limited to 45 characters in length. If it's longer than 45 characters, LISTGEN will chop it to 45 characters. LISTGEN's internal default is to leave the description field blank in the output listing when it encounters a DIR entry without a description. LISTGEN Version 4.50 - Page 12 THE LISTGEN CONFIGURATION FILE (continued) OUTFILE [filename] - The OUTFILE keyword and associated [filename] tell LISTGEN where to place the output files list it produces, as well the name of the file itself. [filename] may include a full drive and path designation. If the OUTFILE keyword is not included in the configuration file, LISTGEN will create an output files list named "FILES.TXT" in the default directory. Including the OUTFILE keyword, but not providing the [filename] information is functionally the same as not including the OUTFILE keyword at all. PAGE [page length] - The PAGE [page length] keyword tells LISTGEN to format the output listing file with page breaks and to include page numbering. If the optional [page length] information if included, LISTGEN will produce a listing that will properly fit on a form of the selected length. If the PAGE keyword is used without providing the [page length] LISTGEN will assume a default form length of 66 lines. As mentioned before, either form feeds or multiple CR/LFs are used to advance to the next page, depending on whether or not the FF keyword is used. LISTGEN's internal default is to NOT perform pagination in the output listing file. TITLE [title text] - The TITLE keyword and associated [title text] tell LISTGEN to print title lines in the output listing. Title lines will be printed at the start of the listing, and at the start of each new file area being processed. The file listing creation date will be included with the title text you supply. For example... TITLE Microlink B Master Files Listing Will result in the following text being printed in the output files listing at the start of the listing and at the start of each new area being processed... Microlink B Master Files Listing - Created on MM/DD/YY Where MM/DD/YY are the month, day and year. The date printed is the system date present when LISTGEN was started, and conforms to the selected date format. LISTGEN Version 4.50 - Page 13 THE LISTGEN CONFIGURATION FILE (continued) The last series of keywords and associated commands have to do with LISTGEN's ability to shell out to your favorite archiving utility to produce an archive containing the output listing file. The basic archiving commands are as follows... ARCHIVE [archiver command/switches] ARCFILE [archive filename] ARCCMT [arc comment text filename] Here they are in more detail... ARCHIVE [arc program and associated command line switches] - The exact syntax of this command will depend on the archiving utility you use. Here are some examples to give you some ideas. ARCHIVE pkzip ARCHIVE arc a ARCHIVE lharc a ARCFILE [path/filename] - This option specifies the location for, and the name of the file your archive utility is to produce. For example, ARCFILE MASTER.ARC ARCFILE LISTING.ZIP ARCFILE D:\TEXT\FILES.LZH ARCCMT [comment file path/name] - This keyword provides optional archive comment information (if your archiving utility supports it). For example... ARCCMT c:\text\comment.txt Let's put these together now, and see what happens. Let's assume our LISTGEN configuration file contains the following information. OUTFILE c:\stuff\files.lst ARCHIVE zip ARCFILE d:\text\master.zip LISTGEN Version 4.50 - Page 14 THE LISTGEN CONFIGURATION FILE (continued) In the above example, after LISTGEN has finished producing the output listing file "FILES.LST", it will shell out to DOS with the following command line: ZIP D:\TEXT\MASTER.ZIP C:\STUFF\FILES.LST Assuming the program "ZIP" is available in the default directory OR in one of the directories referenced in your config.sys PATH statement, the file "MASTER.ZIP" would be created on drive D:, in the \TEXT directory. It would contain the file "FILES.LST" found on drive C: in the \STUFF directory, which is the listing file created by LISTGEN during this run. Let's consider a somewhat more ambitious example. Again, let's assume our configuration file contains the following: OUTFILE files.lst ARCHIVE zip -z ARCFILE d:\text\master.zip ARCCMT c:\stuff\comment.txt LISTGEN will shell to DOS with the following command line: ZIP -Z D:\TEXT\MASTER.ZIP FILES.LST < C:\STUFF\COMMENT.TXT Again, this will produce the file "MASTER.ZIP" on drive D: in the \TEXT directory. In addition, it will cause the text found in the file "COMMENT.TXT" on drive C: in the \STUFF directory to be "piped" in as a "ZIP" file comment. This text will be displayed when your users "UNZIP" the archive. Again, archive comments are not supported by all archiving utilities. Further, LISTGEN doesn't test to see if you have used the proper syntax in calling your archiving utility. Generally, if you do something wrong here, your archiving utility will simply not produce what you expected. LISTGEN Version 4.50 - Page 15 LISTGEN RUNTIME DIRECTIVES With the new "Runtime Directives" we've added a new layer of configuration control to LISTGEN. With the new Runtime Directives you have the capability of changing much of LISTGEN's configuration "on the fly" while LISTGEN is producing a files listing. In addition, you can cause any number of text files to be "included" anywhere in the files listing. Runtime directives are a series of commands which are placed on "hidden" comment lines of the DIR file. Using the TBBS style FILES.DIR, a hidden comment line is one which starts with the '*' character. Hidden comment lines are not displayed to on-line callers (see the TBBS manual for more information about hidden comment lines). LISTGEN 4.50 supports the following runtime directives... @ANSI [ON/OFF] @IBM [ON/OFF] @INCLUDE [filename] @LIST [ON/OFF] @NEWPAGE @PSEUDO @REAL @TITLE [ON/OFF] @WRAP [ON/OFF] Let's look at a sample FILES.DIR which shows how runtime directives are used... ; ; This is a "normal" TBBS comment line ; FILES.TXT FILES.TXT This is an active directory line ; * This is a "hidden" TBBS comment line ; *@REAL This is a runtime directive on a hidden comment line *@IBM ON This turns ON IBM Graphics stripping *@ANSI ON This turns ON ANSI stripping *@LIST OFF This turns OFF the listing until a @LIST ON is encountered ; FILES.ZIP FILES.ZIP Will NOT be listed in the files listing ; *@LIST ON Turn listing back ON ; *@INCLUDE C:\TEXT\STUFF.TXT Include this text in the files listing ; ; and so on... ; LISTGEN Version 4.50 - Page 16 LISTGEN RUNTIME DIRECTIVES (continued) While the function of most of these commands will be fairly obvious, here is a detailed description of each one... @ANSI [ON/OFF] - This directive turns ANSI sequence stripping ON or OFF, overriding what may have been selected in the configuration file. If ANSI stripping is turned ON, it will remain in effect until an @ANSI OFF is encountered. @IBM [ON/OFF] - This directive turns IBM graphics character conversion/stripping ON or OFF, overriding what may have been selected in the configuration file. If IBM graphics character conversion/stripping is turned ON, it will remain ON until an @IBM OFF is encountered. @INCLUDE [filename] - This directive causes text from [filename] to be inserted in the output files listing. [filename] may include a drive and path designation. This directive allows you to insert any text anywhere you like in the files listing. When all lines of the inserted text have been processed, the listing will continue with the first line after the @INCLUDE directive. @LIST [ON/OFF] - This directive turns the listing ON or OFF. When a @LIST OFF directive is encountered, LISTGEN will ignore all DIR lines until a @LIST ON directive is encountered. This allows you to exclude portions of your FILES.DIR from the output files listing. @NEWPAGE - This directive causes LISTGEN to start a new page (assuming pagination has been turned on in the configuration file). If pagination hasn't been turned on, LISTGEN will ignore this directive. @PSEUDO - This directive causes LISTGEN to switch over to using the TBBS "pseudo" filename instead of the "real" filename from the DIR file. It will have no effect if LISTGEN is already using the "pseudo" filenames. This directive has no effect while PC-Board style DIRs are being processed. @REAL - This directive causes LISTGEN to switch over to using the TBBS "real" filename instead of the "pseudo" filename from the DIR file. It will have no effect if LISTGEN is already using the "real" filenames. This directive has no effect while PC-Board style DIRs are being processed. @TITLE [ON/OFF] - This directive causes the inclusion of titles (as defined with the TITLE keyword in the configuration file) to be turned ON or OFF. If titles are turned off, they will remain off until a @TITLE ON is encountered. @WRAP [ON/OFF] - This directive causes LISTGEN's word wrap process to be turned ON or OFF. If wrap is turned off, it will remain off until a @WRAP ON directive is encounter. LISTGEN Version 4.50 - Page 17 LISTGEN RUNTIME DIRECTIVES (continued) NOTE: All runtime directives except for the @REAL and @PSEUDO work with PC-Board style DIR files. These two directives have no meaning with PC-Board style DIR files (as should be obvious). Unlike the TBBS DIR file structure, PC-Board style DIR files do not provide a method for hiding comment lines from on-line callers (that we know of). Use of runtime directives with PC-Board style DIR files is exactly the same as it is with TBBS DIR files. To use runtime directives with a PC-Board DIR file, the comment line is started with the '*' character, followed by the desired @DIRECTIVE command. Lines which start with the '*' character will NOT be included in the output listing just as if they were TBBS hidden comments. We are not really sure what TBBS will do with such lines. We believe TBBS will simply treat such a line as normal comment lines, and display them to the on-line caller. LISTGEN Version 4.50 - Page 18 CONFIGURATION EXAMPLES Here is an example of a fully functional LISTGEN configuration file: ; ;===================================================================== ; Microlink B sample LISTGEN Configuration File ;===================================================================== ; real ; Use real filenames instead of pseudo filenames quiet ; Operate in "Quiet Mode" wrap ; Perform word wrap where appropriate ibm ; Strip/Convert IBM Graphics characters ansi ; Filter out any ANSI sequences encountered page 58 ; Listing has page breaks every 58 lines, pages are numbered ff ; Use form feeds instead of spaces to advance the page summary ; Include the summary at the end of the listing header ; Include HEADER.TXT found in the default directory footer ; Include FOOTER.TXT found in the default directory format 2 ; Use the TBBS type 2 listing format ; ; outfile d:\dn00\FILES.108 ;Create a master files listing called ;FILES.108 on drive D: in the DN00 ;directory ; infile C:\tbbs\FILES1.FAR ;Use a FAR file to tell us ;where to find our DIR files ; ;Print the following title at the start of each file area being ;processed: ; title Microlink B Master Files Listing * (303)-972-9600 ; ; ;Print the following text whenever we encounter a file that has no ;description: ; nodesc No Description Was Given for this File ; ;NOTE: Keywords/commands are not case sensitive, and the spacing :between keywords and associated information is not critical. The ;configuration file is fairly freeform in structure. Commands can ;appear in any order in the configuration file. ;===================================================================== ; ;End of example ; LISTGEN Version 4.50 - Page 19 CONFIGURATION EXAMPLES (Continued) By now the various options available for use in the configuration file should be obvious. However, you are probably wondering what to call the configuration file and how to use different configurations for multiple LISTGEN runs. As mentioned before, usage of a configuration file is optional. If a configuration file isn't found, LISTGEN will revert to using its internal default configuration settings. However, most of LISTGEN's power and flexibility is gained when you do make use of one or more configuration files. If LISTGEN is started WITHOUT a command line argument, it will look in the default directory for a configuration file named 'LISTGEN.CFG.' If found, the options contained in LISTGEN.CFG will be used. If LISTGEN is started WITH a command line argument, it will use the file named in the command line argument as the configuration file. As you can guess, LISTGEN can be called from a batch file multiple times, using a different configuration file each time to produce a variety of differently formatted listing files. For example, consider this sample (and very simple) batch file... REM -------------------------------- REM Simple Listgen Sample Batch File REM -------------------------------- LISTGEN LIST1.CFG LISTGEN LIST2.CFG LISTGEN LIST3.CFG LISTGEN LIST4.CFG LISTGEN D:\BACKUP\LIST5.CFG REM END This batch file will cause LISTGEN to do five different runs, each using a different configuration file. Presumably, each configuration will cause LISTGEN to produce a different kind of listing. The first listing could include graphics and be formatted with page breaks, while the second listing might include the graphics but not the page breaks. The next two listings might be the same as the first two, except that IBM graphics are filtered out of the listings. The last output listing produced might be for a totally different set or category of files. With the technique of using multiple configurations, you can produce a variety of files listings to meet just about any needs you or your users may have. LISTGEN Version 4.50 - Page 20 PC-BOARD DIR FILES Let's take a look at the PC-Board style DIR file structure. An active entry in a PC-Board style DIR file is as follows... Col 1-12: Filename (DOS format) Col 13-14: spaces Col 15-21: File Size in decimal bytes, right justified, blank filled Col 22-23: spaces Col 24-31: Date in MM-DD-YY format Col 32-33: spaces Col 34-78: File description, up to 45 ASCII characters. As a special TBBS variation on the PC-Board DIR format, an owner field in single quotes may precede the description field at column 34. TBBS and LISTGEN will use the owner name just as it does with TBBS style DIR files. Further, if a line begins with a vertical bar (|) as the first non-blank character, it is considered to be an extended description. Both TBBS and LISTGEN will handle this situation just as they handle the '!>' sequence found in a TBBS style DIR file. Any line which does not meet the above conditions is considered to be a normal comment line. The information eSoft provided us for PC-Board DIR file structures indicates the positioning of the various elements making up an active (non-comment) line is critical. It's not very critical to LISTGEN as long as all elements (except for the optional owner field) are present, and each element is separated from the others by at least one space. INCLUDING FILE SIZE AND DATE IN A DIR FILE When the size/date information is supplied in a TBBS DIR entry -OR- when PC-Board style DIR files are being processed, LISTGEN will "take your word" for the size/date information, as well as the existence of the file itself. In this case, LISTGEN will NOT This method allows both TBBS and LISTGEN to quickly process very large DIRs or DIRs on CD-ROMS or other slower storage media. LISTGEN Version 4.50 - Page 21 SUMMARY LISTGEN has been tested on a wide variety of hardware configurations including Western Digital's StarLan, LANTastic, and NetWork OS network environments. It's been tested and is known to work with all DOS versions from 2.1 through 5.0. LISTGEN will display itself in color if you have color hardware. Otherwise, the display is totally compatible with a monochrome text or graphics display. We do hope you find LISTGEN to be of value. I welcome any and all comments regarding the operation of LISTGEN, as well as suggestions for making it better. One last pitch... REGISTER your copy of LISTGEN if you use it. It took many hundreds of hours of writing and testing to bring LISTGEN to where it is today. As I'm sure you can understand, it would be very nice to see some reward for all the time and effort spent in writing and maintaining LISTGEN. You'll notice that this demo version of LISTGEN will not run unattended. It requires a "magic number" be entered before it will run. When you register LISTGEN, you'll receive (via US Mail) a fully "unprotected" copy which runs without entry of the magic number. This demo version is NOT crippled in any way, shape or form. The demo version contains all the features and functions found in the registered version. Registered users will receive via US Mail a single free update when a new release version comes out. Registered users will also receive any bug fixes for the present version via US Mail. Notification of maintenance releases (cosmetic changes/bug fixes) will be made on the TBBS support board. When you register LISTGEN, please be sure to use the registration form (REGFORM.TXT) included with this package. This allows us to properly get you entered into our database so that you will receive maintenance releases and your new-release upgrade. We'd like to thank eSoft for providing much needed information and technical specifications to us prior to the release of TBBS 2.2. Without this information and the kind support eSoft has provided us, this release of LISTGEN would have been considerably delayed. We'd also like to thank Brian Bartee, the sysop of the COMMPOST BBS (1:104/666) for acting as our main beta tester for this release of LISTGEN. Brian helped us track down a couple of bugs, and provided us with some feature requests which were incorporated in this release (except for the exploding windows and rude sound effects, which Brian wanted). We sincerely appreciate YOUR support of LISTGEN. LISTGEN Version 4.50 - Page 22 FINAL THOUGHTS/BUG REPORTS If you make use of TBBS's new replaceable parameters in files which LISTGEN accesses, keep in mind that LISTGEN has no way of processing these parameters (since they exist only in the mind of TBBS while it's up and running). Replaceable parameters will be displayed "as is" in the output files listing. This is not a bug... Just a fact of life. Even though we have tried to test LISTGEN to death, sometimes bugs remain undetected during the test period. I would very much appreciate hearing from you if you encounter any problems with LISTGEN. To accommodate the new ways in which TBBS 2.2 handles DIR files LISTGEN was totally rewritten. Internally, it's a fairly complex animal. It is our sincere hope that we have caught all the bugs in beta testing. As always, we'll do our best to quickly correct any problems that may come up. Address comments, suggestions, bug reports, etc. to: SYSOP HUB-800 Support, FidoNet 1:104/801 or Microlink B (BBS), 1:104/108 (303)-972-9600 or write to us at: Professional Computer Sales, Inc. Post Office Box 620247 Littleton, Colorado 80162 LISTGEN Version 4.50 - Page 23