┌── 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