AsciidoctorとGradleでつくる文書執筆環境

$ curl -s "https://get.sdkman.io" | bash (1)
$ source "$HOME/.sdkman/bin/sdkman-init.sh" (2)
$ sdk list java (3)
================================================================================
Available Java Versions for Linux 64bit
================================================================================
 Vendor        | Use | Version      | Dist    | Status     | Identifier
--------------------------------------------------------------------------------
 Temurin       |     | 20.0.2       | tem     |            | 20.0.2-tem
               |     | 20.0.1       | tem     |            | 20.0.1-tem
               |     | 17.0.8       | tem     | installed  | 17.0.8-tem
               |     | 17.0.8.1     | tem     |            | 17.0.8.1-tem
               |     | 17.0.7       | tem     | installed  | 17.0.7-tem
               |     | 17.0.4       | tem     | local only | 17.0.4-tem
               |     | 11.0.20      | tem     |            | 11.0.20-tem
               | >>> | 11.0.20.1    | tem     | installed  | 11.0.20.1-tem
               |     | 11.0.19      | tem     | installed  | 11.0.19-tem
$ sdk install java 11.0.20.1-tem (4)

$ vi ~/.bashrc (1)
export JAVA_HOME=~/.sdkman/candidates/java/current (2)
$ source ~/.bashrc (3)

src/docs/asciidoc/index.adoc (1)
src/docs/asciidoc/attribute.adoc (2)
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)

= AsciidoctorとGradleでつくる文書執筆環境 (1)

== はじめに (2)
(3)
本文書は Asciidoc とその Ruby による実装である... (4)

こんにちは。
(1)
吾輩は段落である。（ここには空行はない） (2)
名前はまだない。

[[project-structure]] (1)
== Asciidoc 記法

[[introduction]] (2)
== はじめに

<<project-structure,章の冒頭>> (1)
<<Chapter01/index.adoc#introduction,はじめに>> (2)

https://h1romas4.github.io/asciidoctor-gradle-template/index.html[AsciidoctorとGradleでつくる文書執筆環境]

[quote, Asciidoctor Documentation Site]
____
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.
____

image::2023-06-30-12-11-56.png[pdfwidth=70%, width=600px]

.VS Code の IntelliSense (1)
[caption="画像. "] (2)
image::2023-09-14-18-52-05.png[pdfwidth=70%, width=70%]

[source, javascript]
[caption=""]
.JavaScript ソースコードのシンタックスハイライトの例
----
function hello() { // <1>
    console.log("Hello, World!"); // <2>
}
----

<1> 関数定義
<2> コンソールに ``Hello, World`` を出力

function hello() { (1)
    console.log("Hello, World!"); (2)
}

menu:メニュー[File > Open]

btn:[OK] ボタン

[source, rust]
----
include::source/hello.rs[]
----

fn main() {
    println!("Hello, world!");
}

[format="csv",cols="1,2"]
[frame="topbot",grid="none"]
[caption=""]
.表形式の例1
|======
キー1,バリュー1
キー2,バリュー2
キー3,バリュー3
|======

[cols="1,2", options="header", stripes="none"]
[frame="topbot"]
[caption=""]
.表形式の例2
|======
|カラム名1
|カラム名2

|キー1
|バリュー1

|キー2
|バリュー2
|======

[cols="1,2a", options="header"]
[frame="topbot"]
|======
|通常カラム
|Asciidoc 形式付きカラム

|
. リスト1
. リスト2
|
. リスト1
. リスト2
|======

. 手順1
. 手順2
+
リスト継続1
+
image::2023-06-30-15-39-26.png[pdfwidth=60%, width=60%]
. 手順3
.. 箇条書きのネスト1
... 箇条書きのネスト2
*** 順序なしリスト1
*** 順序なしリスト2

NOTE: メモ

TIP: チップス

IMPORTANT: 重要

WARNING: 警告

CAUTION: 注意

[NOTE]
====
改行を含む脚注です。

吾輩は脚注である。名前はまだ無い。
====

<<<

'''

対応 OS::
    macOS、Linux、Windows 対応
対応 JDK::
    11 、17、21 の各 LTS バージョン

.コラム
****
ブロックを使ってコラム表現を挿入します。

吾輩はコラムである。名前はまだ無い。
****

// TODO: さらに Asciidoc 記法を追加していくこと。

[plantuml, diag-sequence-sample2, svg, pdfwidth=70%, width=70%]
[caption=""]
----
@startuml diag-sequence-sample2
skinparam monochrome true
hide footbox
participant "ブラウザ\n閲覧者" as browser
participant "baserCMS" as basercms
entity データーベース as Entity
participant "ブラウザ\n管理者" as admin
== コンテンツ閲覧==
browser -> basercms: 表示リクエスト
basercms -> basercms: リクエスト処理
basercms -> Entity: SQL 発行
Entity -> basercms: コンテンツ取得
note right of basercms: バックエンド処理とフロントエンド向け処理（HTML生成）を\n同じシーケンスで行う
basercms -> basercms: テーマテンプレート処理
basercms -> browser: HTML/CSS 返却
== コンテンツ管理==
admin -> basercms: 管理画面リクエスト
basercms <-> Entity: データーベース更新
basercms -> admin: 管理画面 HTML/CSS 返却
@enduml
----

[plantuml, diag-salt-sample1, svg, pdfwidth=30%, width=280px]
[caption=""]
----
' https://github.com/iconic/open-iconic/
@startsalt diag-salt-sample1
{
{T
 + <&folder> wp-admin
 + <&folder> wp-content
 ++ <&folder> themes
 +++ <&folder> my-theme   | 新規作成
 ++++ <&file> style.css   | 新規作成
 ++++ <&file> index.php   | 新規作成
 ++ <&folder> uploads
 + <&folder> wp-includes
 + <&file> .htaccess      | 自動作成
 + <&file> index.php
}
}
@endsalt
----

[plantuml, math-sample1, svg, pdfwidth=70%, width=70%]
[caption=""]
----
@startmath math-sample1
f(t)=(a_0)/2 + sum_(n=1)^ooa_ncos((npit)/L)+sum_(n=1)^oo b_n\ sin((npit)/L)
@endmath
----

[ditaa, diag-ditaa-block, svg, shadows=true, separation=true, pdfwidth=70%, width=70%]
[caption=""]
----
+---------------------------------+
|     baserCMS Plugin, Theme      |
+----------------------------+    +
| cPNK   baserCMS Core       |    |
+----------------------------+----+
|            CakePHP              |
+---------------------------------+
|             MySQL               |
+---------------------------------+

/-------------+-------------\
|cRED RED     |cBLU BLU     |
+-------------+-------------+
|cGRE GRE     |cPNK PNK     |
+-------------+-------------+
|cBLK BLK     |cYEL YEL     |
\-------------+-------------/
----

[ditaa, diag-ditaa-block-2, svg, shadows=true, separation=true, pdfwidth=70%, width=70%]
[caption=""]
----
/--------------------------------\
|                                |
|          program.wasm          |
|   ^                        |   |
+---|------------------------|---+
|   |                        v   |
|       WebAssembly Runtime      |
|   ^                        |   |
+---|------------------------|---+
|   |                        v   |
|         clang/libc/SDK         |
|                            |   |
+----------------------------|---+
|                            v   |
| cGRE       Hardware            |
|                                |
\--------------------------------/
----

[ditaa, diag-ditaa-memory-map, svg, shadows=true, separation=false, pdfwidth=70%, width=70%]
[caption=""]
----
0000H +-------------+ +-------------+ 0000H
      | cGRE        | |             |
      |             | |             |
      |             | |             |
      |             | |  BASIC ROM  |
      |             | |             |
      |             | |             |
      |             | |             |
8000H +- - - - - - -+ +-------------+ 8000H
      |  Main RAM   |
      |             |
      |             |
      |             |
      |             |
C000H +- - - - - - -+ +-------------+ C000H
      |             | |             ++
      |             | | VRAM 0,1,2  |++
F3C8H +-------------+ | BANK SELECT |||
      |  TEXT VRAM  | |             |||
FFFFH +-------------+ ++------------+||
                       ++------------+|
                        +-------------+
----

[plantuml, diag-nwdiag-network1, svg]
----
@startuml diag-network1
<style>
nwdiagDiagram {
    FontSize 14
    group {
        BackGroundColor cadetblue
    }
}
</style>

nwdiag {
    internet [shape = cloud];
    internet -- router;
    router [address = "210.x.x.x"];
    network LAN {
        address = "192.168.0.0/24"
        router [address = "192.168.0.1"];
        thinkpad-p14s [address = "192.168.0.w"];
        minis-um690 [address = "192.168.0.x"];
        xbox-series-s [address = "192.168.0.y"];
        atom-server [address = "192.168.0.z", shape = database"]
    }
    network WLAN {
        address = "172.16.15.0/24"
        router [address = "172.16.15.1"];
        group {
            description = モバイル
            iphone01 [address = "172.16.15.w"];
            ipad01 [address = "172.16.15.x"];
        }
        group {
            color = "#add8e6"
            description = 据え置き
            fire01 [address = "172.16.15.y"];
            echo01 [address = "172.16.15.z"];
        }
    }
}
@enduml
----

[plantuml, diag-c4-component-sample1, svg]
[caption=""]
----
@startuml diag-c4-component-sample1
!include <C4/C4_Container>
!include <office/users/users.puml>
!include <office/Servers/database_server>
!include <office/Servers/file_server>
!include <office/Servers/application_server>
!include <office/Concepts/service_application>
!include <office/Concepts/firewall>
!include <office/Devices/workstation>

skinparam linetype ortho
top to bottom direction
'left to right direction
HIDE_STEREOTYPE()

AddContainerTag("user", $bgColor="#5f9ea0", $shadowing="true")
AddContainerTag("linux", $sprite="application_server", $bgColor="#dcdcdc", $fontColor="#000000", $borderColor="#696969", $sprite="file_server", $shadowing="true")

Person(user_person, "ウェブサイト\n閲覧者", $sprite="users", $tags="user")

System_Boundary(system_1, "Application") {
    Container_Boundary(bound_backend_1, "Backend") {
        ContainerDb(rel_db, "Database", "MySQL 8.0", $sprite="database_server", $tags="linux")
        Container(filesystem, "File System", "ext4", $tags="linux")
        Container(batch, "Bacth Server", "Java, Spring Boot", $tags="linux")
    }
    Container_Boundary(bound_frontend_1, "Frontend") {
        Container(load_balancer, "Load balancer", "nginx", $sprite="application_server", $tags="linux")
        Container_Boundary(bound_cluster_1, "Cluster") {
            Container(web_app_1, "Web Application", "Java, Spring Boot", $tags="linux")
            Container(web_app_2, "Web Application", "Java, Spring Boot", $tags="linux")
        }
    }
    Person(user_admnin, "アプリケーション\n管理者", $sprite="workstation", $tags="user")
}

Lay_R(user_person, system_1)
Lay_D(user_admnin, batch)
Lay_R(bound_backend_1, bound_frontend_1)

Lay_R(load_balancer, web_app_1)
Lay_D(web_app_1, web_app_2)
Lay_D(rel_db, filesystem)
Lay_R(rel_db, batch)

AddRelTag("rel_line", $textColor="black", $lineColor="#696969", $lineStyle=BoldLine())

Rel_R(user_person, load_balancer, "https", $tags="rel_line")
Rel_R(load_balancer, web_app_1, "http", $tags="rel_line")
Rel_R(load_balancer, web_app_2, "http", $tags="rel_line")

Rel_R(bound_cluster_1, rel_db, "JDBC", $tags="rel_line")
Rel_R(bound_cluster_1, filesystem, "NFS", $tags="rel_line")

Rel_R(batch, rel_db, "JDBC", $tags="rel_line")
Rel_R(user_admnin, batch, "ssh", $tags="rel_line")

@enduml
----

[plantuml, diag-timing-sample1, svg, pdfwidth=90%, width=80%]
----
@startuml diag-timing-sample1
scale 40 as 150 pixels
clock "Clock" as clk with period 1
binary "CS" as CS
binary "WR" as WR
binary "RD" as RD
binary "A0" as A0
binary "A1" as A1
binary "IC" as IC
concise "DataBus" as DB

@0 as :start
@20 as :set_data_bus_1
@30 as :set_addr_1
@40 as :write_start_1
@60 as :write_end_1

@:start
IC is high
CS is high
WR is high
RD is high
A0 is low
A1 is low

@:set_data_bus_1
DB is "0xff"
DB -> WR@+20
note bottom of DB : MCP23S17 GPIOB から

@:set_addr_1
A0 is high
A1 is low

@:write_start_1
CS is low : WR/CS 同時に設定
WR is low
DB@40 <-> @60 : {10 us}

@:write_end_1
CS is high
WR is high

highlight 40 to 60 #SkyBlue;line:DimGrey : 書き込み
@enduml
----

[plantuml, diag-mindmap-sample1, svg]
[caption=""]
----
@startmindmap diag-mindmap-sample1
<style>
mindmapDiagram {
    FontSize 18
    .rose {
        BackgroundColor #ffbbcc
    }
}
</style>
* ウェブブラウザー
** HTML
** CSS
** JavaScript
** <&star> WebAssembly <<rose>>
@endjson
----

./gradlew docs (1)

.\gradlew docs (1)

$ ./gradlew tasks
..snip..
Documentation tasks
-------------------
asciidoctor - Generic task to convert AsciiDoc files and copy related resources
asciidoctorPdf - Convert AsciiDoc files to PDF format
checkPdfInfo - Utility task to check PDF document metadata
checkSyncImage - Utility to check the consistency of Asciidoc text and file system images
cleanDocs - Task to delete all files and directories under docs/
docs - Generate HTML/PDF documents from Asciidoc documents and output them under docs/
..snip..

./gradlew docs

asciidoctor {
    dependsOn asciidoctorGemsPrepare (1)
    baseDir file('src/docs/asciidoc') (2)
    sources {
        include 'index.adoc' (3)
    }
    resources {
        from('src/docs/asciidoc') {
            include 'Chapter*/images/*' (4)
        }
    }
    asciidoctorj {
        attributes 'stylesdir': '@style',
            'stylesheet': 'asciidoctor.css' (5)
    }
}

asciidoctorPdf {
    dependsOn asciidoctorGemsPrepare (1)
    baseDir file('src/docs/asciidoc') (2)
    fontsDir file('src/docs/asciidoc/@font') (3)
    sources {
        include 'index.adoc' (4)
    }
    asciidoctorj {
        attributes 'pdf-themesdir': "@style",
            'pdf-theme': 'pdf-theme.yml' (5)
    }
}

asciidoctorj {
    version = '2.5.6' (1)
    modules {
        diagram.use()
        diagram.version '2.2.8' (2)
        pdf.version '1.6.2' (3)
    }
    requires = [ (4)
        'asciidoctor-diagram',
        'prawn_svg_font_patch', (5)
        'asciidoctor/nabetani', (6)
    ]
    attributes 'source-highlighter': 'rouge' (7)
}

tasks.register('docs', Copy) {
    dependsOn(asciidoctor, asciidoctorPdf, cleanDocs)
    group 'documentation'
    description 'Generate HTML/PDF documents from Asciidoc documents and output them under docs/'
    from 'build/docs/asciidoc/index.html' (1)
    from 'build/docs/asciidocPdf/index.pdf' (1)
    from('build/docs/asciidoc/') { (2)
        include 'Chapter*/images/*'
    }
    into 'docs/'
}

tasks.register('cleanDocs', Delete) {
    group 'documentation'
    description 'Task to delete all files and directories under docs/'
    // docs/ ディレクトリは残しその配下のファイルとディレクトリを全て削除
    delete file('docs/').listFiles()
}

./gradlew -q checkPdfInfo

Content-Type: application/pdf
access_permission:assemble_document: true
access_permission:can_modify: true
access_permission:can_print: true
access_permission:can_print_degraded: true
access_permission:extract_content: true
access_permission:extract_for_accessibility: true
access_permission:fill_in_form: true
access_permission:modify_annotations: true
dc:creator: https://github.com/h1romas4/asciidoctor-gradle-template
dc:format: application/pdf; version=1.4
dc:title: AsciidoctorとGradleでつくる文書執筆環境
dcterms:created: 2023-10-04T06:17:20Z
dcterms:modified: 2023-09-25T08:40:46Z
pdf:PDFVersion: 1.4
pdf:annotationSubtypes: Link
pdf:annotationTypes: null
pdf:charsPerPage: 0
pdf:containsDamagedFont: false
pdf:containsNonEmbeddedFont: false
pdf:docinfo:created: 2023-10-04T06:17:20Z
pdf:docinfo:creator: https://github.com/h1romas4/asciidoctor-gradle-template
pdf:docinfo:creator_tool: Asciidoctor PDF 1.6.2, based on Prawn 2.4.0
pdf:docinfo:modified: 2023-09-25T08:40:46Z
pdf:docinfo:producer: https://github.com/h1romas4/asciidoctor-gradle-template
pdf:docinfo:title: AsciidoctorとGradleでつくる文書執筆環境
pdf:encrypted: false
pdf:hasCollection: false
pdf:hasMarkedContent: false
pdf:hasXFA: false
pdf:hasXMP: false
pdf:num3DAnnotations: 0
pdf:overallPercentageUnmappedUnicodeChars: 0.0
pdf:producer: https://github.com/h1romas4/asciidoctor-gradle-template
pdf:totalUnmappedUnicodeChars: 0
pdf:unmappedUnicodeCharsPerPage: 0
xmp:CreatorTool: Asciidoctor PDF 1.6.2, based on Prawn 2.4.0
xmpTPg:NPages: 77

./gradlew -q checkSyncImage

::Unused images:
Chapter01/images/unused-image-1.png
Chapter03/images/unused-image-1.png
::Image not found:
Chapter01/images/2023-09-17-13-43-06.png

tasks.register('checkSyncImage', SyncImageTask) {
    group 'documentation'
    description 'Utility to check the consistency of Asciidoc text and file system images'
    // 起点の文書ディレクトリ
    baseDir = file('src/docs/asciidoc')
    // 起点の Asciidoc 文書（include を辿る）
    index = 'index.adoc'
    // ファイルシステム上で画像として認識する拡張子
    // 文書内で image:: として使われているファイル全ての拡張子を設定すること
    imageExt = ['png', 'jpg', 'jpeg', 'svg']
}