ドキュメント作成にAsciiDocを利用してみる (2)

AsciiDocを使った、ドキュメント作成の続きです。

下記の記事を参考にして、本格的なPDF形式のマニュアルを作成してみました。
大変参考になりました。望んでいた通りのドキュメントが作成できました。
記事を書かれ、公開して頂きました方々には感謝いたします。

参考にした記事
  ・(1) asciidoctor-pdfで社内ドキュメントを書こう
  ・(2) asciidoc (asciidoctor) で索引（インデックス）を作る方法
  ・(3) Asciidoctor 文法クイックリファレンス(日本語訳)

作成したのは、「豊四季Tiny BASIC for Arduino STM32」の
コマンドリファレンスマニュアルです。

リファレンスマニュアルレベルになると、次の機能が必要となります。
  ・表紙の作成
  ・目次の自動作成
  ・章・節番号を自動で振る
  ・内部文書間の参照（キーワードをクリックするとその記事のジャンプする）の定義
  ・索引の作成（これは、なくてもよいかも）

このあたりの処理は、asciidoctor-pdf が賢く処理してくれます。

作成したマニュアルは次のような感じです。
結構、立派なものが作成できました。
今回の試行錯誤で、かなり使えると判断出来ました。

表紙 (Arrobat Reader で表示しています）

目次

本文（各コマンド毎のドキュメント）

ドキュメント内の水色の項目は、クリックするとマニュアル内の関連記事にジャンプ出来ます。

索引

Wordで文書作成するよりも、かなり楽ちんです。

作成したマニュアルの各コマンドの文書は別ファイルで作成し、
include文で集結しています。

下記のトップページと、PDFレイアウト定義ファイルをカスタマイズすることで、
分割した文書を部品的に利用して、比較的簡単に構成を変更することが出来ます。

集結用のトップページの定義

= 豊四季Tiny BASIC for Arduino STM32 V0.86 リファレンスマニュアル
たま吉さん 
v0.01(Draft) 2018/9/10
// 属性定義
:experimental:
:module:    豊四季Tiny BASIC for Arduino STM32
:Author:    たま吉さん
:Email:     tamacat2014@gmail.com
:Date:      2018/09/04
:Revision:  R01
:lang: ja
:doctype: book
:description:
:docname: 豊四季Tiny BASIC for Arduino STM32 リファレンスマニュアル
// ラベルの日本語設定
:toc-title: 目次
:preface-title: はじめに
:appendix-caption: 付録
:caution-caption: 注意
:example-caption: 例
:figure-caption: 図
:important-caption: 重要
:last-update-label: 最終更新
//:listing-caption: リスト
:manname-title: 名前
:note-caption: 注記
:preface-title: まえがき
:table-caption: 表
:tip-caption: ヒント
:toc-title: 目次
:untitled-label: 無題
:version-label: バージョン
:warning-caption: 警告
// 見出し設定
:sectnums:
:chapter-label: 
// 目次作成
:toc:
:toclevels: 3

// 定数リファレンスの組み込み
include::定数.adoc[]
<<<<

// 各コマンドのリファレンスマニュアルの組み込み
:sectnums:
== コマンドリファレンス
:sectnums!:
include::ABS.adoc[]
<<<<
include::ANA.adoc[]
<<<<
include::ASC.adoc[]
<<<<
include::ATTR.adoc[]
<<<<
include::BIN.adoc[]
<<<<
include::BITMAP.adoc[]
<<<<
include::BLOAD.adoc[]
<<<<
include::BSAVE.adoc[]
<<<<
include::BYTE.adoc[]
<<<<
include::CAT.adoc[]
<<<<
include::CHR.adoc[]
<<<<
include::CIRCLE.adoc[]
<<<<
include::CLS.adoc[]
<<<<
include::CLT.adoc[]
<<<<
include::CLV.adoc[]
<<<<
include::COLOR.adoc[]
<<<<
include::CONFIG.adoc[]
<<<<
include::console.adoc[]
<<<<
include::CSCROLL.adoc[]
<<<<
include::DATE.adoc[]
<<<<
include::DELETE.adoc[]
<<<<
include::DMP.adoc[]
<<<<
include::DWBMP.adoc[]
<<<<
include::EEPFORMAT.adoc[]
<<<<
include::EEPREAD.adoc[]
<<<<
include::EEPWRITE.adoc[]
<<<<
include::END.adoc[]
<<<<
include::ERASE.adoc[]
<<<<
include::EXPORT.adoc[]
<<<<
include::FILES.adoc[]
<<<<
include::FOR_TO_NEXT.adoc[]
<<<<
include::FREE.adoc[]
<<<<
include::GETDATE.adoc[]
<<<<
include::GETS.adoc[]
<<<<
include::GETTIME.adoc[]
<<<<
include::GINP.adoc[]
<<<<
include::GOSUB.adoc[]
<<<<
include::GOTO.adoc[]
<<<<
include::GPEEK.adoc[]
<<<<
include::GPIO.adoc[]
<<<<
include::GPRINT.adoc[]
<<<<
include::GSCROLL.adoc[]
<<<<
include::HEX.adoc[]
<<<<
include::I2CR.adoc[]
<<<<
include::I2CW.adoc[]
<<<<
include::IF.adoc[]
<<<<
include::IN.adoc[]
<<<<
include::INKEY.adoc[]
<<<<
include::INPUT.adoc[]
<<<<
include::LDBMP.adoc[]
<<<<
include::LEN.adoc[]
<<<<
include::LET.adoc[]
<<<<
include::LINE.adoc[]
<<<<
include::LIST.adoc[]
<<<<
include::LOAD.adoc[]
<<<<
include::LOCATE.adoc[]
<<<<
include::LRUN.adoc[]
<<<<
include::MAP.adoc[]
<<<<
include::MKDIR.adoc[]
<<<<
include::NEW.adoc[]
<<<<
include::NOTONE.adoc[]
<<<<
include::OUT.adoc[]
<<<<
include::PEEK.adoc[]
<<<<
include::PLAY.adoc[]
<<<<
include::POKE.adoc[]
<<<<
include::POUT.adoc[]
<<<<
include::PRINT.adoc[]
<<<<
include::PSET.adoc[]
<<<<
include::PULSEIN.adoc[]
<<<<
include::RECT.adoc[]
<<<<
include::REDRAW.adoc[]
<<<<
include::REM.adoc[]
<<<<
include::REMOVE.adoc[]
<<<<
include::RENUM.adoc[]
<<<<
include::RETURN.adoc[]
<<<<
include::RGB.adoc[]
<<<<
include::RMDIR.adoc[]
<<<<
include::RND.adoc[]
<<<<
include::RUN.adoc[]
<<<<
include::SAVE.adoc[]
<<<<
include::SAVECONFIG.adoc[]
<<<<
include::SCLOSE.adoc[]
<<<<
include::SCREEN.adoc[]
<<<<
include::SETDATE.adoc[]
<<<<
include::SHIFTIN.adoc[]
<<<<
include::SHIFTOUT.adoc[]
<<<<
include::SMODE.adoc[]
<<<<
include::SOPEN.adoc[]
<<<<
include::SPRINT.adoc[]
<<<<
include::SREAD.adoc[]
<<<<
include::SREADY.adoc[]
<<<<
include::STR.adoc[]
<<<<
include::SWRITE.adoc[]
<<<<
include::TEMPO.adoc[]
<<<<
include::TICK.adoc[]
<<<<
include::TONE.adoc[]
<<<<
include::VPEEK.adoc[]
<<<<
include::WAIT.adoc[]
<<<<
include::WIDTH.adoc[]
<<<<

[index]
== 索引

追記

HTML形式でも出力してみました。

左側の目次の幅をもう少し広げたいところです。
PDF形式の出力とは、カスタマイズ方法が異なるようです。
スタイルシートを編集して、paddingを広げればよさそうですが、
何か流儀があるかのか、調査中です。