Black Box 4/BlackBox.cdr/bbs_ra/dgbg100.arj/DGBG.DOC

Text File | 1991-02-24 | 18KB | 440 lines

        ┌── Thanks for considering DGBG! ──────────────────────────────┐
        │                                                              │
        │                                                              │
        │                                                              │
        │           DGBG is The Darn Good Bulletin Generator           │
        │                       ^    ^    ^        ^                   │
        │               Copyright 1991, Brian McCormick                │
        │                                                              │
        │                                                              │
        │                                                              │
        └───────────────────────────────────────────────── DGBG 1.00 ──┘





























     Distribution and Liability Statement:

         This software is free, and may be distributed for free to other
         people.  Charging a fee for this software is a violation of the
         author's copyright.  As usual with software of this nature, no
         warranty either stated or implied is offered.  By using this
         software, you agree that you assume all liability in connection
         with its use or misuse.

     What is DGBG?

         DGBG was designed for the purpose of compiling a visually
         appealing news bulletin for use on BBS's.  DGBG is only one
         of many such programs, but it supports more useful features
         and is more visually appealing than any similar program this
         author has seen.  Among the features that DGBG supports:

            *  DGBG creates ANSI (.ANS), ASCII (.ASC), and
               AVATAR (.AVT) files.

            *  Each news item is displayed in a window of its
               own.

            *  Input text is automatically line wrapped for an
               optimal fit within display windows.

            *  Each window can be independently positioned, and
               will overlap previously drawn windows.

            *  The background color, text color, frame color,
               frame style, highlight color, and title can be
               set individually for each window.

            *  Sequential display of windows with overlap is
               supported in ASCII, ANSI, and AVATAR output files.



     How to use DGBG

         DGBG works in much the same way as other news bulletin
         compilers.  Like other news bulletin compilers, this program
         scans an input file containing message text and control
         parameters.  The information contained within that file is
         used to produce up to three output files, one containing ANSI
         terminal control information, one a flat ASCII file, and the
         last an optional AVATAR output file.  The ASCII file contains
         no terminal control information other than screen clearing
         codes.  Both files are elaborately formatted and decorated to
         produce a visually appealing display.

         The default input file for DGBG is called DGBG.TXT, and it
         should be present within the directory that DGBG is invoked
         from.  DGBG will look for that file when it starts up, and
         will abort with an error message if the file is not found.
         DGBG can be forced to process a file other than DGBG.TXT by
         providing the name of that file on the command line.  If this
         option is used, all references to DGBG.TXT in this document
         can be considered to apply to the file specified.




                                    2
         Since DGBG.TXT contains both message text and formatting
         commands, there must be a way for DGBG to distinguish
         between the two.  Formatting commands are therefore dis-
         tinguished from message text by the fact that all commands
         start with an asterisk ("*") and must begin in the first
         text column.  Without going into any detail as yet into what
         the various commands mean, the following simple illustration
         should show how commands are distinguished from text:

            *Title Simple Illustration
            This is a line of text

            This is another line of text
            *Style 4
            *Window

         All the lines beginning with an asterisk are formatting
         commands, and all the rest of the lines (including the blank
         one) are lines of message text.

         Text input into the DGBG control file is a fairly straight-
         forward task.  Simply entering the text in paragraph format
         will work.  Line length is not especially important since
         any input text will automatically be line wrapped to a length
         of 60 characters per line.  Input lines should not exceed 110
         characters though, for longer lines may be truncated.

         The line wrapping algorithm in DGBG keys on two things to
         determine when to end a paragraph of text and begin a new one.
         The first of these is a blank line.  Any blank line will cause
         DGBG to finish the current paragraph, skip a line, and begin
         the next one.  Vertical spacing with blank lines is thereby
         preserved in the output files.  A line beginning with a space
         (such as a paragraph indention) will also trigger the end of
         the current paragraph and the beginning of a new one.  In this
         case however, no lines are skipped between paragraphs.  The
         indention is preserved however, and thus horizontal spacing is
         preserved in the output file.  DGBG's line wrapping algorithm
         does NOT remove extra blanks between individual words unless a
         line break also occurs between those words.

         The real power of DGBG is not derived merely from simple text
         input, however.  What makes DGBG special is the ability to
         configure multiple overlapping windows, each with its own
         individual characteristics.  This is accomplished through the
         use of a set of formatting commands.

         DGBG's commands essentially fall into two categories:  the
         Window command and all the rest.  All the commands except the
         Window command are used to set various parameters which will
         be used when the window command is invoked to determine what
         characteristics (such as location, color, etc.) a window will
         have when it is displayed.  Each time a command other than the

                                    3
         Window command (with some exceptions, as will be seen later)
         is invoked, the value of the setting controlled by that command
         is changed.  The order of commands is not important, as long as
         all the desired characteristics of a command are established
         before the Window command is used.  A command occurring twice
         before a Window command will not cause an error.  The last
         value given will be the one used when the window is written to
         the output files.

         Text is processed in a manner similar to the way non-Window
         commands are processed.  It is saved up until a Window
         command is reached, and then it is all put into the display
         window at once.


     DGBG Commands

         Following this section is an alphabetical listing of all
         the commands supported by DGBG.  For each command, both a
         description and a syntax definition are given.

         This document describes the function of DGBG's commands in
         ordinary English, and therefore their purpose should be
         reasonably self evident.  The syntax definitions may not be
         so obvious however, and so the following descriptions are
         given:

            *Command <1..10>

            This syntax means that the (purely hypothetical) command
            "Command" would accept an integer between 1 and 10 as its
            parameter.

            *Command <string>

            This syntax means that the command would accept a
            character string as a parameter.

            *Command [<string>]

            When the parameter is enclosed in square brackets,
            it is optional. In this case, the command "Command"
            would accept either a string parameter or no parameter
            at all.

         Many of the commands deal specifically with color.  The
         specific color values available vary from command to command
         and are given in the syntax definition for each command.
         The following chart shows what colors are associated with
         each color value:




                                    4
                                 Non-Blinking

                     0 - Black           8 - Dark Gray
                     1 - Blue            9 - Bright Blue
                     2 - Green          10 - Bright Green
                     3 - Cyan           11 - Bright Cyan
                     4 - Red            12 - Bright Red
                     5 - Magenta        13 - Bright Magenta
                     6 - Brown          14 - Yellow
                     7 - Light Gray     15 - White


                                   Blinking

                    16 - Black          24 - Dark Gray
                    17 - Blue           25 - Bright Blue
                    18 - Green          26 - Bright Green
                    19 - Cyan           27 - Bright Cyan
                    20 - Red            28 - Bright Red
                    21 - Magenta        29 - Bright Magenta
                    22 - Brown          30 - Yellow
                    23 - Light Gray     31 - White

         With that out of the way, here are the commands:

     AVATAR

         Syntax:  *Avatar

         The Avatar command enables the output of a file ending in
         the extension .AVT containing AVATAR terminal control
         information.  This option is for Sysops who are running
         BBS's that support the AVATAR terminal type as described
         in FSC-0025.  AVATAR output is not produced unless this
         command is given.  The AVATAR command must be issued before
         the Path command in order to have any effect.

     BACKGROUND

         Syntax:  *Background <0..7>

         The Background command is used to set the color that will be
         used as the background of the next window to be drawn.  The
         default value used if no Background command is issued is
         one (blue).

     FRAMECOLOR

         Syntax:  *Framecolor <0..31>

         The Framecolor command is used to set the foreground color of
         the frame around the next window.  The default value for this
         parameter if it is not given is five (magenta).

                                    5
     HIGHLIGHTS

         Syntax:  *Highlights <0..31>

         The Highlights command sets the foreground color used for
         displaying the window title, prompt, and DGBG edition stamp.
         The default setting is 15 (white).

     MESSAGECOLOR

         Syntax:  *Messagecolor <0..31>

         The Messagecolor command establishes the foreground color which
         will be used for actual news text within a window.  The default
         setting is 10 (bright green).

     NORIMS

         Syntax:  *Norims

         Without the benefit of color, the output of DGBG can be
         difficult to read because the lines separating windows do not
         always define the window well enough to separate it from other
         windows that it overlaps.  Since ASCII files never have color,
         DGBG by default draws in a blank line above and below each
         window in the ASCII output that overlaps another window.
         These blank lines, or "rims" can be disabled by using the Norims
         command.  All windows drawn after the Norims command is used
         will be rimless.  The Norims command can not be reversed except
         by removing it from the configuration file altogether.

     PATH

         Syntax:  *Path <string>

         This command establishes the path and name of the output files
         and causes those files to be opened.  This command should only
         be used once.  Do not provide an extension as part of the argument
         to the Path command.  The extensions .ASC, .ANS, and .AVT will
         be automatically appended by DGBG.  There is no default value,
         and this command must be issued before the first window command
         is issued.

     STYLE

         Syntax:  *Style <1..12>

         The STYLE command is used to select the style of frame which
         will surround the text in the next window to be shown.  There
         are twelve frame styles as shown at the top of the next page.




                                    6
        ┌─┤ Frame Style 1 ├────────┐     ┌── Frame Style 4 ─────────┐
        │ Single line with serifs  │     │ Single line w/o serifs   │
        └────────────┤ DGBG 1.00 ├─┘     └───────────── DGBG 1.00 ──┘

        ╔═╡ Frame Style 2 ╞════════╗     ╔══ Frame Style 5 ═════════╗
        ║ Double line with serifs  ║     ║ Double line w/o serifs   ║
        ╚════════════╡ DGBG 1.00 ╞═╝     ╚═════════════ DGBG 1.00 ══╝

        █▀█ Frame Style 3 █▀▀▀▀▀▀▀▀█     █▀▀ Frame Style 6 ▀▀▀▀▀▀▀▀▀█
        █ Thick border with serifs █     █ Thick border w/o serifs  █
        █▄▄▄▄▄▄▄▄▄▄▄▄█ DGBG 1.00 █▄█     █▄▄▄▄▄▄▄▄▄▄▄▄▄ DGBG 1.00 ▄▄█

        ┌─[ Frame Style 7 ]────────┐         Frame Style 10
        │ Single line w/ brackets  │       No frame
        └────────────[ DGBG 1.00 ]─┘                    DGBG 1.00

        ╔═[ Frame Style 8 ]════════╗     *** Frame Style 11 *********
        ║ Double line w/ brackets  ║     * Asterisks                *
        ╚════════════[ DGBG 1.00 ]═╝     ************** DGBG 1.00 ***

        █▀[ Frame Style 9 ]▀▀▀▀▀▀▀▀█     +-| Frame Style 12 |-------+
        █ Thick border w/ brackets █     | ASCII only               |
        █▄▄▄▄▄▄▄▄▄▄▄▄[ DGBG 1.00 ]▄█     +------------| DGBG 1.00 |-+


        The default setting for the Style command is two (double line
        with serifs).

     TITLE

         Syntax:  *Title [<string>]

         Sets the value for the title string that will be used when the
         next Window command is issued.  If no parameter is provided,
         the next window will not have a title.  The default setting is
         for no title, and the maximum title length is 50 characters.

     WINDOW

         Syntax:  *Window

         When the window command is issued, all of the current color,
         title, etc. settings and the message text collected since the
         last Window command (or the beginning of the file if there was
         no previous window command) is used to create a window.  That
         window is then written to the output file.

         If no Window command is found in the configuration file, DGBG
         does not produce any output.  The last command in the
         configuration file should therefore be a Window command.




                                    7
     X

         Syntax:  *X <1..16>

         Sets the X coordinate (column) at which the upper left hand
         corner of the next window to be drawn will reside.  The default
         X value of nine produces a window which is approximately
         centered (horizontally) on the screen.  The X and Y coordinates
         should be altered if an overlapping window effect is desired.
         If they are not, windows will simply overwrite one another.

     Y

         Syntax:  *Y <1..10>

         Sets the Y coordinate (row) at which the upper left hand
         corner of the next window to be drawn will reside.  The
         default setting of six produces a window which is approx-
         imately centered on the screen.  The X and Y coordinates
         should be altered if an overlapping window effect is desired.
         If they are not, windows will simply overwrite one another.


      Final Words

         If you believe you have found a bug in this program, first
         go back and reread the documentation, make sure you have
         at least files=25 in your CONFIG.SYS, and perform all the
         other normal double checks.  If you are still unable to
         get the program to work, and think you have found a bug,
         please attempt to send me netmail and I will see what I
         can do.  I am currently accepting netmail at 1:391/21. I am
         a college student however, so this should not be considered
         a permanent arrangement.  After 1 May 1990, just look for
         Brian_McCormick in the FidoNet nodelist.  Regrettably, I am
         too poor to provide unlimited support for this program, but
         if you can contact me, I will be more than happy to look
         into any bug reports, and I will fix any real bugs that can
         be found.

         I would like to thank Bernard Johnson of DigiKing BBS
         (1:391/16) for assisting in testing this program and for
         his many valuable suggestions.  Without his help, DGBG
         would not be what it is today.  Also instrumental to the
         development of this program was Greg Langham of Ozark
         Connection BBS (1:391/7), who wrote a program that set
         the standard for this one.  (Please don't bother Bernard or
         Greg about support for this program, because they do not
         have the source.)





                                    8