作成したツール等のマニュアルの作成にはいつも苦労します。
WordやMarkdown記述で作成しているのですが、もう少しいい方法が無いかと
調べていると、「AsciiDocがいい感じ」と思い、最近使い始めました。
AsciiDocは、Markdownと同じような感じの軽量マークアップ言語です。
テキスト主体で作成します。
良いと思うこと
・インクルド文で、細切れの文書やデータをかき集めて、文書が作成出来る。
・コメントの利用や条件付き文書変換等が出来る。
・Markdownのような方言がない。思った通りに表示出来る。
特にやりたいことは、
ドキュメントを２層構造にして、目的別・利用者別に文書を結合・再構成です。
とりあえず、「豊四季TinyBASIC for Arduino STM32」のTONEコマンドの
ドキュメントをAsciiDocで作成してみました。
元の文書（Word 2013で作成）
エディタのチョイス
AsciiDocでの文書作成は、テキストエディタがあれば出来ますが、ビュアーも必要です。
色々調べ、今回は「Visual Studio Code」を使ってみました。
「Visual Studio Code」に拡張機能 AsciiDocを組み込んで利用します。
Visual Studio Code による AsciiDoc文書の作成(クリックで拡大表示)
左がテキストエディタ、右がビュアーです。
ビュアーはテキストの修正に応じて、リアルタイムに更新されます。
とりあえず、Wordの文書をテキスト形式で「Visual Studio Code」にコピペし再利用。
、「Visual Studio Code」のテキスト置換機能のを有効に使って、項目名等を
AsciiDocの見出しに変換します。
"▢ 項目名" ＝＞ "=== 【項目名】" に変換
完成したAsciiDocの記述は次のような感じです。
TONE.adoc
//
// 作成日 2018/09/06
//
include::include\common.adoc[]
== TONE 単音出力
=== 【書式】
[%hardbreaks]
*TONE* 周波数
*TONE* 周波数, 出力期間
=== 【引数】
周波数;; 0 ～ 32767 （Hz） 0の場合は消音
出力期間;; 0 ～ 32767 (ミリ秒) 0の場合は、継続再生
=== 【説明】
*PB9* ピンより、指定した周波数のパルス出力(デューティ比50%)を行います。 +
*PB9* ピンに圧電スピーカー（圧電サウンダ）を接続すること音を出すことが出来ます。 +
出力期間の指定がある場合は、その期間パスルを出力します(ミリ秒単位)。 +
出力期間の指定がある場合、出力完了待ちを行います。 +
出力期間の指定がない場合は、*NOTONE* コマンドで停止指示をするまでパスルを出力し続けます。 +
（ *TONE* 0は *NOTONE* と等価です） +
.音階・周波数対応表
[format="csv",options="autowidth",cols="^,^,^,^,^,^,^,^,^,^,^,^,^"]
|===
include::csv/tone.csv[]
|===
=== 【エラーメッセージ】
Syntax error;; 文法エラー、書式と異なる利用を行った
Overflow;; 指定した数値が-32768 ～ 32767を超えている
=== 【利用例】
.スペースキーを押したら音を鳴らす
----
10 IF INKEY() = 32 TONE 800,50
20 GOTO 10
----
やはり、include文が利用出来ると便利です。
「音階・周波数対応表」の部分は、CSV形式の別ファイルを読み込んでいます。
読み込んでいる csv/tone.csv ファイル
,ド,ド♯,レ,レ♯,ミ,ファ,ファ♯,ソ,ソ♯,ラ,ラ♯,シ
1,33,35,37,39,41,44,46,49,52,55,58,62
2,65,69,73,78,82,87,93,98,104,110,117,123
3,131,139,147,156,165,175,185,196,208,220,233,247
4,262,277,294,311,330,349,370,392,415,440,466,494
5,523,554,587,622,659,698,740,784,831,880,932,988
6,1047,1109,1175,1245,1319,1397,1480,1568,1661,1760,1865,1976
7,2093,2217,2349,2489,2637,2794,2960,3136,3322,3520,3729,3951
8,4186,4435,4699,4978,5274,5588,5920,6272,6643,7040,7459,7902
これで表の作成が非常に楽出来ます。
作成した文書の公開
GitHUBがAsciiDocに対応しており、若干制限がありますが簡単に公開出来ます。
gitsに上記のテキストファイルをアップロードして、表示してみると、
ちゃんと表示出来ました..
と言いたいと所ですが、残念ながらinclude文が使えないようです。
(使えないと判断した根拠のソース : Asciidoctor: support include directives for other asciidoc files #1095)
仕方が無く、音階・周波数の部分は、CSVデータを直接記述する形式に修正しました。
修正部分（csvデータを直接埋め込み）
.音階・周波数対応表
[format="csv",options="autowidth",cols="^,^,^,^,^,^,^,^,^,^,^,^,^"]
|===
//include::csv/tone.csv[]
,ド,ド♯,レ,レ♯,ミ,ファ,ファ♯,ソ,ソ♯,ラ,ラ♯,シ
1,33,35,37,39,41,44,46,49,52,55,58,62
2,65,69,73,78,82,87,93,98,104,110,117,123
3,131,139,147,156,165,175,185,196,208,220,233,247
4,262,277,294,311,330,349,370,392,415,440,466,494
5,523,554,587,622,659,698,740,784,831,880,932,988
6,1047,1109,1175,1245,1319,1397,1480,1568,1661,1760,1865,1976
7,2093,2217,2349,2489,2637,2794,2960,3136,3322,3520,3729,3951
8,4186,4435,4699,4978,5274,5588,5920,6272,6643,7040,7459,7902
|===
作成した文書のリンク
https://gist.github.com/Tamakichi/cbc69f27ffb2d2b0b944f3529a2797f2
gists上の文書は、ブログの記事内に埋め込むことが出来ます。
上記のリンクの文書を埋め込んでみます。
赤い枠のコードをブログの記事に埋め込みます。
こんな感じ（ちょっと大きすぎかな？）
AsciiDocは、まだまだ使い始めたばかりですが、
とりあえずマニュアル一冊作成してみて、その過程で色々と試してみたいと思います。
AsciiDocの文書作成で参考にした記事・サイト
・脱Word、脱Markdown、asciidocでドキュメント作成する際のアレコレ
・Asciidoctor 文法クイックリファレンス(日本語訳)
・AsciiDoc User Guide
公式サイト
・Asciidoctor
・Asciidoctor User Manual
最近のコメント