home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / thelp021.lzh / Thelp.doc < prev    next >
Text File  |  1994-06-15  |  24KB  |  462 lines
  1.  
  2.  ================================================================= 
  3.                       Thelp for OS/2
  4.      A text mode OS/2 inf and hlp view, convert and search program.
  5.                 A help system for tshell users.
  6.   ================================================================= 
  7.   Contents.
  8.   =========
  9.  
  10.          1 - Overview.
  11.          2 - History.
  12.          3 - Starting Thelp.
  13.          4 - Command Line arguments.
  14.          5 - The Topics List and Nesting Levels.
  15.          6 - Expanding the Topics List.
  16.          7 - Viewing a Topic
  17.          8 - Converting an inf or hlp File to a Text File.
  18.          9 - Moving Between Windows and Within Windows
  19.         10 - Thelp Commands.
  20.           10.1  Open a New File.
  21.           10.2  Viewing Topics in Inf and Hlp Files
  22.           10.3  Convert an inf or hlp file a text file.
  23.           10.4  Search for a word.
  24.           10.5  List all Topics in a File.
  25.           10.6  Print the Current Topic.
  26.           10.7  Quit.
  27.           10.8  List of Keys.
  28.           10.9  Set Optional Values.
  29.         11 - Thelp with Tshell.
  30.         12 - Thelp with 4OS/2.
  31.         13 - What Thelp doesn't do.
  32.         14 - Thelp's Temporary Directory.
  33.         15 - Inf file oddities.
  34.         16 - Background.
  35.         17 - Registration.
  36.         18 - Version & Files.
  37.         19 - Copyright, Disclaimer and Author.
  38.  
  39.  =================================================================
  40.  
  41.  1- Overview.
  42.  
  43.   Thelp is an OS/2 text mode IPF file manipulation program.  With Thelp you
  44.   can search, view and convert inf and hlp files to text.  It is a text mode
  45.   program which runs in OS/2 sessions, either windowed on the desktop or 
  46.   fullscreen. The Thelp package includes a replacement file for HELP.CMD which 
  47.   will call Thelp.exe (instead of View.exe) with OS/2's native syntax for 
  48.   calling help. Also included is a file which can replace View.exe so that 
  49.   4OS/2 can use Thelp as its help viewer.  
  50.  
  51.  2 - History.
  52.  
  53.   OS/2's Information Presentation Format (IPF) files (.inf and .hlp files) are a
  54.   convienient way to distribute large amount of information in a compact form,
  55.   with hypertext linkage and enbedded graphics. However OS/2's native viewer 
  56.   'View.exe' does not allow conversion of the text in an IPF file to be 
  57.   printed or manipulated as one file. My first IPF conversion programs were
  58.   written to overcome this limitation. 
  59.   Thelp was developed from the conversion program which was written for 
  60.   Infconvert PM. Several people requested that I attempt to produce a text mode
  61.   version of Infconvert.  Thelp is my initial response.  Thelp has been  
  62.   designed with the users of Tshell, the OS/2 character mode shell, in mind.  
  63.  
  64.  3 - Starting Thelp.
  65.  
  66.   Thelp is an OS/2 character mode program, and as such will run in an OS/2 
  67.   windowed or fullscreen session. The files Thelp.exe, emx.dll, and emxlibc.dll
  68.   are all required. Emx.dll and Emxlibc.dll need to be placed in a directory 
  69.   specified in the LIBPATH statement ( eg OS2\APPS\DLL ). Thelp initially writes
  70.   a file, Thelp.ini in the directory of Thelp.exe. Thus Thelp cannot be run
  71.   from non writeable media ie a write protected floppy  disk. Thelp checks the
  72.   environment variables TEMP and TMP  to find a place  for its temporary files.
  73.   If these are not set, or the entries do not specify directories which can
  74.   be accessed, Thelp creates its own temporary directory  (called 'thtemp')
  75.   under the directory of Thelp.exe. Type 'Thelp' at the OS/2 prompt to start
  76.   Thelp. When the program opens, it will display two large windows, with a
  77.   status line and command entry line at  the bottom. The upper of the two
  78.   windows is where the topics in the inf file  are listed. The lower window is
  79.   where the topics text can be viewed. Initially Thelp tries to open the file
  80.   'cmdref.inf' if no command line arguments are  given. Thelp searches the
  81.   directories specified in the PATH, BOOKSHELF, and HELP environment variables
  82.   and the current directory in an attempt to find this  file. If found, Thelp
  83.   lists the topics in the upper window.
  84.  
  85.  
  86.  4 - Command Line arguments.
  87.  
  88.   Thelp accepts command line arguments as follows. The first argument is taken
  89.   as the inf file to open. If a second argument is given Thelp searches for the
  90.   argument string in the inf file denoted by the first argument and brings up a
  91.   list of topics where the string was found, or, if it was not found, lists the
  92.   topics in the file. Thus 'Thelp rexx' will open and list the topics in 
  93.   Rexx.inf.  'Thelp rexx mode' will list topics in rexx.inf containing the
  94.   word 'mode'. Thelp accepts multiple concatonated inf files to search from the 
  95.   command line ONLY. Inf files need to be listed with a '+' between them and
  96.   no intervening space. This feature was added for compatibility with
  97.   'View.exe' and the replacement 'Help.cmd' for use in Tshell. However, 
  98.   although it will search the list of files for the search text, it will open
  99.   and list the topics in the FIRST file where the search text was found. It
  100.   will not search subsequent files in the list.
  101.  
  102.  5 - The Topics List and Nesting Levels.
  103.  
  104.   Initially the topics list consists only of a list containing the top level of
  105.   topics in the inf or hlp file. Each topic entry consists of a number before 
  106.   the forward slash, which denotes the number of the topic in the file, a number
  107.   after the slash, which denotes the nesting level of the topic and possibly a 
  108.   '+' or a '-' after this which denotes that this topic has child topics not 
  109.   initially shown listed under it. This is followed by the text of the topic 
  110.   title. In some files, many topics have no topic title, thus appear in the list
  111.   as a number with no text following. Topics with a nesting level of 0 are 
  112.   generally footnotes, and tend to appear in large numbers in files used both by
  113.   View.exe and OS/2's help system - eg cmdref.inf.
  114.  
  115.  6 - Expanding the Topics List
  116.  
  117.   Pressing enter or '+' when focused on the topic window with the highlight bar
  118.   over a topic with a '+' at it will expand the topic list at that point.  
  119.   Similarily '-' contracts the list at topics with a '-' beside them.
  120.  
  121.  7 - Viewing a Topic
  122.  
  123.   Press <enter> to view the topic under the highlight bar. Alternately enter 'v'
  124.   at Thelp's command line and specify a topic number to view.
  125.  
  126.  8 - Converting an inf or hlp File to a Text File.
  127.  
  128.   You can convert all or part of an inf or hlp to text by entering 'c' at the 
  129.   Thelp command line. Thelp will prompt you "Convert this File? Y/n/r".  'Y' or
  130.   <enter> will result in the whole file being converted to text. 'R' will bring
  131.   up a further prompt for topic number to start conversion at, and topic number
  132.   to end conversion at. Both these numbers are inclusive. The text output file
  133.   is placed in the current directory, unless an output directory has been
  134.   specified via the 'Options' screen. The output file will have the name of the
  135.   inf file, but will have the extension 'txt'. If 'Overwrite existing output
  136.   files' is set to 'No', any further files produced will have their extensions
  137.   consecutively numbered from '.tx1' to '.999'. Certain parts of text within
  138.   inf files are closely related by cross reference within the inf files, and
  139.   usually these are best converted with the cross reference as part of the main
  140.   text. Thus some topics are converted as part of other topics. If this happens
  141.   they are not converted by Thelp again. This can lead to topics apparently
  142.   being missing from converted files. To check to ensure that a topic has been
  143.   converted, set the option 'Inline Cross Reference' to No. Thelp should never
  144.   miss a topic.
  145.  
  146.  9 - Moving Between Windows and Within Windows
  147.  
  148.   The tab key or the '/' key toggles between the windows. The window which
  149.   has focus will have highlighted text. The 'w' key or the '*' key toggles the
  150.   windows between split screen (both visible at once) and (nearly) full
  151.   screen.  
  152.  
  153.   In either window:-
  154.       'Page up' moves the text one srceenful up in the window in focus.
  155.       'Page down' moves the text one screenful down.
  156.       The up arrow key moves the text up one line in the view window and moves
  157.       the highlight bar one line up in the topics list window.
  158.       The down arrow key moves the text down one line in the view window and
  159.       moves the highlight bar one line down in the topics list window.
  160.       'Control-Home' takes you to the top of the current text or list.
  161.       'Control-End' takes you to the bottom of the current text or list.
  162.  
  163.   When the viewer line length is greater than the screen width :-
  164.       'Home' moves the text so the left margin is visible.
  165.       'End' moves the text so that the right margin is visible.
  166.       The right arrow key moves the visible text one character to the right.
  167.       The left arrow key moves the visible text one character to the left.
  168.  
  169.   10 - Thelp Commands.
  170.  
  171.  10.1 - 'F', 'f' - Open a New File.
  172.  
  173.    The filename without the extension is all that need be entered if the file is
  174.   in a directory specified in the 'HELP', BOOKSHELF' or 'PATH' envionment
  175.   variables, or is in the current diectory. Both '.inf' and '.hlp' extensions
  176.   are searched for. The '.inf' extension is searched for first, so if two files
  177.   of the same name and both '.inf' and '.hlp' extensions exist in the same
  178.   directory, the '.inf' file will always be opened if no extension is specified.
  179.  
  180.  10.2 - 'V', 'v', <enter> - Viewing Topics in Inf and Hlp Files
  181.  
  182.   View a topic by pressing <enter> when the highlight bar is over the selected
  183.   topic, or by pressing 'v' and entering the topic number.  The text will
  184.   be displayed in the window below the topic list.  The next topic can be viewed
  185.   by pressing enter again, or by  pressing '+'. The previous topic can be
  186.   viewed by pressing '-'.
  187.  
  188.  10.3 - 'C', 'c' - Convert an inf or hlp file a text file.
  189.  
  190.   You can convert all or part of an inf or hlp to text. Thelp will prompt you 
  191.   "Convert this File? Y/n/r".  'Y' or <enter> will result in the whole file
  192.   being converted to text. 'R' will bring up a further prompt for topic number  
  193.   to start conversion at, and topic number to end conversion at. Both these
  194.   numbers are inclusive. 
  195.  
  196.  10.4 - 'S', 's' - Search for a word.
  197.  
  198.    Searches can be case sensitve & or insensitive, and whole word or non whole
  199.   word.  Strings of up to 250 characters can be searced for. A list of topics
  200.   where the search text appears is placed in the top window.  
  201.   Words or part words may be searched for, however phrases and symbols made
  202.   up from separate elements will not be found. e.g. a non whole word search for
  203.   "ever" would be sucessful if the file searched had "ever" or "never" or
  204.   "However" in it, but a search for "OS/2" may well fail, because in the word
  205.   list of the inf file "OS/2" is (most probably) stored as "O" & "S" & "/" & "2"
  206.   in separate locations. Nevertheless, Thelp searches the topic names as
  207.   well as the list of words, and the topic names are stored as text strings, so 
  208.   a search for "OS/2" may well not fail, but almost certainly would be
  209.   incomplete. After a successful search :-
  210.   'N' or spacebar brings up the next topic where the search text was found
  211.   'L' or backspace brings up the previous one.
  212.   Text found after a search will be highlighted in the view window. This feature
  213.   follows the settings for case and whole word in searches. If line length is
  214.   extended, and only part of the word is visible in the window, it will not be 
  215.   highlighted.
  216.  
  217.  10.5 - 'T', 't' - List all Topics in a File.
  218.  
  219.    The topics list produced initially only shows the top level of topics. Those 
  220.   listed with a '+' beside them have subtopics under them. '+' expands the topic
  221.   list when the highlight bar is over a topic with a '+' beside it. Similarily 
  222.   when expanded these topics will have a '-' beside them and the '-' key will 
  223.   contract the list at them.
  224.   When a topic list is produced, any list produced by a previous search is lost.
  225.  
  226.  
  227.  10.6 - 'P', 'p' - Print the Current Topic.
  228.  
  229.   The printer port needs to be set via the 'Options' screen.
  230.   Use upper case and no colon, eg LPT1. Thelp's printing function is limited, 
  231.   specifically in order to work under Tshell, where no print queues are
  232.   available. If you wish to print all of an inf file, convert it to text and 
  233.   print it via an editor, word processor or print utility program.
  234.   The printer type and eject page options are only of concern where the PM is
  235.   not loaded, they have no effect within PM. The text printed is exactly as it 
  236.   is displayed on the screen. Viewer line length may need to be adjusted.
  237.  
  238.  10.7 - 'Q', 'q', 'F3', <Escape> - Quit.
  239.  
  240.    Thelp prompts before ending, and should delete its temporary files.
  241.   If a directory named Thtemp is found  under the directory Thelp was run from,
  242.   it and all its contents may be safely  deleted after Thelp has closed.
  243.  
  244.  10.8 - 'F1' - List of Keys.
  245.  
  246.   'F1' brings up a window with a brief description of the keystroke actions.
  247.  
  248.  10.9 - 'O', 'o' - Set Optional Values.
  249.  
  250.   A variety of options can be set from the options screen. They are listed with 
  251.   the key press to access the setting highlighted in a different colour.
  252.  
  253.  They are :-
  254.         'L' - line length. This is the line length in the text file produced on
  255.   conversion. The range available is 40 to 500. Some inf files, particularily 
  256.   those with data in tabular form or ascii character drawings, need to have line
  257.   length extended over 80 (the default) in order for the formatting of the text
  258.   to be represented correctly.
  259.  
  260.         'M' - margin. The margin in the output files can be from 0 to 40. The 
  261.   default is 2. The margin in the viewer window is always 1 and can not be 
  262.   altered.
  263.  
  264.         'V' - viewer line length. The line length in the view window can be 
  265.   extended if required. This is most likely to be necessary with tables and line
  266.   drawings as above.
  267.  
  268.         'B' - text file blank lines. Thelp always strips out double blank lines
  269.   in text, and can be configured to strip out all blank lines, leave in single
  270.   blank lines, (the default) or leave blank lines only at topic headings. This 
  271.   setting afect only text files produced by convertin
  272.  
  273.         'K' - viewer blank lines. Thelp always strips out double blank lines in
  274.   text, and can be configured to strip out all blank lines, leave in single
  275.   blank lines (the default), or leave blank lines only at topic headings. This 
  276.   setting only affects the text as it appears in the viewer, not in the text 
  277.   files Thelp produces.
  278.  
  279.  
  280.         'C' - toggles on and off case sensitive searches.
  281.  
  282.         'W' - toggles on and off whole word only searches.
  283.  
  284.         'O' - overwrite existing files. If Thelp finds another file with the 
  285.   same name it can either be made to overwrite these, or rename the next output 
  286.   file (from the same inf or hlp file) by numbering the extension, according to 
  287.   this setting.
  288.  
  289.         'D' - directory for output. Thelp will put the text files it produces in
  290.   the current directory unless you specify another.
  291.  
  292.         'I' - inital file to open. By default, if no file is specified from 
  293.   the command line when Thelp is started cmdref.inf is opened. Specify an 
  294.   alternative if necessary.
  295.  
  296.         'U' - screen colours. The colours of the main windows, the command entry
  297.   line, the status line, the options window, and the help screen, can be altered
  298.   to suit.
  299.  
  300.         'S' - save to inifile. Although most of Thelps settings take effect 
  301.   immediately they are changed, none are saved  between sessions unless they are
  302.   saved to Thelp's ini file, Thelp.ini.
  303.  
  304.         'P' - printer port. Specify the printer port for the 'Print Topic' 
  305.   function. Specify a port in uppercase with no colon, eg LPT1 or COM2 etc.
  306.  
  307.         'R' - printer type. Specify printer type for correct page eject if PM is
  308.   not loaded.
  309.  
  310.         'E' - eject page after printing a topic. Neither this nor the previous 
  311.   setting have any effect if PM is loaded, the PM print subsystem does what it 
  312.   thinks is appropriate.
  313.  
  314.         'N' - inline cross reference. Certain types of cross reference within 
  315.   inf and hlp are usually best converted as part of the main text. Thelp 
  316.   defaults to this behaviour. The types of file most commonly affected bythis 
  317.   behaviour are those where a small list of topics appears in the text with 
  318.   'Select a Topic' beside it. Thelp doesn't convert the same section again in 
  319.   that conversion, and it my appear to be skipping topics. Setting 'inline cross
  320.   reference' to no will result in every topic being converted independantly.
  321.  
  322.  11 - Thelp with Tshell.
  323.  
  324.   Thelp was developed for use with Tshell at the request of several Tshell
  325.   users. As the help system is limited within Tshell, (view.exe not being
  326.   available as its a PM program) I have included a replacement for HELP.CMD
  327.   which calls Thelp instead of view.exe, but will allow OS/2, through 
  328.   Helpmsg.exe, to display the sys000? type messages on the screen. These
  329.   messages are located in the *.msg files in X:\OS2\system directory. These are
  330.   not IPF files, but tagged text files. 
  331.  
  332.   Steps to get a functioning help system in Tshell :-
  333.   a) Rename HELP.CMD in X:\OS2 (where X is the drive letter).
  334.   b) Place the files Helpsrt.exe and HELP001.CMD in X:\OS2.
  335.   c) Place Thelp.exe in a directory on the path, or in X:\OS2.
  336.   d) Rename HELP001.CMD to HELP.CMD.
  337.  
  338.    Do NOT remove or rename Helpmsg.exe.
  339.  
  340.   The help system should now work with the same syntax as OS/2 native help 
  341.   system (within the limitations of Thelp).
  342.  
  343.  12 - Thelp with 4OS/2.
  344.  
  345.   Thelp can be used as a replacement for 'View.exe' when 4OS/2 is used as the 
  346.   shell. 4OS/2 calls view.exe directly and expects the program to be a PM 
  347.   program, thus renaming Thelp to 'view.exe' for 4OS/2 to call it doesn't work.
  348.   The program View005.exe supplied, is a PM program whose sole function is to
  349.   call Thelp.exe with the arguments given. If View.exe in X:\OS2 is renamed or
  350.   removed, and View005.exe is placed in X:\OS2 and renamed View.exe, pressing
  351.   F1 in 4OS/2  will bring up Thelp instead of view.exe. Thelp must be on the 
  352.   PATH for view005.exe to be able to find it.
  353.   I am gratefully indebted to Jonathan de Boyne Pollard for pointing out this 
  354.   limitation, suggesting the solution, and  providing virtually all the code 
  355.   for the View005.exe file.
  356.  
  357.  
  358.  13 - What Thelp doesn't do.
  359.  
  360.   It ignores graphics and text effects such as italics, bold  type, font
  361.   changes, etc. There are no hypertext links in the view window. Thelp checks 
  362.   the top of the inf file for a byte which should be present if the file is an
  363.   inf or hlp file. If this byte isn't present Thelp doesn't continue. There are
  364.   some files on OS/2 systems which have a hlp or inf extension, but are not of
  365.   the IPF type. Thelp won't run from non writeable media (ie a write protected 
  366.   floppy or a cdrom).
  367.  
  368.  14 - Thelp's Temporary Directory.
  369.  
  370.   Thelp uses the temporary directory specified by the 'Temp' or 'Tmp' 
  371.   environment variables to write temporary files to. If neither of these 
  372.   variables is set, or Thelp can't change to the directory specified by the 
  373.   variable, Thelp writes a temporary directory called Thtemp as a sudirectory of
  374.   the directory of Thelp.exe. This directory is not deleted when Thelp ends,
  375.   although the files in it are.
  376.  
  377.  15 - Inf file oddities.
  378.  
  379.   Some inf files have lots of small sections with topics with no names.
  380.   Some inf files have sections which are just large lists of other topics.
  381.   Some inf files have hard coded carriage returns which prevent the line length
  382.   from being extended - very annoying.
  383.   Some inf files reference entries in other inf files - Thelp can't handle
  384.   these.
  385.   Some topics have no text associated with them - sometimes these appear in 
  386.   large numbers at the end of files.
  387.   Some topics are still shown by Thelp, although never displayed by view.exe.
  388.   Topics with a nesting level of 0 are listed as footnotes.
  389.  
  390.   Depending on the degree of blank line stripping used, Thelp typically
  391.   produces text files which are 1.25 times the size of their inf originals. With
  392.   inf files with lots of graphics and complicated structures, this ratio is
  393.   nearer 1 to 1, with files which have acres of text in them and little else, 
  394.   its nearer 1.5 to 1
  395.  
  396.   Converting inf and hlp files to text files produces text files of varying
  397.   usefulness. Some inf files use large lists of topic names to cross reference 
  398.   other topics, and some inf files have highly cross linked structures. These
  399.   files often do not produce text files which are easy to read.
  400.  
  401.  16 - Background.
  402.  
  403.   Thelp was produced using the Emx port of the GCC compiler, and was developed
  404.   from a previous version written entirely in OS/2's REXX. The conversion
  405.   'engine' is almost identical to that in the latest version of Infconvert PM 
  406.   (beta.85)
  407.  
  408.   The bulk of my understanding of IPF files comes from studying hex dumps of inf
  409.   files and the text they produced. However I am indebted to Carl Hauser for
  410.   some information from his document Inf01.doc, in regard to which bits are set
  411.   for various nesting conditions. Inf01.doc has now been upgraded by Marcus
  412.   Groeber, (its now Inf02.doc) and is now accurate in in its description of the
  413.   inf file header. Inf02.doc will point you in the right direction if you wish
  414.   to produce an inf viewer. Apart from a few minor differences it now is
  415.   similar to my understanding of IPF file structure. It is, however, written in
  416.   "C" pseudoEnglish.
  417.  
  418.   I deciphered the IPF file stucture independently, unwittingly duplicating much
  419.   of the work which Carl and Marcus had done. 
  420.  
  421.  17 - Registration.
  422.  
  423.   Thelp is Shareware. You have a licence to use and evaluate Thelp for a period
  424.   of sixty days. If you wish to use it past this point, please register your copy.
  425.   Please send the registration fee of 10 pounds Sterling to the address at the 
  426.   bottom fo this file.
  427.  
  428.  
  429.  18 - Version & Files.
  430.  
  431.   This is Thelp beta.21, the third wide public release. The archive
  432.   Thlep021.lzh should include the following files :-
  433.  
  434.             Thelp.exe - the main program.
  435.             Emx.dll & Emxlibc.dll - the compiler's runtime libraries.
  436.             Help001.cmd - a modified version of OS/2's HELP.CMD.
  437.             Helpsrt.exe - an auxillary program for Help001.cmd's use.
  438.             View005.exe - a dummy view.exe for 4OS/2.
  439.             Thelp.doc - This file.
  440.             Whats.new - Changes from beta 018.
  441.             Readme.now - Essentials & install outline.
  442.  
  443.   This archive may be freely distributed until a later version is released,
  444.   provided:- 
  445.    1) All the files are distributed together, unaltered and in full.
  446.    2) Thelp may not be bundled with any commercial product.
  447.  
  448.  19 - Copyright, Disclaimer and Author.
  449.  
  450.    Emx.dll and Emxlibc.dll are Copyright (c) 1990-1993 Eberhard Mattes.
  451.    Thelp is Copyright (c) Colin Thomson 1994.  All Rights Reserved.
  452.    No warranty of any kind is implied or given.
  453.    No liability is accepted for any consequences of the use of this program.
  454.  
  455.     My address is :- Colin Thomson, 9, Manor Park, Oakworth, Keighley,
  456.                              West Yorkshire, UK, BD22 7PW.
  457.  
  458.   Fidonet DoNoR/2 2:440/4     15th June 1994.    colin@donor2.ukmail.net
  459.  
  460. =============================================================================
  461.  
  462.