QuickHTM
                                  ========

                        Convert a text file to HTML

Converts a QL text file to HTML using the <pre></pre> construct. Ie
formatting should look the same as the text file. Characters are
substituted for UTF-8 as far as possible and "illegal" HTML characters are
replaced (eg < is converted to &lt; etc.)

A header and footer can be added to the output. These can contain
user-defined and environmental information, formatting, and styles.


Requirements
============

This utility was created with QPC2 and SMSQmulator in mind, but could
possibly run on any QL system. The compiled version needs Qlib_run or
equivalent.


Quick Start
===========

To execute this program, the following syntax applies:

        PRINT FEW("<path>QuickHTM_obj" [; <command line>])

To test it right now:

Say you have unzipped QuickHTMxx.zip to ram1_. Get the name of this file
into the Stuffer Buffer, eg select its name in Qpac2 Files, or re-save
this file in QD, then type

        PRINT FEW("ram1_QuickHTM_obj")

In a perfect world you should hear a short squeak and see zero printed in
your SBASIC console window. Assuming for a moment that the world is
perfect, have a look in ram1_ again: a new file, ram1_QuickHTM.htm should
now be there! (If not, read on!)

Copy that file, and the file called ram1_plain.css (Note: unzip may have
converted this file to plain_css! Make sure you copy it to your host as
plain.css!) to a suitable place on your host file system - Windows, Linux,
or Mac. Open up your host's file manager and click on QuickHTM.htm. You
should now see this file in your browser. Press CTRL+ a couple of times
if you need to zoom in (most browsers support this). Then you should be
able to see why this program is a good idea..?


How To
======

However, this is not necessarily the best way to operate it.

The best way to use this program is to:

1. Add it to a Hotkey. Thus, somewhere in your boot file add the line:

              ERT HOT_LOAD1(<key>, "<path>"QuickHTM_obj")

   where <key> is some suitable key of your choice. Pressing ALT + <key>
   would then execute the program and convert the file which name is
   in your Stuffer Buffer into HTML into your configured destination.

   You could have different keys for different command line options (eg
   using different auxiliary files and/or destinations) if you choose to.

    ERT HOT_LOAD1(<another key>, "<path>"QuickHTM_obj"; "/C other_cfg")

2. The program can also be added to FileInfo2, and to most program
   launchers. Once you try it, it shouldnt be too hard to see how!


Input/Output
============

The program requires an input file, an output destination, and various
auxiliary files for its proper operation.

All the files you need to get started are included.

The following section describes, in soul-destroying detail, all you need
to know about specifying input and output files. You probably dont need
to know all that now; its here when you need it! So skip to the next
section: Configuration!


The input file can be specified in different ways:

1. If there is no command line, the input file name is taken from the
   Stuffer Buffer (eg by saving a file in QD, or by clicking a file name
   in Qpac2 Files, or ditto in FSEL, etc)

2. If there is a command line but it doesnt contain a source file, ie
   there is no /S<filename>, then, again, the source file name is taken
   from the Stuffer Buffer

3. If there is something on the command line, but there is no key command
   (no /Something) then the whole command line is taken to be the source
   file name.

4. Specify the source file name on the command line with /S<filename>


The output destination can also be specified in various ways.

1. If a destination directory has been set in the configuration file (See
   configuration, below) then, if no override has been specified (see next)
   then the configured destination will be used, and the current file's name
   will be used as the destination file's name, with the source file's
   extention (if any) removed and .htm appended.

2. If no destination directory has been configured (or it is configured as
   <blank>, ie nothing) and no destination or target supplied on the command
   line, then the source directory is used as the destination directory, and
   the destination file name will be formed as described above.

3. Whether a destination directory has been configured or not, if a
   destination directory is specified on the command line with /D<directory>,
   that will be used as the destination.

4. If a target file name has been specified on the command line (/T<file
   name> - ie a full path, file name, and extension) then that takes
   precedence and that directory, file name, and extension will be used.


Regarding the auxiliary files:

1. Unless a different header file is specified on the command line with
   /H<header file name>, or in the configuration file, the default header
   file, <home>header_txt, will be used. If the designated file does not
   exist an error will result.

2. Unless a different footer file is specified on the command line with
   /F<footer file name>, or in the configuration file, the default footer
   file, <home>footer_txt, will be used. If the designated file does not
   exist an error will result.

3. The translation table <home>SMSQ2UTF8_txt must always be present. The
   only way to change it is to exchange the file with another of the same
   name and similar construction. If the file cant be found an error will
   result.


Configuration
=============

There is a simple configuration file, <home>QuickHTM_cfg that can be used
to set some basic defaults. Each line is preceded by the same key as the
corresponding command line key. However, contrary to the command line, the
order and number of entries is fixed.

The file could look like this: (Comments, including and after the |-bar,
are for information only and must not be included in the actual file!)

/D dos3_html_         | Destination directory. Must be valid, or left blank
/H header_txt         | HTML header and footer files. If no path given
/F footer_txt         | the home directory is assumed.
/P                    | Optional user-defined parameter (see HTML below)

A blank setting is just the key with nothing following
Quotes must not be used here!
Different configuration files can be used by supplying a link to them on
the command line (see below).


HTML
----

To begin with, just use the header and footer files supplied. When you
need to know more, theres a chance you may find it in this section.

If this is your first reading, I suggest for your peace of mind that
you just skip to the next bit: Command Line!

At its simplest, the only thing you need in an HTML header for local files
are the opening tag <HTML> and in the footer, the closing tag </HTML>.
Two sample HTML files are provided, header_txt and footer_txt. You could
use these, or devise your own. (The footer contains some javascript.
Clearly, that wont work if you have switched javascript off in your
browser. It is only for demonstration, so you can just remove it.)

Since the sample header and footer include some CSS style formatting,
a simple CSS file, plain.css, is included. Copy this file, or something
similar of your own design, to your designated destination folders in the
host's file system.

In the header and footer files you can use a few variables. These
variables are bracketed in "hats" like this ^variable^. As the header
and footer files are written to the destination, these variables are
substituted for their values:

                ^title^ = name of file
                ^date^  = date, eg 2021 Dec 14
                ^time^  = time, eg 14:33
                ^param^ = user defined parameter (max 42 characters!)


Command Line
============

These are the various possible command line parameters.

                Parameter = /<key>[<space>]<data>       [<optional>]

Parameters that contain spaces needs to be quoted: /P "my parameter".
Parameters can be given in any order.
All parameters are optional (depending on circumstances. See Input/Output,
above.)

                /S - full Source path amd filename

                /C - optional alternative Configuration file

                /T - optional full Target path and filename

                     OR

                /D - optional target Directory
                     /D ignored if /T is also specified

                /H - Header filename

                /F - Footer filename

                /P - Parameter - user supplied value (default *)

/C can be used to pass a different configuration file to the program.

/C /H and /F file names can be given in full, or just the name - in which
case the path will be the current home directory.


Program notes
=============

This program was stitched together from different parts that were
developed over the years for different purposes. Some of those routines
were never meant to be seen by others! They may be ugly, inefficient and
clumsy, but they have worked for me over the years and so I dont feel
like "fixing" them all in one go, otherwise I could never move forward.

The S*BASIC program can be EXecuted directly in SMSQ/E, provided the
toolkit commands are pre-loaded. The source codes for the toolkit can be
gathered from Knoware.no.


Program Status
==============

V0.05, pjw, 2021 Dec 14, based on tx2htm (used for all text files on Knoware)

Conditions of use and DISCLAIMER as per Knoware.no