	   ___ Region Oriented Ascii Processor [USAGE] ___

Usage
=====

Output processed data to STDOUT when type such following on shell.

    $ roap.py script-file input-file

About script-file
=================

The script written with XML and external processor is called carrying out 
matching processing of the described regular expression.

For example, external tools (script which is written by python, perl, sed, awk,
etc.) are started, the text which wrote to the format recognition file and 
has been recognized to be recognized as a title is passed to standard input and
the standard output which comes on the contrary is received to change into HTML
a certain fixed form format (for example, to suppose that there is rule that
the next line of a text is fill uped with "=" in a title).

The format is changed by repeating this.

Region definitions
------------------

The region recognized as follows is set up by setting a route element to "roap".

    <region processor="executable">
      <match range="*">regex text</match>
      <match range="1">regex text</match>
      ...
    </region>

Matching processing is performed in order to judge to which external processor
it should apply. The external processor is specified to be a region element,
respectively. The number of lines (range attribute) applied is specified to be
the character sequence which contained the regular expression in the match
element. Moreover, if it is "*" and is zero or more lines and "+", it becomes
matching specification of one or more lines.

Extreme example
---------------

In the following examples, the filter of all the regions is carried out to cat.

    <roap>
     <region processor="cat">
      <match range="+">.*</match>
     </region>
    </roap>

When this file (USAGE) itself is considered as an input file and the text file
which wrote the above-mentioned script is set to cat.xml, the keys of the
following commands will be touched.

    $ roap.py cat.xml USAGE

Although it thinks that it turns out that it performs, it should turn out that
the empty line is crowded and outputted.

That is, since the empty line is recognized as a pause, the empty line itself
is not outputted.

Fundamental example
-------------------

In an example a while ago, since it is hard to call it practical usage,
the example to say and which uses, being able to exceed is shown.

    <roap>
     <region processor="python title.py">
      <match range="+">\s+___ .* ___</match>
     </region>
     <region processor="python header.py -2">
      <match range="+">.*</match>
      <match range="1" content="no">=+</match>
     </region>
     <region processor="python header.py -3">
      <match range="+">.*</match>
      <match range="1" content="no">-+</match>
     </region>
     <region processor="python preformat.py">
      <match range="+">    .*</match>
     </region>
     <region processor="python list.py">
      <match range="+">o .*</match>
     </region>
     <region processor="python paragraph.py">
      <match range="+">.*</match>
     </region>
    </roap>

This script defines five regions. These regular expressions can process this
document now. And it is the script of Python which actually processes these.
I want actual contents to look at a sample code (following 'examples/').

Important things
----------------

Although it may understand that I have how to put a region element in order
observed, there is a certain fixed rule. It means that there is a tendency for
the pattern definition of matching to become ambiguous, so that it goes to the
lower one. If this says what thing it is, it finds out whether roap reads a
region in an input file and matches it from the top of a region element. In the
all tried place, if one does not match, even an output is not carried out.
Since the region element in the last of the above-mentioned example matches
no matter what character sequence may come, an output may be carried out.
When this pattern definition is coming to the top (beginning), it will match
first and that the pattern definition after it is disregarded.

In addition, usage thought of
=============================

o Registration batch processing to a database.
o Markup document creation support of LaTeX, HTML, etc.

-- bug report to <urago@users.sourceforge.net>
