  Menus which are generated from a file (as opposed to those generated by
  viewing a listed directory) consist of menu entries and commands.

  A menu entry is a pair of lines which specify the title of the entry, its
  keypress, its type, and its action. Commands modify these entries as well as
  altering which parts of the menu actually get processed.

  Blank lines in a menu file are ignored, as are lines starting with #.

Message:

Subject: 10.1 Menu Entries

  Menu entries take the following form:

   title
key type file

  where title is the text that will be displayed in the menu, which may
  include spaces and attributes, and file is the filename of the entry. key is
  the keypress associated with the entry (which may be a case insensitive
  letter, a number, or an unused punctuation character), and type is the type
  of the entry, which may be one of the following:

  CCACA   Animation - run via the QManim interpreter, not included with this
      package. QManim was written by Richard Boulton <rjb37@cam.ac.uk>, and is
      available on Monochrome BBS (telnet to mono.org) at CC<RGRINM>CA from the
      main menu.

      Note that animations must be world-readable and reside in a
      world-executable directory, since group permissions are dropped before
      the animation is run. Also note that the filename of an animation is
      restricted; only 0-9, A-Z, a-z, +, -, . and _ are allowed in any of the
      path.

  CCBCA   Binary - cannot be viewed directly.

  CCCCA   Comment File - suitable for adding comments to. May be edited directly
      with an editor.

  CCLCA   Listed Directory - generate a menu from the contents of the specified
      directory. See section 10.4 Listed Directories.

  CCMCA   Menu File - generate a menu from the contents of the menu file.

  CCRCA   Read-only File - Not suitable for adding comments to.

  CCSCA   Spooled Output - run a subprocess, spooling the output to a temporary
      file. When complete, display this temporary file as per normal. A
      timeout may be specified by suffixing a suitable number of seconds after
      the S - this will cause the process to terminate after that length of
      time. Environment variables in the path or options will be suitably
      expanded; See section 10.3 Menu Environment.

      If, instead of a number, the S is suffixed by an exclamation mark (!),
      the menu will be reloaded after the file has been viewed. This allows
      the use of scripts which modify the menu, or files that the menu depends
      on, when run.

      Note that inside CCmbbsCA non-admin users cannot put arbitrary commands into
      S constructs. If they do, only they will be able to run them; other
      people will only be able to execute file if it is listed in the special
      "paths" file owned by the admin. See section 5.3 MBBS Configuration.

  CCTCA   Telnet Connection - connect to the machine file using Telnet.

  CCXCA   Executable - run a subprocess file. Output is discarded after being
      written to the standard output.

      If the X is suffixed with an ampersand (&), the subprocess is run in the
      background; if it is suffixed with an exclamation mark (!), the menu
      will be reloaded on completion, as with the spooled output type S.

      Environment variables will be expanded as with type S, and the same
      caveat about arbitrary commands applies.

  For examples, look at the menus supplied with this package in the CCextraCA
  directory.

  Note that when using the BBS system CCmbbsCA, users may only write menu code
  which links to files that they own. If they wish to link to another user's
  files, special provision must be made. See section 5.4 ACLs.

Message:

Subject: 10.2 Menu Commands

  Lines beginning with a "." in a menu file will be interpreted as commands.
  Commands are not case sensitive and may be abbreviated to as few characters
  as necessary to be distinctive, but here they are capitalised and written
  out in full for readability.

  In the following descriptions, square brackets, [ ], are used to denote
  optional items, whereas angle brackets, < >, are used to denote items that
  should be replaced with real values. The pipe symbol, |, is used to denote a
  choice between items, of which only one should be used, whereas an ellipsis,
  ..., signifies that further items may be added to form a list.

  Note that this documentation is based on, and indeed copies chunks out of,
  amf's Monochrome documentation which can be found on Monochrome BBS at the
  keypath <EYS> from the main menu.

10.2.1 .COMMENTFILE

  aSyntax:

   .COMMENTFILE <file> [IF ...]

  Associate the commentfile <file> with the next entry in the menu. The
  CC.COMMENTFILECA construct allows an entry to use two files - one which will be
  displayed, and another to which edits added to the entry will be appended.
  This is useful when you want users to be able to add to a file without them
  seeing what other users have added.

10.2.2 .HEIGHT

  aSyntax:

   HEIGHT <lines> [IF ...]

  Allocate <lines> of the display to the menu's title. This is ignored, but
  retained for compatibility with Monochrome.

10.2.3 .IF

  aSyntax:

   .IF [NOT] <condition> [&& ... | || ...]
.ELSE
.ENDIF

  Execute the following commands only if the test after the CC.IFCA is true. If
  the test is false, and an CC.ELSECA is given, execute the commands following the
  CC.ELSECA instead.

  Note that CC.IFCAs can be arbitrarily nested.

  The test is composed of one or more conditions, which should be joined by
  either CC&&CA or CC||CA, acting as Boolean AND and OR operators respectively. Both
  operators have equal priority, and will be grouped from right to left.

  A condition may be prefixed with CCNOTCA to negate the result it returns.

  <condition> may be one of the following:

  CCACLOKCA CC<CCfileCC>CA    Returns true if <file> exists and linking to it would be
                  allowed by the ACL mechanism. See section 5.4 ACLs.

  CCENVIRONMENTCA CC<CCnameCC>CA CC<CCvalueCC>CA CC[...]CA        Returns true if the contents of the
                                          environment variable <name> are
                                          equal to <value>. More than one
                                          name/value pair may be specified per
                                          line, in which case, the condition
                                          will return true if one or more of
                                          them match. A value of * will match
                                          anything. See section 10.3 Menu
                                          Environment.

  CCEXISTSCA CC<CCfileCC>CA   Returns true if <file> exists.

  CCEXTERNALCA        Returns true if the user is an external or a guest.

  CCGUESTCA     Returns true if the user is a guest. See CCEXTERNALCA.

  CCHOSTNAMECA CC<CChostCC>CA CC[...]CA       Returns true if the client is running on the
                              machine <host>. This value must be specified
                              exactly, and will only match if it is the
                              canonical name of the machine. More than one
                              value may be specified per line. A value of *
                              will match anything.

  CCLOCATIONCA CC<CChostCC>CA CC[...]CA       Returns true if the user's location is <host>.
                              This value must be specified exactly, and will
                              only match if it is the same as that which would
                              be displayed when examining the user. More than
                              one value may be specified per line. A value of
                              * will match anything.

  CCSITECA CC<CCaddressCC>CA CC[...]CA        Returns true if the user's email address stub is
                              within <address>. This will match substrings, so
                              long as they contain the last character of the
                              address - thus cam.ac.uk will be matched by
                              ac.uk and uk. More than one value may be
                              specified per line.

  CCTERMINALCA CC<CCtypeCC>CA CC[...]CA       Returns true if the user's terminal type matches
                              <type>. More than one value may be specified per
                              line. A value of * will match anything.

  CCTTYCA CC<CCttyCC>CA CC[...]CA       Returns true if the user's tty matches <tty>, being of
                        the form ttyp7. More than one value may be specified
                        per line. A value of * will match anything.

  CCUSERCA CC<CCuserCC>CA CC[...]CA     Returns true if the user's account name matches <user>.
                        More than one value may be specified per line; a value
                        of * will match anything.

                        If <user> has a trailing slash it is treated as a
                        userlist file, or group (in CCmbbsCA only). Groups of the
                        form CCfoo/CA refer to the system group file CCfooCA, whereas
                        groups of the form CCfoo/bar/CA refer to the user CCfooCA's "CCbarCA"
                        group.

10.2.4 .LINE

  aSyntax:

   .LINE [<text>]

  Use the <text> provided to fill a line of the display.

  Note that if attributes are used in <text>, the whole line will not be
  filled. Also note that <text> must be at least two characters long for
  anything other than a blank line to be displayed.

10.2.5 .LOG

  aSyntax:

   .[NOW|SUBSEQUENT] LOG <option> <file> [IF ...]
.LOG CLEAR

  Associate a log file with the next menu entry, with the current menu if the
  CCNOWCA option is given, or with all subsequent menu entries in this menu if the
  CCSUBSEQUENTCA option is given. When triggered, a line will be added to the log
  file, containing the date, time and the username of the user who triggered
  it, together with additional information depending on the value of <option>,
  which may be as follows:

  CCTITLECA     Log the title of the entry which triggered the log file. This is
            useful when multiple entries are logged to a single log file, in
            order to distinguish which accesses are for which entries.

  CCUSERCA      Log the nameline of the user.

  CC.LOGCA CCCLEARCA will clear any log files associated with the next menu entry.

10.2.6 .OPTIONS

  aSyntax:

   .OPTIONS <lines> [IF ...]

  Allocate <lines> of the display to the menu options, displaying only this
  number of options at once.

  This command is ignored, but retained for compatibility with Monochrome.

10.2.7 .PATHNAME

  aSyntax:

   .PATHNAME <path> [IF ...]
.PATHNAME

  By default, filenames that are not absolutely specified will be searched for
  in the directory containing the menu from which they were referenced. The
  CC.PATHNAMECA construct allows this default to be changed to the specified <path>,
  which is useful should you wish to reference a number of files in a
  different directory, without having to specify each one absolutely.

  If a path is not specified, CC.PATHNAMECA will restore the path back to the
  default for that menu.

10.2.8 .QUIT

  aSyntax:

   .QUIT [IF ...]

  Stop processing the menu at the current line.

  Note that if no earlier commands have been processed before a CC.QUITCA, and
  there are no earlier entries in the menu, the user will be returned to the
  parent menu.

10.2.9 .SETENV

  aSyntax:

   .SETENV <var>=<value>

  Set an environment variable to be passed to the next executable menu entry.
  The environment variable <var> will be set to the value <value>. Note that
  the environment of CCmbbsCA is not modified - only the environment of the next
  executable menu entry.

  This command is ignored in version 1.2.7.

10.2.10 .STATUS

  aSyntax:

   .[NOW|SUBSEQUENT] STATUS [NOT] <option> [...] [IF ...]

  Alter the status of the next menu entry, the current menu if the CCNOWCA option
  is given, or all subsequent menu entries in this menu if the CCSUBSEQUENTCA
  option is given. More than one <option> may be given on each line, and these
  may be negated by means of the CCNOTCA options.

  <option> may take the following values:

  CCADDCA       Permit the user to add comments to the file with [BAb].

  CCANONYMOUSCA       Prevent the display of the author of each comment in the
                  CCaFrom:CA line (see section 2.2.2 CCFromCA line), and the logging
                  of comment added to the Add Log.

  CCBARDELETECA       Prevent the user from deleting comments from the file with [B.b][BDb].

  CCBARINFOCA   Prevent the user from generating an index of the file with [BIb]. In
            listed directories, prevents filenames being "prettified" and thus
            causes filenames to be displayed as they really are.

  CCBARLOGCA    Prevent the menu entry from being logged in any of the system
            logs.

  CCBARMAILCA   Prevent the user from mailing the file with [BMb].

  CCBARSENDREPLYCA    Prevent the user from sending a reply to an edit in the
                  file.

  CCCLEARCA     Clear all previously set status values set for this entry.

  CCDELETECA    Permit the user to delete any comment from the file with [B.b][BDb].

  CCEDITCA      Permit the user to edit the entire file in the editor with [B.b][BAb].

  CCHIDETITLECA       Stop the title of the menu entry being displayed in a user's
                  current action and from being logged in any of the system
                  log files.

  CCLOWPRIORITYCA     Cause the entry to be scanned only on the second scan. This
                  is ignored, but retained for compatibility with Monochrome.

  CCNOINDEXCA   Prevent the entry from being recursively indexed, only displaying
            the top level entry. This is ignored in version 1.2.7.

  CCNOLASTCA    Prevent last access information being stored for the entry.

  CCNOSCANCA    Cause the entry to be ignored on scanning.

  CCNOTIMECA    Prevent the last modification time of the entry from being
            displayed in the menu.

  CCREADONLYCA        Prevent the user from altering the file in any way.

  CCXRATEDCA    Mark the entry as being X-rated, which displays an X next to the
            entry in the menu, prevents guests from entering it, and displays
            a warning on entry.

10.2.11 .TEXT

  aSyntax:

   .TEXT [<text>]

  Display the <text> centred. Environment variables are expanded.

10.2.12 .TITLE

  aSyntax:

   .TITLE <option> <file> [IF ...]

  Display the title file <file> at the top of the menu, formatted in a manner
  depending on <option>, which can be one of the following:

  CCCENTRECA    Centre the title file.

  CCLEFTCA      Left justify the title file.

  In titles, lines beginning with a # will be treated as comments, and not
  displayed. Prefix such lines with a null attribute (eg: ^[a) should you wish
  them to be displayed as part of the title.

10.2.13 .VIEW

  aSyntax:

   .[NOW] VIEW <file> [IF ...]

  Associate a view file with the next entry, or with the current menu if the
  CCNOWCA option is given. A view file can be thought of as a local Message of the
  Day, and will displayed on entry to the file or menu if it has been modified
  since the user last saw it.

  If the user presses [BQb] when reading the viewfile, they will not proceed to
  the menu entry itself.

10.2.14 .VIEWALWAYS

  aSyntax:

   .[NOW] VIEWALWAYS <file> [IF ...]

  Associate a view file with the next entry, or with the current menu if the
  CCNOWCA option is given, as per CC.VIEWCA (see section 10.2.13 .VIEW), but display
  it every time the user enters the file or menu, regardless as to whether it
  has been updated.

Message:

Subject: 10.3 Menu Environment

  Environment variables may be referenced from a menu file by writing them as
  you would in the shell; i.e. if you want the value of environment variable
  FOO substituted somewhere, write CC$CCFOOCA.

  If a variable cannot be found in the environment, the string will be left as
  it is.

  The following environment variables are guaranteed to be set when a menu is
  being processed:

  CCACCOUNTCA
  CCMONO_ACCOUNTCA    The account name of the current user. The second name is
                  kept for compatibility with Monochrome BBS.

  CCNAMELINECA        The current nameline of the current user, or a blank string
                  if none has been set.

  CCKEYPATHCA
  CCMONO_KEYPATHCA    The keypath of the current menu (Bnotb of the current menu
                  entry). This will be a blank string unless the menu is being
                  viewed through CCmbbsCA. Once again, the second name is for
                  compatibility with Monochrome BBS.

  When a user executes a Spooling menu entry - type S (see section 10.1 Menu
  Entries) - the following will be put into the environment of the command:

  CCSPOOL_FILECA      The filename of the file to which output is being
                  redirected. If your program puts part of itself in the
                  background then terminates to allow the user to read the
                  output, the background job can check for the existence of
                  this file. When it has been removed, the user has stopped
                  reading the file and you should terminate your job.

                  For an example of this, look in the CCextra/utilsCA directory
                  which came with this package.

Message:

Subject: 10.4 Listed Directories

  If you specify a menu entry of type L (see section 10.1 Menu Entries), then
  the directory you gave as a filename will be read and a submenu generated
  from its contents. The following suffixes may be given to files to change
  how they appear:

  CC~CA   Files with this extension are omitted from directory listings, as are
      "hidden" files (beginning with a CC.CA).

  CC.aclCA      Treated as a comment file (type C). If you create a file of this
            type using [B.b][BAb] in a listed directory, it will be created
            group-readable but not group-writeable, for security. See section
            5.4 ACLs.

  CC.anCA       Treated as an animation (type A). Note that animations must be
            world-readable and reside in a world-executable directory, since
            group permissions are dropped before the animation is run. Also
            note that the filename of an animation is restricted; only 0-9,
            A-Z, a-z, +, -, . and _ are allowed in any of the path.

  CC.mnCA       Treated as a submenu file (type M). If you create a file of this
            type using [B.b][BAb] in a listed directory, it will be created
            group-readable but not group-writeable, for security.

  CC.cmCA       Treated as a comment file (type C). If it is group writable, the
            file will be addable to other users in CCmbbsCA.

  CC.cm.gzCA
  CC.roCA
  CC.ro.gzCA    Treated as a readonly comment file (type C).

  CC.txtCA
  CC.txt.gzCA   Treated as a formatted file (type F).

  CC.shCA
  CC.plCA
  CC.perlCA     Entered as an executable entry (type X).

  CC.sp.shCA
  CC.sp.plCA    Entered as a spooled executable entry (type S).

  CC.htmlCA
  CC.htmCA      Entered as an executable entry (type X), which when chosen will
            launch the web browser CClynxCA to point at the file.

  CC.scCA       Entered as an executable entry (type X), which when chosen will
            launch the spreadsheet calculator CCscCA on that file.

  Files with unknown extensions will be marked as type B (binary), and files
  with no extension will be marked as type F (formatted file).

  Subdirectories will be entered in the menu as type L submenus.

  For a full list of supported file extensions, look at the source file
  CCsrc/display/menu/listed.cCA. Suggestions for additions would be gratefully
  received - see 12. Reporting Bugs.

  Please note that setting the CC.STATUSCA CCBARINFOCA flag stops filenames being
  "munged" (prettified), which means that the original filenames are shown.
  This can be useful if you're just using a listed directory as an
  organisational tool rather than for general user-friendly use.

