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

リファレンスマニュアルを作成していると
(1) 機能一覧での各機能の概要・インタフェースの記載
(2) 個別の機能詳細の記載

の記載が必要となるのですが、この(1)(2)は一部冗長的な部分があります。

冗長部は、仕様変更等に修正を継続的に行っていると、
やがて差異や用語の不統一等が発生したります。

これを、なんとか一元管理しないなぁと思い、

AsciiDocで何とかならないこと調べると、
  「タグを使った部分抽出」
が出来ることが分かりました。

下記のように、テキスト内にコメント文にて、tag:タグ名[] ～ end:タグ名[] で囲むことで、
// tag::タグ名[]
   抽出したい文章
// end::タグ名[]

別のAsciiDoc文書中にて
   include::テキストファイル名[tag=タグ名]
と記述することで、部分抽出して挿入することが出来ます。

次の文書は、別の文書から抽出してリストを作成しています。

[options="autowidth",cols="<,<"]
|===
^|コマンド・書式	^|概要
|
include::WAIT.adoc[tag=summary_1]
|
include::WAIT.adoc[tag=summary_2]

|
include::TICK.adoc[tag=summary_1]
|
include::TICK.adoc[tag=summary_2]

|
include::CLT.adoc[tag=summary_1]
|
include::CLT.adoc[tag=summary_2]

|
include::DATE.adoc[tag=summary_1]
|
include::DATE.adoc[tag=summary_2]

|
include::GETDATE.adoc[tag=summary_1]
|
include::GETDATE.adoc[tag=summary_2]

|
include::GETTIME.adoc[tag=summary_1]
|
include::GETTIME.adoc[tag=summary_2]

|
include::SETDATE.adoc[tag=summary_1]
|
include::SETDATE.adoc[tag=summary_2]

|===

HTMLに変換すると次のような感じになります。

コマンド・書式	概要
WAIT 待ち時間(ミリ秒)	時間待ち
TICK () TICK (モード)	経過時間取得
CLT	経過時間カウントのリセット
DATE	現在時刻の表示
GETDATE 年格納変数, 月格納変数, 日格納変数, 曜日格納変数	日付の取得
GETTIME 時格納変数 , 分格納変数 , 秒格納変数	時刻の取得
SETDATE 年,月,日,時,分,秒	時刻の設定

抽出される側のWAITコマンドの文書ファイルは次のように記述しています。

:sectnums:
[[WAIT]]
= WAIT 時間待ち
:sectnums!:

// tag::summary_2[]
時間待ち
// end::summary_2[]

== 【書式】
// tag::summary_1[]
*<<WAIT,WAIT>>* 待ち時間(ミリ秒)
// end::summary_1[]

== 【引数】
待ち時間;; 0 ～ 32767 （単位 ミリ秒）

== 【説明】
引数で指定した時間(ミリ秒単位)、時間待ち(ウェイト)を行います。 +
最大で32767ミリ秒（32.8秒）の時間待ちが可能です。 +
長い時間待ちを行う必要がある場合は、*<<TICK,TICK>>* 関数や *<<GETTIME,GETTIME>>*
コマンドを使った方法を検討してください。 +
[%hardbreaks,icons=None,caption="注意"]
WARNING: 時間待ち中はキー操作によるプログラム中断を行うことは出来ません。 
短い時間の指定にてループ処理を行う等の対策を行ってください。

== 【エラーメッセージ】
Syntax error;;	文法エラー、書式と異なる利用を行った
Illegal value;;	待ち時間に範囲外の値を指定した
Overflow;;		指定した数値が-32768 ～ 32767を超えている

== 【利用例】
.画面上の指定位置に時刻を1秒間隔で更新表示する
----
10 SETDATE 2017,4,1,12,0,0
20 CLS
30 LOCATE 5,5
40 DATE
50 WAIT 1000
60 GOTO 30
----

上記の文書はそのままHTMLに変換すると次のようになります。

1. WAIT 時間待ち

時間待ち

【書式】

WAIT 待ち時間(ミリ秒)

【引数】

待ち時間

0 ～ 32767 （単位 ミリ秒）

【説明】

引数で指定した時間(ミリ秒単位)、時間待ち(ウェイト)を行います。
最大で32767ミリ秒（32.8秒）の時間待ちが可能です。
長い時間待ちを行う必要がある場合は、TICK 関数や GETTIME コマンドを使った方法を検討してください。

注意	時間待ち中はキー操作によるプログラム中断を行うことは出来ません。 短い時間の指定にてループ処理を行う等の対策を行ってください。

【エラーメッセージ】

Syntax error

文法エラー、書式と異なる利用を行った

Illegal value

待ち時間に範囲外の値を指定した

Overflow

指定した数値が-32768 ～ 32767を超えている

【利用例】

画面上の指定位置に時刻を1秒間隔で更新表示する

10 SETDATE 2017,4,1,12,0,0
20 CLS
30 LOCATE 5,5
40 DATE
50 WAIT 1000
60 GOTO 30

こんな感じで、記載するファイル（場所）を一か所にして一元管理出来るので、
タグはとても便利な機能です。

タグの記述は、AsciiDoc文書以外のテキストファイルでも利用出来ます。
C言語等のプログラムソースのコメント内に記述を想定しているようです。
うまく利用すれば、プログラムソースからドキュメント作成できると思います。