Skip to content

Commit bf2e51c

Browse files
authored
Merge pull request #1860 from kmuto/doc-update-1858
formatドキュメント更新
2 parents 7d07405 + a5d34ba commit bf2e51c

File tree

2 files changed

+137
-65
lines changed

2 files changed

+137
-65
lines changed

doc/format.ja.md

Lines changed: 69 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ Re:VIEW フォーマットの文法について解説します。Re:VIEW フォ
9696

9797
## 番号付き箇条書き
9898

99-
番号付きの箇条書き(HTML で言う ol)は「` 1. 〜`」「` 2. 〜`」「` 3. 〜`」のように示します。ネストはサポートしていません
99+
番号付きの箇条書き(HTML で言う ol)は「` 1. 〜`」「` 2. 〜`」「` 3. 〜`」のように示します。`1-1` のようなネスト出力は標準では提供していません( `//beginchild``//endchild` を使った入れ子の表現は可能です)
100100

101101
例:
102102

@@ -108,6 +108,23 @@ Re:VIEW フォーマットの文法について解説します。Re:VIEW フォ
108108

109109
番号付き箇条書きも、ただの箇条書きと同様、行頭に1つ以上の空白が必要です。
110110

111+
数字が実際にそのとおり出るかは、出力を行うソフトウェアに依存します。
112+
113+
- HTML (EPUB), TeX: 記入の数字にかかわらず1から始まる番号になります。
114+
- IDGXML, テキスト: 記入したとおりの番号が出力されます。よって、すべて「1.」にするといった形にしてしまうとおかしな結果になります。
115+
116+
HTML (EPUB) や TeX ビルダにおいて最初の番号を 1 ではないものにしたいときには、`//olnum[番号]` を指定します。なお、番号箇条書きの途中の番号を変えることはできません。
117+
118+
例:
119+
120+
```
121+
//olnum[10]
122+
123+
1. この箇条書きの番号は出力ソフトウェア上では10になる
124+
2. これは11になる
125+
6. 記入上で飛ばしても連続数で12となる
126+
```
127+
111128
## 用語リスト
112129

113130
用語リスト(HTML で言う dl)は空白→「:」→空白、で始まる行を使って示します。
@@ -186,7 +203,7 @@ Re:VIEW フォーマットの文法について解説します。Re:VIEW フォ
186203

187204
## ソースコードなどのリスト
188205

189-
ソースコードなどのリストには`//list`を使います。連番を付けたくない場合は先頭に `em`(embedded の略)、行番号を付ける場合は末尾に `num` を付加します。まとめると、以下の4種類になります。
206+
ソースコードなどのリストには `//list` を使います。連番を付けたくない場合は先頭に `em`(embedded の略)、行番号を付ける場合は末尾に `num` を付加します。まとめると、以下の4種類になります。
190207

191208
* `//list[識別子][キャプション][言語指定]{ 〜 //}`
192209
* 通常のリスト。言語指定は省略できます。
@@ -471,7 +488,7 @@ complexmatrixという識別子に基づく画像ファイルが貼り込まれ
471488
//}
472489
```
473490

474-
## 引用
491+
## 引用・中央揃え・右揃え
475492

476493
引用は「`//quote{ 〜 //}`」を使って記述します。
477494

@@ -485,6 +502,24 @@ complexmatrixという識別子に基づく画像ファイルが貼り込まれ
485502

486503
複数の段落を入れる場合は、空行で区切ります。
487504

505+
中央揃えの段落を表現するには、「`//centering{ 〜 //}`」を使います。同様に右寄せにするには「`//flushright{ 〜 //}`」を使います。複数の段落を入れる場合は、空行で区切ります。
506+
507+
例:
508+
509+
```
510+
//centering{
511+
これは
512+
513+
中央合わせ
514+
//}
515+
516+
//flushright{
517+
これは
518+
519+
右寄せ合わせ
520+
//}
521+
```
522+
488523
## 囲み記事
489524

490525
技術書でよくある、コラムにするほどではないけれども本文から独立したちょっとした記事を入れるために、以下の命令があります。
@@ -634,7 +669,7 @@ LaTeX の式を挿入するには、`//texequation{ 〜 //}` を使います。
634669

635670
参照するにはインライン命令 `@<eq>` を使います(たとえば `@<eq>{emc}`)。
636671

637-
インライン命令では `@<m>{〜}` を使います。インライン命令の式中に「}」を含む場合、`\}` とエスケープする必要があることに注意してください(`{` はエスケープ不要)。「インライン命令のフェンス記法」も参照してください
672+
インライン命令では `@<m>{〜}` を使います。インライン命令の式中に「}」を含む場合、`\}` とエスケープする必要があることに注意してください(`{` はエスケープ不要)。長い式を書くときにはフェンス記法(`@<m>$〜$` または `@<m>|〜|`)を使うと、エスケープが不要になり、記述が楽になります。「インライン命令のフェンス記法」を参照してください
638673

639674
LaTeX の数式が正常に整形されるかどうかは処理系に依存します。LaTeX を利用する PDFMaker では問題なく利用できます。
640675

@@ -889,32 +924,7 @@ Lesser General Public License, ★"i"nternationalizatio"n"☆
889924

890925
## 生データ行
891926

892-
Re:VIEW のタグ範囲を超えて何か特別な行を挿入したい場合、`//raw` ブロック命令や`//embed`ブロック命令、または `@<raw>` インライン命令や `@<embed>` インライン命令を使います。
893-
894-
### `//raw`
895-
896-
例:
897-
898-
```
899-
//raw[|html|<div class="special">\nここは特別な行です。\n</div>]
900-
```
901-
902-
ブロック命令は1つだけオプションをとり、「|ビルダ名|そのまま出力させる内容」という書式です。`\n`は改行文字に変換されます。
903-
904-
ビルダ名には「`html`」「`latex`」「`idgxml`」「`markdown`」「`top`」のいずれかが入ります。ビルダ名は「,」で区切って複数指定することも可能です。該当のビルダを使用しているときのみ、内容が出力されます。
905-
906-
例:
907-
908-
```
909-
(HTMLビルダの場合:)
910-
<div class="special">
911-
ここは特別な行です。
912-
</div>
913-
914-
(ほかのビルダの場合は単に無視されて何も出力されない)
915-
```
916-
917-
インライン命令は、`@<raw>{|ビルダ名|〜}` という書式で、記述はブロック命令に同じです。
927+
Re:VIEW のタグ範囲を超えて何か特別な行を挿入したい場合、`//embed`ブロック命令や `@<embed>` インライン命令を使います。ほかに従来の `//raw` ブロック命令および `@<raw>` インライン命令もありますが、IDGXML ビルダ以外での使用は推奨しません。
918928

919929
### `//embed`ブロック
920930

@@ -963,13 +973,38 @@ LaTeXビルダを使用している場合:
963973
964974
```
965975

976+
### `//raw`行(IDGXML ビルダ以外では非推奨)
977+
978+
例:
979+
980+
```
981+
//raw[|html|<div class="special">\nここは特別な行です。\n</div>]
982+
```
983+
984+
ブロック命令は1つだけオプションをとり、「|ビルダ名|そのまま出力させる内容」という書式です。`\n`は改行文字に変換されます。
985+
986+
ビルダ名には「`html`」「`latex`」「`idgxml`」「`markdown`」「`top`」のいずれかが入ります。ビルダ名は「,」で区切って複数指定することも可能です。該当のビルダを使用しているときのみ、内容が出力されます。
987+
988+
例:
989+
990+
```
991+
(HTMLビルダの場合:)
992+
<div class="special">
993+
ここは特別な行です。
994+
</div>
995+
996+
(ほかのビルダの場合は単に無視されて何も出力されない)
997+
```
998+
999+
インライン命令は、`@<raw>{|ビルダ名|〜}` という書式で、記述はブロック命令に同じです。
1000+
9661001
`//raw``//embed``@<raw>` および `@<embed>` は、HTML、XML や TeX の文書構造を容易に壊す可能性があります。使用には十分に注意してください。
9671002

9681003
### 入れ子の箇条書き
9691004

9701005
Re:VIEW の箇条書きは `*` 型の箇条書きを除き、基本的に入れ子を表現できません。いずれの箇条書きも、別の箇条書き、あるいは図表・リストを箇条書きの途中に配置することを許容していません。
9711006

972-
この対策として、Re:VIEW 4.2 では試験的に `//beginchild``//endchild` というブロック命令を追加しています。箇条書きの途中に何かを含めたいときには、それを `//beginchild``//endchild` で囲んで配置します。多重に入れ子にすることも可能です。
1007+
この対策として、Re:VIEW 4.2 以降では `//beginchild``//endchild` というブロック命令があります。箇条書きの途中に何かを含めたいときには、それを `//beginchild``//endchild` で囲んで配置します。多重に入れ子にすることも可能です。
9731008

9741009
```
9751010
* UL1
@@ -1054,6 +1089,8 @@ UL1-OL1-PARAGRAPH
10541089
* `@<tcy>{〜}` : 縦書きの文書において文字を縦中横にします。
10551090
* `@<ins>{〜}` : 挿入箇所を明示します(デフォルトでは下線が引かれます)。
10561091
* `@<del>{〜}` : 削除箇所を明示します(デフォルトでは打ち消し線が引かれます)。
1092+
* `@<sup>{〜}` : 上付き文字にします。
1093+
* `@<sub>{〜}` : 下付き文字にします。
10571094

10581095
### 参照
10591096
* `@<chap>{章ファイル名}` : 「第17章」のような、章番号を含むテキストに置換されます。
@@ -1075,8 +1112,8 @@ UL1-OL1-PARAGRAPH
10751112
* `@<m>{数式}` : インラインの数式を出力します。
10761113
* `@<w>{キー}` : キー文字列に対応する、単語ファイル内の値文字列を展開します。
10771114
* `@<wb>{キー}` : キー文字列に対応する、単語ファイル内の値文字列を展開し、太字にします。
1078-
* `@<raw>{|ビルダ|〜}` : 生の文字列を出力します。`\}``}`に、`\\``\`に、`\n`は改行に置き換えられます。
10791115
* `@<embed>{|ビルダ|〜}` : 生の文字列を埋め込みます。`\}``}`に、`\\``\`に置き換えられます(`\n`はそのままです)。
1116+
* `@<raw>{|ビルダ|〜}` : 生の文字列を出力します。`\}``}`に、`\\``\`に、`\n`は改行に置き換えられます(非推奨)。
10801117
* `@<idx>{文字列}` : 文字列を出力するとともに、索引として登録します。索引の使い方については、makeindex.ja.md を参照してください。
10811118
* `@<hidx>{文字列}` : 索引として登録します (idx と異なり、紙面内に出力はしません)。`親索引文字列<<>>子索引文字列` のように親子関係にある索引も定義できます。
10821119
* `@<balloon>{〜}` : コードブロック (emlist など) 内などでのいわゆる吹き出しを作成します。たとえば「`@<balloon>{ABC}`」とすると、「`←ABC`」となります。デフォルトの挙動および表現は簡素なので、より装飾されたものにするにはスタイルシートを改変するか、`review-ext.rb` を使って挙動を書き換える必要があります。

doc/format.md

Lines changed: 68 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ The document is a brief guide for Re:VIEW markup syntax.
44

55
Re:VIEW is based on EWB of ASCII (now KADOKAWA), influenced RD and other Wiki system's syntax.
66

7-
This document explains about the format of Re:VIEW 5.3.
7+
This document explains about the format of Re:VIEW 5.5.
88

99
## Paragraph
1010

@@ -112,7 +112,7 @@ You should add emply lines between Paragraphs and Itemize (same as Ordered and N
112112
## Ordered Itemize
113113

114114
Ordered itemize (ol in HTML) uses ` 1. ...`, ` 2. ...`, ` 3. ...`.
115-
They aren't nested.
115+
Nesting output like `1-1` is not supported by default (nesting can be expressed using `//beginchild` - `//endchild`).
116116

117117
Usage:
118118

@@ -122,15 +122,24 @@ Usage:
122122
3. 3rd condition
123123
```
124124

125-
The value of Number is ignored.
125+
You must write one more space character at line head like itemize.
126+
127+
Whether the numbers appear as described depends on the software that produces the output.
128+
129+
* HTML (EPUB), TeX: The number will start from 1 regardless of the number entered.
130+
* IDGXML, text: The numbers will be output as described. Therefore, writing all numbers as "1." will produce strange results.
131+
132+
In HTML (EPUB) and TeX builders, use `//olnum[number]` to change the first number. Note that the intermediate numbers cannot be changed.
133+
134+
Usage:
126135

127136
```
128-
1. 1st condition
129-
1. 2nd condition
130-
1. 3rd condition
131-
```
137+
//olnum[10]
132138
133-
You must write one more space character at line head like itemize.
139+
1. This number will be 10
140+
2. This number will be 11
141+
6. 12 in continuity, not 6 or 15.
142+
```
134143

135144
## Definition List
136145

@@ -512,6 +521,26 @@ Seeing is believing.
512521

513522
You can use inline markup in quotations.
514523

524+
Center-aligned paragraphs are represented by `//centering{ ~ //}` and right-aligned paragraphs by `//flushright{ ~ //}`.
525+
526+
To include multiple paragraphs, separate them with a blank line.
527+
528+
Usage:
529+
530+
```
531+
//centering{
532+
This is
533+
534+
center aligned.
535+
//}
536+
537+
//flushright{
538+
This is
539+
540+
right aligned.
541+
//}
542+
```
543+
515544
## Short column
516545

517546
Some block commands are used for short column.
@@ -670,7 +699,7 @@ If you'd like to assign a number like 'Equation 1.1`, specify the identifier and
670699

671700
To reference this, use the inline command `@<eq>`.
672701

673-
There is `@<m>{ ... }` for inline (see "Fence notation for inline commands" section also).
702+
There is `@<m>{ ... }` for inline. When writing long expressions, it is convenient to use fence notation (`@<m>$~$` or `@<m>|~|`) to avoid escaping. (see "Fence notation for inline commands" section also).
674703

675704
Whether LaTeX formula is correctly displayed or not depends on the processing system. PDFMaker uses LaTeX internally, so there is no problem.
676705

@@ -943,20 +972,27 @@ Usage:
943972

944973
## Raw Data Block
945974

946-
When you want to write non-Re:VIEW line, use `//raw` or `//embed`.
975+
When you want to write non-Re:VIEW line, use `//embed` or `@<embed>`.
947976

948-
### `//raw` block
977+
### `//embed` block
949978

950979
Usage:
951980

952981
```
953-
//raw[|html|<div class="special">\nthis is a special line.\n</div>]
982+
//embed{
983+
<div class="special">
984+
this is a special line.
985+
</div>
986+
//}
987+
988+
//embed[html,markdown]{
989+
<div class="special">
990+
this is a special line.
991+
</div>
992+
//}
954993
```
955994

956-
In above line, `html` is a builder name that handle raw data.
957-
You can use `html`, `latex`, `idgxml` and `top` as builder name.
958-
You can specify multiple builder names with separator `,`.
959-
`\n` is translated into newline(U+000A).
995+
In above line, `html` and `markdown` is a builder name that handle raw data.
960996

961997
Output:
962998

@@ -970,27 +1006,22 @@ this is a special line.
9701006

9711007
(In other formats, it is just ignored.)
9721008

973-
Note: `//raw` and `@<raw>` may break structured document easily.
1009+
For inline, use `@<embed>{|builder|raw string}`.
9741010

975-
### `//embed` block
1011+
### `//raw` block
1012+
1013+
`//raw` and `@<raw>` is an old notation and should no longer be used (use it only if you want to avoid line breaks in IDGXML builder).
9761014

9771015
Usage:
9781016

9791017
```
980-
//embed{
981-
<div class="special">
982-
this is a special line.
983-
</div>
984-
//}
985-
986-
//embed[html,markdown]{
987-
<div class="special">
988-
this is a special line.
989-
</div>
990-
//}
1018+
//raw[|html|<div class="special">\nthis is a special line.\n</div>]
9911019
```
9921020

993-
In above line, `html` and `markdown` is a builder name that handle raw data.
1021+
In above line, `html` is a builder name that handle raw data.
1022+
You can use `html`, `latex`, `idgxml` and `top` as builder name.
1023+
You can specify multiple builder names with separator `,`.
1024+
`\n` is translated into newline(U+000A).
9941025

9951026
Output:
9961027

@@ -1004,11 +1035,13 @@ this is a special line.
10041035

10051036
(In other formats, it is just ignored.)
10061037

1038+
Note: `//embed`, `@<embed>`, `//raw` and `@<raw>` may break structured document easily.
1039+
10071040
### Nested itemize block
10081041

10091042
Re:VIEW itemize blocks basically cannot express nested items. Also, none of itemize blocks allow to contain another itemize block or paragraph/image/table/list.
10101043

1011-
As a workaround, Re:VIEW 4.2 provides an experimental `//beginchild` and `//endchild`. If you want to include something in an itemize block, enclose it with `//beginchild` and `//endchild`. It is also possible to create a multiple nest.
1044+
As a workaround, Re:VIEW provides `//beginchild` and `//endchild` since Re:VIEW 4.2. If you want to include something in an itemize block, enclose it with `//beginchild` and `//endchild`. It is also possible to create a multiple nest.
10121045

10131046
```
10141047
* UL1
@@ -1091,9 +1124,11 @@ Output:
10911124
@<tti>{FooClass}:: teletype (monospaced font) and italic
10921125
@<ttb>{BarClass}:: teletype (monospaced font) and bold
10931126
@<code>{a.foo(bar)}:: teletype (monospaced font) for fragments of code
1094-
@<tcy>{}:: short horizontal text in vertical text
1127+
@<tcy>{text}:: short horizontal text in vertical text
10951128
@<ins>{sentence}:: inserted part (underline)
10961129
@<del>{sentence}:: deleted part (strike through)
1130+
@<sup>{text}:: superscript
1131+
@<sub>{text}:: subscript
10971132
```
10981133

10991134
### References
@@ -1121,8 +1156,8 @@ Output:
11211156
@<m>{a + \alpha}:: TeX inline equation
11221157
@<w>{key}:: expand the value corresponding to the key.
11231158
@<wb>{key}:: expand the value corresponding to the key with bold style.
1124-
@<raw>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}`, `\\` is `\`, and `\n` is newline.
11251159
@<embed>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}` and `\\` is `\`.
1160+
@<raw>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}`, `\\` is `\`, and `\n` is newline. (deprecated)
11261161
@<idx>{string}:: output a string and register it as an index. See makeindex.md.
11271162
@<hidx>{string}:: register a string as an index. A leveled index is expressed like `parent<<>>child`
11281163
@<balloon>{abc}:: inline balloon in code block. For example, `@<balloon>{ABC}` produces `←ABC`. This may seem too simple. To decorate it, modify the style sheet file or override a function by `review-ext.rb`

0 commit comments

Comments
 (0)