Merge commit '1629fdec4ebf3c155ed67a83dd18f25637fdc860'

h1romas4 · Sep 25, 2023 · 70743a2 · 70743a2
2 parents ddd2881 + 1629fde
commit 70743a2
Show file tree

Hide file tree

Showing 9 changed files with 265 additions and 111 deletions.
diff --git a/.vscode/asciidoc.code-snippets b/.vscode/asciidoc.code-snippets
@@ -269,7 +269,7 @@
     "asciidoc-hr": {
         "prefix": "ag-hr",
         "body": [
-            "- - -"
+            "'''"
         ],
         "description": "horizon line"
     },

diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -49,12 +49,16 @@
         "gradlew",
         "graphviz",
         "h1romas4",
+        "highlightjs",
         "hiromasa",
+        "ifdef",
+        "ifndef",
         "imagesdir",
         "IntelliJ",
         "jebbs",
         "linewrap",
         "listopeniconic",
+        "manname",
         "Mincho",
         "mindmap",
         "Morisawa",
@@ -72,10 +76,13 @@
         "Ricty",
         "runtimes",
         "SDKMAN",
+        "sectnums",
         "Sideris",
+        "sourcedir",
         "startsalt",
         "startuml",
         "Stathis",
+        "stylesdir",
         "temurin",
         "thinkpad",
         "winget",

diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/index.pdf b/docs/index.pdf
diff --git a/src/docs/asciidoc/Chapter02/index.adoc b/src/docs/asciidoc/Chapter02/index.adoc
@@ -322,12 +322,13 @@ powershell.exe -ExecutionPolicy Bypass -File pc.ps1 ${DISTPATH}$1
 VS Code には統合ターミナルと呼ばれる VS Code 画面内で使えるターミナルエミュレータが備わっており、ここで文書変換コマンドを実行できます。
 
 .VS Code 統合ターミナルからの文書変換
-[caption=""]
+[caption="画面. "]
 image::2023-09-20-15-30-52.png[width=60%, pdfWidth=60%]
 
 統合ターミナルは menu:表示[ターミナル] と操作して開きます。
 
 .VS Code 統合ターミナルの起動
+[caption="画面. "]
 image::2023-09-20-15-26-40.png[width=60%, pdfWidth=60%]
 
 統合ターミナルを活用すると VS Code を離れることなく文書の変換ができます。
@@ -339,7 +340,7 @@ image::2023-09-20-15-26-40.png[width=60%, pdfWidth=60%]
 また、統合ターミナル内では btn:[↑] を押下することで前回入力した履歴が呼び出せます。この操作は文書変換コマンドを再実行する際に便利です。
 ====
 
-- - -
+'''
 
 .その他の Asciidoc 文書編集が可能な統合開発環境
 ****

diff --git a/src/docs/asciidoc/Chapter03/index.adoc b/src/docs/asciidoc/Chapter03/index.adoc
@@ -5,50 +5,90 @@ include::../attribute.adoc[]
 
 Asciidoc ではテキスト中に特定の記法を挿入することで文書表現や付随情報を追加しながら執筆を進めます。
 
-ここでは Asciidoc 文書で利用可能な記法の中で、この文書で使われている表現を取り上げて解説します。始めは本文書を手元に置いてコピーアンドペーストするのも良い方法です。
+本項では Asciidoc 文書で利用可能な記法の中で、この文書で使われている表現を取り上げて解説します。初めは本文書を手元に置いて、使いたい部分からコピーアンドペーストするのも良い方法です。
 
 また、Asciidoc 記法の入力の助けになるよう、プロジェクトフォルダの ``.vscode/asciidoc.code-snippets`` 設定には VS Code の btn:[Ctrl + Space] 操作で補完可能な形式で Asciidoc 記法のスニペットが格納されています。プロジェクトで定形の記法があれが追加・修正すると便利でしょう。
 
 image::2023-09-14-18-52-05.png[pdfwidth=60%, width=60%]
 
 NOTE: 補完文字列は他の補完と区別しやすいよう `ag-` が先頭に付与されています。補完操作後、最初に `ag-` と入力することで一覧できます。
 
-=== ドキュメントヘッダー
+=== ドキュメントヘッダーとセクションタイトル
 
-章やチャプターを表すヘッダーは次のように記述します。
+文書名を表すドキュメントヘッダーや、章やチャプターを表すセクションタイトルは次のように記述します。
 
 [source]
 ----
-= AsciidoctorとGradleでつくる文書執筆環境
+= AsciidoctorとGradleでつくる文書執筆環境 // <1>
 
-== はじめに
+== はじめに // <2>
+// <3>
+本文書は Asciidoc とその Ruby による実装である... // <4>
 ----
+<1> ドキュメントヘッダー
+<2> セクションタイトル
+<3> 本文との間には空行を入れる。
+<4> ここから本文。
 
 [TIP]
 ====
-本文書で提供される ``.adoc`` はドキュメントタイプが ``book`` に指定され、ヘッダーのレベル1が文書名となります。ドキュメントタイプは ``attribute.adoc`` の ``:doctype: book`` で指定されています。
+本文書で提供される ``.adoc`` はドキュメントタイプが ``book`` に指定され、``=``（レベル 0）がドキュメントヘッダー（文書名）となり、それ移行がセクションタイトルとなります。 +
+なお、ドキュメントタイプは ``attribute.adoc`` の ``:doctype: book`` で指定されています。
 ====
 
 === 段落
 
-文章の段落は改行で表現します。新しい段落にする場合は改行のみの空行を挿入します。
+文章の段落は改行でコントロールします。新しい段落にする場合は改行のみの空行を挿入します。
 
 [source]
 ----
 こんにちは。
-
-吾輩は段落である。（ここには空行はない）
+// <1>
+吾輩は段落である。（ここには空行はない） // <2>
 名前はまだない。
 ----
+<1> 空行により「こんにちは。」が段落となる。
+<2> 空行がない行は同一段落として扱われる。
 
 こんにちは。
 
 吾輩は段落である。（ここには空行はない）
 名前はまだない。
 
+=== 文章中のテキストフォーマット
+
+==== コマンドやファイル名などの等角フォント
+
+文中に現れるコマンドやファイル名などは ``コマンド`` で記述します。
+
+[source]
+----
+``コマンド``
+----
+
+==== 強調
+
+文中の**強調**は ``**`` で括ることで記述します。
+
+[source]
+----
+文中の**強調**は ``**`` で括ることで記述します。
+----
+
+==== エスケープ
+
+文章中に Asciidoc 記法で使われる文字列と同一の文字が存在し、意図せず Asciidoc として解釈されてしまう場合は、``\`` でエスケープすることができます。
+
+[source]
+----
+...参照リンクは参照先に ``\[[ラベル名]]`` を付与して...
+----
+
+...参照リンクは参照先に ``\[[ラベル名]]`` を付与して...
+
 === 文書中の相互参照
 
-文書内の参照リンクは ``.adoc`` 文書中で次のように指定します。HTML/PDF でクリックリンクが生成されます。
+``.adoc`` 文書内の参照リンクは参照先に ``\[[ラベル名]]`` を付与して設定します。HTML/PDF 上はクリックリンクが生成されます。
 
 [source]
 ----
@@ -61,9 +101,8 @@ NOTE: 補完文字列は他の補完と区別しやすいよう `ag-` が先頭
 <<project-structure,章の冒頭>> // <1>
 <<Chapter01/index.adoc#introduction,はじめに>> <2>
 ----
-
-<1> 同一 `.adoc` 内での内部参照
-<2> `.adoc` をまたいだドキュメント間参照
+<1> 同一 `.adoc` 内での内部参照用のラベル定義と参照
+<2> ファイルを跨いだ場合のラベル参照
 
 リンクの例
 
@@ -108,8 +147,6 @@ https://docs.asciidoctor.org/
 Welcome to the Asciidoctor documentation site! Here you can find the reference material, guides, and examples to write content in AsciiDoc and publish it using Asciidoctor. This documentation will help you start your journey with AsciiDoc or dive deeper if you're already well on your way.
 ____
 
-<<<
-
 === 画像
 
 画像の挿入は、画像ファイルを編集中の ``.adoc`` 文書から相対パスでみた ``images/`` フォルダに格納した上で、次のように記述します。
@@ -126,6 +163,22 @@ image::2023-06-30-12-11-56.png[pdfwidth=70%, width=600px]
 
 NOTE: これは ``src/docs/asciidoc/attribute.adoc`` で ``:imagesdir: ./images`` が設定済みであるための動作です。
 
+また、ブロックタイトルと画像を組み合わせることで画像キャプションを追加できます。
+
+[source]
+[caption=""]
+----
+.VS Code の IntelliSense // <1>
+[caption="画像. "] // <2>
+image::2023-09-14-18-52-05.png[pdfwidth=70%, width=70%]
+----
+<1> ブロックタイトルを指定
+<2> キャプションを指定
+
+.VS Code の IntelliSense
+[caption="画像. "]
+image::2023-09-14-18-52-05.png[pdfwidth=70%, width=70%]
+
 === ソースコードシンタックスハイライト
 
 ``[source]`` ブロックを用いて文書中にソースコードをシンタックスハイライト付きで埋め込みます。また、ソースコードに ``// <1>`` などのコメント形式でソースコード下部に対応する説明が記述できます。
@@ -157,17 +210,6 @@ function hello() { // <1>
 <1> 関数定義
 <2> コンソールに ``Hello, World`` を出力
 
-<<<
-
-=== インラインコマンド・ファイル名
-
-文中に現れるコマンドやファイル名などは ``コマンド`` で記述します。
-
-[source]
-----
-``コマンド``
-----
-
 === メニュー・ボタン
 
 コンピュータの操作で使われる menu:メニュー[File > Open] や btn:[OK] ボタンなどは次のように記述します。
@@ -179,6 +221,11 @@ menu:メニュー[File > Open]
 btn:[OK] ボタン
 ----
 
+[NOTE]
+====
+この表現は Asciidoc のマクロで実装されており、``attribute.adoc`` の ``:experimental:``（実験的） 指定で有効にされています。
+====
+
 === ファイルインクルード
 
 `.adoc` ファイルから別のファイルをインクルードできます。ソースコードや後述のダイアグラム形式などを別ファイルとして切り出すのに便利です。
@@ -200,8 +247,6 @@ IMPORTANT: Gradle のファイル更新監視は `.adoc` からインクルー
 include::source/hello.rs[]
 ----
 
-<<<
-
 === 表形式
 
 表形式は次のようなコードで定義します。データ形式、罫線表現に関していくつかの属性が設定できます。
@@ -237,9 +282,9 @@ include::source/hello.rs[]
 
 [source]
 [caption=""]
-.表形式の例2（デフォルト形式、ヘッダーあり、グリッドあり）
+.表形式の例2（ヘッダーあり、グリッドあり、ストライプなし）
 -----
-[cols="1,2", options="header"]
+[cols="1,2", options="header", stripes="none"]
 [frame="topbot"]
 [caption=""]
 .表形式の例2
@@ -255,7 +300,7 @@ include::source/hello.rs[]
 |======
 -----
 
-[cols="1,2", options="header"]
+[cols="1,2", options="header", stripes="none"]
 [frame="topbot"]
 |======
 |カラム名1
@@ -336,8 +381,6 @@ image::2023-06-30-15-39-26.png[pdfwidth=60%, width=60%]
 *** 順序なしリスト1
 *** 順序なしリスト2
 
-<<<
-
 === 脚注
 
 補足点を脚注するいくつかの表現があります。
@@ -384,9 +427,7 @@ CAUTION: 注意
 吾輩は脚注である。名前はまだ無い。
 ====
 
-<<<
-
-=== 改ページ・水平線
+=== 改ページ・ブレイク表現
 
 改ページは次の記述で挿入します。PDF 文書のみに効果があり HTML 文書には影響しません。
 
@@ -395,18 +436,18 @@ CAUTION: 注意
 <<<
 ----
 
-水平線は HTML/PDF 文書のどちらでも有効です。
+ブレイク表現（水平線）は HTML/PDF 文書のどちらでも有効です。
 
 [source]
 ----
-- - -
+'''
 ----
 
-- - -
+'''
 
-=== ラベル
+=== ラベル文言
 
-特定のラベルに対して定義文を記述する表現は次のように記述します。
+特定のラベル文言に対して定義文を記述する表現は次のように記述します。
 
 [source]
 ----
@@ -423,7 +464,7 @@ CAUTION: 注意
 
 === コラム表現
 
-Asciidoc のサイドバーとブロック名称機能を組み合わせ、コラム表現を挿入します。
+Asciidoc のサイドバーとブロックタイトル記法を組み合わせ、コラム表現を挿入します。
 
 [source]
 -----

diff --git a/src/docs/asciidoc/Chapter04/index.adoc b/src/docs/asciidoc/Chapter04/index.adoc
@@ -123,7 +123,7 @@ include::puml/math-sample1.puml[]
 include::puml/math-sample1.puml[]
 ----
 
-- - -
+'''
 
 .PlantUML の Salt 記法のフォントサイズ
 ****
@@ -360,7 +360,7 @@ highlight 40 to 60 #SkyBlue;line:DimGrey : 書き込み
 include::puml/diag-timing-sample1.puml[]
 ----
 
-- - -
+'''
 
 .Open Iconic アイコン
 ****

diff --git a/src/docs/asciidoc/Chapter99/index.adoc b/src/docs/asciidoc/Chapter99/index.adoc
@@ -11,16 +11,17 @@ include::../attribute.adoc[]
     ソフトウェア開発者。近年はハードウェア工作にも注目し、オープンソースハードウェアの公開なども行っている。座右の銘は「論よりラン」。
 
 // TODO: ページ下部に配置できるか検証。
-- - -
+'''
 
 Asciidoctor と Gradle でつくる執筆環境::
-    2023年 9月 14日 v4.1.0 発行
+    2023年 10月 1日 v4.1.0 発行
 
 [format="csv",cols="1,3"]
 [frame="topbot",grid="none",stripes="none"]
 |======
-著者, 田中 広将 （ひろましゃ - `h1romas4`）
+著者, 田中 広将
 カバーデザイン, Fujix
-発行, https://github.com/h1romas4/asciidoctor-gradle-template
 ライセンス, MIT License
+発行, https://github.com/h1romas4/asciidoctor-gradle-template
+連絡先, https://github.com/h1romas4/asciidoctor-gradle-template/issues
 |======
diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc
@@ -27,7 +27,7 @@ endif::[]
 // Producer: https://github.com/h1romas4/asciidoctor-gradle-template
 = AsciidoctorとGradleでつくる文書執筆環境
 https://github.com/h1romas4/asciidoctor-gradle-template
-v4.1.0, 2023-09-12
+v4.1.0, 2023-10-01
 :toc: macro
 
 // 章ごとにインクルードしていく（画像パスも上書きすること）