ulmul 0.4.1 → 0.5.0

data/README-en

@@ -1,67 +1,74 @@
 = ULMUL (Ultra Lightweight MarkUp Language)
 "ULMUL" is an original Ultra Lightweight MarkUp Language.
-ULMUL texts can be converted into HTML5 with "ulmul2html5" command
-and into XHTML with "ulmul2xhtml" command.
+ULMUL texts can be converted into HTML5 with "ulmul2html5"
+command and into LaTeX with "ulmul2latex" command.
 TeX style equations are converted into MathML.
 ULMUL is written in Ruby.
 You can also use ulmul.rb as a library.
 
 Homepage of ULMUL: http://ulmul.rubyforge.org/
 
-Download ULMUL from: http://rubyforge.org/projects/ulmul or http://rubygems.org/gems/ulmul
+Download ULMUL from: http://rubygems.org/gems/ulmul or http://rubyforge.org/projects/ulmul
 
 == Features
- * TeX style equations between two dollar marks ($) and between Eq. and /Eq.
-   will be converted into MathML. You can use Firefox version 3.x, IE+MathPlayer,
-   etc. to read MathML.
- * ulmul2xhtml output is good with the Slidy presentation environment
+ * TeX style equations between two dollar marks ($) and between \Eq:foo and /Eq:foo
+   will be converted into MathML. You can use Firefox4, IE9, etc. to read MathML.
+ * ulmul2html5 output is good with the Slidy presentation environment
    http://www.w3.org/Talks/Tools/Slidy/ using Firefox+CSS+XHTML+JavaScript.
    Please use ulmul-slidy.js and ulmul-slidy.css in the package.
+ * Figures, tables and code can be inserted to the document.
+   They can be easily refered in the text.
  * Lines starting from "#" are comments.
  * You can add your conversion rules to @subs_rules.
- * List of contents will be automatically generated.
+ * "Table of Contents" will be automatically generated.
  * "= ABC EFGH" will be the document title and the cover page of Slidy.
  * Use utf-8 for ULMUL texts.
    Specify your natural language with a --language option, e.g. --language=en.
 
 == Installation of ULMUL
-There are two different ways to install ULMUL.
-=== I. Conservative way; use setup.rb
-ulmul-X.Y.Z.tgz package can be installed as:
-  $ tar zxf ulmul-X.Y.Z.tgz
-  $ cd ulmul-X.Y.Z
-  $ su
-  # ruby setup.rb
-Note that the eim_xml and math_ml libraries are required.
-=== II. RubyGems users can take an easy way
-There is an easy way, if you are a RubyGems user:
-  $ su
-  # gem install ulmul
-If you do not have the eim_xml and math_ml libraries, gem will download and install the
-library automatically.
+Please use gem ( RubyGems https://rubygems.org/ ) for the installation.
+  $ sudo gem install ulmul
+If you do not have the eim_xml, math_ml, aasm and exifr libraries,
+gem will download and install the libraries automatically.
 
 == How to write ULMUL texts
 The encode of input file must be utf-8.
 === lines
+Inside ulmul.rb, input lines are processed as "events"
+with aasm library https://rubygems.org/gems/aasm .
 ==== empty
 Empty lines divide paragraphs.
 ==== heading
 Starting with "= ", "== ", "=== ", "==== ", "===== ", and "====== ".
 "= " will be used for the title.
 ==== asterisk
-Lines starting with
- " *"
- "   *"
- "     *"
- "       *"
- "         *"
-become itemize.
+Lines starting with asterisks become itemizing list.
+For example,
+ # Nesting is allowed uo to 5th level.
+  * First
+    * Second
+      * Third
+        * Fourth
+        * more for Fourth
+      second continue
+      * More for third
+  * More for first
+become
+# Nesting is allowed uo to 5th level.
+ * First
+   * Second
+     * Third
+       * Fourth
+       * more for Fourth
+     second continue
+     * More for third
+ * More for first
 ==== offset
 Lines starting with some spaces but not asterisks become verbatim lines.
 ==== end
 EOF or "=end" end the process.
 ==== ignore
-Lines starting with"#" and "=begin" are ignored.
+Lines starting with "#" and "=begin" are ignored.
 ==== normal
 Other lines.
 === Other rules
@@ -70,49 +77,83 @@ Other lines.
 === Equations
 Input:
  Mass $m$ can be converted into energy $E$ as
- Eq. 1
+ \Eq:Emc2
             E=mc^2.
- /Eq.
+ /Eq:Emc2
 
 Output:
 
 Mass $m$ can be converted into energy $E$ as
-Eq. 1
-            E=mc^2.
-/Eq.
+\Eq:Emc2
+           E=mc^2.
+/Eq:Emc2
 
 To view the equations in MathML correctly, please use
- * Firefox http://mozilla.jp/firefox/
- * IE8 + MathPlayer http://www.dessci.com/en/products/mathplayer/
+ * Firefox 4 http://mozilla.jp/firefox/
+ * IE9
  * etc.
 
 === Figures
+Start a Figure environment with "\Fig:foo FILENAME.jpg"
+and terminate it with "/Fig:foo", where "foo" is a tag for the figure.
+You can write a figure caption between them.
+You can refer the figure with "Fig:foo" as Fig:ruby.
+
 Input:
- Fig. 1 ruby.jpg
+ \Fig:ruby ruby.jpg
    The is a dummy figure for an example.
    Cute red logo of Ruby, isn't it?
- /Fig.
+ /Fig:ruby
 
 Output:
-Fig. 1 ruby.jpg
+\Fig:ruby ruby.jpg
   The is a dummy figure for an example.
   Cute red logo of Ruby, isn't it?
-/Fig.
+/Fig:ruby
+
+=== Tables
+Table environment is NOT IMPLEMENTED yet.
+Start a Table environment with "\Table:bar"
+and terminate it with "/Table:bar", where "bar" is a tag for the table.
+You can write a figure caption between them.
+You can refer the figure with "Table:bar" as Table:diamond.
 
-== Usage
-There are ulmul2xhtml and ulmul2html5 commands.
+Input:
+ \Table:diamond
+   The is a dummy caption for the table.
+ /Table:diamond
 
-Use .html extensions even for ulmul2xhtml outputs.
+Output:
+\Table:diamond
+  The is a dummy caption for the table.
+/Table:diamond
+
+=== Code
+Start a Code environment with "\Code:baz FILENAME"
+and terminate it with "/Code:baz", where "baz" is a tag for the code.
+You can write a figure caption between them.
+You can refer the figure with "Code:baz" as Code:hello.
+Code will be highlighted with
+google-code-prettify http://code.google.com/p/google-code-prettify/ ,
+when options of -s google-code-prettify/src/prettify.css and
+-j google-code-prettify/src/prettify.js are given.
 
-To view HTML5 documents,
-change the setting of the "html5.enable" entry to "true" in "about:config".
-See http://kb.mozillazine.org/About:config for details.
+Input:
+ \Code:hello hello.c
+   Ordinary hello.c.
+   Can you see stdio.h?
+ /Code:hello
 
+Output:
+\Code:hello hello.c
+  Ordinary hello.c.
+  Can you see stdio.h?
+/Code:hello
+
+== Usage of ulmul2html5
 === Examples
- $ ulmul2xhtml without-equations.txt > without-equations.html   # XHTML1.0 Transitional
- $ ulmul2xhtml with-equations.txt    > with-equations.html      # XHTML1.1 + MathML2.0
- $ ulmul2xhtml -n 'Takeshi Nishimatsu' -s ulmul-slidy.css -j ulmul-slidy.js presentation.txt > presentation.xhtml
- $ ulmul2html5 with-equations.txt    > with-equations.html      # HTML5
+ $ ulmul2html5 foo.txt > foo.html
+ $ ulmul2html5 -n 'Takeshi Nishimatsu' -s ulmul-slidy.css -j ulmul-slidy.js presentation.txt > presentation.html
 
 === Command options
 ==== --help
@@ -125,10 +166,10 @@ Specify your name for copyright notices.
 Specify JavaScript filename.
 ==== -l, --language
 Specify natural language. Its default is "en".
-==== -c, --contents-range
-Range of "Contents". Its default is "2..3".
-If you do not need "Contents" at the beginning of the
-output HTML file, set it 3..2.
+==== -m, --max-table-of-contents
+Maximum depth for the Table of Contents.
+Its default is 3.
+If you do not need the Table of Contents, specify 1.
 
 === ULMUL and Slidy examples
  * http://loto.sourceforge.net/feram/
@@ -138,22 +179,31 @@ output HTML file, set it 3..2.
  * http://ulmul.rubyforge.org/index.en.html
    * Its source is http://ulmul.rubyforge.org/README-en (this document)
 
+=== ulmul2xhtml is obsolete
+ulmul2xhtml will be removed from next version 0.6.x.
+
+== Usage of ulmul2latex
+ $ ulmul2latex --help
+ $ ulmul2latex test.ulmul | tee test.tex
+ $ latex test.tex
+ $ latex test.tex
+ $ dvipdfmx test.dvi
+ulmul2latex is still under development. Sorry.
+
 == TODO
- * rescue syntax errors (raises) in an input file and report the
-   errors as #{$FILENAME}:#{file.lineno}:...
+ * More usefull error messages for syntax errors.
  * Unit test, tests/ulmul_test.rb
- * @body must be XML object, not a String.
- * Tables.
- * References to figures, tables and code.
+ * @body shoud be XML object, not a String.
  * Citation.
- * Include highlighted code between Code.../Code.
+For more, see TODO file.
 
 == Subversion repository
-You can checkout the latest source tree of ULMUL anonymously from RubyForge with svn(1) command:
+You can checkout the latest source tree of ULMUL anonymously from RubyForge
+with svn(1) command:
  $ svn co svn://rubyforge.org/var/svn/ulmul/ulmul/trunk ulmul
 
 == Copying
-Copyright © 2008-2010 by Takeshi Nishimatsu
+Copyright © 2008-2011 by Takeshi Nishimatsu
 
 ulmul.rb is distributed in the hope that
 it will be useful, but WITHOUT ANY WARRANTY.
@@ -169,6 +219,11 @@ http://www.w3.org/Talks/Tools/Slidy/ . You can find
 their licenses at http://www.w3.org/Consortium/Legal/copyright-documents
 and http://www.w3.org/Consortium/Legal/copyright-software .
 
+Google Inc. has copyrights for files under google-code-prettify
+directory. Package prettify-21-Jul-2010.zip is distributed
+from http://code.google.com/p/google-code-prettify/ under the
+Apache License, Version 2.0.
+
 == Author of ULMUL
 Takeshi Nishimatsu (t_nissie{at}yahoo.co.jp) http://t-nissie.users.sourceforge.net/
 

data/README-ja

@@ -1,57 +1,69 @@
 = ULMUL取扱説明書
 ULMULは独自の軽量マークアップ言語 (Ultra Lightweight MarkUp Language) です。
-コマンドulmul2html5でHTML5に、ulmul2xhtmlでXHTMLに変換できます。
+コマンドulmul2html5でHTML5に、ulmul2latexでLaTeXに変換できます。
 文章中のTeXスタイルで書かれた数式をMathMLに変換できるのが特徴です。
 Rubyで書かれています。ulmul.rbをライブラリとして利用することも可能です。
 
 ホームページ: http://ulmul.rubyforge.org/
 
-ダウンロード: http://rubyforge.org/projects/ulmul/ または http://rubygems.org/gems/ulmul
+ダウンロード: http://rubygems.org/gems/ulmul または http://rubyforge.org/projects/ulmul/
 
 == 特徴
- * 文章中の２つのドル記号($)で挟まれた部分とEq.…/Eq.で挟まれた行が数式としてTeX形式からMathML形式に変換されます。
-   MathMLとはXMLで数式を記述するための規格です。込み入った規格なので人間が直接MathMLを記述する
-   ことは想定されていませんが、ULMULでやっているようにTeXなどからの変換により生成することができます。
-   Firefoxのバージョン3.0以上やIE+MathPlayerで読めるようです。
+ * 文章中の２つのドル記号($)で挟まれた部分と\Eq:fooと/Eq:fooとで挟まれた行が
+   数式としてTeX形式からMathML形式に変換されます。MathMLとはXMLで数式を記述
+   するための規格です。込み入った規格なので人間が直接MathMLを記述する
+   ことは想定されていませんが、ULMULでやっているようにTeXなどからの変換により
+   生成することができます。Firefox4やIE9で読めるようです。
    math_ml.rb http://www.hinet.mydns.jp/?mathml.rb を使っています。
  * ウェブ・ブラウザ+CSS+XHTML+JavaScriptを使ったプレゼン環境
    Slidy http://www.w3.org/Talks/Tools/Slidy/ に対応したxhtmlが出力可能。
    パッケージの中の ulmul-slidy.js と ulmul-slidy.css とを使ってください。
+ * 図、表、コードが挿入でき、文中でそれらの参照ができます。
  * =begin, =end はあってもなくてもかまいません。
  * 行を#ではじめるとコメントになります。
  * ulmul.rbをライブラリとしても使えます。
  * subs_rulesに俺ルールを加えることができます。
- * 目次 (Contents) を自動的に生成できます。
+ * 目次 (Table of Contents) を自動的に生成できます。
  * はじめの「= ABCD EFGH」がタイトルになります。Slidyの表紙にもなります。
  * テキストファイルはutf-8で書きます。自然言語は--language=jaなどとオプションで指定できます。
 
 == インストール方法
-２通りのインストール方法があります。
-=== I. setup.rbを使う方法
-パッケージ ulmul-X.Y.Z.tgz を次のようにインストールします:
-  $ tar zxf ulmul-X.Y.Z.tgz
-  $ cd ulmul-X.Y.Z
-  $ sudo ruby setup.rb
-なお、ULMULを使うにはeim_xmlライブラリとmath_mlライブラリとが必要です。
-=== II. RubyGemsを使えば簡単にインストールができます
-gemでインストールすればeim_xmlライブラリとmath_mlライブラリとは自動的にインストールされます:
+gemでインストールすれば必要なライブラリも自動的にインストールされます:
   $ sudo gem install ulmul
 
 == ULMULテキストの書き方
 ULMULテキストのエンコーディングにはutf-8を使ってください。
 === 各行の種類
+ulmul.rbは状態遷移 (state machine) ライブラリaasmを使っていて、
+入力の各行を「イベント」として扱っています。
 ==== 空行 (empty)
 空行は段落を分割します。
 ==== ヘディング (heading)
 "= ", "== ", "=== ", "==== ", "===== ", または "====== " で始めてください。
 「= ABCD EFGH」ならABCD EFGHがタイトルになります。Slidyの表紙にもなります。
 ==== アスタリスクで始まる行は箇条書きになります (asterisk)
-６段までネストした箇条書きが可能です:
- " *"
- "   *"
- "     *"
- "       *"
- "         *"
+５段までネストした箇条書きが可能です:
+たとえば、
+ # Nesting is allowed uo to 5th level.
+  * First
+    * Second
+      * Third
+        * Fourth
+        * more for Fourth
+      second continue
+      * More for third
+  * More for first
+は
+# Nesting is allowed uo to 5th level.
+ * First
+   * Second
+     * Third
+       * Fourth
+       * more for Fourth
+     second continue
+     * More for third
+ * More for first
+と変換されます。
 ==== オフセットされて書かれた行はそのまま出力 (verbatim, pre) されます (offset)
 １つスペースを置いて書き始めた行はverbatimになります。
 ==== 終わり (end)
@@ -67,59 +79,69 @@ Lines starting with"#" and "=begin" are ignored.
 
 === 数式の書き方
 文章中の２つのドル記号($)で挟まれた部分がTeX形式からMathML形式に変換されます。
-また、Eq.…/Eq.で挟まれた行も次の例のように処理されます。
+また、\Eq:fooと/Eq:fooとで挟まれた行も次の例のように処理されます。
 
 入力:
  Mass $m$ can be converted into energy $E$ as
- Eq. 1
+ \Eq:Emc2
             E=mc^2.
- /Eq.
+ /Eq:Emc2
 
 出力:
 
 Mass $m$ can be converted into energy $E$ as
-Eq. 1
-            E=mc^2.
-/Eq.
+\Eq:Emc2
+           E=mc^2.
+/Eq:Emc2
 
 数式を正しくご覧いただくには
- * Firefox http://mozilla.jp/firefox/
- * IE8 + MathPlayer http://www.dessci.com/en/products/mathplayer/
+ * Firefox4 http://mozilla.jp/firefox/
+ * IE9
 などのブラウザを試してみて下さい。
 
 === 図の挿入方法
+「図環境」は "\Fig:foo FILENAME.jpg" で始めて "/Fig:foo" で閉じてください。
+間に図のキャプションを書くことができます。
+ここで "foo" は図のタグです。
+"Fig:foo"で図を参照することができます。こんな具合です Fig:ruby 。
+
 入力:
- Fig. 1 ruby.jpg
+ \Fig:ruby ruby.jpg
    The is a dummy figure for an example.
    Cute red logo of Ruby, isn't it?
- /Fig.
+ /Fig:ruby
 
 出力:
-Fig. 1 ruby.jpg
+\Fig:ruby ruby.jpg
   The is a dummy figure for an example.
   Cute red logo of Ruby, isn't it?
-/Fig.
+/Fig:ruby
 
-== 使用方法
-ulmul2xhtmlとulmul2html5の２つのコマンドがあります。
-特に指定がなければ ulmul2xhtml.css と ulmul2html5.css とがそれぞれのCSSファイルのなります。
-これら２つのファイルはパッケージに同梱されています。
+=== 表の挿入方法
+Table環境はまだインプリメントされていません。
 
-2010年4月現在、ulmul2xhtmlの出力を.htmlの拡張子を持ったファイルにリダイレクトして
-httpサーバからtext/htmlのMIMEタイプで送信されるようにすれば
-いくつかのブラウザが数式を表示してくれるようです。
-１行目のxml宣言を取るとさらにうまく表示される場合もあります。
+=== コードの挿入方法
+「コード環境」は "\Code:baz FILENAME" で始めて "/Code:baz" で閉じてください。
+間にキャプションを書くことができます。
+ここで "baz" は図のタグです。
+"Code:baz"で当該コードを参照することができます。こんな具合です Code:hello 。
 
-Firefox3.6でHTML5を表示するには、URLとして about:config を入力して、
-html5.enableをfalseからtrueに変更してください。
+入力:
+ \Code:hello hello.c
+   Ordinary hello.c.
+   Can you see stdio.h?
+ /Code:hello
 
-IE8はMathMLで書かれた数式を含んだHTML5をうまく表示できないようです。
+出力:
+\Code:hello hello.c
+  Ordinary hello.c.
+  Can you see stdio.h?
+/Code:hello
 
+== ulmul2html5の使用方法
 === 例
- $ ulmul2xhtml without-equations.txt > without-equations.html   # XHTML1.0 Transitional
- $ ulmul2xhtml with-equations.txt    > with-equations.html      # XHTML1.1 + MathML2.0
- $ ulmul2xhtml -n 'Takeshi Nishimatsu' -s ulmul-slidy.css -j ulmul-slidy.js presentation.txt > presentation.xhtml
- $ ulmul2html5 with-equations.txt    > with-equations.html      # HTML5
+ $ ulmul2html5 foo.txt > foo.html
+ $ ulmul2html5 -n 'Takeshi Nishimatsu' -s ulmul-slidy.css -j ulmul-slidy.js presentation.txt > presentation.html
 
 === コマンド・ライン・オプション
 ==== --help
@@ -132,11 +154,11 @@ IE8はMathMLで書かれた数式を含んだHTML5をうまく表示できない
 JavaScriptのファイル名を指定します。
 ==== -l, --language
 自然言語の種類を指定します。既定値は"en"です。日本語の場合は-l jaとします。
-==== -c, --contents-range
-目次の深さを指定します。既定値は"2..3"です。
-目次が必要なければ-c 3..2とします。
+==== -m, --max-table-of-contents
+目次の深さを指定します。既定値は"3"です。
+目次が必要なければ1を指定してください。
 
-=== 使用例
+=== 実際の使用例
  * http://loto.sourceforge.net/feram/
    * ソースは http://loto.sourceforge.net/feram/README
  * http://loto.sourceforge.net/feram/doc/film.xhtml
@@ -144,18 +166,25 @@ JavaScriptのファイル名を指定します。
  * http://ulmul.rubyforge.org/index.ja.html
    * ソースは http://ulmul.rubyforge.org/README-ja （この文章）
 
-== ulmul.rbの仕組み
-入力の各行をイベントとして状態遷移しています。
-定数Ulmul::TABLEが状態遷移表です。
+=== ulmul2xhtmlは消します
+次のバージョン (0.6.x) からulmul2xhtmlは消します。
+
+== Usage of ulmul2latex
+ $ ulmul2latex --help
+ $ ulmul2latex test.ulmul | tee test.tex
+ $ latex test.tex
+ $ latex test.tex
+ $ dvipdfmx test.dvi
+ulmul2latexはまだ発展途上です。
 
 == 最新のソース・ツリーの入手方法
 ソース・ツリーはRubyForge.orgのSubversionレポジトリで管理されています。
 svn(1)コマンドを使って
  $ svn co svn://rubyforge.org/var/svn/ulmul/ulmul/trunk ulmul
-とcheckoutできます。
+と匿名でcheckoutできます。
 
 == 著作権表示
-Copyright © 2008-2010 by Takeshi Nishimatsu
+Copyright © 2008-2011 by Takeshi Nishimatsu
 
 ulmul.rb is distributed in the hope that
 it will be useful, but WITHOUT ANY WARRANTY.
@@ -171,6 +200,11 @@ http://www.w3.org/Talks/Tools/Slidy/ . You can find
 their licenses at http://www.w3.org/Consortium/Legal/copyright-documents
 and http://www.w3.org/Consortium/Legal/copyright-software .
 
+Google Inc. has copyrights for files under google-code-prettify
+directory. Package prettify-21-Jul-2010.zip is distributed
+from http://code.google.com/p/google-code-prettify/ under the
+Apache License, Version 2.0.
+
 == 作者
 西松タケシ (t_nissie{at}yahoo.co.jp) http://t-nissie.users.sourceforge.net/