Revision Level

1.0

WARNING: Please note that a new HTML based hypertext help and explain system with an equivalent embedded browser is in preparation; it should become available with the next major upgrade release.

HyperText Format

The data/text to be displayed should be provided in plain ASCII text files, that can be easily generated and updated with any common editor such as vi. Hypertext files are located in the $PROJECT/data/explain directory, pictures and icons in $PROJECT/data/icons or $PROJECT/data/images. Please note that these locations can be redefined in the application CONFIG, which can also define multiple locations in the respective search pathes.

The following special commands are available to structure hypertext display including raster images, and provide linkages through text keys and icons:

\font{fontname} ... to set a specific font; fontname can be
         ns - standard (normal) font, small size,
         nm - standard (normal) font, medium size,
         nb - standard (normal) font, big size,
         bs - bold font, small size,
         bm - bold font, medium size,
         bb - bold font, big size,
\color{color number or name} ... to change color,
\vspace{distance} ... vertical spacing; "distance"
        can be given in pixels (99p) or lines (99l),
\hspace{distance} ... horizontal spacing; "distance"
        can be given in pixels (99p) or in characters (99c),
\hline{length} ... horizontal line; "length"
        can be given in pixels (99p) or in characters (99c),
\begin{verbatim} ... begin of verbatim, maximal font character width used
\begin{verbatim}{c} ... begin of verbatim, the width of character 'c' used
\end{verbatim } ... end of verbatim
\%...comment...'\n'  ... \% until '\n'(including) is ignored
\_{text} ... subscript
\^{text} ... superscript
\- ... possible hyphenation in words, like hyper\-explain
\picture{icon file} ... draws icon file in directory
      'datapath' in current position, (either xwd or sun raster)
      '\newline' plus ' ' or '\n' ... new line
      '\bigpara' plus ' ' or '\n' ... new paragraph below
          the last used y-position (e.g. below icons too)
      '\leftmargin{margin} ... sets left margin; "margin"
          can be given in pixels (99p) or in characters (99c),
          or original margin can be set (0)

      1 space or return following the ending '}' of commands
      is ignored; leading spaces of the line or after the
      pictured are ignored.

      'return' ... the paragraph is made if next character
          is 'return', else it is used as space,
      \\ ... single backslash '\' is drawn,
      \x ... '\' in another combination - if HTA_FUNCTION
          was specified in mask for xCreateHTStruct,
          specified function is called with arguments:
          function(aca, win, &text, &width, &length,
              option, test, ht->fdata); arguments text,
              width, length and option are the same as
              in 'xHyperTextSegment' function, other were
              specified here. It should return 1 if successful,
              2 if specified command was found in function
              but something was wrong or 0 if command was
              not found
\input{input file} ... input file is included
\key{keyword text}{explain file} ... to make a window
      with 'keyword text' pickable with the left mouse
      button; if the left button is pressed a new
      hyper explain tool is created from data in 'explain file',
\icon{icon file}{explain file} ... to make a pickable window
      from 'icon file' which should be either an xwd or a sun
      raster file.  If the left button is pressed on this window,
      a new hyper explain tool is created from data in 'explain file'.
      'explain file' in '\key' and '\icon' and 'info->filename'
      can be a sequence of filenames separated by comma; for example
      "file1,file2,file3".
\window{[icon=icon_file[,[ ]]][func=f_name[,[ ]]][w=width[,[ ]]]
       [h=height[,[ ]]][wname=window_name[,[ ]]][data=a _data[,[ ]]]
       [keyw=key_text[,[ ]]][exfile=explain_file[,[ ]]]
       [link=link_name]} to make a window
       icon_file ... creates the icon window,
       width, height ... dimensions of created window,
       window_name ... symbolic name of the window,
       a_data ... copied to data item of event data; maximum 300 characters,
       key_text ... displayed text; maximum 128 characters,
       explain_file ... data for another hyper explain level,
       link_name ... windows with the same link_name are highlighted together,
       f_name ... symbolic name for function which is called after an event
       on the window; function(aca, event, data), data is a pointer to a
       he_key_event_data_t structure or to a he_icon_event_data_t structure
       depending if keyw was used or not, if f_name is _explain, xHyperExplain
       is called , it uses a_data as a set of keywords with the same meaning
       as below: title, tx, ty, twidth, theight, width, h eight, aname
       for example data="title='Population, China', tx=10,ty=20" if tx or
       ty value starts with 'a', position is absolute in aca->win