ulmul 0.1.0 → 0.3.0

data/README-en

@@ -0,0 +1,172 @@
+= 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.
+TeX stile 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
+
+== 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
+   http://www.w3.org/Talks/Tools/Slidy/ using Firefox+CSS+XHTML+JavaScript.
+ * Lines starting from "#" are comments.
+ * You can add your conversion rules to @subs_rules.
+ * List 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 eimxml and mathml 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 eimxml and mathml libraries, gem will download and install the
+library automatically.
+
+== How to write ULMUL texts
+The encode of input file must be utf-8.
+=== lines
+==== empty
+Empty lines divide paragraphs.
+==== heading
+Starting with "= ", "== ", "=== ", "==== ", "===== ", and "====== ".
+"= " will be used for the title.
+==== asterisk
+Lines starting with
+ " *"
+ "   *"
+ "     *"
+ "       *"
+ "         *"
+become itemize.
+==== 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.
+==== normal
+Other lines.
+=== Other rules
+ * Lines after "=end" are ignored.
+ * Add your substitution rules to @subs_rules.
+=== Equations
+Input:
+ Mass $m$ can be converted into energy $E$ as
+ Eq. 1
+            E=mc^2.
+ /Eq.
+
+Output:
+
+Mass $m$ can be converted into energy $E$ as
+Eq. 1
+            E=mc^2.
+/Eq.
+
+To view the equations in MathML correctly, please use
+ * Firefox http://mozilla.jp/firefox/
+ * IE8 + MathPlayer http://www.dessci.com/en/products/mathplayer/
+ * etc.
+
+=== Figures
+Input:
+ Fig. 1 ruby.jpg
+   The is a dummy figure for an example.
+   Cute red logo of Ruby, isn't it?
+ /Fig.
+
+Output:
+Fig. 1 ruby.jpg
+  The is a dummy figure for an example.
+  Cute red logo of Ruby, isn't it?
+/Fig.
+
+== Usage
+There are ulmul2xhtml and ulmul2html5 commands.
+
+Use .html extensions even for ulmul2xhtml outputs.
+
+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.
+
+=== 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 slidy.js presentation.txt > presentation.xhtml
+ $ ulmul2html5 with-equations.txt    > with-equations.html      # HTML5
+
+=== Command options
+==== --help
+Show a help message.
+==== -s, --style
+Specify stylesheet filename.
+==== -n, --name
+Specify your name for copyright notices.
+==== -j, --javascript
+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.
+
+=== ULMUL and Slidy examples
+ * http://loto.sourceforge.net/feram/
+   * Its source is http://loto.sourceforge.net/feram/README
+ * http://loto.sourceforge.net/feram/doc/film.xhtml
+   * It is a Slidy presentation made from http://loto.sourceforge.net/feram/doc/film.txt
+
+== TODO
+ * rescue syntax errors (raises) in an input file and report the
+   errors as #{$FILENAME}:#{file.lineno}:...
+ * Unit test, tests/ulmul_test.rb
+ * @body must be XML object, not a String.
+ * Tables.
+ * References to figures, tables and code.
+ * Citation.
+ * Include highlighted code between Code.../Code.
+
+== Subversion repository
+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
+ulmul.rb is distributed in the hope that
+it will be useful, but WITHOUT ANY WARRANTY.
+You can copy, modify and redistribute ulmul.rb,
+but only under the conditions described in
+the GNU General Public License (the "GPL").
+
+W3C has copyrights for slidy.js and ulmul-slidy.css (originally
+named slidy.css). Takeshi Nishimatsu modified them.
+You can download the original package, slidy.zip, from
+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 .
+
+== Author of ULMUL
+Takeshi Nishimatsu (t_nissie{at}yahoo.co.jp)
+
+# Local variables:
+#   mode: rd
+#   compile-command: "rake index.en.html"
+# End:

data/README-ja

@@ -1,34 +1,24 @@
-# README-ja for ULMUL -*-rd-*-
-= ULMUL (ulmul.rb) 取扱説明書
-ULMUL (ulmul.rb) は独自の軽量マークアップ言語 (Ultra Lightweight MarkUp Language) を
-(X)HTMLファイルへ変換します。文章中のTeXスタイルで書かれた数式をMathMLに変換できるのが特徴です。
-また、ウェブ・ブラウザ+CSS+XHTML+JavaScriptを使ったプレゼン環境
-HTML Slidy http://www.w3.org/Talks/Tools/Slidy/ に対応したhtmlかxhtmlも出力可能です。
-sourceforge.jpのWikiシンタックス http://sourceforge.jp/projects/sourceforge/wiki/Guide%2FWikiSyntax
-と同様なことができるようになることをめざして開発しています。
+= ULMUL取扱説明書
+ULMULは独自の軽量マークアップ言語 (Ultra Lightweight MarkUp Language) です。
+コマンドulmul2html5でHTML5に、ulmul2xhtmlでXHTMLに変換できます。
+文章中のTeXスタイルで書かれた数式をMathMLに変換できるのが特徴です。
+Rubyで書かれています。ulmul.rbをライブラリとして利用することも可能です。
 
-http://ulmul.rubyforge.org/ がホームページです。
-http://rubyforge.org/projects/ulmul/ から関連するファイルをダウンロードすることができます。
-
-作者は作者のwebページと学会発表用のスライドを作るのにULMULを使っています。
-http://loto.sourceforge.net/feram/ のソースは
-http://loto.sourceforge.net/feram/README です。
-http://loto.sourceforge.net/feram/doc/film.xhtml というスライドは
-http://loto.sourceforge.net/feram/doc/film.txt から生成されました。
+ホームページ: http://ulmul.rubyforge.org/
 
+ダウンロード: http://rubyforge.org/projects/ulmul/ または http://rubygems.org/gems/ulmul
 
 == 特徴
  * 文章中の２つのドル記号($)で挟まれた部分とEq.…/Eq.で挟まれた行が数式としてTeX形式からMathML形式に変換されます。
    MathMLとはXMLで数式を記述するための規格です。込み入った規格なので人間が直接MathMLを記述する
    ことは想定されていませんが、ULMULでやっているようにTeXなどからの変換により生成することができます。
-   Firefoxのバージョン3.0以上で読めるようです。
+   Firefoxのバージョン3.0以上やIE+MathPlayerで読めるようです。
    math_ml.rb http://www.hinet.mydns.jp/?mathml.rb を使っています。
  * ウェブ・ブラウザ+CSS+XHTML+JavaScriptを使ったプレゼン環境
-   Slidy http://www.w3.org/Talks/Tools/Slidy/ に対応したhtmlかxhtmlも出力可能です。
-   ただし、PowerPointより優れたプレゼンができるかというと、そうとも限りません。
+   Slidy http://www.w3.org/Talks/Tools/Slidy/ に対応したxhtmlが出力可能。
  * =begin, =end はあってもなくてもかまいません。
  * 行を#ではじめるとコメントになります。
- * ライブラリとしても使えます。
+ * ulmul.rbをライブラリとしても使えます。
  * subs_rulesに俺ルールを加えることができます。
  * 目次 (Contents) を自動的に生成できます。
  * はじめの「= ABCD EFGH」がタイトルになります。Slidyの表紙にもなります。
@@ -41,23 +31,11 @@ http://loto.sourceforge.net/feram/doc/film.txt から生成されました。
 パッケージ ulmul-X.Y.Z.tgz を次のようにインストールします:
   $ tar zxf ulmul-X.Y.Z.tgz
   $ cd ulmul-X.Y.Z
-  $ su
-  # ruby setup.rb
+  $ sudo ruby setup.rb
 なお、ULMULを使うにはeimxmlライブラリとmathmlライブラリとが必要です。
 === II. RubyGemsを使えば簡単にインストールができます
 gemでインストールすればeimxmlライブラリとmathmlライブラリとは自動的にインストールされます:
-  $ su
-  # gem install ulmul
-
-== 必要なファイル
- * ulmul.rb         Rubyスクリプト。
- * slidy.js         Slidy用JavaScript。オリジナルをちょっとだけ改変。
- * ulmul-slidy.css  Slidy用CSSファイル。オリジナルを大幅に改変。
- * style.css        普通のウェブページ用CSSファイル。
-もしあなたがULMULをgemでインストールしたなら、上記のファイル
-は /usr/local/lib/ruby/gems/1.8/gems/ulmul-X.Y.Z/
-もしくは /usr/lib/ruby/gems/1.8/gems/ulmul-X.Y.Z/
-以下にあるかもしれません。
+  $ sudo gem install ulmul
 
 == ULMULテキストの書き方
 ULMULテキストのエンコーディングにはutf-8を使ってください。
@@ -82,12 +60,14 @@ EOF と "=end" が出てくると処理が終了します。
 Lines starting with"#" and "=begin" are ignored.
 ==== その他の入力行 (normal)
 地の文になります。
+
 === その他のルール
  * "=end"より後の行はすべて無視されます。
  * あなたのオリジナル・ルールを @subs_rules に加えることができます。
+
 === 数式の書き方
 文章中の２つのドル記号($)で挟まれた部分がTeX形式からMathML形式に変換されます。
-また、Eq.…/Eq.で挟まれた行も次の例のように処理されます
+また、Eq.…/Eq.で挟まれた行も次の例のように処理されます。
 
 入力:
  Mass $m$ can be converted into energy $E$ as
@@ -102,24 +82,46 @@ Eq. 1
             E=mc^2.
 /Eq.
 
+数式を正しくご覧いただくには
+ * Firefox http://mozilla.jp/firefox/
+ * IE8 + MathPlayer http://www.dessci.com/en/products/mathplayer/
+などのブラウザを試してみて下さい。
+
 === 図の挿入方法
 入力:
  Fig. 1 ruby.jpg
    The is a dummy figure for an example.
+   Cute red logo of Ruby, isn't it?
  /Fig.
 
 出力:
 Fig. 1 ruby.jpg
   The is a dummy figure for an example.
+  Cute red logo of Ruby, isn't it?
 /Fig.
 
 == 使用方法
+ulmul2xhtmlとulmul2html5の２つのコマンドがあります。
+
+2010年4月現在、ulmul2xhtmlの出力を.htmlの拡張子を持ったファイルにリダイレクトして
+httpサーバからtext/htmlのMIMEタイプで送信されるようにすれば
+いくつかのブラウザが数式を表示してくれるようです。
+１行目のxml宣言を取るとさらにうまく表示される場合もあります。
+
+Firefox3.6でHTML5を表示するには、URLとして about:config を入力して、
+html5.enableをfalseからtrueに変更してください。
+
+IE8はMathMLで書かれた数式を含んだHTML5をうまく表示できないようです。
+
 === 例
- $ ruby ulmul.rb foo.txt
- $ ruby ulmul.rb --style=style.css --name="John Smith" foo.ulmul > foo.html
- $ ./ulmul.rb --style=ulmul-slidy.css --javascript=slidy.js \
-   --name="Takeshi Nishimatsu" presentation.txt > presentation.xhtml
+ $ 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 slidy.js presentation.txt > presentation.xhtml
+ $ ulmul2html5 with-equations.txt    > with-equations.html      # HTML5
+
 === コマンド・ライン・オプション
+==== --help
+ヘルプ情報が表示されます。
 ==== -s, --style
 スタイルシートのファイル名を指定します。--style=style.css などがよいでしょう。
 ==== -n, --name
@@ -131,14 +133,22 @@ JavaScriptのファイル名を指定します。
 ==== -c, --contents-range
 目次の深さを指定します。既定値は"2..3"です。
 目次が必要なければ-c 3..2とします。
-==== --help
-ヘルプ情報が表示されます。
+
+=== 使用例
+ * http://loto.sourceforge.net/feram/
+   * ソースは http://loto.sourceforge.net/feram/README
+ * http://loto.sourceforge.net/feram/doc/film.xhtml
+   * ソースは http://loto.sourceforge.net/feram/doc/film.txt
 
 == ulmul.rbの仕組み
 入力の各行をイベントとして状態遷移しています。
-class Ulmulの中の定数TABLEが状態遷移表です。
-これが正しい実装方法なのかよくわかりません。
-たぶんオートマトンとかを勉強した方がよいのだと思います。
+定数Ulmul::TABLEが状態遷移表です。
+
+== 最新のソース・ツリーの入手方法
+ソース・ツリーはRubyForge.orgのSubversionレポジトリで管理されています。
+svn(1)コマンドを使って
+ $ svn co svn://rubyforge.org/var/svn/ulmul/ulmul/trunk ulmul
+とcheckoutできます。
 
 == 著作権表示
 ulmul.rb is distributed in the hope that
@@ -158,5 +168,6 @@ and http://www.w3.org/Consortium/Legal/copyright-software .
 西松タケシ (t_nissie{at}yahoo.co.jp)
 
 # Local variables:
-#   compile-command: "rake README-ja.xhtml"
+#   mode: rd
+#   compile-command: "rake index.ja.html"
 # End:

data/Rakefile

@@ -1,6 +1,6 @@
 #! /usr/bin/env rake
 # -*-Ruby-*-
-# Time-stamp: <2009-01-04 11:56:08 takeshi>
+# Time-stamp: <2010-04-01 08:37:35 takeshi>
 # Author: Takeshi Nishimatsu
 ##
 $LOAD_PATH.unshift('lib')
@@ -14,7 +14,7 @@ require 'archive/tar/minitar'
 require 'zlib'
 
 spec = eval(File.read("ulmul.gemspec"))
-spec.version = ULMUL_RB_VERSION
+spec.version = Ulmul::VERSION
 ULMUL_PACKAGE_DIR = '..'
 # RDOC_OPTS = %w(--title ulmul --line-numbers)
 # spec.rdoc_options = RDOC_OPTS
@@ -48,28 +48,20 @@ end
 # end
 
 desc "Publish to RubyForge"
-task :rubyforge => ["README-en.xhtml",
-                    "README-ja.xhtml",
-                    "style.css", "index.html", "favicon.ico", "ruby.jpg"] do |t|
+task :rubyforge => ["index.en.html",
+                    "index.ja.html",
+                    "style.css", "favicon.ico", "ruby.jpg"] do |t|
   t.prerequisites.each do |f|
     sh "scp #{f} t-nissie@rubyforge.org:/var/www/gforge-projects/ulmul/"
   end
 end
 
-desc "Build Packages"
-task :package => [ :ulmul_version_rb ]
-
-desc "Copy lib/ulmul.rb ../ulmul-X.Y.Z.rb"
-task :ulmul_version_rb do
-  FileUtils.copy_file('lib/ulmul.rb', ULMUL_PACKAGE_DIR + '/ulmul-' + ULMUL_RB_VERSION + '.rb')
-end
-
-desc "Create README-en.xhtml"
-file "README-en.xhtml" => ["bin/ulmul.rb", "style.css", "lib/ulmul.rb"] do |t|
-  sh "ruby #{t.prerequisites[0]} -c 2..3 -s #{t.prerequisites[1]} #{t.prerequisites[2]} > #{t.name}"
+desc "Create index.en.html"
+file "index.en.html" => ["bin/ulmul2xhtml", "ulmul2xhtml.css", "README-en", "lib/ulmul.rb"] do |t|
+  sh "ruby -I lib #{t.prerequisites[0]} -n 'Takeshi Nishimatsu' -l en #{t.prerequisites[2]} > #{t.name}"
 end
 
-desc "Create README-ja.xhtml"
-file "README-ja.xhtml" => ["bin/ulmul.rb", "style.css", "README-ja"] do |t|
-  sh "ruby #{t.prerequisites[0]} -c 2..3 -s #{t.prerequisites[1]} #{t.prerequisites[2]} > #{t.name}"
+desc "Create index.ja.html"
+file "index.ja.html" => ["bin/ulmul2xhtml", "ulmul2xhtml.css", "README-ja", "lib/ulmul.rb"] do |t|
+  sh "ruby -I lib #{t.prerequisites[0]} -n 'Takeshi Nishimatsu' -l ja #{t.prerequisites[2]} > #{t.name}"
 end

data/XHTML-vs-HTML5.ja.txt

@@ -0,0 +1,86 @@
+= XHTML vs HTML5
+XHTMLとHTML5とを比較
+
+== XHTML
+=== XHTML+MathMLの例
+ <?xml version="1.0" encoding="utf-8"?>
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN"
+    "http://www.w3.org/Math/DTD/mathml2/xhtml-math11-f.dtd">
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja">
+   <head>
+     <title>XHTML+MathMLの例</title>
+   </head>
+   <body>
+   <p>XHTML+MathMLの例だよ。</p>
+   <p>
+   質量<math display='inline' xmlns='http://www.w3.org/1998/Math/MathML'><mi>m</mi></math>は
+   エネルギー<math display='inline' xmlns='http://www.w3.org/1998/Math/MathML'><mi>E</mi></math>に
+   <math display='block' xmlns='http://www.w3.org/1998/Math/MathML'>
+     <mi>E</mi>
+     <mo>=</mo>
+     <mi>m</mi>
+     <msup>
+     <mi>c</mi>
+     <mn>2</mn>
+     </msup>
+   </math>
+   と転換されるよ。
+   </p>
+   </body>
+ </html>
+
+=== 留意点
+ * 拡張子は.xhtml
+ * httpサーバからapplication/xhtml+xmlのMIMEタイプで送信される
+ * DTDを使ってvalid XML documentかどうかチェックされる
+ * もちろん well-formed XML document
+ * 文書はhtmlをルート要素（root element＝一番の親要素）として記述
+ * このルート要素において、xmlns属性でXHTMLのXML名前空間を指定
+ * ルート要素の前に有効な文書型宣言を行なう
+ * １行目のxml宣言はMUSTではない http://www.spacewalker.jp/webtips/xhtmlviewmode/
+ * 拡張子を.htmlにしてhttpサーバからtext/htmlのMIMEタイプで送信されるようにすればたいていのブラウザが読んでくれるみたい
+
+=== 参考文献
+[Kanzaki] http://www.kanzaki.com/docs/html/xhtml1.html
+
+
+== HTML5
+=== HTML5の例（数式付き）
+ <!DOCTYPE html>
+ <html>
+   <head>
+     <meta charset=utf-8>
+     <title>HTML5の例</title>
+   </head>
+   <body>
+   <p>HTML5の例だよ。</p>
+   <p>
+   質量<math display='inline'><mi>m</mi></math>は
+   エネルギー<math display='inline'><mi>E</mi></math>に
+   <math display='block'>
+     <mi>E</mi>
+     <mo>=</mo>
+     <mi>m</mi>
+     <msup>
+     <mi>c</mi>
+     <mn>2</mn>
+     </msup>
+   </math>
+   と転換されるよ。
+   </p>
+   </body>
+ </html>
+
+=== 留意点
+ * 拡張子は.html
+ * httpサーバからtext/htmlのMIMEタイプで送信される
+
+
+== 疑問点
+ * <hr> or <hr/> ?
+ * MathMLでよく使う<none/>は？
+
+# Local variables:
+#   mode: rd
+#   compile-command: "rake XHTML-vs-HTML5.ja.html"
+# End: