【Asciidoc】コードブロック ー ソースインクルードとインデント ー

引き続き、「コードブロック」について。。。
今回はソースインクルードについて。
前半は構文の復習、後半は利用法の考察。

で、基本コードは

using System;

class Program
{

// tag::main[]

    static void Main()
    {
        Console.WriteLine("ようこそC#の世界に！");
    }

// end::main[]

}

を利用します。ファイル名は「hello.cs」にしましょう。

単純にインクルードする場合、

:source-highlighter: rouge

[source, csharp, linenums]
----
include::hello.cs[]
----

変換すると

単純インクルード例

行を利用した範囲指定を行います。

[source, csharp, linenums]
----
include::hello.cs[lines=7..12]
----

次にタグを利用した範囲指定です。

[source, csharp, linenums]
----
include::hello.cs[tags=main]
----

変換すると、何方も同じ表示になります。

範囲指定インクルード例

ここまでは以前に
　「【Asciidoc】インクルードの応用ー部分を組み込むー」
で紹介しています。
次にインデントを調整してみます。（初めて紹介するテクニック）

[source, csharp, linenums,indent=0]
----
include::hello.cs[tags=main]
----

[source, csharp, linenums,indent=2]
----
include::hello.cs[tags=main]
----

変換すると、

インデント設定例

この方法はリスト形式のブロックであれば、組み込みインクルード処理であることを問わない。しかし、組み込みインクルード処理の場合は元のファイルを変更したくないのでインデントを再設定できるのが特に嬉しい。

---

さて、このテクニックはどこで利用できるのだろうか？
　・ 教科書や解説書
　・ コード仕様書（設計書）
前者はかなり利用できると思われる。後者は「？」である。
そもそも、実際のコードから（設計書 or 仕様書等）解説文書の作成がおかしい。
（本来、設計書や仕様書はプログラミングを行う為に書かれるのだから・・・）
が、それを要求する会社も儘有る。その時、実コードのインクルードは利用できるか？
結論から行くと利用できない。
過去、やってみたら。。。
　・ 実コード変更によって利用したい場所が変わる。
　・ コード流用する時、「Asciidoc」用コメントまで流用する。
　・ 部分インクルード用のタグを親切な人に消される。
　・ コールアウトコメントを親切な人に消される。
所感：
　・ コード変更したら関係文書もメンテナンスして。。。
　・ 流用する？二回以上コピーするなら関数化して。。。
　・ 親切な人はコメントを嫌っているのか・・・全てのコメントを消してくれる。
　　（嫌がらせですか？）

結局、ソースブロックインクルードは自分が管理しているものに対してしか利用できない。また、設計書 or 仕様書にコード内容を書かなければならない様な体制ではそれ以外の問題も（ある意味必然的に）発生するので、あまり一緒に働きたくないものである。
結論、利用するのは解説本作成等で個人が管理しているものだけになる訳だ。
この時には有効に利用できる。
　・ サンプルコードは度々利用することが有る。
　・ 書いている時に文書本文と例文を分離でき文書構造を把握しやすい。
　　等など。。。
やはり、これを利用できるのは教科書や解説書を書く時だと思う。
仕様書や設計書は「ダイヤグラム」で・・・。
いや、今日の思考はネガティブだ・・・いけない。

取り敢えず今回はここまで。

…ではまた。

当Noteは下記の「AsciiDoc Language Documentation」の文法に従っています。

AsciiDoc - AsciiDoc Language Documentation