Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

formatドキュメント更新 #1860

Merged
merged 2 commits into from
Sep 24, 2022
Merged

formatドキュメント更新 #1860

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d17d90e
囲み記事のラベルをMEMO,NOTE等妥当なものにする (Closes: #1843)
kmuto Sep 4, 2022
a5d34ba
update format document (#1858)
kmuto Sep 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 69 additions & 32 deletions doc/format.ja.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ Re:VIEW フォーマットの文法について解説します。Re:VIEW フォ

## 番号付き箇条書き

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

例:

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

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

数字が実際にそのとおり出るかは、出力を行うソフトウェアに依存します。

- HTML (EPUB), TeX: 記入の数字にかかわらず1から始まる番号になります。
- IDGXML, テキスト: 記入したとおりの番号が出力されます。よって、すべて「1.」にするといった形にしてしまうとおかしな結果になります。

HTML (EPUB) や TeX ビルダにおいて最初の番号を 1 ではないものにしたいときには、`//olnum[番号]` を指定します。なお、番号箇条書きの途中の番号を変えることはできません。

例:

```
//olnum[10]

1. この箇条書きの番号は出力ソフトウェア上では10になる
2. これは11になる
6. 記入上で飛ばしても連続数で12となる
```

## 用語リスト

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

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

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

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

## 引用
## 引用・中央揃え・右揃え

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

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

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

中央揃えの段落を表現するには、「`//centering{ 〜 //}`」を使います。同様に右寄せにするには「`//flushright{ 〜 //}`」を使います。複数の段落を入れる場合は、空行で区切ります。

例:

```
//centering{
これは

中央合わせ
//}

//flushright{
これは

右寄せ合わせ
//}
```

## 囲み記事

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

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

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

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

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

## 生データ行

Re:VIEW のタグ範囲を超えて何か特別な行を挿入したい場合、`//raw` ブロック命令や`//embed`ブロック命令、または `@<raw>` インライン命令や `@<embed>` インライン命令を使います。

### `//raw`行

例:

```
//raw[|html|<div class="special">\nここは特別な行です。\n</div>]
```

ブロック命令は1つだけオプションをとり、「|ビルダ名|そのまま出力させる内容」という書式です。`\n`は改行文字に変換されます。

ビルダ名には「`html`」「`latex`」「`idgxml`」「`markdown`」「`top`」のいずれかが入ります。ビルダ名は「,」で区切って複数指定することも可能です。該当のビルダを使用しているときのみ、内容が出力されます。

例:

```
（HTMLビルダの場合:）
<div class="special">
ここは特別な行です。
</div>

（ほかのビルダの場合は単に無視されて何も出力されない）
```

インライン命令は、`@<raw>{|ビルダ名|〜}` という書式で、記述はブロック命令に同じです。
Re:VIEW のタグ範囲を超えて何か特別な行を挿入したい場合、`//embed`ブロック命令や `@<embed>` インライン命令を使います。ほかに従来の `//raw` ブロック命令および `@<raw>` インライン命令もありますが、IDGXML ビルダ以外での使用は推奨しません。

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

Expand Down Expand Up @@ -963,13 +973,38 @@ LaTeXビルダを使用している場合:

```

### `//raw`行（IDGXML ビルダ以外では非推奨）

例:

```
//raw[|html|<div class="special">\nここは特別な行です。\n</div>]
```

ブロック命令は1つだけオプションをとり、「|ビルダ名|そのまま出力させる内容」という書式です。`\n`は改行文字に変換されます。

ビルダ名には「`html`」「`latex`」「`idgxml`」「`markdown`」「`top`」のいずれかが入ります。ビルダ名は「,」で区切って複数指定することも可能です。該当のビルダを使用しているときのみ、内容が出力されます。

例:

```
（HTMLビルダの場合:）
<div class="special">
ここは特別な行です。
</div>

（ほかのビルダの場合は単に無視されて何も出力されない）
```

インライン命令は、`@<raw>{|ビルダ名|〜}` という書式で、記述はブロック命令に同じです。

`//raw`、`//embed`、`@<raw>` および `@<embed>` は、HTML、XML や TeX の文書構造を容易に壊す可能性があります。使用には十分に注意してください。

### 入れ子の箇条書き

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

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

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

### 参照
* `@<chap>{章ファイル名}` : 「第17章」のような、章番号を含むテキストに置換されます。
Expand All @@ -1075,8 +1112,8 @@ UL1-OL1-PARAGRAPH
* `@<m>{数式}` : インラインの数式を出力します。
* `@<w>{キー}` : キー文字列に対応する、単語ファイル内の値文字列を展開します。
* `@<wb>{キー}` : キー文字列に対応する、単語ファイル内の値文字列を展開し、太字にします。
* `@<raw>{|ビルダ|〜}` : 生の文字列を出力します。`\}`は`}`に、`\\`は`\`に、`\n`は改行に置き換えられます。
* `@<embed>{|ビルダ|〜}` : 生の文字列を埋め込みます。`\}`は`}`に、`\\`は`\`に置き換えられます（`\n`はそのままです）。
* `@<raw>{|ビルダ|〜}` : 生の文字列を出力します。`\}`は`}`に、`\\`は`\`に、`\n`は改行に置き換えられます（非推奨）。
* `@<idx>{文字列}` : 文字列を出力するとともに、索引として登録します。索引の使い方については、makeindex.ja.md を参照してください。
* `@<hidx>{文字列}` : 索引として登録します (idx と異なり、紙面内に出力はしません)。`親索引文字列<<>>子索引文字列` のように親子関係にある索引も定義できます。
* `@<balloon>{〜}` : コードブロック (emlist など) 内などでのいわゆる吹き出しを作成します。たとえば「`@<balloon>{ABC}`」とすると、「`←ABC`」となります。デフォルトの挙動および表現は簡素なので、より装飾されたものにするにはスタイルシートを改変するか、`review-ext.rb` を使って挙動を書き換える必要があります。
Expand Down
101 changes: 68 additions & 33 deletions doc/format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The document is a brief guide for Re:VIEW markup syntax.

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

This document explains about the format of Re:VIEW 5.3.
This document explains about the format of Re:VIEW 5.5.

## Paragraph

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

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

Usage:

Expand All @@ -122,15 +122,24 @@ Usage:
3. 3rd condition
```

The value of Number is ignored.
You must write one more space character at line head like itemize.

Whether the numbers appear as described depends on the software that produces the output.

* HTML (EPUB), TeX: The number will start from 1 regardless of the number entered.
* IDGXML, text: The numbers will be output as described. Therefore, writing all numbers as "1." will produce strange results.

In HTML (EPUB) and TeX builders, use `//olnum[number]` to change the first number. Note that the intermediate numbers cannot be changed.

Usage:

```
1. 1st condition
1. 2nd condition
1. 3rd condition
```
//olnum[10]

You must write one more space character at line head like itemize.
1. This number will be 10
2. This number will be 11
6. 12 in continuity, not 6 or 15.
```

## Definition List

Expand Down Expand Up @@ -512,6 +521,26 @@ Seeing is believing.

You can use inline markup in quotations.

Center-aligned paragraphs are represented by `//centering{ ~ //}` and right-aligned paragraphs by `//flushright{ ~ //}`.

To include multiple paragraphs, separate them with a blank line.

Usage:

```
//centering{
This is

center aligned.
//}

//flushright{
This is

right aligned.
//}
```

## Short column

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

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

There is `@<m>{ ... }` for inline (see "Fence notation for inline commands" section also).
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).

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

Expand Down Expand Up @@ -943,20 +972,27 @@ Usage:

## Raw Data Block

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

### `//raw` block
### `//embed` block

Usage:

```
//raw[|html|<div class="special">\nthis is a special line.\n</div>]
//embed{
<div class="special">
this is a special line.
</div>
//}

//embed[html,markdown]{
<div class="special">
this is a special line.
</div>
//}
```

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

Output:

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

(In other formats, it is just ignored.)

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

### `//embed` block
### `//raw` block

`//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).

Usage:

```
//embed{
<div class="special">
this is a special line.
</div>
//}

//embed[html,markdown]{
<div class="special">
this is a special line.
</div>
//}
//raw[|html|<div class="special">\nthis is a special line.\n</div>]
```

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

Output:

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

(In other formats, it is just ignored.)

Note: `//embed`, `@<embed>`, `//raw` and `@<raw>` may break structured document easily.

### Nested itemize block

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.

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.
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.

```
* UL1
Expand Down Expand Up @@ -1091,9 +1124,11 @@ Output:
@<tti>{FooClass}:: teletype (monospaced font) and italic
@<ttb>{BarClass}:: teletype (monospaced font) and bold
@<code>{a.foo(bar)}:: teletype (monospaced font) for fragments of code
@<tcy>{}:: short horizontal text in vertical text
@<tcy>{text}:: short horizontal text in vertical text
@<ins>{sentence}:: inserted part (underline)
@<del>{sentence}:: deleted part (strike through)
@<sup>{text}:: superscript
@<sub>{text}:: subscript
```

### References
Expand Down Expand Up @@ -1121,8 +1156,8 @@ Output:
@<m>{a + \alpha}:: TeX inline equation
@<w>{key}:: expand the value corresponding to the key.
@<wb>{key}:: expand the value corresponding to the key with bold style.
@<raw>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}`, `\\` is `\`, and `\n` is newline.
@<embed>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}` and `\\` is `\`.
@<raw>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}`, `\\` is `\`, and `\n` is newline. (deprecated)
@<idx>{string}:: output a string and register it as an index. See makeindex.md.
@<hidx>{string}:: register a string as an index. A leveled index is expressed like `parent<<>>child`
@<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`
Expand Down
Loading