{!title        -- The XHelp index.. -- } 
                    !XHelp 

{!index Introduction}
A Cross Reference Text Display Utility.
{!index Overview}Overview.  

This programme will display an ascii
textfile, just like !Edit. However some
words/sentences are crossreferenced. These
'{annotated}' words show up with a grey back-
ground. DClicking on these words will bring 
you to a place in the text which is associa-
ted with this word, a '{reference}'.

Apart from that there is also an {index}, from
were the 'idexed chapters' can be reached
quickly.

To help you keep track of were you were,
i.e. where you left the 'main text' to read a
{reference}, one further aid has been build
into the programme: {Bookmarkers}.

The work just as regular bookmarkers. You
can {insert them at a certain point} and {flip}
to them quickly at another time. You can
insert them manualy, however when you leave
the text at a certain point to jump to
either the {index} or a {referenced word}, a
{bookmarker} is left automaticly. This
enables you to return to your text after
having read a reference. The bookmarkers are
accesible in a {LastIn-FirstOut} stacked
order, unlike their real-live counterparts.

The programme supports {interactive help}.

{!index Getting started}
Getting started.

You are now reading the !Help file of the
application !XHelp. When you DClick on the
!Xhelp application in the filer window a
demo file will be shown.

You can do that NOW, whilst leaving this
text on the screen. Also start Acorns !Help
application, you can find it on application
disc one.

Right. A window, titled Helper, should have
appeard in the middle of the screen. A
{toolbox} has appeared to the left. It
contains four icons.

The top two icons are for the bookmarker 
handling, the bottom two allow you to switch
betwee text and index. Curently the text
should be displayed.

Now click on the bottom icon in the toolbox,
the index icon. (You can verify this by
looking in the {'Interactive Help' window.})

The contents of the window should change
now, a header saying 'The INDEX, compiled'
appears, followed by four items preceeded by
a grey box, numbered 1..4.

You can DClick on each of these items. Let's
try the second item, introduction.

DClick on the grey area. The window will
change and the introductotory text will
apear. 

Right. Read It ?

Now suppose that you want to return to the
place you left just before you read the
index. Clicking on the second bookmarker
icon in the toolbox will get you there.
Again, studying the 'Interactive help'
explanations should get you going.

Once you have returned there, you will see
that several 'difficult' words have been
referenced, i.e. 'they have a grey
background'. These words are annotated...

DClicking on these words will bring you to a
short reference. Once you have read the
reference you can return to the place you've
left to read that reference by using the
'return to bookmarker' icon, the second icon
from the top. 

Right thats all there is to this application
apart from the thing that you can leave a
bookmarker by clicking on it. A black
triangle will show, defining the exact spot
to were you will return when you click the
'return to bookmark' icon.
{<LastIn-FirstOut}
The bookmarks are stored on a LiFo basis, a
computer boffins term for a certain stacking
method. It works on a LastIn, FirstOut
basis, or if you prefer FirtsIn, LastOut.
This means that Clicking on the 'return to
bookmark' icon will bring you both to the
topmost marker, ie the last marker inserted
AND will remove that marker.

Apart from these there are a few more actions,
these are mainle preformed with the ADJUST 
button, refer to the appedix for this.

Now we will deal with the main features..

{!index The Manual}

From the users point of view...

 There are three important concepts in this
 programme:

 o The annotation/reference structure
 o The bookmarers and 
 o The index

 We will deal with these three in dept, 
 DClick on these items to get the information
 concerned.

From the 'writers' point of view.

 Together with the users-list of concepts, the
 following list will give a complete overview.
 o main text
 o token structure
 o coding -annotations
          -references
          -index items
                 title
          -colours
 o configuring
 o limits -speed
          -memory

 Apart from these, there is also a reference
 section, which is most easly accesed through
 the index system.














----------------------------------------------
-------    U S E R S   G U I D E      --------
----------------------------------------------

{!index USERs Guide}
{!index      - Annotation/references structure}
{<annotated}{<reference}{<referenced word}
Annotation/Reference structure

 Normaly a reference is a bit of text, often
 numbered, to which the numbered annotation 
 points. 

 An example could be this fragment,

   "... however most Acorn Computers were
    assembled in the early 1960's on a ..."

 Matching the '' annotation at the bottom of
 the page you would find something like..

{<'Acorn'}  ) Acorn, a small Camebridebased compagny
     building unconventional but very special
     homecomputers, among which the elevated
     BBC Micro Computer.
    
 The '' is called the annotation, Acorn is the
 annotated word. The explanation preceeded by the
 ) is the reference.

 In this computer versioun one would expect the
 word {'Acorn'} to have a grey background. 
 DClicking on it would lead to the ) reference.

 Just try....


















==============================================
{!index      - On Bookmarkers} {<Bookmarkers}{<bookmarker}

On bookmarkers...

To help you keep track of were you were,
for example where you left the {main text} 
to read a {reference}, one further aid has
been build into the programme: 

         Bookmarkers.

The work just as regular bookmarkers. You
can {insert them at a certain point} and {flip}
to them quickly at another time. You can
insert them manualy, however when you leave
the text at a certain point to jump to
either the {index} or a {referenced word}, a
{bookmarker} is left automaticly. This
enables you to return to your text after
having read a reference. The bookmarkers are
accesible in a {LastIn-FirstOut} stacked
order, unlike their real-live counterparts.

























==============================================
{!index      - On indexes}{<index} 

On the index 

 Every {display-file} can have an index. The
 index can displayed by clicking on the
 index icon. It is not compulsory
 to have an index. If there is no index
 defined then a text telling you so will be
 displayed...

 The index falls into three parts, the
 title, the items, and the grey numbered
 reference boxes.

 Each item is preceeded by a grey numbered
 box. These serve as 'clicking pads'. DClicing
 on them will bring you to that item. You
 can always leave the index by clicking on
 the 'main text' icon. You will be brought
 to the place you left when you clicked 
 the 'index icon' in the first place.

 I leave it to the interested reader to
 discover the obvious title.









{!index Writers Guide...}

----------------------------------------------
-------  W R I T E R S   G U I D E    --------
----------------------------------------------

{<main text}
{!index    - Main text}Main text

  The main thing the writer has to do is to
  write the 'main text', i.e. the text which
  is going to be displayed in this window.

  The main text is actually the only data-
  structure. It can be edited with any ascii
  editor, like !Edit, and you do not need
  a fancy programme to specify the index or
  the references.

  This maintext is in stored as a file, the
             {'display-file'}{<'display file'}

  All the special features are coded into
  the ascii text. But first, the character-
  istics of the main text...

  
{!index        o filename}Filename 
   
   Both filename and file path are completely
   free. No assumptions are made. The file
   displayed is in the OSvar:
 
   <Xhelp$Xtext>

   And you can set it to any path by commands
   like:

   Set Xhelp$Xtext <obey$dir>.ReadMe 
   Set Xhelp$Xtext IDEFS::Harddisc4.$.Examp
   
   These paths do not depent on the appli-
   cation dir of !Xhelp. The var Xhelp$Xtext
   is currently defined in the !Run file of
   Xhelp, feel free to change things.



{!index        o filetype} Filetype 

  Although no checking is done, use a &FFF or
  text type for the time being. Expect the
  programme to be adapted in the near future
  to autorun certain filetypes. 

{!index        o tokenstructure} Token structure

  Commands always have this format :

  '{/}token parameters{\}

   A space between token and paramter is 
   compulsory. Currently the following
   tokens are defined :

    < annotation           , one param
     reference            , one param
    ! subcommand:           
       title               , one param
       index               , one param
       col                 , 16 params
    / trick to obtain a {/}  , no params
    \ trick to obtain a {\}  , no params

the '{/}' trick

    As you cannot use the chars {\} and {/}
    freely a little trick allows you to
    code them:

    In asccifile       Displayed
    {/}/{\}                {/}
    {/}\{\}                {\}
  
{!index      o Auto run}Auto run

    No filetype has been chosen yet, so this
    function is switched off.






















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

{!index    - The index} 
The index
 Every {display-file} can have an index. The
 index can displayed by clicking on the
 index icon. It is not compulsory
 to have an index. A suiteble text, see
 message {US2}, will be displayed if no
 index is available.

 The index falls into three parts, the
 title, the items, and the grey numbered
 reference boxes.
            
{!index        o title}* The title. 

 The index can have title defined in your 
 text. If you do not define a title in
 your display-file, a preset title will
 be used, see message {US1}.

 The definition of the title has the form
 
 {/}!title just as title{\}  

 The 'title' token is case-sensitive, and
 the space just after !title is ignored.

 The whole {/}..{\} definition MUST be on the 
 first line of your file. the {/}..{\} must be
 the first character.

 Hint {/}!index {\} will result in no title
 at all.

{!index        o items}* The items

  Items are the beast which make up the
  index. There can be as many as you 
  like. However there is a small catch,
  as the index is compiled on each (re)
  draw of the index, long indexes on long
  files do take their time.

  An index token is placed somewere in
  the text, in the line it refers to. It
  has the structure :

  {/}!index Introduction{\}

  Again the word 'index' is case-sensitive,
  and the space is ignored. It can be placed
  anywere in the text. It is not displayed.

{!index        o grey boxes}* The grey reference boxes

  Each item is prefixed by a grey box with
  a black number in it. Double clicking with
  select in these boxes will result in a
  jump to that index point, the place
  where the matching '!index ..' reference
  is found.














==============================================
{!index    - Bookmarkers}Bookmarkers

 A bookmarker serves as a temporarily
 reminder of a place in the text.

 Up to 64 bookmarkers can be defined in
 a stackwise fashion. 

 Either the programme will place bookmarks
 or the user.

 The programme places bookmarKs if you
 switch to the index, and will jump and
 remove that bookmarker if you return
 to the main text.

 It will also place a bookmark if you jump
 to a reference or index-rerenced spot.

 In addition you can also place the book-
 markers with the '{leave bookmark}' icon
 in the toolbox.

 You can only access the topmost marker, also
 referred to as the latest or newest book-
 marker. This is done by the '{goto bookmark}'
 function.
















==============================================
{!index    - Annotations}Annotations

 Any word can have an annotation.

 This annotation 'points' to a certain reference.
 An annotated word(s) looks like

 {An Annotation}
 
 and is ASCII coded like
 
 {/}An Annotation{\}

 DClicking on these annotation will bring you to
 the first associated reference. On DClick
 a search is made, starting on the first line
 of the main text, for a reference with EXACTLY
 the same word(s) as in the annotation. DClick
 on {An Annotation} to see the reference.























==============================================
{!index    - References}References 

 Normaly a reference is a bit of text, often
 numbered, to which the numbered annotation 
 points. 

 An example could be about The Acorn Computer
 build in the early 1960 at Culham. At the
 bottom of the page you would find something
 like..

 ) Acorn, a small Camebridebased compagny
    building unconventional but very special
    homecomputers, among which the elevated
    BBC Micro Computer.
    
 The XHelp programme uses references in a slightly
 stricter sense. A reference is a place in the 
 text to which any annotation might point.

 A reference can be hidden or visible. 

 The structure is..

 Hidden  :  {/}<string{\}
 Visible :  {/}<string{\} looks like {string}

 The string must be spelled exactly as the 
 matching annotation. Below you can see the
 matching reference to {An Annotation}

 {An Annotation} coded as {/}An Annotation{\}

 On DClick on '{An Annotation}' to page to
 this reference.













============================================== 
{!index -   Techo stuff...}
{!index      o Memory consumption}Programme memory consumtion

 Before the text file is loaded the required
 memory is claimed from the free wimp-pool.

 This will assure minimal memory consumption,
 althoug people with little memory will be
 better of, on a four meg machine, the small-
 est chunck is 32k.

 As the index is compiled during the display
 of that index no memory is used up for a
 index building.

 The same goes for references and annotations
 which are checked/found on the spot, no 
 elaborate tables are set up and stored.

 However a small table is build while loading
 the text file, storing the addresses where
 each sucsessive line starts in memory. This
 enables the programme to redraw the screen
 quicly. The length of this table is calculated
 from the file lenght. This is a guessed process
 and a verY short avarage line-lenght can upset
 the guessing algorithm. the error 'Too many 
 lines.., message {ER5} will be given. Very
 long lines however will result in a memory 
 waste of up to 4 percent on long files.


{!index      o Speed}Speed 

 No speed optimalization has been done yet.

 I am planning to hand-code things into
 arm-assembler. Hold on for now.

 You will find that speed does matter,
 especially during index display. To
 save memory all interpreting actions
 are done on the spot.

Colours customizing
{!index      o Colours customizing}

 Has been build in, but not tested yet, hang
 on for this.

 Anyway, the first line should read..

 {/}!col xxxxxxxxxx{\}

 With xxxxxxxxx numbers from 0..F or an X.

 Parameter 1 text background, not used.
           2      foreground.
           3 reference  bg
           4            gg
           5 Annotation bg
           6            fg
           7 Index      bg
           8            fg
           9 Marker     last
          10            others

 An X indicates that the defaults have to be
 used. Example, if the first line looks like
 
 {/}!title the demo index{\}{/}!col xxxxC6xxxx{\}

 you can be sure that the colours of the 
 annotated words are dark-grey on a slightly
 off white, yellowish, colour.


{!index Reference Section}

{!index - Features}
Features
 o {Asciifile} display in scrollable window
 o Length only limited by {memory}
 o Full {reference} posibilities
 o Easy {bookmarker} actions
 o Offers easy access for the beginner, but
   remains quick enough to the expert
 o {Online index compilation}
 o Easy writing of {sourcetext}, just with !Edit
 o Small apllication <32Kram
 o {Installs} in any directory, especially on
   a hardisc.
 o interactive help
 o adaptable programe dialogues/messages
 o Can be auto-run on certain filetypes
 o {Multi langual}

{<interactive help}.
{!index - Interactive Help}Interactive Help
 
 This programme supports level-1 interactive
 help as asked for by the Acorn !Help appli-
 cation on the welcome disk (version 1.13).

 You can load this !Help programme. 
{<'Interactive Help' window.}
 It will open a window titled 'interactive help' 
 which will display any information avalable
 about the object the pointer is curently
 pointing at.

 This !Xhelp application will make a lot
 of information available. All it functions
 are covered. 

 Expert can change the information displayed.
 The information messages are coded {H01..H11}
 in the message file.








{<toolbox}
{!index - The toolbox}Toolbox

 The toolbox is situated left of the main
 window. It has no title bar and it is
 attached firmly to the main window. It
 has 4 icons on a grey background. Each
 icon has a few special functions. The
 easiest way to obtain information is to
 use the interactive help application.

 The four icons function are 'Leave book-
 marker','goto bookmarker','show maintext', 
 and 'show index'. The respond to SELECT 
 and ADJUST in a different way. Use SELECT
 only if you are new to the programme.
{<insert them at a certain point}{<leave bookmark}
{!index   o Leave bookmarker}*'Leave bookmarker'

 The icon is intended to look like a book-
 marker pointing right to the text. It is
 the first icon from the top in the toolbox.

 Clicking SELECT will leave a bookmarker to
 which you can return with the function 
 'goto bookmarker'. A black triangle will
 mark the spot.

 ADJUST will bring you to the last marker
 and is functionally the same as 'goto
 bookmarker.

 The bookmarkers are stored stackwise. Only
 the newest marker is accesible. Up to 64
 markers can be placed.
{<flip}{<goto bookmark}
{!index   o Goto bookmarker}*'Goto bookmarker'

 This is the second icon from the top, it
 also looks bookmarker, vertical, pointing
 downwards with two black triangles in it,
 both pointing back, left.
 
 Clicking on it with SELECT will bring
 you to the newest bookmarker. This book-
 marker will be removed when you arrive
 to its spot. If there are no bookmarkers
 a beep will be heard.

 However using ADJUST will not remove the
 latest bookmarker, you can use it to return
 time after time to the same spot.

{!index   o Display main text}*'Display main text'

 This is the third icon from the top in the
 toolbox. It looks like a 'text'

 Clicking SELECT will force the main window
 to display the main text. If the main
 text is already there a beeb will be heard.

 Clicking ADJUST will toggle the contents of
 the main window. It will switch to the Index
 if the main text was on display or the other
 way round.

 The programme will 'bookmark' the main text
 before displaying the index, so on return
 you are brought back to the exact spot you
 had left.
 
{!index   o Display index}*'Display Index'

 This is the bottom icon in the toolbox. It
 should look like an 'numbered index'

 Clicking SELECT will force the main window
 to display the index. If the index is 
 already there a beeb will be heard.

 Clicking ADJUST will toggle the contents of
 the main window. It will switch to the Index
 if the main text was on display or the other
 way round. 

 The programme will 'bookmark' the main text
 before displaying the index, so on return
 you are brought back to the exact spot you
 had left.



{!index - Internationalizing}
Internationalizing

The Message file in the application directory
can be changed. The lines contain a 3 char
code, a double colon and a string terminated
by either a chr(13) or a chr(10).

This string can be freely translated/changed. 
However you are oblidged (to rename and) leave
the original message file in the directory if
you pass it along. The USx messages are the
ones a user most likely would like to change.

A short abstract is given below :

ERx: codes, errors after which the
     application will quit...

{<ER1}     ER1:Cannot find the file to be shown
{<ER7}     ER7:Cannot find my sprite file 
{<ER2}     ER2:Cannot find my template file.
{<ER3}     ER3:Unexpected redraw request
{<ER5}     ER5:Too many lines..
{<ER6}     ER6:Missing { or } at line :
{<ER8}     ER8:index_reference not found
{<ER9}     ER9:Cannotretrun to bookmarker 
{<ER4}     ER4:File has lenght ZERO !

Two messages for general use..

{<WAR}     WAR:Pleasenote...: 
{<AP1}     AP1:Displaying 'Xref'ed files 

The main user configurable messages

{<US1}     US1:Default index header
{<US2}     US2:Default 'no index' text
{<US3}     US3:Default warning if a annotaion/
         reference set is not found!

And finally H01 .. H11:{H01..H11}
     are the interactive help messages.

















{!index - The window and mouse actions}
The Window and mouse actions

 The main window responds to the following
 actions.

 DClick with select on a annotated word/index
 item.

   Which will jump to the reference/indexed
   place in the main text.

 DClick with adjust on plain text.

   Which doubles the return to last marker
   action.

 Pressing Menu.

   This will bring up a menu with the
   items info and quit along with a plain
   print options.
















{!index - The application}
The application

 The application consists of 10 files, which
 are stored in the !XHelp dir.

 Acorn specific names/functions :
 
  !Run           type OBEY     ;to start-up
  !Help               OBEY     ;provide help
  !Sprites            SPRITE   ;filer-picture

 The running kernel :

  !RunImage           BASIC    ;the worker

 This helpfile :

  !HelpText           TEXT     ;this text

 And some defintions files :
  Messages            TEXT     ;user editable 
                                messages,
  Sprites             SPRITE   ;toolbox icons
  Templates           TEMPLATE ;window defs
  menus               DATA     ;menu defs

 And finally there is the textfile to
 be displayed, often named 

 Textfile             TEXT

 It uses two system vars..

 Xhelp$Dir   ; full path to the appl. dir
 Xhelp$Xtext ; the text to be displayed












{!index - Printing}
Printing

 Printing is possible. Use menu on the main
 window and use the middle item. The text
 file is brutally copied to the Printer:
 path, including coded references etc.

 There are no subtilities in this, the whole
 text is send, with a chr(13) separating the
 lines.

 Not very usefull though...

