You are allowed to use this program for testing and evaluation until a next version is available.
The program, in its current version, may be installed on as many machines as you like.
You are free to distribute the program provided that you include all the files in the original archive without any modification.
You are not allowed to sell the program, but can charge
a reasonable amount to cover the cost of the distribution media.
Under no circumstances will the author be liable for any loss
or damage that may be derived from the use of the program.
HtmlBook is the copyrighted property of Alessandro Felice
Cantatore, Bitonto, Bari, Italy.
The use of the program implies acceptance of the conditions stated above!
Introduction
For various reasons, the html format is probably the most suitable for
writing computer related documentation:
it is simple, supports most national languages and codepages, html browser
are available for all the operating systems,
there are plenty of programs to create html files, etc.
On the other side, html documentation comes divided in many different
files, does not provide an easy method to search text among all those
files, sometimes makes it hard to find a starting
point (quite often the first page is not called index.html) and
does not provide a standard way to browse a document page by page
(i.e. many documents just provide a "contents" page with no
link to go from a page to the previous or the next one).
As a first step to overcome some of the above mentioned disadvantages,
it migth be possible to just group all the files making a document
with ZIP or another archiver. The resulting package, anyway, could not
be immediately viewed with an html viewer as it would be necessary to:
unzip all the files in a termporary path,
open the folder containing the temporary files,
find the first page,
double click on it to start the html viewer.
In order to avoid all those boring steps, and with the plan to later add
text search and other functions, I wrote a small program, HtmlBook, which
packs all the files the documentation consists of into a unique file.
HtmlBook, when in viewing mode, runs in background so that as soon as
a packaged html document (a file with ".htb" extension),
is opened, the proper page is displayed in your favourite html browser.
The purpose of the current implementation is mostly a proof of concept.
In future, according to the users' feedback I'll try to add soem essential
feature like text searching both in the single HtmlBook files and in multiple
files, with the option to associate a set of keywords to each HtmlBook file.
Important note:
The format of the HtmlBook files (the default extension is ".htb")
is subject to change. In order to improve the performance of text searching,
since the next version I may adopt a different format.
Installation
Installing HtmlBook is easy, even if there is no real installer, but
just a couple of REXX scripts to create/destroy program objects.
To install:
create a directory for the program files;
unzip htmlbook01.zip there;
run makeobj.cmd to create:
the HtmlBook folder in your Desktop\Programs\Utilities
folder (or directly on the Desktop if the previous path is not found)
the HtmlBook program object associated with the
".htb" files;
the Creator object to create new HtmlBook files;
the Options object to set the program options;
the Documentation object, that is this file.
download and install ZIP.EXE and UNZIP.EXE in a directory
specified in the "PATH" environment variable.
To uninstall:
open the folder where you unzipped the program files;
run delobj.cmd to destroy all the program objects;
When the program is started without parameters it displays an alphabetically
sorted list of the previously viewed documents.
It is possible:
to click on a item to put the item name in the field below the
list so that one can open it via the Open button (optionally
after having modified it to open a file with a slightly
different name, not yet in the list);
to double click on an item to directly open the file;
to type a file name in the entry field and then click on the
Open button;
to select a file via the standard file dialog by the browse
button (the "..." button);
It is easy to create new HtmlBook documents as the creation window
supports drag and drop.
The window is divided by two group boxes.
The upper group contains:
a list of files to be included in the HtmlBook file,
an entry field where to type the name of a file,
a "+" (add) button to add the entry field content to the list,
a "-" (delete) button to delete the selected item from the list,
a "..." button to select multiple files via the file dialog.
It might be easier to add items to the list by just opening the folder
containing the files and dragging them over the list.
When the whole content of a folder must be added, it is possible to just
drag the folder. In that case the program automatically appends
"\*" to the full folder path name.
Direct conversion of ZIP files containing html documentation (e.g.
OS2eZine or OS/2Voice, etc.). might be supported in a future version.
The group at the bottom contains a field for entering the name of the cover page
and for entering the root directory (relative to the links among the
html pages).
The Index page field supports drag and drop: just drag the
first html file to be opened over this field.
As most html documentation starts with well known file names (index.html,
start.html, contents.html), since the next version I'll probably replace
the field with a dropdown box as the file name might be more easily choosed
from a list.
The Root directory field also supports drag and drop.
It is possible to just drag the folder representing the base common
path of all the files to be included in the HtmlBook.
The buttons at the bottom of the dialog perform the following functions:
Save allows to choose a name and path where to save the
HtmlBook document being generated,
Clear empties the content of the list and of all the fields,
The Options dialog currently allows to define the name and the
parameters of the program used to view the html files and the path
to be used for the temporary files.
On the first execution the fields are filled with the data retrieved
from OS2.INI and from the "TMP" or "TEMP" environment
variable values.
The Program field support drag and drop so it is possible either
to type the full path name of the html viewer or just drag the program
file over the field. The default is taken from OS2.INI.
The Parameters field is used to type additional parameters
needed by the html viewer. A "%s" in the parameter field is
substituted with the name of the cover page (typically index.html) of
the HtmlBook document.
For instance, it might be useful to define a new netscape profile just
for the purpose of reading the HtmlBook documents, customizing it to
display just the navigation buttons. In this case, supposing to call
the new profile "htmlReader", the content of the Parameters
field will be:
-phtmlReader %s
As Temporary files path is possible to use what is defined
as environment variable or to specify any path.
The temporary files are usually deleted even if the program process
is terminated by a different program (e.g. a process killer).
The Use the path specified below field supports drag and
drop, so it is possible to set the temporary path just by dragging
a folder over it.
The development of this application is mainly conditioned by the users
interest and feedback, so if you want me to add new features to this program
just send me an email message.
Possible modifications could include:
simple conversions of html documentation contained in a ZIP file.
a different format to allow quick word/sentence searches within a
single HtmlBook document or within multiple documents (1),
automatic remotion of unneeded spaces and comments from the html files,
optional association of one or multiple keywords to the HtmlBook documents,
port to linux, windows or other platforms,
allow adding notes to existing documents (1),
allow to add bookmarks to existing documents (1),
add a frame with previous/next buttons (1),
allow definition of a contents page to be displayed in a frame
(1).
Notes:
(1)
some of these features might be difficult to implement without
imposing restrictions on the selection of the html viewer.
Registration
At the moment the program is free and no program registration is required to use it.
Future versions might require a small fee for the license of use.
History
v. 0.11
Now the program correctly handles files names containing blank spaces.
The objects creation script has been corrected so now the program can
open HtmlBook files with blank spaces in the name.
