From 128b320ed135e29e1076f65707deab0ae617546a Mon Sep 17 00:00:00 2001 From: Kenshi Muto Date: Thu, 31 Dec 2020 11:42:26 +0900 Subject: [PATCH] update doc --- README.md | 8 +++ markdown-format.ja.md | 131 +++++++++++++++++++++++++++++++++++++++-- test/test_reviewlua.rb | 4 +- 3 files changed, 134 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 4c8362f..7e1a1a5 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,9 @@ **pandoc2review** is Re:VIEW Filter/Writer for Pandoc. You can convert any documents to [Re:VIEW](https://reviewml.org/) format. +- **Use case 1:** It can be used to first convert a manuscript such as Markdown or Docx into Re:VIEW format (.re) for an editing and typesetting environment using Re:VIEW. +- **Use case 2:** It can be used to continue to use Markdown as your writing format, but use Re:VIEW for typesetting. + ## Installation 1. Setup [Ruby](https://www.ruby-lang.org/) (any versions) and [Pandoc](https://pandoc.org/) (newer is better). @@ -30,6 +33,7 @@ pandoc2review file > file.re ## Options - `--shiftheading `: Add to heading level. (pandoc >= 2.8) - `--disable-eaw`: Disable compositing a paragraph with Ruby's EAW library. +- `--hideraw`: Hide raw inline/block with no review format specified. ## Specification - [pandoc2review における Markdown 形式処理の注意事項](markdown-format.ja.md) @@ -52,6 +56,9 @@ TBD. **pandoc2review** は、Pandoc の Re:VIEW Filter/Writer です。各種のドキュメントから [Re:VIEW](https://reviewml.org/) 形式に変換できます。 +- **ユースケース 1:** Re:VIEW の編集・組版環境向けに、Markdown や Docx などの原稿を最初に Re:VIEW 形式 (.re) に変換できます。 +- **ユースケース 2:** Markdown を原稿形式として使い続けながら、Re:VIEW の組版環境を使うことができます。 + ## インストール 1. [Ruby](https://www.ruby-lang.org/) (バージョンは問いません) および [Pandoc](https://pandoc.org/) (新しいものほどよいです) をセットアップします。 @@ -76,6 +83,7 @@ pandoc2review ファイル名 > ファイル名.re ## オプション - `--shiftheading <数>`: 見出しレベルに <数> だけ加えます (pandoc >= 2.8) - `--disable-eaw`: Ruby の EAW ライブラリを使った段落構築を使いません +- `--hideraw`: raw 判定されたインライン・ブロックを出力に含めません ## 仕様 - [pandoc2review における Markdown 形式処理の注意事項](markdown-format.ja.md) diff --git a/markdown-format.ja.md b/markdown-format.ja.md index df506ea..d80dd61 100644 --- a/markdown-format.ja.md +++ b/markdown-format.ja.md @@ -96,7 +96,7 @@ Setext 形式・ATX 形式は問いません。見出しレベル 7 以上は、 '>' による引用は Re:VIEW の `//quote` になります。Re:VIEW の `//quote` は段落のみをサポートしているため、段落以外の要素 (箇条書きなど) は期待の出力になりません。 -また、Markdown では `> ` を連ねることで引用を入れ子にすることができますが、Re:VIEW ではこの文法をサポートしていないため、Re:VIEW のコンパイル時にエラーになります。(★) +また、Markdown では `> ` を連ねることで引用を入れ子にすることができますが、Re:VIEW ではこの文法をサポートしていないため、Re:VIEW のコンパイル時にエラーになります。 ``` > This is a block quote. This @@ -208,8 +208,7 @@ Berkeley, CA 94718 - Markdown での空行を項目の間に挟む「ゆるいリスト」は無視され、継続した箇条書きになります。 - 改行でテキストを継続することは、「怠惰な記法」を含めて可能ですが、段落と同様、自然言語上の意味を見ずに前後のスペースは削除されます。 -- 「箇条書きの箇条書き」は `//beginchild`・`//endchild` で囲まれて表現されます。 -- 箇条書きの子として置いた箇条書き以外の要素、つまり段落やコードブロックなどは、箇条書きの子として扱われずに普通の段落・コードブロックとなります。これらを戻すには、手作業で `//beginchild`・`//endchild` で囲む必要があります。(★) +- 「箇条書きの子要素」は `//beginchild`・`//endchild` で囲まれて表現されます。 ### ビュレット (ナカグロ) 箇条書き @@ -257,7 +256,38 @@ Markdown では指定の順序数値を無視しますが、pandoc2review では ### 定義リスト -定義リストは単純なものであれば正しく変換できますが、複数の段落があったり、子要素があったりすると、子の要素にならない、改行されない、といった期待とは異なる結果になるでしょう。(★) +定義リストも、子要素を含めて表現できます。 + +``` +Term 1 + +: Definition 1 + +Term 2 with *inline markup* + +: Definition 2 + + { some code, part of Definition 2 } + + Third paragraph of definition 2. + +↓ + + : Term 1 + Definition 1 + : Term 2 with @{inline markup} + Definition 2 + +//beginchild + +//emlist{ +{ some code, part of Definition 2 } +//} + +Third paragraph of definition 2. + +//endchild +``` ## 水平線 @@ -499,6 +529,95 @@ The whole paragraph can be indented, or just the firstline. In this way, multi-p `@` は Twitter ID などの地の文で使うことのほうが一般的であると思われるため、pandoc2review では Citation (引用文献) 機能を使いません。リテラルに `@` を出力します。(★) -## 生のHTML +## 生の HTML/LaTeX + +Markdown において Div, Span 以外の HTML タグは生のデータとして扱われます。HTML タグは変換時に `//embed[html]{ 〜 //}` で囲まれます。 + +``` + + + +
TABLEHEAD
Cell1Cell2
+ +↓ + +//embed[html]{ + +//} + +//embed[html]{ + +//} + +//embed[html]{ + +//} + +//embed[html]{ + +//} + +//embed[html]{ + +//} + +//embed[html]{ + +//} + +//embed[html]{ + +//} + +//embed[html]{ + +//} + +//embed[html]{ + +//} + +//embed[html]{ + +//} + +//embed[html]{ + +//} + +//embed[html]{ +
+//} + +TABLEHEAD -★ +//embed[html]{ +
+//} + +Cell1 + +//embed[html]{ + +//} + +Cell2 + +//embed[html]{ +
+``` + +行ではなくタグ単位で囲まれ、普通の文字列はそのまま表現されることに注意してください。 + +`--hideraw` オプションを付けると、`//embed` を使わず空行になります。 + +LaTeX コードと解釈されるところは `@$|latex|〜$` のインライン命令になります。 + +``` +$$ \\alpha = \\beta\\label{eqone}$$ +Refer equation (\\ref{eqone}). + +↓ + +@$\\displaystyle{} \\alpha = \\beta\\label{eqone}$ Refer equation (@$|latex|\\ref{eqone}$). +``` diff --git a/test/test_reviewlua.rb b/test/test_reviewlua.rb index 9e01e36..1c430b5 100644 --- a/test/test_reviewlua.rb +++ b/test/test_reviewlua.rb @@ -385,7 +385,6 @@ def test_itemize //endchild EOB - # XXX: pandoc2review can't handle nested elements except list. assert_equal expected, pandoc(src) src = <<-EOB @@ -502,7 +501,7 @@ def test_enumerate 2. subtwo EOB - # XXX: pandoc2review can't handle nested elements except list. Re:VIEW doesn't care paren number and roman number enumerate by default also. + # XXX: Re:VIEW doesn't care paren number and roman number enumerate by default also. assert_equal expected, pandoc(src) end @@ -537,7 +536,6 @@ def test_definition //endchild EOB - # XXX: pandoc2review can't handle nested elements except list. assert_equal expected, pandoc(src) src = <<-EOB