This is doc/mconv.info, produced by makeinfo version 4.0b from
../doc/mconv.texi.

   This file documents the "mconv" package, version 1.2.7.

   Copyright 2003 Andrew Wood

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by Andrew Wood.

INFO-DIR-SECTION Miscellaneous
START-INFO-DIR-ENTRY
* Mconv: (mconv).      BBS, text converter and menu viewer
END-INFO-DIR-ENTRY


File: mconv.info,  Node: Top,  Next: Overview,  Up: (dir)

Mconv
*****

   The `mconv' package converts MCONV BBS files.  Specifically, it
allows conversion of text between ANSI colour, bold and so on to and
from MCONV's more compact attribute format as well as converting to
HTML.  It incorporates the programs `mconv' - the command-line
converter - and `mview' - a full-screen viewer for both files and menus.

   Also included is a fully functional BBS based on the `mview' code,
called `mbbs'.

   This edition of the `Mconv manual', last updated 5 August 2003,
documents `mconv' version 1.2.7.

* Menu:

* Overview::           Overview of the whole `mconv' package.
* Concepts::           Concepts behind text formatting and menu code.
* MCONV::              The conversion program, `mconv'.
* MVIEW::              The file and menu viewer, `mview'.
* MBBS::               The bulletin board client, `mbbs'.
* MGID::               A small utility for changing the GID of files.
* MTIME::              A small utility to write datestamps.
* MTRUNC::             A small utility for truncating log files.
* MTE::                The MCONV text editor.
* Menu Code::          Preparing and tailoring menus.
* Examples::           Example uses of `mconv' and `mview'.

* Reporting Bugs::     How to report a problem with the `mconv' package.

* Attribute List::     Colour and weight indicators.
* Menu Command List::  Commands to use in menu code.

* Concept Index::      Index of concepts.

 --- The Detailed Node Listing ---

Concepts behind text formatting and menu code

* Attribute codes::  Formatting commands to change the appearance of text.
* Special lines::    Certain lines in text files have special meanings.
* Menus::            What a menu is and how it is displayed.
* Last Access::      How `mview' knows which files you've visited.

The conversion program, `mconv'

* MCONV Overview::             What `mconv' does and why you'd want to.
* MCONV Invocation::           Options that `mconv' accepts.
* Converting to Plain Text::   Turning BBS format files to text.
* Converting to Colour Text::  Seeing BBS format files in colour.
* Converting to HTML::         Generating a web page from a BBS file.
* Converting the Other Way::   Converting scrollback buffers to flat files.
* A note on menus::            Remembering to use the `-m' switch.

The file and menu viewer, `mview'

* MVIEW Invocation::      Options that `mview' accepts.
* File Viewer::           Viewing a BBS format file.
* Last Access Database::  Keeping track of where you've been.
* Menu Viewer::           Viewing a BBS menu, and files within it.
* Scanning::              Finding any files updated since you last read them.

The BBS, `mbbs'

* MBBS Invocation::       How to run `mbbs' as a user.
* MBBS Administration::   Things that the sysop should know about.
* MBBS Configuration::    The configuration file.
* ACLs::                  Enforcing menu code security.
* User Messaging::        Sending messages between users.
* Privileges and Bans::   Dealing with abuses of the system.
* External Users::        Users without a shell account on the system.

Menu code documentation

* Menu Entries::          How a menu entry is defined.
* Menu Commands::         Altering entries and changing the menu properties.
* COMMENTFILE::           Associate a separate comment file with an entry.
* HEIGHT::                Ignored.
* IF::                    Conditional menu code.
* LINE::                  Fill a line with text.
* LOG::                   Log accesses to a file.
* OPTIONS::               Ignored.
* PATHNAME::              Set the path prefixing all subsequent filenames.
* QUIT::                  Stop processing the menu immediately.
* SETENV::                Ignored.
* STATUS::                Set the status of this or subsequent entries.
* TEXT::                  Centre a line of text.
* TITLE::                 Give the current menu a title.
* VIEW::                  Associate a viewfile with an entry.
* VIEWALWAYS::            Associate a compulsory viewfile with an entry.
* Menu Environment::      Environment variables available to menu code.
* Listed Directories::    Menus generated from directory contents.

Examples

* Session Log Example::    Log a TELNET session and view it later.
* HTMLification Example::  Make a BBS section into web pages.
* Offline Diary Example::  Keep your diary offline and upload the changes.
* General Example::        Non-BBS example of the uses of menu code.


File: mconv.info,  Node: Overview,  Next: Concepts,  Prev: Top,  Up: Top

Overview
********

   This is the documentation for the `mconv' package, a BBS with
several bundled utilities.  The program `mconv' converts files between
BBS file and menu formats and plain text, ANSI colour text, and HTML.
A text editor, `mte', and a standalone file/menu viewer called `mview'
are also included.  The BBS itself is the program `mbbs'.

   Originally, this package was written to manipulate files used in
Monochrome BBS, a "multi-user conferencing and messaging system" written
by David Brownlee (http://www.mono.org/abs). However it has since grown
into a BBS codebase in its own right.

   Files viewed with `mbbs' can contain attributes such as colour or
bold, as well as special entities like datestamps and subject lines.
It can be handy to view and manipulate this type of file outside the
system.  Example applications include:

   * Keeping your Mono diary offline

   * Doing your scan quickly, dumping to a log to view later

   * Converting the files in your section to HTML

   * Organising projects on your home system

   * Building a BBS

   These are just suggestions.  Since `mconv' can convert from ANSI
colour text to `mbbs' attribute files, from `mbbs' attribute files to
plain text, ANSI colour text, and HTML, and from `mbbs' menu files to
text or HTML, and `mview' provides a full-screen menu and file viewing
interface without the additional material of a BBS behind it, the
package should be flexible enough for you to think of more applications.

   Please see `http://mconv.sourceforge.net/' - the `mconv' package
home page - for more information.


File: mconv.info,  Node: Concepts,  Next: MCONV,  Prev: Overview,  Up: Top

Concepts
********

   The `mconv' package deals with `mbbs' files in two forms - normal
files and menu files.

   Normal files describe text to be displayed.  They contain only text,
attribute codes, datestamps and other special lines.  Menu files, on
the other hand, describe a menu which can contain text, menu options,
submenus, and so on.  They may therefore contain text, attributes, and
menu code.

   These different kinds of "special" data are described below.

* Menu:

* Attribute codes::  Formatting commands to change the appearance of text.
* Special lines::    Certain lines in text files have special meanings.
* Menus::            What a menu is and how it is displayed.
* Last Access::      How `mview' and `mbbs' know which files you've visited.


File: mconv.info,  Node: Attribute codes,  Next: Special lines,  Up: Concepts

Attribute codes
===============

   Any text in any file may be highlighted in bold or reverse,
underlined, or given a different colour.  To do this, character
sequences called _attribute codes_ are used.

   An attribute code is an escape character (typically `^[' or `^]')
followed by another character signifying the attribute to be used.  In
general, an uppercase second character turns an attribute _on_, and a
lowercase character turns it _off_.  The exception to this rule is the
colour attribute code, which is always uppercase `C'.

   Attributes are automatically turned off at the end of each line, but
it is good practice to turn them off explicitly anyway.

   For example, the following can be used to highlight some text:

     This is some ^]Bbold text^]b.

   This would be displayed as follows:

     This is some *bold text*.

   Full details of attribute codes are given later in this manual.
*Note Attribute List::.


File: mconv.info,  Node: Special lines,  Next: Menus,  Prev: Attribute codes,  Up: Concepts

Special lines
=============

   Within text files, lines beginning in certain ways have special
meanings.  They are used to define datestamps (marking when entries
were written, or simply dividing files into pieces), entry authors,
subject headings, or message recipients.

* Menu:

* Message line::  Mark the start of an entry, optionally giving its date.
* From line::     Specify the author of an entry.
* Subject line::  Optionally specify a subject heading for an entry.
* To line::       Optionally specify the intended recipient(s) of a message.


File: mconv.info,  Node: Message line,  Next: From line,  Up: Special lines

`Message' line
--------------

   Any line in a file which begins with the word "Message", followed by
a colon (":"), will be expanded into a separator.  If an 8-digit
hexadecimal number follows, this separator will be a datestamp.

   For instance:

     Message: 36A3B6B4             (Mon Jan 18 22:33:24 1999)
     foo
     Message:

   ...is turned, by `mconv' and `mview', into:

     ----------------------------[Mon Jan 18 22:33:24 1999]--
     foo
     --------------------------------------------------------

   Note how any text after the 8-digit number is simply ignored.  This
number, incidentally, is simply the number of seconds since 1 January
1970, or the "Epoch"; it can be obtained by the C function `time()' or
by the GNU `date' program with `date +%s'.  You will then have to
convert this number to hexadecimal.

   These separators are useful for marking divisions between entries in
files; for instance, in a discussion file, they record where a new
addition begins, and can also record the time it was added.

   A handy Unix command line utility for generating `Message:' lines for
any given date is `mtime'.  *Note MTIME::.

   Given a date as a parameter, `mtime' will produce a datestamp line
for that date; given no parameter, it produces a datestamp line for the
current date.  Invalid dates produce blank separators.

   Adding entries to files with the <A> key, in `mview' (*note
MVIEW::), automatically prefixes your text with a datestamp.


File: mconv.info,  Node: From line,  Next: Subject line,  Prev: Message line,  Up: Special lines

`From' line
-----------

   Lines beginning with `From:' mark the author of an entry in a file,
and should go just after a datestamp line (*note Message line::).

   The text `From:' (including the colon and a trailing space) should be
followed by descriptive text known as the _nameline_ - usually the
author's real name - and ends with their username in brackets.

   This information is used to determine who wrote an entry, and the
username is also used when indexing files with the <I> key in `mview'.

   If a file is marked as "anonymous", then when it is viewed the
username is automatically stripped so that the viewer cannot see who
wrote the entry.  Note that the nameline is still visible, so it should
be left blank in anonymous files if you wish to remain anonymous.

   When being viewed, all text after the word `From:' is shown in bold
green to distinguish it from the body of the message.

   `From:' lines are automatically added just after the datestamp when
adding an entry with the <A> key in `mview'.


File: mconv.info,  Node: Subject line,  Next: To line,  Prev: From line,  Up: Special lines

`Subject' line
--------------

   Any text following a line beginning with `Subject:' will be
highlighted in underlined cyan automatically, to distinguish it from
the body of the message.  Thus there is no need to add attributes
(*note Attribute codes::) to outline your headings.


File: mconv.info,  Node: To line,  Prev: Subject line,  Up: Special lines

`To' line
---------

   Lines beginning with `To:' mark a list of recipients for a message,
and should normally go on the line after a `From:' line (*note From
line::).  The word `To:' should be followed by one or more bracketed
usernames, which will be shown in green.


File: mconv.info,  Node: Menus,  Next: Last Access,  Prev: Special lines,  Up: Concepts

Menus
=====

   Menus are generated from text files which contain menu commands and
entry specifiers.

   The entry specifiers say what a menu entry's name is, its keypress,
and what action to take when it is selected; the menu commands
determine which parts of the menu are visible to which users, and what
permissions those users will have in terms of modifying files.

   A menu command is indicated by prefixing it with a dot (`.').  More
specific information about menu code is given later in this manual.
*Note Menu Code::.


File: mconv.info,  Node: Last Access,  Prev: Menus,  Up: Concepts

Last Access
===========

   When using the file viewer `mview' and the BBS system `mbbs', it is
possible to record the position you were last at when reading files, so
that at any time you may quit and come back later exactly where you
left off.

   This "bookmarking" of your position is done automatically, provided
your last access database has been set up properly (*note Last Access
Database::).  Your last access database, or LDB, also stores
information about subscription to menus and files (*note Scanning::).

   If you are a user of the `mbbs' BBS system, then you shouldn't have
to worry about setting up your LDB; you just need to know it exists,
and the BBS administrator should have sorted everything else out.


File: mconv.info,  Node: MCONV,  Next: MVIEW,  Prev: Concepts,  Up: Top

MCONV
*****

   The `mconv' program allows conversion between `mbbs' attributes and
other formats, and also includes the facility to turn scrollback buffers
into `mbbs' type files for later viewing with `mview' or `mbbs'.

* Menu:

* MCONV Overview::             What `mconv' does and why you'd want to.
* MCONV Invocation::           Options that `mconv' accepts.
* Converting to Plain Text::   Turning BBS format files to text.
* Converting to Colour Text::  Seeing BBS format files in colour.
* Converting to HTML::         Generating a web page from a BBS file.
* Converting the Other Way::   Converting scrollback buffers to flat files.
* A note on menus::            Remembering to use the `-m' switch.


File: mconv.info,  Node: MCONV Overview,  Next: MCONV Invocation,  Up: MCONV

MCONV Overview
==============

   The `mconv' program is a tool to convert both normal files and menu
code on the standard input to either ANSI colour text, plain text, or
HTML on the standard output.

   Also, conversion from `ANSI' colour text to `mbbs' format text
(*note Converting the Other Way::) can be done - the reverse of the
above - allowing session logs and scrollback buffers to be viewed with
`mview'.

   Converting to ANSI colour text (*note Converting to Colour Text::)
is perhaps the least useful, given that it can be done interactively
with the `mview' program.

   Converting to plain text simply expands all special tags and then
removes formatting instructions (like bold, colour etc).  Thus it can
be handy if you want to convert a file to a plain email.  *Note
Converting to Plain Text::.

   Finally, conversion to HTML allows the creation of web pages from
`mbbs' files, especially in conjunction with the experimental Perl
script supplied with this package in the `extra/' directory.  *Note
Converting to HTML::.


File: mconv.info,  Node: MCONV Invocation,  Next: Converting to Plain Text,  Prev: MCONV Overview,  Up: MCONV

MCONV Invocation
================

   The general form for invocation is as follows:

     mconv [OPTIONS] [FILE]...

   This will concatenate all FILEs given, parse `mbbs' attribute codes,
and give the result on the standard output.  If no files are specified,
or a file called `-' is specified, the standard input is read.

   The following options determine the way input data is processed:

`-f'
`--file-input'
     This is the default operation - each input file is assumed to be a
     normal `mbbs' file, containing `mbbs' attribute codes (*note
     Attribute codes::), datestamps (*note Special lines::), and so on.

     The `-h', `-t', and `-c' options determine whether the output is
     to be HTML, plain text, or the default of coloured text.  `-y' and
     `-w' also modify the output.

`-m'
`--menu-input'
     Each input file is assumed to contain `mbbs' menu code.  The `-h',
     `-t', and `-c' options determine whether the output is to be HTML,
     plain text, or the default of coloured text.  If the output is
     HTML, each menu item is a link to the relevant file, with `.html'
     appended to the filename.

     The `-g' and `-w' options also modify the output, and `-d' and
     `-n' specify whether to read an LDB file to show subscription and
     last access information in the output (*note Last Access::).

`-i'
`--menu-info'
     Each input file is assumed to contain `mbbs' menu code.  On
     standard output, information about each menu - title, logfiles,
     entries and so on - is given.  No conversion of attribute
     characters is done; the `-h', `-t', and `-c' options are ignored.

     This is primarily intended for use by other programs and/or by
     shell scripts.

`-a'
`--ansi-input'
     The input is assumed to be normal text containing ANSI colour
     codes and other escape sequences.  It is always converted into
     normal `mbbs' attribute format; the only other options which have
     any effect when used with `-a' are the `-w' and `-H' options,
     which determine the size of the original terminal (which produced
     the incoming ANSI text), for the purpose of working out which
     lines are datestamps, handling scrolling, and so on.

     This option is useful for converting  session  logs to viewable
     files; for instance, turning a screenlog file created by `screen'
     into something to be viewed by `mview'.  *Note Converting the
     Other Way::.

   The next few options determine the output format.

`-h'
`--html-output'
     (`-f' and `-m' only)

     When processing files and menus, output HTML.  The resultant HTML
     will be surrounded by a `<PRE>' tag, thus preserving the
     formatting.

     Menu code will have links put to each menu item, as described
     above in the description of the `-m' option.

`-t'
`--text-output'
`--no-colour'
     (`-f' and `-m' only)

     Menus and files are output as plain text only, with no colour
     codes.

`-c'
`--colour-output'
     (`-f' and `-m' only)

     Menus and files are output as files containing ANSI colour codes.
     This is the default output format for `-f' and `-m' processing.

   These options slightly modify the behaviour of the input parser:

`-y'
`--anonymous'
     (`-f' only)

     Strip the account names from `From:' lines.  *Note From line::.

`-g'
`--guest'
     (`-m' and `-i' only)

     Output the menu as a guest user would see it.

`-d FILE'
`--ldb=FILE'
     (`-m' only)

     Read last-access information from FILE.  This overrides any file
     specified by the environment variables `MCONV_LDB' or `MVIEW_LDB'.

`-n'
`--no-ldb'
     (`-m' only)

     Do not use any last-access information at all; mark all menu
     entries as up to date and subscribed to.

`-u'
`--unbuffered'
     (standard input only)

     Do not line buffer standard input, and do not buffer output.
     Useful if `mconv' is being used to prettify the output of an
     interactive script.

`-w NUM'
`--width=NUM'
     For file and menu input (`-f' and `-m'), change the number of
     columns in the output from the default of 80 to NUM.  For ANSI
     colour text input (`-a'), change the number of columns that the
     input text is assumed to have from the default of 80 (or the value
     of the environment variable `COLUMNS') to NUM.

`-H NUM'
`--height=NUM'
     For ANSI colour text input only (`-a'), change the number of rows
     that the input text is assumed to have from the default of 25 (or
     the value of the environment variable `LINES') to NUM.

   The last two options give information about the program.

`--help'
     Print a usage message on standard output and exit successfully.

`-V'
`--version'
     Print version information on standard output and exit successfully.

   Finally, it should be noted that the environment variables
`MCONV_USER' or `MVIEW_USER' (if both are set, `MCONV_USER' takes
precedence) can be used to override the user that the menu code "sees".
However these variables are ignored if the `-g' option is passed.


File: mconv.info,  Node: Converting to Plain Text,  Next: Converting to Colour Text,  Prev: MCONV Invocation,  Up: MCONV

Converting to Plain Text
========================

   To convert from `mbbs' format to plain text, run a command like the
following:

     mconv -t < input.cm > output.txt

   This will convert `input.cm' to `output.txt'.  Attributes (*note
Attribute codes::) will be stripped and special lines (*note Special
lines::) expanded.

   If you wish to make the file anonymous (i.e. strip usernames from
`From:' lines), then use the `-y' switch:

     mconv -y -t < input.cm > output.txt

   The final change which may be made is to change the output width.
The default action is to assume that the output is to be no more than
80 columns wide.  This can be set with the `-w' option.  For instance,
to convert a file to 132 column text:

     mconv -w 132 -t < input.cm > output.txt

   The two options `-y' and `-w' apply to coloured output and HTML
output as well.


File: mconv.info,  Node: Converting to Colour Text,  Next: Converting to HTML,  Prev: Converting to Plain Text,  Up: MCONV

Converting to Colour Text
=========================

   This is the default operation if no switches or options are given.
As with conversion to plain text (*note Converting to Plain Text::),
the optional arguments `-y' and `-w' may be given to set anonymity or
change the output width respectively.


File: mconv.info,  Node: Converting to HTML,  Next: Converting the Other Way,  Prev: Converting to Colour Text,  Up: MCONV

Converting to HTML
==================

   If the `-h' flag is passed instead of `-t' in the previous examples
(*note Converting to Plain Text::), the output is HTML code.  Colours
are implemented using the `<FONT COLOR=...>' construct; background
colour is done with `STYLE="background:..."' attribute, so will only be
visible on web browsers that support CSS.  The entire text is
surrounded by `<PRE>' tags so that the formatting is preserved.

   In the case of menu code (*note A note on menus::), all menu options
are turned into relative HTML links.  It is the responsibility of the
calling program to generate the files that these links refer to.

   An example Perl script showing the use of HTML menu generation is
supplied with this package, in the `extra/' directory.


File: mconv.info,  Node: Converting the Other Way,  Next: A note on menus,  Prev: Converting to HTML,  Up: MCONV

Converting the Other Way
========================

   `mconv' incorporates a reasonable emulation of a VT100 terminal, so
that session logs and scrollback buffers can be turned into flat files.
To do this, pass the `-a' flag to `mconv'.

   To work properly, `mconv -a' must know the original size of the
terminal for which the data was intended; if it was not the same as the
current terminal size then it must be given with the `-w' and `-H'
(note the capital) options.

   What this converter does is to handle screen clearing, line wiping,
scrolling and so on invisibly, and only output lines when a newline
character is received.  Thus "footer prompts" and the like on `mbbs',
which are erased before being overwritten, do not appear in the output.

   `mconv -a' can be used to make `screen' (*note Screen: (screen)Top.)
logs readable, or can even function as input to a BBS robot or
something.

   *Note Examples::, for examples.


File: mconv.info,  Node: A note on menus,  Prev: Converting the Other Way,  Up: MCONV

A note on menus
===============

   All of the foregoing assumes that you are converting normal files.
To convert a menu, you must tell `mconv' that it is dealing with a menu
by supplying the `-m' flag.

   When this flag is given, the `-y' option (anonymity) obviously
ceases to have any meaning, and some new options appear:

`-g'
     Display as user "guest" would see it.

`-d FILE'
     Use LDB file `FILE' for last access information.

`-n'
     Do not use an LDB file at all, even if one is specified by the
     environment variable `MCONV_LDB' or `MVIEW_LDB'.

   The LDB file, if specified, contains information about which files
in the menu have been read, which you are unsubscribed from, and so on.
*Note Last Access::, for more information about LDB files.


File: mconv.info,  Node: MVIEW,  Next: MBBS,  Prev: MCONV,  Up: Top

MVIEW
*****

   The `mview' program is a full-screen viewer, for viewing both files
and menus.  It can even be used as a mini-BBS, although from a security
point of view its usefulness in this respect is limited - you'd be
better off using the BBS program `mbbs' instead.

* Menu:

* MVIEW Invocation::      Options that `mview' accepts.
* File Viewer::           Viewing a BBS format file.
* Last Access Database::  Keeping track of where you've been.
* Menu Viewer::           Viewing a BBS menu, and files within it.
* Scanning::              Finding any files updated since you last read them.


File: mconv.info,  Node: MVIEW Invocation,  Next: File Viewer,  Up: MVIEW

MVIEW Invocation
================

   The general form for invocation of the viewer `mview' is:

     mview [OPTIONS] FILE...

   Each FILE specified will be displayed in turn.

   The first few options determine the way that data is displayed.

`-m'
`--menu'
     Each specified file is to be displayed as a menu, not as a normal
     file.

`-L'
`--listed'
     Each specified file is a directory, to be displayed as a menu
     showing all of the items in the directory.

`-l N'
`--line=N'
`+N'
     Start the file viewer with line N at the bottom of the screen.

     Note that `-l' and `--line' apply to _all_ files specified on the
     command line, but `+N' only applies to those files specified after
     it.

     Also note that this option has no effect if the `-m' option is
     given.

`-z'
`--bottom'
     Start at the bottom of each file.  This does not affect menu
     viewing.

`-T'

`--top'
     Start at the top of each file (the default action if there is no
     LDB entry to use).  Again, this does not affect menu viewing.

`-c'

`--no-colours'

`--monochrome'
     Do not output any colour attributes - view everything in black and
     white.

   The following options control the use of a database recording the
files read and the last position they were read at.  *Note Last
Access::.

`-d FILE'
`--ldb=FILE'
     Use FILE as a last-access database containing records of which
     files have been looked at in the past.  If FILE does not exist, it
     will be created.  Note that old records are never purged
     automatically; use the `-p' option for that.

     This option overrides the `MVIEW_LDB' environment variable.

`-n'
`--no-ldb'
     Don't use a last-access database, even if one is specified in the
     `MVIEW_LDB' environment variable.

`-p'
`--purge-ldb'
     Purge the last access database specified by `-d' or `MVIEW_LDB' by
     removing from it any records pertaining to files that can no
     longer be found, and then exit without viewing any files.

`-f FILE'
`--file=FILE'
     Pretend, for last access database purposes, that FILE was the file
     accessed instead of using the real file name.  In other words,
     record the last access details for the current file under the name
     FILE.

   The new few options determine which restrictions are to be put in
effect.

`-y'
`--anonymous'
     Account names are stripped from `From:' lines, leaving only the
     namelines.

`-r'
`--readonly'
     The files cannot be modified.

`-e'
`--no-edit'
     Direct-editing is disallowed, though files can still be added to.

   The last two options give information about the program.

`--help'
     Print a usage message on standard output and exit successfully.

`-V'
`--version'
     Print version information on standard output and exit successfully.


File: mconv.info,  Node: File Viewer,  Next: Last Access Database,  Prev: MVIEW Invocation,  Up: MVIEW

File Viewer
===========

   To view a file, do `mview FILE'.  This will open FILE in the
full-screen viewer, with all editing enabled (depending on file
ownership and permissions).

   If file's name ends in `.gz', it is treated as a file compressed
with GNU zip (`gzip' - *note Gzip: (gzip)Top.).  This means that it is
decompressed to a temporary file and this temporary file is viewed
instead.

   Note that only regular (seekable) files may be viewed.  FIFOs,
pipes, and serial devices will cause problems.

   For information about the key presses available in the viewer, see
the manual page (`man mview') or press <?> while viewing a file.


File: mconv.info,  Node: Last Access Database,  Next: Menu Viewer,  Prev: File Viewer,  Up: MVIEW

Last Access Database
====================

   Optionally, you can record your position in files by means of a
last-access database (LDB).  This is a file containing details of which
files you have read, when you last read them, and where you left off,
and thus acts as a kind of "bookmark".

   To use an LDB file, you can either give its name with the `-d FILE'
option or you can set the `MVIEW_LDB' environment variable to point to
the file you wish to use as an LDB.

   Note that LDB files have a specific format and should not be created
by hand.

   LDB files also record which menus and files you are subscribed to -
see the menu viewer section (*note Menu Viewer::) and the section on
scanning (*note Scanning::) for more information about subscriptions.

   It is a good idea to purge your LDB now and again - that is, remove
entries which refer to nonexistent files.  This can be done with `mview
-p'.


File: mconv.info,  Node: Menu Viewer,  Next: Scanning,  Prev: Last Access Database,  Up: MVIEW

Menu Viewer
===========

   To view a menu, do `mview -m FILE'.  This will open file in the
full-screen menu viewer.  Note that, unlike in the case of the file
viewer, file must _not_ be compressed.

   If you are using a last access database, you may mark entries in a
menu as "uninteresting", so that when you do a scan (*note Scanning::)
those entries are skipped.  This is known as "unsubscribing", and is
done with the <=> key.

   For information about the key presses available in the viewer, see
the manual page (`man mview') or press <?> while viewing a menu.

   Information about menu code and writing menus is given elsewhere in
this document.  *Note Menu Code::.


File: mconv.info,  Node: Scanning,  Prev: Menu Viewer,  Up: MVIEW

Scanning
========

   Menus may be "scanned" for new files.  This is triggered by hitting
<SPACE>, and causes the viewer to search for the first unread file that
has not been unsubscribed from.

   If all files in the current menu have been read up to date, submenus
are scanned recursively until one is found, at which point the scan
stops and the viewer displays the menu in which that file was found.
Upon hitting <SPACE> again, the viewer will enter that file.

   If no files at all can be found, the viewer exits to the next
highest menu, unless it was already at the top level, in which case
nothing happens.


File: mconv.info,  Node: MBBS,  Next: MGID,  Prev: MVIEW,  Up: Top

MBBS
****

   The `mbbs' program is a fully functional BBS system; the only thing
missing is a multi-user talker (choose one and run it separately).

   In general, if you are a user of this BBS rather than someone who is
running it, you should look at the MVIEW section for commands,
terminology and so on.  *Note MVIEW::.

* Menu:

* MBBS Invocation::       How to run `mbbs' as a user.
* MBBS Administration::   Things that the sysop should know about.
* MBBS Configuration::    The configuration file.
* ACLs::                  Enforcing menu code security.
* User Messaging::        Sending messages between users.
* Privileges and Bans::   Dealing with abuses of the system.
* External Users::        Users without a shell account on the system.


File: mconv.info,  Node: MBBS Invocation,  Next: MBBS Administration,  Up: MBBS

MBBS Invocation
===============

   To run the `mbbs' BBS client, simply do:

     mbbs [OPTIONS...]

   This will read the global configuration file and enter the main menu.

   The following options can be used:

`-e'
`--external'
     Log in as an external user.  *Note External Users::.  Useful in
     the login script for the `bbs' external account; for instance the
     shell for a `bbs' Unix account could be set to `/bbs/login.sh'
     which could contain something like this:

          #!/bin/sh
          
          PATH=/bin:/usr/bin:/usr/local/bin
          export PATH
          
          cat /bbs/issue.txt
          
          bbs --external

     Internal users may also use this to log in as a different,
     external, account.

`-x'
`--xterm-title'
     Use the xterm title to display the current action.  This is the
     default if the terminal type in `$TERM' is "xterm".

`--no-xterm-title'
     Do not use the xterm title to display the current action.

`-c'
`--no-colours'
`--monochrome'
     Do not output any colour attributes - view everything in black and
     white.

`-s'
`--scan'
     Perform a scan (like pressing <SPACE> in the main menu), but don't
     actually log in or view any files, just list what the scan would
     have hit.  Outputs nothing if there would be nothing to look at.

`--help'
     Print a usage message on standard output and exit successfully.

`-V'
`--version'
     Print version information on standard output and exit successfully.

   The following environment variables will be read:

`TERM'
     Used to determine the current terminal type.  If it starts with
     "xterm", then xterm titling is turned on by default.

`ACTION_FILE'
     If the file referred to by `$ACTION_FILE' exists and is writable
     when `mbbs' starts up, the current action will be stored here
     every time it changes.  This was useful for a script the author
     wrote once, and has been retained in case anyone else finds it
     handy.

`MANIM_PROG'
     Program to use instead of `qmanim' to run Anim programs.  Note that
     whatever program you specify must accept the `-n' and `-e' options
     (account name and nameline).

`REMOTE_HOST'
     What to put in the "Location" field on the Users On screen if the
     relevant information cannot be obtained from the `utmp' file.
     Useful if you are running your BBS on a machine to which you do
     not have root access, since you can hang `telnetd' off a port and
     tell it to use a script instead of `login' - you can then write
     this script such that it sets `REMOTE_HOST' accordingly.


File: mconv.info,  Node: MBBS Administration,  Next: MBBS Configuration,  Prev: MBBS Invocation,  Up: MBBS

MBBS Administration
===================

   To begin with, it is probably best to copy the example configuration
and system files which came with the package in the `extra/bbs'
directory.  These can then be modified to suit your setup.

   It is recommended that before you try to set up a BBS with `mbbs',
you get to grips with menu coding and the ins and outs of the menu/file
viewer, `mview'.

   When `mbbs' is run, it reads the global configuration file (which
should only be writable by the BBS administrator).

   The location of the main menu, the location of the <ESCAPE> menu, the
system logging directories, the location of the options (<ESCAPE> <O>)
menu, and so on - all are controlled by the configuration file, the
format of which is explained in the next section.

   It is worth noting that the <ESCAPE> menu and the options menu are
read from files which you, as BBS admin, can edit; it is therefore
important that they are set up correctly.  They both use some
"nonstandard" extensions to menu coding - the "?" action type - and the
keypresses inside them should not be altered.

   The BBS client, `mbbs', and the GID setting utility, `mgid', should
both be installed setgid to some group which nobody is a member of.  The
installation scripts will use the group "bbs" by default, creating it
if it does not exist.

   This means that the menu code absolutely controls who has access to
what, because access to all files has to be through the BBS client.  It
is important, when running the BBS, to make sure that the Unix file
permissions and ownership are always set properly to ensure that nobody
can get access to anything they shouldn't.

   A good idea is to set up a crontab for yourself as BBS admin and
make yourself a member of the "bbs" group, then schedule jobs to
regularly do useful things such as purge users' LDB files of old
entries.  Whether you do this, and how you actually do it, are of
course entirely dependent on your setup.


File: mconv.info,  Node: MBBS Configuration,  Next: ACLs,  Prev: MBBS Administration,  Up: MBBS

MBBS Configuration
==================

   The global configuration file for `mbbs' should be placed in
`/usr/local/etc', `/etc', or whichever `etc/' directory is appropriate
to the configuration you chose with the `./configure' script when
compiling.  Its filename should be `bbsrc' or `bbs.cf'.

   Each line should contain a key and a value. Blank lines, and
anything following a hash (#), are ignored.  Unknown keys will cause an
error, and defining the value of a key more than once will result in
the key having the value that is nearest the end of the file.

   The following keys can be defined:

`root'
     This is the top-level directory for the BBS system.  Any
     subsequent filenames with `$' in them will have the `$' expanded
     to the value of this key. For example:

          root /bbs
          main $/main.mn

     This will set the key "`main'" to `/bbs/main.mn'.

`main'
     This is the location of the main menu, which is the first thing
     that a user will see on running `mbbs'.

`special'
     This is the location of the menu that is to appear when the user
     presses <ESCAPE> in a file or a menu.  In this menu, certain
     keypresses have special meanings when combined with the "?" action
     type.  Look at the example menu supplied with this package for
     more information.

`options'
     This is the location of the menu that is to appear when the user
     presses <ESCAPE> then <O>.  This menu should be kept pretty much
     the same as the example supplied for it to work properly.

`xwarn'
     Before entering an X-rated menu item, users will be shown this
     file.  If they press <Q> while reading it, they will not be
     allowed to continue on to the menu entry itself.

`udb'
     This is the filename template for users' UDB (User DataBase)
     files.  In it, the character `%' will be replaced with the user's
     account name.  It should refer to a file in a group-writable (but
     not world-writable) directory.

`ldb'
     This is the filename template for users' LDB (Last-access
     DataBase) files.  As with the UDB template, the character `%' will
     be replaced with the user's account name, and again it should
     refer to a file in a group-writable directory.  It should _not_
     refer to a file in a user-owned directory, because then clever use
     of symbolic links could compromise BBS security.

`edit'
     This is the filename template for a user's temporary edit file,
     used when adding to a file with the <A> key.  The character `~'
     will be expanded to the current user's home directory.

`friends'
     This is the file in which to store a user's "friends list" (users
     listed in this file will be highlighted on the Users On screen).

`u2u'
     This is the directory in which to store files relating to
     user-to-user messaging.

`u2uomax'
     This is the maximum size, in kilobytes, that a user's messages
     file can be when they log out.  If it is larger than this when
     they log out, it will be truncated.  Default value: 100.

`u2uimax'
     This is the maximum size, in kilobytes, that a user's messages
     file can be while they are logged in.  If it grows above this
     size, it will be truncated.  Default value: 1000.

`u2uomin'
     This is the size, in kilobytes, to which a user's messages file
     will be truncated when they log out if its size exceeds `u2uomax'.
     Default value: 50.

`u2uimin'
     This is the size, in kilobytes, to which a user's messages file
     will be truncated if its size exceeds `u2uimax' while the user is
     logged in.  Default value: 600.

`u2ulog'
     This is the file in which to store a copy of all messages sent by
     users.  Only the sysop should be allowed access to this file;
     allowing access is up to you.

`u2ulgsz'
     The size, in kilobytes, that the above log will be allowed to grow
     to.  If it gets any larger it will be truncated to 10% of this
     size.

`sysop'
     A list of users to treat as "sysop" of the BBS, separated by
     spaces.  Any user whose name is in this list will be able to write
     menus containing execution entries (type X or S) that anyone will
     be able to execute even if those entries' commands are not listed
     in "paths" (see below).  Since this is a lot of power to give
     someone on a multi-user system, only the BBS administrator(s)
     should be in this list.

`logdir'
     The directory in which the system logs (below) will be stored.  It
     should be writable to group if you haven't already created all of
     the files below inside it.

`addlog'
`dellog'
`editlog'
`runlog'
`maillog'
`bbslog'
     The filenames, inside the "logdir" directory, of the log files for
     addition of entries to files, deletion of entries from files,
     direct editing of files, execution of X or S type menu entries,
     the emailing of files with <M>, or the exiting of an `mbbs' client.

     These files should be created with permissions 660 and should be
     owned by the BBS group.

`logsize'
     The maximum size of any one of the log files above, in kilobytes.
     If a log file becomes larger than this, it will be truncated to
     10% of this size.

`usrlist'
     Inside this directory should be either a set of user-owned
     directories or a set of symbolic links.  Each of these will be
     that user's group list directory, as referred to by the `.IF USER
     user/group/' construct in menu code.

`listdir'
     The system group directory; this directory should contain all
     system-wide groupings, for instance "admin".  Remember that group
     files should be group-readable to be of any use.

`extlim'
     The maximum number of users allowed on the BBS before external
     access is denied.  *Note External Users::.

`idleext'
     The maximum allowed idle time for an external user.  Defaults to
     1800 seconds, or 30 minutes.

`idleint'
     The maximum allowed idle time for an internal user.  Defaults to
     10800 seconds, or 3 hours.

`paths'
     The name of a file which lists, one per line, the commands that a
     non-admin member's menu code can get another user to run via the X
     or S menu types.

     A whole line must match the first part of a command line for the
     command to be allowed.  For instance the line `/bin/false' would
     allow the command lines `/bin/false', `/bin/falsefoo', and so on.

`nolog'
     This is a kludge to allow the author to keep files from different
     BBSes inside an `mbbs' BBS.  Any log file whose path matches all of
     "nolog" will be ignored - logs will not be written to that file.

     Leave this blank unless you know what you are doing.

`status'
     The name of a directory, which must be group-readable,
     group-writable and group-executable, in which each client will
     store details of their current action.  This is used to generate
     the Users On listing.


File: mconv.info,  Node: ACLs,  Next: User Messaging,  Prev: MBBS Configuration,  Up: MBBS

ACLs
====

   Users writing menu code for use in `mbbs' may only link to files that
they own, unless the user who owns the file they are linking to
expressly gives them permission.

   This is so that, for instance, if user "b" owns a file "`x.cm'"
which is supposed to be marked `.STATUS ANONYMOUS', a malicious user
"a" cannot write menu code which links to "`x.cm'" without "b"'s
permission.

   In this case, user "b" would have to create an Access Control List,
or ACL, which is a file containing the names of users allowed to link
to a file.  Creating the file "`x.cm.acl'", group readable but not
writable, containing just "a" on a line, would give user "a" permission
to link to the file.

   Thus you can allow only "trusted" users to link to your files if
they are sensitive.

   An ACL file is simply a text file containing the names of all users
who you want to permit to link to your file.  Blank lines, and text
after a #, are ignored.  More than one name may be given per line, and
only usernames (not group names) are valid.

   Alternatively, making your file world-readable gives everyone
permission to link to it.  This is of course not recommended for
sensitive or anonymous files.

   Note that listed directories (*note Listed Directories::) cannot have
associated ACL files; if you want other users to be able to link to
them in their menu code, you will have to make them world-readable.


File: mconv.info,  Node: User Messaging,  Next: Privileges and Bans,  Prev: ACLs,  Up: MBBS

User Messaging
==============

   Users may send each other messages in `mbbs'.  Each message a user
receives is stored in their private messages file, which they alone can
read.  Although each user cannot directly edit their own messages file,
they may delete individual messages from it if they wish.

   Messages are sent by pressing <S> in a file and selecting the edit
you wish to reply directly to, or by pressing <ESC> <S> and specifying
the user or users to send to.

   Once the message has been written and the editor has been exited, a
menu of options is presented.  Any users who are ignoring messages,
logged out, or whose message file does not yet exist are listed at the
top of this menu.

   Any given message may be postponed instead of being sent.  If you
wish to resume a postponed message, simply begin sending to exactly the
same users as the original message (which implies that if you postpone
two messages to the same recipients, things might well get confused).

   Note that all postponed messages are erased when you exit the BBS -
they are not retained between sessions.

   Users' messages files are automatically truncated when that users
logs out, if they are 100K or larger.  It is thus advisable to mail
your messages to yourself (do <ESC> <R> then <M>) before logging out if
you want to keep a copy.


File: mconv.info,  Node: Privileges and Bans,  Next: External Users,  Prev: User Messaging,  Up: MBBS

Privileges and Bans
===================

   Since any communications system is open to abuse, `mbbs' has a
system of privileges and bans.

   Any user may have one or more of the following privilege flags:

`D - Disconnect Users'
     Allow the user to disconnect any other user by pressing <D> while
     examining them.

`A - Alter Account Details'
     Allow the user to alter another user's account details by pressing
     <E> while examining them, change their password with <P>, remove
     the account with <R>, and create a new account with <C>.

   Any user may also have any of the following ban flags set:

`N - Alter Nameline'
     The user is not allowed to change their nameline with <ESC> <O>
     <N>.

`M - Mail Files'
     The user is not allowed to mail any files to themselves.

`2 - Messages'
     The user cannot send messages.

`E - Alter Files'
     The user is not allowed to alter files in any way - no editing,
     adding, or deleting.

`B - Full Ban'
     The user cannot log into the BBS at all.

   Any of these flags can be set by someone with an Alter Account
privilege.  Privileges are conferred by adding the relevant letter to
`BBS_PRIVS', and bans are applied by adding the relevant character to
`BBS_BANS'.

   However, a user's level - `BBS_LEVEL' - determines who they can apply
their privilege to.  A higher level user cannot alter the details of a
user with a lower or equal level.

   The sysop always has all privileges and no bans, and has a level of
0.  The default user level of other users is 10.  The user "guest"
always has no privileges, all bans except total ban, and a level of 99.


File: mconv.info,  Node: External Users,  Prev: Privileges and Bans,  Up: MBBS

External Users
==============

   Several times in this manual, there have been mention of "external"
and "internal" users or accounts.

   An "internal" account is simply one which exists in Unix as a shell
account - `root', for example.  Users of internal accounts cannot log
into the BBS as "external" users, and cannot change their password via
the BBS - they must continue to do it via `passwd' as usual.

   Internal accounts can never be fully removed from the BBS; using the
Remove Account privilege on them will only erase their BBS data to
default values.  To prevent an internal account from logging on, either
erase the Unix account or set their "ban from BBS" flag by putting a
`B' in their `BBS_BANS' UDB field (*note Privileges and Bans::).

   External accounts, on the other hand, exist entirely on the BBS.
External users, such as `guest', do not have a shell account in Unix
and all external users have the same effective UID.  They can set their
password from within the BBS, as it is controlled by the BBS and not by
the Unix password system.

   Also, external users can be prevented from logging in if the BBS is
"full" - if there are `extlim' or more users on the BBS, no more
external logins are allowed.  *Note MBBS Configuration::.

   An example way of allowing external access is to create a Unix
account called `bbs' on the server, with no password, and set its login
shell to something like `/bbs/login.sh'.  The contents of
`/bbs/login.sh', which should be owned by `root' and `chmod 755', would
be something like the following:

     #!/bin/sh
     
     PATH=/bin:/usr/bin:/usr/local/bin
     export PATH
     
     cat << EOF
     
     Welcome to XXX BBS.  If you do not have an account, log in as "guest" for
     limited access; you can apply for an account by emailing XXX@XXX.
     EOF
     
     mbbs --external

   Obviously this requires root access to the server, so you could try
hanging it off a port or something.  For instance, as a non-root user
on a Red Hat 6.x system, you could make a file `/home/me/inetd.conf'
containing this:

     9999 stream tcp nowait me /usr/sbin/in.telnetd in.telnetd -L /home/me/bbs/login.sh

   Then, run the command `/usr/sbin/inetd /home/me/inetd.conf' to start
`inetd', and create the file `/home/me/bbs/login.sh' (make sure it is
`chmod 700' to be executable) containing the following:

     #!/bin/sh
     export REMOTE_HOST=$2
     export PATH=/bin:/usr/bin:/usr/local/bin
     cat << EOF
     Some welcome message or other
     EOF
     /home/me/mbbs --external

   Change the paths as necessary - basically this just sets the
`REMOTE_HOST' environment variable (*note MBBS Invocation::), displays
a welcome message, and runs the BBS in external mode.


File: mconv.info,  Node: MGID,  Next: MTIME,  Prev: MBBS,  Up: Top

MGID
****

   The `mgid' utility simply sets the group ID of all files it is given
to the same as that of `mgid' and `mbbs'.  If you are running a BBS
system using a setgid `mbbs' client, then this utility allows users who
are not members of the "bbs" group to make their files available on the
BBS.

   A typical sequence of commands would be:

     touch newfile.cm
     mgid newfile.cm
     chmod 660 newfile.cm

   This would create the file newfile.cm and make it readable and
writeable by its owner and by users of the BBS.


File: mconv.info,  Node: MTIME,  Next: MTRUNC,  Prev: MGID,  Up: Top

MTIME
*****

   The `mtime' utility allows the generation of arbitrary datestamps, to
be used in files viewed with `mview' or `mbbs'.  Calling it with no
arguments causes a current datestamp to be output; calling it with a
date string will cause a datestamp appropriate to that time to be
output.

   The date string can be in any common format, even something like
"last Tuesday" will suffice.  If entering a date gives an unexpected
result, please let the author know (*note Reporting Bugs::).

   An invalid date will result in a blank datestamp with the words
"Invalid Date" after it.


File: mconv.info,  Node: MTRUNC,  Next: MTE,  Prev: MTIME,  Up: Top

MTRUNC
******

   The `mtrunc' utility truncates the given log file if it is bigger
than a certain size (default is 100 kilobytes).  Enough lines are left
from the bottom of the file to leave it at a smaller size (default 10
kilobytes).  The message "(truncated)" is left at the top of the file.

   An archive file may be specified, into which data will be copied
before it is removed from the log file being truncated.

   File locking is performed while truncation is being done to ensure
that no data is lost.

   The general form for invocation of `mtrunc' is:

     mtrunc [OPTIONS] FILE

   Only one FILE must be specified.  The following options are
available:

`--maxsize=MAXSIZE'
`--max=MAXSIZE'
`-m MAXSIZE'
     Truncate the file if it is larger than MAXSIZE bytes.  MAXSIZE may
     optionally be followed by B, K, or M to denote bytes, kilobytes
     and megabytes respectively.

`--truncto=TRUNCTO'
`--to=TRUNCTO'
`-t TRUNCTO'
     When truncating, leave at most TRUNCTO bytes in the file,
     including the "(truncated)" message at the top.  As with, MAXSIZE,
     TRUNCTO can be followed by any of B, K or M.

`--archive=ARCHIVE'
`-a ARCHIVE'
     Append any data to ARCHIVE before removing it from FILE.  The
     default is to silently discard truncated data.

`--commentfile'
`-c'
     Treat the file as a comment file.  That is, do not touch the
     header; everything up to and including the first line starting
     with ``Message:'' will be left as it is.

     Note that if no header can be found, the file is not truncated.

`--help'
     Print a usage message on standard output and exit successfully.

`--version'
`-V'
     Print version information on standard output and exit successfully.


File: mconv.info,  Node: MTE,  Next: Menu Code,  Prev: MTRUNC,  Up: Top

MTE
***

   The MCONV Text Editor is the one which is used internally by `mconv'.
You can use it outside the BBS by using `mte FILE' to edit FILE.

   In the editor, typing `.' on a line by itself and then hitting
<RETURN> will exit and save any changes.  Typing `.quit' then <RETURN>
will exit WITHOUT saving any changes.

   For more information about the keypresses available, run `mte' on
any file and press Control-O (Options) to see the help screen.

   `mte' recognises the following options on the command line:

`--help'
     Print a usage message on standard output and exit successfully.

`--version'
`-V'
     Print version information on standard output and exit successfully.

   Note that the environment variable `$EDITOR_OPTIONS' is also read. It
may contain the following characters:

`i'
     Insert mode off.

`I'
     Insert mode on.

`a'
     Autoindent mode off.

`A'
     Autoindent mode on.

`w'
     Word wrapping off.

`W'
     Word wrapping on.

`Rnnn'
     Right margin for word wrapping (default is R77, i.e. 77 characters)


File: mconv.info,  Node: Menu Code,  Next: Examples,  Prev: MTE,  Up: Top

Menu Code
*********

   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 #.

* Menu:

* Menu Entries::          How a menu entry is defined.
* Menu Commands::         Altering entries and changing the menu properties.
* Menu Environment::      Environment variables available to menu code.
* Listed Directories::    Menus generated from directory contents.


File: mconv.info,  Node: Menu Entries,  Next: Menu Commands,  Up: Menu Code

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:

`A'
     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
     `<RGRINM>' 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.

`B'
     Binary - cannot be viewed directly.

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

`L'
     Listed Directory - generate a menu from the contents of the
     specified directory. *Note Listed Directories::.

`M'
     Menu File - generate a menu from the contents of the menu file.

`R'
     Read-only File - Not suitable for adding comments to.

`S'
     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; *Note 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 `mbbs' 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.  *Note MBBS
     Configuration::.

`T'
     Telnet Connection - connect to the machine FILE using Telnet.

`X'
     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
`extra' directory.

   Note that when using the BBS system `mbbs', 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.  *Note ACLs::.


File: mconv.info,  Node: Menu Commands,  Next: Menu Environment,  Prev: Menu Entries,  Up: Menu Code

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.

* Menu:

* COMMENTFILE::           Associate a separate comment file with an entry.
* HEIGHT::                Ignored.
* IF::                    Conditional menu code.
* LINE::                  Fill a line with text.
* LOG::                   Log accesses to a file.
* OPTIONS::               Ignored.
* PATHNAME::              Set the path prefixing all subsequent filenames.
* QUIT::                  Stop processing the menu immediately.
* SETENV::                Ignored.
* STATUS::                Set the status of this or subsequent entries.
* TEXT::                  Centre a line of text.
* TITLE::                 Give the current menu a title.
* VIEW::                  Associate a viewfile with an entry.
* VIEWALWAYS::            Associate a compulsory viewfile with an entry.


File: mconv.info,  Node: COMMENTFILE,  Next: HEIGHT,  Up: Menu Commands

.COMMENTFILE
------------

   Syntax:

     .COMMENTFILE <FILE> [IF ...]

   Associate the commentfile <FILE> with the next entry in the menu.
The `.COMMENTFILE' 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.


File: mconv.info,  Node: HEIGHT,  Next: IF,  Prev: COMMENTFILE,  Up: Menu Commands

.HEIGHT
-------

   Syntax:

     HEIGHT <LINES> [IF ...]

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


File: mconv.info,  Node: IF,  Next: LINE,  Prev: HEIGHT,  Up: Menu Commands

.IF
---

   Syntax:

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

   Execute the following commands only if the test after the `.IF' is
true.  If the test is false, and an `.ELSE' is given, execute the
commands following the `.ELSE' instead.

   Note that `.IF's can be arbitrarily nested.

   The test is composed of one or more conditions, which should be
joined by either `&&' or `||', 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 `NOT' to negate the result it
returns.

   <CONDITION> may be one of the following:

`ACLOK <FILE>'
     Returns true if <FILE> exists and linking to it would be allowed
     by the ACL mechanism.  *Note ACLs::.

`ENVIRONMENT <NAME> <VALUE> [...]'
     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.  *Note Menu
     Environment::.

`EXISTS <FILE>'
     Returns true if <FILE> exists.

`EXTERNAL'
     Returns true if the user is an external or a guest.

`GUEST'
     Returns true if the user is a guest.  See `EXTERNAL'.

`HOSTNAME <HOST> [...]'
     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.

`LOCATION <HOST> [...]'
     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.

`SITE <ADDRESS> [...]'
     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.

`TERMINAL <TYPE> [...]'
     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.

`TTY <TTY> [...]'
     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.

`USER <USER> [...]'
     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 `mbbs' only).  Groups of the form `foo/' refer to the
     system group file `foo', whereas groups of the form `foo/bar/'
     refer to the user `foo''s "`bar'" group.


File: mconv.info,  Node: LINE,  Next: LOG,  Prev: IF,  Up: Menu Commands

.LINE
-----

   Syntax:

     .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.


File: mconv.info,  Node: LOG,  Next: OPTIONS,  Prev: LINE,  Up: Menu Commands

.LOG
----

   Syntax:

     .[NOW|SUBSEQUENT] LOG <OPTION> <FILE> [IF ...]
     .LOG CLEAR

   Associate a log file with the next menu entry, with the current menu
if the `NOW' option is given, or with all subsequent menu entries in
this menu if the `SUBSEQUENT' 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:

`TITLE'
     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.

`USER'
     Log the nameline of the user.

   `.LOG CLEAR' will clear any log files associated with the next menu
entry.


File: mconv.info,  Node: OPTIONS,  Next: PATHNAME,  Prev: LOG,  Up: Menu Commands

.OPTIONS
--------

   Syntax:

     .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.


File: mconv.info,  Node: PATHNAME,  Next: QUIT,  Prev: OPTIONS,  Up: Menu Commands

.PATHNAME
---------

   Syntax:

     .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 `.PATHNAME' 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, `.PATHNAME' will restore the path back
to the default for that menu.


File: mconv.info,  Node: QUIT,  Next: SETENV,  Prev: PATHNAME,  Up: Menu Commands

.QUIT
-----

   Syntax:

     .QUIT [IF ...]

   Stop processing the menu at the current line.

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


File: mconv.info,  Node: SETENV,  Next: STATUS,  Prev: QUIT,  Up: Menu Commands

.SETENV
-------

   Syntax:

     .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 `mbbs' is not modified - only the
environment of the next executable menu entry.

   This command is ignored in version 1.2.7.


File: mconv.info,  Node: STATUS,  Next: TEXT,  Prev: SETENV,  Up: Menu Commands

.STATUS
-------

   Syntax:

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

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

   <OPTION> may take the following values:

`ADD'
     Permit the user to add comments to the file with <A>.

`ANONYMOUS'
     Prevent the display of the author of each comment in the `From:'
     line (*note From line::), and the logging of comment added to the
     Add Log.

`BARDELETE'
     Prevent the user from deleting comments from the file with <.><D>.

`BARINFO'
     Prevent the user from generating an index of the file with <I>.
     In listed directories, prevents filenames being "prettified" and
     thus causes filenames to be displayed as they really are.

`BARLOG'
     Prevent the menu entry from being logged in any of the system logs.

`BARMAIL'
     Prevent the user from mailing the file with <M>.

`BARSENDREPLY'
     Prevent the user from sending a reply to an edit in the file.

`CLEAR'
     Clear all previously set status values set for this entry.

`DELETE'
     Permit the user to delete any comment from the file with <.><D>.

`EDIT'
     Permit the user to edit the entire file in the editor with <.><A>.

`HIDETITLE'
     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.

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

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

`NOLAST'
     Prevent last access information being stored for the entry.

`NOSCAN'
     Cause the entry to be ignored on scanning.

`NOTIME'
     Prevent the last modification time of the entry from being
     displayed in the menu.

`READONLY'
     Prevent the user from altering the file in any way.

`XRATED'
     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.


File: mconv.info,  Node: TEXT,  Next: TITLE,  Prev: STATUS,  Up: Menu Commands

.TEXT
-----

   Syntax:

     .TEXT [<TEXT>]

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


File: mconv.info,  Node: TITLE,  Next: VIEW,  Prev: TEXT,  Up: Menu Commands

.TITLE
------

   Syntax:

     .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:

`CENTRE'
     Centre the title file.

`LEFT'
     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.


File: mconv.info,  Node: VIEW,  Next: VIEWALWAYS,  Prev: TITLE,  Up: Menu Commands

.VIEW
-----

   Syntax:

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

   Associate a view file with the next entry, or with the current menu
if the `NOW' 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 <Q> when reading the viewfile, they will not
proceed to the menu entry itself.


File: mconv.info,  Node: VIEWALWAYS,  Prev: VIEW,  Up: Menu Commands

.VIEWALWAYS
-----------

   Syntax:

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

   Associate a view file with the next entry, or with the current menu
if the `NOW' option is given, as per `.VIEW' (*note VIEW::), but
display it every time the user enters the file or menu, regardless as
to whether it has been updated.


File: mconv.info,  Node: Menu Environment,  Next: Listed Directories,  Prev: Menu Commands,  Up: Menu Code

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 `$FOO'.

   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:

`ACCOUNT'
`MONO_ACCOUNT'
     The account name of the current user.  The second name is kept for
     compatibility with Monochrome BBS.

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

`KEYPATH'
`MONO_KEYPATH'
     The keypath of the current menu (_not_ of the current menu entry).
     This will be a blank string unless the menu is being viewed
     through `mbbs'.  Once again, the second name is for compatibility
     with Monochrome BBS.

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

`SPOOL_FILE'
     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 `extra/utils' directory which
     came with this package.


File: mconv.info,  Node: Listed Directories,  Prev: Menu Environment,  Up: Menu Code

Listed Directories
==================

   If you specify a menu entry of type L (*note 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:

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

`.acl'
     Treated as a comment file (type C).  If you create a file of this
     type using <.><A> in a listed directory, it will be created
     group-readable but not group-writeable, for security.  *Note
     ACLs::.

`.an'
     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.

`.mn'
     Treated as a submenu file (type M).  If you create a file of this
     type using <.><A> in a listed directory, it will be created
     group-readable but not group-writeable, for security.

`.cm'
     Treated as a comment file (type C).  If it is group writable, the
     file will be addable to other users in `mbbs'.

`.cm.gz'
`.ro'
`.ro.gz'
     Treated as a readonly comment file (type C).

`.txt'
`.txt.gz'
     Treated as a formatted file (type F).

`.sh'
`.pl'
`.perl'
     Entered as an executable entry (type X).

`.sp.sh'
`.sp.pl'
     Entered as a spooled executable entry (type S).

`.html'
`.htm'
     Entered as an executable entry (type X), which when chosen will
     launch the web browser `lynx' to point at the file.

`.sc'
     Entered as an executable entry (type X), which when chosen will
     launch the spreadsheet calculator `sc' 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
`src/display/menu/listed.c'.  Suggestions for additions would be
gratefully received - see *Note Reporting Bugs::.

   Please note that setting the `.STATUS BARINFO' 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.


File: mconv.info,  Node: Examples,  Next: Reporting Bugs,  Prev: Menu Code,  Up: Top

Examples
********

   This chapter contains a few examples of the uses of the MCONV
package.

* Menu:

* Session Log Example::    Log a TELNET session and view it later.
* HTMLification Example::  Make a BBS section into web pages.
* Offline Diary Example::  Keep your diary offline and upload the changes.
* General Example::        Non-BBS example of the uses of menu code.


File: mconv.info,  Node: Session Log Example,  Next: HTMLification Example,  Up: Examples

Session Log Example
===================

   To record a telnet session for later viewing:

     telnet some.where.com | tee sesslog.tmp
     mconv -a < sesslog.tmp > session.log
     rm sesslog.tmp

   Or, without using any intermediary files:

     telnet some.where.com | tee /dev/tty | mconv -a > session.log

   ...and to view that log:

     mview session.log

   The session log obtained will be free of all special characters like
cursor positioning and screen clearance; it will be a simple linear
file of text plus `mbbs' attributes to keep the colour and highlighting
relatively intact.

   Note that because of the linear nature of the output, you will get
unexpected results if you view any animations or other applications
which mess around with cursor positioning a lot.  There isn't really
any way around this, as there isn't really any way of making a linear
log of such things.


File: mconv.info,  Node: HTMLification Example,  Next: Offline Diary Example,  Prev: Session Log Example,  Up: Examples

HTMLification Example
=====================

   To use the "quick and dirty" experimental Perl script supplied with
this distribution to convert your Monochrome BBS section, whose
top-level menu file is `~/u1/foo.mn', to a set of web pages in
directory `bar', using `template.html' as an HTML template:

     m2ht.pl ~/u1/foo.mn "FOO menu title" template.html bar

   Note that this is an _experimental_ script.  You should at least read
the comments at the top of it before trying it out.


File: mconv.info,  Node: Offline Diary Example,  Next: General Example,  Prev: HTMLification Example,  Up: Examples

Offline Diary Example
=====================

   If you are a member of staff on Monochrome BBS and have direct
access to your public diary file, then you can keep it offline.
Download a copy to your local machine, and whenever you want to make
changes, do:

     mview diary.cm

   Here, the diary file is assumed to be `diary.cm'.  When you've added
an entry, you may upload it to Monochrome BBS at your leisure (instead
of having to either type it all online, or type it offline and guess
how it will be formatted - `mview' shows you how it will look).

   For instance, uploading could be done something like this:

     scp diary.cm whoever@el.mono.org:u1/diary.cm

   Scripts can also be written to do such things as converting
mailed-to-self Monochrome BBS files to `mview'-able files, datestamps
intact, and so on.


File: mconv.info,  Node: General Example,  Prev: Offline Diary Example,  Up: Examples

General Example
===============

   It be useful to set up a series of menus containing various
utilities, system logs, and so on, to be accessed by a convenient alias
in the shell.  For instance, my "private" menu once looked like this at
the top level:

                      Private Area (ivarch) <P>
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ivarch ~~
     
     ( 1 Hour  7 Min)        [R] + Latest Reminder
     
                      Menu   [S] = GPLed Source
                      Menu   [D] = Private Diaries
                      Menu   [P] = Public Diaries
                      Menu   [W] = Work Area
     
                      Menu   [O] = Online Utilities
                      Menu   [T] = Other Utilities
     
                      Menu   [C] = Configuration files
                      Menu   [L] = System Logs
     
                       Run   [>] * Regenerate Reminder

   The source code for that menu looks something like this:

     .NOW STATUS EDIT
     .SUB STATUS EDIT
     
     .LINE
     
     .STATUS READONLY
     Latest ^]BR^]beminder
     R C reminder.cm
     
     .LINE
     
     .STATUS NOSCAN NOLAST
     ^]CGGPLed ^]BS^]bource
     S M ../src/gpl/.index.mn
     
     ^]CGPrivate ^]BD^]biaries
     D M ../diary/private.mn
     
     ^]CG^]BP^]bublic Diaries
     P M ../diary/public.mn
     
     ^]CG^]BW^]bork Area
     W M ../var/work/index.mn
     
     .LINE
     
     .STATUS NOSCAN NOLAST
     ^]CG^]BO^]bnline Utilities
     O M online.mn
     
     .STATUS NOSCAN NOLAST
     ^]CGOther U^]Bt^]bilities
     T M utils.mn
     
     .LINE
     
     .STATUS NOSCAN NOLAST
     ^]CG^]BC^]bonfiguration files
     C M config.mn
     
     ^]CGSystem ^]BL^]bogs
     L M /var/log/.index.mn
     
     .LINE
     
     Regenerate Reminder
     > X reminder|sed '/^          /d'>~/tmp/rem.$$;[... snipped]

   As a generalised menu system, the applications are obviously as
numerous as you care to make them.


File: mconv.info,  Node: Reporting Bugs,  Prev: Examples,  Up: Top

Reporting Bugs
**************

   Please report bugs to <mconv@ivarch.com>.  Be sure to include the
word `mconv' somewhere in the subject heading.

   Suggestions for future improvements are also welcome at the same
address, as are reports of successful use.

   The latest version of `mconv' can always be found at its home page,
<http://mconv.sourceforge.net/>.


File: mconv.info,  Node: Attribute List,  Next: Menu Command List,  Up: Top

Attribute List
**************

   An attribute sequence starts with an escape character, commonly <^[>,
although <^]>, <^\> and <^^> are also valid.  It is followed by one of
the following letters:

`B'
     Bold on

`F'
     Flash on

`R'
     Reverse on

`S'
     Standout on

`U'
     Underline on

`b'
     Bold off

`f'
     Flash off

`r'
     Reverse off

`s'
     Standout off

`u'
     Underline off

`a'
     All off

`C'
     Colour - see below

   In general, an upper case letter turns on an attribute, and a lower
case one turns it off.  The only exception to this is `C' for Colour,
which does not have a "turn off" attribute and must be followed by a
third character which signifies the colour.

   Valid colour sequences (after an escape character) are:

`CK'
     Black foreground

`CR'
     Red foreground

`CG'
     Green foreground

`CY'
     Yellow foreground

`CB'
     Blue foreground

`CM'
     Magenta foreground

`CC'
     Cyan foreground

`CW'
     White foreground

`CA'
     Default foreground (white)

`Ck'
     Black background

`Cr'
     Red background

`Cg'
     Green background

`Cy'
     Yellow background

`Cb'
     Blue background

`Cm'
     Magenta background

`Cc'
     Cyan background

`Cw'
     White background

`Ca'
     Default background (black)


File: mconv.info,  Node: Menu Command List,  Next: Concept Index,  Prev: Attribute List,  Up: Top

Menu Command List
*****************

   Menu entries are specified like this:

     TITLE LINE
     <KEY> <TYPE> <FILENAME | ACTION>

   Entry types are:

`A'
     Animation

`B'
     Binary

`C'
     Comment File (most useful type)

`L'
     Listed Directory

`M'
     Menu File (i.e. a submenu)

`R'
     Read-only File

`S'
     Spooled Output (S! = spool then reload menu, S<NUM> [eg S30] =
     spool but kill command if it's still going after NUM seconds)

`T'
     Telnet connection

`X'
     Executable (X! = execute then reload menu, X& = execute in
     background)

   Valid menu commands are:

     .COMMENTFILE <file> [IF...]
     .IF [NOT] <condition> [&& ... | || ...]
         <condition> can be:
           ACLOK <file>
           ENVIRONMENT <var> <val> [...]
           EXISTS <file>
           EXTERNAL
           GUEST
           HOSTNAME <host> [...]
           LOCATION <host> [...]
           SITE <address> [...]
           TERMINAL <type> [...]
           TTY <tty> [...]
           USER <user> [...]
          (NB <user> can be user, sysgroup/ or user/usersgroup/ )
     .ELSE
     .ENDIF
     .LINE [<text>]
     .[NOW|SUBSEQUENT] LOG [TITLE|USER] <file> [IF ...]
     .LOG CLEAR
     .PATHNAME <path> [IF ...]
     .PATHNAME
     .QUIT [IF ...]
     .[NOW|SUBSEQUENT] STATUS [NOT] <option> [...] [IF ...]
         <option> can be:
           ADD
           ANONYMOUS
           BARDELETE
           BARINFO
           BARLOG
           BARMAIL
           BARSENDREPLY
           CLEAR
           DELETE
           EDIT
           HIDETITLE
           LOWPRIORITY
           NOINDEX
           NOLAST
           NOSCAN
           NOTIME
           READONLY
           XRATED
     .TEXT [<text>]
     .TITLE [CENTRE|LEFT] <file> [IF ...]
     .[NOW] VIEW <file> [IF ...]
     .[NOW] VIEWALWAYS <file> [IF ...]

   Thanks are due to AMF for compiling the original Monochrome BBS
documentation on which this is based.


File: mconv.info,  Node: Concept Index,  Prev: Menu Command List,  Up: Top

Concept Index
*************

* Menu:

* .COMMENTFILE:                          COMMENTFILE.
* .HEIGHT:                               HEIGHT.
* .IF:                                   IF.
* .LINE:                                 LINE.
* .LOG:                                  LOG.
* .OPTIONS:                              OPTIONS.
* .PATHNAME:                             PATHNAME.
* .QUIT:                                 QUIT.
* .SETENV:                               SETENV.
* .STATUS:                               STATUS.
* .TEXT:                                 TEXT.
* .TITLE:                                TITLE.
* .VIEW:                                 VIEW.
* .VIEWALWAYS:                           VIEWALWAYS.
* Access Control Lists:                  ACLs.
* Access logs:                           LOG.
* ACLs:                                  ACLs.
* Attributes, colours:                   Attribute List.
* Attributes, from ANSI text:            Converting the Other Way.
* Attributes, introduction:              Attribute codes.
* Attributes, listing:                   Attribute List.
* Attributes, to colour text:            Converting to Colour Text.
* Attributes, to HTML:                   Converting to HTML.
* Attributes, to plain text:             Converting to Plain Text.
* Author of entries:                     From line.
* BBS, abuse:                            Privileges and Bans.
* BBS, access control lists:             ACLs.
* BBS, ACLs:                             ACLs.
* BBS, administration:                   MBBS Administration.
* BBS, bans:                             Privileges and Bans.
* BBS, client:                           MBBS Invocation.
* BBS, configuration:                    MBBS Configuration.
* BBS, external users:                   External Users.
* BBS, internal users:                   External Users.
* BBS, messaging:                        User Messaging.
* BBS, privileges:                       Privileges and Bans.
* BBS, setting ownership:                MGID.
* BBS, user level:                       Privileges and Bans.
* BBS, user-to-user messaging:           User Messaging.
* Bold text:                             Attribute List.
* Colour text:                           Attribute List.
* Colour text, converting to:            Converting to Colour Text.
* Comment files:                         COMMENTFILE.
* Conditional menu code:                 IF.
* Conversion, to attributes:             Converting the Other Way.
* Conversion, to colour text:            Converting to Colour Text.
* Conversion, to HTML:                   Converting to HTML.
* Conversion, to plain text:             Converting to Plain Text.
* Datestamps:                            Message line.
* Datestamps, generating:                MTIME.
* Directories, listed:                   Listed Directories.
* Editor:                                MTE.
* Environment variables:                 Menu Environment.
* External users:                        External Users.
* Files, viewing:                        File Viewer.
* Flashing text:                         Attribute List.
* From: line:                            From line.
* Header, author:                        From line.
* Header, date:                          Message line.
* Header, from:                          From line.
* Header, recipient:                     To line.
* Header, subject:                       Subject line.
* Header, to:                            To line.
* HTML, converting to:                   Converting to HTML.
* Internal users:                        External Users.
* Last Access, introduction:             Last Access.
* LDB, introduction:                     Last Access.
* LDB, setup & details:                  Last Access Database.
* Listed directories:                    Listed Directories.
* Logging access:                        LOG.
* Logs, truncating:                      MTRUNC.
* Menu code, access control lists:       ACLs.
* Menu code, access logging:             LOG.
* Menu code, ACLs:                       ACLs.
* Menu code, commands:                   Menu Commands.
* Menu code, conditional:                IF.
* Menu code, default path:               PATHNAME.
* Menu code, entries:                    Menu Entries.
* Menu code, entry status:               STATUS.
* Menu code, environment:                Menu Environment.
* Menu code, listed directories:         Listed Directories.
* Menu code, listing:                    Menu Command List.
* Menu code, overview:                   Menu Code.
* Menu code, title file:                 TITLE.
* Menus, introduction:                   Menus.
* Menus, scanning:                       Scanning.
* Menus, viewing:                        Menu Viewer.
* Message of the day:                    VIEW.
* Message recipients:                    To line.
* Message: line:                         Message line.
* Messaging, user-to-user:               User Messaging.
* MOTD:                                  VIEW.
* Plain text, converting to:             Converting to Plain Text.
* Reverse video text:                    Attribute List.
* Scanning:                              Scanning.
* Scrollback buffers, viewing:           Converting the Other Way.
* Separators:                            Message line.
* Special lines:                         Special lines.
* Standout text:                         Attribute List.
* Storing author name:                   From line.
* Subject heading:                       Subject line.
* Subject: line:                         Subject line.
* Terminal emulation:                    Converting the Other Way.
* Text editor:                           MTE.
* To: line:                              To line.
* Truncating logs:                       MTRUNC.
* U2Us:                                  User Messaging.
* Underlined text:                       Attribute List.
* User-to-user messaging:                User Messaging.
* Users, external:                       External Users.
* Users, internal:                       External Users.
* Variables, environment:                Menu Environment.
* Viewer, file:                          File Viewer.
* Viewer, menu:                          Menu Viewer.
* Viewfiles:                             VIEW.
* Viewfiles, compulsory:                 VIEWALWAYS.
* VT100 emulation:                       Converting the Other Way.



Tag Table:
Node: Top962
Node: Overview5476
Node: Concepts7146
Node: Attribute codes7989
Node: Special lines9008
Node: Message line9657
Node: From line11210
Node: Subject line12335
Node: To line12712
Node: Menus13060
Node: Last Access13682
Node: MCONV14478
Node: MCONV Overview15263
Node: MCONV Invocation16385
Node: Converting to Plain Text21523
Node: Converting to Colour Text22510
Node: Converting to HTML22937
Node: Converting the Other Way23842
Node: A note on menus24896
Node: MVIEW25757
Node: MVIEW Invocation26427
Node: File Viewer29315
Node: Last Access Database30069
Node: Menu Viewer31083
Node: Scanning31858
Node: MBBS32544
Node: MBBS Invocation33367
Node: MBBS Administration36056
Node: MBBS Configuration38135
Node: ACLs45162
Node: User Messaging46669
Node: Privileges and Bans48099
Node: External Users49841
Node: MGID52662
Node: MTIME53263
Node: MTRUNC53925
Node: MTE55719
Node: Menu Code56849
Node: Menu Entries57657
Node: Menu Commands60959
Node: COMMENTFILE62698
Node: HEIGHT63187
Node: IF63455
Node: LINE66556
Node: LOG66934
Node: OPTIONS67858
Node: PATHNAME68188
Node: QUIT68828
Node: SETENV69176
Node: STATUS69618
Node: TEXT72038
Node: TITLE72235
Node: VIEW72796
Node: VIEWALWAYS73308
Node: Menu Environment73696
Node: Listed Directories75345
Node: Examples77962
Node: Session Log Example78427
Node: HTMLification Example79416
Node: Offline Diary Example80030
Node: General Example80972
Node: Reporting Bugs83030
Node: Attribute List83465
Node: Menu Command List84838
Node: Concept Index86883

End Tag Table
