"Fossies" - the Fresh Open Source Software Archive

Member "asciidoctor-2.0.10/README-jp.adoc" (1 Jun 2019, 25500 Bytes) of package /linux/www/asciidoctor-2.0.10.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming AsciiDoc format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "README-jp.adoc": 2.0.9_vs_2.0.10.

Asciidoctorは, AsciiDoc で書かれたコンテンツをHTML5, DocBook, PDFなどのフォーマットに変換する, 高速で オープンソース のテキストプロセッサおよびパブリッシングツールチェインです. AsciidoctorはRubyで書かれており, すべての主要オペレーティングシステムで動作します. Asciidoctorプロジェクトは GitHubにホスティング されています.

インストールをシンプルにするため, AsciidoctorはRubyGem(gem)パッケージとして, RubyGems.org で配布されています. さらに, Asciidoctorは主要なLinuxディストリビューション用およびmacOS用パッケージとしても配布されています. AsciidctorはRubyで動作するだけでなく, AsciidoctorJとしてJVM上でも動作します. また, Asciidoctor.jsとしてどのようなJavaScript環境(ブラウザを含む)でも実行できます.

このドキュメントには以下の言語版が存在します:
English | 汉语 | Deutsch | Français

スポンサー

スポンサー のみなさまが, このプロジェクトをサポートし, より良いテクニカルドキュメンテーションの実現にコミットメントをしてくださっていることに感謝します. スポンサーのみなさま, ありがとうございます! みなさまの多くのサポートなくしてAsciidoctorは実現不可能です.

Asciidoctorの主な資金的サポートは, Change Maker である OpenDevise, Strategy Sponsors である Khronos Group とLinda Roberts, そして Pull Request Backers である Brian Dominick, Guillaume Grossetie, Abel Salgado Romero によって提供されています. さらに, Community Backers のページに掲載されているサポーターによって追加的な資金が提供されています.

OpenCollective を通じてスポンサーになることにより, このプロジェクトを支援することができます.

全体像

Asciidoctorは, 下図左側のようなプレーンテキストを読み込んで, 右側のようなHTML5に変換します. 特別な設定をしなくてもきれいな表示が得られるよう, HTML5の出力にはデフォルトのスタイルシートが適用されます.

AsciiDocソースとレンダリングされたHTMLのプレビュー

AsciiDocの処理

Asciidoctorは, AsciiDoc文法で書かれたテキストを読み込んでパースします. 次に内蔵コンバータにパースツリーを渡します. これによりHTML5, DocBook 5やman(マニュアルmanページ)が出力されます. 出力をカスタマイズしたりフォーマットを追加したりしたいときは, ユーザ独自のコンバータや Tilt 対応テンプレートを使用することができます.

AsciidoctorはオリジナルのAsciiDoc Pythonプロセッサ(asciidoc.py)に完全互換です. Asciidoctorのテストスイートには, AsciiDoc文法との互換性を保証するために 2350個を超えるテスト が入っています.

Asciidoctorでは, AsciiDocの従来の文法のほかに, Asciidoctorで追加されたマークアップとフォーマッティングオプションが使用できます. フォントベースのアイコン (例えば, icon:fire[]) やUIエレメント(button:[Save])がそれにあたります. またAsciidoctorは, HTML5出力時のスタイルとして Foundation に基づいたモダンでレスポンシブなテーマも提供します.

RubyのあるところAsciidoctorも動く

AsciidoctorはJRubyを用いてJVM上でも実行できます. Javaや他のJVM言語からAsciidoctor APIを直接呼び出すには, AsciidoctorJ を使ってください. AsciidoctorJを使ったAsciiDocの処理をビルドに直接組み込むビルドツール用プラグインとして, Apache Maven用, Gradle用, および Javadoc用 が存在します.

AsciidoctorはJavaScriptでも実行可能です. Rubyで書かれたソースを Opal を使ってJavaScriptにトランスパイルすることで Asciidoctor.js が作成されています. Asciidoctor.jsはどんなJavaScript環境(WebブラウザやNode.jsを含む)でも動作する, JavaScript版の完全なAsciidoctorです. Chrome, Atom, Bracketsやその他のウェブベースのツールで, AsciiDocをプレビューするための拡張機能にAsciidoctor.jsが使われています.

必要条件

AsciidoctorはLinux, macOS, およびWindowsで動作し, 下記の Ruby実装の一つを必要とします.

  • CRuby (aka MRI) 2.3 - 2.6

  • JRuby 9.1 - 9.2

  • TruffleRuby (GraalVM)

  • Opal (JavaScript)

もし非英語環境のWindowsを使っているなら, Asciidoctorを起動した時に Encoding::UndefinedConversionError に遭遇するかもしれません. これを解決するには, 以下のコマンドにより, 使っているコンソールの有効なコードページをUTF-8に変更することを推奨します:

chcp 65001

一度この変更をすると, Unicode関連の頭痛の種は消えるでしょう. もしEclipseのようなIDEを使っているなら, 同様にエンコーディングをUTF-8にするのを忘れないでください. AsciidoctorはUTF-8の環境において最も良好に動作します.

インストール

Asciidoctorは, (a) 主なLinuxディストリビューションのパッケージマネージャ, (b) macOSのHomebrew, (c) gem install コマンド(Windowsユーザに推奨), (d) Asciidoctor Dockerイメージ, あるいは(e) Bundlerを用いてインストールできます.

Linuxパッケージマネージャを用いてインストールする利点は, もしRubyやRubyGemsライブラリがまだインストールされていなかったら, それらをインストールしてくれることです.

(a) Linuxのパッケージマネージャ

パッケージマネージャによってインストールされるAsciidoctorは最新バージョンではないかもしれません. ディストリビューションの各リリースにおいてどのバージョンのAsciidoctorがパッケージされているかを確認するには, パッケージリポジトリを参照してください.

パッケージマネージャによってインストールされるバージョンよりも新しいAsciidoctorを使用したい場合は, gemのインストール方法 を参照してください.

apk (Alpine Linux)

Alpine Linuxにgemをインストールするには, ターミナルを開き, 以下を入力してください:

$ sudo apk add asciidoctor

pacman (Arch Linux)

Archベースのディストリビューションにgemをインストールするには, ターミナルを開き, 以下を入力してください:

$ sudo pacman -S asciidoctor

APT

Debian, またはUbuntuなどDebianベースのディストリビューションでは, APTを使ってAsciidoctorをインストールしてください. Asciidoctorパッケージをインストールするには, ターミナルを開き, 以下を入力してください:

$ sudo apt-get install -y asciidoctor

DNF

Fedora, CentOS, RHELなどRPMベースのLinuxディストリビューションでは, DNFパッケージマネージャを使ってAsciidoctorをインストールしてください. Asciidoctorパッケージをインストールするには, ターミナルを開き, 以下を入力してください:

$ sudo dnf install -y asciidoctor

(b) Homebrew (macOS)

macOSでは, パッケージマネージャHomebrewを使用してAsciidoctorをインストールすることができます. Homebrewをお持ちでない場合は, まず brew.sh の説明に従ってHomebrewをインストールしてください. Homebrewをインストールできたら, asciidoctor gemをインストールすることができます. ターミナルを開き, 以下を入力してください:

$ brew install asciidoctor

Homebrewにより, システムレベルのgemとは別の独立したprefixのパスに asciidoctor gemがインストールされます.

(c) Windows

WindowsでAsciidoctorを使う場合は, 簡単な方法が2つあります.

Chocolatey

すでにお使いのマシンで chocolatey を使用しているなら, 以下の方法を使用することができます:

choco install ruby

そのあとは gemのインストール方法 に従ってください.

Rubyinstaller

Rubyinstaller を使用したい場合は, お使いのWindowsのバージョンに適したRubyinstallerをダウンロードしてRubyをインストールしたあと, gemのインストール方法 に従ってください.

(d) gem install

Asciidoctorを gem install を使ってインストールするのであれば, その前に RVM を使ってhomeディレクトリ(つまりユーザ領域)にRubyをインストールしておくべきです. そうすれば, gem コマンドを使用して安全にAsciidoctor gemのインストールやアップデートができます. RVMを使用すると, システムから隔離された場所にgemがインストールされます.

ターミナルを開き, 以下のように入力してください:

$ gem install asciidoctor

もし, 先行リリースバージョン(例えばリリース候補版)をインストールしたければ以下のようにします.

$ gem install asciidoctor --pre

(e) Docker

Installing Asciidoctor using Dockerを参照してください.

(f) Bundler

  1. プロジェクトのルートフォルダ(またはカレントディレクトリ)にGemfileを作成

  2. asciidoctor gemをGemfileに以下のように追加:

    source 'https://rubygems.org'
    gem 'asciidoctor'
    # または明示的にバージョンを指定
    # gem 'asciidoctor', '2.0.10'
  3. Gemfileを保存

  4. ターミナルを開き, gemをインストール:

    $ bundle

gemをアップグレードするには, Gemfileで新バージョンを指定し, bundle を再び実行してください. bundle update を(gemを指定せずに)行うことは推奨 されません . 他のgemもアップデートされて思わぬ結果になるかもしれないためです.

アップグレード

オペレーティングシステムのパッケージマネージャでAsciidoctorをインストールしたのであれば, おそらくパッケージは自動的にアップデートされるように設定されています. その場合は, gemを手動でアップデートする必要はありません.

apk (Alpine Linux)

gemをアップグレードするには, 以下を使用してください:

$ sudo apk add -u asciidoctor

APT

gemをアップグレードするには, 以下を使用してください:

$ sudo apt-get upgrade -y asciidoctor

DNF

gemをアップグレードするには, 以下を使用してください:

$ sudo dnf update -y asciidoctor

Homebrew (macOS)

gemをアップグレードするには, 以下を使用してください:

$ brew update
$ brew upgrade asciidoctor

gem install

gem コマンドを使ってAsciidoctorをインストールした場合は, 新しいバージョンのAsciidoctorがリリースされたら手動でアップグレードする必要があります. 以下を入力することでアップグレードできます:

$ gem install asciidoctor

gem install を使って新しいバージョンのgemをインストールすると, 複数のバージョンがインストールされた状態になります. 以下のコマンドを使って古いバージョンを削除してください.

$ gem cleanup asciidoctor

使い方

Asciidoctorのインストールが成功すると, asciidoctor コマンドがPATHに存在するようになり, Asciidoctorのコマンドラインインターフェース(CLI)が使用できるようになります. 確認のために, ターミナルで以下を実行しましょう:

$ asciidoctor --version

AsciidoctorのバージョンとRuby環境についての情報がターミナルに出力されるはずです.

Asciidoctor 2.0.10 [https://asciidoctor.org]
Runtime Environment (ruby 2.6.0p0 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

AsciidoctorはAPIも提供します. APIは他のRubyソフトウェア, たとえばRails, Sinatra, GitHub, そして他の言語, たとえばJava (AsciidoctorJ 経由)やJavaScript (Asciidoctor.js 経由)と組み合わせて使用するためのものです.

コマンドラインインターフェース (CLI)

asciidoctor コマンドによりコマンドライン(つまりターミナル)からAsciidoctorを起動することができます.

次のコマンドにより, README.adocというファイルがHTMLに変換され, 結果が同じディレクトリのREADME.htmlとして保存されます. 生成されるHTMLファイルの名前は, ソースファイルのファイル名の拡張子を .html に替えたものとなります.

$ asciidoctor README.adoc

さまざまなフラグやスイッチを与えることでAsciidoctorプロセッサをコントロールすることができます. フラグやスイッチの説明は以下のコマンドで表示されます:

$ asciidoctor --help

例えば, ファイルを異なるディレクトリに書き出すには以下を使用します:

$ asciidoctor -D output README.adoc

コマンドラインインタフェースの完全なリファレンスは asciidoctormanページ にあります.

asciidoctor コマンドの使い方の詳細については以下を参照してください.

Ruby API

Asciidoctorをアプリケーションの中で使うには, まずgemをrequireする必要があります:

require 'asciidoctor'

そうすると, 以下のようにしてAsciiDocソースファイルをHTMLファイルに変換できます:

Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe
AsciidoctorをAPI経由で使っているとき, デフォルトのセーフモードは :secure (セキュアモード)です. セキュアモードでは, include ディレクティブを含むいくつかのコア機能が無効化されています. これらの機能を有効化したい場合, 明示的にセーフモードを :server (推奨)か :safe にする必要があります.

AsciiDoc文字列を, 埋め込み用HTML(HTMLページヘの挿入用)に変換することもできます:

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
Asciidoctor.convert content, safe: :safe

もし完全なHTMLドキュメントが必要であれば, 以下のように header_footer オプションを有効にしてください:

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safe

パースされたドキュメントにアクセスしたい場合は, 変換を複数のステップに分割します:

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convert

Asciidoctorの生成する出力が気に入らない場合は, あなたはそれを変更できる ことを忘れないでください! パースされたドキュメントを出力形式に変換するコンバータは, カスタマイズが可能です.

出力を部分的にカスタマイズする簡単な方法としてはテンプレートコンバータがあります. テンプレートコンバータでは, ドキュメントの各ノードの変換に Tilt対応テンプレートファイルを使うことができます.

さまざまな方法を使って出力は100%制御することが できます . APIの使い方や出力のカスタマイズ方法についてのより詳しい情報は ユーザマニュアル を参照してください.

コントリビューション

新しいコントリビューションを常に歓迎します! もしソースコード, ドキュメント, あるいはウェブサイトに間違いや不備を見つけたら遠慮なく, イシューを作成するか, 修正をおこなってpull requestを作成してください.

あなた にもできることがあります:

  • 先行バージョン(alpha, beta, またはpreview版)の使用

  • バグレポート

  • 新機能提案

  • ドキュメントの執筆または編集

  • テストをつけてコードを書くこと — どのようなパッチであれ小さすぎるなどということはありません

    • typoの修正

    • コメントの追加

    • 一貫性のないホワイトスペースの除去

    • テストの記述!

  • リファクタリング

  • イシュー の解決

  • パッチのレビュー

Asciidoctorプロジェクトにイシュー, 機能リクエスト, コード, ドキュメントを送る際の, 作成方法, スタイル, および送り方は, Contributing ガイドに記載されています.

助けを得る

Asciidoctorは, コンテンツの執筆と公開を簡単にするために開発されています. しかしあなたからのフィードバックがなくてはAsciidoctorの開発は進みません! ディスカッションリスト, Twitter, チャットルームを使って, 質問をしたりプロジェクトのさまざまな側面について話し合ったりすることをお勧めします.

チャット(Gitter)

Gitter

ディスカッションリスト(Nabble)

http://discuss.asciidoctor.org

Twitter

ハッシュタグ #asciidoctor またはメンション @asciidoctor

GitHub上のAsciidoctorのorganizationではプロジェクトのソースコード, イシュートラッカー, サブプロジェクトが管理されています.

ソースリポジトリ(git)

https://github.com/asciidoctor/asciidoctor

イシュートラッカー

https://github.com/asciidoctor/asciidoctor/issues

GitHub上のAsciidoctorのorganization

https://github.com/asciidoctor

ライセンス

Copyright © 2012-2019 Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor. 本ソフトウェアはMITライセンスのもとで使用できます.

ライセンスの詳細については LICENSE ファイルを参照してください.

作者

AsciidoctorDan AllenSarah White がリードし, Asciidoctorの素晴らしきコミュニティの 数多くのメンバ からコントリビューションを受けてきました. このプロジェクトは Nick Hengeveldプロトタイプ をベースに Ryan Waldron により2012年から創始されました.

AsciiDoc は Stuart Rackham により創始され, AsciiDocコミュニティの数多くのメンバからコントリビューションを受けてきました.

変更履歴

2.0.10 (2019-05-31) - @mojavelinux

Bug Fixes
  • fix Asciidoctor.convert_file to honor header_footer: false option when writing to file (#3316)

  • fix placement of title on excerpt block (#3289)

  • always pass same options to SyntaxHighlighter#docinfo, regardless of value of location argument

  • fix signature of SyntaxHighlighter#docinfo method (#3300)

  • when icons is set to image, enable image icons, but don’t use it as the value of the icontype attribute (#3308)

過去のリリースの完全な変更点リストについては CHANGELOG を参照してください.