mirror of
https://github.com/simh/simh.git
synced 2026-02-11 02:31:35 +00:00
SCP: Added hierarchical help capability (from Timothe Litt)
This commit is contained in:
Mark Pizzolato
256
scp_help.h
Normal file
256
scp_help.h
Normal file
@@ -0,0 +1,256 @@
|
||||
/* scp_help.h: hierarchical help definitions
|
||||
|
||||
Copyright (c) 2013, Timothe Litt
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a
|
||||
copy of this software and associated documentation files (the "Software"),
|
||||
to deal in the Software without restriction, including without limitation
|
||||
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
and/or sell copies of the Software, and to permit persons to whom the
|
||||
Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in
|
||||
all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
||||
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
||||
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
Except as contained in this notice, the name of the author shall not be
|
||||
used in advertising or otherwise to promote the sale, use or other dealings
|
||||
in this Software without prior written authorization from the author.
|
||||
*/
|
||||
|
||||
#ifndef SCP_HELP_H_
|
||||
#define SCP_HELP_H_ 0
|
||||
|
||||
/* The SCP structured help uses help text that defines a hierarchy of information
|
||||
* organized into topics and subtopics. This is modelled on the VMS help command.
|
||||
*
|
||||
* This arrangement allows the long help messages being used in many devices to be
|
||||
* organized to be easier to approach and navigate.
|
||||
*
|
||||
* The helpx utility (a Perl script) will read a device source file
|
||||
* that conforms to the previous conventions, and produce a template and
|
||||
* initial translation into the format described here.
|
||||
*
|
||||
* The structure of the help text is:
|
||||
*
|
||||
* Lines beginning with whitespace are displayed as part of the current topic, except:
|
||||
* * The leading white space is replaced by a standard indentation of 4 spaces.
|
||||
* Additional indentation, where appropriate, can be obtained with '+', 4 spaces each.
|
||||
*
|
||||
* * The following % escapes are recognized:
|
||||
* * %D - Inserts the name of the device (e.g. "DTA").
|
||||
* * %U - Inserts the name of the unit (e.g. "DTA0").
|
||||
* * %S - Inserts the current simulator name (e.g. "PDP-10")
|
||||
* * %#s - Inserts the string suppled in the "#"th optional argument to the help
|
||||
* routine. # starts with 1. Any embedded newlines will cause following
|
||||
* text to be indented.
|
||||
* * %#H - Appends the #th optional argument to the help text. Use to add common
|
||||
* help to device specific help. The text is placed AFTER the current help
|
||||
* string, and after any previous %H inclusions. Parameter numbers restart
|
||||
* with the new string, following the last parameter used by the previous tree.
|
||||
* * %% - Inserts a literal %.
|
||||
* * %+ - Inserts a literal +.
|
||||
* - Any other escape is reserved and will cause an exception. However, the goal
|
||||
* is to provide help, not a general formatting facility. Use sprintf to a
|
||||
* local buffer, and pass that as a string if more general formatting is required.
|
||||
*
|
||||
* Lines beginning with a number introduce a subtopic of the device. The number indicates
|
||||
* the subtopic's place in the help hierarchy. Topics offered as Additional Information
|
||||
* under the device's main topic are at level 1. Their sub-topics are at level 2, and
|
||||
* so on. Following the number is a string that names the sub-topic. This is displayed,
|
||||
* and what the user types to access the information. Whitespace in the topic name is
|
||||
* typed as an underscore (_). Topic names beginning with '$' invoke other kinds of help,
|
||||
* These are:
|
||||
* $Registers - Displays the device register help
|
||||
* $Set commands - Displays the standard SET command help.
|
||||
* $Show commands - Displays the standard SHOW command help.
|
||||
*
|
||||
* For these special topics, any text that you provide will be added after
|
||||
* the output from the system routines. This allows you to add more information, or
|
||||
* an introduction to subtopics with more detail.
|
||||
*
|
||||
* Topic names that begin with '?' are conditional topics.
|
||||
* Some devices adopt radically different personalities at runtime,
|
||||
* e.g. when attached to a processor with different bus.
|
||||
* In rare cases, it's better not to include help that doesn't apply.
|
||||
* For these cases, ?#, where # is a 1-based parameter number, can be used
|
||||
* to selectively include a topic. If the specified parameter is TRUE
|
||||
* (a string with the value "T", "t" or '1'), the topic will be visible.
|
||||
* If the parameter is FALSE (NULL, or a string with any other value),
|
||||
* the topic will not be visible.
|
||||
*
|
||||
* If it can be determined at compile time whether the topic in question
|
||||
* is needed, #ifdef around those lines of the help is a better choice.
|
||||
*
|
||||
* If both $ and ? are used, ? comes first.
|
||||
*
|
||||
* Guidelines:
|
||||
* Help should be concise and easy to understand.
|
||||
*
|
||||
* The main topic should be short - less than a sceenful when presented with the
|
||||
* subtopic list.
|
||||
*
|
||||
* Keep line lengths to 76 columns or less.
|
||||
*
|
||||
* Follow the subtopic naming conventions (under development) for a consistent style:
|
||||
*
|
||||
* At the top level, the device should be summarized in a few sentences.
|
||||
* The subtopics for detail should be:
|
||||
* Hardware Description - The details of the hardware. Feeds & speeds are OK here.
|
||||
* Models - If the device was offered in distinct models, a subtopic for each.
|
||||
* Registers - Register descriptions
|
||||
*
|
||||
* Configuration - How to configure the device under SimH. SET commands.
|
||||
* Operating System - If the device needs special configuration for a particular
|
||||
* OS, a subtopic for each such OS goes here.
|
||||
* Files - If the device uses external files (tapes, cards, disks, configuration)
|
||||
* A subtopic for each here.
|
||||
* Examples - Provide usable examples for configuring complex devices.
|
||||
*
|
||||
* Operation - How to operate the device under SimH. Attach, runtime events
|
||||
* (e.g. how to load cards or mount a tape)
|
||||
*
|
||||
* Monitoring - How to obtain status (SHOW commands)
|
||||
*
|
||||
* Restrictions - If some aspects of the device aren't emulated, list them here.
|
||||
*
|
||||
* Debugging - Debugging information
|
||||
*
|
||||
* Related Devices - If devices are configured or used together, list the other devices here.
|
||||
* E.G. The DEC KMC/DUP are two hardware devices that are closely related;
|
||||
* The KMC controlls the DUP on behalf of the OS.
|
||||
*
|
||||
* This text can be created by any convenient means. It can be mechanically extracted from the device
|
||||
* source, read from a file, or simply entered as a string in the help routine. To facilitate the latter,
|
||||
* this file defines two convenience macros:
|
||||
*
|
||||
* L(text) - provides a string with a leading space and a trailing \n. Enter a line of topic text.
|
||||
* T(n, NAME) - provides a string with the topic level n and the topic name NAME, and a trailing \n.
|
||||
*
|
||||
* These are concatenated normally, e.g.
|
||||
const char *const help =
|
||||
L (The %D device is interesting)
|
||||
L (It has lots of help options)
|
||||
T (1, TOPIC 1)
|
||||
L (And this is topic 1)
|
||||
;
|
||||
*
|
||||
* API:
|
||||
* To make use of this type of help in your device, create (or replace) a help routine with one that
|
||||
* calls scp_help. Most of the arguments are the same as those of the device help routine.
|
||||
*
|
||||
* t_stat scp_help (FILE *st, struct sim_device *dptr,
|
||||
* struct sim_unit *uptr, int flag, const char *help, char *cptr, ...)
|
||||
*
|
||||
* If you need to pass the variable argument list from another routine, use:
|
||||
*
|
||||
* t_stat scp_vhelp (FILE *st, struct sim_device *dptr,
|
||||
* struct sim_unit *uptr, int flag, const char *help, char *cptr, va_list ap)
|
||||
*
|
||||
* To obtain the help from an external file (Note this reads the entire file into memory):
|
||||
* t_stat scp_helpFromFile (FILE *st, struct sim_device *dptr,
|
||||
* struct sim_unit *uptr, int flag, const char *helpfile, char *cptr, ...)
|
||||
* and for va_list:
|
||||
* t_stat scp_vhelpFromFile (FILE *st, struct sim_device *dptr,
|
||||
* struct sim_unit *uptr, int flag, const char *helpfile, char *cptr, va_list ap) {
|
||||
*
|
||||
* dptr and uptr are only used if the %D and/or %U escapes are encountered.
|
||||
* help is the help text; helpfile is the help file name.
|
||||
*
|
||||
* flag is usually the flag from the help command dispatch. SCP_HELP_FLAT is set in non-interactive
|
||||
* environments. When this flag, or DEV_FLATHELP in DEVICE.flags is set, the entire help text
|
||||
* will be flattened and displayed in outline form.
|
||||
*
|
||||
* Help files are easier to edit, but can become separated from the SimH executable. Finding them
|
||||
* at runtime can also be a challenge. SimH tries...but the project standard is to embed help
|
||||
* as strings in the device. (It may be easier to develop help as a file before converting it
|
||||
* to a string.)
|
||||
*
|
||||
* Lines beginning with ';' will be ignored.
|
||||
*
|
||||
* Here is a worked-out example:
|
||||
*
|
||||
;****************************************************************************
|
||||
The Whizbang 100 is a DMA line printer controller used on the Whizbang 1000
|
||||
and Gurgle 1200 processor familes of the Obsolete Hardware Corporation.
|
||||
1 Hardware Description
|
||||
The Whizbang 100 is specified to operate "any printer you and a friend can
|
||||
lift", and speeds up to 0.5 C.
|
||||
|
||||
The controller requires a refrigerator-sized box, consumes 5.5KW, and is
|
||||
liquid cooled. It uses GBL (Granite Baked Logic).
|
||||
|
||||
Painted a cool blue, it consistently won industrial design awards, even
|
||||
as mechanically, it was less than perfect. Plumbers had full employment.
|
||||
2 Models
|
||||
The Whizbang 100 model G was commissioned by a government agency, which
|
||||
insisted on dull gray paint, and speeds limited to 11 MPH.
|
||||
|
||||
The Whizbang 100 Model X is powered by the improbability drive, and is
|
||||
rarely seen once installed.
|
||||
2 $Registers
|
||||
The two main registers are the Print Control register and the Print Data
|
||||
register. The Print Maintenance register is usually broken.
|
||||
3 Print Control register
|
||||
Bit 0 turns the attached printer on when set, off when clear.
|
||||
Bit 1 ejects the current page
|
||||
Bit 2 ejects the operator
|
||||
Bit 3 enables interrupts
|
||||
3 Print data register
|
||||
The print data register is thiry-seven bits wide, and accepts data in
|
||||
elephantcode, the precursor to Unicode. Paper advance is accomplished
|
||||
with the Rocket Return and Page Trampoline characters.
|
||||
1 Configuration
|
||||
The Whizbang 100 requires 4 address slots on the LooneyBus.
|
||||
+ SET WHIZBANG LUNA 11
|
||||
will assign the controller to its default bus address.
|
||||
2 $Set commands
|
||||
The output codeset can be ASCII or elephantcode
|
||||
+ SET WHIZBANG CODESET ASCII
|
||||
+ SET WHIZBANG CODESET ELEPHANTCODE
|
||||
|
||||
The VFU (carriage control tape) is specifed with
|
||||
+ SET WHIZBANG TAPE vfufile
|
||||
2 WOS
|
||||
Under WOS, the device will only work at LooneyBus slot 9
|
||||
2 RTG
|
||||
The RTG driver has been lost. It is not known if the
|
||||
Whizbang will operate correctly.
|
||||
2 Files
|
||||
The VFU is programmed with an ASCII text file. Each line of the
|
||||
file corresponds to a line of the form. Enter the channel numbers
|
||||
as base 33 roman numerals.
|
||||
2 Examples
|
||||
TBS
|
||||
1 Operation
|
||||
Specify the host file to receive output using the
|
||||
+ATTACH WHIZBANG filespec
|
||||
command.
|
||||
1 Monitoring
|
||||
The Whizbang has no lights or switches. The model X may be located
|
||||
with the
|
||||
+SHOW WHIZBANG LOCATION
|
||||
simulator command.
|
||||
2 $Show commands
|
||||
1 Restrictions
|
||||
The emulator is limited to a single Whizbang controller.
|
||||
1 Debugging
|
||||
The only implemented debugging command is
|
||||
+ SET WHIZBANG DEBUG=PRAY
|
||||
To stop:
|
||||
+ SET WHIZBANG NODEBUG=PRAY
|
||||
1 Related Devices
|
||||
See also the Whizbang paper shredder (SHRED).
|
||||
*
|
||||
*/
|
||||
|
||||
#define T(level, text) #level " " #text "\n"
|
||||
#define L(text) " " #text "\n"
|
||||
|
||||
#endif
|
||||
Reference in New Issue
Block a user