ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/TEXT/UTILITY/DRC.ZIP/README.SRC

Text File | 1991-11-28 | 9.8 KB | 268 lines

%%*
%%*  README.SRC
%%*  User's guide for David's Readme Compiler
%%*  (c) 1991, David Harris, all rights reserved.
%%*
%%*  Compile an executable readme from this file using
%%*  the command 'RCOM README.SRC'.
%%*
%%*  This line is a comment.
%%*  The next line is the title for the main screen (note the %%T).
%%T  0, David's Readme Compiler - User's Guide
%%*
%%*      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.

The programs can be on the path if you wish, but
they don't have to be.
%%*
%%*     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
%%*
%%*     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.
%%*
%% 0, 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!
%% 0, 0, Using the compiled readme

Once you have compiled and bound your readme, you can use
it at once simply by typing its name.

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.
%%*
%% 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 with products if they wish.

The 
ONLY
 restriction on David's Readme Compiler, is that
you 
may not sell it directly
, although it's OK to include
it as part of another system.

If you want 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, 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]
).

Cheers!
-- David --
27 Nov '91.
%% 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.
%% 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 the following:

   
%%*
    Comment: text to end-of-line is ignored.
   
%%T
    Title: the title on the main screen. An
          optional integer can be included which sets
          the video attribute of the title bar. For
          a list of values, see 
Setting Colour in
          
Windows
 later in this menu.

The other type of marker line is a 
topic heading
: this
consists of 2 mandatory integers, 2 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 
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 
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, The sample file
^   ^   ^  ^   ^   ^──  The title
│   │   │  │   └──────  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, 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 512
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.
%%*
%%*  Note that the file MUST end with a blank '%%' pair.
%%