@h1romas4@h1romas4

AsciidoctorとGradleでつくる文書執筆環境 [応援版]

  • Digital
    500 JPY

About Gift

AsciidoctorとGradleでつくる文書執筆環境 [応援版]
AsciidoctorとGradleでつくる文書執筆環境 [応援版]

AsciidoctorとGradleでつくる文書執筆環境 [応援版] 技術書や仕様書を執筆する際に使える Asciidoc 執筆環境構築ガイドです。環境構築手順や執筆時のノウハウを 1冊の本にまとめました。

最新版ファイル名

2023-10-02: asciidoctor-gradle-book-v4.1.0.pdf - Git による文書管理を追加しました。 - クラウド執筆環境 GitHub Codespace をサポートしました。 - VS Code の操作解説を詳細化しました。 - その他の校正を反映しました。

オープンソースドキュメント

本書「AsciidoctorとGradleでつくる文書執筆環境」は、同じ内容のものをオープンソースドキュメントとして GitHub から無償でダウンロードすることができます。 PDF版: https://h1romas4.github.io/asciidoctor-gradle-template/index.pdf HTML版: https://h1romas4.github.io/asciidoctor-gradle-template/index.html BOOTH [応援版] は、本書を気に入ってくださり、プロジェクトのご支援くださる方のために頒布されています。売上は今後の製作で使わせていただきます。 GitHub リポジトリ: https://github.com/h1romas4/asciidoctor-gradle-template ご購入された方には、本書の版が大きく上がった際に BOOTH 経由でお知らせすることができます。

目次

はじめに 　Asciidoc と Asciidoctor について 　ライセンス 　謝辞 1. Asciidoc 文書変換用スクリプトを使う準備 　1.1. Java 実行環境の導入（macOS / Linux） 　1.2. Java 実行環境の導入（Windows） 2. Asciidoc から HTML/PDF 文書を作成する 　2.1. サンプル文書の変換を試す 　2.2. 変換後の文書 　2.3. テキストエディタで Asciidoc 文書を編集する 　2.4. 文書のファイル構成 　2.5. 執筆の開始 　2.6. 執筆のイテレーション 　2.7. 文書の Git 管理 　2.8. クラウド環境による執筆 　2.9. クラウド環境でのファイル保存と執筆の再開 　2.10. GitHub Actions によるビルド 3. Asciidoc 記法 　3.1. ドキュメントヘッダーとセクションタイトル 　3.2. 段落 　3.3. 文章中のテキストフォーマット 　3.4. 文書中の相互参照 　3.5. 外部リンク 　3.6. 引用 　3.7. 画像 　3.8. ソースコードシンタックスハイライト 　3.9. メニュー・ボタン 　3.10. ファイルインクルード 　3.11. 表形式 　3.12. リスト 　3.13. 脚注 　3.14. 改ページ・ブレイク表現 　3.15. ラベル文言 　3.16. コラム表現 　3.17. コメント行 4. ダイアグラム記法 　4.1. シーケンス図 　4.2. フォルダ・ファイルツリー 　4.3. 数式 　4.4. ブロック図 　4.5. メモリーマップ 　4.6. ネットワーク構成図 　4.7. システム構成図 　4.8. タイミングチャート 　4.9. マインドマップ 奥付

はじめに（抜粋）

本文書は Asciidoc とその Ruby による実装である Asciidoctor を用いて Asciidoc 文書を執筆する環境を構築するガイドです。実行環境は macOS、Linux、Windows の各 OS に対応しています。 この文書の手順から次のことができるようになります。 - Asciidoc 形式で執筆した文書を HTML/PDF 形式に変換 - テキストエディターで変換結果をリアルタイムにプレビューしながら文書を編集 Asciidoc は表現力の高い文書をテキストファイルベースで執筆できる軽量なマークアップ言語です。他の軽量テキストマークアップが持たない文書間のインクルードやソースコードの挿入などの機能も有し、かつ簡潔です。特に技術文書の執筆には大きな力を発揮することでしょう。 一般的にテキストプロセッサーを用いた執筆とパブリッシング環境を整えるには多くの準備が必要ですが、本文書の手順は極力初期導入するプロダクトを少なく、簡単に快適な執筆環境を整えられるよう考えられました。 具体的には文書の変換に、実行を JVM 環境だけに依存する AsciidoctorJ と Gradle を活用し、執筆環境については Visual Studio Code を用いることでリアルタイムに文書をプレビューしながら、最後にコマンド一つで HTML/PDF 化できるように準備しました。またさらに、クラウド統合環境である Gitpod や GitHub の Codespaces もサポートし、ウェブブラウザだけでの執筆・変換も実現しています。 手間がかかることが多い PDF 出力に関しても、フォントセットや禁則処理設定をプロジェクトに持たせることにより、実行環境に関わらず同一出力が得られるように調整しました。 Asciidoc による文書の執筆は形式的で効率が良く、また更新差分が取りやすいため、文書履歴管理や共同執筆環境としても有効です。このメリットをさらに活用するため、本文書ではバージョン管理システムの Git やテキストダイアグラム記法による図形や数式のベクター画像挿入をフォローしています。 本文書がみなさんの執筆活動のお手伝いになれば幸いです。

@h1romas4