Category : Miscellaneous Language Source Code
Archive   : COGTEX.ZIP
Filename : CTHELP.CTX

 
Output of file : CTHELP.CTX contained in archive : COGTEX.ZIP
.chap Main

Help is available on the following topics:

<%Overview%> The big picture
<%KeyBoard%> What the various keys are used for
<%Command Subsystem%> Use of the F2 menu system
<%Creating CogentText%> How to convert a document to CogentTEXT
<%Cogent Prolog Predicates%> Help system for underlying Prolog
<%Environment%> Tailoring CT to meet your needs

Choose topic using the space bar and then hit Enter,
or hit Esc to leave help.

.x

$Overview$ : visit_chap($Overview$).
$KeyBoard$ : visit_chap($Keyboard$).
$Creating CogentText$ : visit_chap($Creating_CogentText$).
$Command Subsystem$ : visit_chap($commands$).
$Cogent Prolog Predicates$ : pred_help.
$Environment$ : visit_chap($files-used$).

quit.
.end_chap

==============================================================================

.chap Keyboard

CogentText makes use of the following keys:

SpaceBar or TabKey - Move lightbar between buttons
Home - Move lightbar to first button
Enter - Press button under lightbar
PgUp - Go to previous page in current chapter
PgDn - Go to next page in current chapter
Esc - Leave current chapter
F1 - Get to this help system
F2 - Get to command menu

.end_chap

==============================================================================

.chap Overview

CogentTEXT works by displaying information contained in text
files. The information consists of two parts

TEXT - this is displayed in windows on the screen.

EXECUTABLE CODE - this consists of small programs which
are, in general, attached to different portions of
text.

The code section is not displayed but it is executed by a built in
<%Prolog%> <%interpreter%> in the system.
.x
$Prolog$ : visit_document('prolog.ctx', $Main$).
$interpreter$ : small_message($
This means there is no need
to compile or otherwise process
the code. When the system reads
the code it executes it directly$).
quit.

.page ----------------------------------------------------------------------

A portion of text which has attached code is called a <%Button%>.
The text of a button is usally highlight on the screen and
can be 'pushed' by choosing it with the light-bar (pressing
the space key) and the hitting the Enter key.

When a button is pushed, any code attached to it is
executed. This is the basic mechanism behind all that CogentTEXT
achieves.

The code attached to the button is called an <%Action%>. Actions
can be any valid Prolog program, but usually the code just
turns to another <%linked%> section of text and displays it.
.x

$Button$ : visit_chap($Buttons$).
$Action$ : visit_chap($Actions$).
$linked$ : small_message($
It is the construction of buttons
and actions by the editor of the
document that allows this linking
of concepts, text etc.$).

quit.

.page -----------------------------------------------------------------------

It is important to realize that the Code section is 'attached'
to the page.

This means that the code is defined only when the page is being
displayed. When a new page is displayed any code defined by
the previous page is removed from the database.

This means that buttons with the same text can be attached to
different actions on different pages (but the text defines a
unique action on any given page).

Also, note that code for a page does not need to be attached to
a button. You can define ordinary prolog predicates using the
':-' operator and these will also be abolished when the page
is replaced.

.page ----------------------------------------------------------------------

The TEXT/CODE is divided into named documents - each in a file
of the form name.ctx.

Documents are divided into named CHAPTERS, and each chapter
is divided into pages which may or may not be named.

<%Predicates%> are given which open a new document, move
to a specific chapter or move to a specific page. These
predicates will be the most commonly used actions since they
allow you to move through the document,
.x
$Predicates$ : visit_chap($builtin_acts$).
quit.

.end_chap

==============================================================================

.chap Creating_CogentText

CogentText is created by editing text in a text editor. Plain
text is annotated by dividing it into logical sections
and then specifying what actions are associated with
buttons on a screen.

The following topics are explained

<%Document Sections%> <%Actions & Buttons%>
<%Variables%>

One a document has been edited it should be <%indexed%> for
speed. NOTE: If you modify a .CTX file then you MUST either
re-index the file or delete the index file.

.x---------------------------------------------------------------------------

$Document Sections$ : visit_chap($Document_Sections$).
$Actions & Buttons$ : visit_chap($Actions$).
$Variables$ : visit_chap($Variables$).
$indexed$ : visit_chap($index_doc$).

quit.
.end_chap

=============================================================================

.chap Document_Sections

To take full advantage of CogentText a document should be
divided into sections. A document is divided into CHAPTERS,
and each chapter is composed of a number of PAGES.

All annotation of a text document is done using dot commands.

A dot command is a sequence of characters, beginning with a
period - "." - as the first character on the line of text.

If a line in a document begins with a period it
will NOT be displayed but rather it will be taken
as a directive to do something by the CogentText system.
Otherwise the line will simply be displayed on the screen.
.page
A chapter is indicated by placing two markers in the text

.chap <%OptionalName%>

You text goes here -- it can be as much or
as little as you like.

.end_chap

Notice the .chap and .end_chap markers. They must be positioned
so their leading "." is the first charcter on the line.
For clarity we have indented them in this example.

Any text on lines between the .end_chap and the next .chap is
ignore, so you are free to place comments here if you wish.
.x ---------------------------------------------------------------------------

$OptionalName$ : small_message(
$A Chapter may be named - it will appear
in the window frame, and it permits the
chapter to be "visited" from another
chapter.

The Name is separated from the .chap
by exactly one space, and may contain
no spaces.$).
quit.

.page ======================================================================

You can page up/down through the text in a given chapter,
but when you reach the end of the chapter you cannot page
beyond it.

Hitting Esc at any point will get you out of the current
chapter and return you to the chapter from which you were
visiting.

Size of chapters is limited only by disk size, but it is
recommended they be kept to a moderate size since they
are constantly being searched by the CogentText system.

.page ========================================================================
Chapters are divided into pages separated by the ".page"
command. Again this command must occur at the beginning of
a line. The .page command denotes the END of a pages (and, by
default, the begining of another). So, for example

.chap Regulations

The regulations regarding the sale of company
assets fall into three categories

.page <%OptionalName%>
a).. b).. c)..

<%.end_chap%>
divides the chapter into two pages. Notice that the first page
will have a leading blank line whereas the second will not.
.x ---------------------------------------------------------------------------
$OptionalName$ : small_message(
$A page may be named - it permits
the user to refer to the page
by name rather than number.

The Name is separated from the .page
by exactly one space, and may contain
no spaces.$).

$end_chap$ : small_message(
$The end-of-chapter marker also serves
as an end of page marker and so the final
.page is not required$).

quit.
.page =====================================================================
Each page of text will be displayed in its entirety in the current
chapter window. If there are <%too many%> lines to be displayed in full
then the lines will scroll until the last line is printed. Lines
scrolled off the top of the window by this process will be lost.

Each page may be divided into <%several%> intermixed sections of text
to be displayed and code to be executed. The command ".xec" is used
to separate the two types of areas. For example

.chap
This is text -- it will be displayed
in the page
.xec
<%Code%> goes here .. it is not displayed
.page
Next page .. text
.x ---------------------------------------------------------------------------

$too many$ : small_message($Each window holds eighteen\nlines of text$).

$several$ : small_message($Usually, at most one of each$).

$Code$ : visit_chap($Actions$).

quit.
.end_chap

==============================================================================

.chap Actions
The Code <%Section%> of a Page contains a list Actions that
are to be taken if a certain <%button%> (highlighted text)
on the screen is pressed. It may also contain raw Prolog code.

The Code section consists of a statements of the form

<%$Text-of-Button$%> : Action<%.%>
or
<%Head%> :- Body. % A conventional <%Prolog clause%>

When a button is pressed, the CogentText system will look
through its list of action statments and try to find one whose
head (the text contained in $ $) matches the text of the button.

If it finds a matching statement then the Action in the body of
the statement is executed and then control returns to the screen.
.x ---------------------------------------------------------------------------
$Section$ : visit_chap($Document_Sections$).
$Prolog clause$ : visit_document('prolog.ctx', $Main$).
$button$ : visit_chap($Buttons$).
$Head$ : small_message(38,10,
$The head of the clause may be
omitted. In this case the clause of
form ':- Body.' is called a latent
expression and the body is executed
at the time the code is loaded.
Consequently, if Body depends on
any other code in the page, the
latent expression must be placed
AFTER dependent code.$).

$\$Text-of-Button\$$ : small_message(
$Exactly the same text as is contained
within the <ÿ% and %ÿ> defining the
button. Note the text in the action must
be contained inside dollar signs \$.$).

$.$ : small_message($Do not forget the terminating "."$).

quit.

.page ========================================================================

Actions (the right hand side of Button : Action) is how
CogentText actually gets things done. In general, the Action
can any valid <%Prolog%> goal (or conjuction of goals). So
they have the form

goal.
or
goal1, goal2, goal3, .. goaln.


When the proof of the goal (or conjunction) finishes
(in either success or failure, it doesn't matter) the user
is return to the page with the lightbar postioned
where it was before.

.x ---------------------------------------------------------------------------
$Prolog$ : visit_doc('prolog.ctx', $Main$).

quit.

.page
The action may be any Prolog goal, but we have added a number
of useful built-in predicates which permit navigation of the
hypertext system freely. Hit any key to continue on with the
a introduction to these built in predicates.

HIT A KEY
.x ---------------------------------------------------------------------------
% Clever stuff here when we read this we doit !!

:- get0_noecho(_), % Wait for the key
visit_chap($builtin_acts$), % And go here
leave_chap. % Leave this chapter behind us
quit.
.end_chap

==============================================================================

.chap builtin_acts

We have built in several useful predicates which "know"
about the hypertext system and can exploit it.

These only make sense when they appear in the hypertext
code section of a page (they rely on sideffects from the running
hypertext system)

.page
The currently supported builtins are as follows:

turn_page % Turn to the next page of the document

leave_chap % Returns to previous chapter (or leaves if top level)
% This is exactly the same result as hitting Esc
visit_document('DocName', $ChapName$)
% Visits the named document (doesn't need .ctx suffix) at the
% named chapter. When you leave you get back to where you were

visit_chap($Chap Name$)
% Visit named chapter - when you return from it you return
% to where you were

goto_page($Page Name$)
% Goto named page -- you cannot return automatically to the
% page you were at when you called this
.page
small_message($Message$).
% Displays a 8 x 40 window in the centre of the screen and writes
% Message to it. The window is cleared when the user hits a key

small_message(Width, Height, $Message$)
% Displays a Height x Width window in the centre of the screen and
% writes Message to it. The window is cleared when a key is struck

prompt(Width, Height, $Title$, $Msg$, Resp)
% Displays a Height x Width window in the centre of the screen and
% writes Message to it. The window has title $Title$. The string
% typed in by a user terminated with is returned in Resp

The string, Resp, can be <%parsed%> by Prolog Definite Clause
Grammars (<%DCG%>s) and values (integers, reals etc) pulled
from the string.
.x ---------------------------------------------------------------------------

$parsed$ : visit_chap($Parsing$).
quit.

.end_chap

==============================================================================

.chap Variables

A variable occurs in the text portion of a page and is indicated
by surrounding a valid Prolog atom name in < ! and !ÿ> brackets.

For example the text < !my_name! > would indicate
a variable called my_name.

When CogentText sees this variable name as it writes out the
text it forms a Prolog Goal

my_name(X)

which it then tries to prove. my_name(X) should succeed with
X being bound to a character list. CogentText then writes out
THIS List and not my_name. For <%example%> we will query you
for your name and print it out on the next page ...
.x

$example$ : prompt(30, 1, $$, $Type your name: $, Str),
string_list(Str, L),
assert(your_name(L)).
quit.
.page

The following text contains the variable called your_name.
We have asserted the fact your_name($$) into the
Prolog database when you answered the previous prompt.

If you did not run the 'example' button on the previous page
then your_name(X) does not exist and so CogentText will
print the string !UNKNOWN! instead.

So, this is your name ? :

Go back to the previous page if you want to and run different
names into 'example'.
.x
:- abolish(your_name, 1).
quit.

.end_chap

==============================================================================

.chap Parsing

CogentText has some built-in predicates to parse Lists. Since
prompt() returns a string as its last argument we will need to
use

<%string_list%>(String, List).

Armed with a list, we can now parse off values from the user
supplied response e.g. :

prompt(5, 10, $ Title $, $Type something$, Resp),
string_list(Resp, List),
--- process the list ---

.x ---------------------------------------------------------------------------

$string_list$ : help(string_list/2).

quit.
.page

The predicate supplied for parsing lists is

sscanf(ListIn, ControlList, Vars)

ListIn is the list to be parsed, Control List is a list
which describes the pattern in which the input list is to
be parsed, and Vars is a list of variables to hold the values
resulting from the parsing.

Readers familiar with the "C" programming language will
recognize this predicate is as being closely modelled
on the "C" function of the same name.

.page

The control string consists of

* 'Ordinary characters'. Each character must match its
corresponding character in the input list.

* Conversion specifications. This is a pair of characters
of the form %X where X may be any of the characters listed
below. For each conversion spec. there must be a
corresponding variable in the VarList. The matching portion
of the input list is parsed into a form specified by the X
character, and the value is placed into the
corrsponding variable.

For example, %d specifies an integer should be parsed. So, the call
sscanf("123", "%d", [Var]) will bind Var to the INTEGER 123.
.page

The conversion characters accepted are

d - parse a decimal integer
f - parse a floating point number
w - parse whitespace (spaces, tabs, control characters
etc). This does NOT return the value into a variable.
a - parse an atom - a series of characters
containing no white space
s - parse of the rest of the list
c - parse the next character in the input list
% - matches the character '%' in the input stream
(does not bind a value)
.page

So now consider the code

$<%foo%>$ : prompt(40, 5, $ Test $,
$Type two integers (seperated by spaces) : $,
Resp),
string_list(Resp, List),
sscanf(List, "%w%d%w%d%s", [I1, I2, Junk]),
Val is I1 + I2,
small_message('The sum of the integers is ' : Val).

We use scanf to parse - some optional whitespace, an integer,
some more optional whitespace, an integer, and then we ignore
the rest of the input (binding it to Junk).

.x ---------------------------------------------------------------------------
$foo$ : prompt(40, 5, $ Test $,
$Type two integers (seperated by spaces) : $, Resp),
string_list(Resp, List),
sscanf(List, "%w%d%w%d%s", [I1, I2, _]),
Val is I1 + I2,
small_message(('The sum of the integers is ' : Val)).
quit.

.end_chap

==============================================================================

.chap Buttons

A button is an area of highlighted text on the screen which
has an action associated with it. Text is made into a button
by enclosing it in the delimiters <ÿ% and %ÿ>
.end_chap

==============================================================================

.chap commands

The command option is available by hitting F2 whenever
the system is displaying a screen and you are able to
use the hypertext move keys (page-up, page-dn etc).

Hitting F2 causes a menu to be displayed with the following
options

<%VisitDoc%>
<%Print Page%>
<%Index Doc%>
<%Toggle GC%>
<%Edit File%>
<%Enter DOS%>
<%Return%>
.x ---------------------------------------------------------------------------

$VisitDoc$ : visit_chap($visit-doc$).
$Print Page$ : visit_chap($print_page$).
$Index Doc$ : visit_chap($index_doc$).
$Edit File$ : visit_chap($edit-file$).
$Enter DOS$ : visit_chap($enter-dos$).
$Return$ : visit_chap($Return$).
$Toggle GC$ : visit_chap($toggle-gc$).

quit.
.end_chap

=============================================================================

.chap index_doc

Index Doc
---------
This option allows you to specify the name of a hypertext
document file to be indexed. An index file (name.cti is the
index file for document file name.ctx) allows page and
chapter searches to be executed far quicker. However, an
index file is not mandatory.

If you select to index a file you will be prompted for the
name of a document file. Type in its name (you may omit the
".ctx"). A message will appear indicating that indexing is
taking place and then the commands menu will vanish, putting you
back in the hypertext document.

.page

Note that the index file is Not loaded by this operation.
However the next time the named document is entered, the
newly created index file will be loaded and document browsing
will be much faster.

It is essential that the index file always reflect the
latest version of the text file.

.end_chap

============================================================================

.chap visit-doc

Visit Doc
---------

This option allows you to visit a specified chapter
in another document.

You will be prompted for the document name and then
the chapter name. When you return from the visited
document you will be back to where you started.

If the specified chapter does not exist, you will be
placed at the first chapter in the visited document.

.end_chap

==============================================================================

.chap print_page

Print Page
----------

This option prints the current page on the screen to a
printer. To determine which port the output is sent to
edit the file <%prolog.env%>.

Find the line ioport(printer, 'XXXXX'). and change
the XXXX to whichever port you want (e.g. 'lpt1', 'com2' etc).
.x
$prolog.env$ : small_message($
The is the Cogent Prolog Environment
file. It contains many parameters
which Prolog uses e.g. screen colors,
name for an editor, I/O ports etc.$).

quit.

.end_chap

==============================================================================

.chap edit-file

Edit File
---------

You are prompted for a file name and then the editor
specified in the <%prolog.env%> file is invoked on the
file (it is assumed that the editor is invoked at the
DOS level by typing file-to-be-edited.

.x
$prolog.env$ : visit_chap($prolog-env$).
quit.
.end_chap

==============================================================================

.chap enter-dos

Enter DOS
---------

A copy of the DOS command processor is invoked and
you have access to all the DOS commands.

Type EXIT at the DOS prompt to return to CogentTEXT.

.end_chap

==============================================================================

.chap toggle-gc

Toggle GC
---------

Garbage collection (GC) is the process of recovering and
reusing memory in the CogentTEXT system. This process is
automatic and can be ignored by a user of the system -
when GC is occurring, there may be a brief pause of one or
two seconds (on an AT class machine).

The memory recovered is reused by CogentTEXT - however it
is not available to a DOS command processor you may wish
to invoke to edit a file for example (see Edit File command).

.page

The result is that as you work within CogentTEXT, the memory
available to do work in DOS and then return to CogentTEXT is
gradually diminished. Eventually if you try to run the editor
you will get an "insufficient memory" error.

To ameliorate this the Toggle GC command allows you to swap
between two modes of internal garbage collection:

.page

* Optimized for SPACE - DOS memory will shrink much more
slowly and you will be able to continue to edit files.
However, garbage collection is invoked after each page
is read and there will be slight pause which might be
annoying on a 4MHz PC.


* Optimized for TIME - garbage collection occurs only when
needed so there will be fewer pauses - but it may
eventually become impossible to run the editor or DOS
commands.

TIME optimization is the default.

.page
If you are DEVELOPING a CogentTEXT application we recommend
you run in SPACE optimization mode. If you are just using
a fully developed application we suggest you use TIME optimization.

Choosing Toggle GC option gives you a prompt which
indicates the current optimization, and asks you if you wish
to change it. Your application can also set the optimization
mode as follows. If the goal

abolish(gc_page_flag$).

is proved then TIME optimzation ensues. If the goal

assert(gc_page_flag$)

is proved then SPACE optimization ensues.
.end_chap

==============================================================================

.chap Return

Return
------

This option returns you to the CogentText system from the
command menu.


.end_chap

==============================================================================

.chap files-used
CogentText requires the following files

dct.xpl -- the CogentText Program
dct.exe -- the CogentText runtime
<%prolog.env%> -- the Prolog environment file
cthelp.ctx -- the CogentText help file
cthelp.cti -- and its index
help.txt -- the Prolog predicate help file
help.idx -- and its index

All the other .ctx and .cti files are required only for
the purposes of the demo.

IF YOU ARE MAKING A COPY OF THIS DISK FOR A FRIEND
OR COLLEAGUE, PLEASE COPY ALL THE FILES.

.x
$prolog.env$ : visit_chap($prolog-env$).
quit.
.end_chap

==============================================================================

.chap prolog-env

The file prolog.env is used by the Cogent Prolog system
(which in turn is invoked by the CogentTEXT system).

The file contains a number of defaults and global values which
may be edited by the user to tailor her CogenTEXT system
to the combination of hardware/software being used.

The file contains Prolog source code which may be edited.

.page
% This first block of code checks to see what kind of
% monitor is being used and tries to set up for color

:- set_video(3,_) -> % Can we put it in color mode
assert(wina$(main, 113, 112)), % These numbers are color codes
assert(wina$(alert, 113, 4)), % for window panes, borders and
assert(wina$(highlight, 56)), % text .. experiment !!!
assert(wina$(bold, 116)),
set_video(-1,_)
;
assert(wina$(main, 7, 112)), % No then use monochrome
assert(wina$(alert, 112, 7)),
assert(wina$(highlight, 112)),
assert(wina$(bold, 15)).

.page

% Do not change these
help$(idx, 'help.idx').
help$(txt, 'help.txt').

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% The name of your editor - be certain to include a space as
%% the last element of the string, also make sure it is
%% a character list NOT an atom

editor$("ed ").

% Assign ports

ioport(printer, 'com2'). % Used by printer -- set the second
% argument to the name of your printer port

page_eject. % Comment out if you dont want a page feed
% after each page is printed
.end_chap



  3 Responses to “Category : Miscellaneous Language Source Code
Archive   : COGTEX.ZIP
Filename : CTHELP.CTX

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/