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

はじめに

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

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

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

## 1. コメント類

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

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

## 2. 文字飾り

基本

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

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

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

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

記述 | 説明
--- | ---
    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:ファイル[保存]
| ファイル 保存

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

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

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

## 5. 箇条書き

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

表 2. 箇条書き(項目)
結果 | 記述
--- | ---
項目1 サブ項目1 サブ項目2 サブ項目の中に複数行に渡る大きな大きな大きな大きなブロックを記述できる 項目2 |
    - 項目1
    	* サブ項目1
    	* サブ項目2
    +
    --
    サブ項目の中に複数行に渡る大きな大きな大きな大きなブロックを記述できる
    --
    - 項目2

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

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

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

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

## 7. ラベル

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

結果 | 記述
--- | ---
第一項 第一項の定義 さらにそのサブ サブの内容 |
    第一項::
    	第一項の定義
    	さらにそのサブ:::
    		サブの内容

## 8. ブロックラベル

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

## 9. ブロック

- ``(バッククウォート)で囲むとパスされる →エスケープ方法

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);
     ----

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

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

    単行の場合:

    NOTE: <内容>

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

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

## 11. 区切り線

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

表 4. 区切り線
結果 | 記述
--- | ---
| `---`

## 12. 改行

- `␣+`で繋ぐ。

- もしくは[%hardbreaks]で段落全体で改行を有効にする（段落毎にリセットされる）

表 5. 改行
結果 | 記述
--- | ---
１行目 ２行目 |
    １行目 +
    ２行目

## 13. コメント

    // コメント行

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

## 14. エスケープ方法

    * $$ ～ $$で囲む        :通常文字になる
    * +++ ～ +++で囲む      :HTML制御になる(インライン要素)
    * pass:[xxxx]で囲む	    :HTML制御になる(インライン要素、同上）
    * ``～``で囲む          :リテラルになる　バッククウォートx2
    * \(バックスラッシュ)   :次の文字の制御のみをキャンセルする。\*bold*や\{lt}など
    * その他は<<特殊記号>>で記載すること。

## 15. 特殊記号

特殊記号は`{}`を使う

表 6. 特殊記号の一覧
記号 * ({}で囲む) | 表現
--- | ---
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 |

## 16. 色

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

赤いコンテンツ、背景黄色

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

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

⇒ だめ

以下の定義みたい(rubyの中)

  lib\ruby\gems\2.4.0\gems\asciidoctor-1.5.7.1\data\stylesheets\asciidoctor-default.css

お試し

■■■■■■■ OK
■■■■■■■ OK
■■■■■■■ OK
■■■■■■■ NG
■■■■■■■ NG
■■■■■■■
■■■■■■■ OK
■■■■■■■ OK
■■■■■■■ OK
■■■■■■■ OK
■■■■■■■ OK
■■■■■■■ OK
■■■■■■■ OK
■■■■■■■ NG

■■■■■■■ NG

■■■■■■■ TEST

■■■■■■■

The application is called MyApp2.

adfasd€dfasdfa † renders as †

adfasdf

[[<abc> ]]

例

図

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

赤色

ライム

シアン

シアン

color

the '例'

ja

File Save

`F11`

2020-02-06

C:/Users/AA004035

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

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

X | Y

{

a #FF0000
Cell data

## 17. リンク

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

santanaのCMM

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

## 18. イメージリンク

- 通常

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

- インライン（行内)

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

行でをいれる

## 19. テーブル

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

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

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

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

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

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

表現は以下のとおり

    	|================================
    	|
    	// 左段落
    	[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
    	!=========

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

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

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

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

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

例.

イメージリンク

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

# その他

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

2. 色名

3. 本

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

トップページ_Asciidoctor Documentation

Syntax-quick-ref

writers-guide

diagram

style-guide(draft)

macro defineがあるんですけどね

# Nested Tables

Nested tables

## 24. 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

.

# まとめ

## 25. タイトル

`。。。`（。。。）

表 8. タイトル例
結果 | 記述
--- | ---
<左列のレンダリング結果> |
    <右側列の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 これ消したら消えた*/
    	}

## 26. テストコード

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

    単行記述は以下：

    IMPORTANT: 本文の記載

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

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

# 付録

## 28. 属性パラメータ

    :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:
    	*マクロを有効するにる

表 9. 完全な例
     // 属性定義
    :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: 警告