AsciidoctorとGradleでつくる文書執筆環境

投稿日時: 投稿者:

技術文書を書く環境が欲しくなり、VS Code と Gradle を使って Asciidoc 文書を執筆する環境を整えてみました。 お手軽に構成できて、300ページくらいの文書でも耐えられそうです。 🙂

VS Code でリアルタイムプレビューしながら Asciidoc 文書を執筆し、最後に HTML/PDF 文書にすることができように仕込んだ Gradle ビルド、フォントや CJK パッチ、.vscode 設定などをパッケージして github で公開しています。

https://h1romas4.github.io/asciidoctor-gradle-template/index.html

本文書は Asciidoc とその Ruby による実装である Asciidoctor を用いて Asciidoc 文書を執筆する環境を構築する手順を示します。実行環境は Windows、Linux、macOS の各 OS に対応しています。

上記のサイト（Asciidoc 文書のサンプルになっています）で詳しく手順を書いていますが、基本的にリポジトリを取得し、文書を書いて、 ./gradlew docs するだけでいい感じに Asciidoc を HTML/PDF 文書に変換して公開できるようになっています。

PDF 文書は次のようなものが出力されます。

AsciidoctorとGradleでつくる文書執筆環境（PDF版）

https://h1romas4.github.io/asciidoctor-gradle-template/index.pdf

PDF に関しては本文フォントを明朝体にできるとより技術書らしくなると思うのですが、残念ながら prawnpdf ライブラリが OpenType に対応していないため導入を断念しました。（リポジトリの方では .ttf の 源様明朝 を導入しました）

しかし、対応は進んでいるようなので期待します。

https://github.com/prawnpdf/ttfunk/issues/53

Hey there maintainers! I’ve been working for the last several months on supporting OpenType fonts, which really just means supporting the CFF font table.

さて、今回このプロジェクトを作成するにあたり初めて Asciidoc の書式を全て確認しましたが、表現力が高く、思ったことは思った通り書けばよい感じなのでお気に入りました。 😀

(2020/4/17 更新) Qiita に最新の Gradle 定義で記事を書きました。

AsciidoctorとGradleでつくる文書執筆環境 v2

asciidoctor-gradle-pluginを活用して Asciidoc 形式の文書を Gradle を使って簡単に HTML/PDF 文書に変換できるビルドテンプレートをつくってみました。

リポジトリを github に置けば Github Pages ですぐ綺麗な文書を公開できるようになりますので、良ければお試しください！

関連

Asciidoc と PlantUML で文書をつくる
ファイルツリー表記をテキストで記述する

「AsciidoctorとGradleでつくる文書執筆環境」への16件のフィードバック

  1. 知人からこちらを教えていただき試しています。
    私は日頃の設計書に関する悩みを解消する方法を模索しているしがないSEです。
    設計書にはいくばくかの図を埋め込む可能性がありますが、UML は PlantUML があるので、このテンプレートに asciidoctorj-diagram を組み込んで試したいと思ったのですが、いかんセンチ知識不足でして、自分ではおいそれと追加することが、未だできません。。。
    どのようにすれば良いかご教示いただけるとありがたいです。

  3. 素晴らしい環境をありがとうございます。
    お伺いしたい、ご相談したい事項があります。
    asciidoctor-pdfに関して、表組の中で文字を書くと、日本語の禁則処理がかからないようです。
    以下の作者の方に、以下のプログラムでは修正いただいたのですが、
    https://github.com/fuka/asciidoctor-pdf-linewrap-ja/issues/1#event-1847471497
    それをこの環境に組み込むことは可能でしょうか？
    当方、あまり詳しくなくよくわかりません。ご教示いただけると助かります。
    よろしくお願いします。

  4. コメントありがとうございます。

    表組の禁則処理について気が付きませんでした。お教えいただいた asciidoctor-pdf-linewrap-ja に禁則処理パッチを変更して取り込むことができると思います。

    修正してコミットしたいと思いますので数日お待ちいただければと思います。

  5. 早速にありがとうございます。
    迅速に対応検討いただいてありがとうございます。お時間のある時でかまいませんので、よろしくお願いいたします。

  6. すみません、もう一点気がついたことです。
    PDFの表紙のバージョンの表記が、
    バージョン unspecified,
    となってしまいます。
    これはサンプルで提供していただいている、
    https://h1romas4.github.io/asciidoctor-gradle-template/index.pdf
    においても同様です。
    これはなにか対策をするとなおるものでしょうか？
    自分でもいろいろと記述を試してみましたがだめでした。
    度々ですみませんが、ご教示あるいは何か修正策があれば、修正をご検討いただけると助かります。
    よろしくお願いいたします。

  7. 宮沢さん

    asciidoctor-pdf-linewrap-ja の取り込みをやってみたのですが、使用している asciidoc か Ruby のバージョンの関係かエラーがでて単純な入れ替えだとうまく動作させることができませんでした。

    実は、利用している asciidocj の gradle プラグインが先日アップデートして 1系から 2系になっていましてこちらなら動くかもなのですが、かなり API が変更されているためちょっと修正に時間がかかりそうです。

    自分も本件気になっていまして、再び取り組んでみますのでまた少々お待ち頂ければと思います！（unspecified の件も合わせて修正されるのではないかと思っています）

  8. 大変時間が経ってしまいましたが以下の点を対応してみました。

    – Gradle Asciidoctor plugin を 3.1 系の最新に変更。
    – バージョン unspecified 修正
    – Gradle を 6 系の最新に変更。
    – asciidoctor-pdf-linewrap-ja を 0.6 に（表中の禁則処理対応）
    – svg のフォントパッチを動作するように修正。

    https://github.com/h1romas4/asciidoctor-gradle-template

    以上、ご連絡のみでした!

  9. こちらの環境を利用してドキュメントの作成を試行錯誤しています。

    質問なのですが、表を作成してセルを縦結合をして次ページまでまたがって結合した際に、表の崩れが発生します。

    何か解消する方法があったりしますでしょうか？

  10. ネコさん

    情報ありがとうございます。こちらでも連結セル中にページブレイクすると崩れる不具合が確認できました。

    どうやら asciidoctor-pdf がテーブルレンダリングする時に使う prawn-table ライブラリーから表の途中が取得できないためうまく処理できないようで、かなり前から issue が上がっているのですが解決に至っていないようです。

    https://github.com/asciidoctor/asciidoctor-pdf/issues/403

    次のバージョンの asciidoctpr-pdf から、このようなパターンでアラートを出力することが検討されているようです。

    https://github.com/asciidoctor/asciidoctor-pdf/issues/1626

    表中で `<<<<` などでページブレイクできると良いのですが、残念ながらできなく、今のところページを見ながら表を分けるしかなさそうですね。この場合、HTML 版でも表が分れてしまうのが悩みどころです。。

  11. 回答ありがとうございます。
    issue にあがっていた問題なんですね。。

    とりあえずPDFのバージョンを「1.5.0-alpha.16」に変えて、
    ビルドできるようにしていったらセル結合がうまくはいきましたが、
    表中のページブレイクも検討していきます。

  12. ネコさん

    > とりあえずPDFのバージョンを「1.5.0-alpha.16」に変えて、
    > ビルドできるようにしていったらセル結合がうまくはいきましたが、
    > 表中のページブレイクも検討していきます。

    asciidoctor-pdf は最新を使ったほうがいろいろ不具合が解消されていそうですね。情報ありがとうございました。こちらもウォッチしていきたいと思います。

  13. ひろまささん

    こちらの環境を使って、執筆を進めております。
    非常に助かっているのですが、数式をどうやって記述すれば良いのかで悪戦苦闘しております。何か方法はございますでしょうか。

  14. こんにちは。コメントありがとうございます！

    数式なのですが、PlantUML を有効にしていますので以下の書式でかくことができると思います。


    [plantuml, math-sample1, svg]
    ----
    @startmath
    f(t)=(a_0)/2 + sum_(n=1)^ooa_ncos((npit)/L)+sum_(n=1)^oo b_n\ sin((npit)/L)
    @endmath
    ----

    内部的に Java 内蔵の将来リリースから削除される JavaScript ランタイムを呼び出している関係で少しビルドでワーニングがでるかもしれません。

    書式などはこちらに記載がありました。数学の知識がないので、書ける範囲などご確認いただけたらと思います。
    https://plantuml.com/ja/ascii-math

    そのほかにも asciidoctor-mathematical というのがあるようですが、ちょっとこのビルドに組み込むのは難しそうでした。

  15. ひろまささん

    非常に早く回答いただけ、とても助かりました。
    無事にpdfに数式が出力されるようになりました。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です