review 2.0.0.beta1 → 2.0.0

data/doc/format.md

@@ -2,7 +2,10 @@
 
 The document is a brief guide for Re:VIEW markup syntax.
 
-Re:VIEW is based on EWB of ASCII, influenced RD and other Wiki system's 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 2.0.
+
 
 ## Paragraph
 
@@ -22,6 +25,7 @@ Two empty lines or more are same as one empty line.
 ## Chapter, Section, Subsection (headings)
 
 Chapters, sections, subsections, subsubsections use `=`, `==`, `===`, `====`, `=====`.
+You should add one or more spaces after `=`.
 
 Usage:
 
@@ -39,9 +43,11 @@ Usage:
 
 Headings should not have any spaces before title; if line head has space, it is as paragraph.
 
+You should add emply lines between Paragraphs and Headings.
+
 ## Column
 
-`[column]` in heading are column's caption.
+`[column]` in a heading are column's caption.
 
 Usage:
 
@@ -75,9 +81,15 @@ Compiler-compiler is ...
 blah, blah, blah (this is paragraphs outside of the column)
 ```
 
+There are some more options of headings.
+
+* `[nonum]` : no numbering, but add it into TOC (Table of Contents).
+* `[nodisp]` : not display in document, only in TOC.
+* `[notoc]` :  no numbering, not in TOC.
+
 ## Itemize
 
-Itemize (ul in HTML) use ` *` (one space char and asterisk).
+Itemize (ul in HTML) uses ` *` (one space char and asterisk).
 
 Nested itemize is like ` **`, ` ***`.
 
@@ -94,9 +106,11 @@ Usage:
 In itemize, you must write one more space character at line head.
 When you use `*` without spaces in line head, it's just paragraph.
 
-## Ordered itemize
+You should add emply lines between Paragraphs and Itemize (same as Ordered and Non-Orderd).
 
-Ordered itemize (ol in HTML)  use ` 1. ...`, ` 2. ...`, ` 3. ...`.
+## Ordered Itemize
+
+Ordered itemize (ol in HTML)  uses ` 1. ...`, ` 2. ...`, ` 3. ...`.
 They aren't nested.
 
 Usage:
@@ -142,7 +156,44 @@ After dt line, space-indented lines are descriptions(dd in HTML).
 
 You can use inline markup in texts of lists.
 
-## Code list
+## Block Commands and Inline Commands
+
+With the exception of headings and lists, Re:VIEW supports consistent syntax.
+
+Block commands are used for multiple lines to add some actions (ex. decoration).
+
+The syntax of block commands is below:
+
+```
+//command[option1][option2]...{
+(content lines, sometimes separated by empty lines)
+  ...
+//}
+```
+
+If there is no options, the begining line is just `//command{`.  When you want to use a character `]`, you must use escaping `\]`.
+
+Some block commands has no content.
+
+```
+//command[option1][option2]...
+```
+
+Inline commands are used in block,  paragraphes, headings, block contents and block options.
+
+```
+@<command>{content}
+```
+
+When you want to use a character `}` in inline content, you must use escaping `\}`.
+
+There are some limitations in blocks and inlines.
+
+* Block commands do not support nestins.  You cannot write blocks in another block.
+* You cannot write headings and itemize in block contents.
+* Inline commands also do not support nestins.  You cannot write inlines in another inline.
+
+## Code List
 
 Code list like source codes is `//list`. If you don't need numbers, you can use ``em`` prefix (as embedded). If you need line numbers, you can use ``num`` postfix.  So you can use four types of lists.
 
@@ -179,7 +230,7 @@ puts "hello world!"
 Usage:
 
 ```review
-//emlist[][ruby]{
+//emlist[][c]{
 printf("hello");
 //}
 ```
@@ -192,14 +243,16 @@ puts "hello world!"
 //}
 ```
 
+The Language option is used for highlightings.
 
 You can use inline markup in blocks.
 
 When you refer a list like `see list X`, you can use an ID in `//list`
 such as `@<list>{main}`.
 
+When you refer a list in the other chapter, you can use an ID with chapter ID, such like `@<list>{advanced|main}`, to refer a list `main` in `advanced.re`.
 
-### Quoting source code
+### Quoting Source Code
 
 `//source` is for quoting source code. filename is mandatory.
 
@@ -222,7 +275,7 @@ Usage:
 When you ..., see @<list>{hello}.
 ```
 
-## Inline source code
+## Inline Source Code
 
 You can use `@<code>{...}` in inline context.
 
@@ -232,15 +285,16 @@ Usage:
 @<code>{p = obj.ref_cnt}
 ```
 
-## Shell session
+## Shell Session
 
 When you want to show command line operation, you can use `//cmd{ ... //}`.
+You can use inline commands in this command.
 
 Usage:
 
 ```
 //cmd{
-$ ls /
+$ @<b>{ls /}
 //}
 ```
 
@@ -267,6 +321,8 @@ V1 --> V6 --|
 //}
 ```
 
+The third option is used to define the scale of images.  `scale=X` is scaling for page width (`scale=0.5` makes image width to be half of page width).
+
 When you want to refer images such as "see figure 1.", you can use
 inline reference markup like `@<img>{unixhistory}`.
 
@@ -291,6 +347,10 @@ The order of finding image is as follows.  The first matched one is used.
 * ``<id>`` is the ID of the first argument of `//image`.  You should use only printable ASCII characters as ID.
 * ``<ext>`` is file extensions of Re:VIEW.  They are different by the builder you use.
 
+### Inline Images
+
+When you want to use images in paragraph, you can use the inline command `@<icon>{ID}`.  The order of finding images are same as `//image`.
+
 ## Images without caption counter
 
 `//indepimage[filename][caption]` makes images without caption counter.
@@ -351,7 +411,21 @@ When you want to write "see table X", you can write `@<table>{envvars}`.
 
 You can use inline markup in the tables.
 
-## Quoting text
+### Complex Table
+
+If you want to use complex tables, you can use `imgtable` block command with an image of the table.  `imgtable` supports numbering and `@<table>`.
+
+Usage:
+
+```
+//imgtable[complexmatrix][very complex table]{
+to use image "complexmatrix".
+The rule of finding images is same as image command.
+//}
+```
+
+
+## Quoting Text
 
 You can use `//quote{ 〜 //}` as quotations.
 
@@ -365,6 +439,22 @@ Seeing is believing.
 
 You can use inline markup in quotations.
 
+## Short column
+
+Some block commands are used for short column.
+
+* `//note[caption]{ 〜 //}`
+* `//memo[caption]{ 〜 //}`
+* `//tip[caption]{ 〜 //}`
+* `//info[caption]{ 〜 //}`
+* `//warning[caption]{ 〜 //}`
+* `//important[caption]{ 〜 //}`
+* `//caution[caption]{ 〜 //}`
+* `//notice[caption]{ 〜 //}`
+
+`[caption]` is optional.
+
+The content is like paragraph; separated by empty lines.
 
 ## Footnotes
 
@@ -383,7 +473,7 @@ is in footnotes.
 
 Note that In LATEXBuilder, you should use `footnotetext` option to use `@<fn>{...}` in columns and tables.
 
-### --footnotetext option
+### `--footnotetext` option
 
 When you want to use `footnotetext` option, you can add `--footnotetext` with `params` in config.yml.
 With this option, you can use footnote in tables and short notes.
@@ -429,7 +519,7 @@ Usage:
 … is the well-known project.(@<bib>{lins})
 ```
 
-## Lead sentences
+## Lead Sentences
 
 lead sentences are `//lead{ ... //}`.
 You can write as `//read{ ... //}`.
@@ -443,7 +533,7 @@ and I show the way how to write a program in Linux.
 //}
 ```
 
-## TeX equations
+## TeX Equations
 
 You can use `//texequation{ ... //}` to insert mathematical equations of LaTeX.
 
@@ -460,11 +550,89 @@ Usage:
 `//noindent` is a tag for spacing.
 
 
-* `//noindent` : ingore indentation immediately following line. (in HTML, use noindent class)
+* `//noindent` : ingore indentation immediately following line. (in HTML, add `noindent` class)
 
 
 `//linebreak` and `//pagebreak` will be obsoleted.
 
+
+## Referring headings
+
+There are 3 inline commands to refer a chapter.  These references use Chapter ID. The Chapter ID is filename of chapter without extentions.  For example, Chapter ID of `advanced.re` is `advance`.
+
+* `@<chap>{ChapterID}` : chapter number (ex. `Chapter 17`).
+* `@<title>{ChapterID}` : chapter title
+* `@<chapref>{ChapterID}` : chapter number and chapter title (ex. `Chapter 17. other topics`).
+
+`@<hd>` generate referred section title and section number.
+You can use deeper section with separator `|`.
+
+Usage:
+
+```
+@<hd>{intro|first section}
+```
+
+If section title is unique, `|` is not needed.
+
+```
+@<hd>{first section}
+```
+
+If you want to refer another chapter (file), you should add the chapter ID.
+
+Usage:
+
+```
+@<hd>{preface|Introduction|first section}
+```
+
+When section has the label, you can use the label.
+
+```
+=={intro} Introduction
+:
+=== first section
+:
+@<hd>{intro|first section}
+```
+
+
+### Heading of columns
+
+You can refer the heading of a column with `@<column>`.
+
+Usage:
+
+```
+@<column>{The usage of Re:VIEW}
+```
+
+You can refer labels.
+
+```
+==[column]{review-application} The application of Re:VIEW
+:
+@<column>{review-application}
+```
+
+## Links
+
+You can add a hyperlink with `@<href>` and `//label`.
+Notation of the markup is `@<href>{URL, anchor}`. If you can use URL itself
+as anchor, use `@<href>{URL}`.
+If you want to use `,` in URL, use `\,`.
+
+Usage:
+
+```
+@<href>{http://github.com/, GitHub}
+@<href>{http://www.google.com/}
+@<href>{#point1, point1 in document}
+@<href>{chap1.html#point1, point1 in document}
+//label[point1]
+```
+
 ## Comments
 
 If you want to write some comments that do not output in the document, you can use comment notation `#@#`.
@@ -491,7 +659,7 @@ Usage:
 @<comment>{TODO}
 ```
 
-## Raw data block
+## Raw Data Block
 
 When you want to write non-Re:VIEW line, use `//raw`.
 
@@ -520,58 +688,15 @@ this is a special line.
 
 Note: `//raw` and `@<raw>` may break structured document easily.
 
-## Other syntax
-
-In Re:VIEW, you can add your customized blocks.  So you can define
-special block for some books.
-
-* `//prototype` : function prototype. It's used in the book `Futu no Linux programming`.
-* `//type` : type definition. It's used in the book `Futu no Haskell programming`.
+## Inline Commands
 
-You can define customized block in the file `review-ext.rb`.
-
-Usage:
-
-```ruby
-# review-ext.rb
-ReVIEW::Compiler.defblock :foo, 0..1
-class ReVIEW::HTMLBuilder
-  def foo(lines, caption = nil)
-    puts lines.join(",")
-  end
-end
-```
-
-You can add the syntax as below:
+### Styles
 
 ```
-//foo{
-A
-B
-C
-//}
-```
-
-```
-# Result
-A,B,C
-```
-
-
-## Syntax in paragraph (Inline Markups)
-
-```
-@<list>{program}:: `List 1.5`
-@<img>{unixhistory}:: `Figure 1.3`
-@<table>{ascii}:: `Table 1.2`
-@<fn>{site}:: footnote number
 @<kw>{Credential, credential}:: keyword.
-@<chap>{advanced}:: chapter number like `Chapter 17`
-@<title>{advanced}:: title of the chapter
-@<chapref>{advanced}:: a chapter number and chapter title like `Chapter 17. advanced topic`
 @<bou>{appropriate}:: bou-ten.
-@<ruby>{Matsumoto, Matz}:: ruby
 @<ami>{point}:: ami-kake (shaded text)
+@<u>{AB}:: underline
 @<b>{Please}:: bold
 @<i>{Please}:: italic
 @<strong>{Please}:: strong(emphasis)
@@ -579,19 +704,39 @@ A,B,C
 @<tt>{foo($bar)}:: teletype (monospaced font)
 @<tti>{FooClass}:: teletype (monospaced font) and italic
 @<ttb>{BarClass}:: teletype (monospaced font) and bold
-@<u>{AB}:: underline
+@<code>{a.foo(bar)}:: teletype (monospaced font) for fragments of code
+@<tcy>{}:: short horizontal text in vertical text
+```
+
+### References
+
+```
+@<chap>{advanced}:: chapter number like `Chapter 17`
+@<title>{advanced}:: title of the chapter
+@<chapref>{advanced}:: a chapter number and chapter title like `Chapter 17. advanced topic`
+@<list>{program}:: `List 1.5`
+@<img>{unixhistory}:: `Figure 1.3`
+@<table>{ascii}:: `Table 1.2`
+@<hd>{advanced|Other Topics}:: `7-3. Other Topics`
+@<column>{another-column}:: reference of column.
+```
+
+### Other inline commands
+
+```
+@<ruby>{Matsumoto, Matz}:: ruby markups
 @<br>{}::  linebreak in paragraph
-@<m>{a + \alpha}:: TeX inline equation
-@<icon>{samplephoto}:: inline image
 @<uchar>{2460}:: Unicode code point
 @<href>{http://www.google.com/, google}:: hyper link(URL)
+@<icon>{samplephoto}:: inline image
+@<m>{a + \alpha}:: TeX inline equation
 @<raw>{|html|<span>ABC</span>}:: inline raw data inline. `\}` is `}` and `\\` is `\`.
 ```
 
-## Tags for Authors (pre-processor commands)
+## Commands for Authors (pre-processor commands)
 
-These tags are used in the output document. In contrast,
-tags as below are not used in the output document,  used
+These commands are used in the output document. In contrast,
+commands as below are not used in the output document,  used
 by the author.
 
 ```
@@ -603,144 +748,106 @@ by the author.
 #@mapoutput(command) ... #@end:: Execute command and insert their output.
 ```
 
-## HTML/LaTeX layout
-
-`layouts/layout.html.erb` and `layouts/layout.tex.erb` are used as layout file.
-You can use ERb tags in the layout files.
-
-
-Sample layout file(layout.html.erb):
-
-```html
-<html>
-  <head>
-    <title><%= title %></title>
-  </head>
-  <body>
-    <%= body %>
-    <hr/>
-  </body>
-</html>
-```
-
-## Part title (in TOC)
+You should use these commands with preprocessor command `review-preproc`.
 
-In version 1.2 or before, you can define the parts in PART file.
-PART file correspond with chapters in CHAPS file.
-
-Usage:
+## Internationalization (i18n)
 
-```
-CHAPS:
-  intro.re
+Re:VIEW support I18N of some text like `Chapter`, `Figure`, and `Table`.
+Current default language is Japanese.
 
-  start.re
+You add the file locale.yml in the project directory.
 
-  end.re
-```
+Sample local.yml file:
 
-```
-PART:
-  (empty line)
-  start section
-  last section
+```yaml
+locale: en
 ```
 
-In version 1.3 or after, you can use catalog.yml file.
-For more information of catalog.yml, see Re:VIEW catalog file guide(catalog.md).
-
-## Referring headings
-
-`@<hd>` generate referred section title and section number.
-You can use deeper section with separator `|`.
+If you want to customize texts, overwrite items.
+Default locale configuration file is in lib/review/i18n.yml.
 
-Usage:
+Sample local.yml file:
 
-```
-@<hd>{intro|first section}
+```yaml
+locale: en
+image: Fig.
+table: Tbl.
 ```
 
-If section title is unique, `|` is not needed.
+### Re:VIEW Custom Format
 
-```
-@<hd>{first section}
-```
+In `locale.yml`, you can use these Re:VIEW custom format.
 
-If you want to refer another chapter (file), you should add the ID of chapter.
+* `%pA` : Alphabet (A, B, C, ...)
+* `%pa` : alphabet (a, b, c, ...)
+* `%pAW` : Alphabet (Large Width) Ａ, Ｂ, Ｃ, ...
+* `%paW` : alphabet (Large Width) ａ, ｂ, ｃ, ...
+* `%pR` : Roman Number (I, II, III, ...)
+* `%pr` : roman number (i, ii, iii, ...)
+* `%pRW` : Roman Number (Large Width) Ⅰ, Ⅱ, Ⅲ, ...
+* `%pJ` : Chainese Number 一, 二, 三, ...
+* `%pdW' : Arabic Number (Large Width for 0..9) １, ２, ...,９, 10, ...
+* `%pDW' : Arabic Number (Large Width) １, ２, ... １０, ...
 
 Usage:
 
 ```
-@<hd>{preface|Introduction|first section}
-```
-
-When section has the label, you can use the label.
-
-```
-=={intro} Introduction
-:
-=== first section
-:
-@<hd>{intro|first section}
+locale: en
+  part: Part. %pRW
+  appendix: Appendix. %pA
 ```
 
+## Other Syntax
 
-### Heading of columns
+In Re:VIEW, you can add your customized blocks and inlines.
 
-You can refer the heading of a column with `@<column>`.
+You can define customized commands in the file `review-ext.rb`.
 
 Usage:
 
-```
-@<column>{The usage of Re:VIEW}
+```ruby
+# review-ext.rb
+ReVIEW::Compiler.defblock :foo, 0..1
+class ReVIEW::HTMLBuilder
+  def foo(lines, caption = nil)
+    puts lines.join(",")
+  end
+end
 ```
 
-You can refer labels.
+You can add the syntax as below:
 
 ```
-==[column]{review-application} The application of Re:VIEW
-:
-@<column>{review-application}
+//foo{
+A
+B
+C
+//}
 ```
 
-## Links
-
-You can add a hyperlink with `@<href>` and `//label`.
-Notation of the markup is `@<href>{URL, anchor}`. If you can use URL itself
-as anchor, use `@<href>{URL}`.
-If you want to use `,` in URL, use `\,`.
-
-Usage:
-
 ```
-@<href>{http://github.com/, GitHub}
-@<href>{http://www.google.com/}
-@<href>{#point1, point1 in document}
-@<href>{chap1.html#point1, point1 in document}
-//label[point1]
+# Result
+A,B,C
 ```
 
-## Internationalization (i18n)
 
-Re:VIEW support I18N of some text like `Chapter`, `Figure`, and `Table`.
-Current default language is Japanese.
+## HTML/LaTeX Layout
 
+`layouts/layout.html.erb` and `layouts/layout.tex.erb` are used as layout file.
+You can use ERb tags in the layout files.
 
-You add the file locale.yml in the project directory.
 
-Sample local.yml file:
+Sample layout file(layout.html.erb):
 
-```yaml
-locale: ja
+```html
+<html>
+  <head>
+    <title><%= @config["booktitle"] %></title>
+  </head>
+  <body>
+    <%= @body %>
+    <hr/>
+  </body>
+</html>
 ```
 
-If you want to customize texts, overwrite items.
-Default locale configuration file is in lib/review/i18n.yml.
-
-Sample local.yml file:
-
-```yaml
-locale: en
-image: Fig.
-table: Tbl.
-```