sb2htm v0.98

sb2htm converts tokenised SuperBASIC source files into syntax coloured, navigable, HTML. This manual describes how to do it and what options are available.
  1. Quick start
  2. Installation*
  3. Usage
  4. Command Line
  5. Configuration files
    1. sb2htm_cfg
    2. Header and Footer Files
    3. Character Set File
    4. Core Keyword Files*
  6. Substitution
  7. Batch File
  8. SBhtm - convert _bas files to HTML directly*
  1. Troubleshooting
  2. Config line syntax

* Major changes since previous release (see History_txt)

0. Quick start

From within a QL environment unzip the files to a suitable folder on your hard disk (or on a floppy disk). Unzip will create a sub-directory called s2h. It will also create further sub-directories under that.

Tip: To quickly test the program: Unzip to ram1_, ensure TK2 and QLib_run are loaded, then run the batch file:

LRUN ram1_s2h_tst_Batch_bas

This will translate a number of sample source files (more or less useful utility programs all) into HTML, allowing you to test the program before you decide to install it. It also has the advantage of converting the HTML-related file extension separators back into dots, invariably undone by unzip.

The resulting test files and assorted items in the directory ram1_s2h_tst_ are then best copied over to your Box or PC to be viewed there in your favourite browser.

NB: Any files in a pre-existing directory called s2h will be overwritten! Any previous configuration files you may have made are in all likelihood obsolete, as this version of sb2htm is geared towards using the css style sheet system.

sb2htm needs the Q_Liberator runtime, QLib_run, to be pre-loaded before starting the program. It also needs TK2 or SMSQ/E (see the boot file for details).

Once installed you could try to run the test batch to see that all works satisfactorily. Unless you installed sb2htm to ram1_ you need to configure the batch (formerly "link") file. Open ..s2h_tst_Link_s2h in an editor and alter the path names of the listed files to their actual locations. Save the file and then LRUN or EXecute the batch file ..s2h_tst_Batch_bas.

If this process completes happily within a few seconds, the chances are that the program will work in your environment.

To view the files you may need to transfer them to another medium or folder. To ensure that the demo files display properly the following files from the ..s2h_tst_ directory should all appear in the same location before browsing:

NB: The extension separator must be a dot, not an underscore! This often gets lost during unziping into the QL environment. If you experience broken links when browsing the test files, this is the probable cause.

DIY:

REMark Load program to convert into SuperBASIC
LOAD win1_my_little_program_bas
:
REMark Save tokenised program to file
QSAVE win1_my_little_program
:
REMark Convert it to HTML
EX win1_uti_s2h_sb2htm_obj; '-i!win1_my_little_program_sav -odos2_temp_'

Fire up your favourite browser and view the file in dos2_temp_. Make sure the sbas.css file is also in dos2_temp_. You can simplify this process to one or two clicks by utilising the utility program SBhtm. A detailed article describing this program may be found here.

Default Configuration:

sb2htm now uses the Home Directory to determine the default location of its configuration files, which it expects to find at ..s2h_cfg_.

You can override the default location on the command line with the -@<rootcfg> option. The name of the configuration file must then be specified separately with the -c option. The default name is sb2htm_cfg.

1. Installation

Installation is now just a question of unzipping the program, as described above. The distribution consists of the following sub-directories and files:

*Only marked files and folders are required for proper program operation. The remainder may be deleted if desired

2. Usage

If you have followed the installation guide above, there is little you need to configure to be able to use the program. The main steps you should perform to get the best out of sb2htm is to integrate it with your system, by setting up Hotkeys and/or configuring FileInfo2, as described further on. Once this is done, sb2htm is very easy to use. At its simplest level you could just type:

	EX <path>sb2htm_obj;'-i<inputfile name>'

However, the program is quite flexible, and allows you to personalise it and tweak it in various ways. The rest of this manual describes in gory detail how you can do this if you want to.

You can execute it from the Qpac Files menu (and probably from most other file managers), filling in any command line parameters at the prompt. For this you need to configure FileInfo2 (as per Appendix A, below) to can make it run automatically for the selected file(s). You can also run it from the Start button (Casqade).

New: Now you can also use SBhtm to convert both _sav and _bas files into glorious HTML.

Theres not much to say about output styles and the like, just experiment! Please let me know if youve thought up a good style sheet!

In-line mark-up:

REMark &!

allows you to add HTML mark-up directly in your source code. Anything following that, up to the end of the line is considered to be HTML. No character translation (from QDOS to HTML) takes place, but substitutions are performed as normal. Thus you could have:

1230 rem &!For more info see <a href="#enlighten">here</a>
1240 rem &!or see the manual, <a href="manual#section4">section 4</a>
...
...
5300 rem &!<font color=^Procedures^><a id="enlighten"></a></font>
5310 rem This section explains the intricacies of..

REMark &~

As for &! above, except the REMark symbol itself does not display

See the demo programs for examples.

3. Command line

Settings given on the command line compliment and override those in the configuration file. Not all settings available in the configuration file have a corresponding command line setting, and vice versa.

Only the first instance of a given setting is acted upon. Unknown - or misspelt - settings are ignored.

NB: Some QL platforms may restrict the maximum length of the command line, eg on JS it is 128 characters.

The permitted syntax for the entities is the same as for Config file settings. For a description of the syntax and file names used here please refer to Appendix B.

Typical syntax (abbreviated in list below for clarity)

-<cmd> [!] [<space>] ["] <root> | <filename> ["] <space> | <eol> [default value]

List of settings:

-@
Base location of configuration files or <rootcfg>: optional.[<rootprg>cfg_]

-@ <directory>
If not provided the default location, <homedir>cfg_, is used.
Note: Setting this option also effects the location of the footer and header files. If any of these are located elsewhere their full file names must be provided in the config file.
-c
Config file: optional [<rootcfg>sb2htm_cfg]

-c [<rootcfg>] <name> [<ext>]

Name and location of configuration file to use. If not provided, the default name and location are used. If not located in the configuration file directory, <rootcfg>, the full path and file name must be specified
-d
Dump: optional[<reportfile>]

-d
Dump configuration settings into report file and quit. In aid of debugging configuration settings and the command line.
-i | -l
Input file: mandatory

-i [!] <filename>
An input file name or a link file name must always be provided on the command line.
No output occurs if there is an existing file with the same name as the output file, that is younger than the corresponding source file. This behaviour can be overridden by using an exclamation mark after the -i command:
-i! <filename>
	
if the file name extension happens to be s2h it is taken to be a batch file, ie a file containing a regular list of names of files to be processed (see Batch File), below. If an output root is given (see -o) all the processed files in the batch end up in that location, otherwise the output file location is the same as that of the input file.

-l [!] <filename>
As for -i but input file will always be taken for a batch (link) file, whatever the extension.
-m
Max output line length: optional [100]

-m<integer>
set max line length to given number of characters
Has no effect at present.

-n
Switch line numbers on or off: optional[on]

-n on | off
-n on its own => off

-o
Output root: optional[<rootinput>]
-o <root> [<name> [<ext>]]

This will be the name for the output file in single file mode. If no extension is given, the default is supplied. If no name is given, the input file name is used with the default extension.
Note: No directories are created in single file mode. If the "directory" specified doesnt exist, it is considered to be part of the file name!
In batch mode, if the supplied output directory does not exist, it, and all non-existent parent directories, will be created!
-r
Report file: optional [<rootout><name><_err>]

-r [!] <filename>|<device>|<bank>|*

A report file is only created in the event of an error or warning condition arising. Here you can override the default file name which is always <rootout> <name> <_err> for batch files and screen for single files. Some more examples:
 
 -r ram1_err_log  Output to this file
 -rcon_200x200	  Output to screen
 -r prt		  Output to printer
 -r ""		  Output to <rootprg>err_log
 -r *		  Output to <inputfilename>_err
	
Note: If an error occurs during the initialisation phase a burp is heard and the warning or error message is displayed on screen whatever the error device specified.
Tip: If you want to raise the console so as to edit the command line before execution, start the command line with a '?' or similar to trigger an error.

-t
Title: optional [<name>]

-t <string>
Title text can be max 40 chars long. Can be used as HTML title and/or be displayed on the page.

-v
Version: optional[none]

-v <string>
Use for substitution in headers and footers, etc.

-x
HTML file Extension: optional [.htm]

-x <extension separator> <extension>

Set the output file extension.

4. Configuration Files

This is not an HTML/CSS tutorial. Nowadays it is simple enough for anyone with enough interst in the matter to want to use this program to get the relevant information off the Internet. I have found the W3Schools.com very useful in this respect.

However there is no need to change anything in these files unless you want to, and then it can be done incrementally, making small changes and seeing the result before making more. Work on copies of the originals.

4.1 sb2htm_cfg

Strangely, lines starting with # are significant, while all other lines are ignored, unless they form part of a block, such as #scheme and #html.

Not all statements need be present, but the order of identifiers in the file is significant!

Quotes and significant spaces must be quoted. (See Appendix B. for the nitty-gritty.)

Anything past the first parameter string is ignored.

You can define terms in terms of other terms that have been defined already.

(The ^ symbol, used in matching pairs, is the substitution marker. See Substitution.) Example:

Variables = red            Variables shown in red
Repeat = ^Variables^       also the FOR/REP ones

The config file:

(Some evolutionary dead-ends still persist in the format of the config file, hence various inconsistencies. These may be removed in the future.)

#sh01 must be first item defined
#maxllen<int.b>max output line length
#linenum<on | off>line numbers on by default
#eol<int.b>end of line code
#exthtm<xsep><ext>nomally .htm
#title<string>title string
#version<string>version string or whatever
#preamble<HTML string>*
#postamble<HTML string>*
#report<device>|<filename>'ram1_err_log', or prt, con..
#header<name>|<filename>footer or dev2_cfg_foot_htm
#footer<name>|<filename>header_old
#charset<name>|<filename>"ram1_temp char_asc"
#keywords<name>|<filename>smsqe_txt

*You can now provide a single line pre- and post-amble string. They are inserted into the output stream just after the header file and just before the footer file, respectively. As for headers and footers, the pre- and post-amble strings are considered to be HTML. Substitutions are performed, but not character translation.

#scheme startMultiple schemes no longer supported
Borderany borders
Paperbackground colour = paper
Textmarkup without a <font>..</> get this colour
Languagelanguage, ie core keywords = text color
Unknownunknown and line numbers
Separatorsseparators
Literalliteral 'strings' and numbers
RemarksREMarks and MIStakes
Toolkitsextension keywords
Variablesvariables
ProceduresPROCs/FNs
RepeatREPeat/FOR
Labelsline numbers and labels

All the identifiers above take a <item> parameter, that is almost anything (see parameter syntax, below). These identifiers represent a value that is inserted into the output stream. The names are merely an indication of function. They can in theory be inserted anywhere where substitution is supported by wrapping the identifier between the substitution markers, thus: ^<identifier>^


#html startLoad array of clause definitions (part of scheme)
OpenLangOpening clause for S*BASIC language - the default
CloseLangClosing clause for the above
OpenLabOpening clause for line numbers (and labels)
CloseLabClosing clause for the above
OpenUnknOpening clause for anything unknown
CloseUnknClosing clause for the above
OpenSepOpening clause for separators
CloseSepClosing clause for the above
OpenLitOpening clause for literal numbers and strings
CloseLitClosing clause for the above
OpenRemOpening clause for REMarks
CloseRemClosing clause for the above
OpenTkOpening clause for non-core keywords
CloseTkClosing clause for the above
OpenVarOpening clause for variables
CloseVarClosing clause for the above
OpenRepOpening clause for REPeat and FOR variables
CloseRepClosing clause for the above
OpenRefOpening clause for procedure calls
CloseRefClosing clause for the above
OpenDefOpening clause for PROCedure and FuNction definitions
CloseDefClosing clause for the above
#scheme endEnds HTML and ends scheme

All these identifiers take a <string> parameter. These strings consist of HTML mark-up interspersed with css selectors and attributes. There is no reason why javascript or any other recognised script could not be thrown into the mix, if you could think of a good reason and a way to do so.

The opening and closing clause strings are used as HTML wrappers for the various source code components encountered. When the sb2htm token parser hits, say, a toolkit keyword, it wraps the keyword between the opening and closing clause strings and passes them down the output chain.

The best way to find out about the configuration options is to have a look at the sample files included.

4.2 Header and Footer Files

The Header and Footer files are text files. The contents of the Header file is copied as the first thing in the output file, and the Footer file as the last. These files contain a legal HTML definition of the first or last part of an HTML page. The details are beyond the scope of this manual. It is, however possible to get away with a single line of HTML in each if one so chooses. The Header file could contain

<html>
and the Footer file
</html>

Thats fine for home, but if your opus is to go on the Internet a more elaborate scheme may be needed, for example:

The Header file:

<!DOCTYPE HTML>
<html>
   <head>
      <meta http-equiv="Content-Type" content="text/html;charset=ISO-8859-1">
      <meta name="author" content="©pjwitte 2oo1">
      <meta name="generator" content="sb2htm V0.98">
      <title>^title^</title>
      <link rel="stylesheet" type="text/css" href="sbas.css">
   </head>
   <body>
      <a id="_top_"></a>
      <h1>^title^</h1>
      <pre>

Many of the HTML components here should be easy enough to figure out how to edit to your own requirements. Notice the lines:

      <title>^title^</title>
..
      <h1>^title^</h1>

^title^ is substituted by the command line parameter -tTitle or, if not present, by the definition in the config file, normally ^fname^ (which itself is substituted for the input file name (sans extension).

  <link rel="stylesheet" type="text/css" href="sbas.css">

points to the style sheet file on the HTML side of things. A sample file is included, but is not documented here.

The task of the Footer file is to close any remaining open tags and display any footer type information. As fas as sb2htm is concerned it works in the same way as the Header file, except that it is appended to the output file at the end.

The Footer file:

      </pre>
      <div id="address">
         Generated with sb<em>2</em>htm on ^Date^ at ^Time^<br>
         ©pjwitte March 2oo1
      </div>
      <div id="foot">
         <ul>
            <li><a href="javascript:history.go(-1)">&lt;-Back</a></li>
            <li><a href="#_top_">ToP</a></li>
         </ul>
      </div>
   </body>
</html>

The result of this is more or less what you see below on this page, incuding the navigation bar. As you can see, there is plenty of scope to fiddle around if the fancy should take you..

PS: If javascript is switched off in your browser the above example wont work.

4.3 Character Set File

This file contains a QDOS to iso-8859 translation table. Other translation tables can be cannibalised from asm2htm if required.

Each QL character can be translated to up to 8 HTML characters, as shown below:

 QL - HTML		[ -----     ignored      ------ >

183 : 164		 => &curren;	-  general currency sign
154 : '&ugrave;'	 =  249		-  small u, grave accent
127 : &copy;				-  copyright sign

Note the colon (:) is mandatory. To "switch off" a translation you could replace the : with something else:

127 - &copy;				-  this wont register

The most common translations are built into the program, eg < > &, etc, but they can be overridden here.

The header and footer sections are not translated to the HTML character set (as theyre supposed to contain standard HTML), only substitutions are performed. Only output text and names are translated.

4.4 Core Keyword Files

Core keyword files are used to determine which keywords are part of the S*BASIC language. Core keywords are also sometimes referred to as Language keywords in this document. All the rest are considered to be external. A number of OS keywords relate to underlying hardware, or a specific platform. These are excluded, as a programming aid to flag up keywords that may not work across all intended target environments. They will present as toolkit keywords.

Three core keyword files are included: qdos_txt (QDOS JS), qdostk2_txt (QDOS JS + TK2 v2.12), and smsqe_txt (SMSQ/E 3.27, sans hardware/platform). Choose the appropriate one - or create your own - for your project and set it in the config file:

	#keywords  = smsqe_txt  List of base keyword set

5. Substitution:

Substitution allows more intelligent output in that you can insert up to date information in the display. You can also use substitution as an aid to devising colour and coding schemes. See the config files for examples.

Substitution is first applied, on a first-come basis, on all Config settings as the Config file is loaded. Then, before each file is processed, last minute substitutions are done (date, time, fname). Finally, substitution is performed on all text output and inside mark-up. Header and footer files receive the same treatment.

The maximum depth of substitutions of substitutions is 10

The following substitutions are defined in the program:

^date^
- substituted at the time of output
^time^
- substituted at the time of output
^fname^
- parsed from the given input file name

The following substitutions, defined in the config file, may be overridden by the appropriate command line setting:

^title^
- Use as you like:  -t<title>
^vers^
- Use as you like:  -v<version>
^report^
- error log            -r<log_file_name>

The following substitutions are only parsed in the Mark-up, ie not in headers and footers (?):

^name^
Anchor
^href^
Link

All the scheme variables can be used in substitution.

Example: Say you wish to make the FOR/REPeat variables look the same as ordinary variables, and the following are defined in the config file:

..
Literal    = black		literal 'strings' and numbers
..
Variables  = #D22		variables
Procedures = #d07050		Procs/Fns
Repeat     = orange		REP/FOR
..

Then in the #html section the following mark-up is defined:

OpenVar    = '<font color=^Variables^>'
CloseVar   = '</font>'
OpenRep    = '<font color=^Variables^>'
CloseRep   = '</font>'

This will end up looking like this in the HTML file:

.. REPeat <font color=#D22>loop</font>
.. <font color=#D22>s%</font> = <font color=black>0</font>
..

Which ends up looking like:

.. REPeat loop
.. s% = 0
..

NB: Some modern browsers no longer support <font> tags and the like. When using css style sheets, all the colour information goes into the .css file so the colour idendifiers become redundant, or may perhaps be put to other use. Here is how the same is achieved using style sheets:

OpenLit    = '<span class="lit">'
CloseLit   = '</span>'
..
OpenVar    = '<span class="var">'
CloseVar   = '</span>'
OpenRep    = '<span class="var">'
CloseRep   = '</span>'

Then in the style sheet you need to define the class "var":

span.lit {color:black;}
span.var {color:#D22;}

and you end up with HTML which looks like this, and displays same as above.

.. REPeat <span class="var">loop</span>
.. <span class="var">s%</span> = <span class="lit">0</span>
..

Tip: Your neednt make a separate style sheet if you dont want to. You can add all the style definitions to the <header> section of your header configuration file. Just enclose them between <style></style> tags.

6. Batch File

The batch or "link" file is a plain text file, containing an ID followed by a list of file names. Here is how it could look:

#shl01
#
#    Sample link file for sb2htm

# Lines starting with # are ignored
# as are blank lines

win1_test_MkConfig_sav
dev7_prg_tst_CrossHairs_sav
ram1_dehexpoke_sav
flp1_dehexpoke_sav

# end

The ID #shl01 must be the first item on the first line to validate the file.

The default extension is _s2h.

If no output location has been given then each file in the set is output to its native location with the _sav extension exchanged to .htm

If a location (device + directory) is given, the directory is created and all files are exported to this location with their original names and the .htm extension. No sub-directories are created.

Note: Unfortunately it is not possible to differentiate between two different files with the same name but different locations (eg ram1_dehexpoke_sav and flp1_dehexpoke_sav, in the example above) from a file you simply want to update! One of the output files here will be overwritten, so take care!

No cross-referencing is done between the files (as in asm2htm), so in reality it is a batch file, not a link file, as was once the intention..

7. SBhtm

SBhtm is a new utility hack for sb2htm. SBhtm only works under SMSQ/E, though it could possibly be made to work under Minerva too (with a bit of programming effort). It takes any S*BASIC source code file, with or without line numbers, tokenised (_sav) or plain (_bas), and sends it to sb2htm to process and output.

You can use it while editing (assumes your editor, like QD, stuffs the filename of the recently saved file in the Stuffer Buffer): Save file and press hotkey: Lo and behold! your current opus it converted to HTML and squirted into your default DOS or NFA device, ready for viewing in your browser. No need to re-add line numbers or tokenise first.

Or add to FileInfo2 (see below) to convert any S*BASIC source file to HTML from your favourite File Manager at a mouse click or two.

You need to configure the source SBhtm_bas code to suit your situation and requirements (lines 31-34). (For example, it comes pre-configured to reside in the same directory as sb2htm and to output to dos3_.) You can compile the program if you like - or leave it as it is. Either way, it is invoked with EXEC thus:

	EXEC <path>SBhtm; '<inputfile>; -odos5_'
To put it on a Hotkey:
	ERT HOT_RES1(<key>, <path>SBhtm_obj, "SBhtm")
The best way, to my mind, is to add it to FileInfo2:

Extensionsbas, sav
ActionsTo HTML
Requested file type for this actionirrelevant
Thing to launchSBhtm
Executable file to loadwin2_util_s2h_SBhtm_obj
Command line-i«devN_name_ext»
Put it on job stackyes
Pick caller backno

For a detailed look at this program, see my article!

Appendices

A. Troubleshooting

  1. Testing/Running
  2. HTML
  3. Translation
  4. Warnings and Errors
  5. File names and Defaults
  6. Configuration File and Command Line
  7. Configuring FileInfo2

Testing/Running:

Q: On booting into the demo program I get files not found.

Q: On booting into the demo program I get an error: 'invalid parameter'

A: You did unzip sb2htm to a QDOS-formatted medium and not a PC or other?

Q: The test files dont display properly.

A: Are you sure all the files listed in Quick Start are included in the same directory?

Q: Browser cant find files; dud links.

A: Ensure all files copied to the browser side use a dot as the file name extension separator, not underscore as for QDOS/SMSQ

Q: Windows® complains about "Device name not valid" or similar.

A: It should be noted that Windows finds some names unpalatable as file or directory names. The names include, but are not limited to: nul, con, aux, com1..com9, lpt, etc. Rename the source file or supply a valid output name with -o<dir> (or -o<filename> for single files).

HTML:

Q: I get strange characters in my header/footer

Q: Parts of the display is garbled

A: The header and footer sections are not translated to the HTML character set, only substitutions are performed, so make sure any changes made to these files conform with HTML (and CSS if used). Or check the next answer.

Translation:

Q: sb2htm does not seem to read my character translation table.

A: Make sure the relevant setting in the config file (#charset) points to the correct character translation file

The colon (:) is mandatory in the htmchr file, otherwise the translation is "switched off".

The table may not be correct.

Warnings and errors:

For batch files there is normally no display, unless an error occurs during program initialisation.

Youll normally find the report file, if any, in the output location.

File names and defaults:

<rootprg> the configured base location of sb2htm
<rootinp> location of input - batch or source file(s)
<rootout> location to put output files and report file

If no <rootout> is specified, <rootout> = <rootinp>

File names supplied to the program in the config file or on the command line must conform to the following rules:

Initially the program expects its configuration files to be located in

<rootcfg> = <rootprg> <cfg>, where <cfg> = 'cfg_' (and <rootprg> = <homedir> these days) and have the following default names and extensions:

<name><ext> 
sb2htm_cfgconfiguration file
htmchr_txtcharacter translation table
Header_htmHeader files
Footer_htmFooter files

Using these default values, the program will accept:

[<rootcfg>] <name> [<ext>] (square brackets imply optional items.)

NB: If a new root is given with the -@ option, the given value will become both the default config file directory and the program directory.

The following defaults are also applied or accepted by sb2htm:

<name>_errError log. <name> = name of source or batch file
<name>_s2hbatch files, no default name
<name>_savsource files, no default name

NB: Unfortunately it is not possible to differentiate between two different files with the same name but different locations, from a file you simply want to update! (See this note).

If only a directory name is specified it should terminate on one of

_underscore
/slash
\backslash

The above characters are considered to be illegal in any part of the file name! They may be used as alternatives to underscore in supplying file names (they will be translated to QDOS type file names on interaction with the system, naturally.) (Not completely implemented yet. Use underscore.)

NB! If the supplied directory already exists, the trailing separator is not required, otherwise it is. Best always use a trailing separator when specifying directories.

Configuration file and command line:

If the program doesnt appear to be doing what you expect you can try dumping its understanding of your input to the log file with the -d parameter. Once the configuration has been read and output, processing stops. Note that not all substitutions will have been effected at that time, so it may look as if there are some unresolved definitions in the configuration. Eg, if you find ^names^ in the output, that indicates an unresolved term, but this is not necessarily a problem.

Configuring FileInfo2:

Try the following settings. Leave all other settings at default values unless you know otherwise.

Extensionsav
ActionsTo HTML
Requested file type for this actionirrelevant
Executable file to loadwin2_util_s2h_sb2htm_obj
Command line-i«devN_name_ext» -odos2_temp_
Put it on job stackyes
Pick caller backno

Save to memory. Try it out, then save to disk. Youll have made a backup first, of course. Next time you use your FI2-enabled file manager, click on a program file name with the extension sav, select To HTML from the menu and it will automatically be converted to HTML in the default output directory. In the example above, if you have QPC2 running on Windows, the output is directed to a Windows directory called temp, where it can be viewed in your browser immediately. Naturally you can do the same for the link file extension _s2h.

B. Config line syntax

This syntax for lists and strings applies to all items in the configuration file and on the command line.

Meta characters used to describe the syntax:

["]	    = optional matching quotes " | '
		use if parameter contains spaces or quotes
[<space>]	optional space
<space>		mandatory space
<root>		device and path
<name>		name portion of file

<filename>  = <root> <name> | <root> <name> <extension>
<rootprg>	configured program location
<rootcfg>   = <rootprg> + cfg_	configuration file location

A parameter string item may take the form:

item 		= [<string> | <code>] [<delimiter> <item>] *
string		= [<start quote>] [<ascii characters>]* [<end quote>]
code		= "$" <$digit> [<$digit>] |
		  "%" <%digit> [<%digit>] *7 |
		  <digit> [<digit>] *2
quote		= "'" | '"' AND <start quote> = <end quote>
delimiter	= "," | "<SPACE>" | <end-of-string>
$digit		= {0..9,A..F,a..f}
%digit		= {0..1}
digit		= {0..9}

where:
		< >	represents an entity
		[ ]	represents an optional item
		..   	=> from..to
		{}	=> one of
		*	=> repeat item 0.. times
		*n	=> repeat item 0..n times
		|	=> either | or
		" "	=> literal

eg: The code
		"abc",$10 %10101 "r""s" "t"u, ,x  ,12,'"'
equals
		97,98,99,16,21,114,115,116,117,120,32,32,12,34
in bytes.

Note that all this implies that quotes, spaces, $, % and null strings must be quoted or given as a code if they are intended literally or you may get some weird effects!

Note that <space> is treated as a space inside unquoted strings and as a delimiter outside them.



sb2htm V0.98
©pjwitte 2oo1, 2oi6