StrawHelp FAQ

You upgraded to use MSIE8, right? It is trying to be smart and is making a nuisance of itself...
Upgrade to the latest version of StrawHelp, that contains a trap to make it work correctly.

StrawHelp does nothing for ages, then crap appears on the screen!

Look carefully at the junk on the screen. You'll probably see the first four characters are "SQSH". While your attempts to view a squashed file are usually trapped and refused, direct links from help pages to squashed content is not trapped.

It is quite unusual to encounter squashed help pages - this, a form of LZW compression, is usually reserved for sprites (bitmap graphics) and DrawFiles (vector graphics) and seeing as StrawHelp supports neither it seemed pointless to include support for squashed files.

The HTML uses a lot of weird styles and MSIE-like stuff.

StrawHelp uses some ActiveX control or other which provides a mini MSIE 'browser' with which we view the help files, and to this end the conversion to HTML makes liberal use of <span...> with embedded styles and all sorts. Basically anything that looks correct within MSIE with scant regard to other browsers. Normally I'd say this is really bad manners, however with a program kinda 'hardwired' to use MSIE, it makes sense...

If you are hoping to save various documents from within StrawHelp, they will probably look more-or-less correct with up-to-date versions of Opera and Firefox / Mozilla. If you were intending to view them with a RISC OS browser... unless something amazing has happened since mid-2007 I could cry at the situation with browsers under RISC OS. You see, Microsoft can invest some of their profits into making a kick-ass browser. It gives them a market domination stance. The code-base for Mozilla was open-sourced and extended to become Firefox, plus being open source and popular, many people are working (or have worked) to make it what it is today.
Meanwhile, RISC OS, sadly, is a minority platform that is not keeping up. It is all well and good saying we are totally immune to all those Internet viruses, trojans, and scripting nasties (we are!), but the fact is we don't have a browser that can do proper style sheets and JavaScript. It seems the approach of people working on RISC OS browsers has been to design a browser that tries to do a good job or rendering the page content, while marginalising JavaScript as something that is mostly unnecessary. I will agree 100% that JavaScript has had some horrible abuse in the past; I recall a site (BT's customer services?) many years ago that built up a document using long spewage of document.write (this is probably something PHP would be better suited for these days, make the server end 'smart', not the browser). And the worst sin of all surely has to be calling JavaScript to execute a link. Much wasted effort over a simple "a href" link! However JavaScript also has its uses, and some sites rely upon basic support to auto-size according to whether the user is running in sane or stupid resolutions, plus other little bits and pieces like that. I'm sure a hard-core JavaScript user could give better examples, I don't use it much myself, except for my movie reviews where it switches in and out layering to allow extended comments (which may contain 'spoilers') to be hidden until requested. Only one RISC OS browser correctly supported layers when I tested it (in the summer of 2007), however it was of little use as it did not support JavaScript so these layers couldn't be manipulated. Duh!

Clicking on a link fails to find the page, why?

There are three main reasons why the link will fail.

The first is due to some really dumb-ass stuff in the #Prefix and #Postfix tags (these define stuff to be automatically added to the beginning/end of links) which when coupled with the link content itself results in something so manged that my parser can't work it out. I hope you won't encounter this too much - as I put a lot of thought into a link parser that was able to make sense of the OS320 manual's links. ☺

The second reason, which you'll see with manuals such as the ExtBasAsm one (by Steve Drain) is that files can include a > character for a redirection, hence a filename like "P>EQU" (for example) means "if the user is trying to look at the file 'P', show them 'EQU' instead". I will probably support this one day, but I'm not in any great hurry as it is possible to do this in a more friendly way inside the help file itself (a link in the form "<P->EQU>" (show 'P' on screen, actually go to 'EQU').

The final reason shows up in the supplied VDU manual if you try to follow the link to OS_ReadModeVariable (etc, look under VDU 22). This manual uses the very old method of using <manual>.<page> to define a link to a different manual. StrawHelp does not understand this, so the message returned is misleading - it reports the help file could not be found when it should say that links in other manuals are not supported yet.

I'm confused, if 'blah' is a StrongHelp help file, why do say about files not being found?

When reading a manual, click on the button Browse file system some time. You'll see that each 'file' (manual) contains a selection of files which comprise that manual.

The terminology could be a bit ambiguous, so when I say "manual", I am referring to the single file that is the entirety of the StrongHelp manual; and when I say "file", I am referring to the individual parts extracted from within the manual.

What are those weird file icons?!?

It makes sense to RISC OS users. ☺

For non-RISC OS users, the system uses a method of file typing using extended meta-data.
For example, under Windows a file's type is determined by its extension, and it has associated meta-data giving stuff like the last modified time and if the file is read only.
RISC OS uses extra meta-data to provide a range of file types (0x000-0xFFF), it does not use extensions at all.

The convention for file icons, as you'll see below, is that an application has a distinctive 'logo' (like Internet Explorer has a big blue 'e'), and then the associated file is a black rectangle which contains some sort of representation of what the file is, along with something related to the application icon. The DrawFile shows two shapes plus !Draw's compass. The Sprite file shows part of a painting plus !Paint's paintbrush... The big blue/red/yellow 'A' types are hangovers from the days of the "Archimedes", and these are system files. In more modern versions of RISC OS they are represented using something akin to yucky green cog-wheels (as an attempt to drop the heritage and make the icons a little nicer looking than something that was designed in the mid '80s!).

	This is a directory, a "folder" in Windows parlance.
	This is the icon given to StrongHelp files. It is of the '3D-look' style.
	This is a DrawFile. It's a sort of vaguely PostScript-like vector-based graphics system built into RISC OS (with a basic editor supplied with the machine). It is conceptually related to .WMF and .SVG files; but compatible with neither.
	This is a Squashed file. Any file, when squashed, becomes a Squash file. It is a short header (describing what the file really is) followed by a 12 bit LZW stream. Apparently if you strip off the 20 byte header, the Unix commands uncompress and/or gunzip can decompress these files...
	This is a Sprite file. A sprite file is a pixel-based graphics format that is very similar to .BMP files, except it can work in any of the graphics resolutions that RISC OS provides, using square or rectangular pixels accordingly, a transparency 'mask' is optional (alpha blending on later machines), and there can be numerous sprites inside one sprite file - makes things a lot tidier if you wish to completely redesign the window 'furniture' (rather like basic "skinning" on Windows, only system-wide).
	This is a 'utility' written in ARM code. Unlike an Absolute file, which is akin to an .EXE, a utility is usually a lot smaller, plus it has numerous things pre-defined on entry (like R13 points to a stack, R0-R3 are often set up...). StrongHelp uses this system to permit help file authors to transparently edit the 'search string' between the user and StrongHelp itself. An example is if the user is looking for "XParallel_Op", remove the "X" as all that means is "don't actually cause an error, just return with V flag set on error" version of the SWI. It is not necessary to look specifically for "XParallel_Op" as every SWI automatically has an 'X' version, it's the OS that does this... [SWI is SoftWare Interrupt: RISC OS makes extensive use of these. They are much cleaner, but conceptually the same as INT calls on the PC]
	This is a Data file. It is a type usually given to miscellaneous files that do not otherwise have any type. In the context of StrongHelp, these files are actually text files (just like below), however the use of the Data file type lets StrongHelp know that it should not perform searching on this file.
	This is a Text file. Plain 8 bit ASCII text (in the Latin1 (aka ISO 8859/1) character set) is what these files contain. Important: These files will not display correctly in most regular versions of Notepad. This is because RISC OS uses only a single byte (ASCII 10) to mark a line ending, as opposed to the Windows CRLF (ASCII 13,10) style. I have replaced Notepad with Metapad, a much better lookee-likee: http://liquidninja.com/metapad/
	This is an Untyped file. On RISC OS, this denotes a file that uses Load/Exec addresses (a hang-over from the days of the BBC micro) instead of file typing. In StrawHelp, this is the icon given to any file which is encountered that isn't recognised as "one of the above"...

EUPL? Why isn't this GPL like everything else?

Might I suggest you read the EUPL licence text sometime? Compare and contrast with GPL (especially version 3). You'll come to understand what an open licence is, and why I feel that the GPL is far to restrictive to ever taint my software with it.
Of course, this does not mean you cannot use my EUPL code in your GPL (v2) software. Read the text of the EUPL. Learn what freedom really means...

Other questions? Contact me!

You can contact me at: heyrick1973 -at- yahoo -dot- co -dot- uk