Kwaff Users' Guide

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

Table of Contents:

Introduction
Install
Kwaff Format
- Element
- Attribute
- Text
- Comment
- CData
- Document Type
- XML Declaration
Kwaff and REXML

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