ドキュメント作成に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 待ち時間(ミリ秒) |
時間待ち |
経過時間取得 | |
経過時間カウントのリセット | |
現在時刻の表示 | |
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を超えている
【利用例】
10 SETDATE 2017,4,1,12,0,0 20 CLS 30 LOCATE 5,5 40 DATE 50 WAIT 1000 60 GOTO 30
こんな感じで、記載するファイル(場所)を一か所にして一元管理出来るので、
タグはとても便利な機能です。
タグの記述は、AsciiDoc文書以外のテキストファイルでも利用出来ます。
C言語等のプログラムソースのコメント内に記述を想定しているようです。
うまく利用すれば、プログラムソースからドキュメント作成できると思います。
« ドキュメント作成にAsciiDocを利用してみる (2) | トップページ | 豊四季Tiny BASIC for Arduino STM32 を更新しました »
「ツール・フリーソフト」カテゴリの記事
- gitでサブモジュールを作成する(2025.02.01)
- パッケージ管理システム Chocolateyの導入(2024.11.17)
- DockerをWindows 10に導入しました(2020.03.01)
- Windows 10でisoイメージファイルをDVDに書き込む(2020.02.28)
- TextsでWord文書をMarkdown形式に変換してみる(2019.11.16)
「AsciiDoc」カテゴリの記事
- TextsでWord文書をMarkdown形式に変換してみる(2019.11.16)
- ドキュメント作成にAsciiDocを利用してみる (3)(2018.09.12)
- ドキュメント作成にAsciiDocを利用してみる (2)(2018.09.10)
- ドキュメント作成にAsciiDocを利用してみる(2018.09.06)
« ドキュメント作成にAsciiDocを利用してみる (2) | トップページ | 豊四季Tiny BASIC for Arduino STM32 を更新しました »
コメント