Unix pages
Home -> UNIX software -> JOYCE -> Moonstone BasHelp

Moonstone BasHelp

BasHelp is a memory-resident help program for the Amstrad PCW, designed to add pop-up help screens to Mallard BASIC. When launched, it relocates itself to the top of memory and loads BASIC.COM. It will not work if BASIC.COM has RSXs attached.

When the user presses ALT+F1, the help index is displayed. If they press SHIFT+ALT+F1, the word immediately to the left of the cursor is used as a search term. An exact match takes the user to the appropriate topic; otherwise, the page of the index starting with the first letter of the topic is displayed.

Example BASHELP screen

Text storage

The help text is stored in the file BASHELP.DAT, in an obfuscated form. The following C code will deobfuscate it:

int main(int argc, char **argv)
{
	unsigned addr = 0x80;
	int ch;
	unsigned char a, b;

	while ((ch = getchar()) != EOF)
	{
		b = (ch ^ 0xA7) - addr;
		a = 0x8F - b;
		++addr;
		if (addr == 0x100) addr = 0x80;	
		putchar(a);
	}
	return 0;
}

Once the obfuscation is removed, the file consists of a list of topics, each topic made up of a number of pages. The first topic is the table of contents.

A topic begins with a single byte giving the number of pages in the topic, followed by the pages:

	DB	n_links		;Number of hyperlinks: can be 0
	DB	hyperlinks	;Six bytes per link
	DB	page text	;Lines are terminated with 0Dh
	DB	0FFh

A hyperlink is 6 bytes:

	DB	row		; 1-based row of anchor text
	DB	col		; 1-based column of anchor text
	DB	length		; Length of anchor text
	DW	offset / 128	; Offset of target topic (CP/M record)
	DB	offset % 128	; Offset of target topic (position in record)

The BASHELP.COM utility expects the first topic to be the table of contents, and to consist entirely of links to all the other topics.

Utilities

I have written a pair of utilities that can convert a BASHELP.DAT file to plain text, and vice versa. They are supplied as COM files (for CP/M) and C source, suitable for compiling on a modern UNIX or Windows system.

[ZIP] BASHELP.ZIP (31K)

Example customised BASHELP helpfile


John Elliott 16 July 2016