OS/2 Professional/OS2PRO194.ISO/os2/wps/file/infxdl/infcon.doc

Text File | 1993-10-24 | 15.8 KB | 271 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.
/*----------------------------------------------------------------------*/

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. The included file is the VRobj.dll
of VXREXX 1.01a, Infconvert PM will NOT work properly with the dll of VXREXX
1.0.

After an initial info and nag screen, Infconvert PM brings up a window with a
menu across the top. Click on 'File', and then on 'Inf' or 'Hlp' to bring up a
file selection window. Select an inf or hlp file from this standard OS/2 file
selection. When the file has been selected, a few seconds will pass before the
file's list of Topics will appear in the main Infconvert window.
Alternatively all inf or hlp files on any drive can be listed by choosing 'List
All' from the 'File' menu. A "Drive and Type" window lets you select the drive,
inf or hlp. A selection from this window opens another window with a list of
all of the chosen file types on the chosen drive.  Select groups of files to
convert by clicking on the individual file titles. Alternatively if you check
the "Sweep Select" option from the "Viewer" page in Options 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.

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 right top of the window under the menu will show as being active.
Clicking on the button with the down arrow fills the window with the next part
of the list. This does take a second or two.

 Converting Files.
The 'Convert' item on the menu drops down a secondary list of 'Convert All' and
'Convert Range'. Clicking on Convert All starts the converison of the inf or hlp
file according to the settings of the 'Options' window. Conversion is in a
separate thread, so the manipulation of the main window is unaffected by it.
When conversion is complete, a message box appears on the screen, giving the
output file name and the time for conversion if more than 10 seconds. Clicking
on 'Convert Range' starts conversion of the range of topics set by the 'Start
At' and 'End At' entryfields. These default to the first and last topics and can
be altered in two ways:-
1 - The start and end topic numbers can be typed into the entryfields.
2-  Click on 'Start At' or 'End At' button and then double click on the number
of the topic in the main window. Note if you double click on the number in the
main window first, you will view the topic and not set 'Start At' or 'End At'.
Otherwise 'Convert Range' is the same as 'Convert All'.
"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 "Options" 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.

  The View Window.
You can view an individual topic by either double clicking on the number part of
the topic listing, or by swipe selecting on the number part of the topic listing
and clicking on the 'View' item on the menu. Both these actions bring up a view
window and display the selected topic. 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.
The font in the view window is 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. Changes are saved in Infconvert.ini when save is pressed in the
options window.

 The Options Window.
Cilcking on the 'Options' 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 'File' find dialog defaults to can be set from this
'page' for both inf and hlp files.
 Viewer.
Infconvert produces temporary files with an extension '.HDN' when producing its
topic lists. If this file is alredy present in the output directory from a
previous opening of the inf or hlp file, the listing of the topics is
considerably faster. Check 'Delete Heading Files After Use' to delete these
files on a new inf or hlp file selection.
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.
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
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.

The options window now 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. )


/*---------------------------------------------------------------*/

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.

Inf file oddities
Some inf files have lots of small sections with topics with no names.
Some inf files have section 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.

/*---------------------------------------------------------------*/

Infconvert was produced using Watcom's VXREXX and Borland's BC++ for OS/2,
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 actually a PM program with no output
other than to file, and only command line arguments as input. I intend to change
this from an exe to a dll at some point.
 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.

/*--------------------------------------------------------------*/

I intend to develop Infconvert as my understanding of the internal nature of IPF
files increases. I have only recently acquired an IPF compiler (along with BC++)
and haven't had any great chance to study the documentation or the structure of
output created from known input. The text files which Infconvert produces
are likely to be improved upon a little -but I think they're pretty good already
- and there is likely to be improvements in linking at viewing in future
versions of Infconvert.
 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 will point you in the right direction if
you wish to produce an inf viewer but is substantially inconsistent with my
interpretation of inf file structure. When I have time I will 'update' Info1.doc
with my interpretation.
Please let me know of any problems you have or improvements you would like to
see.
/*--------------------------------------------------------------*/

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.

/*--------------------------------------------------------------*/
Version & Files.  The zip file, Infcnb79.zip, contains the following files;
                Infcon.exe - the VXRexx 'exe' file.
                Infccona.exe - the C exe file.
                Infcon.doc - this document.
                VROBJ.DLL - Watcom's runtime dll for Infcon.exe.
                Infprint.cmd - a small print utility program.
                Infprint.doc - some notes for the above.
                Whats.New - changes over versions.

      The zip file, Infxdl79.zip, contains the above files without VRobj.dll.

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.

NB The file VROBJ.DLL must not be distributed other than with the rest of this
package.

(c) Copyright Colin Thomson 1993.  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 @ STRANGE***daze*** 2:250/313           24rd October 1993.
/*----------------------------------------------------------------------*/