Media Share 9/MEDIASHARE_09.ISO/utility/drc20.zip/README.SRC

Text File | 1992-08-16 | 23KB | 628 lines

%%*
%%*  README.SRC
%%*  User's guide for David's Readme Compiler v2.0
%%*  (c) 1991, 1992, David Harris, all rights reserved.
%%*
%%*  Compile an executable readme from this file using
%%*  the command 'RCOM README.SRC'.
%%*
%%*
%%*      This line is a comment.
%%*      Note that because of the particular way this file is
%%*      parsed, blank lines ARE significant.
%%*
%%*      The next line is the title for the main screen.
%%*
%%Title             0, David's Readme Compiler v2.0 - User's Guide
%%*
%%*
%%*      The next statement specifies an opening screen, which is
%%*      presented to the user when the program is run.
%%*
%%Opening_screen    2000
%%*
%%*      Now we'll actually declare the opening screen. For
%%*      performance reasons, it should be placed as close
%%*      to the start of the file as possible.
%%*
%% 2000, 0, 0, 0, 8, Welcome to David's Readme Compiler v2

David's Readme Compiler allows you to create standalone guides,
readme files, and other textual references.

Version 2 of DRC supports many new features: if you currently
use DRC v1, please examine the section "What's new in DRC v2"
on the main menu.
%%*
%%*
%%*      Now we'll define a status line for the main screen:
%%*
%%Status_line       2001
%%*
%% 2001, 0, 7, Status line
            David's Readme Compiler, (c) 1991, 1992, David Harris.
%%*
%%*
%%*      Next, define a screen which DRC can present when the
%%*      user asks to edit a topic using the <F10> menu
%%*
%%Edit_screen   2002
%%*
%% 2002, 0, 87, 87, Editing a topic

While you edit this topic, the following keys are
available for your use:

   
Arrows:
       move in the indicated direction
   
Ctrl-Arrows:
  move a word at a time
   
PgUp/PgDn:
    move a screen at a time
   
Tab:
          moves to the next field on the screen:
                 a field is anything starting with a
                 left square bracket (
[
). This feature
                 is handy for designing forms which the
                 user is to complete.
   
Ctrl-Y:
       delete the current line
   
Del, Bks:
     delete char right, delete char left
   
Ins:
          toggle insert mode (defaults to OFF)

%%*
%%*
%%*      And lastly we'll set the default flags values for
%%*      the whole script. We'll use the value 7, which indicates
%%*      that the user can Edit, Save, and Print the readme screens.
%%*
%%Default_flags     7
%%*
%%*
%%*      The next line is the first top-level entry in the file (note
%%*      the type of 0). The second integer means that this entry leads
%%*      to a sub-menu of items of type 100 in the file.
%%*
%% 0, 100, About the Readme Compiler
%%*
%%*
%%*      The next entry is a top level item with no sub-entries: when
%%*      selected, its associated text will display at once.
%%*
%% 0, 0, Installing the Readme Compiler

To install David's Readme Compiler, place the files
README.BIN and RCOM.EXE in a directory somewhere.
Actual location doesn't matter, so long as both are
in the same place. If you intend to use the -s switch
to RCOM to create simple readmes (ie, readmes without
extended searching and formatting features) then you
should also copy README1.BIN to the same location.

The programs can be on the path if you wish, but
they don't have to be, provided they are all in
the same directory.
%%*
%%*
%%*      The next line is an index entry for items of
%%*      type 300: when it is selected, all the items
%%*      of type 300 in the file will be collected into
%%*      a menu and displayed. Notice that the index
%%*      entry itself has no associated text.
%%*
%% 0, 300, Creating a Readme source file
%%*
%% 0, 25, Using David's Readme Compiler
%%*
%% 25, 0, Compiling the source file

To create a standalone guide, enter the command

         
RCOM <filename>

where <filename> is the name of the source file you
have created. RCOM will make a temporary file, and
will then bind it to README.BIN as a .EXE file with
the same name as the input file. That's all there
is to it!
%%*
%% 25, 0, Simplified Readmes

David's Readme Compiler allows you to create two types of
readme; the usual readme has full searching capabilities,
a number of extra formatting features, and enhanced print
facilities, including PostScript printing.

If the size of the final readme is critical, or you don't
need the extra capabilities, you can have DRC create a

simplified
 readme by using the 
-S
 switch on the command
line. A Simplified readme is about 10KB smaller than a
standard readme, but is much less capable.

    Example:  
RCOM -s <filename>

Standard and simplified readmes can be created from the
same file - the syntax is common.
%%*
%% 25, 0, To clear or not to clear...

By default, DRC clears and paints the screen, but you can
force it to come up over the top of the current screen by
by invoking it with a 
/S
 switch: when it terminates, the
screen will be left as it was on entry. This is useful if
you want to use DRC to generate a help system which is
spawned by a parent program.
%%*
%% 25, 0, Running the compiled readme

Once you have compiled and bound your readme, you can use
it at once simply by typing its name.
%%*
%% 25, 0, Using the compiled readme

When your readme is running, the user will normally use it like
a simple menu-driven application. When the user hightlights an
option in a topic list and presses <Enter>, either another list
will appear, or the actual text of the entry. Pressing <Esc>
steps back to the previous list.

At any time the user can press <F10>, which will popup a menu
containing the options which are available at the time. From
a list, only the search options are ever available. From the
text of a topic, the search options and any others you have
enabled will be present in the menu. By default, options other
than the search options are disabled, but you can enable them
on a case-by-case basis, or globally, using the %%D operator
in the source file.
%%*
%% 25, 0, Searching for text

The user can search for text in the readme either by selecting

Find text
 from the option menu, or by pressing 
<F7>
. The
search options cannot be disabled - they are always available.
The 
Find text
 operation always starts at the beginning of the
readme, while the 
Find again
 option starts after the last
find. A short-cut for 
Find again
 is the 
<F8>
 key.

Searches are case-insensitive - so 
NETWare
 is matched the same
as 
NetWare
.
%%*
%% 25, 0, Printing a topic's text

If you have enabled printing on an option, then the user can
select 
Print
 from the options menu. A small dialog will
appear allowing the user to choose a printer port, and to
indicate whether the printer is a PostScript printer. The
values for each setting can be changed by pressing <Space>,
and the user can move between fields using the arrow keys.

DRC's printing is not fancy, but it's functional.
%%*
%% 25, 0, Editing a topic's text

If you have enabled editing for an option, then the user
can choose 
Edit
 from the options menu. If you have defined
an edit-mode screen using the %%E operator, it will appear
as soon as the choice is made.

DRC's editing facilities are not extensive, but they are
perfectly adequate for allowing a user to fill in an order
form or a questionnaire. While editing, the following
keys are available:

   Arrows:       move in the indicated direction
   Ctrl-Arrows:  move a word at a time
   PgUp/PgDn:    move a screen at a time
   Tab:          moves to the next field on the screen:
                 a field is anything starting with a
                 left square bracket (
[
). This feature
                 is handy for designing forms which the
                 user is to complete.
   Ctrl-Y:       delete the current line
   Del, Bks:     delete char right, delete char left
   Ins:          toggle insert mode (defaults to OFF)
%%*
%% 25, 0, Saving a topic's text

If you have enabled saving for an entry, this choice on
the option menu will allow the user to save the contents
of the current topic to a text file.

If editing is enabled, and the user has made changes to
the text, then the changes will also be saved into the
text file.


NOTE
: The Save command does NOT allow the user to alter
the actual readme file itself.
%%*
%% 25, 0, A sample form

This is an example of DRC's forms capability: select

Edit
 from the <F10> menu, then press <Tab> to move
to the first field. Note that you got an instruction
screen when you selected 
Edit
 - a %%Edit_screen
keyword in the field defined that.

Try moving from field to field entering data and
editing the text. Don't worry, you can't alter the
actual readme file itself. Press <Tab> a few times.

    Name:       [                             ]
    Address:    [                             ]
    Phone:      [                             ]

%%*
%%*      Next, we have the first entry of type 100: this
%%*      and the other type 100 entries will be displayed
%%*      as a submenu when the index entry (above,
%%*      "About the readme compiler") is chosen.
%%*
%% 100, 0, What the Readme compiler is...

It's a very rare PC software package indeed these days which
doesn't have a profusion of readme files associated with it.
Readme files can get lost, and it's not immediately intuitive
what you do with them. What's more, it's almost impossible to
create a Readme file which presents the necessary information
in an accessible way.


David's Readme Compiler
 attempts to provide a better way of
creating readme files. It's a set of programs which allow
you to create 
executable user guides
 - one program contains
it all, no need for extra files. You create a simple text
file which tells DRC how to present your guide, run it
through the compiler (RCOM.EXE), and violà! All done!
%%*
%% 100, 0, And what it can do ...

DRC allows you to "nest" text, effectively creating a
hierarchical menu structure. You can do this to an
arbitrarily deep level.

DRC supports colour, and allows printing and extracting
of text. You can highlight words in a message.

DRC has a search command which can look through a file
in a free-text form for keywords.
%% 100, 0, Then, some applications ...

You can use DRC for more than just readme files: here are
some ideas I've come up with.

    On-line manuals for software.
    Help systems, maybe for your LAN.
    Presentations
    Reference systems

   ... and so on. Pretty much anything which involves
   organizing text for reference.
%%*
%% 100, 0, Licensing (good news!)...

The good news about DRC is that it is 
totally free
. You
may use it in any way you wish, without restriction,
obligation, liability or responsibility. Commercial
organizations may distribute all, or any part of David's
Readme Compiler and derivatives with products if they wish.

The 
ONLY
 restrictions on David's Readme Compiler, are that
you 
may not sell it directly
 (although it's OK to include
it as part of another system) and you 
may not alter the

.BIN files in any way
 without explicit written permission
from the author.

If you would care to include a small credit in any readme
you create using DRC, I'd always be grateful, but I don't
even require this.

I hope you enjoy using DRC!
%%*
%% 100, 0, Some technical details...

DRC is written in C, using Borland C++ v3.1. It consists
of about 2,500 lines of C and Assembler for the actual
system, and another 12,000 lines for the user interface
code, which is a routine library (if you are familiar with
Pegasus Mail, you'll probably recognize much of the user
interface of DRC).

If would have been impossible to create DRC without the
help of the best editor ever written, Brief, by Solution
Systems.
%%*
%% 100, 0, And contacting the author.

DRC is written by David Harris, P.O. Box 5451, Dunedin,
New Zealand. If you have problems or questions, I can
be reached by e-mail as 
[e-mail]
 (or from
CompuServe, 
>internet:[e-mail]
).

I can also be reached as [e-mail].

Cheers!

-- David --
15 Aug '92
%%*
%% 300, 0, 94, 90, The sample file

The source file used to create this readme file
is supplied with the system as README.SRC.

You can refer to it to get a general feel for
how the source file needs to be prepared.

(Note, the horrible colours are deliberate!)
%% 300, 0, The general format

The source file for DRC is a single relatively simple
text file, which contains special markers to indicate
topics and section headings. Marker lines are always
introduced by two percentage signs (%%) at the start
of a line. Some marker lines require a character in
the third position - these are described in detail
in the next section.

Lines beginning with 
%%*
 are comments, and are ignored.

The other type of marker line is a 
topic heading
: this
consists of 2 mandatory integers, 3 optional integers
and a title.

  The 
first
 integer is a type field, which is simply
   a numeric tag for the entry. A file can have several
   entries with the same type number, which will make
   up a menu. Type 0 entries are always the top-level
   entries, and a file must have at least one of these.

  The 
second
 integer is either 0, in which case the
   entry has text which should be displayed when the
   item is selected, or a positive value. If it is
   the latter then it indicates that the entry is an
   index for another type of entry: when the item is
   chosen, DRC scans the file for all other entries
   of the type specified and creates a sub-menu from
   them, which it presents to the user.

  The first two 
optional
 integers specify the video
   attributes for text in a the window, and the window
   frame respectively. A table of values is provided in
   the menu (see 
Colour changes in Windows
). You can
   omit one or both of these, in which case DRC will
   assume default values.

  The third optional integer is a flags field, which
   is a bit pattern describing the characteristics of
   the topic, and the options which should be available
   in the <F10> menu. This field is described in detail
   later in this menu. You can set default flag values
   which will apply to all topics with no explicit
   flag field using a %%Default_flag keyword.

  The 
title
 is displayed in the text window, and as
   the choice in the menu.

Example: the line used to create the entry 
The Sample

File
 in this menu:

%% 300, 0, 94, 90, 6, The sample file
^   ^   ^  ^   ^   ^  ^─  The title
│   │   │  │   │   └────  Flags: (Save and Print only)
│   │   │  │   └────────  Frame colour (Lt Green/Magenta)
│   │   │  └────────────  Text colour (Yellow/Magenta)
│   │   └───────────────  Entry is not an index field
│   └───────────────────  The type for this entry
└───────────────────────  The marker line prefix
%%*
%% 300, 325, Keyword markers
%% 325, 0, Keyword markers

The marker lines described in this section have special
meanings in DRC: they are used to alter aspects of DRC's
behaviour, or to enable or disable special features.

DRC actually only examines the first letter of the key-
word, but you can use descriptive names for clarity,
provided they don't contain spaces or tabs.
%%*
%% 325, 0, %%* - Comment

Any line beginning with %%* is a comment, and is
ignored.
%%*
%% 325, 0, %%Title_bar

Use a %%Title_bar line to define a title bar for the
main screen. An optional integer can be included
which sets the video attribute of the title bar. For
a list of values, see the section 
Setting Colour in

Windows.

Example:  
%%Title_bar 31, Sample title bar
    - defines a title bar in white on blue, with
      the text "Sample title bar".

Only the last %%Title_bar option encountered in a
source file will be used.
%%*
%% 325, 0, %%Opening_screen

If you want to define a screen which is presented only
when the readme file is run, use a %%Opening_screen
keyword. This takes one mandatory integer value - the
ID of the screen to present. The screen is just a normal
topic like any other, except that no options are available.

The screen ID should be unique - there should be only
one topic in the file with the number you provide. If
there is more than one, DRC will use the first one it
encounters.

For performance reasons, the opening screen should be
declared early in the source file.

   Example:  
Opening_screen     2000
      - tells DRC to present the screen with the
        ID tag 2000 at startup.
%%*
%% 325, 0, %%Status_line

This keyword declares a status line - text which DRC
will draw along the bottom of the screen. It takes one
mandatory integer parameter - the ID of the topic which
contains the text to display. The topic is just like any
other topic - you can set colours and other attributes.
The status line can be multi-line if you wish, but I
suggest you keep to one or two lines.

This is useful for a help line or a copyright notice.
%%*
%% 325, 0, %%Default_flags

Topics have a flag field which allows you to specify
border values for the window, and what options should
be available in the <F10> menu for the topic.

Use a %%Default_flags keyword to define a default flag
value for all successive topic definitions. The default
will be used for definitions without an explicit flag
field of their own. One integer parameter is required,
the value to use as a default. A full list of possible
flag field values is provided elsewhere in this guide.

You can use %%Default_flags repeatedly throughout the
source file. The value assigned lasts until either the
end of the source, or until another %%Default_flags
keyword is encountered.
%%*
%% 325, 0, %%Edit_screen

You can allow the user to edit screens in your readme
files. If you do, you may want to provide the user
with some help on the keys available while editing,
or other instructions: you can do this using this
keyword.

If an editing screen has been defined using this key-
word, DRC will present it when the user chooses Edit
from the <F10> menu. Once the user has closed the
edit screen, he or she can begin editing the text.

Only one %%Edit_screen can be declared in a file.
%%*
%% 300, 0, Flag fields for topics

The flag field for a topic controls what type of window
border DRC will use, and what features should be made
available in the <F10> menu. It is a bit pattern which
uses the following values:

   Value │ Meaning
   ──────┼───────────────────────────────────────
     1   │ The user may EDIT this topic
     2   │ The user may PRINT this topic
     4   │ The user may SAVE this topic
     8   │ Draw NO border around the topic window
     16  │ Draw a DOUBLE border around the window
     32  │ Draw a THICK border around the window

Add these values to combine effects: so, to have a topic
which the user can EDIT and PRINT, with a thick border,
add 1 + 2 + 32 = 35.
%%*
%% 300, 0, Highlighting text

DRC automatically sizes the window for text according to
the maximum line width, and the number of lines. If there
are more lines than will fit in the Window, the user can
scroll using the arrow and page keys.

You can highlight text in a topic by enclosing it in 
^A

characters
 (the IBM smiley face). You can reverse text
by enclosing it in ^B characters.
%% 300, 0, Colour changes in windows

The colour fields in entry headers are numeric values
which represent IBM screen attributes, according to
the following table:

      Colour          │   Text   │ Background
     ─────────────────┼──────────┼───────────
      Blue            │    1     │  add 16
      Green           │    2     │  add 32
      Cyan            │    3     │  add 48
      Red             │    4     │  add 64
      Magenta         │    5     │  add 80
      Brown           │    6     │  add 96
      Light grey      │    7     │  add 112
      Dark grey       │    8     │  --na--
      Light blue      │    9     │  --na--
      Light green     │    10    │  --na--
      Light cyan      │    11    │  --na--
      Light red       │    12    │  --na--
      Light magenta   │    13    │  --na--
      Yellow          │    14    │  --na--
      White           │    15    │  --na--
     ─────────────────┴──────────┴─────────

      Example:
         
Yellow text on Magenta background
         = 
14 + 80
         = 
94
%% 300, 0, Colour changes in text

Colour changes in text are a little more tricky, and
may not work satisfactorily on monochrome systems.
To imbed a colour change, enter a ^C character in the
text, followed immediately by one of the following
characters:

    
A
   Blue text             
B
   Green text
    
C
   Cyan text             
D
   Red text
    
E
   Magenta text          
F
   Brown text
    
G
   Light grey text       
H
   Dark grey text
    
I
   Light Blue text       
J
   Light Green text
    
K
   Light Cyan text       
L
   Light Red text
    
M
   Light Magenta text    
N
   Yellow text
    
O
   Bright white text

   Example: CCyan, DRed, NYellow, JLight-Green@

   
^C@
 has a special meaning - it means "change to
   whatever the original video colour was".
%%*
%% 300, 0, Limitations and notes

No single entry may be larger than about 16KB and
the file cannot at this stage have more than 640
total entries.

The source file MUST end with a single '%%' pair
on a line of its own.

If running under Novell NetWare, a guide compiled
with DRC must not be flagged Execute-only, although
it can be set to read only.
%%*
%% 0, 0, What's new in DRC v2.0
DRC v2.0 is a considerable enhancement over v1.0. The
following new features are provided:

    Free-text searching (promised, but not delivered
     in version 1.0)
    Enhanced printing, including PostScript support
    User can save the text of a topic to a file
    User can edit the text of a topic
    Forms mode input (using the <Tab> key
    Options menu on <F10> replaces the <P>-Print
     command of v1.0. You have control over which
     options are made available on the menu.
    Startup screen can be specified
    Edit screen: a topic which DRC will present
     when the user asks to edit a topic.
    Status line - you can define text which DRC
     will display along the bottom of the screen.
    Control over window borders
    Simplified readme support - the .BIN file from
     DRC 1.0 is provided with this release, since
     it generates readmes which are about 10KB
     smaller than the default mode. Create a sim-
     plified readme using the -S switch to RCOM.
%%*
%%*  Note that the file MUST end with a blank '%%' pair.
%%