GNU/Linux >> Linux の 問題 >  >> Linux

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

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

何年にもわたって、私はさまざまなツールを使用して記事、レポート、またはドキュメントを作成しました。フランスの編集者バージョンソフトのAppleIIcでのLucBartheletの書簡からすべてが始まったと思います。次に、AppleMacintosh用の優れたMicrosoftWord 5を備えたGUIツールに切り替えました。次に、Linuxに確実に切り替えたときにOpenOfficeとして知られていたSparc Solaris上の（私にとって）説得力のないStarOfficeに切り替えました。これらのツールはすべて本当に ワードプロセッサ。

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

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

なぜAsciiDoc（またはその他のテキストファイル形式）なのか？

テキスト形式を使用して書くことには2つの利点があります。1つは、コンテンツとプレゼンテーションが明確に分離されていることです。 TeXやHTMLなどの一部のテキスト形式では、その分離を順守するために適切な規律が必要であるため、この議論は議論の余地があります。一方、WYSIWYGエディターでテンプレートとスタイルシートを使用することで、ある程度の分離を実現できます。私はそれに同意します。それでも、GUIツールではプレゼンテーションの問題が煩わしいと感じています。一方、テキスト形式を使用する場合は、フォントスタイルや未亡人の線が文章の邪魔になることなく、コンテンツにのみ焦点を当てることができます。でも多分それは私だけですかただし、スタイリングのマイナーな問題を修正するためだけに執筆を停止した回数は数えられません。テキストに戻ったときにインスピレーションを失ってしまいました。同意できない場合や別の経験がある場合は、下のコメントセクションを使用して私と矛盾することを躊躇しないでください！

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

AsciiDocとは何ですか？

厳密に言えば、AsciiDocはファイル形式です。これは、プロセッサがテキストのさまざまな部分のセマンティクスを理解するのに役立つ構文構造を定義します。通常、適切にフォーマットされた出力を生成するためです。

その定義が抽象的なように見える場合でも、これは単純なことです。ドキュメント内の一部のキーワードまたは文字には、ドキュメントのレンダリングを変更する特別な意味があります。これは、HTMLのタグとまったく同じ概念です。ただし、AsciiDocとの主な違いは、ソースドキュメントのプロパティが簡単に維持されることです。 人間が読める形式。

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

  • coffee.man 由緒あるtroffを使用 プロセッサ（1964年のRUNOFFプログラムに基づく）。今日では主にmanページを作成するために使用されます。 coffee.*をダウンロードしてからお試しいただけます。 man ./coffee.manと入力してファイルを作成します コマンドプロンプトで。
  • coffee.tex LaTeXを使用します 構文（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上にはすでにたくさんのチュートリアルがあります。したがって、事実上すべてのドキュメントで使用する非常に基本的な構文構造についてのみ説明します。上で引用した単純な「コーヒー」コマンドの例から、次のように表示されます。

  • タイトル AsciiDocでは、===で基になることで識別されます または--- （タイトルレベルによって異なります）、
  • 太字 文字スパンは開始の間に書き込まれます
  • およびイタリック アンダースコアの間。

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

// HyperText links
link:http://dashing-kazoo.flywheelsites.com[ItsFOSS Linux Blog]

// Inline Images
image:https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

// Block Images
image::https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

しかし、AsciiDoc構文はそれよりもはるかに豊富です。さらに必要な場合は、その素敵なAsciiDocチートシートを紹介できます：http：//powerman.name/doc/asciidoc

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

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

# Download the AsciiDoc User Guide source document
BASE='https://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？

PDFバックエンドは2つあるため、通常の質問は「どちらが最適ですか？」です。 答えられないことがあります。

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

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="summary"]
AsciiDoc is a text document format ....

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

.summary {
    font-style: italic;
}

ドキュメントを再生成します：

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

  1. et voila：最初の段落が斜体で表示されるようになりました。少しの創造性、ある程度の忍耐力、そしていくつかのCSSチュートリアルがあれば、ドキュメントを自由にカスタマイズできるはずです。

AsciiDocからPDFへ

PDF出力のカスタマイズはやや複雑です。ソーステキストは同一のままであるため、作成者の観点からではありません。最終的には、上記と同じ役割属性を使用して、特別な処理が必要なパーツを特定します。

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

dblatexでサポートされているパラメーターのリストについては、http：//dblatex.sourceforge.net/doc/manual/sec-params.html

を参照してください。

DocBook XSLパラメーターのリストについては、http：//docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html

を参照してください。

マージン調整はかなり一般的な要件であるため、それも確認することをお勧めします：http://docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

パラメータ名が2つのバックエンド間である程度一貫している場合、それらの値をバックエンドに渡すために使用されるコマンドライン引数は dblatex間で異なります。 およびfop 。したがって、明らかにこれが機能していない場合は、最初に構文を再確認してください。しかし、正直なところ、この記事を書いている間、私はbody.font.familyを作成することができませんでした パラメータはdblatexで機能します バックエンド。私は通常fopを使用するので 、多分私は何かを逃しましたか？それについてもっと手がかりがあれば、この記事の最後にあるコメントセクションであなたの提案を読んで喜んでいます！

fop を使用している場合でも、非標準フォントの使用について言及する価値があります。 –追加の作業が必要です。ただし、ApacheのWebサイト（https://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-to-LaTeXXSLTスタイルシートの変更が必要になる場合があります。後者の場合、カスタムLaTeXパッケージを使用する必要がある場合もあります。ただし、 dblatex 以降は、これに焦点を当てません。 私が自分で使用するバックエンドではありません。詳細を知りたい場合にのみ、公式ドキュメントを参照できます。ただし、これに精通している場合は、コメントセクションでヒントやコツを共有してください。

fopだけに焦点を当てている場合でも 、手順全体を詳しく説明する余地はありません。したがって、上記のHTML出力でいくつかのCSS行を使用して取得したものと同様の結果を取得するために使用できる変更を示します。つまり、セクションのタイトルは赤で、概要 イタリック体の段落。

ここで使用するトリックは、新しいXSLTスタイルシートを作成し、元のDocBookスタイルシートをインポートしますが、変更する要素の属性セットまたはテンプレートをオーバーライドすることです。

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:exsl="http://exslt.org/common" exclude-result-prefixes="exsl"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<!-- Import the default DocBook stylesheet for XSL-FO -->
<xsl:import href="/etc/asciidoc/docbook-xsl/fo.xsl" />

<!--
    DocBook XSL defines many attribute sets you can
    use to control the output elements
-->
<xsl:attribute-set name="section.title.level1.properties">
    <xsl:attribute name="color">#FF0000</xsl:attribute>
</xsl:attribute-set>

<!--
    For fine-grained changes, you will need to write
    or override XSLT templates just like I did it below
    for 'summary' simpara (paragraphs)
-->
<xsl:template match="simpara[@role='summary']">
  <!-- Capture inherited result -->
  <xsl:variable name="baseresult">
    <xsl:apply-imports/>
  </xsl:variable>

  <!-- Customize the result -->
  <xsl:for-each select="exsl:node-set($baseresult)/node()">
    <xsl:copy>
      <xsl:copy-of select="@*"/>
      <xsl:attribute name="font-style">italic</xsl:attribute>
      <xsl:copy-of select="node()"/>
    </xsl:copy>
  </xsl:for-each>
</xsl:template>


</xsl:stylesheet>

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

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

XSLT、ここで提供されるヒント、およびお気に入りの検索エンジンに関するいくつかのクエリに少し慣れれば、XSL-FO出力のカスタマイズを開始できるはずです。

しかし、私は嘘をつきません。ドキュメント出力の明らかに単純な変更では、DocBook XMLおよびXSL-FOのマニュアルを検索し、スタイルシートのソースを調べ、いくつかのテストを実行してから、最終的に目的の結果を得る必要がある場合があります。 。

私の意見

テキスト形式を使用してドキュメントを作成することには、大きな利点があります。また、HTMLに公開する必要がある場合、しない理由はあまりありません。 AsciiDocを使用します。構文はすっきりとしていて、処理は簡単で、必要に応じてプレゼンテーションを変更できます。ほとんどの場合、CSSスキルを簡単に習得する必要があります。

また、HTML出力を直接使用しない場合でも、HTMLは、今日の多くのWYSIWYGアプリケーションとの交換形式として使用できます。例として、これは私がここで行ったことです。この記事のHTML出力をWordPressエディション領域にコピーしたため、WordPressに直接何も入力しなくても、すべてのフォーマットが保存されます。

PDFに公開する必要がある場合、ライターにとっての利点は変わりません。ただし、デフォルトのレイアウトを大幅に変更する必要がある場合は、状況は確かに厳しくなります。企業環境では、おそらくXSLTで熟練したドキュメントを採用して、ブランディングや技術要件に適したスタイルシートのセットを作成するか、チームの誰かがそれらのスキルを習得することを意味します。しかし、一度実行すると、AsciiDocを使用してテキストを作成できるようになります。そして、それらの文章が自動的に美しいHTMLページまたはPDFドキュメントに変換されるのを見てください！

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



Linux

  1. cronを使用してタスクをスケジュールするためのLinuxのヒント

  2. 初心者向けのLinuxターミナルガイド

  3. Linuxパッケージ管理のためのAppImageの使用

  1. Linux用の3つの軽量テキストエディタ

  2. Linux 用 SQLCMD での変数の使用

  3. Sublime Text から Windows Subsystem for Linux (WSL) を使用する

  1. Linuxでtopコマンドを使用するためのヒント

  2. Ubuntuおよびその他のLinuxディストリビューションでスナップパッケージを使用するための完全ガイド

  3. Linuxコマンド-完全ガイド