Kwaff Users' Guide

last update: $Date: 2005-06-14 21:50:59 +0900 (Tue, 14 Jun 2005) $

Introduction

Kwaff is a little tool to convert Kwaff format document into XML document.

Kwaff format is a simple and friendly format for human than XML. You'd like it.

Kwaff format document (filename `example.kwaff'):
? encoding = ISO-8859-1
? doctype  = @xhtml
* html
  - lang  = en
  * body
    * ul
      * li = item1
      * li = item2
      * li = item3
  # this is a XML comment
  // this is a Kwaff comment (ignored by kwaff)
Convert:
$ kwaff example.kwaff > example.xml
XML format document (filename `example.xml'):
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en">
  <body>
    <ul>
      <li>item1</li>
      <li>item2</li>
      <li>item3</li>
    </ul>
  </body>
  <!-- this is a XML comment -->
</html>

Indent width is 2 (default). You can change it by the command-line option -iN (input indent width) and -IN (output indent width).

Kwaff can also revert XML document into Kwaff format document.

### revert XML document into Kwaff document
$ kwaff -r example.xml > example.kwaff

Install

  • If you have installed RubyGems, just type gem install --remote kwaff.
  • Else if you can be administrator, use setup.rb.
    $ tar xjf kwaff_X.X.X.tar.bz2
    $ cd kwaff_X.X.X/
    $ ruby setup.rb config
    $ ruby setup.rb setup
    $ su -
    # ruby setup.rb install
    
  • Else copy bin/kwaff script and lib/kwaff* into proper directory.
    $ tar xjf kwaff_X.X.X.tar.bz2
    $ cd kwaff_X.X.X/
    $ mkdir $HOME/bin;  copy bin/kwaff $HOME/bin
    $ mkdir $HOME/lib/ruby;  copy lib/kwaff* $HOME/lib/ruby
    $ export RUBYLIB=$HOME/lib/ruby
    

Kwaff Format

Element

Kwaff:
* html
  * body
    * p = text
XML:
<?xml version="1.0"?>
<html>
  <body>
    <p>text</p>
  </body>
</html>

Attribute

Kwaff:
* div
  - align = center
  * a = Kwaff homepage
    - href = http://kuwata-lab.com/kwaff
    - class = link
XML:
<?xml version="1.0"?>
<div align="center">
  <a href="http://kuwata-lab.com/kwaff" class="link">Kwaff homepage</a>
</div>

Text

Kwaff:
* body
  * p = foo bar  baz...
  * p
    . foo
    .    bar
    . baz...
  * p = <<<END
      foo
         bar
      baz...
END
  * p = <<<END
      foo
         bar
      baz...
      END
XML:
<?xml version="1.0"?>
<body>
  <p>foo bar  baz...</p>
  <p>foo
   bar
baz...</p>
  <p>      foo
         bar
      baz...</p>
  <p>foo
   bar
baz...</p>
</body>

Comment

Kwaff:
* body
  # This is a XML comment
  // This is a Kwaff comment
  * p = foo bar baz...
XML:
<?xml version="1.0"?>
<body>
  <!-- This is a XML comment -->
  <p>foo bar baz...</p>
</body>

CData

Kwaff:
* body
  * p
    . if (a > 0 && a < 100) ... end
  * p
    ~ if (a > 0 && a < 100) ... end

  * pre = <<<END
    <b>foo</b>
    <i>bar</i>
    END
  * pre = <<<'END'
    <b>foo</b>
    <i>bar</i>
    END

  ~ <!--
  ~
  * dl
    * dt = word
    * dd = desc
  ~ -->
  ~
XML:
<?xml version="1.0"?>
<body>
  <p>if (a &gt; 0 &amp;&amp; a &lt; 100) ... end</p>
  <p>if (a > 0 && a < 100) ... end</p>

  <pre>&lt;b&gt;foo&lt;/b&gt;
&lt;i&gt;bar&lt;/i&gt;</pre>
  <pre><b>foo</b>
<i>bar</i></pre>

<!--
  <dl>
    <dt>word</dt>
    <dd>desc</dd>
  </dl>
-->
</body>

Document Type

Kwaff:
? doctype = <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
* html
  * body
XML:
<?xml version="1.0"?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <body/>
</html>

Kwaff allow you to specify doctype shortly.

Kwaff:
? doctype = @xhtml
* html
  * body
XML:
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <body/>
</html>

You can see all short name of document type by 'kwaff -D'. If you want to add new document type, see lib/kwaff/doctypes.yaml file.

XML Declaration

Kwaff:
? xmlversion = 1.1
? encoding   = ISO-8859-1
? doctype    = @xhtml
* html
  * body
    * p = foo
XML:
<?xml version="1.1" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <body>
    <p>foo</p>
  </body>
</html>

Kwaff and REXML

You can convert Kwaff format string into REXML document.

Kwaff format string ==> REXML document
#/usr/bin/env ruby
require 'kwaff'
require 'kwaff/rexml'
require 'rexml/document'

## read Kwaff format string
kwaff_str = ARGF.read()

## convert Kwaff format string into REXML::Document
rexml_document = Kwaff::Rexml::parse_document(kwaff_str)
rexml_document.write($stdout, 0)
REXML document ==> Kwaff format string
#/usr/bin/env ruby
require 'kwaff'
require 'kwaff/rexml'
require 'rexml/document'

## create REXML Document
xml_str = ARGF.read()
rexml_document = REXML::Document.new(xml_str)

## convert REXML::Document into Kwaff format string
translator = Kwaff::Rexml::KwaffTranslator.new()
kwaff_str = translator.translate(rexml_document)
print kwaff_str
XML string ==> Kwaff format string
#/usr/bin/env ruby
require 'kwaff'
require 'kwaff/rexml'

## read XML format string
xml_str = ARGF.read()

## convert XML format string into Kwaff format string
kwaff_str = Kwaff::Rexml::revert(xml_str)
print kwaff_str