root/src/simh/scp_help.h

/* */

   1 /*
   2  * scp_help.h: hierarchical help definitions
   3  *
   4  * vim: filetype=c:tabstop=4:ai:expandtab
   5  * SPDX-License-Identifier: X11
   6  * scspell-id: 9896d74a-f62a-11ec-9179-80ee73e9b8e7
   7  *
   8  * ---------------------------------------------------------------------------
   9  *
  10  * Copyright (c) 2013 Timothe Litt
  11  * Copyright (c) 2021-2022 The DPS8M Development Team
  12  *
  13  * Permission is hereby granted, free of charge, to any person obtaining a
  14  * copy of this software and associated documentation files (the "Software"),
  15  * to deal in the Software without restriction, including without limitation
  16  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  17  * and/or sell copies of the Software, and to permit persons to whom the
  18  * Software is furnished to do so, subject to the following conditions:
  19  *
  20  * The above copyright notice and this permission notice shall be included in
  21  * all copies or substantial portions of the Software.
  22  *
  23  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  24  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  25  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  26  * THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  27  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  28  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  29  *
  30  * Except as contained in this notice, the name of the author shall not be
  31  * used in advertising or otherwise to promote the sale, use or other dealings
  32  * in this Software without prior written authorization from the author.
  33  *
  34  * ---------------------------------------------------------------------------
  35  */
  36 
  37 #ifndef SCP_HELP_H_
  38 # define SCP_HELP_H_  0
  39 
  40 /* The structured help uses help text that defines a hierarchy of information
  41  * organized into topics and subtopics.
  42  *
  43  * The structure of the help text is:
  44  *
  45  * Lines beginning with whitespace are displayed as part of the current topic, except:
  46  *   * The leading white space is replaced by a standard indentation of 4 spaces.
  47  *     Additional indentation, where appropriate, can be obtained with '+', 4 spaces each.
  48  *
  49  *   * The following % escapes are recognized:
  50  *     * %D    - Inserts the name of the device     (e.g. "DSK").
  51  *     * %U    - Inserts the name of the unit       (e.g. "DSK0").
  52  *     * %S    - Inserts the current simulator name (e.g. "DPS-8/M")
  53  *     * %#s   - Inserts the string supplied in the "#"th optional argument to the help
  54  *               routine.  # starts with 1.  Any embedded newlines will cause following
  55  *               text to be indented.
  56  *     * %#H   - Appends the #th optional argument to the help text.  Use to add common
  57  *               help to device specific help.  The text is placed AFTER the current help
  58  *               string, and after any previous %H inclusions.  Parameter numbers restart
  59  *               with the new string, following the last parameter used by the previous tree.
  60  *     * %%    - Inserts a literal %.
  61  *     * %+    - Inserts a literal +.
  62  *      - Any other escape is reserved and will cause an exception.  However, the goal
  63  *        is to provide help, not a general formatting facility.  Use sprintf to a
  64  *        local buffer, and pass that as a string if more general formatting is required.
  65  *
  66  * Lines beginning with a number introduce a subtopic of the device.  The number indicates
  67  * the subtopic's place in the help hierarchy.  Topics offered as Additional Information
  68  * under the device's main topic are at level 1.  Their sub-topics are at level 2, and
  69  * so on.  Following the number is a string that names the sub-topic.  This is displayed,
  70  * and what the user types to access the information.  Whitespace in the topic name is
  71  * typed as an underscore (_).  Topic names beginning with '$' invoke other kinds of help,
  72  * These are:
  73  *    $Registers     - Displays the device register help
  74  *    $Set commands  - Displays the standard SET command help.
  75  *    $Show commands - Displays the standard SHOW command help.
  76  *
  77  * For these special topics, any text that you provide will be added after
  78  * the output from the system routines.  This allows you to add more information, or
  79  * an introduction to subtopics with more detail.
  80  *
  81  * Topic names that begin with '?' are conditional topics.
  82  * Some devices adopt radically different personalities at runtime,
  83  * e.g. when attached to a processor with different bus.
  84  * In rare cases, it's better not to include help that doesn't apply.
  85  * For these cases, ?#, where # is a 1-based parameter number, can be used
  86  * to selectively include a topic.  If the specified parameter is TRUE
  87  * (a string with the value "T", "t" or '1'), the topic will be visible.
  88  * If the parameter is FALSE (NULL, or a string with any other value),
  89  * the topic will not be visible.
  90  *
  91  * If both $ and ? are used, ? comes first.
  92  *
  93  * Guidelines:
  94  *   Help should be concise and easy to understand.
  95  *
  96  *   The main topic should be short - less than a sceenful when presented with the
  97  *   subtopic list.
  98  *
  99  *   Keep line lengths to 76 columns or less.
 100  *
 101  *   Follow the subtopic naming conventions (under development) for a consistent style:
 102  *
 103  *   At the top level, the device should be summarized in a few sentences.
 104  *   The subtopics for detail should be:
 105  *     Hardware Description - The details of the hardware.  Feeds & speeds are OK here.
 106  *          Models          -   If the device was offered in distinct models, a subtopic for each.
 107  *          Registers       -   Register descriptions
 108  *
 109  *     Configuration         - How to configure the device under SimH.  SET commands.
 110  *          Operating System -   If the device needs special configuration for a particular
 111  *                               OS, a subtopic for each such OS goes here.
 112  *          Files            - If the device uses external files (tapes, cards, disks, configuration)
 113  *                             A subtopic for each here.
 114  *          Examples         - Provide usable examples for configuring complex devices.
 115  *
 116  *     Operation             - How to operate the device under SimH.  Attach, runtime events
 117  *                             (e.g. how to load cards or mount a tape)
 118  *
 119  *     Monitoring            - How to obtain status (SHOW commands)
 120  *
 121  *     Restrictions          - If some aspects of the device aren't emulated, list them here.
 122  *
 123  *     Debugging             - Debugging information
 124  *
 125  *     Related Devices       - If devices are configured or used together, list the other devices here.
 126  *                             E.G. The DEC KMC/DUP are two hardware devices that are closely related;
 127  *                             The KMC controlls the DUP on behalf of the OS.
 128  *
 129  * API:
 130  *  To make use of this type of help in your device, create (or replace) a help routine with one that
 131  *   calls scp_help.  Most of the arguments are the same as those of the device help routine.
 132  *
 133  *  t_stat scp_help (FILE *st, DEVICE *dptr,
 134  *                   UNIT *uptr, int flag, const char *help, char *cptr, ...)
 135  *
 136  *  If you need to pass the variable argument list from another routine, use:
 137  *
 138  *  t_stat scp_vhelp (FILE *st, DEVICE *dptr,
 139  *                    UNIT *uptr, int flag, const char *help, char *cptr, va_list ap)
 140  */
 141 
 142 # define T(level, text) #level " " #text "\n"
 143 # define L(text) " " #text "\n"
 144 
 145 #endif

/* */