From ac280c83d3dfbb36550d67ec407dccd87dbfb1b3 Mon Sep 17 00:00:00 2001 From: Kenshi Muto Date: Sun, 29 Dec 2019 15:39:29 +0900 Subject: [PATCH] update quickstart to follow v4 --- doc/quickstart.ja.md | 63 ++++++++++++++++++++++++++++---------------- doc/quickstart.md | 48 ++++++++++++++++++++++----------- 2 files changed, 73 insertions(+), 38 deletions(-) diff --git a/doc/quickstart.ja.md b/doc/quickstart.ja.md index 62bd73b69..2546a38d4 100644 --- a/doc/quickstart.ja.md +++ b/doc/quickstart.ja.md @@ -8,11 +8,11 @@ Re:VIEW は GNU Lesser General Public License Version 2.1 に基づいて配布 このドキュメントでは、Re:VIEW のセットアップから変換の例までを簡単に説明します。 -このドキュメントは、Re:VIEW 3.0 に基づいています。 +このドキュメントは、Re:VIEW 4.0 に基づいています。 ## セットアップ -Re:VIEW は Ruby 言語で記述されており、Linux/Unix 互換システムで動作します。macOS および Windows Cygwin でも動作可能です。Ruby gem あるいは Git のいずれかを使ってダウンロード・展開します。 +Re:VIEW は Ruby 言語で記述されており、Linux/Unix 互換システムで動作します。macOS および Windows でも動作可能です。Ruby gem あるいは Git のいずれかを使ってダウンロード・展開します。 なお、Re:VIEW フォーマット自体は文字で表現されたタグが付いている以外は単なるテキストファイルなので、エディタ、OS については UTF-8 文字エンコーディングさえ使用できれば制限はありません。 @@ -34,7 +34,7 @@ Ruby gem の bin ディレクトリにパスを通すようにしておいてく $ gem update review ``` -Gemfile を使っている場合は、以下の行を Gemfile に追加して、`bundle`コマンドを実行します。 +Gemfile を使っている場合は、以下の行を Gemfile に追加して、`bundle` コマンドを実行します。 ```Gemfile gem 'review' @@ -58,29 +58,37 @@ review というディレクトリに展開されるので、review/bin にパ $ git pull ``` -## Re:VIEW ドキュメントの作成 +## Re:VIEW プロジェクトの作成 ### 雛型の作成 -review-init コマンドを使って、雛型となる作業フォルダを作成できます。 +review-init コマンドを使って、雛型となるプロジェクトフォルダを作成できます。 ``` -$ review-init ドキュメント名 +$ review-init プロジェクト名 ``` -これで指定のドキュメント名のフォルダが用意され、中に次のようなファイルが置かれます。 +TeX を利用した PDF 作成を目的としているならば、雛型の作成時に、Web ブラウザによるウィザードモードで基本版面設計を行うことができます。これには `-w` オプションを付けます。 - * ドキュメント名を冠した「.re」拡張子を持つファイル（Re:VIEW フォーマットテキストファイル） +``` +$ review-init -w プロジェクト名 +``` + +「http://localhost:18000」に Web ブラウザでアクセスし、文字数×行数および余白を調整できます。 + +これで指定のプロジェクト名のフォルダが用意され、中に次のようなファイルが置かれます。 + + * プロジェクト名を冠した「.re」拡張子を持つファイル（Re:VIEW フォーマットテキストファイル） * config.yml : 設定ファイル + * config-ebook.yml : 電子ブック用設定ファイル（ウィザードモード使用時） * catalog.yml : カタログファイル（目次構成） * Rakefile : rake コマンドのルールファイル * images : 画像の配置フォルダ - * layouts : レイアウトファイルの配置フォルダ * style.css : サンプルスタイルシート * sty : スタイルファイル配置フォルダ（TeX 用） * doc : 本ドキュメントを含む使い方のドキュメント * lib : 主に rake コマンドの詳細ルールファイル -review-init コマンドによらず、独自に作業フォルダを作成してもかまいません。 +review-init コマンドによらず、独自にプロジェクトフォルダを作成してもかまいません。 ### Re:VIEW テキストの作成と変換 @@ -115,28 +123,37 @@ review-init コマンドによらず、独自に作業フォルダを作成し テキストファイルの文字エンコーディングには、UTF-8 を使用してください。 -### PDF 化と EPUB 化、プレインテキスト化 +### PDF 化と EPUB 化、プレインテキスト化、XML 化 + +review-*maker コマンドで一括して変換作成ができます。 -review-pdfmaker コマンドで PDF ブックの作成、review-epubmaker コマンドで EPUB ファイルの作成、review-textmaker コマンドでプレインテキストの作成ができます。 +- review-pdfmaker コマンド：PDF ブックの作成 +- review-epubmaker コマンド：EPUB ファイルの作成 +- review-textmaker コマンド：プレインテキストの作成 +- review-idgxmlmaker コマンド：InDesign XML の作成 PDF を作成するには、TeXLive2012 以上の環境が必要です。EPUB を作成するには、rubyzip gem あるいは zip コマンドが必要です（MathML も使いたいときには、 [MathML ライブラリ](http://www.hinet.mydns.jp/?mathml.rb)も必要です）。 いずれのコマンドも、必要な設定情報を記した YAML 形式ファイルを引数に指定して実行します。review-init コマンドで作成した環境には、デフォルトで config.yml として用意されているので、これを利用します。 ```bash -$ review-pdfmaker config.yml ←PDFの作成 -$ review-epubmaker config.yml ←EPUBの作成 -$ review-textmaker config.yml ←テキストの作成（装飾情報あり） -$ review-textmaker -n config.yml ←テキストの作成（装飾情報なし） +$ review-pdfmaker config.yml ←PDFの作成 +$ review-pdfmaker config-ebook.yml ←電子ブック設定でのPDFの作成 +$ review-epubmaker config.yml ←EPUBの作成 +$ review-textmaker config.yml ←テキストの作成（装飾情報あり） +$ review-textmaker -n config.yml ←テキストの作成（装飾情報なし） +$ review-idgxmlmaker config.yml ←InDesign XMLの作成 ``` rake コマンドを利用できるなら、次のように実行することもできます。 ```bash $ rake pdf ←PDFの作成 +$ REVIEW_CONFIG_FILE=config-ebook.yml rake pdf ←電子ブック設定でのPDFの作成 $ rake epub ←EPUBの作成 $ rake text ←テキストの作成（装飾情報あり） $ rake plaintext ←テキストの作成（装飾情報なし） +$ rake idgxml ←InDesign XMLの作成 ``` config.yml のサンプルについては以下を参照してください。 @@ -177,7 +194,7 @@ Re:VIEW の使用実例については、https://github.com/reviewml/review-samp $ review-compile --target text sample.re > sample.txt ←テキストにする $ review-compile --target html sample.re > sample.html ←HTMLにする $ review-compile --target latex sample.re > sample.tex ←LaTeXにする -$ review-compile --target idgxml sample.re > sample.xml ←XMLにする +$ review-compile --target idgxml sample.re > sample.xml ←InDesign XMLにする $ review-compile --target markdown sample.re > sample.md ←Markdownにする ``` @@ -206,14 +223,14 @@ $ review-vol $ review-index --level 掘り下げる見出しレベル数 -a ``` -## ドキュメントフォルダを新しい Re:VIEW バージョンに追従する方法 +## プロジェクトフォルダを新しい Re:VIEW バージョンに追従する方法 -Re:VIEW は定期的に更新されています。おおむね後方互換性を保持していますが、新しいバージョン固有の機能を利用したいときには、ドキュメントフォルダを新しいバージョンに更新する review-update コマンドを利用します。 +Re:VIEW は定期的に更新されています。おおむね後方互換性を保持していますが、新しいバージョン固有の機能を利用したいときには、プロジェクトフォルダを新しいバージョンに更新する review-update コマンドを利用します。 ```bash $ review-update -** review-update はプロジェクトを 3.0.0 に更新します ** -config.yml: 'review_version' を '3.0' に更新しますか? [y]/n ←Enterで実行 +** review-update はプロジェクトを 4.0.0 に更新します ** +config.yml: 'review_version' を '4.0' に更新しますか? [y]/n ←Enterで実行 Rakefile は Re:VIEW バージョンのもの (/.../review/samples/sample-book/src/Rakefile) で置き換えられます。本当に進めますか? [y]/n lib/tasks/review.rake は Re:VIEW バージョンのもの (/.../review/samples/sample-book/src/lib/tasks/review.rake) で置き換えられます。本当に進めますか? [y]/n INFO: 新しいファイル /.../sty/plistings.sty が作成されました。 @@ -229,9 +246,9 @@ INFO: 新しいファイル /.../sty/gentombow.sty が作成されました。 ## クレジット -Re:VIEW は、青木峰郎によって最初に作成されました。武藤健志がこの開発・保守を引き継ぎ、2019年2月時点では、武藤健志、高橋征義、角征典が開発・保守を継続しています。 +Re:VIEW は、青木峰郎によって最初に作成されました。武藤健志がこの開発・保守を引き継ぎ、2019年12月時点では、武藤健志、高橋征義、角征典が開発・保守を継続しています。 -バグ・パッチの報告、開発者用メーリングリストなどについての情報は、 +バグ・パッチの報告、その他の情報は、 * http://reviewml.org/ * https://github.com/kmuto/review/wiki diff --git a/doc/quickstart.md b/doc/quickstart.md index 6926b68cf..00b2a8643 100644 --- a/doc/quickstart.md +++ b/doc/quickstart.md @@ -9,7 +9,7 @@ Re:VIEW is free software under the terms of the GNU Lesser General Public Licens This article describes how to setup Re:VIEW and use it. -The supported version of the article is Re:VIEW 3.0. +The supported version of the article is Re:VIEW 4.0. ## Set up Re:VIEW @@ -59,7 +59,7 @@ $ git pull ## Writing Re:VIEW Document -### Generating template fiels +### Generating template files After setup, you can use `review-init` command to generate Re:VIEW project directory. @@ -72,14 +72,23 @@ $ ls hello Rakefile catalog.yml config.yml hello.re images/ layouts/ sty/ style.css ``` +If your purpose is to create a PDF using TeX, it is a good idea to use the wizard mode for basic layouting in a web browser. Add `-w` option to review-init. + +(notice: currently wizard UI supports only Japanese language) + +```bash +$ review-init -w hello +(access http://localhost:18000 on Web browser) +``` + In `hello` directory, many files are generated. * `*.re` : Re:VIEW format file. * config.yml : configuration file +* config-ebook.yml : configuration file for ebook (when using the wizard mode) * catalog.yml : catalog file (for TOC) * Rakefile : rule file for `rake` command * images : folder for images -* layouts : forlder for layout files * style.css : sample stylesheet * sty : style files for LaTeX * doc : various documents (including this document) @@ -116,29 +125,38 @@ The web site of Re:VIEW is @{https://reviewml.org/}. You should use UTF-8 as encodings in text files. -### generating PDF, EPUB, and plain-text +### generating PDF, EPUB, plain-text, and InDesign XML + +To convert files in the project, use review-*maker command. -You can generate a PDF file with `review-pdfmaker` command. Also you can generate an EPUB file with `review-epubmaker` command, and can generate an plain-text file with 'review-textmaker' command. +- review-pdfmaker: generate PDF +- review-epubmaker: generate EPUB +- review-textmaker: genrate plaintext +- review-idgxmlmaker: genrate InDesign XML -To generate PDF, you should install TeXLive 2012 or later. To generate EPUB, you should install zip command. +To generate PDF, you should install TeXLive 2012 or later. To generate EPUB, you should install zip command. When you want to use MathML, you should install [MathML library](http://www.hinet.mydns.jp/?mathml.rb) -Each maker need `config.yml`, configuration YAML files. `review-init` command generates `config.yml` in default. +Each maker need `config.yml`, configuration YAML files. `review-init` command generates `config.yml` in default. ```bash -$ review-pdfmaker config.yml ## generate PDF -$ review-epubmaker config.yml ## generate EPUB -$ review-textmaker config.yml ## generate text with decoration -$ review-textmaker -n config.yml ## generate text without decoration +$ review-pdfmaker config.yml ## generate PDF +$ review-pdfmaker config-ebook.yml ## generate PDF (for ebook) +$ review-epubmaker config.yml ## generate EPUB +$ review-textmaker config.yml ## generate text with decoration +$ review-textmaker -n config.yml ## generate text without decoration +$ review-idgxmlmaker config.yml ## generate InDesign XML ``` You also can generate them with Rake. ```bash $ rake pdf ## generate PDF +$ REVIEW_CONFIG_FILE=config-ebook.yml rake pdf ## generate PDF (for ebook) $ rake epub ## generate EPUB $ rake text ## generate text with decoration $ rake plaintext ## generate text without decoration +$ rake idgxml ## generate InDesign XML ``` There is a sample YAML file [config.yml.sample](https://github.com/kmuto/review/blob/master/doc/config.yml.sample) in the same directory of this document. @@ -210,12 +228,12 @@ $ review-index --level -a ## how to update the document folder to the new Re:VIEW version -Re:VIEW is updated regularly. We Re:VIEW team watch the backward compatibility carefully, but if you want to use the features in the new version, you can use review-update command to update the document folder. +Re:VIEW is updated regularly. We Re:VIEW team watch the backward compatibility carefully, but if you want to use the features in the new version, you can use review-update command to update the project folder. ```bash $ review-update -** review-update updates your project to 3.0.0 ** -config.yml: Update 'review_version' to '3.0'? [y]/n +** review-update updates your project to 4.0.0 ** +config.yml: Update 'review_version' to '4.0'? [y]/n Rakefile will be overridden with Re:VIEW version (/.../review/samples/sample-book/src/Rakefile). Do you really proceed? [y]/n lib/tasks/review.rake will be overridden with Re:VIEW version (/.../review/samples/sample-book/src/lib/tasks/review.rake). Do you really proceed? [y]/n INFO: new file /.../sty/plistings.sty is created. @@ -231,7 +249,7 @@ Finished. ## Copyright -The original author of Re:VIEW is Minero Aoki. The current maintainer is Kenshi Muto(@kmuto), and committers are Masayoshi Takahashi and Masanori Kado (February 2019). +The original author of Re:VIEW is Minero Aoki. The current maintainer is Kenshi Muto(@kmuto), and committers are Masayoshi Takahashi and Masanori Kado (December 2019). If you want to report bugs and patches, or to get more information, see: