MCONV package:

[Top] | [Contents] | [Index] | [ ? ]

# MCONV package

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.

> 1. Overview |  | Overview of the whole `mconv` package.
> 2. Concepts |  | Concepts behind text formatting and menu code.
> 3. MCONV |  | The conversion program, `mconv`.
> 4. MVIEW |  | The file and menu viewer, `mview`.
> 5. MBBS |  | The bulletin board client, `mbbs`.
> 6. MGID |  | A small utility for changing the GID of files.
> 7. MTIME |  | A small utility to write datestamps.
> 8. MTRUNC |  | A small utility for truncating log files.
> 9. MTE |  | The MCONV text editor.
> 10. Menu Code |  | Preparing and tailoring menus.
> 11. Examples |  | Example uses of `mconv` and `mview`.

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

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

> The conversion program, `mconv`

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

> The file and menu viewer, `mview`

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

> The BBS, `mbbs`

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

> Menu code documentation

> 10.1 Menu Entries |  | How a menu entry is defined.
> 10.2 Menu Commands |  | Altering entries and changing the menu properties.
> 10.2.1 .COMMENTFILE |  | Associate a separate comment file with an entry.
> 10.2.2 .HEIGHT |  | Ignored.
> 10.2.3 .IF |  | Conditional menu code.
> 10.2.4 .LINE |  | Fill a line with text.
> 10.2.5 .LOG |  | Log accesses to a file.
> 10.2.6 .OPTIONS |  | Ignored.
> 10.2.7 .PATHNAME |  | Set the path prefixing all subsequent filenames.
> 10.2.8 .QUIT |  | Stop processing the menu immediately.
> 10.2.9 .SETENV |  | Ignored.
> 10.2.10 .STATUS |  | Set the status of this or subsequent entries.
> 10.2.11 .TEXT |  | Centre a line of text.
> 10.2.12 .TITLE |  | Give the current menu a title.
> 10.2.13 .VIEW |  | Associate a viewfile with an entry.
> 10.2.14 .VIEWALWAYS |  | Associate a compulsory viewfile with an entry.
> 10.3 Menu Environment |  | Environment variables available to menu code.
> 10.4 Listed Directories |  | Menus generated from directory contents.

> Examples

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.1 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. See section Attribute List.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

> 2.2.1 `Message` line |  | Mark the start of an entry, optionally giving its date.
> 2.2.2 `From` line |  | Specify the author of an entry.
> 2.2.3 `Subject` line |  | Optionally specify a subject heading for an entry.
> 2.2.4 `To` line |  | Optionally specify the intended recipient(s) of a message.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 2.2.1 `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`. See section 7. 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` (see section 4. MVIEW), automatically prefixes your text with a datestamp.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 2.2.2 `From` line

Lines beginning with `From:` mark the author of an entry in a file, and should go just after a datestamp line (see section 2.2.1 `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`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 2.2.3 `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 (see section 2.1 Attribute codes) to outline your headings.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 2.2.4 `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 (see section 2.2.2 `From` line). The word `To:` should be followed by one or more bracketed usernames, which will be shown in green.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.3 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. See section 10. Menu Code.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.4 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 (see section 4.3 Last Access Database). Your last access database, or LDB, also stores information about subscription to menus and files (see section 4.5 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.1 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 (see section 3.6 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 (see section 3.4 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. See section 3.3 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. See section 3.5 Converting to HTML.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.2 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 (see section 2.1 Attribute codes), datestamps (see section 2.2 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 (see section 2.4 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`. See section 3.6 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. See section 2.2.2 `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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.3 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 (see section 2.1 Attribute codes) will be stripped and special lines (see section 2.2 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.4 Converting to Colour Text

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.5 Converting to HTML

If the `-h` flag is passed instead of `-t` in the previous examples (see section 3.3 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 (see section 3.7 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.6 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` (see section `Screen' in Screen) logs readable, or can even function as input to a BBS robot or something.

See section 11. Examples, for examples.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.7 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. See section 2.4 Last Access, for more information about LDB files.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 4.1 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. See section 2.4 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 4.2 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` - see section `Gzip' in Gzip). 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 4.3 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 (see section 4.4 Menu Viewer) and the section on scanning (see section 4.5 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'`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 4.4 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 (see section 4.5 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. See section 10. Menu Code.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 5. 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. See section 4. MVIEW.

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.1 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. See section 5.7 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.3 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. See section 5.7 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.4 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 (see section 10.4 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 5.7 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 (see section 5.6 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. See section 5.3 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 (see section 5.1 MBBS Invocation), displays a welcome message, and runs the BBS in external mode.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 7. 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 (see section 12. Reporting Bugs).

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

> 10.1 Menu Entries |  | How a menu entry is defined.
> 10.2 Menu Commands |  | Altering entries and changing the menu properties.
> 10.3 Menu Environment |  | Environment variables available to menu code.
> 10.4 Listed Directories |  | Menus generated from directory contents.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 10.1 Menu Entries

Menu entries take the following form:

    title
    key type file

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

`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. See section 10.4 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; See section 10.3 Menu Environment.

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

  Note that inside `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. See section 5.3 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. See section 5.4 ACLs.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 10.2 Menu Commands

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

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

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

> 10.2.1 .COMMENTFILE |  | Associate a separate comment file with an entry.
> 10.2.2 .HEIGHT |  | Ignored.
> 10.2.3 .IF |  | Conditional menu code.
> 10.2.4 .LINE |  | Fill a line with text.
> 10.2.5 .LOG |  | Log accesses to a file.
> 10.2.6 .OPTIONS |  | Ignored.
> 10.2.7 .PATHNAME |  | Set the path prefixing all subsequent filenames.
> 10.2.8 .QUIT |  | Stop processing the menu immediately.
> 10.2.9 .SETENV |  | Ignored.
> 10.2.10 .STATUS |  | Set the status of this or subsequent entries.
> 10.2.11 .TEXT |  | Centre a line of text.
> 10.2.12 .TITLE |  | Give the current menu a title.
> 10.2.13 .VIEW |  | Associate a viewfile with an entry.
> 10.2.14 .VIEWALWAYS |  | Associate a compulsory viewfile with an entry.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 10.2.2 .HEIGHT

Syntax:

    HEIGHT <lines> [IF ...]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 10.2.3 .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. See section 5.4 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. See section 10.3 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 10.2.10 .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 (see section 2.2.2 `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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 10.2.11 .TEXT

Syntax:

    .TEXT [<text>]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 10.2.14 .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` (see section 10.2.13 .VIEW), but display it every time the user enters the file or menu, regardless as to whether it has been updated.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 10.3 Menu Environment

Environment variables may be referenced from a menu file by writing them as you would in the shell; i.e. if you want the value of environment variable FOO substituted somewhere, write `$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 (see section 10.1 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 10.4 Listed Directories

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

`~`
  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. See section 5.4 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 12. 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 11. Examples

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

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# Concept Index

Jump to: | . A B C D E F H I L M P R S T U V

| Index Entry | Section
. |  |
| .COMMENTFILE | 10.2.1 .COMMENTFILE
| .HEIGHT | 10.2.2 .HEIGHT
| .IF | 10.2.3 .IF
| .LINE | 10.2.4 .LINE
| .LOG | 10.2.5 .LOG
| .OPTIONS | 10.2.6 .OPTIONS
| .PATHNAME | 10.2.7 .PATHNAME
| .QUIT | 10.2.8 .QUIT
| .SETENV | 10.2.9 .SETENV
| .STATUS | 10.2.10 .STATUS
| .TEXT | 10.2.11 .TEXT
| .TITLE | 10.2.12 .TITLE
| .VIEW | 10.2.13 .VIEW
| .VIEWALWAYS | 10.2.14 .VIEWALWAYS
A |  |
| Access Control Lists | 5.4 ACLs
| Access logs | 10.2.5 .LOG
| ACLs | 5.4 ACLs
| Attributes, colours | Attribute List
| Attributes, from ANSI text | 3.6 Converting the Other Way
| Attributes, introduction | 2.1 Attribute codes
| Attributes, listing | Attribute List
| Attributes, to colour text | 3.4 Converting to Colour Text
| Attributes, to HTML | 3.5 Converting to HTML
| Attributes, to plain text | 3.3 Converting to Plain Text
| Author of entries | 2.2.2 `From` line
B |  |
| BBS, abuse | 5.6 Privileges and Bans
| BBS, access control lists | 5.4 ACLs
| BBS, ACLs | 5.4 ACLs
| BBS, administration | 5.2 MBBS Administration
| BBS, bans | 5.6 Privileges and Bans
| BBS, client | 5.1 MBBS Invocation
| BBS, configuration | 5.3 MBBS Configuration
| BBS, external users | 5.7 External Users
| BBS, internal users | 5.7 External Users
| BBS, messaging | 5.5 User Messaging
| BBS, privileges | 5.6 Privileges and Bans
| BBS, setting ownership | 6. MGID
| BBS, user level | 5.6 Privileges and Bans
| BBS, user-to-user messaging | 5.5 User Messaging
| Bold text | Attribute List
C |  |
| Colour text | Attribute List
| Colour text, converting to | 3.4 Converting to Colour Text
| Comment files | 10.2.1 .COMMENTFILE
| Conditional menu code | 10.2.3 .IF
| Conversion, to attributes | 3.6 Converting the Other Way
| Conversion, to colour text | 3.4 Converting to Colour Text
| Conversion, to HTML | 3.5 Converting to HTML
| Conversion, to plain text | 3.3 Converting to Plain Text
D |  |
| Datestamps | 2.2.1 `Message` line
| Datestamps, generating | 7. MTIME
| Directories, listed | 10.4 Listed Directories
E |  |
| Editor | 9. MTE
| Environment variables | 10.3 Menu Environment
| External users | 5.7 External Users
F |  |
| Files, viewing | 4.2 File Viewer
| Flashing text | Attribute List
| From: line | 2.2.2 `From` line
H |  |
| Header, author | 2.2.2 `From` line
| Header, date | 2.2.1 `Message` line
| Header, from | 2.2.2 `From` line
| Header, recipient | 2.2.4 `To` line
| Header, subject | 2.2.3 `Subject` line
| Header, to | 2.2.4 `To` line
| HTML, converting to | 3.5 Converting to HTML
I |  |
| Internal users | 5.7 External Users
L |  |
| Last Access, introduction | 2.4 Last Access
| LDB, introduction | 2.4 Last Access
| LDB, setup & details | 4.3 Last Access Database
| Listed directories | 10.4 Listed Directories
| Logging access | 10.2.5 .LOG
| Logs, truncating | 8. MTRUNC
M |  |
| Menu code, access control lists | 5.4 ACLs
| Menu code, access logging | 10.2.5 .LOG
| Menu code, ACLs | 5.4 ACLs
| Menu code, commands | 10.2 Menu Commands
| Menu code, conditional | 10.2.3 .IF
| Menu code, default path | 10.2.7 .PATHNAME
| Menu code, entries | 10.1 Menu Entries
| Menu code, entry status | 10.2.10 .STATUS
| Menu code, environment | 10.3 Menu Environment
| Menu code, listed directories | 10.4 Listed Directories
| Menu code, listing | Menu Command List
| Menu code, overview | 10. Menu Code
| Menu code, title file | 10.2.12 .TITLE
| Menus, introduction | 2.3 Menus
| Menus, scanning | 4.5 Scanning
| Menus, viewing | 4.4 Menu Viewer
| Message of the day | 10.2.13 .VIEW
| Message recipients | 2.2.4 `To` line
| Message: line | 2.2.1 `Message` line
| Messaging, user-to-user | 5.5 User Messaging
| MOTD | 10.2.13 .VIEW
P |  |
| Plain text, converting to | 3.3 Converting to Plain Text
R |  |
| Reverse video text | Attribute List
S |  |
| Scanning | 4.5 Scanning
| Scrollback buffers, viewing | 3.6 Converting the Other Way
| Separators | 2.2.1 `Message` line
| Special lines | 2.2 Special lines
| Standout text | Attribute List
| Storing author name | 2.2.2 `From` line
| Subject heading | 2.2.3 `Subject` line
| Subject: line | 2.2.3 `Subject` line
T |  |
| Terminal emulation | 3.6 Converting the Other Way
| Text editor | 9. MTE
| To: line | 2.2.4 `To` line
| Truncating logs | 8. MTRUNC
U |  |
| U2Us | 5.5 User Messaging
| Underlined text | Attribute List
| User-to-user messaging | 5.5 User Messaging
| Users, external | 5.7 External Users
| Users, internal | 5.7 External Users
V |  |
| Variables, environment | 10.3 Menu Environment
| Viewer, file | 4.2 File Viewer
| Viewer, menu | 4.4 Menu Viewer
| Viewfiles | 10.2.13 .VIEW
| Viewfiles, compulsory | 10.2.14 .VIEWALWAYS
| VT100 emulation | 3.6 Converting the Other Way

Jump to: | . A B C D E F H I L M P R S T U V

[Top] | [Contents] | [Index] | [ ? ]

# Table of Contents

1. Overview
2. Concepts

2.1 Attribute codes
2.2 Special lines

2.2.1 `Message` line
2.2.2 `From` line
2.2.3 `Subject` line
2.2.4 `To` line

2.3 Menus
2.4 Last Access

3. MCONV

3.1 MCONV Overview
3.2 MCONV Invocation
3.3 Converting to Plain Text
3.4 Converting to Colour Text
3.5 Converting to HTML
3.6 Converting the Other Way
3.7 A note on menus

4. MVIEW

4.1 MVIEW Invocation
4.2 File Viewer
4.3 Last Access Database
4.4 Menu Viewer
4.5 Scanning

5. MBBS

5.1 MBBS Invocation
5.2 MBBS Administration
5.3 MBBS Configuration
5.4 ACLs
5.5 User Messaging
5.6 Privileges and Bans
5.7 External Users

6. MGID
7. MTIME
8. MTRUNC
9. MTE
10. Menu Code

10.1 Menu Entries
10.2 Menu Commands

10.2.1 .COMMENTFILE
10.2.2 .HEIGHT
10.2.3 .IF
10.2.4 .LINE
10.2.5 .LOG
10.2.6 .OPTIONS
10.2.7 .PATHNAME
10.2.8 .QUIT
10.2.9 .SETENV
10.2.10 .STATUS
10.2.11 .TEXT
10.2.12 .TITLE
10.2.13 .VIEW
10.2.14 .VIEWALWAYS

10.3 Menu Environment
10.4 Listed Directories

11. Examples

11.1 Session Log Example
11.2 HTMLification Example
11.3 Offline Diary Example
11.4 General Example

12. Reporting Bugs
Attribute List
Menu Command List
Concept Index

[Top] | [Contents] | [Index] | [ ? ]

# Short Table of Contents

> 1. Overview
> 2. Concepts
> 3. MCONV
> 4. MVIEW
> 5. MBBS
> 6. MGID
> 7. MTIME
> 8. MTRUNC
> 9. MTE
> 10. Menu Code
> 11. Examples
> 12. Reporting Bugs
> Attribute List
> Menu Command List
> Concept Index

[Top] | [Contents] | [Index] | [ ? ]

# About this document

This document was generated by Andrew Wood on June, 12 2004 using texi2html

The buttons in the navigation panels have the following meaning:

Button | Name | Go to | From 1.2.3 go to
--- | --- | --- | ---
[ < ] | Back | previous section in reading order | 1.2.2
[ > ] | Forward | next section in reading order | 1.2.4
[ << ] | FastBack | previous or up-and-previous section | 1.1
[ Up ] | Up | up section | 1.2
[ >> ] | FastForward | next or up-and-next section | 1.3
[Top] | Top | cover (top) of document |
[Contents] | Contents | table of contents |
[Index] | Index | concept index |
[ ? ] | About | this page |

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

- 1. Section One

- 1.1 Subsection One-One

- ...

- 1.2 Subsection One-Two

- 1.2.1 Subsubsection One-Two-One
- 1.2.2 Subsubsection One-Two-Two
- 1.2.3 Subsubsection One-Two-Three <== Current Position
- 1.2.4 Subsubsection One-Two-Four

- 1.3 Subsection One-Three

- ...

- 1.4 Subsection One-Four

This document was generated by Andrew Wood on June, 12 2004 using texi2html It was then munged by a Perl script to stop it looking horrible in Lynx.