Help¶
AUX ROM HELP “RULES OF THE ROAD”¶
You can type:
- HELP
Shows the top level “85_Index” help file.
- HELP THIS
Tries to find a help file called “THIS.txt” and if found, shows it. If not found, does a wildcard search for files that match “THIS”. If not found, generates “NOT FOUND” error. If exactly 1 is found, shows THAT file, otherwise if >1 is found, builds an “on the fly” help screen containing up to 64 lines with one link per line for each file found that matches “THIS” and shows that.
- HELP THIS OR THAT
Same as “HELP THIS” except that it doesn’t try to find the exact file first, but rather immediately does a wildcard search for “THIS*OR*THAT”, then handles the result the same as “HELP THIS” with regards to 0, 1, or more results.
HELP *THIS
HELP *THIS*
HELP THIS*
HELP THIS OR THAT*
HELP THIS*OR*THAT
When wildcards are included in the search term, then no searching is done for an exact match, and NO wildcards are ADDED to the search term, but rather a wildcard search is done using the exact wildcard search term provided. Results, again, are handled the same for 0, 1, or more results.
In creating Help files for use with the AUX ROM’s HELP function, some things are DITWAD (Do It This Way As Demanded) and other things are PROG (Please Remember Our Guidelines) . Few things are actually enforced, but if you follow DITWAD and PROG, everyone is likely to be happier.
DITWAD (Do It This Way As Demanded)¶
The Help screens are each stored in individual files of up to 64 lines of up to 32 chars each, with each line terminated by an end-of-line sequence (either LF or CR/LF). The HP-85 CRT alpha memory holds exactly that amount, hence the limit.
The file names for the Help screen files should be no more than 28 characters long (so that they will fit on a single line of the CRT along with the “<..>” tag header). This 28 character limit does NOT include the “.txt” file extension, so with that extension, the filename can be a total of 32 characters long. The file name MUST end with a “.txt” file extension. The file names should not contain any of these characters:
SPACE COMMA / \ : $ @ ! * ?
The file contents must be plain, simple ASCII, as they will get displayed using the HP-85’s font or character set, so don’t try anything fancy or idiotic like a UTF-8 file or Unicode or blah-blah-blah.
When you create a Help screen file and name it, you must then place it in the appropriate sub-folder of the HELP85 sub-folder. If you’re doing this on the EBTKS SD card, then the HELP85 folder will be in the root of the card (“/HELP85”), whereas on the Series 80 Emulator, the HELP85 folder will be wherever you’ve installed the Emulator (wherever the HP85.EXE file exists). In either case, the SDHOME$ function (on the real or emulated HP-85) will return the path to this ‘home’ directory, and THAT is where you’ll find the HELP85 folder. Within that HELP85 folder are sub-folders 00, 01, 02, etc. You’ll place your new Help file in one of those sub-folders, usually the highest numbered one. Each folder will hold approximately 100 help files before the next higher one should be created. NOTE: It’s critical that these sub-folders be numbered sequentially and as 2-digit names, as that’s what the AUX ROM expects and generates as it’s searching for desired help files. Remember: don’t use SPACE characters (or any of the above-mentioned verboten characters) in the name. Use an ‘_’ (underscore) character in place of SPACE.
Within the limits of 64 lines of 32 characters, you can do whatever you want, just remember to keep to simple ASCII characters (look at the HP-85 character set from 32-127, removing the verboten characters, and those are the only ones you should use, although if you want to get tricky, you COULD use the 0-31 characters, except for CR and LF, although your editor might choke on some of those).
If the file is longer than 64 lines, all lines beyond 64 will be ignored. If lines are longer than 32 characters, the excess characters will wrap around to the next line and make a bloody mess out of everything, so don’t do that. There is NO automatic “word breaking” if your lines are longer than 32 characters. The “wrap around” will happen exactly at 32 characters if you’re foolish enough to have a line longer than 32.
LINKS in a Help screen begin with <..> and are immediately followed by the filename (minus the .txt suffix) of the file being linked to. For example, to put a link to “85_Index” in a Help screen, use this text:
<..>85_Index
The “<..>” tells the Help code that there’s a link here and that the filename follows immediately after WITH NO SPACES! When loaded, the “..” will get replaced by a two digit number starting at “<00>” and increasing with each link up to a maximum of “<99>”, so a maximum total of 100 links can be included on a single help page (if you can fit them in…) The link filename is terminated when a space is encountered or the end of the CRT line (the right edge of the CRT), whichever comes first. So, everything between “<..>” and the first space or right-side of the CRT line is the filename being linked to. There are no other limitations. The “<..>” can start at the left side or it can be in the middle of the screen, just so long as there’s room for the entire filename to exist on the same line with the link tag.
At runtime, when the Help screen is being displayed, the “current LINK” is indicated by an underline beneath the “<xx>” for that link. You can move the “current link” marker with the cursor keys. If there are multiple link tags on a single line, up and down cursor pick the one that is CLOSEST to the same column. Left and right cursor only work when there ARE multiple links on the same (current) row.
If you have Help content that won’t fit in a single 64-line file, you can make “sequential help files” by adding sequential two-digit numbers to the end of the file name (before the “.txt” extension). Then, when displayed by HELP, the + and - keys can be used to move forward and backward (respectively) through the sequential files. NOTE: you may not use “00” as one of the numbers, as that is used internally in a way that will fail to link to a file with 00. An example would be:
HELP_TEST01.txt
HELP_TEST02.txt
HELP_TEST03.txt
etc
If you’re viewing HELP_TEST01 and the - key is pressed, nothing will happen, but if you press the + key, then HELP_TEST02 will be displayed. Another + key press will display HELP_TEST03, at which point further + key presses will do nothing, but - key presses can be used to move back to HELP_TEST02 and from there back to HELP_TEST01. If you need more than 99 sequential files, you’re writing a novel, not help screens, and should move to a more modern writing environment. It is expected that this will be a fairly rarely used feature, but my expectations have been dashed before.
PROG (Please Remember Our Guidelines)¶
This is where we come to the “what to do to make all of the Help screens look and work reasonably the same.”
If the filename specified with the HELP keyword isn’t found exactly, then it will search for filenames that ‘similar’. In order to facilitate this (that means, “to make this work for other people, you borking fidnip!”) it would be very good to use certain ‘keywords’ in your filenames, and in a certain order. It’s impossible to come up with a complete, exhaustive list of keywords to use, but below is a list of reasonably obvious ones. It’s important that everyone SPELLS THEM THE SAME, so that the search functions will work properly. For example, if different files use “IOROM”, “ROM_IO”, and “ROMIO”, only one of those are going to be found for the user, depending upon what the user types in. In NO case should you use “I/O ROM”, “IO ROM”, “ROMI/O”, “ROM I/O”, or “ROM IO”, because both ‘/’ and SPACE are verboten characters in file names. Further, if you’re making a Help screen on, say, the CONTROL keyword from the IO ROM, you would name the file “ROM_IO_CONTROL.txt” (upper/lower case doesn’t matter), not “CONTROL.txt” or “CONTROL_ROM_IO.txt”. You want to include all reasonable “search keywords” that will help the HELP statement find your file. If you do it right, then your file (along with others, potentially) will be found if the user types any of these commands:
HELP ROM IO
HELP CONTROL
HELP ROM CONTROL
HELP CONTROL ROM IO
Your file would still be found for all four of those, even if you named it “CONTROL_ROM.txt” or “CONTROL_ROM_IO.txt”, but it would be very nice, thank you, please, to have some semblance of consistency in the naming of these files.
So, when using multiple ‘keywords’ in your file name (think of them as “search terms”), they should be used in “highest-to-lowest” hierarchical order. You’re welcome to choose whichever keywords make the most sense (and fit within the 28 character limit), and make up your own, as well. But please keep the above in mind.
You do NOT need to use all ‘levels’ of keywords, and in general should OMIT levels of keywords unless they seem necessary for clarity OR for separating THIS help subject from foreseeable OTHER help subjects. For example, you will rarely want to place 83, 85, 86, 87 at the start of your Help, as any given collection of help screens will be targeted at EITHER the HP 85 family of computers OR targeted at the 86/87 family of computers, and their respective help files will be in different folder trees (HELP85 and HELP87). But if it’s REALLY important, then you would start off with one of those. Try to dredge up some logic, reason, and uncommon sense when choosing which levels of keywords to include, using everything that seems reasonable to use, and no more. Further, management reserves the right to rename your Help files without notice, consultation, or lip service. In general, avoid “model numbers” in filenames whenever possible (such as “82936A” … what the hell is THAT? Rather, use “ROM_DRAWER”; instead of “82937A”, use “HPIB”). Keep it simple, because HELP users need help, and if they have model numbers memorized, they probably don’t need help. You can put model numbers IN the Help screen itself, as THAT might be helpful…
Suggested keywords, in highest-to-lowest groupings, are:
DEVICE¶
83
85
85A
85B
86
86A
86B
87
87XM
DISK (external)
PRINTER (external)
PLOTTER
etc.
SUB-SYSTEM¶
KEYBOARD
CRT
TAPE
PRINTER (internal)
DISK (86 “parallel interface” drives)
etc.
IO MODULES¶
HPIB
GPIO
SERIAL
BCD
PARALLEL
MODEM
RAM
ROM
EBTKS
etc.
ROMS & BPGMS¶
SYS (system ROMs)
GRAPH
PROGDEV
MIKSAM
LANG
EXT
ASM
SYSEXT
FORTH
MATRIX
IO
EMS
MS
ED
SERVICE
AP
PP
AUX
BPGM [name]
KEYWORDS¶
(actual keywords from Basic language provided by SYS/ROM/BPGM)
Ideally, there will be “hierarchical index pages,” so that the top-level ‘default’ page (85_Index) will have links to all of the other “next level index pages”, and those pages will have links to either further index pages or to actual files, so that a user could ‘browse’ or ‘drill’ their way down to the information they’re looking for, as well as trying to search directly for it via a HELP xxxxx command.
With only one link per line, a single index could point to 64 files or other index pages. If we average that out to half of that, 32 links per index page… if 85_Index has 32 links to other index pages, and each of those averaged links to 32 files, just that would handle 1024 help files. So, using this scheme, the index is quite BROAD and SHALLOW, not more than 2 or 3 levels of indexing, most likely. It’s conceivable that some Help pages will need to be linked to from more than one index, but that would definitely be an exception and not a rule.