OS/2 Shareware BBS: 5 Edit/05-Edit.zip/infxdl86.lzh/INFCON.DOC

Text File | 1994-05-10 | 25KB | 478 lines

          INFCONVERT PM - AN OS/2 .INF AND .HLP FILE CONVERTER.

Infconvert PM converts OS/2 .inf & .hlp format files to plain text files. It is
an OS/2 PM program, part written with Watcom's VXREXX, part written in C.
Infconvert PM was written because I wanted to print the help and inf files in
os/2 2.0 and was fed up with the huge quantities of paper required when using
View. Converting inf files to ascii text removes the need for a fresh page for
every heading, allows the use of condensed printing utilities, (see the enclosed
Infprint.cmd and infprint.doc) and produces files which can be read on and
printed from non OS/2 systems.

Three Things You Must Do :-

1 - Remove Any Old Version Of 'Infcon.ini' Before Loading this Newer Version !!
2 - Replace any old version of BOTH Infcon.exe and Infccona.exe with the ones in
    this package, and put them in the same directory.
3 - Ensure Vrobj.dll (ver1.01 or later - not included) is in a directory on the
    Libpath.

Usage :-

Set up infcon.exe as an object on the desktop. Ensure infcon.exe and
infccona.exe are in the same directory, the working directory of the object
settings, or that infccona.exe is in a directory included in the path statement
in config.sys There is an icon, infcon.ico, which can be set to infcon.exe.
The VXREXX dll file VRobj.dll needs to be in a directory which is included in
the 'libpath' statement of config.sys. NB. This file is not included in with this
version of Infconvert PM, and needs to be obtained from a previous release or
elsewhere. Infconvert needs the file Vrobj.dll ver 1.01, and will NOT work
properly with the dll of VXREXX 1.0, but it will work with later patch levels.

          _____________________________________

       Contents :-
                1- The Main Window.
                2 - The List All Window.
                3 - The Found Window.
                4 - Converting Files.
                5 - Searching .Inf and .Hlp Files.
                6 - Opening and Viewing Files.
                7 - The Settings Window.
                8 - A Note About Fonts.
                9 - A Note about Threads.
               10 - Window Positions and Sizes.
               11 - Infconvert's Temporary Directory.
               12 - What Infconvert doesn't do.
               13 - Inf file oddities.
               14 - History and Musings.
               15 - Registration.
               16 - Version & Files.
               17 - Copyright, Disclaimer and Author.
          _____________________________________

1- The Main Window

After an initial info and nag screen, Infconvert PM brings up a window with a
stanard OS/2 type menu. Briefly, the items are as follows:-

Open-
   -Open Inf - Opens an inf file to view topics
   -Open Hlp - Opens a hlp file to view topics
   -List All - Opens another window with a list of all the Inf or hlp files on a
                selected drive.

Convert-
   -Convert Inf - Select an Inf file to convert to text
   -Convert Hlp - Select a Hlp file to convert to text
   -Convert Open - Convert the currently open file to text

Settings-
   -Font Palette - Open an OS/2 Font Palette
   -Settings - Opens a secondary window where Infconverts options can be set.

View- Opens a secondary window with the text related to the currently selected
        topic.

Search-
    -Search Inf - Search an Inf for a given word or part word
    -Search Hlp - Search an hlp for a given word or part word
    -Search Open - Search the currently open file for a given word or part word

Most actions from the main Infconvert window relate to actions performed on a
single file. Actions (ie converting, searching) on groups of files can be
performed from the windows brought up from the "List All" selection under the
"Open" item on the main menu.

2 - The List All Window.

Clicking on "List All" selection under the "Open" item on the main menu open a
second window (in a separate thread) whch displays all the Inf or Hlp files on
a particular drive. A separate window is opened for each drive/file type
combination which the user selects. Groups of files can be selected and
converted or searched for the occurance of a word or part word. A single file
may be opened in Infconvert's main window.
 Select groups of files to convert or search by clicking on the individual file
titles. Alternatively if you check the "Sweep Select" option from the "Viewer"
page in Settings window, you can drag down the list of files to select a group.
Unfortunately this option restricts files chosen to a contiguous group in the
file list. If you wish to change to this option once a file list is open it is
necessary to close the list and reopen it before the new selection method takes
effect. Double clicking on the list deselects all items.


3 -The Found Window.

The results of a succesful search of a file from either of the above two windows
are displayed in a third separately threaded window, with a list of topics where
the text was found at the top, and the text relating to the selected topic
displayed in the bottom half of the window. Up to eight separate found windows
can be opened at any one time. Double clicking on a topic will display the
related text, and menu items allow the user to move to the next occurance of the
text found, or to step forward or back topic by topic.

4 - Converting Files.

   Converting IPF files to plain text is Infconvert PM's main purpose.

 Any choice from under "Convert" brings up, after file selection, a dialog box
where the user can set the range of topics to be converted. The "Start At" and
"End At" selections are initially set so that the whole of the file would be
converted. The text files produced are named after the inf or hlp file, with a
"Txt" extension.  The output files are placed in the directory specified by the
option set in the "Settings" dialog. The line length, margin, and degree of
blank line stripping are also configurable from Infconvert's Settings.
Conversion is usually quite fast:- a one megabyte inf usually takes less
than 30 seconds to convert on the author's 486sx25Mhz 8meg machine, if nothing
else intensive is running.

"Convert List" on the "All Files" window allows a group of files selected to be
and converted in full. The settings used are those of "Settings" in the main
window. It is possible to use "Convert List" from several drive/type windows
and also to open a file in the main window at the same time. However, if you
open a file, and that file is on a list of files being converted, but has not
yet been converted, there may be some problem in opening the file and conversion
may fail.

"Cancel" on the "All Files" window allows you to stop the conversion of the
files being converted from "Convert List". This does not halt conversion of the
file currently being converted, but prevents further files from being converted.


5 - Searching .Inf and .Hlp Files.

Infconvert has the ability to search both single or multiple inf and hlp files,
from the main window menu or the menu of the "List All" window. Clicking
on "Search" in either of these windows will bring up a dialog box where you
can enter up to 255 characters to be searched for. In the main window, only one
file, either the presently opened file or the one chosen from "Search Inf"
or Search Hlp" is searched, and if the desired text is found, a "Found" window
is opened which displays where the text has been found in the file. This window
is similar in type to the "View" window mentioned below, with the addition of
a list of topic headings under which the text searched for was found. From the
"List All" window's menu the procedure is similar, except that there is an
intermediate listing of which files the text was found in and one or more files
can be opened and displayed in the "Found" window. Multiple "Found" windows may
be opened at the same time, to a maximum of eight concurrently open. Any number
of files, from 1 to the entire list of files in the "List All" window may be
searched at one time. Searching can be whole word or part word, and either case
sensitive or not.

 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, Infconvert 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.

The "Found" window list of topics is restricted to 250 entries at one time.
However further topics will be displayed if the user double clicks on the
"More...." entry at the bottom (and top) of incomplete lists.

The default action for the "Found" window is to display the next occurance of
the found text, but the user can also view the previous and next topics by
clicking "Back" or "Forward".

Either all the text displayed, or the text the user has marked can be copied to
the OS/2 clipboard.

6 - Opening and Viewing Files.

 Opening an Inf file displays a list of topics on Infconvert's main window.
You can list the contents of a file from the "All files" window by selecting one
file and clicking on "Open". This works if only one file is selected.

Each item listed is in three parts:
1- A number before the slash(/), which is the topic number in the inf file.
2- A number and perhaps a + sign after the slash, which is an indication of the
nesting of the topic in the inf file. Topics nested at 2 are subtopics of a
previous topic nested as 1 etc. A + sign after a nesting number indicates that
this topic has 'children'.
 3- A topic name. This is sometimes blank. If so its because there is no topic
name in the inf file.

The list of topics is limited in size by the 16 bit nature of parts of PM. Large
lists (bigger than about 1000 items) won't all fit in at once. If the inf file
has a topics list which is too big to display all at once the two small buttons
to the bottom left of the window under the list will show as being active.
Clicking on the button with the down arrow fills the window with the next
part of the list. This can take a second or two.

  The View Window.
You can view an individual topic by either double clicking on any number part
of the topic name or by clicking on the 'View' item on the menu. Both these
actions bring up a view window. This window displays the text from the selected
topic. It can be resized as needed.

The menu at the top has three items.

Copy - brings up two choices.
    Copy All copies the whole topic to OS/2's clipboard.
    Copy Selected copies any marked text to OS/2's clipboard.

Back - View the numerically previous topic.

Forward - View the next topic. If 'Convert with Cross Reference' is set then the
numerically next section may have already been viewed. If so, then these will be
skipped when Forward is clicked.



7 - The Settings Window.

Clicking on the 'Settings' item in the menu brings up a sub menu which has two
options :- Font palette' and 'Settings'.

'Font Palette' opens a default view of OS/2's font palette. Fonts from this can
be dropped onto Infconvert. The font of the 'View' window and that of the main
window list can be saved, and these are used by Infconvert for the other view
windows in the 'Found' windows and the main lists in the 'List All' window.

Clicking on the 'Settings' item in the menu brings up a window where most
of the settings of infconvert can be altered and set. The window has a poor
man's version of an OS/2 notebook. Clicking on any of the 'tabs' brings up a
'page' of related options.

  Output File.
Infconvert PM produces plain text files with the same name as the inf or hlp
file, but with a .txt extension. The top box displays the name of the proposed
output file of the selected file. Infconvert PM can be set to either overwrite
the last output file from the selected inf, or to number output files from an
extension '.tx1' to '.999'. The default is not to overwrite files. Check
'Overwrite Existing Files' to alter this. The line length and margin in the
output file can be directly entered in the two fields provided. The line length
is the total line length including the width of the margin. Line length can be
from 40 to 500, and margin can be from 0 to 40.

 Subsections.
Checking 'Convert Cross Reference' enables infconvert PM to convert some types
of inf file more neatly. If, when viewed with View.exe, an inf file shows a list
down one side with 'select one' or some such above, then this selection allows
infconvert to convert all the selections sequentially in the output file. NB- it
doesn't work with all this type of file - try it and see.
Checking 'Convert Subsections with Parent' will make infconvert convert all
subsections of a parent topic even if only the parent was selected to convert.

 Output Dir.
The output directory an be set to that of the input inf or hlp file or to a
directory entered in the box provided. Infconvert checks to ensure the directory
exists before accepting it.

 Blank Lines.
Select 'None' for no blank lines in the output file.
Select 'At Headings Only' for a blank line before and after each topic name.
Select 'Throughout Text' for all blank lines in the text to be included.
Infconvert always suppresses double blank lines, except where two topic
headings with no associated text appear in a file.

 Input Dirs.
The directory the menu 'Open', 'Convert' and 'Search' find dialog defaults to
can be set from this 'page' for both inf and hlp files.

 Viewer.
The view window provided has word wrap turned off as default, mainly for line
diagrams to display properly. You can turn word wrap on so that, for example,
you can view all of some text with the view window set narrow.
Viewer Line Length can be set to any desired length between 50 and 200
characters. Th default is 82. If tables appear corrupted when viewed, try a
longer line length, use a monospaced font and turn word wrap off. All the VIO
fonts are monspaced as well as System Monospaced.

Checking "Sweep Select In All Files List" enables group selection in the "All
Files" window by holding down the mouse button as the mouse is dragged down the
list. Only contiguous groups of files titles may be selected with this option
enabled.

 Save Settings
None of the entries set are saved to infcon.ini unless Save is pressed. In
addition to the settings listed, this also saves the font used in the view
window and the window lists, and Infconverts temporary directory..

 Save Windows.
The Window positions of Infconvert's main windows are saved when the program
is closed. They may also be saved to the ini file by clicking on "Save Windows"
The windows of "List All" and "Found" are only saved after they have been closed
once. Thus if you want to save these during a session, they must first be
opened, repositioned to the desired location, and closed. The position of the
first "Found" window and "List All" window to be opened are the ones which are
saved and used as a reference for the others of their type.


The Settings window has a minimise button and system menu for closing
hiding the window. Most of the options are set by infconvert with the window
open, but closing (or minimising) the window ensures all are. (The ones that may
not be are those where you can enter a value. Focus must leave the entryfield
window before the entry is accepted. Thus clicking on any button after finishing
entries ensures all options are set.)

8 - A Note About Fonts.

All font can be changed, but only the fonts of the topic and file lists, and
those of the view windows can be saved. One saved font is used for view windows,
and a separate font saved for use in the topic and file lists.
The font in the view window is initially set to system monospaced to allow
proper viewing of line drawings with ascii characters. This font can be changed
from OS/2's font palette, which can be brought up from a selection under
"Settings" item on the menu. If this font is changed, it is saved when the
window is closed, so that when the next view window is opened the font from the
last window closed is used.  This font is subsequently used in the View
windows of the Found window as well as the main window's View window.

The font in the View part and the Topic List part of the first Found window open
at any time, are similarily saved when the winodw is closed, and are set to the
default fonts for other list and view windows.
 I have not been able to allow an application wide font change, principally
because the font of the menu can not be changed with VXRexx's internal commands.

Changes are saved in Infcon.ini only when save is pressed in the options window.

9 - A Note about Threads.

Infconvert PM is multithreaded. All conversions and searches take place in
separate threads, and each 'Found' and 'List All' window is in its own thread.
Infconvert tries hard to ensure that all threads are stopped when Infconvert is
closed.

10 - Window Positions and Sizes.

The size and position of all Infconvert's main, Found and List All winodws are
saved when Infconvert closes. They can also be saved from the setting window
with the Save Windows button. The position of the first List All and Found
Window opened at any one time is the one which is saved

11 - Infconvert's Temporary Directory and INI File.

Infconvert uses its own Ini file to store some of its settings in between
sessions. This is a plain text file, which it usually puts on the same directory
as Infcon.exe. If it can't find or write it there, it looks for it and tries to
write it in the same directory as OS2.INI. If neither of these directories can
be used, Infconvert will not start.

Infconvert tries to set up a temporary directory under the directory it is run
from for its temporary files. If it can't set this up when it opens, it will
prompt the user for a path for this directory. It should clean out this
directory when it closes, but any files it leaves there can safely be deleted
after Infconvert has closed.

12 - What Infconvert 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.

Infconvert 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 infconvert
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.

13 - 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 enteries in other inf files - Infconvert 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 infconvert, although never displayed by view.exe.
Topics with a nesting level of 0 are generally footnotes.

Depending on the degree of blank line stripping used, infconvert 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 one, with files which have acres of text in them and little else, its
nearer 1.5

Occasionally Infconvert PM will close but the Vxrexx console persists. It may be
necessary to reboot to remove this console. Watcom are aware of this problem.


14 - History and Musings

Infconvert was produced using Watcom's VXREXX, and Emx port of the GCC
compiler, and was developed from a previous version written entirely in OS/2's
REXX. All the inf file manipulation is done by the C program and all the user
interaction by the VXREXX program. The C program is a PM program with no output
other than to file, and only command line arguments as input.

Because of the nature of VXREXX, a console from it is always present, though
minimised, and will appear in OS/2's windows list. (The latest version of vxrexx
allows this to be turned off, but for some reason this prevents Infconvert from
closing some of its files properly.) If you are programming with VXRexx, please
note that sometimes I cannot get Infconvert to run when the VXRexx editor is
also running.

 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 little differences it now is similar to my understanding of IPF file
structure. It is, however, written in "C" pseudocode, and is thus difficult for
"non C" people to understand.

 For the record, I deciphered the IPF file stucture independently, duplicating
much of the work which Carl and Marcus had done and, with the exception of
the nesting levels mentioned above, nothing I have included in Infconvert has
been derived from Info1.doc or Info2.doc.

I didn't see either of these files until after my decoding effort was done. Its
not that wouldn't have used the information if I had found it, just that I
didn't find it till it was too late!


15 - Registration.

Infconvert PM is Shareware. You have a licence to use and evaluate
Infconvert PM for a period of sixty days. If you wish to use it past this point,
you are obliged to register your copy. The registration fee is 10 pounds
Sterling and should be sent to me at the address below. Unfortunately at this
stage I am unable to accept credit cards or cheques drawn on non UK banks in
currencies other than sterling. Eurocheques and International money orders are
acceptable, however. Please contact me for bulk order discounts. All
registrations will be acknowledged, and a registration number issued which will
turn off the opening information and nag screen. Registration will be for all
future beta releases and at least the first non beta release.

16 - Version & Files.

       The zip file, Infxdl85.lzh, contains the following files;
                Infcon.exe - the VXRexx 'exe' file.
                Infccona.exe - the C exe file.
                Infcon.doc - this document.
                Infprint.cmd - a small print utility program.
                Infprint.doc - some notes for the above.
                Whats.New - changes over versions.
                ReadMe.1st - get going with this.

The file Vrobj.dll (ver1.01), Watcom's runtime .dll is required to run
Infconvert. I have not included it with this version of Infconvert, as it
appears to be readily available on its own, and was distributed with a previous
version's archive -(Infcnb79.lzh). I can make a version of this archive with the
.dll included available for anyone who needs it.

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

17 - 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)           1st March 1994.
    Internet - [e-mail]
      _____________________________________