  The CCmconvCA program allows conversion between CCmbbsCA attributes and other
  formats, and also includes the facility to turn scrollback buffers into CCmbbsCA
  type files for later viewing with CCmviewCA or CCmbbsCA.

Message:

Subject: 3.1 MCONV Overview

  The CCmconvCA 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 CCANSICA colour text to CCmbbsCA 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 CCmviewCA.

  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 CCmviewCA 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 CCmbbsCA
  files, especially in conjunction with the experimental Perl script supplied
  with this package in the `extra/' directory. See section 3.5 Converting to
  HTML.

Message:

Subject: 3.2 MCONV Invocation

  The general form for invocation is as follows:

   mconv [options] [file]...

  This will concatenate all files given, parse CCmbbsCA 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:

  CC-fCA
  CC--file-inputCA    This is the default operation - each input file is assumed
                  to be a normal CCmbbsCA file, containing CCmbbsCA attribute codes
                  (see section 2.1 Attribute codes), datestamps (see section
                  2.2 Special lines), and so on.

                  The CC-hCA, CC-tCA, and CC-cCA options determine whether the output is
                  to be HTML, plain text, or the default of coloured text. CC-yCA
                  and CC-wCA also modify the output.

  CC-mCA
  CC--menu-inputCA    Each input file is assumed to contain CCmbbsCA menu code. The CC-hCA,
                  CC-tCA, and CC-cCA 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 CC-gCA and CC-wCA options also modify the output, and CC-dCA and CC-nCA
                  specify whether to read an LDB file to show subscription and
                  last access information in the output (see section 2.4 Last
                  Access).

  CC-iCA
  CC--menu-infoCA     Each input file is assumed to contain CCmbbsCA 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 CC-hCA, CC-tCA, and CC-cCA options are
                  ignored.

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

  CC-aCA
  CC--ansi-inputCA    The input is assumed to be normal text containing ANSI
                  colour codes and other escape sequences. It is always
                  converted into normal CCmbbsCA attribute format; the only other
                  options which have any effect when used with CC-aCA are the CC-wCA
                  and CC-HCA 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 CCscreenCA into something to be viewed by CCmviewCA. See
                  section 3.6 Converting the Other Way.

  The next few options determine the output format.

  CC-hCA
  CC--html-outputCA   (CC-fCA and CC-mCA only)

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

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

  CC-tCA
  CC--text-outputCA
  CC--no-colourCA     (CC-fCA and CC-mCA only)

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

  CC-cCA
  CC--colour-outputCA       (CC-fCA and CC-mCA only) Menus and files are output as files
                        containing ANSI colour codes. This is the default
                        output format for CC-fCA and CC-mCA processing.

  These options slightly modify the behaviour of the input parser:

  CC-yCA
  CC--anonymousCA     (CC-fCA only)

                  Strip the account names from CCaFrom:CA lines. See section
                  2.2.2 CCFromCA line.

  CC-gCA
  CC--guestCA   (CC-mCA and CC-iCA only)

            Output the menu as a guest user would see it.

  CC-dCA CCFILECA
  CC--ldb=CCFILECA      (CC-mCA only)

                  Read last-access information from FILE. This overrides any
                  file specified by the environment variables CCMCONV_LDBCA or
                  CCMVIEW_LDBCA.

  CC-nCA
  CC--no-ldbCA        (CC-mCA only)

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

  CC-uCA
  CC--unbufferedCA    (standard input only)

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

  CC-wCA CCNUMCA
  CC--width=CCNUMCA     For file and menu input (CC-fCA and CC-mCA), change the number of
                  columns in the output from the default of 80 to NUM. For
                  ANSI colour text input (CC-aCA), 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 CCCOLUMNSCA) to NUM.

  CC-HCA CCNUMCA
  CC--height=CCNUMCA    For ANSI colour text input only (CC-aCA), 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 CCLINESCA) to
                  NUM.

  The last two options give information about the program.

  CC--helpCA    Print a usage message on standard output and exit successfully.

  CC-VCA
  CC--versionCA       Print version information on standard output and exit
                  successfully.

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

Message:

Subject: 3.3 Converting to Plain Text

  To convert from CCmbbsCA format to plain text, run a command like the
  afollowing:

   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 CCaFrom:CA
  lines), then use the CC-yCA 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 CC-wCA option. For instance, to convert a file to
  132 column text:

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

  The two options CC-yCA and CC-wCA apply to coloured output and HTML output as well.

Message:

Subject: 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 CC-yCA and CC-wCA may be given to set anonymity or change the
  output width respectively.

Message:

Subject: 3.5 Converting to HTML

  If the CC-hCA flag is passed instead of CC-tCA in the previous examples (see section
  3.3 Converting to Plain Text), the output is HTML code. Colours are
  implemented using the CC<FONTCA CCCOLOR=...>CA construct; background colour is done
  with CCSTYLE="background:..."CA attribute, so will only be visible on web
  browsers that support CSS. The entire text is surrounded by CC<PRE>CA 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.

Message:

Subject: 3.6 Converting the Other Way

  CCmconvCA 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 CC-aCA flag to CCmconvCA.

  To work properly, CCmconvCA CC-aCA 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 CC-wCA and CC-HCA (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 CCmbbsCA, which are
  erased before being overwritten, do not appear in the output.

  CCmconvCA CC-aCA can be used to make CCscreenCA (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.

Message:

Subject: 3.7 A note on menus

  All of the foregoing assumes that you are converting normal files. To
  convert a menu, you must tell CCmconvCA that it is dealing with a menu by
  supplying the CC-mCA flag.

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

  CC-gCA        Display as user "guest" would see it.

  CC-dCA CCFILECA   Use LDB file `FILE' for last access information.

  CC-nCA        Do not use an LDB file at all, even if one is specified by the
            environment variable CCMCONV_LDBCA or CCMVIEW_LDBCA.

  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.

