macOS 及び Linux の場合で、後述する PlantUML 以外のダイアグラム記法を使う場合は Graphviz の導入が必要です。この文書のサンプルソースでも使っている部分が一部ありますので、ワーニングなしに本文書の完全なファイルを生成したい場合は次のようにインストールしてください。Windows の場合、この操作は不要です。
+macOS 及び Linux で、後述するダイアグラム記法の全てを変換するには Graphviz 画像ライブラリの導入が必要です。この文書のサンプルソースでも依存している部分が一部ありますので、ワーニングなしに本文書の完全なファイルを生成したい場合は次のようにインストールしてください。Windows の場合は内部で処理されるため、この操作は不要です。
2.1. サンプル文書の変換
変換に使うスクリプトは GitHub のリポジトリに公開されており、HTML/PDF 変換に使うファイル一式と、文書のサンプルとして "この文書" の Asciidoc ファイルが配置されています。
文書変換スクリプトの実行には、前項で導入した Java 上で動作する Gradle ビルドツールが使われ、リポジトリに含まれる gradlew シェルスクリプトから定義を元に各種設定が自動的に行われ Asciidoc 文書から HTML/PDF 文書への変換が実行されます。本文書ではこれを、文書のビルドもしくは単純にビルドと呼ぶこととします。
文書変換スクリプトの実行には、前項で導入した Java 上で動作する Gradle ビルドツールが使われ、リポジトリに含まれる gradlew シェルスクリプトを起点として各種設定が自動的に行われ、Asciidoc 文書から HTML/PDF 文書への変換が実行されます。本文書ではこれを、文書のビルドもしくは単純にビルドと呼ぶこととします。
|
-
|
@@ -1452,11 +1452,11 @@
| - + |
@@ -1528,7 +1528,7 @@ 2.1.2. サンプル文書の変換
2.2. 変換後の文書
-
@@ -1544,29 +1544,51 @@
2.2. 変換後の文書
-
成果物の出力先となる ビルド結果の出力先となる HTML/PDF 文書フォルダ（
-
+
+
図. HTML/PDF 文書フォルダ（
docs）
-
成果物文書のソースとなるのは ビルド対象の文書となるソースフォルダ（
-
+
+
図. ビルド対象のソースフォルダ（
src/docs/asciidoc）
-
-
ビルドの基本的な動作は次のようになります。
-
PDF 版のファイルについては
+
-
以上から成果物の配布は次のようになります。 +以上からビルドした文書の配布は次のようになります。
-
なお、VS Code WSL2 拡張の動作の詳細について知りたい場合は以下のドキュメントを参照してください。 +なお、VS Code WSL2 拡張の詳細は次のドキュメントから得ることができます。 @@ -1724,6 +1749,7 @@ 2.3.3. VS Code による Asciidoc 文書のリアルタイムプレビュー@@ -1731,7 +1757,7 @@本手順のプロジェクトフォルダに配置された Asciidoc 文書は、VS Code を利用してリアルタイムに変換結果をプレビューしながら編集できるように設定されています。
@@ -1783,14 +1809,19 @@
-
+
|
最初のステップとして、プロジェクトフォルダを VS Code を開きます。VS Code でプロジェクトを開く場合は、次のように「フォルダで開く」などの操作でプロジェクトフォルダがルートになる形で行うことに注意してください。
+最初のステップとして、プロジェクトフォルダを VS Code を開きます。VS Code でプロジェクトを開く場合は、次のように「フォルダで開く」などの操作でプロジェクトフォルダがルートになる形で行うことに注意します。
|
-
-統合ターミナルはキーボードショートカット Ctrl + @ でも起動可能です。 -
-
また、統合ターミナル内では ↑ を押下することで前回入力した履歴が呼び出せます。この操作は文書変換コマンドを再実行する際に便利です。 +統合ターミナル内で起動する一般的なシェル環境では、↑ を押下することで前回入力した履歴が呼び出せます。この操作は文書変換コマンドを再実行する際に便利です。 |
@@ -1977,7 +2006,7 @@ ||
| 6 | -src/docs/asciidoc/index.adoc から参照される子文書です。build.gradle による画像パス解決のためフォルダ名は Chapter{number} とします。 |
-|
| 7 | -文書を変換する Gradle ビルドスクリプトです。Asciidoc 文書や画像パスの設定があります。 | +src/docs/asciidoc/index.adoc から参照される子文書です。各子文書のフォルダ名は Chapter{number} とします。 |
+2.4. 文書のファイル構成
2.4.1. 文書属性定義
src/docs/asciidoc/attribute.adoc では文書のデフォルトキャプション名などの属性定義が行えます。画像挿入時の「図. 」など標準で付与される文字列がありますので、必要に応じて修正します。
src/docs/asciidoc/attribute.adoc では文書のデフォルトキャプション名などの属性値を定義できます。画像挿入時の「図. 」など標準で付与される文字列がありますので、必要に応じて修正します。
src/docs/asciidoc/attribute.adoc2.4.2. PDF テーマ定義
2.5. 執筆の開始
一通りのサンプル文書の構成確認が終りましたら、次のような流れで新しい執筆を開始します。
+一通りのサンプル文書の構成確認が終われば、次のような流れで新しい執筆を開始できるでしょう。
-
@@ -2171,7 +2195,7 @@
-
-
GitHub 上のリポジトリをクローンしプロジェクトフォルダを得る。（初回のみ操作）
++その環境で初めて執筆する場合は、GitHub 上のリポジトリをクローンしプロジェクトフォルダを得る。
+
@@ -2472,18 +2495,15 @@git clone git@github.com:h1romas4/wasm-micro-book.git (1)2.7.5. 異なる執筆環境で
-
-
別の執筆環境からの修正（プッシュ）を取得するために
+git pull操作を実施。+別の執筆環境からの修正（プッシュ）を取得するために
+git pull操作を行う。-統合ターミナルからgit pullを実行git pull
-
- -
-
HTML、PDF 文書ファイルが存在するか。
+HTML、PDF 文書ファイルが生成されるか。
-
後述の asciidoctor-diagram による .svg 画像生成が動作したか。
@@ -3260,7 +3269,7 @@3.4. 文書中の相互参照
3.5. 外部リンク
-インターネット上の URL は自動的にリンクに変換されます。
+インターネット上の URL 文字列は自動的にリンクに変換されます。
-https://h1romas4.github.io/asciidoctor-gradle-template/index.html
@@ -3448,11 +3457,11 @@3.10. ファイルインクルード
.adocファイルから別のファイルをインクルードできます。ソースコードや後述のダイアグラム形式などを別ファイルとして切り出すのに便利です。+- + Gradle のファイル更新監視は .adocからインクルードされたファイルまでは及びません。インクルード先のファイルだけを書き換えた場合は./gradlew docsが処理なしで終了してしまいますので、この場合は./gradlew cleanとcleanタスクを起動しdocsフォルダをクリーニングしてから再ビルドしてください。 @@ -3831,7 +3840,7 @@3.14. 改ページ・ブレイク表現
3.15. ラベル文言
-特定のラベル文言に対して定義文を記述する表現は次のように記述します。
+特定のラベル文言に対して定義を明記する表現は次のように記述します。
@@ -3898,33 +3907,42 @@3.17. コメント行
4. ダイアグラム記法
--本変換スクリプトでは
+asciidoctorj-diagramが有効になっており、いくつかのダイアグラム記法を追加のアドイン無しで使えます。ダイアグラム記法は、図表をソースコードから出力できる特別なマークアップです。Asciidoc と同様に文書ファイル中のテキスト形式で "描ける" ことから、修正や差分管理がしやすいという利点があります。
--
+- -- - --PDF 出力時に日本語が化けないよう、自動的にフォントパッチが適用されるよう構成されています。 - -+本項では PlantUML と ditaa ダイアグラム記法を用いて、技術文書で使われやすい表現のいくつかの記述例を示します。
-+ダイアグラムを SVG ベクター画像で出力する指定は次のようになります。
+文書のビルドではダイアログ記法をサポートする asciidoctorj-diagram が有効になっており、PlantUML と ditta ダイアグラム記法を追加の操作無しで使えます。また、PDF 出力時に日本語が化けないよう自動的にフォントパッチが適用されるよう構成されています。
++Asciidoc 文書内でダイアグラムを SVG ベクター画像で出力する指定は次のようになります。
--
+[ダイアグラム種類, 出力ファイル名, svg, pdfwidth=70%, width=480px][ダイアグラム種類, 出力ファイル名, svg, pdfwidth=70%, width=480px] (1) (2) +---- +// ダイアグラム記法のソースコード +----++++
++ +1 +ダイアグラム種類には +plantumlかdittaを指定する。+ +2 +pdfwidthは PDF 紙面に対しての比率指定、widthは HTML 上の幅比率もしくはピクセル（px）で指定する。- + 出力ファイル名は imagesフォルダ内で一意になるように設定してください。特にダイアログ記法を別の場所からコピーアンドペーストした場合は要チェックです。同名ファイル名が指定された場合は上書きされる動作になります。 @@ -3933,16 +3951,10 @@4. ダイアグラム記法
--
-pdfwidthは PDF 紙面に対しての比率指定、widthは HTML 上の幅比率もしくはピクセル（px）で指定します。--本項では PlantUML と ditaa ダイアグラム記法を用いて、技術文書で使われやすい表現のいくつかの記述法を示します。
--コピーして使いやすいよう各ダイアグラム内で頻出する記法をなるべくピックアップする形で描いています。作成したい図表と似たようなものからアレンジして使うと良いでしょう。
+次項から PlantUML や ditta 記法を使って描いた実際のダイアグラム図表とソースコードを紹介します。コピーアンドペーストして使いやすいよう各ダイアグラム内で頻出する記法をなるべくピックアップする形で描いています。作成したい図表と似たようなものからアレンジして使うと良いでしょう。
-PlantUML と ditta 記法の詳細な仕様については、次のドキュメントから参照できます。
+PlantUML と ditta 記法の詳細な仕様については、次のドキュメントから得ることができます。
@@ -4471,7 +4483,7 @@
4.8. タイミングチャート
Open Iconic アイコン-PlantUML 内で
+<&アイコン名>形式で使える Open Iconic アイコンは次の通りです。アイコン名は HTML 版の場合 するとコピーアンドペーストで取得できます。PlantUML 内で
<&アイコン名>形式で使える Open Iconic アイコンは次の通りです。なお、アイコン名はこの文書が HTML 版の場合 するとコピーアンドペーストで取得できます。diff --git a/docs/index.pdf b/docs/index.pdf index de9b31a..c664d42 100644 Binary files a/docs/index.pdf and b/docs/index.pdf differ diff --git a/src/docs/asciidoc/Chapter00/index.adoc b/src/docs/asciidoc/Chapter00/index.adoc index e9495b5..82c3f3d 100644 --- a/src/docs/asciidoc/Chapter00/index.adoc +++ b/src/docs/asciidoc/Chapter00/index.adoc @@ -26,7 +26,7 @@ Asciidoc の表現力を示すひとつの例は、このような脚注表現 手間がかかることが多い PDF 出力に関しても、フォントセットや禁則処理設定をプロジェクトに持たせることにより、実行環境に関わらず同一出力が得られるように調整しました。 -Asciidoc による文書の執筆は形式的で効率が良く、また更新差分が取りやすいため、文書履歴管理や共同執筆環境としても有効です。このメリットをさらに活用するため、本手順ではテキストダイアグラム記法による図形や数式のベクター画像挿入をサポートしています。 +Asciidoc による文書の執筆は形式的で効率が良く、また更新差分が取りやすいため、文書履歴管理や共同執筆環境としても有効です。このメリットをさらに活用するため、本文書ではバージョン管理システムの Git やテキストダイアグラム記法による図形や数式のベクター画像挿入をフォローしています。 本文書がみなさんの執筆活動のお手伝いになれば幸いです。 @@ -54,7 +54,7 @@ What is Asciidoctor? Asciidoctor is a fast, open source, text processor for parsing AsciiDoc into a document model, then converting it to output formats such as HTML 5, DocBook 5, man(ual) pages, PDF, and EPUB 3. Asciidoctor is written in the Ruby programming language. ____ -同プロジェクトにおいて、ウェブブラウザ上で Asciidoc の動作を実現する Asciidoctor.js や、PDF 出力を行う Asciidoctor PDF が提供されています。AsciidoctorJ は、Ruby 実装である Asciidoctor を Java でかかれた Ruby 実行環境である JRuby を使って Java VM 上で動作させるプロダクトです。 +同プロジェクトにおいて、ウェブブラウザ上で Asciidoc の動作を実現する Asciidoctor.js や、PDF 出力を行う Asciidoctor PDF が提供されています。また、AsciidoctorJ は、Ruby 実装である Asciidoctor を Java でかかれた Ruby 実行環境である JRuby を使って Java VM 上で動作させるプロダクトとなっています。 <<< diff --git a/src/docs/asciidoc/Chapter01/index.adoc b/src/docs/asciidoc/Chapter01/index.adoc index 56986a0..6cab4de 100644 --- a/src/docs/asciidoc/Chapter01/index.adoc +++ b/src/docs/asciidoc/Chapter01/index.adoc @@ -2,7 +2,7 @@ include::../attribute.adoc[] == Asciidoc 文書変換用スクリプトを使う準備 -本手順で用いる Asciidoc 文書変換用スクリプトはビルドツールである Gradle を活用しており、実行するためには Java 実行環境が必要です。 +本文書で用いる Asciidoc 文書変換用スクリプトはビルドツールである Gradle を活用しており、実行するためには Java 実行環境が必要です。 お使いのコンピューターのコマンドライン環境（macOS/Linux ではターミナル、Windows では cmd.exe か powershell.exe）で ``java -version`` コマンドを入力し、Java 11 以上のバージョンが表示されるようであれば既に環境の準備は整っています。 @@ -26,11 +26,11 @@ OpenJDK Runtime Environment Temurin-11.0.20.1+1 (build 11.0.20.1+1) OpenJDK 64-Bit Server VM Temurin-11.0.20.1+1 (build 11.0.20.1+1, mixed mode) ---- -NOTE: 本文書では Java 11 を用いて解説します。また、ビルド時に僅かに内部処理のワーニングが出力されますが Java 17 でも期待通り動作することを確認しています。Java 21 に関しては周辺ツールの対応待ちのステータスです。 +NOTE: 本文書では Java 11 を用いて解説します。また、ビルド時に僅かに内部処理のワーニングが出力されますが Java 17 でも期待通り動作することを確認しています。Java 21 に関しては周辺ツール対応待ちのステータスです。 .Graphviz の導入 **** -macOS 及び Linux の場合で、後述する PlantUML 以外のダイアグラム記法を使う場合は Graphviz の導入が必要です。この文書のサンプルソースでも使っている部分が一部ありますので、ワーニングなしに本文書の完全なファイルを生成したい場合は次のようにインストールしてください。Windows の場合、この操作は不要です。 +macOS 及び Linux で、後述するダイアグラム記法の全てを変換するには Graphviz 画像ライブラリの導入が必要です。この文書のサンプルソースでも依存している部分が一部ありますので、ワーニングなしに本文書の完全なファイルを生成したい場合は次のようにインストールしてください。Windows の場合は内部で処理されるため、この操作は不要です。 [source, bash] [caption=""] diff --git a/src/docs/asciidoc/Chapter02/index.adoc b/src/docs/asciidoc/Chapter02/index.adoc index f1c1667..87457b9 100644 --- a/src/docs/asciidoc/Chapter02/index.adoc +++ b/src/docs/asciidoc/Chapter02/index.adoc @@ -8,11 +8,11 @@ include::../attribute.adoc[] 変換に使うスクリプトは GitHub のリポジトリに公開されており、HTML/PDF 変換に使うファイル一式と、文書のサンプルとして "この文書" の Asciidoc ファイルが配置されています。 -文書変換スクリプトの実行には、前項で導入した Java 上で動作する **Gradle** ビルドツールが使われ、リポジトリに含まれる ``gradlew`` シェルスクリプトから定義を元に各種設定が自動的に行われ Asciidoc 文書から HTML/PDF 文書への変換が実行されます。本文書ではこれを、文書のビルドもしくは単純にビルドと呼ぶこととします。 +文書変換スクリプトの実行には、前項で導入した Java 上で動作する **Gradle** ビルドツールが使われ、リポジトリに含まれる ``gradlew`` シェルスクリプトを起点として各種設定が自動的に行われ、Asciidoc 文書から HTML/PDF 文書への変換が実行されます。本文書ではこれを、文書のビルドもしくは単純にビルドと呼ぶこととします。 [NOTE] ==== -``gradlew`` コマンドは ``gradlew [タスク名]`` として実行したい機能を呼び分けることができます。本手順では文書の変換をする場合のタスク名を ``docs`` と定義しています。この名称や操作の内容は、リポジトリ中の ``build.gradle`` ファイル中に含まれます。 +``gradlew`` コマンドは ``gradlew [タスク名]`` として実行したい機能を呼び分けることができます。本手順では文書の変換をする場合のタスク名を ``docs`` と定義しています。タスク名称や操作の内容は、リポジトリ中の ``build.gradle`` ファイル中に含まれます。 ==== 最初にリポジトリからこれらのファイルの取得を行い、次に Asciidoc 文書を HTML/PDF 変換するためにビルドを実行します。各 OS ごとの代表的な操作は次のようになります。 @@ -45,7 +45,7 @@ BUILD SUCCESSFUL in 1m 13s <5> ウェブブラウザで URL にアクセスしてファイルの取得を行い、エクスプローラでファイルを展開し、最後にコマンドプロンプトから Gradle タスクを実行します。 -[IMPORTANT] +[CAUTION] ==== Windows の場合 .zip ファイルの展開先はマルチバイト文字を含まないパスにしてください。JRuby の制約により変換処理がエラーとなります。また、プロジェクト内部で使うフォルダやファイル名のマルチバイト名も同様です。 ==== @@ -91,7 +91,7 @@ set JAVA_OPTS=-DproxyHost=example.com -DproxyPort=8080 === 変換後の文書 -``./gradlew docs`` のビルド操作により Asciidoc から変換された文書は、``docs`` フォルダに HTML版(``index.html``)と PDF版（``index.pdf``）として格納されます。 +``./gradlew docs`` のビルド操作により Asciidoc から変換された文書は、プロジェクトフォルダの ``docs`` 配下に HTML版(``index.html``)と PDF版（``index.pdf``）として格納されます。 [caption="画像."] .HTML 文書 @@ -103,40 +103,48 @@ image::pdf.png[pdf, pdfwidth=80%, width=80%] <<< -成果物の出力先となる ``docs`` フォルダの構成は次のとおりです。 +ビルド結果の出力先となる HTML/PDF 文書フォルダ（``docs``）フォルダの構成は次のとおりです。 -[plantuml, directory-structure-1, svg, pdfwidth=72%, width=690px] -[caption=""] +.HTML/PDF 文書フォルダ（``docs``） +[caption="図. "] +[plantuml, directory-structure-1, svg, pdfwidth=70%, width=680px] ---- include::puml/directory-structure-1.puml[] ---- -成果物文書のソースとなるのは ``src/docs/asciidoc`` に配置された Asciidoc 文書と画像ファイル群です。 +ビルド対象の文書となるソースフォルダ（``src/docs/asciidoc``）の構成は次のとおりです。 -[plantuml, directory-structure-2, svg, pdfwidth=55%, width=522px] -[caption=""] +.ビルド対象のソースフォルダ（``src/docs/asciidoc``） +[caption="図. "] +[plantuml, directory-structure-2, svg, pdfwidth=62%, width=590px] ---- include::puml/directory-structure-2.puml[] ---- -``docs`` 出力フォルダの構成としては、章（``Chapter*/images``）フォルダには HTML 版からリンクされるリソースが ``src/docs/asciidoc`` からコピーされ配置されます。また、後述するダイアグラム記法を使った図表や数式も、ビルドのタイミングでベクター画像が生成され同フォルダに出力されます。 +ビルドの基本的な動作は次のようになります。 -PDF 版のファイルについては ``index.pdf`` 単体で完結しており、フォントや画像リソースなど全てが PDF ファイル内に格納されます。 +* HTML/PDF 文書フォルダ（``docs``）内のファイルを全て削除する。 +* ソースフォルダ（``src/docs/asciidoc``）に配置された Asciidoc 文書と画像などのリソースを変換処理し、HTML/PDF 文書フォルダに格納する。 +** Asciidoc 文書に後述するダイアログ記法による図表が存在していた場合はベクター画像生成する。 +** HTML 版の文書は ``docs/index.html`` として生成。``docs/Chapter*/images`` フォルダに配置した画像などのリソースをリンクする。 +** PDF 版の文書は ``docs/index.pdf`` として生成。フォントや画像リソースなど全てを PDF ファイル内に格納する。 -以上から成果物の配布は次のようになります。 +以上からビルドした文書の配布は次のようになります。 [format="csv",cols="1,2"] [frame="topbot",grid="none"] |====== -HTML 文書,``docs``フォルダの ``index.pdf``を除く全てのファイルを配布。 -PDF 文書, ``docs/index.pdf`` のみを配布。 +HTML 版の文書,``docs``フォルダの ``index.pdf``を除く全てのファイルを配布。 +PDF 版の文書, ``docs/index.pdf`` のみを配布。 |====== なおいずれの場合も ``index.*`` のファイル名は任意の名称に変更可能です。 [CAUTION] ==== -``docs`` フォルダは成果物の出力専用フォルダとなっており、ビルド時にいったん全てのファイルが削除されますので、**自らが作成したファイルは配置しない**ように注意してください。執筆で作成するファイルは必ず ``src/docs/asciidoc`` 配下に配置します。 +HTML/PDF 文書フォルダ（``docs``）はビルドした文書を配置する専用フォルダです。ソースフォルダと同期するためビルド時にいったん全てのファイルが削除されますので、**自らが作成したファイルは配置しない**ように注意してください。執筆で作成するファイルは必ず ``src/docs/asciidoc`` 配下に配置します。 + +なお、この後解説する Visual Studio Code テキストエディタでは、プロジェクト設定で ``docs`` フォルダをリードオンリーに指定し、誤ってファイルを追加・修正できないように制御してあります。 ==== === テキストエディタで Asciidoc 文書を編集する @@ -160,13 +168,13 @@ ____ image::2023-09-19-20-26-44.png[width=60%, pdfWidth=60%] -VS Code ではプロジェクトファイルとして「フォルダを開く」操作をよく活用します。このことから、エクスプローラなどのシェルのフォルダ右クリックのコンテキストメニューに VS Code を追加すると素早い操作ができるようになります。 +VS Code ではプロジェクトとして「フォルダを開く」操作をよく活用します。このことから、エクスプローラなどのシェルのフォルダ右クリックのコンテキストメニューに VS Code を追加すると素早い操作ができるようになります。 以上で、VS Code の準備は完了です。 ==== Visual Studio Code の導入（WSL2 Ubuntu 環境） -WSL2 環境上の Ubuntu で VS Code を使う場合は「Windows 版 VS Code」を導入後さらに次の WSL 拡張をインストールします。 +WSL2 環境上の Ubuntu で VS Code を使う場合は「Windows 版 VS Code」を導入後さらに次の WSL 拡張をインストールします。この拡張に処理により、VS Code のバックエンド処理が Ubuntu 側で、フロントエンド画面が Windows 側で動作できるようになります。 [quote, WSL - Visual Studio Marketplace] ____ @@ -179,7 +187,7 @@ ____ 拡張導入後、一度 VS Code を終了してください。 -次に、WSL2 Ubuntu のターミナル画面で `code` コマンドを入力することで WSL2 Ubuntu 上で VS Code サーバの初期セットアップが動作しその後 VS Code 画面が立ち上がります。 +次に、WSL2 Ubuntu のターミナル画面で `code` コマンドを入力することで WSL2 Ubuntu 上で VS Code バックエンドの初期セットアップが動作し、その後 Windows 上で VS Code フロントエンド画面が立ち上がります。 [source, bash] [caption=""] @@ -202,7 +210,7 @@ $ code . <2> <1> 編集したいプロジェクトにカレントディレクトリを移します。 <2> `.` とカレントディレクトリを指定して VS Code を起動します。 -なお、VS Code WSL2 拡張の動作の詳細について知りたい場合は以下のドキュメントを参照してください。 +なお、VS Code WSL2 拡張の詳細は次のドキュメントから得ることができます。 [quote, Developing in the Windows Subsystem for Linux with Visual Studio Code] ____ @@ -211,11 +219,13 @@ https://code.visualstudio.com/docs/remote/wsl The Visual Studio Code WSL extension lets you use the Windows Subsystem for Linux (WSL) as your full-time development environment right from VS Code. You can develop in a Linux-based environment, use Linux-specific toolchains and utilities, and run and debug your Linux-based applications all from the comfort of Windows. ____ +<<< + ==== VS Code による Asciidoc 文書のリアルタイムプレビュー 本手順のプロジェクトフォルダに配置された Asciidoc 文書は、VS Code を利用してリアルタイムに変換結果をプレビューしながら編集できるように設定されています。 -最初のステップとして、プロジェクトフォルダを VS Code を開きます。VS Code でプロジェクトを開く場合は、次のように「フォルダで開く」などの操作でプロジェクトフォルダがルートになる形で行うことに注意してください。 +最初のステップとして、プロジェクトフォルダを VS Code を開きます。VS Code でプロジェクトを開く場合は、次のように「フォルダで開く」などの操作でプロジェクトフォルダがルートになる形で行うことに注意します。 image::2023-09-19-16-33-05.png[width=70%, pdfWidth=70%] @@ -238,7 +248,12 @@ image::2023-09-17-13-30-33.png[pdfwidth=60%, width=60%] + image::vscode-extension2.png[vscode, pdfwidth=50%] -NOTE: 導入推奨拡張は ``.vscode/extensions.json`` ファイルで設定されています。文書に応じて設定し、執筆メンバーの環境を揃えられます。 +[TIP] +==== +VS Code のリアルタイムプレビュー設定は ``.vscode/settings.json`` ファイルで、導入推奨拡張は ``.vscode/extensions.json`` ファイルで定義されています。 + +これらのファイルを修正することで、例えば拡張に日本語校正やスペルチェックを追加し設定を定義するなど、執筆メンバーの執筆環境を揃えられます。 +==== 以上で Asciidoc 文書編集のための準備が完了しました。 @@ -258,6 +273,8 @@ image::vscode-asciidoc.png[width=80%, pdfWidth=80%] ``.adoc`` ファイルには本文書の内容がそのまま Asciidoc 文書形式で書かれているのが分かります。いくつか開いて試し入力などをしてみると、Asciidoc 文書のリアルタイムプレビューを含め執筆の雰囲気が掴めるはずです。 +<<< + ==== クリップボードからの画像挿入 本手順で VS Code の推奨拡張として導入される https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image[Paste Image]（``mushan.vscode-paste-image``） は、クリップボード上にある画像をファイルとして指定の位置に格納した上で、Asciidoc 文書にリンクを挿入する便利な拡張です。 @@ -335,7 +352,7 @@ powershell.exe -ExecutionPolicy Bypass -File pc.ps1 ${DISTPATH}$1 ==== 統合ターミナルの活用 -VS Code には統合ターミナルと呼ばれる VS Code 画面内で使えるターミナルエミュレータが備わっており、ここで文書変換コマンドを実行できます。 +VS Code には統合ターミナルと呼ばれる VS Code 画面内で使えるターミナルエミュレータが備わっており、エディターを離れることなく文書のビルドが可能です。 .VS Code 統合ターミナルからの文書変換 [caption="画面. "] @@ -347,20 +364,18 @@ image::2023-09-20-15-30-52.png[width=60%, pdfWidth=60%] [caption="画面. "] image::2023-09-20-15-26-40.png[width=60%, pdfWidth=60%] -統合ターミナルを活用すると VS Code を離れることなく文書のビルドができます。 +統合ターミナルはキーボードショートカット btn:[Ctrl + @] でも起動可能です。再度、同キーを押下することでクローズするトグル動作となっており、画面を広く使いたい執筆中に活用できます。 [TIP] ==== -統合ターミナルはキーボードショートカット btn:[Ctrl + @] でも起動可能です。 - -また、統合ターミナル内では btn:[↑] を押下することで前回入力した履歴が呼び出せます。この操作は文書変換コマンドを再実行する際に便利です。 +統合ターミナル内で起動する一般的なシェル環境では、btn:[↑] を押下することで前回入力した履歴が呼び出せます。この操作は文書変換コマンドを再実行する際に便利です。 ==== ''' .その他の Asciidoc 文書編集が可能な統合開発環境 **** -本手順では VS Code を Asciidoc 文書編集用のエディタとして活用していますが、Eclipse や IntelliJ IDEA といった統合開発環境も Asciidoc を拡張機能でサポートしています。 +本文書では VS Code を Asciidoc 文書編集用のエディタとして活用していますが、Eclipse や IntelliJ IDEA といった統合開発環境も Asciidoc を拡張機能でサポートしています。 .IntelliJ IDEA の AsciiDoc Plugin で文書編集している例 [caption="画像. "] @@ -373,7 +388,7 @@ image::2023-09-20-18-42-42.png[pdfwidth=100%, width=100%] === 文書のファイル構成 -以下に執筆で編集する Asciidoc 文書フォルダ（``src/docs/asciidoc`` 配下）のファイル構成を示します。 +以下に執筆で編集する Asciidoc 文書フォルダ（``src/docs/asciidoc`` 配下）のファイル構成の詳細を示します。 [plantuml, directory-structure-3, svg, pdfwidth=40%, width=390px] [caption=""] @@ -390,7 +405,6 @@ src/docs/asciidoc/@style/asciidoctor.css # <3> src/docs/asciidoc/@style/pdf-theme.yml # <4> src/docs/asciidoc/@font/**/*.ttf # <5> src/docs/asciidoc/Chapter{number}/index.adoc <6> -build.gradle <7> ---- <1> 文書を作成する起点となる Asciidoc 文書です。表紙となる文書のタイトルなどを記載し、その後から章ごとの Asciidoc 文書を ``include`` して構成していきます。 @@ -398,8 +412,7 @@ build.gradle <7> <3> HTML 出力とプレビュー用のスタイルシートです。文書に合わせて修正できます。 <4> PDF 文書に変換する際に使われるスタイル定義です。文書に合わせて修正できます。 <5> PDF 文書に埋め込みされるフォントファイルを配置します。``pdf-theme.yml`` からファイル名で参照されています。TrueType フォント ``.ttf`` が指定できます。 -<6> ``src/docs/asciidoc/index.adoc`` から参照される子文書です。``build.gradle`` による画像パス解決のためフォルダ名は ``Chapter\{number\}`` とします。 -<7> 文書を変換する Gradle ビルドスクリプトです。Asciidoc 文書や画像パスの設定があります。 +<6> ``src/docs/asciidoc/index.adoc`` から参照される子文書です。各子文書のフォルダ名は ``Chapter\{number\}`` とします。 本構成を元に執筆したい文書に合わせカスタマイズしていきます。文書ファイルの編集や閲覧は VS Code のリアルタイムプレビューで確認しながら行うと分かりやすいでしょう。 @@ -407,7 +420,7 @@ build.gradle <7> ==== 文書属性定義 -``src/docs/asciidoc/attribute.adoc`` では文書のデフォルトキャプション名などの属性定義が行えます。画像挿入時の「図. 」など標準で付与される文字列がありますので、必要に応じて修正します。 +``src/docs/asciidoc/attribute.adoc`` では文書のデフォルトキャプション名などの属性値を定義できます。画像挿入時の「図. 」など標準で付与される文字列がありますので、必要に応じて修正します。 [source] [caption=""] @@ -453,7 +466,7 @@ NOTE: 本手順で採用している Asciidoctor PDF のバージョンは ``1.6 === 執筆の開始 -一通りのサンプル文書の構成確認が終りましたら、次のような流れで新しい執筆を開始します。 +一通りのサンプル文書の構成確認が終われば、次のような流れで新しい執筆を開始できるでしょう。 . サンプル文書の ``src/docs/asciidoc/Chapter02`` 以降のフォルダの削除を行い見通しを良くする。 . ``src/docs/asciidoc/index.adoc`` からの 1. で削除した ``Chapter*`` の``include`` を削除する。 @@ -468,7 +481,7 @@ NOTE: 本手順で採用している Asciidoctor PDF のバージョンは ``1.6 === 執筆のイテレーション -ここまでの手順で執筆環境が整った後の、文書執筆の進め方のイメージは次のようになります。 +ここまでの手順で執筆環境が整った後、毎日の執筆の進め方は次のようになります。 . プロジェクトフォルダを VS Code で開く。 . ``src/docs/asciidocs`` 配下の Asciidoc 文書を VS Code でプレビューしながら執筆する。 @@ -613,7 +626,7 @@ image::2023-09-12-12-51-08.png[width=50%, pdfWidth=50%] コミットはローカル上の Git に対して行われます。この後 GitHub のリモートリポジトリに反映させるため btn:[Sync Changes] を押下しプッシュ操作を行います。 -WARNING: プッシュ操作を行うまで GitHub リモートリポジトリには文書の修正が反映されません。忘れずに実施してください。操作に慣れるまでは、プッシュ操作後にウェブブラウザで GitHub リポジトリにアクセスしファイルの更新を確認すると良いでしょう。 +CAUTION: プッシュ操作を行うまで GitHub リモートリポジトリには文書の修正が反映されません。忘れずに実施してください。操作に慣れるまでは、プッシュ操作後にウェブブラウザで GitHub リポジトリにアクセスしファイルの更新を確認すると良いでしょう。 .VS Code から GitHub Repository へのプッシュ [caption="画面. "] @@ -632,17 +645,17 @@ git push 異なる執筆環境から GitHub リポジトリの文書を取得するには次の操作を行います。 -. GitHub 上のリポジトリをクローンしプロジェクトフォルダを得る。（初回のみ操作） -+ +その環境で初めて執筆する場合は、GitHub 上のリポジトリをクローンしプロジェクトフォルダを得る。 + [source, bash] [caption=""] ---- git clone git@github.com:h1romas4/wasm-micro-book.git # <1> ---- <1> `h1romas4/wasm-micro-book.git` 部分が前項で作成したリポジトリ名になります。 -+ -. 別の執筆環境からの修正（プッシュ）を取得するために `git pull` 操作を実施。 -+ + +別の執筆環境からの修正（プッシュ）を取得するために `git pull` 操作を行う。 + .統合ターミナルから `git pull` を実行 [source, bash] [caption=""] @@ -652,7 +665,7 @@ git pull [NOTE] ==== -個人の執筆活動の Git 操作としては「執筆開始前に `git pull`」「執筆区切りで `commit` と `push`」 と覚えておくだけで十分機能するはずです。 +個人の執筆活動における Git 初歩としては「執筆開始前に必ず `git pull`」「執筆区切りで `commit` と `push`」 と覚えることで十分機能するはずです。 ==== ==== Git による文書の差分比較 @@ -684,7 +697,7 @@ image::2023-09-21-18-31-16.png[pdfwidth=80%, width=80%] === クラウド環境による執筆 -クラウド開発環境である https://www.gitpod.io/[Gitpod] や GitHub の https://github.co.jp/features/codespaces[Codespaces] を活用すると、ローカル環境の準備なしにウェブブラウザだけで執筆と HTML/PDF 文書変換が可能です。このことから、サブマシンや iPad などタブレット端末でも執筆活動が行えます。 +クラウド開発環境である https://www.gitpod.io/[Gitpod] や GitHub の https://github.co.jp/features/codespaces[Codespaces] を活用すると、ローカル環境の準備なしにウェブブラウザだけで執筆と HTML/PDF 文書のビルドが可能です。このことから、サブマシンや iPad などタブレット端末でも執筆活動が行えます。 [quote, Gitpod] ____ @@ -724,7 +737,7 @@ image::2023-07-03-14-28-22.png[] 本手順向けの VS Code 用の推奨拡張が自動導入されるように設定されていますので、特に操作をせずそのまま文書の執筆が開始できます。 -また合わせて、統合ターミナルから HTML/PDF のビルドができるようコンテナ環境も自動設定されます。ターミナルに以下の表示が出力されれば準備完了です。同ターミナルで `./gradlew docs` することによりローカル環境と同様に HTML/PDF の文書変換が開始されます。 +また合わせて、統合ターミナルから文書のビルドができるようコンテナ環境も自動設定されます。ターミナルに以下の表示が出力されれば準備完了です。同ターミナルで `./gradlew docs` することによりローカル環境と同様に HTML/PDF の文書変換が開始されます。 [source, bash] ---- @@ -764,7 +777,7 @@ NOTE: https://github.com/h1romas4/asciidoctor-gradle-template にアクセス後 .ウェブブラウザ上で起動した VS Code と Asciidoc 拡張（Codespaces） image::2023-09-11-19-06-20.png[] -前項の Gitpod と同様に VS Code の拡張は自動導入され、PDF/HTML ビルド用のコンテナ環境も構築されます。コンテナ環境の構築中は統合ターミナルに以下のような表示がされ、終了とともに自動的に閉じられます。 +前項の Gitpod と同様に VS Code の拡張は自動導入され、文書のビルド用のコンテナ環境も構築されます。コンテナ環境の構築中は統合ターミナルに以下のような表示がされ、終了とともに自動的に閉じられます。 [source, bash] ---- @@ -774,7 +787,7 @@ Use Cmd/Ctrl + Shift + P -> View Creation Log to see full logs > bash .devcontainer/build-codespaces-container.sh ---- -PDF/HTML のビルドは本処理が終了後、新しい統合ターミナルを開き環境が日本語設定になっていることを確認の上 `./gradlew docs` を実行します。 +文書のビルドは本処理が終了後、新しい統合ターミナルを開き環境が日本語設定になっていることを確認の上 `./gradlew docs` を実行します。 [source, bash] ---- @@ -790,12 +803,9 @@ BUILD SUCCESSFUL in 3m 19s <2> `Noto Sans CJK JP` になっていること <3> 文書のビルドを開始 -[WARNING] -==== 統合ターミナルの環境が日本語設定になっていない場合、文書中のダイアログ記法で生成された図表の日本語出力が崩れる場合があります。 -クラウド環境初期後に自動的に開かれる統合ターミナルは日本語設定が反映していないため、文書のビルドを行う場合は混乱がないように `exit` コマンドで一旦閉じた上で再起動すると良いでしょう。 -==== +クラウド環境初期後に自動的に開かれる統合ターミナルは日本語設定が反映していないため、文書のビルドを行う場合は混乱がないように `exit` コマンドで一旦閉じた上で統合ターミナルを再起動すると良いでしょう。 NOTE: Codespaces 向けの設定は `.devcontainer/devcontainer.json` 及び `.devcontainer/build-codespaces-container.sh` ファイルで定義されています。 @@ -827,7 +837,7 @@ NOTE: クラウド上で起動していた環境は最終利用時からある .VS Code の Zen Mode **** -VS Code には執筆に集中したい場合に、不要な UI を隠しながらフルスクリーン表示をする Zen Mode があります。標準のキーアサインでは btn:[Ctrl + k, z] でモードが遷移し、再度同じ操作で元の画面に戻ります。 +VS Code には執筆に集中したい場合に、不要な UI を隠しながらフルスクリーン表示をする Zen Mode があります。標準のキーアサインでは btn:[Ctrl + k, z] でモードが遷移し、再度同じ操作もしくは btn:[Esc] 2回押下で元の画面に戻ります。 image::2023-07-02-15-09-43.png[pdfwidth=84%, width=90%] @@ -849,13 +859,13 @@ Zen Mode は、VS Code や OS の不要なコンポーネントが見えなく ==== 文書ファイルの変換テストと検査（gradle.yml） -git による main ブランチへの push 操作を契機に自動的に動作する文書変換テストです。Linux、Windows、macOS のそれぞれの環境で、Java 11 と 17 においてビルドが試行され、一定の検査が行われます。 +git による main ブランチへの push 操作を契機に自動的に動作する文書変換テストです。macOS、Linux、Windows のそれぞれの環境で、Java 11 と 17 においてビルドが試行され、一定の検査が行われます。 -環境はマトリクスになっており、計 6 環境でのテストでビルドが正しいかが確認され GitHub Actions 上のログやメール通知で結果が得られます。自分の執筆環境以外のさまざまな環境で、変換処理が実行できることへの確信が持てるはずです。 +環境はマトリクスになっており、計 6 環境でのテストでビルドが正しいかが確認され GitHub Actions 上のログやメール通知で結果が得られます。自分の執筆環境以外のさまざまな環境で、文書のビルドが実行できることへの確信が持てるはずです。 検査に関しては、文書が生成されたかを基本として確認を行い、文書の内容自体に対しては行われません。 -- HTML、PDF 文書ファイルが存在するか。 +- HTML、PDF 文書ファイルが生成されるか。 - 後述の asciidoctor-diagram による .svg 画像生成が動作したか。 - GitHub Actions ログへのファイル数、一覧の出力。 diff --git a/src/docs/asciidoc/Chapter02/puml/directory-structure-1.puml b/src/docs/asciidoc/Chapter02/puml/directory-structure-1.puml index 70c113c..248acb1 100644 --- a/src/docs/asciidoc/Chapter02/puml/directory-structure-1.puml +++ b/src/docs/asciidoc/Chapter02/puml/directory-structure-1.puml @@ -17,7 +17,7 @@ ++ <&folder> Chapter03 +++ <&folder> images ++++ <&file> diag-salt-sample1.svg | HTML 版向けに自動生成されたベクター画像 - ++++ <&file> diag-salt-sample2.svg | 後述のダイアグラム記法による + ++++ <&file> diag-salt-sample2.svg ++++ <&file> ..snip.. ++ <&file> index.html | HTML 版（CSSを内包・画像はファイルに依存） ++ <&file> index.pdf | PDF 版（全ての画像・フォントリソースを内包） diff --git a/src/docs/asciidoc/Chapter02/puml/directory-structure-2.puml b/src/docs/asciidoc/Chapter02/puml/directory-structure-2.puml index 8f8e296..84284b7 100644 --- a/src/docs/asciidoc/Chapter02/puml/directory-structure-2.puml +++ b/src/docs/asciidoc/Chapter02/puml/directory-structure-2.puml @@ -13,7 +13,10 @@ ++++++ <&file> AdoptOpenJDK.png | 文書で使う画像ファイル ++++++ <&file> windows-01.png ++++++ <&file> windows-02.png + ++++ <&folder> Chapter03 + +++++ <&file> index.adoc | ダイアグラム記法を含む Asciidoc 文書 ++++ <&folder> ..snip.. + ++++ <&file> index.adoc | 各章を統合する Asciidoc 文書 } } @endsalt diff --git a/src/docs/asciidoc/Chapter02/puml/directory-structure-3.puml b/src/docs/asciidoc/Chapter02/puml/directory-structure-3.puml index 05b4eb6..9e22e84 100644 --- a/src/docs/asciidoc/Chapter02/puml/directory-structure-3.puml +++ b/src/docs/asciidoc/Chapter02/puml/directory-structure-3.puml @@ -23,7 +23,6 @@ ++++ <&folder> ..snip.. ++++ <&file> attribute.adoc | ❷ ++++ <&file> index.adoc | ❶ - + <&file> build.gradle | ❼ } } @endsalt diff --git a/src/docs/asciidoc/Chapter03/index.adoc b/src/docs/asciidoc/Chapter03/index.adoc index b054a58..f4d3179 100644 --- a/src/docs/asciidoc/Chapter03/index.adoc +++ b/src/docs/asciidoc/Chapter03/index.adoc @@ -111,7 +111,7 @@ NOTE: 補完文字列は他の補完と区別しやすいよう `ag-` が先頭 === 外部リンク -インターネット上の URL は自動的にリンクに変換されます。 +インターネット上の URL 文字列は自動的にリンクに変換されます。 https://h1romas4.github.io/asciidoctor-gradle-template/index.html @@ -230,7 +230,7 @@ btn:[OK] ボタン `.adoc` ファイルから別のファイルをインクルードできます。ソースコードや後述のダイアグラム形式などを別ファイルとして切り出すのに便利です。 -IMPORTANT: Gradle のファイル更新監視は `.adoc` からインクルードされたファイルまでは及びません。インクルード先のファイルだけを書き換えた場合は `./gradlew docs` が処理なしで終了してしまいますので、この場合は `./gradlew clean` と ``clean`` タスクを起動し ``docs`` フォルダをクリーニングしてから再ビルドしてください。 +CAUTION: Gradle のファイル更新監視は `.adoc` からインクルードされたファイルまでは及びません。インクルード先のファイルだけを書き換えた場合は `./gradlew docs` が処理なしで終了してしまいますので、この場合は `./gradlew clean` と ``clean`` タスクを起動し ``docs`` フォルダをクリーニングしてから再ビルドしてください。 [source] ----- @@ -447,7 +447,7 @@ CAUTION: 注意 === ラベル文言 -特定のラベル文言に対して定義文を記述する表現は次のように記述します。 +特定のラベル文言に対して定義を明記する表現は次のように記述します。 [source] ---- diff --git a/src/docs/asciidoc/Chapter04/index.adoc b/src/docs/asciidoc/Chapter04/index.adoc index bb00259..98a425c 100644 --- a/src/docs/asciidoc/Chapter04/index.adoc +++ b/src/docs/asciidoc/Chapter04/index.adoc @@ -2,26 +2,29 @@ include::../attribute.adoc[] == ダイアグラム記法 -本変換スクリプトでは `asciidoctorj-diagram` が有効になっており、いくつかのダイアグラム記法を追加のアドイン無しで使えます。 +ダイアグラム記法は、図表をソースコードから出力できる特別なマークアップです。Asciidoc と同様に文書ファイル中のテキスト形式で "描ける" ことから、修正や差分管理がしやすいという利点があります。 -NOTE: PDF 出力時に日本語が化けないよう、自動的にフォントパッチが適用されるよう構成されています。 +本項では **PlantUML** と **ditaa** ダイアグラム記法を用いて、技術文書で使われやすい表現のいくつかの記述例を示します。 -ダイアグラムを SVG ベクター画像で出力する指定は次のようになります。 +文書のビルドではダイアログ記法をサポートする **asciidoctorj-diagram** が有効になっており、PlantUML と ditta ダイアグラム記法を追加の操作無しで使えます。また、PDF 出力時に日本語が化けないよう自動的にフォントパッチが適用されるよう構成されています。 + +Asciidoc 文書内でダイアグラムを SVG ベクター画像で出力する指定は次のようになります。 [source] ----- -[ダイアグラム種類, 出力ファイル名, svg, pdfwidth=70%, width=480px] +[ダイアグラム種類, 出力ファイル名, svg, pdfwidth=70%, width=480px] // <1> <2> +---- +// ダイアグラム記法のソースコード +---- ----- +<1> ダイアグラム種類には ``plantuml`` か ``ditta`` を指定する。 +<2> ``pdfwidth`` は PDF 紙面に対しての比率指定、``width`` は HTML 上の幅比率もしくはピクセル（``px``）で指定する。 -IMPORTANT: 出力ファイル名は `images` フォルダ内で一意になるように設定してください。特にダイアログ記法を別の場所からコピーアンドペーストした場合は要チェックです。同名ファイル名が指定された場合は上書きされる動作になります。 - -``pdfwidth`` は PDF 紙面に対しての比率指定、``width`` は HTML 上の幅比率もしくはピクセル（``px``）で指定します。 - -本項では PlantUML と ditaa ダイアグラム記法を用いて、技術文書で使われやすい表現のいくつかの記述法を示します。 +CAUTION: 出力ファイル名は `images` フォルダ内で一意になるように設定してください。特にダイアログ記法を別の場所からコピーアンドペーストした場合は要チェックです。同名ファイル名が指定された場合は上書きされる動作になります。 -コピーして使いやすいよう各ダイアグラム内で頻出する記法をなるべくピックアップする形で描いています。作成したい図表と似たようなものからアレンジして使うと良いでしょう。 +次項から PlantUML や ditta 記法を使って描いた実際のダイアグラム図表とソースコードを紹介します。コピーアンドペーストして使いやすいよう各ダイアグラム内で頻出する記法をなるべくピックアップする形で描いています。作成したい図表と似たようなものからアレンジして使うと良いでしょう。 -PlantUML と ditta 記法の詳細な仕様については、次のドキュメントから参照できます。 +PlantUML と ditta 記法の詳細な仕様については、次のドキュメントから得ることができます。 [quote, PlantUML] ____ @@ -364,7 +367,7 @@ include::puml/diag-timing-sample1.puml[] .Open Iconic アイコン **** -PlantUML 内で ``<&アイコン名>`` 形式で使える Open Iconic アイコンは次の通りです。アイコン名は HTML 版の場合 menu:ウェブブラウザ[右クリック > 画像を開く] するとコピーアンドペーストで取得できます。 +PlantUML 内で ``<&アイコン名>`` 形式で使える Open Iconic アイコンは次の通りです。なお、アイコン名はこの文書が HTML 版の場合 menu:ウェブブラウザ[右クリック > 画像を開く] するとコピーアンドペーストで取得できます。 [plantuml, open-iconic-list, svg] [caption=""]
2.5. 執筆の開始
2.6. 執筆のイテレーション
ここまでの手順で執筆環境が整った後の、文書執筆の進め方のイメージは次のようになります。
+ここまでの手順で執筆環境が整った後、毎日の執筆の進め方は次のようになります。
-
@@ -2422,11 +2446,11 @@
2.7.4. 修正し
コミットはローカル上の Git に対して行われます。この後 GitHub のリモートリポジトリに反映させるため Sync Changes を押下しプッシュ操作を行います。
-
+
-
+
プッシュ操作を行うまで GitHub リモートリポジトリには文書の修正が反映されません。忘れずに実施してください。操作に慣れるまでは、プッシュ操作後にウェブブラウザで GitHub リポジトリにアクセスしファイルの更新を確認すると良いでしょう。
@@ -2455,10 +2479,9 @@ 2.7.5. 異なる執筆環境で
異なる執筆環境から GitHub リポジトリの文書を取得するには次の操作を行います。
-
-
-
-
-
@@ -2492,7 +2512,7 @@ 2.7.5. 異なる執筆環境で
-個人の執筆活動の Git 操作としては「執筆開始前に git pull」「執筆区切りで commit と push」 と覚えておくだけで十分機能するはずです。
+個人の執筆活動における Git 初歩としては「執筆開始前に必ず git pull」「執筆区切りで commit と push」 と覚えることで十分機能するはずです。
@@ -2550,7 +2570,7 @@ 2.7.6. Git による文書の差分
2.8. クラウド環境による執筆
-クラウド開発環境である Gitpod や GitHub の Codespaces を活用すると、ローカル環境の準備なしにウェブブラウザだけで執筆と HTML/PDF 文書変換が可能です。このことから、サブマシンや iPad などタブレット端末でも執筆活動が行えます。
+クラウド開発環境である Gitpod や GitHub の Codespaces を活用すると、ローカル環境の準備なしにウェブブラウザだけで執筆と HTML/PDF 文書のビルドが可能です。このことから、サブマシンや iPad などタブレット端末でも執筆活動が行えます。
@@ -2631,7 +2651,7 @@ 2.8.1. Gitpod
本手順向けの VS Code 用の推奨拡張が自動導入されるように設定されていますので、特に操作をせずそのまま文書の執筆が開始できます。
-また合わせて、統合ターミナルから HTML/PDF のビルドができるようコンテナ環境も自動設定されます。ターミナルに以下の表示が出力されれば準備完了です。同ターミナルで ./gradlew docs することによりローカル環境と同様に HTML/PDF の文書変換が開始されます。
+また合わせて、統合ターミナルから文書のビルドができるようコンテナ環境も自動設定されます。ターミナルに以下の表示が出力されれば準備完了です。同ターミナルで ./gradlew docs することによりローカル環境と同様に HTML/PDF の文書変換が開始されます。
@@ -2707,7 +2727,7 @@ 2.8.2. Codespaces
画像.ウェブブラウザ上で起動した VS Code と Asciidoc 拡張（Codespaces）
-前項の Gitpod と同様に VS Code の拡張は自動導入され、PDF/HTML ビルド用のコンテナ環境も構築されます。コンテナ環境の構築中は統合ターミナルに以下のような表示がされ、終了とともに自動的に閉じられます。
+前項の Gitpod と同様に VS Code の拡張は自動導入され、文書のビルド用のコンテナ環境も構築されます。コンテナ環境の構築中は統合ターミナルに以下のような表示がされ、終了とともに自動的に閉じられます。
@@ -2718,7 +2738,7 @@ 2.8.2. Codespaces
-PDF/HTML のビルドは本処理が終了後、新しい統合ターミナルを開き環境が日本語設定になっていることを確認の上 ./gradlew docs を実行します。
+文書のビルドは本処理が終了後、新しい統合ターミナルを開き環境が日本語設定になっていることを確認の上 ./gradlew docs を実行します。
@@ -2747,22 +2767,11 @@ 2.8.2. Codespaces
-
-
-
-
-
-
-
統合ターミナルの環境が日本語設定になっていない場合、文書中のダイアログ記法で生成された図表の日本語出力が崩れる場合があります。
-クラウド環境初期後に自動的に開かれる統合ターミナルは日本語設定が反映していないため、文書のビルドを行う場合は混乱がないように exit コマンドで一旦閉じた上で再起動すると良いでしょう。
-
-
-
-
+クラウド環境初期後に自動的に開かれる統合ターミナルは日本語設定が反映していないため、文書のビルドを行う場合は混乱がないように exit コマンドで一旦閉じた上で統合ターミナルを再起動すると良いでしょう。
@@ -2839,7 +2848,7 @@ 2.9. ク
VS Code の Zen Mode
-VS Code には執筆に集中したい場合に、不要な UI を隠しながらフルスクリーン表示をする Zen Mode があります。標準のキーアサインでは Ctrl + k, z でモードが遷移し、再度同じ操作で元の画面に戻ります。
+VS Code には執筆に集中したい場合に、不要な UI を隠しながらフルスクリーン表示をする Zen Mode があります。標準のキーアサインでは Ctrl + k, z でモードが遷移し、再度同じ操作もしくは Esc 2回押下で元の画面に戻ります。
@@ -2878,10 +2887,10 @@ 2.10. GitHub Actions によるビル
2.10.1. 文書ファイルの変換テストと検査（gradle.yml）
-git による main ブランチへの push 操作を契機に自動的に動作する文書変換テストです。Linux、Windows、macOS のそれぞれの環境で、Java 11 と 17 においてビルドが試行され、一定の検査が行われます。
+git による main ブランチへの push 操作を契機に自動的に動作する文書変換テストです。macOS、Linux、Windows のそれぞれの環境で、Java 11 と 17 においてビルドが試行され、一定の検査が行われます。
-環境はマトリクスになっており、計 6 環境でのテストでビルドが正しいかが確認され GitHub Actions 上のログやメール通知で結果が得られます。自分の執筆環境以外のさまざまな環境で、変換処理が実行できることへの確信が持てるはずです。
+環境はマトリクスになっており、計 6 環境でのテストでビルドが正しいかが確認され GitHub Actions 上のログやメール通知で結果が得られます。自分の執筆環境以外のさまざまな環境で、文書のビルドが実行できることへの確信が持てるはずです。
検査に関しては、文書が生成されたかを基本として確認を行い、文書の内容自体に対しては行われません。
@@ -2889,7 +2898,7 @@ 2.10.1. 文書
コミットはローカル上の Git に対して行われます。この後 GitHub のリモートリポジトリに反映させるため Sync Changes を押下しプッシュ操作を行います。
| - + |
プッシュ操作を行うまで GitHub リモートリポジトリには文書の修正が反映されません。忘れずに実施してください。操作に慣れるまでは、プッシュ操作後にウェブブラウザで GitHub リポジトリにアクセスしファイルの更新を確認すると良いでしょう。
@@ -2455,10 +2479,9 @@ 2.7.5. 異なる執筆環境で
異なる執筆環境から GitHub リポジトリの文書を取得するには次の操作を行います。
|
|
-
個人の執筆活動の Git 操作としては「執筆開始前に 個人の執筆活動における Git 初歩としては「執筆開始前に必ず |
| - - | -
統合ターミナルの環境が日本語設定になっていない場合、文書中のダイアログ記法で生成された図表の日本語出力が崩れる場合があります。
-
-クラウド環境初期後に自動的に開かれる統合ターミナルは日本語設定が反映していないため、文書のビルドを行う場合は混乱がないように |
-
クラウド環境初期後に自動的に開かれる統合ターミナルは日本語設定が反映していないため、文書のビルドを行う場合は混乱がないように exit コマンドで一旦閉じた上で統合ターミナルを再起動すると良いでしょう。