* Major changes since previous release (see History_txt)
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.
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.
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.
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
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!
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.
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]
-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.
<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>_errNote: 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.
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.
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
(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 start | Multiple schemes no longer supported |
---|---|
Border | any borders |
Paper | background colour = paper |
Text | markup without a <font>..</> get this colour |
Language | language, ie core keywords = text color |
Unknown | unknown and line numbers |
Separators | separators |
Literal | literal 'strings' and numbers |
Remarks | REMarks and MIStakes |
Toolkits | extension keywords |
Variables | variables |
Procedures | PROCs/FNs |
Repeat | REPeat/FOR |
Labels | line 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 start | Load array of clause definitions (part of scheme) |
---|---|
OpenLang | Opening clause for S*BASIC language - the default |
CloseLang | Closing clause for the above |
OpenLab | Opening clause for line numbers (and labels) |
CloseLab | Closing clause for the above |
OpenUnkn | Opening clause for anything unknown |
CloseUnkn | Closing clause for the above |
OpenSep | Opening clause for separators |
CloseSep | Closing clause for the above |
OpenLit | Opening clause for literal numbers and strings |
CloseLit | Closing clause for the above |
OpenRem | Opening clause for REMarks |
CloseRem | Closing clause for the above |
OpenTk | Opening clause for non-core keywords |
CloseTk | Closing clause for the above |
OpenVar | Opening clause for variables |
CloseVar | Closing clause for the above |
OpenRep | Opening clause for REPeat and FOR variables |
CloseRep | Closing clause for the above |
OpenRef | Opening clause for procedure calls |
CloseRef | Closing clause for the above |
OpenDef | Opening clause for PROCedure and FuNction definitions |
CloseDef | Closing clause for the above |
#scheme end | Ends 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.
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:
<!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.
</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)"><-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.
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 => ¤ - general currency sign 154 : 'ù' = 249 - small u, grave accent 127 : © - copyright sign
Note the colon (:) is mandatory. To "switch off" a translation you could replace the : with something else:
127 - © - 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.
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
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:
The following substitutions, defined in the config file, may be overridden by the appropriate command line setting:
The following substitutions are only parsed in the Mark-up, ie not in headers and footers (?):
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.
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..
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:
Extensions | bas, sav |
Actions | To HTML |
Requested file type for this action | irrelevant |
Thing to launch | SBhtm |
Executable file to load | win2_util_s2h_SBhtm_obj |
Command line | -i«devN_name_ext» |
Put it on job stack | yes |
Pick caller back | no |
For a detailed look at this program, see my article!
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).
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.
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.
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.
<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 | _cfg | configuration file |
htmchr | _txt | character translation table |
Header | _htm | Header files |
Footer | _htm | Footer 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> | _err | Error log. <name> = name of source or batch file |
<name> | _s2h | batch files, no default name |
<name> | _sav | source 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.
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.
Try the following settings. Leave all other settings at default values unless you know otherwise.
Extension | sav |
Actions | To HTML |
Requested file type for this action | irrelevant |
Executable file to load | win2_util_s2h_sb2htm_obj |
Command line | -i«devN_name_ext» -odos2_temp_ |
Put it on job stack | yes |
Pick caller back | no |
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.
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.