1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417
|
= Asciidoctor
Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]>
v1.5.8, 2018-10-28
// settings:
:page-layout: base
:idprefix:
:idseparator: -
:source-language: ruby
:language: {source-language}
ifndef::env-github[:icons: font]
ifdef::env-github[]
:status:
:outfilesuffix: .adoc
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
// Variables:
:release-version: 1.5.8
// URIs:
:uri-org: https://github.com/asciidoctor
:uri-repo: {uri-org}/asciidoctor
:uri-asciidoctorj: {uri-org}/asciidoctorj
:uri-asciidoctorjs: {uri-org}/asciidoctor.js
:uri-project: http://asciidoctor.org
ifdef::env-site[:uri-project: link:]
:uri-docs: {uri-project}/docs
:uri-news: {uri-project}/news
:uri-manpage: {uri-project}/man/asciidoctor
:uri-issues: {uri-repo}/issues
:uri-contributors: {uri-repo}/graphs/contributors
:uri-rel-file-base: link:
:uri-rel-tree-base: link:
ifdef::env-site[]
:uri-rel-file-base: {uri-repo}/blob/master/
:uri-rel-tree-base: {uri-repo}/tree/master/
endif::[]
:uri-changelog: {uri-rel-file-base}CHANGELOG.adoc
:uri-contribute: {uri-rel-file-base}CONTRIBUTING.adoc
:uri-license: {uri-rel-file-base}LICENSE
:uri-tests: {uri-rel-tree-base}test
:uri-discuss: http://discuss.asciidoctor.org
:uri-irc: irc://irc.freenode.org/#asciidoctor
:uri-rubygem: https://rubygems.org/gems/asciidoctor
:uri-what-is-asciidoc: {uri-docs}/what-is-asciidoc
:uri-user-manual: {uri-docs}/user-manual
:uri-install-docker: https://github.com/asciidoctor/docker-asciidoctor
//:uri-install-doc: {uri-docs}/install-toolchain
:uri-install-osx-doc: {uri-docs}/install-asciidoctor-macosx
:uri-render-doc: {uri-docs}/render-documents
:uri-themes-doc: {uri-docs}/produce-custom-themes-using-asciidoctor-stylesheet-factory
:uri-gitscm-repo: https://github.com/git/git-scm.com
:uri-prototype: {uri-gitscm-repo}/commits/master/lib/asciidoc.rb
:uri-freesoftware: https://www.gnu.org/philosophy/free-sw.html
:uri-foundation: http://foundation.zurb.com
:uri-tilt: https://github.com/rtomayko/tilt
:uri-ruby: https://ruby-lang.org
// images:
:image-uri-screenshot: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/screenshot.png
{uri-project}/[Asciidoctor]は _高速な_ テキストプロセッサで {uri-what-is-asciidoc}[AsciiDoc] をHTML5, DocBook 5(4.5)や他のフォーマットに変換するツールチェインを配布しています.
AsciidoctorはRubyで書かれており, RubyGemとしてパッケージされ, {uri-rubygem}[RubyGems.org] で配布されています.
gemはいくつかのLinuxディストリビューション, Fedora, Debian, Ubuntuにも含まれています.
Asciidoctorはオープンソース {uri-repo}[hosted on Github] で {uri-license}[the MIT licence]のもとに配布されます.
ifndef::env-site[]
Translations of this document are available in the following languages:
* {uri-rel-file-base}README-zh_CN.adoc[汉语]
* {uri-rel-file-base}README.adoc[English]
* {uri-rel-file-base}README-fr.adoc[Français]
endif::[]
.Key documentation
[.compact]
* {uri-docs}/what-is-asciidoc[What is AsciiDoc?]
* {uri-docs}/asciidoc-writers-guide[AsciiDoc Writer's Guide]
* {uri-docs}/asciidoc-syntax-quick-reference[AsciiDoc Syntax Reference]
* {uri-docs}/user-manual[Asciidoctor User Manual]
.Rubyの行く先, Asciidoctorの追うところ
****
AsciidoctorはJRubyを用いてJVM上でも実行できます.
Javaや他のJVM言語からAsciidoctor APIを直接呼び出すには, {uri-asciidoctorj}[AsciidoctorJ] を使ってください.
AsciidoctorJに基づいた, AsciidoctorプロセッサをApache Maven, GradleやJavadocに統合するプラグインがあります.
AsciidoctorはJavaScriptでも実行可能です.
{uri-asciidoctorjs}[Asciidoctor.js], WebブラウザやNode.jsのようなJavaScript環境で動くAsciidoctorの完全機能版, を生成するために, RubyのソースをJavaScriptにトランスパイルするのに http://opalrb.org[Opal]を使います.
Asciidoctor.jsはChrome, Atom, Brackets や他のウェブベースのツールの拡張機能としてAsciiDocのプレビューのために使われます.
****
ifdef::status[]
.*Project health*
image:https://img.shields.io/travis/asciidoctor/asciidoctor/master.svg[Build Status (Travis CI), link=https://travis-ci.org/asciidoctor/asciidoctor]
image:https://ci.appveyor.com/api/projects/status/ifplu67oxvgn6ceq/branch/master?svg=true&passingText=green%20bar&failingText=%23fail&pendingText=building%2E%2E%2E[Build Status (AppVeyor), link=https://ci.appveyor.com/project/asciidoctor/asciidoctor]
//image:https://img.shields.io/coveralls/asciidoctor/asciidoctor/master.svg[Coverage Status, link=https://coveralls.io/r/asciidoctor/asciidoctor]
image:https://codeclimate.com/github/asciidoctor/asciidoctor/badges/gpa.svg[Code Climate, link="https://codeclimate.com/github/asciidoctor/asciidoctor"]
image:https://inch-ci.org/github/asciidoctor/asciidoctor.svg?branch=master[Inline docs, link="https://inch-ci.org/github/asciidoctor/asciidoctor"]
endif::[]
== The Big Picture
Asciidoctorは下図の左側のパネルに示されるように, 平文で書かれた内容を読み, 右のパネルに描かれるようにHTML5に変換します.
Asciidoctorは枠にとらわれない快適なエクスペリエンスのためにデフォルトスタイルシートをHTML5ドキュメントに適用します.
image::{image-uri-screenshot}[Preview of AsciiDoc source and corresponding rendered HTML]
== AsciiDoc Processing
AsciidoctorはAsciiDoc文法で書かれたテキストを読み込み解釈し, それからHTML5, DocBook5(4.5)やman(ual)を出力するために内蔵コンバータセットにパースツリーを渡します.
生成された出力をカスタマイズ, あるいは追加のフォーマットをつくるためにあなた自身のコンバータを使うことや {uri-tilt}[Tilt]-supported テンプレートを読み込むオプションがあります.
NOTE: AsciidoctorはオリジナルのAsciiDoc Pythonプロセッサ(`asciidoc.py`)の完全互換です.
Asciidoctorテストスイートは {uri-tests}[> 1,600 tests] をAsciiDoc文法との互換性を保証するために有しています.
クラシックなAsciiDoc文法に加えて, Asciidoctorは追加のマークアップとフォントベースのicons(例えば, `+icon:fire[]+`)などのフォーマッティングオプションとUIエレメント(`+button:[Save]+`)を 受け付けます.
AsciidoctorはHTML5出力をスタイルするため, モダンで, {uri-foundation}[Foundation] に基づいたレスポンシブテーマをも提供します.
== Requirements
AsciidoctorはLinux, OS X (Mac)とWindowsで動き, 下記の {uri-ruby}[Ruby]実装の一つを必要とします.
* MRI (Ruby 1.8.7, 1.9.3, 2.0, 2.1, 2.2 & 2.3)
* JRuby (1.7 in Ruby 1.8 and 1.9 modes, 9000)
* Rubinius 2.2.x
* Opal (JavaScript)
[CAUTION]
====
もし非英語環境のWindowsを使っているなら, Asciidoctorを起動した時に `Encoding::UndefinedConversionError` に遭遇するでしょう.
これを解決するには使っているコンソールの有効なコードページをUTF-8:
chcp 65001
に変更することを推奨します.
一度この変更をすると, Unicode関連の頭痛の種は消えるでしょう.
もしEclipseのようなIDEを使っているなら, 同様にエンコーディングをUTF-8にするのを忘れないでください.
AsciidoctorはUTF-8が使われているところで最高の働きを見せます.
====
== Installation
Asciidoctorは (a) `gem install` コマンド, (b) Bundler あるいは (c) 有名Linuxディストリビューションのパッケージマネージャ を用いてインストールされます.
TIP: Linuxパッケージマネージャを用いてインストールすることの利点は, もしRubyやRubyGemsライブラリがまだインストールされていなかったら, それらを処理してくれることです.
欠点はgemのリリース直後にはすぐには有効にならないことです.
もし最新バージョンを使いたければ, 必ず `gem` コマンドを使いましょう.
=== (a) gem install
ターミナルを開き, 入力しましょう (先頭の`$`は除く):
$ gem install asciidoctor
もし, 先行リリースバージョン(例えばリリース候補版)をインストールしたければ
$ gem install asciidoctor --pre
.アップグレード
[TIP]
====
もしAsciidoctorの以前のバージョンがインストール済みであれば, 以下によってアップデートできます:
$ gem update asciidoctor
もし gem update の代わりに `gem install` を使ってgemを新バージョンにした場合, 複数バージョンがインストールされるでしょう.
そのときは, 以下のgemコマンドで古いバージョンを削除しましょう:
$ gem cleanup asciidoctor
====
=== (b) Bundler
. プロジェクトフォルダーのルート(かカレントディレクトリ)にGemfileを作成
. `asciidoctor` gemをGemfileに以下のように追加:
+
[source,subs=attributes+]
----
source 'https://rubygems.org'
gem 'asciidoctor'
# or specify the version explicitly
# gem 'asciidoctor', '{release-version}'
----
. Gemfileを保存
. ターミナルを開き, gemをインストール:
$ bundle
gemをアップグレードするには, Gemfileで新バージョンを指定し, `bundle` を再び実行してください.
`bundle update` は他のgemもアップデートするため推奨されて *いない* ので, 思わぬ結果になるかも知れません.
=== (c) Linux package managers
==== DNF (Fedora 21 or greater)
dnfを使いFedora21かそれ以上にインストールするには, ターミナルを開き, 以下を入力してください:
$ sudo dnf install -y asciidoctor
gemをアップグレードするには:
$ sudo dnf update -y asciidoctor
TIP: お使いのシステムは自動的にrpmパッケージをアップデートするよう設定されているかも知れません.その場合, gemのアップデートのためにあなたがすべきことはありません.
==== apt-get (Debian, Ubuntu, Mint)
Debian, UbuntuまたはMintにインストールするには, ターミナルを開き, 以下を入力してください:
$ sudo apt-get install -y asciidoctor
gemをアップグレードするには:
$ sudo apt-get upgrade -y asciidoctor
TIP: お使いのシステムは自動的にdebパッケージをアップデートするよう設定されているかも知れません.その場合, gemのアップデートのためにあなたがすべきことはありません.
パッケージマネージャ(apt-get)によってインストールされたバージョンのAsciidoctorは最新リリースのAsciidoctorではないかもしれません.
ディストリビューションのリリース毎に, どのバージョンがパッケージされているかはパッケージリポジトリを調べてください.
* https://packages.debian.org/search?keywords=asciidoctor&searchon=names&exact=1&suite=all§ion=all[asciidoctor package by Debian release]
* http://packages.ubuntu.com/search?keywords=asciidoctor&searchon=names&exact=1&suite=all§ion=all[asciidoctor package by Ubuntu release]
* https://community.linuxmint.com/software/view/asciidoctor[asciidoctor package by Mint release]
[CAUTION]
====
パッケージマネージャによって管理されているgemをアップデートするのに `gem udpate` コマンドを使うなといわれるでしょう.
そのようなことをするのは, パッケージマネージャがファイル(/usr/local下にインストールされた)を追跡できなくなるためにシステムが不安定な状態にするためです.
単純に, システムgemはパッケージマネージャによってのみ管理されるべきです.
もし, パッケージマネージャによってインストールされたのより新しいバージョンのAsciidoctorを使いたければ, http://rvm.io[RVM] や https://github.com/rbenv/rbenv[rbenv]を使ってRubyをホームディレクトリ(すなわち, ユーザースペース)にインストールするべきです.
それから, 安心して `gem` コマンドをAsciidoctorのアップデート, インストールのために使うことができます.
RVMやrbenvを使っているなら, gemはシステムからは孤立した場所にインストールされます.
====
==== apk (Alpine Linux)
Alpine Linuxにgemをインストールするには, ターミナルを開き, 以下を入力してください:
$ sudo apk add asciidoctor
gemをアップグレードするには:
$ sudo apk add -u asciidoctor
TIP: お使いのシステムは自動的にapkパッケージをアップデートするよう設定されているかも知れません.その場合, gemのアップデートのためにあなたがすべきことはありません.
=== Other installation options
* {uri-install-docker}[Installing Asciidoctor using Docker]
* {uri-install-osx-doc}[Installing Asciidoctor on Mac OS X]
// at the moment, the following entry is just a reiteration of the information in this README
//* {uri-install-doc}[Installing the Asciidoctor toolchain]
== Usage
Asciidoctorのインストールに成功すれば, `asciidoctor` コマンドラインインターフェース(CLI)がPATH中で有効になります.
確認のために, 以下をターミナルで実行しましょう:
$ asciidoctor --version
AsciidoctorのバージョンとRuby環境についての情報がターミナルに出力されたのを見ることができるはずです.
[.output,subs=attributes+]
....
Asciidoctor {release-version} [http://asciidoctor.org]
Runtime Environment (ruby 2.4.1p111 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
....
AsciidoctorはAPIを提供します.
APIは他のRubyソフトウェア, Rails, SinatraとGitHub, そして他の言語, Java (via {uri-asciidoctorj}[AsciidoctorJ] )とJavaScript (via {uri-asciidoctorjs}[Asciidoctor.js])との統合を意図しています.
=== Command line interface (CLI)
`asciidoctor` コマンドはAsciidoctorをコマンドライン(つまりターミナル)から起動することを可能にします.
次のコマンドはファイルREADME.adocをHTMLに変換し, 結果を同じディレクトリのREADME.htmlに保存します.
生成されたHTMLファイルの名前はソースファイル依存し, その拡張子を `.html` に変えます.
$ asciidoctor README.adoc
Asciidoctorプロセッサに様々なフラグやスイッチを与えることで制御できます.それは以下を用いて調べることができます:
$ asciidoctor --help
例えば, ファイルを異なるディレクトリに書き出すには:
$ asciidoctor -D output README.adoc
`asciidoctor` {uri-manpage}[man page] はコマンドライン・インタフェースの完全なリファレンスを提供します.
`asciidoctor` コマンドの使い方についてもっと学ぶには以下を参照してください.
* {uri-render-doc}[How do I convert a document?]
* {uri-themes-doc}[How do I use the Asciidoctor stylesheet factory to produce custom themes?]
=== Ruby API
Asciidoctorをアプリケーションの中で使うには, まずgemをrequireする必要があります:
[source]
require 'asciidoctor'
それから, AsciiDocソースファイルをHTMLファイルに変換できます:
[source]
Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe
WARNING: AsciidoctorをAPI経由で使っている時, デフォルトのセーフモードは `:secure` です.
セキュアモードでは, `include` ディレクティブを含むいくつかのコア機能は無効化されています.
もしこれらの機能を有効化したい場合, 明示的にセーフモードを `:server` (推奨)か `:safe` にする必要があります.
AsciiDoc文字列を埋め込みHTML(HTMLページヘの挿入)へ変換することもできます:
[source]
----
content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
Asciidoctor.convert content, safe: :safe
----
もし完全なHTMLドキュメントを求めるのであれば, `header_footer` オプションを以下の通り有効にしてください:
[source]
----
content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safe
----
パースされたドキュメントにアクセスしたいのなら, 変換を個々のステップに分割することが出来ます:
[source]
----
content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convert
----
Asciidoctorの生成する出力が気に入らないのであれば, _あなたはそれを変更できる_ ことを忘れないでください!
Asciidoctorはパースされたドキュメントを生成された出力に変換する処理を扱うカスタムコンバーターをサポートしています.
断片的な出力をカスタマイズする簡単な方法の一つはテンプレートコンバーターを使うことです.
テンプレートコンバーターによって, ドキュメント中のあらゆるノードの変換を扱うために {uri-tilt}[Tilt]-supportedテンプレートファイルを使うことができます.
そのようにすれば, 出力を100%制御することが _できます_ .
APIの使い方や出力のカスタマイズ方法についてのより詳しい情報は {uri-user-manual}[user manual] を参照してください.
== Contributing
{uri-freesoftware}[free software] の精神においては, _everyone_ がこのプロジェクトを改良するのをたすけることが勧められています.
もしエラーや手抜かりをソースコード, ドキュメント, あるいはウェブサイトに見つけたのなら, 恥じることなく修正と共にpull requestの開設やissueの送信をしてください.
New contributors are always welcome!
*あなた* にもできることがあります:
* 先行バージョン(alpha, beta or preview)の使用
* バグレポート
* 新機能提案
* ドキュメントの執筆
* 仕様の執筆
* コーディング -- _パッチでも, 足りなすぎるなんてことはありません_
** typoの修正
** コメントの追加
** 一貫性のないホワイトスペースの除去
** テストの記述!
* リファクタリング
* {uri-issues}[issues] の修正
* パッチの批評
{uri-contribute}[Contributing] ガイドはどうやってスタイルをつくるか, issueを送るか, 機能リクエスト, コーディング, ドキュメンテーションをAsciidoctor Projectにするかについての情報を提供しています.
== Getting Help
Asciidoctorプロジェクトはあなたが簡単に著作を書いて, 配布するのをたすけるため開発されています.
しかしあなたのフィードバックなしにはできません!
ディスカッションリストで, Twitterで, チャットルームで, 質問し, プロジェクトのあらゆる側面について話し合うようお勧めします.
Discussion list (Nabble):: {uri-discuss}
Twitter:: #asciidoctor hashtag or @asciidoctor mention
ifdef::env-github[]
以下のプロジェクトサイトに、Asciidoctorに関するさらに詳しい情報やドキュメントがあります。
{uri-project}/[Home] | {uri-news}[News] | {uri-docs}[Docs]
endif::[]
GitHub上のAsciidoctorはプロジェクトのソースコード, イシュートラッカー, サブプロジェクトを管理しています.
Source repository (git):: {uri-repo}
Issue tracker:: {uri-issues}
Asciidoctor organization on GitHub:: {uri-org}
== Copyright and Licensing
Copyright (C) 2012-2018 Dan Allen, Ryan Waldron and the Asciidoctor Project.
本ソフトウェアはMITライセンスのもとで自由に使用できます.
詳細は {uri-license}[LICENSE] ファイルを参照してください.
== Authors
*Asciidoctor* は https://github.com/mojavelinux[Dan Allen] と https://github.com/graphitefriction[Sarah White] が先導し, Asciidoctorの素晴らしきコミュニティの数多くのメンバからコントリビューションを受けてきました.
このプロジェクトは2012年から https://github.com/nickh[Nick Hengeveld] の {uri-prototype}[プロトタイプ] をベースに https://github.com/erebor[Ryan Waldron] により創始されました.
*AsciiDoc* は Stuart Rackham により創始され, AsciiDocコミュニティの数多くのメンバからコントリビューションを受けてきました.
ifndef::env-site[]
== Changelog
ifeval::[{safe-mode-level} < 20]
include::CHANGELOG.adoc[tag=compact,leveloffset=+1]
endif::[]
リリースごとの変更一覧は {uri-changelog}[CHANGELOG] を参照してください.
endif::[]
|