LinuxでAsciiDocを使用するための完全ガイド

概要:この詳細ガイドでは、AsciiDocを使用する利点について説明し、LinuxにAsciiDocをインストールして使用する方法を説明します。

長年にわたり、私は記事、レポート、または文書を書くためにさまざまなツールを使用してきました。 私はフランスの編集者バージョンSoftからのApple IIcのLuc Bartheletのエピストルから私のすべてが私のために始めたと思います。 それから私はApple Macintosh用の優れたMicrosoft Word 5を使ってGUIツールに切り替えました。そしてSparc Solaris上でStarOfficeを納得させることは(私にとっては)わかりませんでした。 これらすべてのツールは本当にワープロでした。

しかし、私はWYSIWYGの編集者には本当に納得できませんでした。 そのため、troff、HTML、RTF、TeX / LaTeX、XML、そして最後に私が今日最も使用しているツールであるAsciiDocという、多かれ少なかれ人間が読める形式のテキストフォーマットを調べました。 実際、私はこの記事を書くために今それを使っています!

私がその歴史を作ったなら、それはどういうわけかループが閉じられているからです。 エピストルはテキストコンソール時代のワープロでした。 私が覚えている限りでは、メニューがあり、あなたはテキストを選択するためにマウスを使用することができます - しかしフォーマットのほとんどはテキストに邪魔にならないタグ​​を追加することによって行われました。 AsciiDocを使用した場合と同じです。 もちろん、それが最初のソフトウェアではありませんでした。 しかし、それが私が最初に使ったのです!

なぜAsciiDoc(または他のテキストファイル形式)なのか

テキスト形式を使用して記述することには2つの利点があります。まず、コンテンツとプレゼンテーションが明確に分離されていることです。 TeXやHTMLのようないくつかのテキストフォーマットはその分離を順守するために良い規律を必要とするので、この議論は議論の余地があります。 その一方で、WYSIWYGエディタでテンプレートとスタイルシートを使用することで、ある程度の分離レベルを達成することができます。 私はそれに同意します。 しかし、私はまだプレゼンテーションの問題がGUIツールに邪魔になることを見つけました。 一方、テキスト形式を使用する場合は、フォントスタイルや未亡人の行が文章を乱すことなくコンテンツに集中できます。 しかし、それは私だけですか? しかし、スタイルの問題を解決するためだけに文章の作成をやめた回数を数えることはできません。テキストに戻ったときにインスピレーションを失ったからです。 あなたが同意しない、または異なる経験をしている場合は、以下のコメント欄を使用して私と矛盾することを躊躇しないでください!

とにかく、私の2番目の議論は個人的な解釈の影響を受けにくいでしょう。テキストフォーマットに基づく文書は相互運用性が高いです。 どのプラットフォームのテキストエディタでも編集できるだけでなく、gitやSVNなどのツールを使用して簡単にテキストのリビジョンを管理したり、sed、AWK、Perlなどの一般的なツールを使用してテキストの変更を自動化できます。 具体的な例を挙げると、AsciiDocのようなテキストベースのフォーマットを使用する場合、マスター文書から高度にパーソナライズされたメーリングを作成するためのコマンドは1つだけですが、WYSIWYGエディタを使用する同じ仕事には「フィールド」の賢い使用が必要でした。そして、いくつかのウィザード画面を見ます。

AsciiDocとは何ですか?

厳密に言えば、AsciiDocはファイルフォーマットです。 それはあなたのテキストの様々な部分の意味をプロセッサが理解するのを助ける構文的な構成を定義します。 通常はきれいにフォーマットされた出力を生成するために。

たとえその定義が抽象的に見えるかもしれないとしても、これは簡単なことです:あなたのドキュメントの中のいくつかのキーワードや文字はドキュメントのレンダリングを変える特別な意味を持っています。 これはHTMLのタグとまったく同じ概念です。 しかし、AsciiDocとの主な違いは、ソースドキュメントの特性であり、人間が容易に判読できるようになっています。

GitHubリポジトリをチェックして、いくつかの一般的なテキストファイル形式を使用して同じ出力を生成する方法を比較します。(//www.linuxjournal.com/article/1158によるコーヒーのマンページのアイデア)

  • coffee.manは由緒あるtroffプロセッサ(1964年のRUNOFFプログラムに基づく)を使用しています。 これは主に今日manページを書くのに使われています。 あなたはあなたのコマンドプロンプトでman ./coffee.manとタイプすることによってcoffee.*ファイルをダウンロードした後それを試すことができます。
  • coffee.texLaTeX構文(1985)を使用して、ほぼ同じ結果を達成しますが、PDF出力を生成します。 LaTeXは、数式や表をうまくフォーマットすることができるため、科学出版物に特に適した組版プログラムです。 pdflatex coffee.texを使ってLaTeXソースからPDFを作成できます。
  • coffee.htmlは、ページの説明にHTML形式(1991)を使用しています。 そのファイルをお気に入りのWebブラウザで直接開いて結果を見ることができます。
  • coffee.adocは、AsciiDoc構文(2002)を使用しています。 そのファイルからHTMLとPDFの両方を作成できます。
 asciidoc coffee.adoc # HTML output a2x --format pdf ./coffee.adoc # PDF output (dblatex) a2x --fop --format pdf ./coffee.adoc # PDF output (Apache FOP) 

結果を確認したら、お気に入りのテキストエディタ(nano、vim、SublimeText、gedit、Atomなど)を使用してこれら4つのファイルを開き、ソースを比較します。AsciiDocソースの方が読みやすいことに同意する可能性が高いです。そしておそらく書きます。

LinuxにAsciiDocをインストールする方法?

AsciiDocは、多くの依存関係があるため、インストールが比較的複雑です。 あなたがソースからそれをインストールしたいなら、私は複雑を意味します。 私たちのほとんどにとって、私たちのパッケージマネージャを使うことはおそらく最善の方法です:

 apt-get install asciidoc fop 

または次のコマンド

 yum install acsiidoc fop 

(fopは、PDFを生成するためにApache FOPバックエンドが必要な場合にのみ必要です。これが私が使用しているPDFバックエンドです)

インストールの詳細については、AsciiDocの公式Webサイトを参照してください。 少なくとも私の最低限のDebianシステムでは、AsciiDocをインストールするのに360MBをダウンロードする必要があるので(LaTeXの依存関係のため)、今のところ、今必要なのは少しの忍耐力だけです。 インターネットの帯域幅によっては、この記事の残りの部分を読むのに十分な時間がかかる場合があります。

AsciiDocチュートリアル:AsciiDocの書き方は?

私はそれを数回言った、AsciiDocは人間が読めるテキストファイルフォーマットです 。 それで、あなたはあなたの選んだテキストエディタを使ってあなたのドキュメントを書くことができます。 専用のテキストエディタもあります。 しかし、ここでは説明しません。単に使用しないからです。 しかし、それらのいずれかを使用している場合は、この記事の最後にあるコメント欄を使用してご意見を共有してください。

私はここでさらに別のAsciiDoc構文チュートリアルを作成するつもりはありません。それらはWeb上ですでに利用可能なものがたくさんあります。 だから私はあなたが事実上どんな文書でも使うであろう非常に基本的な構文的な構成物だけに言及するつもりである。 上で引用した簡単な「coffee」コマンドの例から、次のことがわかります。

  • AsciiDocのタイトルは、(タイトルレベルに応じて) ===または---それらを基にすることによって識別されます。
  • 太字のスパンは開始の間に書かれます、
  • アンダースコア間のイタリック体

それらはHTML以前の電子メール時代に遡るかなり一般的な慣習です。 さらに、私の前の例には示されていない、他に2つの一般的な構成要素が必要になるかもしれません。 ハイパーリンク画像の包含、それらの構文はかなり自明です。

 // HyperText links link://dashing-kazoo.flywheelsites.com[ItsFOSS Linux Blog] // Inline Images image://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo] // Block Images image:://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo] 

しかし、AsciiDoc構文はそれよりはるかに豊富です。 あなたがもっと欲しいなら、私はあなたにその素敵なAsciiDocチートシートを示すことができます://powerman.name/doc/asciidoc

最終出力をレンダリングする方法

ここであなたはすでにAsciiDocフォーマットに従ったテキストを書いていると思います。 そうでない場合は、AsciiDocドキュメントから直接コピーしたサンプルファイルをここからダウンロードできます。

 # Download the AsciiDoc User Guide source document BASE="//raw.githubusercontent.com/itsfoss/asciidoc-intro/master" wget "${BASE}"/{asciidoc.txt, customers.csv} 

AsciiDocは人間が読める形式なので、AsciiDocのソーステキストを電子メールで直接誰かに送信することができ、受信者はそれ以上の面倒な操作なしにそのメッセージを読むことができます。 しかし、もっときれいにフォーマットされた出力を提供したいと思うかもしれません。 たとえば、Web公開用のHTMLとして(この記事で行ったように)。 あるいは印刷または表示用のPDFとして。

すべての場合において、あなたはプロセッサを必要とします 。 実際には、フードの下では、いくつかのプロセッサが必要になります。 あなたのAsciiDoc文書は最終的な出力を生成する前に様々な中間フォーマットに変換されるからです。 いくつかのツールが使用されているので、1つの出力が次のツールの入力になるため、 ツールチェーンと呼ばれることもあります。

私がここでいくつかの内部作業詳細を説明したとしても、あなたはそのほとんどがあなたから隠されることを理解しなければなりません。 あなたが最初にツールをインストールしなければならない時、あるいはあなたがプロセスのいくつかのステップを微調整したい時でない限り。

実際には?

HTML出力の場合は、 asciidocツールのみが必要です。 より複雑なツールチェーンの場合は、必要なプロセッサを順番にトリガーするa2xツール(AsciiDoc配布の一部)を使用することをお勧めします。

 # All examples are based on the AsciiDoc User Guide source document # HTML output asciidoc asciidoc.txt firefox asciidoc.html # XHTML output a2x --format=xhtml asciidoc.txt # PDF output (LaTeX processor) a2x --format=pdf asciidoc.txt # PDF output (FOP processor) a2x --fop --format=pdf asciidoc.txt 

HTML出力を直接生成できるとしても、 asciidocツールの中心的な機能は、AsciiDoc文書を中間のDocBook形式に変換することです。 DocBookは、技術文書の発行に一般的に使用されている(ただしこれに限定されない)XMLベースの形式です。 DocBookはセマンティックフォーマットです。 それはあなたの文書の内容を説明しているということです。 しかしそのプレゼンテーションではありません 。 そのため、フォーマットは変換の次のステップになります。 そのために、出力フォーマットがどうであれ、DocBook中間文書はXSLTプロセッサを介して処理され、直接出力(たとえばXHTML)または別の中間形式が生成されます。

これは、DocBook文書がLaTeX中間表現またはXSL-FO(ページ記述用のXMLベースの言語)として変換されるPDF文書を生成する場合です。 最後に、専用のツールがその表現をPDFに変換します。

PDF生成のための追加のステップは、ツールチェーンがPDF出力のページ区切りを処理しなければならないという事実によって特に正当化されます。 これはHTMLのような「ストリーム」フォーマットには必要ないものです。

dblatexかfopか

2つのPDFバックエンドがあるので、通常の質問は「どれが一番いいのか?」です。

どちらのプロセッサにも長所と短所があります。 そして最終的には、その選択はあなたのニーズとあなたの好みの間の妥協点となるでしょう。 それで、あなたが使うバックエンドを選ぶ前に、両方を試してみることをお勧めします。 LaTeXのパスをたどると、dblatexがPDFの作成に使用されるバックエンドになります。 XSL-FO中間フォーマットを使用したい場合は、Apache FOPになります。 それで、これらのツールのドキュメントを見て、自分のニーズに合わせて出力をカスタマイズするのがいかに簡単かを確認することを忘れないでください。 もちろん、デフォルトの出力に満足しているのでなければ!

AsciiDocの出力をカスタマイズするには?

AsciiDocからHTMLへ

箱から出してすぐに、AsciiDocはかなり素敵なドキュメントを作成します。 しかし遅かれ早かれあなたはそれらの外観をカスタマイズするために何をするでしょう。

正確な変更はあなたが使用するバックエンドに依存します。 HTML出力の場合、ほとんどの変更は文書に関連付けられているCSSスタイルシートを変更することによって行うことができます。

たとえば、すべてのセクションの見出しを赤で表示したいとします。次のcustom.cssファイルを作成できます。

 h2 { color: red; } 

そして、少し修正したコマンドを使用して文書を処理します。

 # Set the 'stylesheet' attribute to # the absolute path to our custom CSS file asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt 

ロール属性を要素に付加することによって、より細かいレベルで変更を加えることもできます。 これは生成されたHTMLのクラス属性に変換されます。

たとえば、テキストの最初の段落にrole属性を追加するようにテスト文書を修正してみてください。

 [role="summary"] AsciiDoc is a text document format .... 

次に、 custom.cssファイルに次のルールを追加します。

 .summary { font-style: italic; } 

文書を再生成します。

 asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt 

  1. et voila:最初の段落はイタリック体で表示されます。 ちょっとした創造性、忍耐、そして2、3のCSSチュートリアルを使えば、自分の意思で文書をカスタマイズできるはずです。

AsciiDocからPDFへ

PDF出力のカスタマイズはもう少し複雑です。 原文は同一のままであるため、著者の観点からではありません。 最終的に上記と同じ役割属性を使用して、特別な処理が必要な部分を識別します。

しかし、CSSを使用してPDF出力のフォーマットを定義することはできなくなりました。 最も一般的な設定には、コマンドラインから設定できるパラメータがあります。 dblatexfopバックエンドの両方で使用できるパラメータもあれば、各バックエンドに固有のパラメータもあります。

dblatexでサポートされているパラメータの一覧については、// dblatex.sourceforge.net / doc / manual / sec-params.htmlを参照してください。

DocBook XSLパラメータのリストについては、// docbook.sourceforge.net/release/xsl/1.75.2/doc/param.htmlを参照してください。

マージン調整は非常に一般的な要件であるため、そのことも検討してください。// docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

パラメータ名が2つのバックエンド間である程度一貫している場合、それらの値をバックエンドに渡すために使用されるコマンドライン引数は、 dblatexfopの間で異なります。 明らかに、これがうまくいかない場合は、最初にあなたの構文を再確認してください。 しかし、正直に言うと、この記事を書いている間、 body.font.familyパラメータをdblatexバックエンドで機能させることはできませんでした。 私は普段fopを使っているので、多分私は何かが恋しいですか? あなたがそれについてより多くの手がかりを持っているならば、私はこの記事の終わりにコメント欄であなたの提案を読むのをさらにうれしく思います!

標準外のフォントを使用することに言及する価値があります - たとえfopを使用したとしても - 追加の作業が必要です。 しかし、それはApacheのウェブサイトにかなりよく文書化されています://xmlgraphics.apache.org/fop/trunk/fonts.html#bulk

 # XSL-FO/FOP a2x -v --format pdf \ --fop \ --xsltproc-opts='--stringparam page.margin.inner 10cm' \ --xsltproc-opts='--stringparam body.font.family Helvetica' \ --xsltproc-opts='--stringparam body.font.size 8pt' \ asciidoc.txt # dblatex # (body.font.family _should_ work, but, apparently, it isn't ?!?) a2x -v --format pdf \ --dblatex-opts='--param page.margin.inner=10cm' \ --dblatex-opts='--stringparam body.font.family Helvetica' \ asciidoc.txt 

PDF生成のためのきめ細かい設定

グローバルパラメータは、定義済みの設定を調整するだけの場合に便利です。 しかし、もしあなたがドキュメントを微調整したい(あるいはレイアウトを完全に変更したい)なら、あなたはいくらかの余分な努力を必要とするでしょう。

DocBook処理の中核にはXSLTがあります。 XSLTは、XML表記から表現されたコンピュータ言語であり、XML文書から他のものへの任意の変換を記述することを可能にします。 XMLかどうか

たとえば、DocBook XSLスタイルシートを拡張または変更して、必要な新しいスタイル用のXSL-FOコードを作成する必要があります。 また、 dblatexバックエンドを使用している場合は、対応するDocBookからLaTeX XSLTスタイルシートへの変更が必要になるかもしれません。 後者の場合、あなたはカスタムLaTeXパッケージを使う必要があるかもしれません。 しかし、 dblatexは私が使用しているバックエンドではないので、 これには焦点を当てません。 もっと知りたいのであれば、公式文書を参照することしかできません。 あなたがそれに精通しているのであれば、もう一度、コメント欄であなたのヒントやコツを共有してください!

fopだけに焦点を当てていても、手順全体を詳しく説明するためのスペースはここにはありません。 それで、私はあなたにあなたが上のHTML出力の少数のCSS行で得られたものと同様の結果を得るためにあなたが使うことができる変更をあなたに示すつもりです。 つまり、セクションタイトルを赤で、 要約段落をイタリック体で表しています。

ここで私が使うコツは、新しいXSLTスタイルシートを作成し、元のDocBookスタイルシートをインポートしながら、変更したい要素の属性セットやテンプレートを上書きすることです。

  #FF0000 italic 

次に、 --xsl-fileオプションを使用して、デフォルトの出力ではなく、カスタムXSLスタイルシートを使用して出力を生成するようにa2xに要求する必要があります。

 a2x -v --format pdf \ --fop \ --xsl-file=./custom.xsl \ asciidoc.txt 

XSLT、ここに示されているヒント、そしてお気に入りの検索エンジンに関するいくつかの質問に慣れてきたら、XSL-FOの出力のカスタマイズを始めることができるはずです。

しかし、私は嘘をつかないでしょう。文書出力の明らかに単純な変更で、DocBook XMLとXSL-FOのマニュアルを調べ、スタイルシートのソースを調べ、2、3のテストを実行して最終的に望みの結果に達する。

私の意見

テキスト形式を使用して文書を書くことには大きな利点があります。 HTMLにパブリッシュする必要がある場合、AsciiDocを使用しない理由はそれほど多くありません。 構文はきれいできちんとしており、処理は単純で、必要に応じてプレゼンテーションを変更します。たいていはCSSスキルを習得するのが簡単なことが必要です。

また、HTML出力を直接使用しなくても、HTMLは今日の多くのWYSIWYGアプリケーションとの交換フォーマットとして使用できます。 例として、これは私がここで行ったことです:私はWordPressに直接何も入力する必要なしに、このようにすべてのフォーマットを保存して、この記事のHTML出力をコピーしました。

PDFにパブリッシュする必要がある場合 - 作家にとっても利点は変わりません。 デフォルトのレイアウトを詳細に変更する必要がある場合は、事態は確実に困難になります。 企業環境では、これはおそらく、XSLTに精通したドキュメントを採用して、ブランドや技術的要件に適した一連のスタイルシートを作成するか、チームの誰かがそれらのスキルを習得することです。 しかし一度終わったら、AsciiDocでテキストを書くのは楽しいことです。 そしてそれらの文章が自動的に美しいHTMLページやPDF文書に変換されるのを見てください!

最後に、もしあなたがAsciiDocがあまりにも単純すぎるか複雑すぎると思うなら、同様の目的を持った他のファイルフォーマットを見てみることができるでしょう。 コンピューティングの初期の頃にさかのぼる概念に基づいていても、人間が読めるテキスト形式のエコシステムはかなり豊富です。 たぶんそれはたった20年前だった。 証拠として、現代の多くの静的Webサイトジェネレータはそれらに基づいています。 残念ながら、これはこの記事の範囲外です。 あなたがそれについてもっと知りたいのであれば、私たちにお知らせください!

推奨されます

Raspberry Pi 3+で 'Real Debian'を実行する
2019
Ubuntu Mateが今回LibreTrendで別のハードウェア契約を獲得
2019
オープンソースアプローチが科学に与える影響
2019