フォト
2018年9月
            1
2 3 4 5 6 7 8
9 10 11 12 13 14 15
16 17 18 19 20 21 22
23 24 25 26 27 28 29
30            
無料ブログはココログ

« ドキュメント作成にAsciiDocを利用してみる (2) | トップページ | 豊四季Tiny BASIC for Arduino STM32 を更新しました »

2018年9月12日 (水)

ドキュメント作成に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言語等のプログラムソースのコメント内に記述を想定しているようです。
うまく利用すれば、プログラムソースからドキュメント作成できると思います。

« ドキュメント作成にAsciiDocを利用してみる (2) | トップページ | 豊四季Tiny BASIC for Arduino STM32 を更新しました »

AsciiDoc」カテゴリの記事

ツール」カテゴリの記事

コメント

コメントを書く

(ウェブ上には掲載しません)

トラックバック

この記事のトラックバックURL:
http://app.cocolog-nifty.com/t/trackback/571408/67159819

この記事へのトラックバック一覧です: ドキュメント作成にAsciiDocを利用してみる (3):

« ドキュメント作成にAsciiDocを利用してみる (2) | トップページ | 豊四季Tiny BASIC for Arduino STM32 を更新しました »