\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename mconv.info
@settitle MCONV package
@c %**end of header

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

@ignore
Permission is granted to process this file through TeX and print the results,
provided the printed document carries a copying permission notice identical to
this one except for the removal of this paragraph (this paragraph not being
relevant to the printed manual).

@end ignore
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.

@end ifinfo

@titlepage
@title MCONV/MVIEW 1.2.7
@subtitle BBS, text converter and menu viewer
@author Andrew Wood
@page
@vskip 0pt plus 1filll
Copyright @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.
@end titlepage

@dircategory Miscellaneous
@direntry
* Mconv: (mconv).      BBS, text converter and menu viewer
@end direntry

@ifinfo
@node Top, Overview, , (dir)
@top Mconv

The @code{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 @code{mconv} - the command-line converter - and
@code{mview} - a full-screen viewer for both files and menus.

Also included is a fully functional BBS based on the @code{mview} code,
called @code{mbbs}.

This edition of the @cite{Mconv manual}, last updated 5 August 2003,
documents @code{mconv} version 1.2.7.
@end ifinfo

@menu
* Overview::           Overview of the whole @code{mconv} package.
* Concepts::           Concepts behind text formatting and menu code.
* MCONV::              The conversion program, @code{mconv}.
* MVIEW::              The file and menu viewer, @code{mview}.
* MBBS::               The bulletin board client, @code{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 @code{mconv} and @code{mview}.

* Reporting Bugs::     How to report a problem with the @code{mconv} package.

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

* Concept Index::      Index of concepts.
@detailmenu

 --- 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 @code{mview} knows which files you've visited.

The conversion program, @code{mconv}

* MCONV Overview::             What @code{mconv} does and why you'd want to.
* MCONV Invocation::           Options that @code{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 @samp{-m} switch.

The file and menu viewer, @code{mview}

* MVIEW Invocation::      Options that @code{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, @code{mbbs}

* MBBS Invocation::       How to run @code{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 @sc{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.
@end detailmenu
@end menu

@node Overview, Concepts, Top, Top
@chapter Overview

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

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

Files viewed with @code{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:

@itemize @bullet
@item
Keeping your Mono diary offline

@item
Doing your scan quickly, dumping to a log to view later

@item
Converting the files in your section to @sc{HTML}

@item
Organising projects on your home system

@item
Building a BBS
@end itemize

These are just suggestions.  Since @code{mconv} can convert from @sc{ANSI}
colour text to @code{mbbs} attribute files, from @code{mbbs} attribute files to
plain text, @sc{ANSI} colour text, and @sc{HTML}, and from @code{mbbs} menu
files to text or @sc{HTML}, and @code{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 @uref{http://mconv.sourceforge.net/} - the @code{mconv} package
home page - for more information.

@node Concepts, MCONV, Overview, Top
@chapter Concepts

The @code{mconv} package deals with @code{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 @code{mview} and @code{mbbs} know which files you've visited.
@end menu

@node Attribute codes, Special lines,  , Concepts
@section Attribute codes

@cindex Attributes, introduction

Any text in any file may be highlighted in bold or reverse, underlined, or
given a different colour.  To do this, character sequences called
@emph{attribute codes} are used.

An attribute code is an escape character (typically @kbd{^[} or @kbd{^]})
followed by another character signifying the attribute to be used.  In general,
an uppercase second character turns an attribute @emph{on}, and a lowercase
character turns it @emph{off}.  The exception to this rule is the colour
attribute code, which is always uppercase @kbd{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:

@example
This is some ^]Bbold text^]b.
@end example

This would be displayed as follows:

@example
This is some @strong{bold text}.
@end example

Full details of attribute codes are given later in this manual.
@xref{Attribute List}.

@node Special lines, Menus, Attribute codes, Concepts
@section Special lines

@cindex 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.
@end menu

@node Message line, From line,  , Special lines
@subsection @code{Message} line

@cindex Message: line
@cindex Datestamps
@cindex Header, date
@cindex Separators

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:

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

...is turned, by @code{mconv} and @code{mview}, into:

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

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 @code{time()} or by the
GNU @code{date} program with @samp{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 @code{Message:} lines for
any given date is @code{mtime}.  @xref{MTIME}.

Given a date as a parameter, @code{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 @key{A} key, in @code{mview}
(@pxref{MVIEW}), automatically prefixes your text with a datestamp.

@node From line, Subject line, Message line, Special lines
@subsection @code{From} line

@cindex From: line
@cindex Author of entries
@cindex Storing author name
@cindex Header, author
@cindex Header, from

Lines beginning with @code{From:} mark the author of an entry in a file,
and should go just after a datestamp line (@pxref{Message line}).

The text @code{From:} (including the colon and a trailing space) should be
followed by descriptive text known as the @emph{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 @key{I} key in @code{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 @code{From:} is shown in bold
green to distinguish it from the body of the message.

@code{From:} lines are automatically added just after the datestamp when adding
an entry with the @key{A} key in @code{mview}.

@node Subject line, To line, From line, Special lines
@subsection @code{Subject} line

@cindex Subject: line
@cindex Subject heading
@cindex Header, subject

Any text following a line beginning with @code{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 (@pxref{Attribute codes}) to
outline your headings.

@node To line,  , Subject line, Special lines
@subsection @code{To} line

@cindex To: line
@cindex Message recipients
@cindex Header, recipient
@cindex Header, to

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

@node Menus, Last Access, Special lines, Concepts
@section Menus

@cindex Menus, introduction

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 (@code{.}).  More
specific information about menu code is given later in this manual.
@xref{Menu Code}.

@node Last Access,  , Menus, Concepts
@section Last Access

@cindex Last Access, introduction
@cindex LDB, introduction

When using the file viewer @code{mview} and the BBS system @code{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 (@pxref{Last Access Database}).
Your last access database, or LDB, also stores information about subscription
to menus and files (@pxref{Scanning}).

If you are a user of the @code{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.

@node MCONV, MVIEW, Concepts, Top
@chapter MCONV

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

@menu
* MCONV Overview::             What @code{mconv} does and why you'd want to.
* MCONV Invocation::           Options that @code{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 @samp{-m} switch.
@end menu

@node MCONV Overview, MCONV Invocation,  , MCONV
@section MCONV Overview

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

Also, conversion from @code{ANSI} colour text to @code{mbbs} format text
(@pxref{Converting the Other Way}) can be done - the reverse of the above -
allowing session logs and scrollback buffers to be viewed with @code{mview}.

Converting to ANSI colour text (@pxref{Converting to Colour Text}) is perhaps
the least useful, given that it can be done interactively with the @code{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.  @xref{Converting to Plain Text}.

Finally, conversion to @sc{HTML} allows the creation of web pages from
@code{mbbs} files, especially in conjunction with the experimental Perl
script supplied with this package in the @file{extra/} directory.
@xref{Converting to HTML}.

@node MCONV Invocation, Converting to Plain Text, MCONV Overview, MCONV
@section MCONV Invocation

The general form for invocation is as follows:

@example
mconv [@var{options}] [@var{file}]...
@end example

This will concatenate all @var{file}s given, parse @code{mbbs} attribute codes,
and give the result on the standard output.  If no files are specified, or a
file called @file{-} is specified, the standard input is read.

The following options determine the way input data is processed:

@table @code
@item -f
@itemx --file-input
This is the default operation - each input file is assumed to be a normal
@code{mbbs} file, containing @code{mbbs} attribute codes
(@pxref{Attribute codes}), datestamps (@pxref{Special lines}), and so on.

The @code{-h}, @code{-t}, and @code{-c} options determine whether the output
is to be @sc{HTML}, plain text, or the default of coloured text.
@code{-y} and @code{-w} also modify the output.

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

The @code{-g} and @code{-w} options also modify the output, and @code{-d} and
@code{-n} specify whether to read an @sc{LDB} file to show subscription and
last access information in the output (@pxref{Last Access}).

@item -i
@itemx --menu-info
Each input file is assumed to contain @code{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
@code{-h}, @code{-t}, and @code{-c} options are ignored.

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

@item -a
@itemx --ansi-input
The input is assumed to be normal text containing ANSI colour codes and other
escape sequences.  It is always converted into normal @code{mbbs} attribute
format; the only other options which have any effect when used with @code{-a}
are the @code{-w} and @code{-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 @code{screen} into something to
be viewed by @code{mview}.  @xref{Converting the Other Way}.
@end table

The next few options determine the output format.

@table @code

@item -h
@itemx --html-output
(@code{-f} and @code{-m} only)

When processing files and menus, output @sc{HTML}.  The resultant @sc{HTML}
will be surrounded by a @code{<PRE>} tag, thus preserving the formatting.

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

@item -t
@itemx --text-output
@itemx --no-colour
(@code{-f} and @code{-m} only)

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

@item -c
@itemx --colour-output
(@code{-f} and @code{-m} only)
  
Menus and files are output as files containing @sc{ANSI} colour codes.
This is the default output format for @code{-f} and @code{-m} processing.
@end table

These options slightly modify the behaviour of the input parser:

@table @code

@item -y
@itemx --anonymous
(@code{-f} only)

Strip the account names from @code{From:} lines.  @xref{From line}.

@item -g
@itemx --guest
(@code{-m} and @code{-i} only)

Output the menu as a guest user would see it.

@item -d @var{FILE}
@itemx --ldb=@var{FILE}
(@code{-m} only)

Read last-access information from @var{FILE}.  This overrides any file
specified by the environment variables @code{MCONV_LDB} or @code{MVIEW_LDB}.

@item -n
@itemx --no-ldb
(@code{-m} only)

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

@item -u
@itemx --unbuffered
(standard input only)

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

@item -w @var{NUM}
@itemx --width=@var{NUM}
For file and menu input (@code{-f} and @code{-m}), change the number of columns
in the output from the default of 80 to @var{NUM}.  For @sc{ANSI} colour text
input (@code{-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
@code{COLUMNS}) to @var{NUM}.

@item -H @var{NUM}
@itemx --height=@var{NUM}
For @sc{ANSI} colour text input only (@code{-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 @code{LINES}) to @var{NUM}.
@end table

The last two options give information about the program.

@table @code
@item --help
Print a usage message on standard output and exit successfully.

@item -V
@itemx --version
Print version information on standard output and exit successfully.
@end table

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

@node Converting to Plain Text, Converting to Colour Text, MCONV Invocation, MCONV
@section Converting to Plain Text

@cindex Plain text, converting to
@cindex Attributes, to plain text
@cindex Conversion, to plain text

To convert from @code{mbbs} format to plain text, run a command like the
following:

@example
mconv -t < input.cm > output.txt
@end example

This will convert @file{input.cm} to @file{output.txt}.  Attributes
(@pxref{Attribute codes}) will be stripped and special lines
(@pxref{Special lines}) expanded.

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

@example
mconv -y -t < input.cm > output.txt
@end example

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 @code{-w} option.  For instance, to convert a file to
132 column text:

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

The two options @code{-y} and @code{-w} apply to coloured output and @sc{HTML}
output as well.

@node Converting to Colour Text, Converting to HTML, Converting to Plain Text, MCONV
@section Converting to Colour Text

@cindex Colour text, converting to
@cindex Attributes, to colour text
@cindex Conversion, to colour text

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

@node Converting to HTML, Converting the Other Way, Converting to Colour Text, MCONV
@section Converting to HTML

@cindex HTML, converting to
@cindex Attributes, to HTML
@cindex Conversion, to HTML

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

In the case of menu code (@pxref{A note on menus}), all menu options are turned
into relative @sc{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 @sc{HTML} menu generation is
supplied with this package, in the @file{extra/} directory.

@node Converting the Other Way, A note on menus, Converting to HTML, MCONV
@section Converting the Other Way

@cindex Scrollback buffers, viewing
@cindex Attributes, from ANSI text
@cindex Terminal emulation
@cindex VT100 emulation
@cindex Conversion, to attributes

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

To work properly, @code{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 @code{-w} and @code{-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 @code{mbbs}, which are erased
before being overwritten, do not appear in the output.

@code{mconv -a} can be used to make @code{screen}
(@pxref{Top, , Screen, screen, Screen}) logs readable, or can even
function as input to a BBS robot or something.

@xref{Examples}, for examples.

@node A note on menus,  , Converting the Other Way, MCONV
@section A note on menus

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

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

@table @code
@item -g
Display as user "guest" would see it.

@item -d FILE
Use LDB file @file{FILE} for last access information.

@item -n
Do not use an LDB file at all, even if one is specified by the environment
variable @code{MCONV_LDB} or @code{MVIEW_LDB}.
@end table

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

@node MVIEW, MBBS, MCONV, Top
@chapter MVIEW

The @code{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 @code{mbbs} instead.

@menu
* MVIEW Invocation::      Options that @code{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.
@end menu

@node MVIEW Invocation, File Viewer,  , MVIEW
@section MVIEW Invocation

The general form for invocation of the viewer @code{mview} is:

@example
mview [@var{OPTIONS}] @var{FILE}...
@end example

Each @var{FILE} specified will be displayed in turn.

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

@table @code
@item -m
@itemx --menu
Each specified file is to be displayed as a menu, not as a normal file.

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

@item -l @var{n}
@itemx --line=@var{n}
@itemx +@var{n}
Start the file viewer with line @var{n} at the bottom of the screen.

Note that @code{-l} and @code{--line} apply to @emph{all} files specified
on the command line, but @code{+@var{n}} only applies to those files specified
after it.

Also note that this option has no effect if the @code{-m} option is given.

@item -z
@itemx --bottom
Start at the bottom of each file.  This does not affect menu viewing.

@item -T
@item --top
Start at the top of each file (the default action if there is no @sc{LDB} entry
to use).  Again, this does not affect menu viewing.

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

@end table

The following options control the use of a database recording the files read
and the last position they were read at.  @xref{Last Access}.

@table @code
@item -d @var{file}
@itemx --ldb=@var{file}
Use @var{file} as a last-access database containing records of which files
have been looked at in the past.  If @var{file} does not exist, it will be
created.  Note that old records are never purged automatically; use the
@code{-p} option for that.

This option overrides the @code{MVIEW_LDB} environment variable.

@item -n
@itemx --no-ldb
Don't use a last-access database, even if one is specified in the
@code{MVIEW_LDB} environment variable.

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

@item -f @var{file}
@itemx --file=@var{file}
Pretend, for last access database purposes, that @var{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 @var{file}.

@end table

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

@table @code
@item -y
@itemx --anonymous
Account names are stripped from @code{From:} lines, leaving only the
namelines.

@item -r
@itemx --readonly
The files cannot be modified.

@item -e
@itemx --no-edit
Direct-editing is disallowed, though files can still be added to.

@end table

The last two options give information about the program.

@table @code
@item --help
Print a usage message on standard output and exit successfully.

@item -V
@itemx --version
Print version information on standard output and exit successfully.

@end table

@node File Viewer, Last Access Database, MVIEW Invocation, MVIEW
@section File Viewer

@cindex Files, viewing
@cindex Viewer, file

To view a file, do @samp{mview @var{file}}.  This will open @var{file} in the
full-screen viewer, with all editing enabled (depending on file ownership and
permissions).

If file's name ends in @file{.gz}, it is treated as a file compressed with GNU
zip (@code{gzip} - @pxref{Top, , Gzip, gzip, 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 (@samp{man mview}) or press @key{?} while viewing a file.

@node Last Access Database, Menu Viewer, File Viewer, MVIEW
@section Last Access Database

@cindex LDB, setup & details

Optionally, you can record your position in files by means of a last-access
database (@sc{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 @sc{LDB} file, you can either give its name with the
@samp{-d @var{file}} option or you can set the @code{MVIEW_LDB} environment
variable to point to the file you wish to use as an @sc{LDB}.

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

@sc{LDB} files also record which menus and files you are subscribed to - see
the menu viewer section (@pxref{Menu Viewer}) and the section on scanning
(@pxref{Scanning}) for more information about subscriptions.

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

@node Menu Viewer, Scanning, Last Access Database, MVIEW
@section Menu Viewer

@cindex Menus, viewing
@cindex Viewer, menu

To view a menu, do @samp{mview -m @var{file}}.  This will open file in the
full-screen menu viewer.  Note that, unlike in the case of the file viewer,
file must @emph{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 (@pxref{Scanning}) those entries
are skipped.  This is known as @dfn{unsubscribing}, and is done with the
@key{=} key.

For information about the key presses available in the viewer, see the
manual page (@samp{man mview}) or press @key{?} while viewing a menu.

Information about menu code and writing menus is given elsewhere in this
document.  @xref{Menu Code}.

@node Scanning,  , Menu Viewer, MVIEW
@section Scanning

@cindex Scanning
@cindex Menus, scanning

Menus may be @dfn{scanned} for new files.  This is triggered by hitting
@key{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
@key{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.

@node MBBS, MGID, MVIEW, Top
@chapter MBBS

The @code{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.  @xref{MVIEW}.

@menu
* MBBS Invocation::       How to run @code{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.
@end menu

@node MBBS Invocation, MBBS Administration,  , MBBS
@section MBBS Invocation

@cindex BBS, client

To run the @code{mbbs} BBS client, simply do:

@example
mbbs [OPTIONS...]
@end example

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

The following options can be used:

@table @code
@item -e
@itemx --external
Log in as an external user.  @xref{External Users}.  Useful in the login
script for the @code{bbs} external account; for instance the shell for a
@code{bbs} Unix account could be set to @code{/bbs/login.sh} which could
contain something like this:

@example
#!/bin/sh

PATH=/bin:/usr/bin:/usr/local/bin
export PATH

cat /bbs/issue.txt

bbs --external
@end example

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

@item -x
@itemx --xterm-title
Use the xterm title to display the current action.  This is the default if the
terminal type in @code{$TERM} is ``xterm''.

@item --no-xterm-title
Do not use the xterm title to display the current action.

@item -c
@itemx --no-colours
@itemx --monochrome
Do not output any colour attributes - view everything in black and white.

@item -s
@itemx --scan
Perform a scan (like pressing @key{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.

@item --help
Print a usage message on standard output and exit successfully.

@item -V
@itemx --version
Print version information on standard output and exit successfully.
@end table

The following environment variables will be read:

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

@item ACTION_FILE
If the file referred to by @code{$ACTION_FILE} exists and is writable when
@code{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.

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

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

@node MBBS Administration, MBBS Configuration, MBBS Invocation, MBBS
@section MBBS Administration

@cindex BBS, administration

To begin with, it is probably best to copy the example configuration and system
files which came with the package in the @code{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 @code{mbbs}, you
get to grips with menu coding and the ins and outs of the menu/file viewer,
@code{mview}.

When @code{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 @key{ESCAPE} menu, the
system logging directories, the location of the options (@key{ESCAPE} @key{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 @key{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, @code{mbbs}, and the GID setting utility, @code{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.

@node MBBS Configuration, ACLs, MBBS Administration, MBBS
@section MBBS Configuration

@cindex BBS, configuration

The global configuration file for @code{mbbs} should be placed in
@code{/usr/local/etc}, @code{/etc}, or whichever @code{etc/} directory is
appropriate to the configuration you chose with the @code{./configure} script
when compiling.  Its filename should be @code{bbsrc} or @code{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:

@table @code
@item root
This is the top-level directory for the BBS system.  Any subsequent filenames
with @code{$} in them will have the @code{$} expanded to the value of this
key. For example:

@example
root /bbs
main $/main.mn
@end example

This will set the key "@code{main}" to @code{/bbs/main.mn}.

@item main
This is the location of the main menu, which is the first thing that a user
will see on running @code{mbbs}.

@item special
This is the location of the menu that is to appear when the user presses
@key{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.

@item options
This is the location of the menu that is to appear when the user presses
@key{ESCAPE} then @key{O}.  This menu should be kept pretty much the same as
the example supplied for it to work properly.

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

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

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

@item edit
This is the filename template for a user's temporary edit file, used when
adding to a file with the @key{A} key.  The character @code{~} will be
expanded to the current user's home directory.

@item 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).

@item u2u
This is the directory in which to store files relating to user-to-user
messaging.

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

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

@item 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 @code{u2uomax}.
Default value: 50.

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

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

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

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

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

@item addlog
@itemx dellog
@itemx editlog
@itemx runlog
@itemx maillog
@itemx 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 @key{M}, or
the exiting of an @code{mbbs} client.

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

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

@item 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 @code{.IF USER user/group/} construct in menu code.

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

@item extlim
The maximum number of users allowed on the BBS before external access is
denied.  @xref{External Users}.

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

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

@item 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 @code{/bin/false} would allow the
command lines @code{/bin/false}, @code{/bin/falsefoo}, and so on.

@item nolog
This is a kludge to allow the author to keep files from different BBSes
inside an @code{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.

@item 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.
@end table

@node ACLs, User Messaging, MBBS Configuration, MBBS
@section ACLs

@cindex BBS, access control lists
@cindex BBS, ACLs
@cindex Menu code, access control lists
@cindex Menu code, ACLs
@cindex Access Control Lists
@cindex ACLs

Users writing menu code for use in @code{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 "@code{x.cm}" which is
supposed to be marked @code{.STATUS ANONYMOUS}, a malicious user "a" cannot
write menu code which links to "@code{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 "@code{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 (@pxref{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.

@node User Messaging, Privileges and Bans, ACLs, MBBS
@section User Messaging

@cindex BBS, messaging
@cindex BBS, user-to-user messaging
@cindex Messaging, user-to-user
@cindex User-to-user messaging
@cindex U2Us

Users may send each other messages in @code{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 @key{S} in a file and selecting the edit you
wish to reply directly to, or by pressing @key{ESC} @key{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 @key{ESC} @key{R} then @key{M}) before logging out if you want
to keep a copy.

@node Privileges and Bans, External Users, User Messaging, MBBS
@section Privileges and Bans

@cindex BBS, privileges
@cindex BBS, bans
@cindex BBS, abuse
@cindex BBS, user level

Since any communications system is open to abuse, @code{mbbs} has a system of
privileges and bans.

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

@table @code
@item D - Disconnect Users
Allow the user to disconnect any other user by pressing @key{D} while examining
them.

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

@end table

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

@table @code
@item N - Alter Nameline
The user is not allowed to change their nameline with @key{ESC} @key{O}
@key{N}.

@item M - Mail Files
The user is not allowed to mail any files to themselves.

@item 2 - Messages
The user cannot send messages.

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

@item B - Full Ban
The user cannot log into the BBS at all.

@end table

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

However, a user's level - @code{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.

@node External Users,  , Privileges and Bans, MBBS
@section External Users

@cindex BBS, external users
@cindex BBS, internal users
@cindex Users, internal
@cindex Users, external
@cindex External users
@cindex Internal 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
- @code{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 @code{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 @code{B} in their
@code{BBS_BANS} UDB field (@pxref{Privileges and Bans}).

External accounts, on the other hand, exist entirely on the BBS.  External
users, such as @code{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 @code{extlim} or more users on the BBS, no more external logins
are allowed.  @xref{MBBS Configuration}.

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

@example
#!/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
@end example

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 @code{/home/me/inetd.conf} containing this:

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

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

@example
#!/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
@end example

Change the paths as necessary - basically this just sets the
@code{REMOTE_HOST} environment variable (@pxref{MBBS Invocation}), displays
a welcome message, and runs the BBS in external mode.

@node MGID, MTIME, MBBS, Top
@chapter MGID

@cindex BBS, setting ownership

The @code{mgid} utility simply sets the group ID of all files it is given
to the same as that of @code{mgid} and @code{mbbs}.  If you are running a
BBS system using a setgid @code{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:

@example
touch newfile.cm
mgid newfile.cm
chmod 660 newfile.cm
@end example

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

@node MTIME, MTRUNC, MGID, Top
@chapter MTIME

@cindex Datestamps, generating

The @code{mtime} utility allows the generation of arbitrary datestamps, to
be used in files viewed with @code{mview} or @code{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 (@pxref{Reporting Bugs}).

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

@node MTRUNC, MTE, MTIME, Top
@chapter MTRUNC

@cindex Logs, truncating
@cindex Truncating logs

The @code{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 @code{mtrunc} is:

@example
mtrunc [@var{OPTIONS}] @var{FILE}
@end example

Only one @var{FILE} must be specified.  The following options are available:

@table @code
@item --maxsize=@var{MAXSIZE}
@itemx --max=@var{MAXSIZE}
@itemx -m @var{MAXSIZE}
Truncate the file if it is larger than @var{MAXSIZE} bytes.  @var{MAXSIZE} may
optionally be followed by B, K, or M to denote bytes, kilobytes and megabytes
respectively.

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

@item --archive=@var{ARCHIVE}
@itemx -a @var{ARCHIVE}
Append any data to @var{ARCHIVE} before removing it from @var{FILE}.  The
default is to silently discard truncated data.

@item --commentfile
@itemx -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 `@code{Message:}' will be left
as it is.

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

@item --help
Print a usage message on standard output and exit successfully.

@item --version
@itemx -V
Print version information on standard output and exit successfully.

@end table

@node MTE, Menu Code, MTRUNC, Top
@chapter MTE

@cindex Editor
@cindex Text editor

The MCONV Text Editor is the one which is used internally by @code{mconv}.
You can use it outside the BBS by using @code{mte @var{FILE}} to edit
@var{FILE}.

In the editor, typing @code{.} on a line by itself and then hitting
@key{RETURN} will exit and save any changes.  Typing @code{.quit} then
@key{RETURN} will exit WITHOUT saving any changes.

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

@code{mte} recognises the following options on the command line:

@table @code
@item --help
Print a usage message on standard output and exit successfully.

@item --version
@itemx -V
Print version information on standard output and exit successfully.

@end table

Note that the environment variable @code{$EDITOR_OPTIONS} is also read. It
may contain the following characters:

@table @code
@item i
Insert mode off.

@item I
Insert mode on.

@item a
Autoindent mode off.

@item A
Autoindent mode on.

@item w
Word wrapping off.

@item W
Word wrapping on.

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

@end table

@node Menu Code, Examples, MTE, Top
@chapter Menu Code

@cindex Menu code, overview

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.
@end menu

@node Menu Entries, Menu Commands,  , Menu Code
@section Menu Entries

@cindex Menu code, entries

Menu entries take the following form:

@example
@var{title}
@var{key} @var{type} @var{file}
@end example

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

@table @code
@item 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 @code{<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.

@item B
Binary - cannot be viewed directly.

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

@item L
Listed Directory - generate a menu from the contents of the specified
directory. @xref{Listed Directories}.

@item M
Menu File - generate a menu from the contents of the menu file.

@item R
Read-only File - Not suitable for adding comments to.

@item 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; @xref{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 @code{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 @var{file} if it is listed in the special
"paths" file owned by the admin.  @xref{MBBS Configuration}.

@item T
Telnet Connection - connect to the machine @var{file} using Telnet.

@item X
Executable - run a subprocess @var{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.
@end table

For examples, look at the menus supplied with this package in the @code{extra}
directory.

Note that when using the BBS system @code{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.  @xref{ACLs}.

@node Menu Commands, Menu Environment, Menu Entries, Menu Code
@section Menu Commands

@cindex Menu code, 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.
@end menu

@node COMMENTFILE, HEIGHT,  , Menu Commands
@subsection .COMMENTFILE

@cindex .COMMENTFILE
@cindex Comment files

Syntax:

@example
.COMMENTFILE <@var{file}> [IF ...]
@end example

Associate the commentfile <@var{file}> with the next entry in the menu.  The
@code{.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.

@node HEIGHT, IF, COMMENTFILE, Menu Commands
@subsection .HEIGHT

@cindex .HEIGHT

Syntax:

@example
HEIGHT <@var{lines}> [IF ...]
@end example

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

@node IF, LINE, HEIGHT, Menu Commands
@subsection .IF

@cindex .IF
@cindex Menu code, conditional
@cindex Conditional menu code

Syntax:

@example
.IF [NOT] <@var{condition}> [&& ... | || ...]
.ELSE
.ENDIF
@end example

Execute the following commands only if the test after the @code{.IF} is true.
If the test is false, and an @code{.ELSE} is given, execute the commands
following the @code{.ELSE} instead.

Note that @code{.IF}s can be arbitrarily nested.

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

<@var{condition}> may be one of the following:

@table @code
@item ACLOK <@var{file}>
Returns true if <@var{file}> exists and linking to it would be allowed by the
ACL mechanism.  @xref{ACLs}.

@item ENVIRONMENT <@var{name}> <@var{value}> [...]
Returns true if the contents of the environment variable <@var{name}> are
equal to <@var{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.  @xref{Menu Environment}.

@item EXISTS <@var{file}>
Returns true if <@var{file}> exists.

@item EXTERNAL
Returns true if the user is an external or a guest.

@item GUEST
Returns true if the user is a guest.  See @code{EXTERNAL}.

@item HOSTNAME <@var{host}> [...]
Returns true if the client is running on the machine <@var{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.

@item LOCATION <@var{host}> [...]
Returns true if the user's location is <@var{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.

@item SITE <@var{address}> [...]
Returns true if the user's email address stub is within <@var{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.

@item TERMINAL <@var{type}> [...]
Returns true if the user's terminal type matches <@var{type}>.  More than one
value may be specified per line.  A value of * will match anything.

@item TTY <@var{tty}> [...]
Returns true if the user's tty matches <@var{tty}>, being of the form ttyp7.
More than one value may be specified per line.  A value of * will match
anything.

@item USER <@var{user}> [...]
Returns true if the user's account name matches <@var{user}>.  More than one
value may be specified per line; a value of * will match anything.

If <@var{user}> has a trailing slash it is treated as a userlist file, or
group (in @code{mbbs} only).  Groups of the form @code{foo/} refer to the
system group file @code{foo}, whereas groups of the form @code{foo/bar/} refer
to the user @code{foo}'s "@code{bar}" group.
@end table

@node LINE, LOG, IF, Menu Commands
@subsection .LINE

@cindex .LINE

Syntax:

@example
.LINE [<@var{text}>]
@end example

Use the <@var{text}> provided to fill a line of the display.

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

@node LOG, OPTIONS, LINE, Menu Commands
@subsection .LOG

@cindex .LOG
@cindex Menu code, access logging
@cindex Access logs
@cindex Logging access

Syntax:

@example
.[NOW|SUBSEQUENT] LOG <@var{option}> <@var{file}> [IF ...]
.LOG CLEAR
@end example

Associate a log file with the next menu entry, with the current menu if the
@code{NOW} option is given, or with all subsequent menu entries in this menu if
the @code{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
<@var{option}>, which may be as follows:

@table @code
@item 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.

@item USER
Log the nameline of the user.
@end table

@code{.LOG CLEAR} will clear any log files associated with the next menu entry.

@node OPTIONS, PATHNAME, LOG, Menu Commands
@subsection .OPTIONS

@cindex .OPTIONS

Syntax:

@example
.OPTIONS <@var{lines}> [IF ...]
@end example

Allocate <@var{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.

@node PATHNAME, QUIT, OPTIONS, Menu Commands
@subsection .PATHNAME

@cindex .PATHNAME
@cindex Menu code, default path

Syntax:

@example
.PATHNAME <@var{path}> [IF ...]
.PATHNAME
@end example

By default, filenames that are not absolutely specified will be searched for in
the directory containing the menu from which they were referenced.  The
@code{.PATHNAME} construct allows this default to be changed to the specified
<@var{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, @code{.PATHNAME} will restore the path back to the
default for that menu.

@node QUIT, SETENV, PATHNAME, Menu Commands
@subsection .QUIT

@cindex .QUIT

Syntax:

@example
.QUIT [IF ...]
@end example

Stop processing the menu at the current line.

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

@node SETENV, STATUS, QUIT, Menu Commands
@subsection .SETENV

@cindex .SETENV

Syntax:

@example
.SETENV <@var{var}>=<@var{value}>
@end example

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

This command is ignored in version 1.2.7.

@node STATUS, TEXT, SETENV, Menu Commands
@subsection .STATUS

@cindex .STATUS
@cindex Menu code, entry status

Syntax:

@example
.[NOW|SUBSEQUENT] STATUS [NOT] <@var{option}> [...] [IF ...]
@end example

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

<@var{option}> may take the following values:

@table @code
@item ADD
Permit the user to add comments to the file with @key{A}.

@item ANONYMOUS
Prevent the display of the author of each comment in the @code{From:} line
(@pxref{From line}), and the logging of comment added to the Add Log.

@item BARDELETE
Prevent the user from deleting comments from the file with @key{.}@key{D}.

@item BARINFO
Prevent the user from generating an index of the file with @key{I}.
In listed directories, prevents filenames being "prettified" and thus causes
filenames to be displayed as they really are.

@item BARLOG
Prevent the menu entry from being logged in any of the system logs.

@item BARMAIL
Prevent the user from mailing the file with @key{M}.

@item BARSENDREPLY
Prevent the user from sending a reply to an edit in the file.

@item CLEAR
Clear all previously set status values set for this entry.

@item DELETE
Permit the user to delete any comment from the file with @key{.}@key{D}.

@item EDIT
Permit the user to edit the entire file in the editor with @key{.}@key{A}.

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

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

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

@item NOLAST
Prevent last access information being stored for the entry.

@item NOSCAN
Cause the entry to be ignored on scanning.

@item NOTIME
Prevent the last modification time of the entry from being displayed
in the menu.

@item READONLY
Prevent the user from altering the file in any way.

@item 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.
@end table

@node TEXT, TITLE, STATUS, Menu Commands
@subsection .TEXT

@cindex .TEXT

Syntax:

@example
.TEXT [<@var{text}>]
@end example

Display the <@var{text}> centred.  Environment variables are expanded.

@node TITLE, VIEW, TEXT, Menu Commands
@subsection .TITLE

@cindex .TITLE
@cindex Menu code, title file

Syntax:

@example
.TITLE <@var{option}> <@var{file}> [IF ...]
@end example

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

@table @code
@item CENTRE
Centre the title file.

@item LEFT
Left justify the title file.
@end table

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.

@node VIEW, VIEWALWAYS, TITLE, Menu Commands
@subsection .VIEW

@cindex .VIEW
@cindex Viewfiles
@cindex Message of the day
@cindex MOTD

Syntax:

@example
.[NOW] VIEW <@var{file}> [IF ...]
@end example

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

@node VIEWALWAYS,  , VIEW, Menu Commands
@subsection .VIEWALWAYS

@cindex .VIEWALWAYS
@cindex Viewfiles, compulsory

Syntax:

@example
.[NOW] VIEWALWAYS <@var{file}> [IF ...]
@end example

Associate a view file with the next entry, or with the current menu if the
@code{NOW} option is given, as per @code{.VIEW} (@pxref{VIEW}), but display it
every time the user enters the file or menu, regardless as to whether it has
been updated.

@node Menu Environment, Listed Directories, Menu Commands, Menu Code
@section Menu Environment

@cindex Menu code, environment
@cindex Environment variables
@cindex Variables, 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
@var{FOO} substituted somewhere, write @code{$@var{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:

@table @code
@item ACCOUNT
@itemx MONO_ACCOUNT
The account name of the current user.  The second name is kept for
compatibility with Monochrome BBS.

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

@item KEYPATH
@itemx MONO_KEYPATH
The keypath of the current menu (@emph{not} of the current menu entry).  This
will be a blank string unless the menu is being viewed through @code{mbbs}.
Once again, the second name is for compatibility with Monochrome BBS.
@end table

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

@table @code
@item 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 @code{extra/utils} directory which came
with this package.
@end table

@node Listed Directories,  , Menu Environment, Menu Code
@section Listed Directories

@cindex Menu code, listed directories
@cindex Directories, listed
@cindex Listed directories

If you specify a menu entry of type L (@pxref{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:

@table @code
@item ~
Files with this extension are omitted from directory listings, as are
"hidden" files (beginning with a @code{.}).

@item .acl
Treated as a comment file (type C).  If you create a file of this type using
@key{.}@key{A} in a listed directory, it will be created group-readable but
not group-writeable, for security.  @xref{ACLs}.

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

@item .mn
Treated as a submenu file (type M).  If you create a file of this type using
@key{.}@key{A} in a listed directory, it will be created group-readable but
not group-writeable, for security.

@item .cm
Treated as a comment file (type C).  If it is group writable, the file will
be addable to other users in @code{mbbs}.

@item .cm.gz
@itemx .ro
@itemx .ro.gz
Treated as a readonly comment file (type C).

@item .txt
@itemx .txt.gz
Treated as a formatted file (type F).

@item .sh
@itemx .pl
@itemx .perl
Entered as an executable entry (type X).

@item .sp.sh
@itemx .sp.pl
Entered as a spooled executable entry (type S).

@item .html
@itemx .htm
Entered as an executable entry (type X), which when chosen will launch the web
browser @code{lynx} to point at the file.

@item .sc
Entered as an executable entry (type X), which when chosen will launch the
spreadsheet calculator @code{sc} on that file.
@end table

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
@code{src/display/menu/listed.c}.  Suggestions for additions would be
gratefully received - see @ref{Reporting Bugs}.

Please note that setting the @code{.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.

@node Examples, Reporting Bugs, Menu Code, Top
@chapter Examples

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

@menu
* Session Log Example::    Log a @sc{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.
@end menu

@node Session Log Example, HTMLification Example,  , Examples
@section Session Log Example

To record a telnet session for later viewing:

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

Or, without using any intermediary files:

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

...and to view that log:
   
@example
mview session.log
@end example

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 @code{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.

@node HTMLification Example, Offline Diary Example, Session Log Example, Examples
@section 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
@file{~/u1/foo.mn}, to a set of web pages in directory @file{bar}, using
@file{template.html} as an @sc{HTML} template:

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

Note that this is an @emph{experimental} script.  You should at least read
the comments at the top of it before trying it out.

@node Offline Diary Example, General Example, HTMLification Example, Examples
@section 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:

@example
mview diary.cm
@end example

Here, the diary file is assumed to be @file{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 - @code{mview} shows you how it will look).

For instance, uploading could be done something like this:

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

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

@node General Example,  , Offline Diary Example, Examples
@section 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:

@example
                 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
@end example

The source code for that menu looks something like this:

@example
.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]
@end example

As a generalised menu system, the applications are obviously as numerous as you
care to make them.
   
@node Reporting Bugs,  , Examples, Top
@chapter Reporting Bugs

Please report bugs to @email{mconv@@ivarch.com}.  Be sure
to include the word @code{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 @code{mconv} can always be found at its home page,
@url{http://mconv.sourceforge.net/}.

@node Attribute List, Menu Command List,  , Top
@unnumbered Attribute List

@cindex Attributes, listing
@cindex Bold text
@cindex Flashing text
@cindex Underlined text
@cindex Reverse video text
@cindex Standout text

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

@table @code
@item B
Bold on
@item F
Flash on
@item R
Reverse on
@item S
Standout on
@item U
Underline on
@end table

@table @code
@item b
Bold off
@item f
Flash off
@item r
Reverse off
@item s
Standout off
@item u
Underline off
@end table

@table @code
@item a
All off
@end table

@table @code
@item C
Colour - see below
@end table

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

@cindex Attributes, colours
@cindex Colour text

Valid colour sequences (after an escape character) are:

@table @code
@item CK
Black foreground
@item CR
Red foreground
@item CG
Green foreground
@item CY
Yellow foreground
@item CB
Blue foreground
@item CM
Magenta foreground
@item CC
Cyan foreground
@item CW
White foreground
@item CA
Default foreground (white)
@end table

@table @code
@item Ck
Black background
@item Cr
Red background
@item Cg
Green background
@item Cy
Yellow background
@item Cb
Blue background
@item Cm
Magenta background
@item Cc
Cyan background
@item Cw
White background
@item Ca
Default background (black)
@end table

@node Menu Command List, Concept Index, Attribute List, Top
@unnumbered Menu Command List

@cindex Menu code, listing

Menu entries are specified like this:

@example
TITLE LINE
<KEY> <TYPE> <FILENAME | ACTION>
@end example

Entry types are:

@table @code
@item A
Animation
@item B
Binary
@item C
Comment File (most useful type)
@item L
Listed Directory
@item M
Menu File (i.e. a submenu)
@item R
Read-only File
@item S
Spooled Output (S! = spool then reload menu, S<NUM> [eg S30] = spool but
kill command if it's still going after NUM seconds)
@item T
Telnet connection
@item X
Executable (X! = execute then reload menu, X& = execute in background)
@end table

Valid menu commands are:

@example
.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 ...]
@end example

Thanks are due to @sc{amf} for compiling the original Monochrome BBS
documentation on which this is based.

@node Concept Index, , Menu Command List, Top
@unnumbered Concept Index

@printindex cp

@contents
@bye
