allegro : Help Concept

`Help for this database` 
There are two types of help files: 
•	 RTF document file (extension .RTF) 
•	 ASCII plain text files (no prescribed extension). 
Thera are many more RTF files: the so-called "Flip" technique makes them very versatile. 
All of these files are openly accessible and may be edited or expanded by the user. 
Normally, help texts reside in the HELP subdirectory (see `FLISTENG.TXT`). 
There are help files for various areas and functions: 

	A. `Help for the main functions`
	B. `Help for the sub-windows`
	C. `Editor help`
	D. `Help for the indexes`
	E. `User-supplied RTF help documents`
	F. `Help texts stored in records`

Important: There is a header file  HELPHEAD.RTF . Without it, the ASCII help files cannot be displayed in the display area. The program looks for this file at first on the data path, then on the program directory.This means there may be database-specific versions of it - these then have priority. This file, among other things, supplies the fonts to  use in displaying ASCII files.

Generally, help files may be located in several places:

Location of Help files: Local directory, DbDir, ProgDir\help, ProgDir 
Directories are searched in this order. This means user-specific versions are preferred even over data-specific versions. 

Recommendation: User-specific help files: Local directory of the user 
            Data specific help files: Database path (DbDir) 
            General files for all databases: Program directory (ProgDir) 
            Original File versions: ProgDir\Help 

A. Help for the main functions
These come up automatically, depending on the situation, on pressing  F1 or the [Help] button in dialogs. 
The followinhg file names belong to this group, all files being of type .RTF. A language code may be added to the name. These files are made available with ENG and GER language tags. For example, there is BUTTNGER:RTF and BUTTNENG.RTFMore on  `RTF files` see under E. 

`START`: Help file is displayed before anything else happens 
`GENRL`: Default for database-help (important functions)
`DOKU` : Overview of functions and documentation
`BUTTN`: Help for buttons and other controls
`EXPRT`: Export menu
`COMMD`: for F1 if the focus is in the command line
`FIND` : For the Find button
`FLEX` : FLEX documentation (macro language)
`KONFG`: When the CFG field list is on display in the listbox
`MENU` : Help for the menus
`PRMPT`: when the prompt list is displayed in the listbox
`RECRD`: when the fields of the current record are in the listbox
`RESRV`: when the background store is in the listbox
`RESLT`: Help for result set operations
`SPCHR`: "Special Characters" Help for input  (Alt+m in input field)
`WRITE`: when F1 is pressed in input field  (inputting/editing of fields)

Every  RTF help file can have embedded flips. 
Here's a part of  DOKUENG.RTF to show what flips look like: 

General	`What is allegro`?  - `Elements of the Program` 
 
	`Concepts` - `Background` - `QUICK` 

  (and at the bottom of the file DOKUENG.RTF there are these lines: 

 ?What is allegro=h alleg 
 ?Elements of the Program=h elem 
 ?Concepts=h ac0-0 
 ?Background=h backg 
 ?QUICK=x View help\\quickeng.vw 

Internally, the RTF file looks like this:
\par ?What is allegro=h alleg 
\par ?Elements of the Program=h elem 
\par ?Concepts=h ac0-0 
\par ?Background=h backg 
\par ?QUICK=x View help\\quickeng.vw 

This format is produced automatically when RTF text is saved by WinWord or Wordpad. 
If a flip doesn't react to the mouse click, check the file in an ASCII text editor, preferably the X editor. The sequence "\par " has to be at the beginning of a new line, with no other RTF control commands. 

The words "What is allegro" etc. mostly appear underlined and in a color; but the really important thing is the "grave accent" right and left of the word. The = sign separates the flip text from the command to be executed when the flip is clicked on:   "h alleg" will get the help file alleg.rtf (or allegeng.rtf), to display it. These flip lines are copied, upon reading the rtf file, to the user variables #uYi/#uZi  with character codes i > 128. 
Following the  ?  has to be the exact same character sequence as between the delimiters (grave accents) or enclosed by [...] in the text. 
Following the  =  there may be one of the flip commands or a FLEX command. 
for example:   ...=X backup 
which means: execute the flex  BACKUP.FLX  when the flip is clicked on. 

B. Help for sub-windows
Special case! The help texts for the subwindows have names with no extensions, beginning HE or HA and ending  GER or ENG (German and English versions). Between these, the file name itself always consists of 3 letters. 
If a halp file  HExxxENG cannot be found, the program will look for HExxx, i.e. the name without the language code. 
(HA files are for alcarta, HE for a99) 
When still not found,   HExxxGER.RTF will be searched for. 

The following files are supplied for the subwindows: 
They are all ASCII files with no suffix. The  3letter name begins with a '_'. 
These texts all appear when  F1 is pressed in the subwindow: 

  for both programs: ( a99 will also look for HA if HE is not found)
      .._IX   Index window 
      .._BR   Brief Display 
      .._VW   View list display 
      .._CH   Search command menu 
  only in A99 (HE...) 
      HE_AD   Form Editor 
      HE_GR   Global replacements 

These Texts appear in a grey message window, not in the display field. The message window needs an [OK] before anything else goes on. 

C. Editor help
File names with no extensions, beginning with an H. 
Any existing editing help files for DOS can be re-used (e.g., h20eng or h2eng or h20 or h2). They will come up in the display field (when the cursor is in the write field) or in a message box (when an input form is being used). If no suitable  H file can be found for the field being edited, WRITEENG.RTF is shown instead. 
These texts must be plain ASCII, not RTF. We recommend the `X-Editor` for these files, for Notepad uses ANSI codes. 
If F1 is pressed in the write field or in a form, this is what the program does: it checks which field #ABC is just being worked on, then it looks for HABCeng, then HABC, and if this doesn't exist either,  HAB and then HA. This means one can construct a very detailed help system with a text for every field, or just one text for every field group, or a combination of these.

D. Help for the indexes
For each index there can be a help file HA_InENG for alcarta and a HE_InENG für a99 anlegen (n=1,2,3...). These are ASCII files as well, not RTF. With HE... missing, a99 will use the HA text. There may thus be different help texts for both programs. 
As a minimum, create files HA_I1 ... HA_I0 for your database to have one help file for every index. 

E. User-supplied RTF help documents
The most powerful option. The text you are just reading, HELPENG.RTF, is of this type. 
Type A files are a subset of these. 
The file name is arbitrary. Recommended:  up to  5 letters, then GER or ENG,  extension .RTF. Example:  flexGER.RTF. 
In a monolingual environment, the language code can be omitted. The program always prefers the language specific text, which means it looks for the name plus language code first, like nameENG.RTF, and only after that, name.RTF. (Any help text may thus be created in more than one language.) 
The Microsoft program WordPad may be used to edit RTF files. Important: graphics and tables are not possible. 
But files can be written and edited directly in the display field, and ASCII files as well. 
In this case, save a file using the menu command "File | Save as ...". 

Important case:  dbnENG.RTF  for the  dbn database, the database-specific main help text. 
Location: DbDir 
Example: for demo database see  CATGER.RTF. It appears when pressing the question mark button (lower left) 
 The FLEX command  help !  evokes this file
Recommentation: Create this file for your own databased using a copy of CATGER.RTF and link other help files into it by the flip method. 
Except for graphics and tables, most any feature of WordPad can be applied. Flips are constructed as already described under A. 
Flip texts must be delimited by accent graves, Code 96 (not displayable as such!), i.e., this code has to be placed before and behind the word or string that is supposed to activate the flip command. The exactly same text has to appear on a line beginning ?  (these lines are not displayed). 
Tip: 
help ? : evokes the most recently used help file (This function is also on the "View" menu).
Special funktion: If an  RTF line begins  \par _i  , with any digit i , the display will end at this point if the user has no access right of at least level i  (see access command in the INI-file). This way, help text can be concealed from "lower-class" users. 

If a help file call is to be implemented into a record display, the flip has to be constructed like this: (see example in D-WRTF.APR) 

#xyz p"Information for this record!" e"!" =Y~ 
#xyz p"h name!" e"!" =Z~ 
#t{ 160 t97 t74 "Information for this record" t76 t96 160 } 

The text will appear in blue (text element 74) and underlined (text element 97), 160 is the invisible delimiter). The name must must be given with neither language code nor .RTF, e.g. 
... p"h help!" e"!" ...   for  helpENG.RTF
In this case,  helpGER.RTF will be shown when GER is the current language! 

For delimiters, one may use [ ] or the space-like code 160. (In WinWord, this code is produced by   Shift+Ctrl+spacebar). In the RTF files, there is a  `  instead. The flip text has to be exactly between two such marks. 
From inside a FLEX, help files can be called using the help command. 

Embedding fields and user variables into help files
In any RTF help text there can be embedded variables  %%i  , where   i = 0...9.  If  #uVi  exists at the moment of displaying the text, its content will be inserted for %%i . Record content or other material can thus appear as part of a help text. 
Just as well, field texts %% #nnn or background variables %% #uxy may be directly embedded (with no blank between %% and #), to display the field #nnn or the user variable  #uxy directly as if being part of the text. 
Example: to embed the current title field #20 into the file xyz.rtf ,  but without the title addition (what comes after " : " in #20) :  (see `FLEX-Dokumentation`)
x var #20(e" : ")\ins #utt\help xyz 
and xyz.rtf must contain %%#utt at the the point where the text is supposed to appear. The #uxy variables can also be assigned within the display parameters, to the same effect. 

TIP for comfortable editing of  RTF help files: 
Enter explicitly, in the write field:  h name.rtf   (i.e., the file name with .rtf ) Forget this, and you lose the flips when saving the text! 
The file name.rtf will then be displayed, with a yellow background abd visible markers (grave accents) around the flip texts and the flip command lines visible. Everything can be edited in this mode (use the context menu via right mouse button for convenience), then save the text using "File | Save as" . 
If you enter   h name  without the .rtf, the  flip lines are invisible - as expected for the normal mode. 
For "Save as", the file name extension matters: if it is not .RTF,  just the text will be saved, not the RTF formatting commands. This can be useful if one wants to extract the bare ASCII text of a help file.
Apart from all this, text portions may be exchanged with Winword or Wordpad using cut-and-paste. Attributes will be copied as well, for those programs understand RTF. (With HTML this wouldn't work.) 
Press the right mouse button while the cursor is in the display field. The context menu appears. Press i to switch italics on, for example. The creation of a flip is supported in this way: select the string intended to be clickable, right mouse button and f  - the markers will then be set, the string copied to the end of the file with a preceding  ? and a = behind it. All that's left to do is to write down what FLEX is to be called or what help file brought up. 

Special case: Embedding phrases into help files (to set Strg keys)
If one has a line like 
\par ?zzz=^pabc
in an  RTF help file, then  Strg+p  will be assigned the string abc . If the string abc begins with "x`" or "X`", a FLEX is executed when Strg+p is pressed. Find examples for this at the end of  FLEXGER.RTF. (The characters zzz have no meaning in these commands!)  If a \  occurs as part of   abc , write it down as a single backslash, not a double as usual in RTF . For the lines beginning   \par ?  are not treated as RTF lines when the program reads the text. 

F. Help texts stored in records
As a third way of providing help, a record type may be created that contains help text. This has been done extensively in the database "Theologic Periodical Contents Service" (Tübingen, Dr. Weisweiler). In some 70 such records (each one available in German and English) all commands and options of database use have been described. Suitable parametrization has been added, apart from indexing the help records, to create Flips that bring up other help records,  index sections or particular records. It is just a question of time and imagination to extend this concept ever further. An appropriate parametrization then saves the time that  RTF files tend to consume. (The file HELPHEAD.RTF is not hused for this purpose, but DISPHEAD.RTF instead, like for any other records.) 

?Besen=h besen 
?START=h start 
?GENRL=h genrl 
?DOKU=h doku 
?EXPRT=h exprt 
?MENU=h menu 
?RECRD=h recrd 
?RESRV=h resrv 
?PRMPT=h prmpt 
?COMMD=h commd 
?KONFG=h konfg 
?RESLT=h reslt 
?WRITE=h write 
?SPCHR=h spchr 
?FIND=h find 
?FLEX=h flex 
?BUTTN=h buttn 
?Help for this database=x help ! 
?Help for the sub-windows=x h =B. H 
?Editor help=x h =C. Editor 
?Help for the main functions=x h =A. Help for the main functions 
?Help for the indexes=x h =D. H 
?User-supplied RTF help documents=x h =E. U 
?Help texts stored as records=x h =F. H 
?FLEX-Dokumentation=h flex 
?RTF files=x h =E. B 
?FLISTENG.TXT=h flisteng.txt=Hilfedateien 
?X-Editor=h acd