OS/2 Shareware BBS: 2 BBS/02-BBS.zip/rflow130.zip/ReFlow.Doc

Text File | 1995-03-12 | 22KB | 343 lines

      ReFlow for Bulletin Board Systems, (c)1994,1995 Spudsian Software
                             A FILES.BBS utility
                                    v1.30

OVERVIEW:
        ReFlow is a utility I devised due to my irritation with Maximus-CBCS
file description handling.  It will 'Reflow' (or convert) your FILES.BBS
descriptions from a long format to a smaller, user defined, format.  For
example, if your description line for a file in your FILES.BBS is VERY long
(i.e. 255 characters or more), you can use ReFlow to break up the lines into an
easier to read, multi-line, description.  ReFlow can not only break up file
descriptions, it can also combine them!  This means that it can not only break
long description lines into multiple lines, it can also MAKE long description
lines from multiple lines (either prior to ReFlowing, or by itself).
        As an added bonus, I've added routines to ReFlow to create 4Dos(tm)-
compliant description files (DESCRIPT.ION).  This is of use to the 4Dos user
who would like to see the file descriptions by just typing DIR!  NOTE: This
also works well with 4OS/2 DIR command using the /Z commandline parameter.
        As I said previously, I designed ReFlow with Maximus-CBCS in mind.
Maximus BBS systems will only allow 255 characters per line.  Anything
slightly larger is usually okay, but HUGE descriptions (such as are created by
importing FILE_ID.DIZ) can really wreak havoc on the file database management
system of Maximus.  ReFlow can be used by a Maximus SysOp to break the single,
HUGE, description down into an easier, safer format for user viewing.  With the
default parameters active, ReFlow will break up any file descriptions longer
than 255 characters into ONE line of 255 characters.  Then, with the remainder
of the description, ReFlow will create multiple line comments indented, word-
wrapped, and to the proper length for Maximus-CBCS use!  This way, the
description line of the FILES.BBS entry is tailored to the length Maximus can
handle, and the comment lines will be perfectly formatted and correctly
displayed to the user.  If you're not exactly sure what I'm explaining, then
you probably don't have much need for ReFlow! <G>
        And, last but not least, ReFlow is pretty darn fast!  On _my_ system,
running OS/2 Warp Version 3, HPFS on all drives, 512Kb cache, 486DX/2 66Mhz,
8Mb RAM, on an OS/2 commandline, ReFlow processes _AND_ creates 4Dos(tm)-
compatible description files for my ENTIRE filebase (almost 90 areas, including
CDROM areas!  That's over 7000 files with LARGE descriptions!) in just over a
minute!

RESTRICTIONS:
        ReFlow will handle a MAXIMUM description length of 8K.  (That's 8192
characters!!!!)  I don't look at this as a real restriction, but more as a
temporary limit. <G>  If the need should arise and the users of this program
desire to, then I can easily up this limit, or do away with it entirely.
        ReFlow will handle a MINIMUM specified line length (via /d, /f or /4)
of 20 characters.  What this means is that YOU cannot get ReFlow to flow your
description files into lines less than 20 characters.  WHY, on God's green
earth, anyone would want to is way beyond my comprehension! <G>  Think about
it: The SMALLEST description line you can have in a FILES.BBS is (usually) 13
characters (8 filename, 3 extension, 1 dot).  With a description line length
less than 20 characters, that leaves you _7_ characters for a description!
Besides, anything smaller would crash the program. <Grin>
        ReFlow can be used in either DOS or OS/2 platforms, BUT it requires
extra files to run properly (with the exception of REFLOWP.EXE for OS/2-only
users).  It was written in GNU/EMX C so the OS/2 version requires EMX.DLL in a
LIBPATH directory, and the DOS version requires EMX.EXE (for VCPI memory
compliant systems) or EMX.EXE _AND_ RSX.EXE (for DPMI memory compliant systems)
located somewhere in a PATHed directory.
        While ReFlow accepts masks for selecting description files, it will
NOT accept the "*.*" mask.  "*.BBS" or "FILES.*" are okay, but if you specify
"*.*", ReFlow will change it to the default description file, "FILES.BBS".
This _may_ be changed in the future depending on how much of a restriction it
is to the users.
        I suppose there are limits to the various commandline settings
(Indentation, subsequent description length, etc.), but I don't think they
could be very realistic.  Just stick with realistic settings and rely on
common sense (i.e. setting indent to larger than subsequent description
length doesn't make much sense, eh?), then you shouldn't run into any
problems.  I have minimal error-trapping code in the program, so if you need an
'unusually' odd setting, please test it on a backup FILES.BBS first.  More
often than not, if ReFlow has big problems, it will just do a core dump and
stop working.  BUT, there is always the potential of totally hosing up your
description files, so BE CAREFUL!

COPYRIGHT:
        Okay, now for the part of the document where every SysOp wonders what
they can and cannot do with a program.  This software is not shareware.  I'm
releasing this program in the time-honored tradition of FREEware programs for
the Maximus-CBCS family of BBS systems (I retain the copyright to the original
sourcecode).  Use this program for whatever you see fit.  Change it, delete it,
do whatever you wish to/with it.  All I ask is that you always give me proper
credit for coming up with this nifty utility.  This is my first GNU/EMX 'C'
program I'm releasing to the public, and I don't wanna be forgotten <sniff>.
Should you change the code, you do so at your own risk.  I make no guarantees
that I will upgrade my program to work with anyone else's idea.  The only
exception being that you have enough respect for me to tell me the changes you
made.  I ALWAYS stress the value of feedback and ideas.  I'll tell you, future
user of ReFlow, the same I tell my users of my BBS: I cannot make this thing
what you want unless you tell me what you want.  Nuff said.
        All in all, use this program as you wish, but always remember that I
wrote it and retain the copyright to the original sourcecode.  Give it to your
friends, or keep it to yourself.  I wrote this thing for me, and thought it
handy enough to share with everyone else.  Enjoy this program, and let me know
what you think or would like to see in the future.

INSTALLATION:

     Decompress the ReFlow archive (preferably with a native OS/2 decompressor
so as to preserve the EA's for the OS/2 version).  Here is a list of the files
in the archive and what they are for:

        REFLOW.EXE   - The program that does all the work! (OS/2 or DOS)
        REFLOWP.EXE  - The stand-alone OS/2 version
        REFLOW.DOC   - What you are reading now
        HISTORY.DOC  - Detailed version history of ReFlow.
        FILE_ID.DIZ  - Short description of ReFlow for BBS systems.
        EMX.EXE      - The file required for DOS VCPI-compliant systems
        RSX.EXE      - The file required for DOS DPMI-compliant systems
        EMX.DLL      - The file required for OS/2 systems using REFLOW.EXE

     Copy the REFLOW.EXE file to wherever you wish.  For DOS systems, the
EMX.EXE (and RSX.EXE if your system does not support VCPI) must be able to be
located by ReFlow such as the same directory as REFLOW.EXE or somewhere in you
PATH.  For OS/2 systems, place EMX.DLL in a directory specified by your
LIBPATH variable.
      For OS/2 users who don't plan on EVER using ReFlow in a DOS BOX, you can
just use REFLOWP.EXE and completely forget about messing with EMX.DLL,
RSX.EXE, or EMX.EXE!  NOTE: This file runs somewhat faster than the bound
version!
      NOTE TO OS/2 USERS USING REFLOW.EXE IN A DOS BOX: I see little reason
anyone would want to use this native OS/2 program in a DOS BOX, but a little
ditty just in case.  OS/2 DOS BOXes do not support VCPI, so you will need the
RSX.EXE AND EMX.EXE files located in a directory in your PATH.

        Okay, that's it!  It's installed!  Now how to use it:

USAGE:
        ReFlow is very configurable.  I may have written this thing for my own
personal use, and the default values are based on that, but I've coded in
functions so you can deviate from the defaults to work with your own system.
Here is the commandline format:

    ReFlow [/?/4{#}/!/b/c/s/r/i#/f#/d#/k#/m<path>/~] <Path/filename/mask>

        ReFlow, used by itself, will function with the defaults.  Should you
use any of the commandline options, then they MUST come before the filename of
the description file to reflow (if you use one at all).  Listed below is what
each option is for:

        /?  - Show helpscreen
        /4# - 4Dos(tm) mode.  Creates DESCRIPT.ION files for viewing file
              descriptions via 4Dos/4OS2 DIR command.  {default: do not create
              DESCRIPT.ION}
              Optional # is to control how long the description lengths in
              DESCRIPT.ION will be. {default: 215 characters}
        /!  - Do NOT reflow the description file.  Only good use is in
              conjunction with 4Dos mode if you only want to create the
              DESCRIPT.ION. {default: reflow the description files}
        /b  - Make backups of the description file by copying it to a file with
              the extension .BAK. {default: do NOT make backups}
        /c  - Check for ASCII 255 characters in description file.  If found,
              convert it to an ASCII 32 (space) characters.  "Why would I need
              this?" you may ask.  Well, this is only of use to Maximus v2.01wb
              SysOps.  Maximus' file database compilation utility, FB(P), will
              literally choke if it runs into this character in a description
              file.  On my system, if FB(P) found this character in the file,
              it would stop processing the file, thus, leaving out ALL files
              and descriptions after this character!  "What does this
              character look like?" you may ask.  It looks like this _ _
              (between the underscores).  Looks like a space, don't it?  Well
              it ain't!  If you were to bring this document up with a hex
              editor, you would see an 'FF' between the underscores.  I
              personally call this character a "Hard space" as it can be used
              in many places a space character cannot, like a filename.  The
              solution to the FB(P) problem would be to replace all occurances
              of the hard space with a normal space.  As you can tell, this
              could be a nightmare if you had to do this manually!  Finding
              something that looks like a space, but isn't, is hard for the
              human eye, but a piece of cake for a program!  This feature,
              very simply, takes what looks like a space, and MAKES it a
              space! <Grin>
        /s  - Process all subdirectories too. {default: do NOT process
              subdirectories}
        /r  - REVERSE ReFlow mode.  When this parameter is specified, ReFlow
              will combine multiple line descriptions into one LONG
              description line PRIOR to the actual ReFlowing.  Descriptions
              are considered multi-line ONLY when the following lines begin
              with a space character.  If they begin with anything else, they
              will NOT be combined.  If used in conjunction with the /! (no
              ReFlow) parameter, the description file written to disk will
              be in the LONG description line format.  This is VERY handy for
              those of you using *.DIZ formatting programs such as DIZMAN
              which often make poor attempts at creating multiple line
              descriptions.  For those of you familiar with DownSort, this
              parameter works the same way as if DownSort had re-written the
              description file.
        /i# - Indent subsequent description lines # spaces from the left
              margin. {default: 31 spaces}
        /f# - Maximum length of first line of description.  This is what
              actually controls ReFlow.  If any description lines are larger
              than this, then the line will be reflowed. {default: 255
              characters}
        /d# - Maximum length of subsequent description lines.  If the
              description line is larger than the /f setting, then this is the
              maximum length the flowed lines will be. (NOT including
              indentation) {default: 48 characters}
        /k# - Keep first # lines untouched by ReFlow.  This is for any of you
              who use any description 'headers' for the file which are longer
              than the /f setting so that the headers will not be reflowed.
              Most folks will not need this setting unless their header lines
              are longer than the /f setting. {default: 0 lines}
        /mP - Path to the Maximus-CBCS(tm) AREA.DAT file.  This option is for
              the Maximus SysOp who wishes to reflow all description files as
              defined in their FILEAREA.CTL.  Using this option will place
              ReFlow in MAXIMUS mode, withdrawing the filearea path and
              description filename from AREA.DAT.  Before you ask, YES!,
              ReFlow will work just fine with fileareas which have the
              description file in another directory (FILELIST command verb
              mostly used for CDROM areas). NOTE: Using this option with /s or
              a description filename is redundant and the /m setting will
              override and take precedence. {default: NORMAL mode}
        /~  - Fix Rob Hamerling's DownSort v6.0l header bug.  DownSort is
              YAWFP (Yet Another Wonderful Free Program) which is used by
              many-a-Maximus SysOp for it's excellent filebase description
              processing and allfiles lists capabilities.  With the advent of
              version 6.0, it reaches the realms of absolute beauty with it's
              plethera of features, but, unfortuneatly, it has a slight bug.
              If you were to use DownSort v6.0l to create those nice headers
              for your description files, and had any keys/locks defined for
              that filearea, DownSort would place the keys/locks on the first
              column of line 10.  This makes the header look a bit messy as
              it's the same line in which the "Newest File:" is located.  If
              you use this commandline option of ReFlow, it will simply just
              search for the extraneous information on line 10 and remove it.
              Note, however, that ReFlow will automatically place itself in
              SKIP mode to skip the first 13 lines of the description file in
              order to accomplish this 'fix' (attributable to using the /K10
              commandline option).  This should not impact your system if you
              use DownSort headers for all your fileareas.

        The final piece(s) of data which you can specify on the commandline is
<Path/filename/mask to reflow>.  Here is where some TRUE power comes in! <G>
If you specify nothing (default), then ReFlow will use FILES.BBS as a
description file.  If you specify only a path, then ReFlow will use FILES.BBS
as a description file, looking for such a file in the specified path.  If you
specify only a filename or mask such as DESC.* or *.BBS, but NOT *.* (see
RESTRICTIONS: section above), then ReFlow will use the specified filename (or
mask) as a description file.  If you specify a path AND a filename or mask
such as D:\FILEBASE\DESCRIP.BBS or D:\FILEBASE\DESCRIP.*, but NOT E:\*.* (see
RESTRICTIONS: section above).  ReFlow will use the specified filename,
starting from the specified path!  The default is to use the current
directory, and FILES.BBS.
        You may think I'm over-explaining this option, but I find it VERY
important you know how ReFlow works this way especially if you plan on using
the /s option!  ReFlow DOES NOT differentiate between a textfile and a binary
file and will happily reflow your ZIPfiles as well as your file description
files!  This option is VERY powerful, but with such power comes great danger.
MAKE SURE you know what you plan on doing before you do it!  (This warning is
mostly to those non-Maximus SysOps.  Most Maximus SysOps know what it's like
to totally hose your system by fooling around with a powerful option which was
not properly RTFM'd! <G> )
        NOTE: ReFlowing a file which has already been reflowed will not cause
any harm so long as you use the same, or larger, /d and/or /f settings.
Remember, ReFlow only kicks into action when a description line is longer than
the /f or default setting of 255 characters.
        NOTE ON 4DOS(tm) MODE: If you use this mode, Reflow will DELETE any
prior descriptions you had made in that particular directory!  YOU HAVE BEEN
WARNED! <G>  Also, as I couldn't find a function ANYWHERE in the EMX/GNU
library to control the file attributes (i.e. Hidden, System, Read-Only, etc.),
so the DESCRIPT.ION file will show up with the DIR command.  Normally, 4DOS
DESCRIPT.ION files are hidden by nature.  If any of you EMX/GNU programmers
out there know of a way to control file attributes, please send me mail
sharing your wisdom!  Until then, I'll keep searching the EMX/GNU libraries
for a possible solution to this problem.

CONCLUSION:
        So far (as far as I know), this program has ONLY been tested on my
system.  What does that mean?  Well, I can only say that it works just fine on
my 486DX/2-80Mhz VESA localbus OS/2 Warp Version 3 machine with 16Mb of RAM,
over 80 fileareas containing over 7000 files, under Maximus-CBCS v2.02.  All
aspects of ReFlow worked beautifully in BOTH the OS/2 and DOS BOXes (using
4DOS AND 4OS/2) of MY machine.  If it don't work on your machine, sorry, I
don't have access to your machine. <G> Feel free to drop me a line if it don't
work.  (NOTE: Useless NetMail messages such as "It don't work!" or "It sucks
my fishbowl!" will be expediently ignored.  DETAILS are only what will help me
to help you get the program to work on YOUR machine!)
        Well, folks, that's about enough writing for me.  I will most likely be
changing this program as time goes on, so be prepared!  (see FUTURE: below for
ideas I have)  Enjoy, and any feedback, gripes, suggestions, or comments can be
sent Netmail to:
                Mark Zembrzuski (aka: Spudster)
                1:102/[e-mail]

or SnailMail to:
                CEO: Spudsian Software
                15 E. Olsen Rd #10
                Thousand Oaks, CA 91360

(Postcards welcome for those of you who wish to show your appreciation. <Grin>)

WORD OF THANKS:
        This goes out to a Mr. Scott J. Dudley, programmer extrodianairre.
Author and creator of one of the best BBS programs on the market,
Maximus-CBCS.  (He may be slow, but his code is GREAT!)
        Also, a thanks should most definately go out to Mr. Eberhard Mattes,
author and creator of the EMX/GNU compiler.  Without this combination, I
probably would have never decided to port the REXX version of this program to
'C'.  (I use OS/2, I wanted a native OS/2 version, but I cannot afford an
OS/2 compiler! <G>)
        Another thanks should really go out to Rob Hamerling for the creation
of DownSort(tm).  I've really left him out of this 'THANKS' section for much
too long!  If it wasn't for his program making my description file headers (and
allfiles lists) looking so nice, I wouldn't have had enough pride in my
description files to create ReFlow.  Thanks, Rob!  Please don't give up!!!
        Last, but definately not least, my hats off to Rex Conn & JP
Software, Inc. for creating the most advanced commandline interpreter known to
the IBM world.  I am, of course, speaking of 4DOS and 4OS2.  If you are a
SysOp or an advanced computer user who doesn't have this marvelous program, YOU
SHOULD! <G>

THE FUTURE:
        Here is a short list of things I plan to change/enhance as time goes
on:
        . I hate to mention this because I really don't wanna complicate my
          program anymore that it is already, but: Add KEY/LOCK/BARRICADE
          capability for Maximus-CBCS systems.  As it stands now, ReFlow will
          flow EVERY listing in AREA.DAT.
        . Distribute a stand-alone DOS version.  This will most definately
          happen as soon as I wrinkle out a few coding problems I'm running
          into.  When I accomplish this, DOS users will need neither the
          EMX.EXE or the RSX.EXE.  Also, REFLOW.EXE will be better optimized
          and run a bit faster (maybe).
        . Recode the OS/2 version into whatever compiler I decide to buy in
          the future.  EMX/GNU works, and works well considering the price
          (FREE!), but I'm lead to believe a commercial compiler would create
          slightly better output code.
        . Better documentation!  In the immortal words of oh-so-many
          programmers out there: "Dammit, Jim, I'm a programmer, not a
          novelist!" <G>  (If anyone out there would like to re-write this
          documentation, be my guest!  Everyone knows programmers write crappy
          docs! <grin> )
        . And, of course, implement any and all suggestions from yall!

COPYRIGHTS TO OTHER PROGRAMS MENTIONED IN THIS DOC:
        4DOS, 4OS/2 (c)1988-1994 Rex Conn & JP Software, Inc.
        OS/2 Warp Version 3 (c)1987,1994 IBM Corp
        Maximus-CBCS v2.02 (c)1990, 1994 Lanius Corporation
        GNU (c)1991 Free Software Foundation, Inc.
        EMX (c)1993 Eberhard Mattes
        RSX (c)1993, 1994 Rainer Schnitker
        DownSort, Maximus CBCS DOWNload file SORT and List Utility
          (c)1994 Rob Hamerling