<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/css" href="file:/home/ser/Work/documentation/documentation.css" ?>
<!DOCTYPE documentation SYSTEM "http://www.germane-software.com/software/documentation/documentation.dtd">
<documentation>
  <head>
    <title>Pyx</title>

    <version>1.1</version>

    <date>*2002-080</date>

    <home>http://www.germane-software.com/software/Pyx</home>

    <archive type="unix">Current release</archive>

	<language>java</language>
	<language>ruby</language>

    <base>Pyx</base>
  </head>

  <overview>
    <purpose lang="en">
      <p>PYX is a document format based on XML; it is, in essence,
      extra-simple XML. PYX is ideal for grepping and parsing, and for very
      basic markup. Many XML documents can be converted to and from PYX format
      without any loss of information. PYX records basic tag structure,
      attributes, text, and processing instructions.</p>

      <p>The files in this distribution provide extremely lightweight parsers,
      generators, and converters for PYX documents, for Java and Ruby.</p>
    </purpose>

    <general>
      <p>PYX is is a hyper-simplified XML. Each node is occurs on a line, and
      PYX documents are very easy to parse. Consider:</p>

      <example title="XML">&#60;sometag attribute=&#34;value&#34; att2=&#34;value2&#34;&#62;
  Some text
  &#60;subtag/&#62;
&#60;/sometag&#62;</example>

      <p>This translates into PYX as:</p>

      <example title="PYX">(sometag
Aattribute value
Aatt2 value2
-\n
-  Some text\n
-\n
- 
(subtag
)subtag
-\n
)sometag</example>

      <p>It doesn&#39;t look as nice as the XML, but it actually takes fewer
      characters (usually), and is much easier to parse. This means that Pyx
      parsers are much, much more lightweight than XML parsers, which is
      important for some applications, such as applets and embedded devices.</p>

      <p>These Pyx utilities are not the first; unfortunately, all of the
      existing Pyx parsers for Java are, for some reason, based on SAX, and
      depend on the W3C SAX interfaces. This, in my humble opinion, is Stupid.
      Why use a lightweight mechanism and then weigh it down with a heavy
      interface? The Java Pyx parser supplied in this library is ~3.5KB. Very
      lightweight. All of the classes are independant, with no dependancies,
      so you use what you like.</p>
    </general>

    <features lang="en">
      <item>Parse Pyx files as streams</item>
    </features>
  </overview>

  <operation lang="en">
    <subsection title="Unit tests">
      <p>There are two unit test suites supplied with this package; one for
      the Ruby implementation, and one for the Java. Assuming you have Ruby
      install, running the Ruby test package is a matter of:</p>

      <example>ruby test.rb</example>

      <p>If you have the JUnit test suite, you can run the Java unit test
      with:</p>

      <example>java -cp .:junit.jar junit.textui.TestRunner Tester</example>
    </subsection>

    <subsection title="Using the library">
      <p>These Pyx libraries are fairly simple. Implement a <code>Pyx.Listener</code>
      object, instantiate a <code>Pyx</code> object, and call <code>pyx.parse(
      Reader )</code>.</p>

      <p>The <code>Pyx.Listener</code> interface and the methods accepted by
      the Ruby listener mechanism, are similar to the SAX API. See the API
      documentation and the unit test source code for more information.</p>

      <p>There is both <link href="javadoc">Java API</link> and
      <link href="rubydoc">Ruby API</link> documentation.</p>
    </subsection>
  </operation>

  <status>
    <subsection title="Change Log">
			<p>1.1: Added xml2pyx.rb (requires <link href="http://www.germane-software.com/software/rexml">REMXL</link></p>
      <p>1.0: Initial release</p>
    </subsection>

    <bugs lang="en">
      <item>None</item>
    </bugs>

    <todo lang="en">
			<item>Add Pyx&lt;-&gt;XML converter</item>

      <item>Add Pyx generator</item>
    </todo>
  </status>
</documentation>
