フォト
2018年10月
  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 31      
無料ブログはココログ

AsciiDoc

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

2018年9月10日 (月)

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

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

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

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

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

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

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

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


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

02

目次

03

本文(各コマンド毎のドキュメント)

01

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

索引

04

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形式でも出力してみました。

05

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

2018年9月 6日 (木)

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

作成したツール等のマニュアルの作成にはいつも苦労します。
WordMarkdown記述で作成を作成しているのですが、もう少しいい方法が無いかと
調べていると、「AsciiDocがいい感じ」と思い、最近使い始めました。

AsciiDocは、Markdownと同じような感じの軽量マークアップ言語です。
テキスト主体で作成します。

良いと思うこと
・インクルド文で、細切れの文書やデータをかき集めて、文書が作成出来る。
・コメントの利用や条件付き文書変換等が出来る。
Markdownのような方言がない。思った通りに表示出来る。

特にやりたいことは、
ドキュメントを2層構造にして、目的別・利用者別に文書を結合・再構成です。

とりあえず、「豊四季TinyBASIC for Arduino STM32」のTONEコマンドの
ドキュメントをAsciiDocで作成してみました。

元の文書(Word 2013で作成)

Word


エディタのチョイス

AsciiDocでの文書作成は、テキストエディタがあれば出来ますが、ビュアーも必要です。
色々調べ、今回は「Visual Studio Code」を使ってみました。
Visual Studio Code」に拡張機能 AsciiDocを組み込んで利用します。

Visual Studio Code による AsciiDoc文書の作成(クリックで拡大表示)
Vsc

左がテキストエディタ、右がビュアーです。
ビュアーはテキストの修正に応じて、リアルタイムに更新されます。

とりあえず、Wordの文書をテキスト形式で「Visual Studio Code」にコピペし再利用。
、「Visual Studio Code」のテキスト置換機能のを有効に使って、項目名等を
AsciiDocの見出しに変換します。

"▢ 項目名" => "=== 【項目名】" に変換

Vsc_2

完成した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

これで表の作成が非常に楽出来ます。


作成した文書の公開


GitHUBAsciiDocに対応しており、若干制限がありますが簡単に公開出来ます。
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
上の文書は、ブログの記事内に埋め込むことが出来ます。
上記のリンクの文書を埋め込んでみます。

Gists

赤い枠のコードをブログの記事に埋め込みます。

こんな感じ(ちょっと大きすぎかな?)

AsciiDocは、まだまだ使い始めたばかりですが、
とりあえずマニュアル一冊作成してみて、その過程で色々と試してみたいと思います。

AsciiDocの文書作成で参考にした記事・サイト
脱Word、脱Markdown、asciidocでドキュメント作成する際のアレコレ
Asciidoctor 文法クイックリファレンス(日本語訳)
AsciiDoc User Guide

公式サイト
Asciidoctor
Asciidoctor User Manual