# Adoc使用説明書簡易　(Asciidocの表現を試す)

## 1. はじめに

AsciiDocの記述方法でよくつかうものを記載します。さらに多くの記述を使いたい場合は以下を参照してください。

- Asciidoctor 文法クイックリファレンス(日本語訳)

- Asciidoctor 文法クイックリファレンス(原文)

- ユーザーマニュアル(英語)

- Qiita 細かい設定がよくわかる！

- ビルドインアトリビュートの一覧

## 2. コメント類

コメント部分は、最終出力から除外されます

     // 			:行頭でその行はコメントになる
     ////から////	:ブロック内がすべてコメント

## 3. 文字飾り

基本

`*_`でサンドイッチすることで表現。空白含む場合は **単語A 単語B** の様に２個ずつつけるとよい

結果 | 記述
--- | ---
太字の語句 イタリック 太字のイタリック `モノスペース` |
    *太字の語句*
    _イタリック_
    *_太字のイタリック_*
    `モノスペース`

Table 1. 少し拡張(アンダーラインなど)
結果 | 記述
--- | ---
アンダーライン 通常文字 vs 小さい文字 vs 大きい文字 取り消し線 |
    [.underline]#アンダーライン#
    通常文字 vs [.small]#小さい文字# vs [.big]#大きい文字#

    [.line-through]#取り消し線#

## 4. 見た目(ボタンとアイコン)

記述 | 説明
--- | ---
    kbd:[Ctrl+C]
| `Ctrl`+`C`, `Ctrl`+`Shift`+`V`
    btn:[ボタン]
| ボタン,OK,CANCELなど
    {cboxOn}/{cboxOff}
| `[✔]`/`[ ]` 以下の事前マクロ定義必要 `:cboxOn: pass:normal[``{startsb}&#10004;{endsb}``]` `:cboxOff: pass:normal[``{startsb}{nbsp}{endsb}``]`
    {cboxgOn}/{cboxgOff}
| `✔`/`` 以下の事前マクロ定義必要 `:cboxgOn: kbd:[&#10004;]` `:cboxgOff: kbd:[{nbsp}]`
    menu:ファイル[保存]
| ファイル 保存 階層化:`>`でサブメニュー化 menu:ファイル[保存 > Sub > A] → ファイル 保存 Sub A
{OK} | 事前に定義 `:OK: pass:[<span style="font-family: monospace">&#x1F600;</span>&#x20;]` 😀 アイコンはユニコードで色々定義,Unicodeの絵文字 😍(`&#x1F60D;`)、🙅(`&#x1F645;`)、🌈(`&#x1F308;`) などなど

## 5. セクション（章節）

`=␣<セクション>`で始める行がセクションになる。セクションの区切りには空白行が必要。=の数でセクションレベルが決まる

    = ドキュメントのタイトル
    == 章最初のタイトル
    === 節のタイトル
    ==== 文節のタイトル
    ===== さらにその下タイトル
    ====== さらにさらにタイトル
    == 章次のタイトル

## 6. 箇条書き

- `*␣<項目>`、`-␣<項目>`で始める。異なる記号を使えば、階層的に表現できる

- 形状変更は`[square]`,`[circle]`,`[disc]`を指定

- チェックボックスは`*␣[ ]␣ <項目>` で []の中に[x]or[*]or[ ]

Table 2. 箇条書き(項目)
結果 | 記述
--- | ---
項目1 サブ項目1 サブ項目2 サブ項目の中に複数行に渡る大きな大きなブロックを記述できる 項目2 形状変更 square circle disc チェックボックス checked also checked not checked |
    - 項目1
    	* サブ項目1
    	* サブ項目2
    +
    --
    サブ項目の中に複数行に渡る大きな大きな大きな
    ブロックを記述できる
    --
    - 項目2
    形状変更
    [square]
    * square
    [circle]
    * circle
    [disc]
    * disc
    チェックボックス
    * [*] checked
    * [x] also checked
    * [ ] not checked

## 7. 箇条書き（数字）

`.␣<項目>`（ピリオド）で始める。階層構造は`…​␣`と連ねる。
番号は[arabic]/[decimal]/[loweralpha]/[upperroman]などで階層ごとに指定

Table 3. 箇条書き(数字)
結果 | 記述
--- | ---
項目1 項目1のタイトル サブ項目の中にブロックを記述できる サブ項目1 サブ項目2 サブサブ1 サブサブ2 サブ項目の中にブロックを記述できる 項目2 |
    . 項目1
    +
    --
    サブ項目の中にブロックを記述できる
    --
    	.. サブ項目1
    	.. サブ項目2
    [decimal]
    	... サブサブ1
    	... サブサブ2

    +
    --
    サブ項目の中にブロックを記述できる
    --

## 8. ラベル

- <ラベル名>::(後ろのコロン２つ）でラベルをつける。コロンを増やせば階層化できる。

- [horizontal]指定で一行目から、行が開始される

Table 4. ラベル
結果 | 記述
--- | ---
第一項 第一項の定義 さらにそのサブ サブの内容 |
    第一項::
    	第一項の定義
    	さらにそのサブ:::
    		サブの内容

## 9. ブロックラベル

`.ブロックラベル`(ドット）でラベルをつける。スペースは不要。箇条書き（数字）になってしまう。

## 10. ブロック

- 以下の記号４文字のキーワード行で囲む。それぞれ動作、意味が異なる

- $$～ $$で囲むとパスされる →エスケープ方法

1 | `--` | (ハイフンx2) | オープンブロック。 汎用ブロック。オープンブロックはpassとtableを除き、他のブロックとして機能できます。
2 | `----` | (ハイフンx4) | コードブロック。コードもしくはファイルの表示(リスティング)
3 | `....` | (ドット) | リテラルブロック。書いたままに表示させたいとき。
4 | `====` | (イコール) | サンプルブロック。 通常で枠ができるフォーマット。[caption="キャプション名"]で制御。`=` のみで、ナンバリングもキャプションも除去される様子
5 | `++++` | (プラス) | インラインブロック。変換せずにHTML出力,パススルー/インライン,バックエンドのマークアップの書式を記述する
6 | `****` | (アスタ) | サイドバーブロック
7 | `____` | (アンダーバー) | ブロッククウォート（引用かな?）

コードブロックに指定できる言語

  `C,C++,HTML,Python,Ruby,JavaScript,JSON,Java,XML,YAML ,Clojure,CSS,Delphi,diff,ERB,Go,Groovy,HAML,Lua ,PHP,Sass,SQL,Taskpaper`

結果 | 記述
--- | ---
JavaScript例（タイトル）
    var a = "test";
    echo(a,b);
     [source,JavaScript]
     .JavaScript例（タイトル）
     ----
     var a = "test";
     echo(a,b);
     ----

## 11. 警告、重要、情報などのアイコン

適用するには属性 `:icons: font`が必要

結果 | 記述
--- | ---
| ノート(NOTE)
| 警告(WARNING)
| 重要(IMPORTANT)
| チップス(TIP)
| 注意(CAUTION)
    NOTE,WARNING,IMPORTANT,TIP,CAUTION

    単行の場合:

    NOTE: <内容>

    ブロックの場合: (サンプルブロックを使う)

    [NOTE]
    ====
    <内容>
    ====

■カスタムアイコンの利用方法

PNGもしくはSVGデータとしてこれらのアイコンを変更することができます。iconsフォルダにファイル名"NOTE,WARNING,IMPORTANT,TIP,CAUTION"で、拡張子を`.svg`もしくは`.png`のファイルを配置すればよい。

Table 5. アイコンの属性を変更
    :icons: image
| アイコンのタイプをイメージに変更
    :iconsdir: ./icons
| アイコンの配置場所をiconsに変更（未設定だと{imagesdir}/icons)
    :icontype: svg
| 画像の種類を指定 svg or png

| 属性変更はファイルの先頭がよい。途中で切り換えるとうまくいかない場合があった。

※その他方法

  以下でも一時的に変更することも可能。拡張子は`:icontype: xxx`と同じなら 拡張子を省略可能です

  [NOTE, icon=NoteCustom.svg ]
  ====
  カスタムNOTEアイコン
  ====

## 12. 区切り線

`---`（ハイフン）3個のみ。

Table 6. 区切り線
結果 | 記述
--- | ---
| `---`

## 13. 改行

- `␣+`で繋ぐ。

- もしくは`[%hardbreaks]`で段落全体で改行を有効にする（段落毎にリセットされる）。ドキュメント全体で設定するなら`:hardbreaks:`属性をつけるとよい。個別の解除は`{set:hardbreaks!}` 。

Table 7. 改行
結果 | 記述
--- | ---
１行目 ２行目 |
    １行目 +
    ２行目

## 14. 段落 揃え

- `[.text-left]`,`[.text-right]`,`[.text-center]`で調整する

- `[.text-justify]`はよくわからない

- `[align=xxxx]`、 xxxx=left,center,right,…​でもよい

結果 | 記述
--- | ---
右寄せ センター 左 行内で部分的右 [右] |
    [.text-right]
    右寄せ
    [.text-center]
    センター
    [.text-left]
    左
    行内で部分的右 [.right]##[右]##

This paragraph is aligned right

This paragraph is aligned center

This paragraph is aligned left. This paragraph is aligned left. This paragraph is aligned left. This paragraph is aligned left. This paragraph is aligned left. This paragraph is aligned left. This paragraph is aligned left.

This paragraph is justified, which is the default.This paragraph is justified, which is the default.This paragraph is justified, which is the default.This paragraph is justified, which is the default.

## 15. コメント

    // コメント行

    ////
    	コメントブロック
    ////

## 16. エスケープ方法

記述 | 表現
--- | ---
$$ ～ $$で囲む | 通常文字になる
+++～+++で囲む | HTML制御になる(インライン要素)
pass:[～]で囲む | HTML制御になる(インライン要素、同上）
\(backslash) | 次の文字の制御のみキャンセル。\*bold*や\{lt}など
※ その他は特殊記号で記載すること。

## 17. 特殊記号

特殊記号は`{}`を使う。もしくは`&#<10進数>;` or `&#x<10進数>;`など。

特殊記号の一覧
記号 * ({}で囲む) | 表現
--- | ---
dollar | $(ドル): &#36; or &#x24; ※これは存在しないので、自身で`:dollar: &#36;`を定義すること
sp | `` スペース１文字
nbsp | ノンブランクスペース文字
zwsp | 幅無スペース
quot | `"` (ダブルクウォート)
apos | `'` (アポストロフィー}
backtick | ``` (バッククウォート)
lsquo | `‘`(開始シングルクウォート)
rsquo | `’`(終了シングルクウォート)
ldquo | `“`(開始ダブルクウォート)
rdquo | `”`(終了ダブルクウォート)
deg | `°`(角度)
plus | `+`(プラス)
brvbar | `¦`
vbar | `|`(論理和)
amp | `&` (アンパサンド)
lt | `<` (smaller than)
gt | `>` (gretar than)
startsb | `[` (開始カギカッコ）
endsb | `]` (終了カギカッコ)
caret | `^` (キャレット)
asterisk | `*` (アスタリスク)
tilde | `~` (チルダ)
backslash | `\` (バックスラッシュ)
two-colons | `::` (2つのコロン)
two-semicolons | `;;` (2つのセミコロン)
cpp | ``C`` (C?)
wj |
blank |
empty |

## 18. 色

`[色 色-background]#コンテンツ#`で指定する

赤いコンテンツ、黄色の背景 ← `[red yellow-background]## 赤いコンテンツ、黄色の背景 ##`

- 色名の一覧はwikiのWebColor一覧から取れる

  HTML color names
  この内の基本の16種の色のみ定義されている

  asciidoctor-pdfは以下の定義みたい(rubyの中)

    c:\Ruby24\lib\ruby\gems\2.4.0\gems\asciidoctor-2.0.10\data\stylesheets
    asciidoctor-default.css

  vs-codeプラグインは以下

    %USERPROFILE%\.vscode\extensions\asciidoctor.asciidoctor-vscode-2.8.3\media\
    asciidoctor-default.css

  一覧

    ■■■■■■■ aqua `([aqua]##■...■## aqua )` | ■■■■■■■ black | ■■■■■■■ white
    ■■■■■■■ fuchsia | ■■■■■■■ green | ■■■■■■■ lime
    ■■■■■■■ maroon | ■■■■■■■ navy | ■■■■■■■ olive
    ■■■■■■■ purple | ■■■■■■■ red | ■■■■■■■ silver
    ■■■■■■■ teal | ■■■■■■■ yellow | ■■■■■■■ yellow

※色を拡張したければインラインで定義するか、CSSを拡張するかです。

Example 1. インラインで拡張

    :SpanRed: pass:[<span style="color:#FF00FF;background-color:#00FFFF">]
    // Spanの終了は共通{SpanEnd}
    :SpanEnd: pass:[</span>]

このように定義しておいて
{SpanRed} 適当な文字列 {SpanEnd} → 適当な文字列

Example 2. CSSで拡張

未記載

The application is called MyApp2.

example-caption=Example
figure-caption=Figure

Red `sum_(i=1)\^n i=(n(n+1))/2`$ ←AsciiMathML formula

pass_attribute=the 'Example' ※ passすると[%hardbreaks]などリセットされちゃう

lang={lang}
menu=File Save
keyboad=`F11`
docdate=2021-03-03
user-home=C:\Users\AA004035

## 19. 独自のマクロみたいなの

1. HTML文法における `id` / `class` 指定の対応

    <div id="baz" class="foo bar">

idは要素そのもののユニークなID、classはCSSの指定でスタイルを指定可能。
これは以下の２通りで表現可能
`[#<ID>.<CLASSList1>.<CLASSList1>]` ⇐ これでよいと思う
もしくは
`[[<ID>]]`
`[role="<CLASSList1> <CLASSList1>]`

    	[#baz.foo.bar]
    	----
    	block
    	----
    もしくは
    	[[baz]]
    	[role="foo bar"]
    	----
    	block
    	----

xabc

{ZZ} `abc`

独自のasciidocマクロを定義する方法

    {set:cellbgcolor:gray}
    [grid=none, frame=none]
    |===
    | X >| Y
    |===
    {set:cellbgcolor!}

X | Y

{

a #FF0000
Cell data

## 20. リンク

WebページなののURLへのリンク。<url>[リンク表示]
Windowsファイルパスの場合は、link:<path>[リンク表示]

santanaのCMM

Table 8. タイトル例
結果 | 記述
--- | ---
チートシート英語 |
    https://asciidoctor.org/docs/user-manual/[チートシート英語]

## 21. イメージリンク

- 通常

      image::im.JPG[代替テキスト,x,y,.... align="right/left/center"]

      x,yは表示ピクセル数を指定するか
      もしくは%を用いて実際の表示幅からの割合表示が可能
      image::im.JPG[代替テキスト,"50%"]
      また明示的に記載も可能(width,height)
      image::im.JPG[代替テキスト,width="50%"]

- インライン（行内)

      		image:im.JPG[代替テキスト]

行でをいれる

## 22. テーブル

テーブルの表現 .タイトル例

結果 | 記述
--- | ---
c1 | c2
--- | ---
data1 | data2
    [cols="1a,2a",options="header"]
    |===
    |c1        |c2
    |data1     |data2
    |===
その他の細かい記述方法 | *まだ* cols= 番号で列の幅比率 a:adoc書式、l(エル):リテラル書式

| テーブル内でテーブルを使う場合(Nested Table)は、|の代わりに!(ビックリマーク)を使う。それでも完全で無い。

寄せの設定

      [cols="<,>,^"]

  1列目: 左寄せ | 2列目: 右寄せ | 3列目: 中央寄せ

寄せの設定2

      [cols="{左右}.{上下}, {左右}.{上下}, {左右}.{上下}, ..."]
      [cols="{左右}.{上下}, {左右}.{上下}, {左右}.{上下}, ..."]

  [cols="<.<,"]は 1列目: 左寄せ + 上寄せ | 2列目1 2列目2

  [cols=">.>,"]は 1列目: 右寄せ + 下寄せ | 2列目1 2列目2

  [cols="^.^,"]は 1列目: 中央(左右) + 中央寄せ(上下） | 2列目1 2列目2

寄せの設定3

    行定義|の左側に<,>,^を記述する方法もある。1列ごとに改行して定義する。
    ※ヘッダ行とデータ行の間に改行が必要
    |item
    <|item
    >|item
    <.^|item

列幅の設定

      以下の自動幅autowidth:OK,様々指定方法がある。どれか一つ。
      [options="header,autowidth"]
      [options="autowidth"]
      [%autowidth]
      [%header%autowidth]
      ["%autowidth",cols="a,a",options="header"]
      ※ a,100aはadoc2pdf変換で失敗 1:40で失敗,最大39でいけた

## 23. テーブルを段組に使う技

| 「イメージを左、その説明を右」ぐらいの用途。テーブルにテーブルをいれるのが難しいなど、全表現をいれるのに苦労するのでやめたほうがいい。

テーブルを段組みに使う（2分割）
画像タイトル名
テーブルにテーブルを入れている
head a | head b
--- | ---
a | BBBBBB
| これが二つ目のブロックになる ラベル ラベル

表現は以下のとおり

    	[title="ｘｘｘ",caption="",cols="a,a",frame="none",grid="all"]
    	|================================
    	|
    	// 左段落
    	[caption="",title="画像タイトル名",grid="all"]
    	image::im.JPG[代替テキスト,100,align="center"]

    	[caption=""]
    	.テーブルにテーブルを入れている
    	[cols="1a,2a", options="header"]
    	// [frame="none",grid="none"]
    	!=========
    	!head a	! head b
    	!a		! BBBBBB
    	!=========

    	|
    	// 右段落
    	--
    	.これが二つ目のブロックになる
    	. ラベル
    	. ラベル
    	--
    	|================================

## 24. テキストの折り畳み

[%collapsible]で記述する

    .タイトル
    [%collapsible]
    ====
    ～ ※[%collapsiblee%open]と指定すると初期状態で展開される
    ====

折り畳みテキスト

折り畳み内容

## 25. インクルード

`include::../../hoge.adoc[]`で別のAsciiDocファイル指定する。 `[]`内にオプションを指定できる

    include::path[leveloffset=offset,lines=ranges,tag(s)=name(s),indent=depth,opts=optional]

leveloffset= +n

  セクション階層を変更する。＋の数値を指定することで、階層を下げる。マージしたadocのセクション階層と、include先のadocも単独で参照するようなケースに有効です

## 26. アンカー(内部参照)

- 内部参照へのリンクを表現する。 [[アンカー名 ]]で設定し、<<アンカー名 >>で参照する。設定された直後の章名がアンカー表示名になる。

- アンカー参照時の表示名を別名にしたいときは、設定箇所で[[アンカー名,表示名]]とする。

- デフォルトで、章は、アンカーが設定されており,<<_章名>>(先頭にアンダーバー)で参照できる。vscodeプレビューは日本語でリンクに飛べなかった？

例.

イメージリンク

## 27. 属性設定のサンプル

# その他

1. (済)アンカー(内部参照)

2. 色名

3. 本

## 1. オリジナル先のリンクをしっかりしておこう

トップページ_Asciidoctor Documentation

Syntax-quick-ref

writers-guide

diagram

style-guide(draft)

macro defineがあるんですけどね

# Nested Tables

Nested tables

## 1. Nested tables

To nest a table in a table we must use `!` as table separator instead of `|`. Also the type of the column or cell must be set to `a` so Asciidoc markup is processed.

Col 1 | Col 2
--- | ---
Cell 1.1 | Cell 1.2
Cell 2.1 | Cell 2.2
Col1 | Col2
--- | ---
C11 | C12

MyAp2

MyApp2

CPUここが長くなってしまうとどうする | The brain of the computer. a b
Hard drive | Permanent storage for operating system and/or user files.
RAM | Temporarily stores information the CPU uses during operation.

+ .Q and A

1. アスキードックとは？

   ルビーで実装されたドキュメントフォーマットである。

2. What is the answer to the Ultimate Question?

   42 +

| It’s possible to use Unicode glyphs as admonition icons. WARNING: It’s possible to use Unicode glyphs as admonition icons.

| It’s possible to use Unicode glyphs as admonition icons. WARNING: It’s possible to use Unicode glyphs as admonition icons.

ruby, asciidocto

\$sqrt(4) = 2\$
\$sqrt(4)\$

latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon

    An open block can be an anonymous container, or it can masquerade as any other block. pass:[dfsa]

An open block can be an anonymous container, or it can masquerade as any other block. dfsa

.

# まとめ

## 1. タイトル

`。。。`（。。。）

Table 9. タイトル例
結果 | 記述
--- | ---
<左列のレンダリング結果> |
    <右側列のAsciiDocの記述>

# 属性関係の設定

脱Word、脱Markdown、asciidocでドキュメント作成する際のアレコレ

HTMLのスタイル(CSS)を設定する

    // :stylesdir:   // どこでも有効になる様子
    //:stylesdir:でCSSのフォルダを:stylesheet:でCSSファイルを指定可能

    // html-style.adoc
    // :stylesdir: stylesheets/
    // :stylesheet: asciidoctor-default.css

    // pdf-style.adoc
    // :pdf-style: themes/default-theme.yml

1. stylesdir=.

2. stylesheet=

3. pdf-style={pdf-style}

| 以下のパスを書き換えた：1.2emに。 1.0が今の表示の様子。 C:\Users\AA004035\.vscode\extensions\joaompinto.asciidoctor-vscode-2.7.6\media\asciidoctor-editor.css
    	.literalblock pre,
    	.listingblock>.content>pre:not(.highlight),
    	.listingblock>.content>pre[class="highlight"],
    	.listingblock>.content>pre[class^="highlight "] {
    		font-size: 1.2em;	/*　松尾2em;200%でも変更できる*/
    		/* background: #f7f7f8 これ消したら消えた*/
    	}

## 1. テストコード

    [IMPORTANT]
    ====
    本文の記載
    ====

    単行記述は以下：

    IMPORTANT: 本文の記載

結局これが一番わかり易いかも .AsciiDocのチートシート AsciiDocのチートシート

## 2. テストコードの終わり

# 付録

## 1. 属性パラメータ

- :Keywords:␣ で内部パラメータ定義。キャンセルは`:Keywords!:` or `:!Keywords:`。

- その他 ビルドインアトリビュートの一覧

記述 | 説明
--- | ---
    :toc: left
     left,right,macro(別途 toc::[]で場所指示）
    :imagesdir: ./
     イメージDIR
    :lang: ja
     言語指定
    :doctype: book
    	article/book/manpage/inline(不明)
    :toc-title: 目次
    	目次のタイトル
    :toclevels: 3
    	目次の番号レベル
    :sectnums:
    	セクションに番号をつけるか?
    :sectnumlevels: 4
    	セクションの番号レベル
    :sectlinks:
    :icons: font
    :example-caption: 例
    	例ブロック($$====$$)のキャプション
    :table-caption: 表
     テーブルブロック($$====$$)のキャプション
    :experimental:
    	*マクロを有効するにる

Table 10. 完全な例
     // 属性定義
    :experimental:
     // :module:    モジュール名
    :Author:    著者名
    :Email:     メールアドレス
    :Date:      日付(2020/01/20)
    :Revision:  Rev.1
    :lang: ja
    :doctype: book
    :description:
    :docname: ドキュメント名

     // 見出し設定
    :sectnums:
    :chapter-label:
     // 目次作成
    :toc: left
    :toclevels: 3
     // ラベルの日本語設定
    :toc-title: 目次
    :preface-title: はじめに/まえがき
    :appendix-caption: 付録
    :caution-caption: 注意
    :example-caption: 例
    :figure-caption: 図
    :important-caption: 重要
    :last-update-label: 最終更新
    :listing-caption: リスト
    :manname-title: 名前
    :note-caption: 注記
    :table-caption: 表
    :tip-caption: ヒント
    :toc-title: 目次
    :untitled-label: 無題
    :version-label: バージョン
    :warning-caption: 警告