
 ================================================================= 
                      Thelp for OS/2
     A text mode OS/2 inf and hlp view, convert and search program.
                A help system for tshell users.
  ================================================================= 
  Contents.
  =========

         1 - Overview.
         2 - History.
         3 - Starting Thelp.
         4 - Command Line arguments.
         5 - The Topics List and Nesting Levels.
         6 - Expanding the Topics List.
         7 - Viewing a Topic
         8 - Converting an inf or hlp File to a Text File.
         9 - Moving Between Windows and Within Windows
        10 - Thelp Commands.
          10.1  Open a New File.
          10.2  Viewing Topics in Inf and Hlp Files
          10.3  Convert an inf or hlp file a text file.
          10.4  Search for a word.
          10.5  List all Topics in a File.
          10.6  Print the Current Topic.
          10.7  Quit.
          10.8  List of Keys.
          10.9  Set Optional Values.
        11 - Thelp with Tshell.
        12 - Thelp with 4OS/2.
        13 - What Thelp doesn't do.
        14 - Thelp's Temporary Directory.
        15 - Inf file oddities.
        16 - Background.
        17 - Registration.
        18 - Version & Files.
        19 - Copyright, Disclaimer and Author.

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

 1- Overview.

  Thelp is an OS/2 text mode IPF file manipulation program.  With Thelp you
  can search, view and convert inf and hlp files to text.  It is a text mode
  program which runs in OS/2 sessions, either windowed on the desktop or 
  fullscreen. The Thelp package includes a replacement file for HELP.CMD which 
  will call Thelp.exe (instead of View.exe) with OS/2's native syntax for 
  calling help. Also included is a file which can replace View.exe so that 
  4OS/2 can use Thelp as its help viewer.  

 2 - History.

  OS/2's Information Presentation Format (IPF) files (.inf and .hlp files) are a
  convienient way to distribute large amount of information in a compact form,
  with hypertext linkage and enbedded graphics. However OS/2's native viewer 
  'View.exe' does not allow conversion of the text in an IPF file to be 
  printed or manipulated as one file. My first IPF conversion programs were
  written to overcome this limitation. 
  Thelp was developed from the conversion program which was written for 
  Infconvert PM. Several people requested that I attempt to produce a text mode
  version of Infconvert.  Thelp is my initial response.  Thelp has been  
  designed with the users of Tshell, the OS/2 character mode shell, in mind.  

 3 - Starting Thelp.

  Thelp is an OS/2 character mode program, and as such will run in an OS/2 
  windowed or fullscreen session. Thelp.exe is the only file which is required. 
  Thelp initially writes a file, Thelp.ini in the directory of Thelp.exe. Thus
  Thelp cannot be run from non writeable media ie a write protected floppy 
  disk. Thelp checks the environment variables TEMP and TMP to find a place
  for its temporary files. If these are not set, or the entries do not specify 
  directories which can be accessed, Thelp creates its own temporary directory 
  (called 'thtemp') under the directory of Thelp.exe.
  Type 'Thelp' at the OS/2 prompt to start Thelp. When the program opens, it
  will display two large windows, with a status line and command entry line at 
  the bottom. The upper of the two windows is where the topics in the inf file 
  are listed. The lower window is where the topics text can be viewed. Initially
  Thelp tries to open the file 'cmdref.inf' if no command line arguments are 
  given. Thelp searches the directories specified in the PATH, BOOKSHELF, and HELP
  environment variables and the current directory in an attempt to find this 
  file. If found, Thelp lists the topics in the upper window.


 4 - Command Line arguments.

  Thelp accepts command line arguments as follows. The first argument is taken
  as the inf file to open. If a second argument is given Thelp searches for the
  argument string in the inf file denoted by the first argument and brings up a
  list of topics where the string was found, or, if it was not found, lists the
  topics in the file. Thus 'Thelp rexx' will open and list the topics in 
  Rexx.inf.  'Thelp rexx mode' will list topics in rexx.inf containing the
  word 'mode'. Thelp accepts multiple concatonated inf files to search from the 
  command line ONLY. Inf files need to be listed with a '+' between them and
  no intervening space. This feature was added for compatibility with
  'View.exe' and the replacement 'Help.cmd' for use in Tshell. However, 
  although it will search the list of files for the search text, it will open
  and list the topics in the FIRST file where the search text was found. It
  will not search subsequent files in the list.

 5 - The Topics List and Nesting Levels.
 
  Initially the topics list consists only of a list containing the top level of
  topics in the inf or hlp file. Each topic entry consists of a number before 
  the forward slash, which denotes the number of the topic in the file, a number
  after the slash, which denotes the nesting level of the topic and possibly a 
  '+' or a '-' after this which denotes that this topic has child topics not 
  initially shown listed under it. This is followed by the text of the topic 
  title. In some files, many topics have no topic title, thus appear in the list
  as a number with no text following. Topics with a nesting level of 0 are 
  generally footnotes, and tend to appear in large numbers in files used both by
  View.exe and OS/2's help system - eg cmdref.inf.

 6 - Expanding the Topics List

  Pressing enter or '+' when focused on the topic window with the highlight bar
  over a topic with a '+' at it will expand the topic list at that point.  
  Similarily '-' contracts the list at topics with a '-' beside them.

 7 - Viewing a Topic

  Press <enter> to view the topic under the highlight bar. Alternately enter 'v'
  at Thelp's command line and specify a topic number to view.

 8 - Converting an inf or hlp File to a Text File.

  You can convert all or part of an inf or hlp to text by entering 'c' at the 
  Thelp command line. Thelp will prompt you "Convert this File? Y/n/r".  'Y' or
  <enter> will result in the whole file being converted to text. 'R' will bring
  up a further prompt for topic number to start conversion at, and topic number
  to end conversion at. Both these numbers are inclusive. The text output file
  is placed in the current directory, unless an output directory has been
  specified via the 'Options' screen. The output file will have the name of the
  inf file, but will have the extension 'txt'. If 'Overwrite existing output
  files' is set to 'No', any further files produced will have their extensions
  consecutively numbered from '.tx1' to '.999'. Certain parts of text within
  inf files are closely related by cross reference within the inf files, and
  usually these are best converted with the cross reference as part of the main
  text. Thus some topics are converted as part of other topics. If this happens
  they are not converted by Thelp again. This can lead to topics apparently
  being missing from converted files. To check to ensure that a topic has been
  converted, set the option 'Inline Cross Reference' to No. Thelp should never
  miss a topic.

 9 - Moving Between Windows and Within Windows

  The tab key or the '/' key toggles between the windows. The window which
  has focus will have highlighted text. The 'w' key or the '*' key toggles the
  windows between split screen (both visible at once) and (nearly) full
  screen.  

  In either window:-
      'Page up' moves the text one srceenful up in the window in focus.
      'Page down' moves the text one screenful down.
      The up arrow key moves the text up one line in the view window and moves
      the highlight bar one line up in the topics list window.
      The down arrow key moves the text down one line in the view window and
      moves the highlight bar one line down in the topics list window.
      'Control-Home' takes you to the top of the current text or list.
      'Control-End' takes you to the bottom of the current text or list.

  When the viewer line length is greater than the screen width :-
      'Home' moves the text so the left margin is visible.
      'End' moves the text so that the right margin is visible.
      The right arrow key moves the visible text one character to the right.
      The left arrow key moves the visible text one character to the left.

  10 - Thelp Commands.

 10.1 - 'F', 'f' - Open a New File.

   The filename without the extension is all that need be entered if the file is
  in a directory specified in the 'HELP', BOOKSHELF' or 'PATH' envionment
  variables, or is in the current diectory. Both '.inf' and '.hlp' extensions
  are searched for. The '.inf' extension is searched for first, so if two files
  of the same name and both '.inf' and '.hlp' extensions exist in the same
  directory, the '.inf' file will always be opened if no extension is specified.

 10.2 - 'V', 'v', <enter> - Viewing Topics in Inf and Hlp Files

  View a topic by pressing <enter> when the highlight bar is over the selected
  topic, or by pressing 'v' and entering the topic number.  The text will
  be displayed in the window below the topic list.  The next topic can be viewed
  by pressing enter again, or by  pressing '+'. The previous topic can be
  viewed by pressing '-'.

 10.3 - 'C', 'c' - Convert an inf or hlp file a text file.

  You can convert all or part of an inf or hlp to text. Thelp will prompt you 
  "Convert this File? Y/n/r".  'Y' or <enter> will result in the whole file
  being converted to text. 'R' will bring up a further prompt for topic number  
  to start conversion at, and topic number to end conversion at. Both these
  numbers are inclusive. 

 10.4 - 'S', 's' - Search for a word.

   Searches can be case sensitve & or insensitive, and whole word or non whole
  word.  Strings of up to 250 characters can be searced for. A list of topics
  where the search text appears is placed in the top window.  
  Words or part words may be searched for, however phrases and symbols made
  up from separate elements will not be found. e.g. a non whole word search for
  "ever" would be sucessful if the file searched had "ever" or "never" or
  "However" in it, but a search for "OS/2" may well fail, because in the word
  list of the inf file "OS/2" is (most probably) stored as "O" & "S" & "/" & "2"
  in separate locations. Nevertheless, Thelp searches the topic names as
  well as the list of words, and the topic names are stored as text strings, so 
  a search for "OS/2" may well not fail, but almost certainly would be
  incomplete. After a successful search :-
  'N' or spacebar brings up the next topic where the search text was found
  'L' or backspace brings up the previous one.

 10.5 - 'T', 't' - List all Topics in a File.

   The topics list produced initially only shows the top level of topics. Those 
  listed with a '+' beside them have subtopics under them. '+' expands the topic
  list when the highlight bar is over a topic with a '+' beside it. Similarily 
  when expanded these topics will have a '-' beside them and the '-' key will 
  contract the list at them.
  When a topic list is produced, any list produced by a previous search is lost.


 10.6 - 'P', 'p' - Print the Current Topic.

  The printer port needs to be set via the 'Options' screen.
  Use upper case and no colon, eg LPT1. Thelp's printing function is limited, 
  specifically in order to work under Tshell, where no print queues are
  available. If you wish to print all of an inf file, convert it to text and 
  print it via an editor, word processor or print utility program.
  The printer type and eject page options are only of concern where the PM is
  not loaded, they have no effect within PM. The text printed is exactly as it 
  is displayed on the screen. Viewer line length may need to be adjusted.

 10.7 - 'Q', 'q', 'F3', <Escape> - Quit.

   Thelp prompts before ending, and should delete its temporary files.
  If a directory named Thtemp is found  under the directory Thelp was run from,
  it and all its contents may be safely  deleted after Thelp has closed.

 10.8 - 'F1' - List of Keys.

  'F1' brings up a window with a brief description of the keystroke actions.

 10.9 - 'O', 'o' - Set Optional Values.

  A variety of options can be set from the options screen. They are listed with 
  the key press to access the setting highlighted in a different colour.
 
 They are :-
        'L' - line length. This is the line length in the text file produced on
  conversion. The range available is 40 to 500. Some inf files, particularily 
  those with data in tabular form or ascii character drawings, need to have line
  length extended over 80 (the default) in order for the formatting of the text
  to be represented correctly.

        'M' - margin. The margin in the output files can be from 0 to 40. The 
  default is 2. The margin in the viewer window is always 1 and can not be 
  altered.

        'V' - viewer line length. The line length in the view window can be 
  extended if required. This is most likely to be necessary with tables and line
  drawings as above.

        'B' - text file blank lines. Thelp always strips out double blank lines
  in text, and can be configured to strip out all blank lines, leave in single
  blank lines, (the default) or leave blank lines only at topic headings. This 
  setting afect only text files produced by convertin

        'K' - viewer blank lines. Thelp always strips out double blank lines in
  text, and can be configured to strip out all blank lines, leave in single
  blank lines (the default), or leave blank lines only at topic headings. This 
  setting only affects the text as it appears in the viewer, not in the text 
  files Thelp produces.


        'C' - toggles on and off case sensitive searches.

        'W' - toggles on and off whole word only searches.

        'O' - overwrite existing files. If Thelp finds another file with the 
  same name it can either be made to overwrite these, or rename the next output 
  file (from the same inf or hlp file) by numbering the extension, according to 
  this setting.

        'D' - directory for output. Thelp will put the text files it produces in
  the current directory unless you specify another.

        'I' - inital file to open. By default, if no file is specified from 
  the command line when Thelp is started cmdref.inf is opened. Specify an 
  alternative if necessary.

        'U' - screen colours. The colours of the main windows, the command entry
  line and the status line can be altered to suit.

        'S' - save to inifile. Although most of Thelps settings take effect 
  immediately they are changed, none are save between sessions unless they are
  saved to Thelp's ini file, Thelp.ini.

        'P' - printer port. Specify the printer port for the 'Print Topic' 
  function. Specify a port in uppercase with no colon, eg LPT1 or COM2 etc.

        'R' - printer type. Specify printer type for correct page eject if PM is
  not loaded.

        'E' - eject page after printing a topic. Neither this nor the previous 
  setting have any effect if PM is loaded, the PM print subsystem does what it 
  thinks is appropriate.

        'N' - inline cross reference. Certain types of cross reference within 
  inf and hlp are usually best converted as part of the main text. Thelp 
  defaults to this behaviour. The types of file most commonly affected bythis 
  behaviour are those where a small list of topics appears in the text with 
  'Select a Topic' beside it. Thelp doesn't convert the same section again in 
  that conversion, and it my appear to be skipping topics. Setting 'inline cross
  reference' to no will result in every topic being converted independantly.

 11 - Thelp with Tshell.

  Thelp was developed for use with Tshell at the request of several Tshell
  users. As the help system is limited within Tshell, (view.exe not being
  available as its a PM program) I have included a replacement for HELP.CMD
  which calls Thelp instead of view.exe, but will allow OS/2, through 
  Helpmsg.exe, to display the sys000? type messages on the screen. These
  messages are located in the *.msg files in X:\OS2\system directory. These are
  not IPF files, but tagged text files. 

  Steps to get a functioning help system in Tshell :-
  a) Rename HELP.CMD in X:\OS2 (where X is the drive letter).
  b) Place the files Helpsrt.exe and HELP001.CMD in X:\OS2.
  c) Place Thelp.exe in a directory on the path, or in X:\OS2.
  d) Rename HELP001.CMD to HELP.CMD.

   Do NOT remove or rename Helpmsg.exe.

  The help system should now work with the same syntax as OS/2 native help 
  system (within the limitations of Thelp).
 
 12 - Thelp with 4OS/2.

  Thelp can be used as a replacement for 'View.exe' when 4OS/2 is used as the 
  shell. 4OS/2 calls view.exe directly and expects the program to be a PM 
  program, thus renaming Thelp to 'view.exe' for 4OS/2 to call it doesn't work.
  The program View001.exe supplied, is a PM program whose sole function is to 
  call Thelp.exe with the arguments given. If View.exe in X:\OS2 is renamed ro 
  removed, and View001.exe is placed in X:\OS2 and renamed View.exe, pressing
  F1 in 4OS/2  will bring up Thelp instead of view.exe.
  I am gratefully indebted to Jonathan de Boyne Pollard for pointing out this 
  limitation, suggesting the solution, and  providing virtually all the code 
  for the View001.exe file.


 13 - What Thelp doesn't do.

  It ignores graphics and text effects such as italics, bold  type, font
  changes, etc. There are no hypertext links in the view window. Thelp checks 
  the top of the inf file for a byte which should be present if the file is an
  inf or hlp file. If this byte isn't present Thelp doesn't continue. There are
  some files on OS/2 systems which have a hlp or inf extension, but are not of
  the IPF type. Thelp won't run from non writeable media (ie a write protected 
  floppy or a cdrom).

 14 - Thelp's Temporary Directory.

  Thelp uses the temporary directory specified by the 'Temp' or 'Tmp' 
  environment variables to write temporary files to. If neither of these 
  variables is set, or Thelp can't change to the directory specified by the 
  variable, Thelp writes a temporary directory called Thtemp as a sudirectory of
  the directory of Thelp.exe. This directory is not deleted when Thelp ends,
  although the files in it are.

 15 - Inf file oddities.

  Some inf files have lots of small sections with topics with no names.
  Some inf files have sections which are just large lists of other topics.
  Some inf files have hard coded carriage returns which prevent the line length
  from being extended - very annoying.
  Some inf files reference entries in other inf files - Thelp can't handle
  these.
  Some topics have no text associated with them - sometimes these appear in 
  large numbers at the end of files.
  Some topics are still shown by Thelp, although never displayed by view.exe.
  Topics with a nesting level of 0 are listed as footnotes.

  Depending on the degree of blank line stripping used, Thelp typically
  produces text files which are 1.25 times the size of their inf originals. With
  inf files with lots of graphics and complicated structures, this ratio is
  nearer 1 to 1, with files which have acres of text in them and little else, 
  its nearer 1.5 to 1
 
  Converting inf and hlp files to text files produces text files of varying
  usefulness. Some inf files use large lists of topic names to cross reference 
  other topics, and some inf files have highly cross linked structures. These
  files often do not produce text files which are easy to read.

 16 - Background.

  Thelp was produced using the Emx port of the GCC compiler, and was developed
  from a previous version written entirely in OS/2's REXX. The conversion
  'engine' is almost identical to that in the latest version of Infconvert PM 
  (beta.85)

  The bulk of my understanding of IPF files comes from studying hex dumps of inf
  files and the text they produced. However I am indebted to Carl Hauser for
  some information from his document Info1.doc, in regard to which bits are set
  for various nesting conditions. Info1.doc has now been upgraded by Marcus
  Groeber, (its now Info2.doc) and is now accurate in in its description of the
  inf file header. Info2.doc will point you in the right direction if you wish 
  to produce an inf viewer. Apart from a few minor differences it now is
  similar to my understanding of IPF file structure. It is, however, written in
  "C" pseudoEnglish.

  I deciphered the IPF file stucture independently, unwittingly duplicating much
  of the work which Carl and Marcus had done. 

 17 - Registration.

  Thelp is Shareware. You have a licence to use and evaluate Thelp for a period
  of sixty days. If you wish to use it past this point, please register your copy.
  Please send the registration fee of 10 pounds Sterling to the address at the 
  bottom fo this file.


 18 - Version & Files.

  This is Thelp beta.18, the second wide public release. The archive
  Thlep018.lzh should include the following files :-

            Thelp.exe - the main program.
            Help001.cmd - a modified version of OS/2's HELP.CMD.
            Helpsrt.exe - an auxillary program for Help001.cmd's use.
            View001.exe - a dummy view.exe for 4OS/2.
            Thelp.doc - This file.
            Readme.now - Essentials & install outline.

  This archive may be freely distributed until a later version is released,
  provided:- 
   1) All the files are distributed together, unaltered and in full.
   2) Thelp may not be bundled with any commercial product.

 19 - Copyright, Disclaimer and Author.

  (c) Copyright Colin Thomson 1994.  All Rights Reserved.
   No warranty of any kind is implied or given.
   No liability is accepted for any consequences of the use of this program.

    My address is :- Colin Thomson, 9, Manor Park, Oakworth, Keighley,
                             West Yorkshire, UK, BD22 7PW.

    Fidonet  - DoNoR/2 2:440/4           6th May 1994.
    Internet - colin@donor2.ukmail.net

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

