asciitoscorp.doc

This program will accept a ASCII file (or it can use PC character encoding
or EUC character encoding, if declared in the file; both are supersets of
ASCII) from stdin, and write the Scorpion document file to stdout.


=== Switches ===

Normally, no switches are needed. However, switches can be used to make it
work in different modes.

-I
  Enable internal mode. The output will be in a format which will be used
  by asciitoscorp invoking itself in multi mode. You should not normally
  use this option by yourself; an exception is mentioned below.

-J #
  Enable internal mode, as with -I, but also specify a template file. This
  is used internally by CNVT and has no use to be used for your own use.

-a
  Always regenerate all output files, regardless of modification times.
  This also skips reading the control file (it will still write to the
  control file in multi mode, though). This switch is not meaningful unless
  combined with the -m switch.

-c #
  Set the name of the control file. If not specified, then the name of the
  control file will be read from the command file. This switch is not
  meaningful unless combined with the -m switch.

-m #
  Enable multi mode. It will read a command file from the specified file
  name. If it is - or an empty string then it reads the command file from
  stdin instead. This will produce multiple output files, according to the
  specifications in the command file, instead of writing to stdout.

-v
  Enable verbose mode.


=== Syntax ===

<name> means a command (similar than <name> in HTML or <name/> in XML).

<name| and |name> are also commands but are the beginning and ending
commands (similar than <name> ... </name> in HTML or XML).

|name| or || is a middle command, to separate parts of a <x| |x> block.

<hex> represents a single graphic character by the character code. If the
current encoding is PC then it is always two hex digits (and zero is not
allowed; use FF or 20 instead), otherwise it is a TRON character code.

A blank line is a delimiter between blocks. Multiple blank lines between
blocks are redundant.

<$charset> sets the input and output character encoding. Valid encodings
are: PC, JP, CN, and KR. PC cannot be mixed with the other encodings in the
same block, but you can mix the other encodings with each other.

A line break is treated as a space in most contexts. Leading and trailing
spaces, and multiple consecutive spaces, are treated as a single space in
most contexts.

|= can be followed by a line break to suppress the extra space. You can
also add extra stuff on the same line after |= which will be ignored.

You can use <{ and }> or |{ and }| to surround text which should not be
interpreted as commands; they are interpreted as raw characters. They
must fit within a single line, though.

You can also use << and some other text on the same line, to mean a heredoc
which means that the rest of the text is interpreted as araw characters,
until a line that has the same text that followed << on the first line.
This is only useful in preformatted blocks, because in such a block it will
treat tabs as the <TAB> command and line breaks as the <BR> command.

<! command !> will execute an external program and use its output as the
source text that is accepted by this program. That output is not allowed to
itself include any <! !> block.

<? command ?> will execute an external program like <! !> but instead of
using its output as source text, its exit code is used; if it is nonzero
then it will skip up to the next <? character sequence.


=== Commands ===

In the below list, ** means it is only allowed at the beginning of a block,
and it defines the block type. If no block type is specified, then it is a
normal paragraph block.

||
  Outside of any other command that expects multiple parts, this command is
  used to separate the section number or item number (or bullet) from the
  rest of the text in the same heading or paragraph.

<1> or <1| name |1> **
  Make a level 1 heading (the outermost level). You can optionally specify
  a name which is used after the # in a URL to refer to that heading.
  There are also more heading levels 2 to 6.

<ALT| url |ALT> **
  Make a alternate service link, for mirrors, etc.

<ASK> or <ASK| url |ASK> **
  Make a link that requests input. If you use <ASK> without the URL, then
  it means to use the current URL.

<BODY> **
  Only valid in a template; includes the result from the input file at this
  point in the output file. This command must occur exactly once in a
  template file and is not allowed in any other file.

<BR>
  Line break; only valid inside of a preformatted block.

<DATA> **
  In internal mode and multi mode, this command can be used to add data to
  the data stream; see the section about the command file for details.

<E> or <E| text |E>
  Set style to emphasis. (The second syntax will revert the style to the
  most recent one that uses the first syntax, afterward. Nesting is not
  allowed and will not work.)

<ENV| name |ENV>
  Include the contents of an environment variable.

<F> or <F| text |F>
  Set style to fixpitch.

<FI| size type |FI>
  Set file info in extended link attributes. Only valid in the body of a
  <L> or <ASK> block. (The type is optional and may be omitted. If the size
  is unknown, a question mark may be substituted in place of the size.)

<FIS> or <FIS| type |FIS>
  Set file info in extended link attributes; only valid in the body of a
  <L> block (not valid for <ASK>). The file size will be determined
  automatically, by attempting to read the file; if the file cannot be
  found, then it is an error. (Be careful with using this, that you do not
  end up reading a file whose size changes later, or a file in the wrong
  directory, etc.)

<FUR| base || furigana |FUR>
  Make furigana text. You can use || or |FUR| to mean the same thing.

<INC| file name |INC> **
  Include the contents of another binary Scorpion document file. (It will
  validate that the data is correct.)

<INT> or <INT| url |INT> **
  Make a link to an interactive session.

<L> or <L| url |L> **
  Make a plain link. (The URL can be absolute or relative.)

<N> or <N| text |N>
  Set style to normal.

<PIPE| command |PIPE> **
  Like <INC> but uses the output of an external program instead.

<Q> **
  Begin a block quotation.

<R| text |R>
  The text will use the reverse text direction from that of the paragraph.
  The normal text direction of the paragraph is restored by |R>.

<RAW| command |RAW>
  Like <PIPE> but does not begin a new block; the output of the command is
  entered into the body (and is not necessarily the only text in the body).
  Note that the output might not necessarily be valid for the current kind
  of block; if that is the case, then it will result in an invalid block.
  (This is useful to include the contents of a plain text file (in UNIX
  format) in a preformatted block.)

<RAWI>
  Include raw inline delimited data. This is like <RAW> except that the
  data is inline instead of from an external program; it is immediately
  followed by a delimiter character, which is also used to terminate it.
  All normal processing of tokens is suppressed within the raw data.

<RGR>
  Reset graphic rendition.

<S> or <S| text |S>
  Set style to strong.

<SET| name |SET> or <SET>name=value or <SET| name=value |SET> **
  Set an environment variable. If it is set in an input file which is to
  be included in a template, then the environment variable will also be
  available to be used within the template file.

<SGR| numbers |SGR>
  Set graphic rendition. Put the numbers with semicolons in between.

<TAB>
  Tab; only valid inside of a preformatted block.

<X> or <X| attribute |X> **
  Make a preformatted block.


=== Command file ===

The command file in multi mode consists of a sequence of the commands
listed below. Any blank line and any line starting with # is a comment and
is ignored. (Not all features are implemented yet, although all of the
commands listed below are accepted, even if they are not currently useful.)

ALL
  Follow by a number 0 or 1. If it is 0 (which is the default setting)
  then it will skip any files that have not changed, but if it is 1 then
  it will always regenerate all output files. The -a switch overrides this
  command and causes it to always regenerate all output files. (This
  feature is not fully implemented yet.)

CD
  Change directory. It will automatically change directory to the directory
  containing the command file, if you specify the name of the command file
  by the -m switch; this will change directory relative to that one.

CNV
  Convert one or more files. Give two file names with a space in between;
  first the input file and then the output file. Optionally you can have *
  in both file names, in which case it matches all input files that match
  the pattern, and substitute whatever * matches in the input file name
  for the * in the output file name.

CNVE
  Like CNV but requires a third argument which is a shell command which is
  used instead. This will receive the contents of the input file on stdin
  and produces the output on stdout. This is the only case where it is
  useful to use the -I switch yourself, since the output that is produced
  must be in the format used by asciitoscorp's internal mode.

CNVL
  Like CNV but the first argument is the input file name (which must be a
  single file), and the second argument is the output file name pattern
  (with exactly one asterisk), and third is a shell command. Each line of
  the output of the shell command will be used to substite for the asterisk
  in the output pattern.

CNVT
  Like CNV but requires a third argument which is the name of the template
  file, which has the same format as the usual asciitoscorp input file. The
  output file is made from the template file instead of the input file, but
  you can use the <BODY> command to include the input file.

CNVX
  Line CNV but the second argument is a shell command to execute instead of
  an output file name. It must read the input file itself, which you can
  find by the _in environment variable. It also must produce any desired
  output files itself. The program should not read from stdin. If it
  produces any output on stdout, then the output is treated as additional
  commands to be interpreted as though they are in the command file.

CTR
  Specify the name of the control file, which contains internal data which
  can be restored later to avoid repeating unnecessary work. If the file
  does not already exist, it will be created. The -c switch overrides this
  command, if it is specified. If this command is used, then it should be
  specified before any commands which read or write any other files. (The
  control file is not currently meaningful; it will not read nor write it
  and will not be able to avoid repeating unnecessary work.)

DATA
  Data entry. The data can be arbitrary text.

DIV
  Divert the output from data entry to an external program instead of to
  an internal buffer. The external program will receive EOF when the next
  DIV or END command is reached.

END
  End the diversion from the DIV command.

NOWJ
  Set an environment variable, like SET, but the value will instead be the
  date/time format according to strftime function.

NOWZ
  Same as NOWJ but using UTC instead of local time.

REW
  Rewind the data entry and discard all existing data entry.

SEND
  Follow by an external shell command; it is executed and the data entry
  is provided as stdin. Each data item is null-terminated (unless TERM is
  used to change the termination code).

SEQ
  Reset the sequence number. The next sequence number will be one more
  than the specified number. (See the section about special environment
  variables for details.)

SET
  Set an environment variable. Put = between the name and value.

SIZE
  Set an environment variable to the total size of the data entry so far.

SYS
  Execute an external program. If the exit code is nonzero, it is an error.

TERM
  Define the terminator code for data items, as a 8-bit hexadecimal number.
  The default value is zero.

Note: The control file and the -a switch and ALL command is not currently
implemented; it will always do all of the files in all cases. (It will
accept -a and ALL but they currently have no meaning.)


=== Special environment variables ===

In the multi mode and internal mode, environment variables whose name
starts with _ are special and have the meanings described below. In most
cases, you should treat them as read-only; although writing to them is not
disallowed, it probably won't work properly if you do. (These environment
variables cannot be used in the single file mode.)

_ctim
  The ctime of the current input file.

_glo
  Number of files that the glob pattern of the most recent CNV command
  matched. (If there is no glob pattern, then this variable is not used.)

_in
  Name of input file.

_mtim
  The mtime of the current input file.

_name
  The part of the file name that the * matched in the CNV command.

_out
  Name of output file.

_seq
  The sequence number. This is 1 for the first file converted, 2 for the
  next file, etc. It is not automatically reset between CNV commands; you
  must use the SEQ command to reset it.