1. 表現の統一について
1.1. 統一した文言など表現ゆれを防ぐための利用
define-{定義対象}.adocに定義ずみの項目については、本文中に直書きすることなく定義を参照して利用するようお願いします。
利用方法は「 3.1, “文言や画像、リンク等の定義と利用”」に記載があります。
対象の定義ファイルは以下の通りです。
- define-literal.adoc
-
表現ゆれを防いだり、記載を容易にするための共通的な表現を定義しています。
こちらもindex.adocに記載すると盆雑になるため外部定義となっており、編集中のプレビューもできるように、各ファイルの最上部で条件インクルードされています。 - define-imageNicon.adoc
-
アイコンやイメージの画像を定義しています。
1.2. 文体の整理
本ドキュメントでは、原則として"…です。…ます。"調の敬体（丁寧体）で記載し、常体（普通体）との混用は避けてください。 ただし、文の途中や、説明のための図の中、箇条書にする部分だけを常体にするなど状況に合わせて整理する必要があります。
その他、記載について迷う場合や統一的な記載を確認する際は以下を参照してください。 Microsoft ローカリゼーション スタイル ガイド
1.3. 画像について
画像はその対象やフォーマット毎のルールや、利用時のルールがあります。
|
利用する画像の品質を下げないでください
画像はドキュメントで見栄えの大きな要素を占めています。 |
1.4. セクションの切り方
「 3.2, “セクションタイトルのレベルについて”」を参考に、他の画面と可能な限り統一感を保って表題をつけてください。
1.4.1. セクション内の記載方法
-
原則として手順として必要なものにカウンター機能を付ける
-
項目内の構成について「説明」「画像」の順で記載する
(画面ページの最上部は概要がない場合「画像」が先行するが概要が上に入るものとする) -
指摘事項で良く現れる()表記のタイトルやセクション表記は残さず文章になるように変更
難しいものは見出しとしてそのままにする
1.5. コントロール名
画面のパーツやコントロールは以下の文言で統一します。
| 利用する名称 | 説明 | 利用しない名称 |
|---|---|---|
ドロップダウンリスト |
押すと選択肢がリストで表示されるもの |
プルダウンリスト |
ラジオボタン |
主に丸いボタンで複数の選択肢の内一意で選択するもの |
オプションボタン |
チェックボックス |
主にチェックいれる四角いボタンで複数の選択肢の内、複数を選択可能なもの |
|
コンボボックス |
テキスト入力とドロップダウンリストが同一のコントロールで成り立つもの |
|
アコーディオン |
表示や入力枠が閉じたり開いたりできるコントロール |
1.6. 文中のカッコの扱いについて
本画面の参照のうち、表外の項目については原則「項目名」を利用します。
【〇〇】ボタンのようにコントロール上に表記された項目名は選択肢を除き【項目名】を利用します。
（選択肢は現状バラツキあり）
その他の画面、ロールなど原則として用語定義を利用するものは「」を利用しません。
1.7. OR条件AND条件を日本語で記載する場合
1.7.1. OR条件
[α]または[β] [A]、[B]、[C]、もしくは[D]等の[α]、または[E]、[F]、[G]、もしくは[H]などの[β]
は
α or β α[A or B or C or D (or etc.)] or β[E or F or G or H (or etc.)]
となります。
1.7.2. AND条件
[α]および[β] [A]、[B]、[C]、および[D]等の[α]、並びに[E]、[F]、[G]、および[H]などの[β]
は
α and β α[A and B and C and D (and etc.)] and β[E and F and G and H (and etc.)]
となります。
1.8. 時刻フォーマットの表記
データの項目一覧のフォーマット表記や、スクリーンショット内を置き換える際の日時表記は以下で統一します。
| 書式指定子 | 説明 | 使用例 | 表記可否 |
|---|---|---|---|
d |
月の日にち (1 ～ 31) |
2009-06-01T13:45:30 → 1 |
○ |
dd |
月の日にち (01 ～ 31) |
2009-06-01T13:45:30 → 01 |
○ |
ddd |
曜日の省略名 |
2009-06-15T13:45:30 → Mon (en-US) |
- |
h |
12 時間形式の時間 (1 ～ 12) |
2009-06-15T01:45:30 → 1 |
- |
hh |
12 時間形式の時間 (01 ～ 12) |
2009-06-15T01:45:30 → 01 |
- |
H |
24 時間形式の時間 (0 ～ 23) |
2009-06-15T01:45:30 → 1 |
○ |
HH |
24 時間形式の時間 (00 ～ 23) |
2009-06-15T01:45:30 → 01 |
○ |
m |
分 (0 ～ 59) |
2009-06-15T01:09:30 → 9 |
○ |
mm |
分 (00 ～ 59) |
2009-06-15T01:09:30 → 09 |
○ |
M |
月 (1 ～ 12) |
2009-06-15T13:45:30 → 6 |
○ |
MM |
月 (01 ～ 12) |
2009-06-15T13:45:30 → 06 |
○ |
MMM |
月の省略名 |
2009-06-15T13:45:30 → Jun (en-US) |
- |
s |
秒 (0 ～ 59) |
2009-06-15T13:45:09 → 9 |
- |
ss |
秒 (00 ～ 59) |
2009-06-15T13:45:09 → 09 |
○ |
tt |
AM/PM 指定子 |
2009-06-15T13:45:30 → 午後 (ja-JP) |
- |
yy |
年 (00 ～ 99) |
2019-06-15T13:45:30 → 19 |
- |
yyyy |
年 (4 桁の数値) |
2009-06-15T13:45:30 → 2009 |
○ |
YYYY |
暦週の基準年 |
週の開始が月曜日 : |
- |
zzz |
UTC を基準とする時間および |
2009-06-15T13:45:30-07:00 → -07:00 |
○ |
詳しくはMicrosoftの 「カスタム日時形式文字列」を参照してください。
2. AsciiDocについて
AsciiDocは軽量マークアップ言語の一つで可読文書記述形式です。
出力もHTML, PDF, ePubなどが行えるため出版や開発環境でのナレッジの共有まで様々な用途で利用することが可能です。
-
AsciiDocをドキュメント作成に利用している例
-
AsciiDocを執筆に利用している例
-
O’Reilly Mediaの書籍の一部(Welcome kitとして公開していました)
-
-
AsciiDocをナレッジに利用している例
-
GitHub(READMEやWikiに利用するオープンソースマークアップライブラリに採用されています)
-
2.1. AsciiDocの記述方法
AsciiDocは軽量マークアップ言語でメジャーなフォーマットであるmarkdownと比較し、
同様の記述容易性を供えつつもより高度な文書の論理構造を構築することが可能です。
記載方法の簡単な説明は以下のリンクをご参照ください。
また、ヘルプデスク内で利用している記載方法は「 3, AsciiDocの記載方法」をご覧ください。
2.2. Asciidoctorの利用と環境
Asciidoctorは、AsciiDoc形式のための包括的なツールで、AsciiDoc形式をHTML5、DocBook、PDFなどの形式に変換します。
2.2.1. Asciidoctorの歴史
Asciidoctorは2012年にGitHub開発者であるNick HengeveldがGitのウェブサイトに示されているgitのマニュアルページを生成するために作成したプロトタイプをベースに、同じくGitHub開発者であるRyan Waldronがプロジェクトを開始しました。
2013年にAsciidoctorがGitHubにおいて発表され、その後はオープンソースプロジェクトとしてGitHubでホストされています。
このため、GitHubではサイト上で.adocファイルのプレビューすることができ、READMEやWikiをAsciiDoc形式で記述することが可能です。
2.2.2. Asciidoctorの利用方法と本環境
詳しいマニュアルもありますが、本環境については以下のBlog記事をご参照ください。本環境はBlog記事の構成を発展させたものとなります。
-
公式マニュアル
-
Blog記事
2.3. なぜAsciiDocを利用するのか？
2.3.1. バージョン管理の必要性
システムに紐づくドキュメントはシステムの更新と共に、更新され共存する必要があります。
また、お客様の不明点や、問題解決に必要なTipsの記載も欠かせません。
このため、いつ何のためにどんな修正が行われたか、Gitによるバージョン管理で追跡し、
必要であれば過去のバージョンを取り消すことも必要です。
2.3.2. スタイルの統一
従来のドキュメントエディタの多くは、更新が重なると適用したスタイルを維持することが難しくなります。
Asciidoc形式は記載方法がテキスト形式に限られるため、記載時にスタイルを切り離して記載することができます。
これにより、より大きな文章でも統一されたスタイルで提供することが可能です。
2.3.3. 表現の統一
従来のドキュメントエディタの多くは、文字列の定義や、繰り返し利用される記述の一括定義が行えず、
記載箇所毎の大量の表現ゆれ、表記ゆれに対応する必要がありました。
また、表記ゆれを確認するために検索を行うと大量の検索結果が表示されてしまい
あえて別表現を使っている場合の抽出が困難でした。
Asciidoc形式は文字列の定義や、文書の参照取り込みが可能なため、これらの問題に対し適切な運用が可能です。
2.3.4. 各権限毎の出力
全ての仕様を網羅し的確な説明がなされたナレッジがあれば、それから各権限向けのマニュアル等ドキュメントを作りたいと考えるのは自然な発想です。
従来のドキュメントエディタの多くでも、そのような運用がなされていますが、更新が進むに連れて対象権限毎に表現を修正したドキュメントと、
最新の仕様が記載された網羅的なドキュメントのマージが難しくなり、表現ゆれや記載ミスの原因となっています。
Asciidoc形式はifdefディレクティブの利用により簡易的な出力制御が行えるため、
網羅的なドキュメントに全ての権限に対する記載することができ、安定的に各権限のマニュアル等ドキュメントをリリースすることが可能です。
2.3.5. リリース向け出力形式の最適化
現在、多くのシステムではPDFのドキュメントが配布されますが、
WebシステムではHTMLのドキュメントも多用されています。
HTMLのドキュメントは目次もサイドバー等に表示可能になりブラウザの機能と合わせて目的検索生が向上するためです。
従来のドキュメントエディタもほとんどの場合でPDF出力が可能になっていますが、
HTMLでの出力を行うと、HTMLの利便性を享受できないことが多く、最悪の場合レイアウト崩れ等が発生することが多々あります。
Asciidoc形式はPDF出力とHTML出力に対して、それぞれ最適な出力を提供します。
2.4. AsciiDocに移行するデメリット
ここでは従来のドキュメントと、本ナレッジを比較した場合のデメリットを記載します。
2.4.1. 記載方法に慣れていない
今までOffice suite等のドキュメントエディタを利用していた場合、
多くの方が編集方法に戸惑うと考えられます。
ただしこれらの問題はドキュメントエディタが更新された場合にも当てはまります。
Asciidoc形式はMarkdown形式の様な簡易的な記載ができる学習コストが低い記載方法の一つです。
従来のドキュメントエディタと異なり、スタイルを壊してしまうこともないため大きな問題にならないと考えています。
2.4.2. 編集履歴や校閲機能がない
Asciidoc形式はテキスト形式のため、編集履歴や校閲機能はありません。
これらを同じドキュメントエディタ上で利用していた場合は当初不便を感じると思われます。
Asciidoc形式では、本文中に出力されないコメントを記載することは可能です。
また、より確実なバージョン管理を行うためにGit-hubのプライベートリポジトリを利用することで、
Issueの管理による議論や、それに紐付けた更新など、多彩なバージョン管理等を行うことでカバー可能です。
2.4.3. 記載中にイメージがわかない
Asciidoc形式はテキスト形式のため、従来のドキュメントエディタと異なり、記載中はスタイルが適用されません。
しかし、現在は無料のテキストエディタや統合開発環境に(Atom, VS Code, IntelliJ IDEA, Android studio)等にプラグインをインストールすることで、
簡単にプレビューを表示しながら編集することが可能です。
2.4.4. 特殊な記述ができない
Asciidoc形式は原則として技術本やドキュメントを記載するための汎用的な構成を重視されているため、
画像の上に画像を貼り付けたり、ある一箇所だけ特別なスタイルを変更することができません。
これらについては、更新が進むたびに表現方法がバラついてしまうことがなくなるため、
一長一短だと考えられます。
2.4.5. ドキュメントエディタで校閲や添削できない
Asciidoc形式は出力を行うとPDFやHTMLにて出力されるため、その状態での校閲や添削はできません。
特にPDFではページング制御とうがあるため、出力イメージ上で校閲や添削を行いたいと考えられます。
この点についてPDFは、Adobe Acrobat ReaderやAppleのプレビューアプリには注釈機能があるため、
直接の編集ではない校閲や添削は可能です。
また、HTMLについてもスクリーンショット等にマークアップすることが多くのブラウザやOSで可能になっているため、
編集者以外の校閲や添削に問題はありません。
3. AsciiDocの記載方法
3.1. 文言や画像、リンク等の定義と利用
Asciidocでは定義済み項目を本文中に直書きすることなく簡単に利用することができます。
define-literal.adocに定義された情報は「{name-role-sample}」のように記載することで「サンプルロール」と出力したり、
定義された画像として「{icon-sample-user}」のように記載することで「
」と出力することができます。
1
2
define-literal.adocに定義された情報は「\{name-role-sample}」のように記載することで「{name-role-sample}」と出力したり、
定義された画像として「\{icon-sample-user}」のように記載することで「{icon-sample-user}」と出力することができます。
3.2. セクションタイトルのレベルについて
asciidocはヘッダー(見出し)の扱いが厳格な文書形式です。
また多くの人が同時に修正しやすくGitでのマージ等が低コストで行えるように、
レベル2のヘッダーごとにインクルードによるファイルの分割してください。
また、分割したファイルでは原則レベル3以降のヘッダーを利用し文書の構造化に努めてください。
1
2
3
[[include]]
= 参照先の章の名称
include::include.adoc[]
インクルードするファイルのレベルは「leveloffset」を利用して以下の記載をすると揃えることができます。
1
include::include.adoc[leveloffset=+2]
3.3. 出力設定について
AsciiDocではifdef(ifndef)ディレクティブを利用した簡易的な出力制御が可能です。
本ドキュメントでは主に以下の定義を利用して状況や対象者によって以下のように出力を切り替えています。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
ifdef::backend-html5[]
HTMLのみの出力内容
endif::[]
ifndef::backend-pdf[]
PDFでは出力されない内容
endif::[]
ifndef::convert-for-readers[]
自動化した出力では利用しない内容
(「convert-for-writers」は本サンプルで定義している項目)
endif::[]
ifdef::convert-for-writers[]
明示的にendifを記載する場合。
(「convert-index」は本サンプルで定義している項目)
endif::convert-for-writers[]
3.4. 画像について
ここでは利用方法を記載します。
3.4.1. ブロックでの記述
.ブロック画像
image::contents/images/Logo/analog-logo.svg[pageTop,{full-page}]
画像の指定には定義を利用したサイズルールがあります。
定義を利用することで、全てのサイズを統一することが可能です。
| 対象 | 定義 | 備考 |
|---|---|---|
外部ドキュメントの貼り付け |
full-width |
センタリングも行います。 |
サムネイル |
thumbnail |
|
フルサイズの画面幅 |
full-page |
|
ダイアログのみの画像 |
dialog-page |
3.4.2. インラインでの記述
インライン {icon-h-write} で表示
1
2
インライン {icon-h-write} で表示
image:contents/images/SvgBadges/badges/badge-user-analog-check.svg[]
3.5. 表の書き方
普段の利用でMarkdownより大きな利便性を感じる場面は表の扱いです。
ここでは本ドキュメントで利用している記載法を紹介します。
| TH サイズ1 | TH サイズ2 | TH サイズ3 | ||||
|---|---|---|---|---|---|---|
<で左寄せ R1C1 |
^で中央寄せ R1C2 |
>で右寄せ R1C3 |
||||
hで個別のヘッダ |
AsciiDoc記法で改行→ |
セル内で |
||||
TD |
AsciiDoc記法のリスト→ |
|
||||
.n+縦に結合 |
TD |
TD |
||||
n+横に結合 |
||||||
TD |
↑ 結合されたカラムの定義はしません |
|||||
結合時など色の指定の影響(継承の扱いは微妙) aで内部にテーブル
|
||||||
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
.複雑な表の扱い
[%header,cols="1,2,3"]
|===
|TH サイズ1 |TH サイズ2 |TH サイズ3
<|<で左寄せ R1C1
^|^で中央寄せ R1C2
>|>で右寄せ R1C3
h|hで個別のヘッダ
|AsciiDoc記法で改行→
|セル内で +
改行
|TD
|AsciiDoc記法のリスト→
<a|
* [.cellsfont]#<で左寄せを明示#
* [.cellsfont]#aでAsciiDoc記法を許容#
* [.cellsfont]#[.cellsfont]#内容#にてフォントをテーブルと合わせる#
.3+|.n+縦に結合 +
| {set:cellbgcolor:#00ccff} TD +
色の指定
| {set:cellbgcolor:#transparent} TD +
色の指定(継承)
2+|n+横に結合
| {set:cellbgcolor:#00ccff} TD +
色の指定
| ↑ 結合されたカラムの定義はしません +
色の指定は連続する
3+a| {set:cellbgcolor:#transparent}
[.cellsfont]#結合時など色の指定の影響(継承の扱いは微妙)#
[.cellsfont]#aで内部にテーブル#
[%header,cols="1,3"]
!===
![.cellsfont]#no.# ![.cellsfont]#内容#
^![.cellsfont]#1#
![.cellsfont]#ただしセパレータを\!にかえる#
!===
// 隙間が足りない事があるので隠し文字をいれる
{zwsp}
|===
//最終セルのカラーをリセットして他のテーブルに影響しない様にする
{set:cellbgcolor!}
3.6. ロール指定による文字のスタイル指定
以下のようにロールを利用してスタイルを適用できます。
-
指定なし
-
強調によるボールド
-
大きめ文字
-
赤
-
オレンジ大きめ文字
-
-
テーブル内と同じ文字
-
テーブル内の赤字
1
2
3
4
5
6
7
8
* 指定なし
* *強調によるボールド*
* [.big]#大きめ文字#
* [.red]#赤#
* [.darkorange.big]#オレンジ大きめ文字#
* [.navy.big]#*青の大きめ文字ボールド*#
* [.cellsfont]#テーブル内と同じ文字#
* [.cellsfont.red]#テーブル内の赤字#
3.6.1. 本ドキュメントでロール指定可能な色と色名について
本ドキュメントでは以下のブロックに示す色をHTMLおよびPDF共通で利用できるように「css/docinfo.css」および「themes/default-role-color-theme.yml」に定義しています。
利用の際はSVGなども細かく色を合わせるとともに、ドキュメント全体での統一感を失わないように注意してください。
なお、色名のリストはPDFでは大きくなりすぎるので出力しません。
■black (000000)
■dimgray (696969)
■gray (808080)
■darkgray (a9a9a9)
■silver (c0c0c0)
■lightgray (d3d3d3)
■gainsboro (dcdcdc)
■whitesmoke (f5f5f5)
■white (ffffff)
■snow (fffafa)
■ghostwhite (f8f8ff)
■floralwhite (fffaf0)
■linen (faf0e6)
■antiquewhite (faebd7)
■papayawhip (ffefd5)
■blanchedalmond (ffebcd)
■bisque (ffe4c4)
■moccasin (ffe4b5)
■peachpuff (ffdab9)
■mistyrose (ffe4e1)
■lavenderblush (fff0f5)
■seashell (fff5ee)
■oldlace (fdf5e6)
■ivory (fffff0)
■honeydew (f0fff0)
■mintcream (f5fffa)
■azure (f0ffff)
■aliceblue (f0f8ff)
■lavender (e6e6fa)
■lightsteelblue (b0c4de)
■lightslategray (778899)
■slategray (708090)
■steelblue (4682b4)
■royalblue (4169e1)
■midnightblue (191970)
■darkblue (00008b)
■mediumblue (0000cd)
■blue (0000ff)
■dodgerblue (1e90ff)
■cornflowerblue (6495ed)
■deepskyblue (00bfff)
■lightskyblue (87cefa)
■skyblue (87ceeb)
■lightblue (add8e6)
■powderblue (b0e0e6)
■paleturquoise (afeeee)
■lightcyan (e0ffff)
■cyan (00ffff)
■turquoise (40e0d0)
■mediumturquoise (48d1cc)
■darkturquoise (00ced1)
■lightseagreen (20b2aa)
■cadetblue (5f9ea0)
■darkcyan (008b8b)
■teal (008080)
■darkslategray (2f4f4f)
■darkgreen (006400)
■green (008000)
■forestgreen (228b22)
■seagreen (2e8b57)
■mediumseagreen (3cb371)
■mediumaquamarine (66cdaa)
■darkseagreen (8fbc8f)
■aquamarine (7fffd4)
■palegreen (98fb98)
■lightgreen (90ee90)
■springgreen (00ff7f)
■mediumspringgreen (00fa9a)
■lawngreen (7cfc00)
■chartreuse (7fff00)
■greenyellow (adff2f)
■lime (00ff00)
■limegreen (32cd32)
■yellowgreen (9acd32)
■darkolivegreen (556b2f)
■olivedrab (6b8e23)
■olive (808000)
■darkkhaki (bdb76b)
■palegoldenrod (eee8aa)
■cornsilk (fff8dc)
■beige (f5f5dc)
■lightyellow (ffffe0)
■lightgoldenrodyellow (fafad2)
■lemonchiffon (fffacd)
■wheat (f5deb3)
■burlywood (deb887)
■tan (d2b48c)
■khaki (f0e68c)
■yellow (ffff00)
■gold (ffd700)
■orange (ffa500)
■sandybrown (f4a460)
■darkorange (ff8c00)
■goldenrod (daa520)
■peru (cd853f)
■darkgoldenrod (b8860b)
■chocolate (d2691e)
■sienna (a0522d)
■saddlebrown (8b4513)
■maroon (800000)
■darkred (8b0000)
■brown (a52a2a)
■firebrick (b22222)
■indianred (cd5c5c)
■rosybrown (bc8f8f)
■darksalmon (e9967a)
■lightcoral (f08080)
■salmon (fa8072)
■lightsalmon (ffa07a)
■coral (ff7f50)
■tomato (ff6347)
■orangered (ff4500)
■red (ff0000)
■crimson (dc143c)
■mediumvioletred (c71585)
■deeppink (ff1493)
■hotpink (ff69b4)
■palevioletred (db7093)
■pink (ffc0cb)
■lightpink (ffb6c1)
■thistle (d8bfd8)
■magenta (e4007f)
■fuchsia (ff00ff)
■violet (ee82ee)
■plum (dda0dd)
■orchid (da70d6)
■mediumorchid (ba55d3)
■darkorchid (9932cc)
■darkviolet (9400d3)
■darkmagenta (8b008b)
■purple (800080)
■indigo (043c78)
■darkslateblue (483d8b)
■blueviolet (8a2be2)
■mediumpurple (9370db)
■slateblue (6a5acd)
■mediumslateblue (7b68ee)
■coralred (ef857d)
■poppyred (ea5550)
■tomatored (ea5549)
■vermilion (ea553a)
■scarlet (ea5532)
■carrotorange (ed6d35)
■chinesered (ed6d46)
■terracotta (bd6856)
■cocoabrown (98605e)
■mahogany (6b3f31)
■marron (6a1917)
■sepia (622d18)
■coffee (7b5544)
■burntsienna (bb5535)
■amberrose (e6bfb2)
■beigerose (e8d3ca)
■salmonpink (f3a68c)
■sahara (e29676)
■ashrose (e6bfab)
■shellpink (fbdac8)
■babypink (fdede4)
■nailpink (fce4d6)
■rawsienna (e17b34)
■caramel (bc611e)
■sunset (f6b483)
■cinnamon (be8f68)
■champagne (e9dacb)
■peach (fbd8b5)
■cafeaulait (946c45)
■apricot (f7b977)
■amber (c2894b)
■bronze (ac6b25)
■vanilla (e8c59c)
■cork (c49a6a)
■burntumber (6f5436)
■rawumber (866629)
■flesh (fad09e)
■goldenyellow (f6ae54)
■mandarinorange (f3981d)
■marigold (f39800)
■ecrubeige (f6e5cc)
■oyster (eae1cf)
■ochre (ba8b40)
■buff (caac71)
■saffronyellow (fac559)
■pumpkin (e5a323)
■yellowocher (c4972f)
■blond (f2d58a)
■biscuit (ead7a4)
■leghorn (ffe9a9)
■sunshineyellow (ffedab)
■creamyellow (fff3b8)
■naplesyellow (fdd35c)
■topaz (e9bc00)
■chromeyellow (fcc800)
■cream (e3d7a3)
■straw (ece093)
■jasmineyellow (edde7b)
■antiquegold (c1ab05)
■jaunebrillant (ffdc00)
■citrus (eddc44)
■limelight (fff799)
■mimosa (fff462)
■lemonyellow (fff352)
■melonyellow (e0de94)
■chartreuseyellow (e3e548)
■limeyellow (eaeea2)
■chartreusegreen (d9e367)
■lettucegreen (d1de4c)
■olivegreen (5f6527)
■mossgreen (777e41)
■grassgreen (7b8d42)
■leafgreen (9fc24d)
■whitelily (f0f6da)
■asparagusgreen (dbebc4)
■citrongreen (618e34)
■meadowgreen (65ab31)
■applegreen (a7d28d)
■ivygreen (578a3d)
■spinachgreen (417038)
■cactus (387d39)
■skygreen (bee0c2)
■spearmint (79c06e)
■mintgreen (89c997)
■parrotgreen (37a34a)
■summergreen (009944)
■opalgreen (bee0ce)
■spraygreen (a4d5bd)
■bottlegreen (004d25)
■cobaltgreen (3cb37a)
■evergreen (00984f)
■malachitegreen (009854)
■emeraldgreen (00a968)
■viridian (00885a)
■hollygreen (006948)
■billiardgreen (005c42)
■chromegreen (00533f)
■antiquegreen (54917f)
■watergreen (a5c9c1)
■icegreen (a3d6cc)
■turquoisegreen (00947a)
■peppermintgreen (00ac9a)
■peacockgreen (00a497)
■nileblue (2cb4ad)
■saxeblue (418b89)
■slategreen (3c7170)
■tealgreen (006a6c)
■aquagreen (88bfbf)
■peacockblue (009e9f)
■capriblue (00a3a7)
■cambridgeblue (25b7c0)
■turquoiseblue (00afcc)
■summershower (a1d8e2)
■ceruleanblue (008db7)
■duckblue (007199)
■marineblue (006888)
■madonnablue (00608d)
■egyptianblue (0073a8)
■shadowblue (719bad)
■yachtblue (409ecc)
■chalkblue (68a9cf)
■pigeonblue (88b5d3)
■smokeblue (a4c1d7)
■frostyblue (bbdbf3)
■bleuacide (006eb0)
■cobaltblue (0068b7)
■spectrumblue (0075c2)
■zenithblue (4496d3)
■heavenlyblue (68a4d9)
■orchidgray (bcc7d7)
■daydream (a3b9e0)
■salviablue (94adda)
■hyacinthblue (7a99cf)
■hyacinth (6c9bd2)
■ironblue (192f60)
■inkblue (003f8e)
■orientalblue (26499d)
■ultramarineblue (4753a2)
■ultramarine (434da2)
■wistaria (8d93c8)
■bluelavender (a4a8d4)
■pannsy (4d4398)
■heliotrope (9079b6)
■deeproyalpurple (47266e)
■grape (56256e)
■mauve (915da3)
■iris (c7a5cc)
■lilac (d1bada)
■crocus (b79fcb)
■lavendermauve (a688bd)
■royalpurple (7f1184)
■raisin (6b395f)
■raspberry (841a75)
■framboise (9a0d7c)
■dahliapurple (a50082)
■orchidpurple (af0082)
■raspberryred (9f166a)
■lilla (e0b5d3)
■rosetendre (e6afcf)
■orchidpink (da81b2)
■cyclamenpink (d04f97)
■bougainvillaea (e62f8b)
■ruby (c70067)
■claret (941f57)
■azalee (d83473)
■cosmos (dc6b9a)
■lotuspink (de82a7)
■oldorchid (e3adc1)
■rosemist (debecc)
■rosedragee (e5c1cd)
■cherrypink (eb6ea0)
■opera (e95388)
■rosered (ea618e)
■oldlilac (b0778c)
■cocoa (6e4a55)
■winered (b33e5c)
■garnet (942343)
■cochinealred (c82c55)
■strawberry (e73562)
■carmine (d70035)
■signalred (e8383d)
■burgundy (6c2735)
■bordeaux (6c272d)
■camellia (da536e)
■rose (e95464)
■rosepink (f19ca7)
■flamingopink (f5b2ac)
■oldrose (e29399)
■pinkalmond (e3acae)
■rosedust (e6c0c0)
■snowwhite (fafdff)
■pinkwhite (fef9fb)
■milkywhite (fffff9)
■amberwhite (fff9f5)
■lavenderice (f7f6fb)
■pearlwhite (f7f6f5)
■powderpink (f5ecf4)
■silverwhite (efefef)
■frostygray (e8ece9)
■silverpink (eeeaec)
■beigecameo (eee9e6)
■ecru (eee7e0)
■pinkbeige (ede4e1)
■frostywhite (e6eae6)
■oysterwhite (eae8e1)
■wisteriamist (d3d6dd)
■cloud (d4d9df)
■moongray (d4d9dc)
■chinaclay (d4dcd3)
■sandbeige (dcd6d2)
■orchidmist (d3d3d8)
■reedgray (d4d9d6)
■skygray (cbd0d3)
■lavendergray (bcbace)
■pearlgray (c9c9c4)
■sandgray (c9c9c2)
■marblegray (c0c5c2)
■opalgray (bfbec5)
■frenchgray (8da0b6)
■mist (b4aeb1)
■ashblond (b5b5ae)
■fog (abb1b5)
■beigegray (b4ada9)
■silvergray (afafb0)
■stormgray (aaaab0)
■greenfog (abb1ad)
■ashgray (9fa09e)
■rosegray (9d8e87)
■elephantskin (9f9f98)
■battleshipgray (898989)
■stonegray (898880)
■mossgray (7e837f)
■dovegray (7d7b83)
■steelgray (736d71)
■ivygray (666c67)
■graphite (594e52)
■charcoalgray (4e454a)
■taupe (504946)
■lampblack (24140e)
3.7. 特殊なAttributeの利用
3.7.1. リンクの定義
本ドキュメントは{link-site-preview}で閲覧できます。
{zwsp}は日本語との結合時に必要です。
1
2
3
4
link:https://github.com/Analog-inc/asciidoctor-action[利用しているActionのリポジトリ]
本ドキュメントは{zwsp}{link-site-preview}で閲覧できます。 +
\{zwsp}は日本語との結合時に必要です。
3.7.2. 定義の途中で色指定
通常の記載は『【テスト】ボタン』で、一部のみ赤字は『【テスト】ボタン』です。 /がpassでそのまま出力されるために2行に分けています。
1
2
3
4
5
6
:name-button-test: 【テスト】ボタン
:name-button-test-red-name: pass:quotes[[.red]#【テスト】#]
:name-button-test-red: {name-button-test-red-name}{zwsp}ボタン
通常の記載は『{name-button-test}』で、一部のみ赤字は『{name-button-test-red}』です。
/{zwsp}がpassでそのまま出力されるために2行に分けています。
3.7.3. 定義内で改行
定義内で改行はしても 表示では改行しません。
定義内で改行して
表示でも改行します。
1
2
3
4
5
6
7
8
:sentence-no-newline: 定義内で改行はしても \
表示では改行しません。
:sentence-newline: 定義内で改行して + \
表示でも改行します。
{sentence-no-newline} +
{sentence-newline}
3.8. 脚注
脚注はアイコンが左側に表示されるスタイルです。 変更容易性や表現の幅を考慮しブロック形式で記載することをお勧めします。
|
インフォメーションマークが出力されます。 |
1
2
3
4
5
6
[NOTE]
.[.navy.big]#*NOTE*#
====
インフォメーションマークが出力されます。 +
補足となる内容を記載してください。
====
|
TIP
電球マークが出力されます。 |
1
2
3
4
5
6
[TIP]
.[.big]#*TIP*#
====
電球マークが出力されます。 +
少し高度な利用方法などを記載してください。
====
|
WARNING
三角オレンジの注意マークが出力されます |
1
2
3
4
5
6
7
[WARNING]
.[.orange.big]#*WARNING*#
====
三角オレンジの注意マークが出力されます +
システムを利用する上で不用意にデータの閲覧ができなくなるなどの +
問題を回避する方法を記載してください。
====
|
IMPORTANT
丸い赤の警告マークが出力されます |
1
2
3
4
5
6
[IMPORTANT]
.[.red.big]#*IMPORTANT*#
====
丸い赤の警告マークが出力されます +
システムを利用する上でセキュリティリスクなどを記載してください。
====
|
CAUTION
現在ある不具合やバグ、明らかな矛盾点など記載してください。 |
1
2
3
4
5
[CAUTION]
.[.darkgreen.big]#*CAUTION*#
====
現在ある不具合やバグ、明らかな矛盾点など記載してください。
====
3.9. ブロック
3.9.1. Example block (例示)
例示的な内容を指定するか、
または勧告ブロックを定義します。
-
リスト
-
リスト
1
2
3
4
5
6
7
8
9
.〇〇について
[example]
====
例示的な内容を指定するか、 +
または勧告ブロックを定義します。
. リスト
. リスト
====
3.9.2. Listing block
// 入力されたソースコードやキーボード入力が表示されます
ただし +
吹き出し機能が使えます。(1)
document.write("Hello world!!");
| 1 | 吹き出しの内容をここで定義します。 |
1
2
3
4
5
6
7
8
9
10
11
12
.〇〇について
[listing, javascript]
\----
// 入力されたソースコードやキーボード入力が表示されます
ただし +
吹き出し機能が使えます。(1)
document.write("Hello world!!");
\----
<1> 吹き出しの内容をここで定義します。
3.9.3. Fenced
1
2
3
4
5
// 入力されたソースコードまたはキーボード入力が表示されます。
ドキュメントで有効になっていて、言語が設定されている場合は、 +
ソース・ハイライターで色付けされます。
document.write("Hello world!!");
1
2
3
4
5
6
7
8
.〇〇について
```
// 入力されたソースコードまたはキーボード入力が表示されます。
ドキュメントで有効になっていて、言語が設定されている場合は、 +
ソース・ハイライターで色付けされます。
document.write("Hello world!!");
```
3.9.4. Literal block
入力された通りに + 出力テキストが表示されます 吹き出し機能が使えます。(1)
| 1 | 吹き出しの内容をここで定義します。
スペースを開けた一行が同じ表示になるので注意 |
1
2
3
4
5
6
7
8
9
10
.〇〇について
[literal]
....
入力された通りに +
出力テキストが表示されます
吹き出し機能が使えます。(1)
....
<1> 吹き出しの内容をここで定義します。
スペースを開けた一行が同じ表示になるので注意
3.9.5. Passthrough block
出力に直接送られる + 未処理のコンテンツ1
2
3
4
5
6
.〇〇について
[pass]
++++
出力に直接送られる +
未処理のコンテンツ
++++
3.9.6. Blockquotes(引用)
ミスをしたことのない人は、 + 新しいことに挑戦したことがありません。 吹き出し機能が使えます。(1)
| 1 | 吹き出しの内容をここで定義します。 |
1
2
3
4
5
6
7
8
.〇〇について
[quote, Albert Einstein,proverb,]
\----
ミスをしたことのない人は、 +
新しいことに挑戦したことがありません。
吹き出し機能が使えます。(1)
\----
<1> 吹き出しの内容をここで定義します。
3.9.7. Sidebar
1
2
3
4
5
6
7
8
9
10
.〇〇について
[sidebar]
****
文書の流れの外に表示される +
テキストやコンテンツを
非表示にする
. リスト
. リスト
****
3.9.8. Source
1
2
3
4
5
6
// 入力されたとおりに表示されるソースコードまたはキーボード入力。
ドキュメントで有効になっていて、言語が設定されている場合は、 +
ソース・ハイライターで色付けされます。
吹き出し機能が使えます。(1)
document.write("Hello world!!");
| 1 | 吹き出しの内容をここで定義します。 |
1
2
3
4
5
6
7
8
9
10
11
12
.〇〇について
[source,Java]
/----
// 入力されたとおりに表示されるソースコードまたはキーボード入力。
ドキュメントで有効になっていて、言語が設定されている場合は、 +
ソース・ハイライターで色付けされます。
吹き出し機能が使えます。(1)
document.write("Hello world!!");
/----
<1> 吹き出しの内容をここで定義します。
3.9.9. Stem
1
2
3
4
5
.〇〇について
[stem]
++++
インタプリタに直接送られる未処理のコンテンツ (AsciiMath や LaTeX math など)
++++
3.10. リスト
3.10.3. チェックリスト
リーフレットなどを作成する場合に利用してください。
-
チェック済みの要素
-
これもチェック済みの要素
-
未チェックの要素
1
2
3
- [*] チェック済みの要素
- [x] これもチェック済みの要素
- [ ] 未チェックの要素
3.11. カウンター
カウンターは型を定義することができる。
1. カウンターの利用方法
2. 自動的にインクリメント
見せずにインクリメント
4. 飛んでるはず
1. リセットは普通のAttributeと同じ
a. カウンターは型を定義することができる。
b. インクリメントができればいい
1
2
3
4
5
6
7
8
9
10
11
12
{counter2:sequence-count-sample-no:0}カウンターは型を定義することができる。 +
{counter:sequence-count-sample-no}.{nbsp}カウンターの利用方法 +
{counter:sequence-count-sample-no}.{nbsp}自動的にインクリメント +
{counter2:sequence-count-sample-no}見せずにインクリメント +
{counter:sequence-count-sample-no}.{nbsp}飛んでるはず
:sequence-count-sample-no: 0
{counter:sequence-count-sample-no}.{nbsp}リセットは普通Attributeと同じ
{counter:sequence-count-sample-alphabet:a}.{nbsp}カウンターは型を定義することができる。 +
{counter:sequence-count-sample-alphabet}.{nbsp}インクリメントができればいい
3.12. 改ページ
<<<
3.14. ラベル
辞書形式に利用します。
- 第一項
-
第一項の定義
- 二条
-
第一項二条の定義
- 第二項
-
第二項の定義
1
2
3
第一項:: 第一項の定義
第一項二条::: 第一項二条の定義
第二項:: 第二項の定義
3.16. インラインマクロ
3.16.1. Inline image macro
「image:」で始まるインライン画像はインラインマクロの一つです。
詳しくは「 3.4.2, “インラインでの記述”」を参照してください。
3.16.2. Inline pass macro
「pass:」を利用するとAsciiDocの文法などが無視され未処理でそのまま出力されます。
3.16.3. Inline Macro Processor Extension
Inline Macro Processor Extensionは自分で処理を記載して利用するAsciidoctor Extensionsの1種類です。
3.16.3.1. datetimeformat
現在はAsciiDocで定義されたAttributesのみ対応しています。
本ドキュメントは2021/01/01版です。
2024年08月09日
2024-08-09
本ドキュメントは
2024年08月09日 13時02分47秒
に更新されました。
2024年08月09日 13時02分
13時02分
2024/08/09 13:02:47
2024/08/09 13:02
13:02
2024-08-09T13:04:02+09:00
13時02分47秒
13:04:02
Fri, 09 Aug 2024 04:02:47 GMT
2024-08-09T13:02:47+09:00
Fri, 09 Aug 2024 13:02:47 +0900
Fri, 09 Aug 2024 13:02:47 +0900
2024-08-09T13:02:47+09:00
08/09/24 13:02:47 JST
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
本ドキュメントは{zwsp}datetimeformat:revdate[/]{zwsp}版です。 +
datetimeformat:docdate[年月日] +
datetimeformat:localdate[-] +
本ドキュメントは
datetimeformat:docdatetime[年月日時分秒]
に更新されました。 +
datetimeformat:docdatetime[年月日時分] +
datetimeformat:docdatetime[時分] +
datetimeformat:docdatetime[/:ss] +
datetimeformat:docdatetime[/:] +
datetimeformat:docdatetime[:] +
datetimeformat:localdatetime[T] +
datetimeformat:doctime[時分秒] +
datetimeformat:localtime[:ss] +
datetimeformat:docdatetime[httpdate] +
datetimeformat:docdatetime[iso8601] +
datetimeformat:docdatetime[rfc2822] +
datetimeformat:docdatetime[rfc822] +
datetimeformat:docdatetime[xmlschema] +
datetimeformat:docdatetime[%D %T %Z]
3.17. 記号の記載
一部の記号は記載時にリプレースやエスケープを行う必要があります。
例えば「|」はリプレースとして「{vbar}」と記載を行います。 また、テーブル内で別のセパレーターとして「!」と利用する場合などはエスケープとして「/!」とすることで出力できます。
1
2
例えば「{vbar}」はリプレースとして「\{vbar}」と記載を行います。
また、テーブル内で別のセパレーターとして「!」と利用する場合などはエスケープとして「/!」とすることで出力できます。
以下はリプレースを行うべき記号や文字のリストとなります。
| Attribute name | Replacement text | Appearance |
|---|---|---|
|
nothing |
|
|
nothing |
|
|
single space |
|
|
  |
|
|
​ |
|
|
⁠ |
|
|
' |
' |
|
" |
" |
|
‘ |
‘ |
|
’ |
’ |
|
“ |
“ |
|
” |
” |
|
° |
° |
|
+ |
+ |
|
¦ |
¦ |
|
| |
| |
|
& |
& |
|
< |
< |
|
> |
> |
|
[ |
[ |
|
] |
] |
|
^ |
^ |
|
* |
* |
|
~ |
~ |
|
\ |
\ |
|
` |
` |
|
:: |
:: |
|
;; |
;; |
|
C++ |
C++ |
[1] いくつかの置換はUnicode文字ですが、他の置換は数値の文字参照です(例えば、")。 これらの文字参照は、Unicode文字の使用がAsciiDocの構文に干渉したり、レンダラー(すなわちブラウザ)を混乱させる可能性がある場合に使用されます。 参照をレンダラーが理解できるものに変換するのはコンバータ次第です(マニュアルページとPDFコンバータの両方が処理するもの)。
[2] Asciidoctor は、定義済みの属性を再割り当てすることを妨げるものではありません。 しかし、出力形式が異なるエンコーディング方式の使用を必要としない限り、それらを読み取り専用として扱うのが最善です。 これらの属性は、コンテンツとプレゼンテーションを切り離すための効果的なツールです。
[3] Asciidoctorでは、HTMLで定義されている名前付き文字参照(別名：名前付き実体)のいずれかを使用できます。 しかし、名前付き文字参照を使用すると、PDFなどの非HTML出力を生成する際に問題が発生することがあります。 これらの名前を解決するために必要な参照テーブルが定義されていない可能性があるからです。私たちの推奨事項は、XMLで定義されているもの(すなわち lt ・ gt ・ amp ・ quot ・ apos)を除いて、名前付き文字参照の使用を避けることです。 その代わりに、数値の文字参照を使用してください。
[4] ゼロ幅空間(ZWSP)は、必要に応じて長い単語を分割できる場所を示すUnicodeのコードポイントです。
[5] ワードジョイナー(WJ)は、その位置での改行を防ぐUnicodeのコードポイントです。
3.18. ダイアグラム
Asciidoctorではダイアグラムを記載できますが、生成画像はプレビューできません。
ダイアグラムの名称は必ず一意のものを設定してください。
4. 本ドキュメントの設定について
4.1. 参照ディレクトリの扱い
本ドキュメントはできる限り VS Code 上でファイルを編集している時のリアルタイムプレビューと、Github Actions を利用したコンバートの両立を行えるようにしています。 その中でいくつかの対応が必要になったので記載します。
4.1.1. Asciidoc ファイルのファイル名の扱い
基本的に .adoc 拡張子のみを対応しています。
またrootディレクトリ直下の index- プリフィックスのみコンバート処理を実施します。
さらに README.adoc はコンバート処理を考慮しない様にしています。
そして、define- プリフィックスのものは特に注意が必要です。
この要件は以下の記載を上記以外のファイルに行うことで、記載しやすくしています。
1
2
3
4
5
6
7
8
9
10
== タイトル
:includedir: ../../
include::{includedir}contents/defines/define-all-include.adoc[]
ifeval::[{env} == vscode]
ifndef::imagesdir[]
:imagesdir: ../../
endif::imagesdir[]
endif::[]
本文
| 1 | ここでのパスはプロジェクト(ドキュメント)ルートへの相対パスを設定 |
これにより画像は全てプロジェクト(ドキュメント)ルートからのフルパス(VS codeでファイル右クリックで相対パスってとったパス)を指定することでPDFもHTMLも問題なく出力できます。 一方で、includeは {homedir} てつけるとフルパス、自分同じ場所か配下なら {homedir} をつけずに相対パスにして扱うことができます。
4.1.2. ディレクトリ名を指定する属性の話
- includedir
-
この指定は本ドキュメント固有のCustom Document Attributeです。この指定を利用することでincludeを指定しやすくしています。
本指定をindexは空、個別のファイルを相対パスで行うことで、複雑なディレクトリ構成でのincludeの指定を容易にしています。
この定義の名称は Asciidocterの公式ドキュメントのInclude file resolutionを参考にしています。 - basedir
-
Asciidocに定義されたBuilt-In Document Attributeです。この定義はCLIで動作する際にフルパスで値が設定されるため利用していません。
- imagesdir
-
asciidocに定義された default asset directory Attributeです。この定義はHTML(:data-uri:のしては除く) の場合と画像を埋め込みするPDFで扱いが変わるため、CLIで指定します。画像へのリンクは(ドキュメント)ルートからのフルパスを利用することになります。
- iconsdir
-
asciidocに定義された default asset directory Attributeです。現在は利用していませんし、動作の解析もしていません。
- stylesdir
-
asciidocに定義された default asset directory Attributeです。この定義はおそらくHTMLの場合のみ利用されますが、現在は利用していませんし、動作の解析もしていません。
- scriptsdir
-
asciidocに定義された default asset directory Attributeです。この定義はおそらくHTMLの場合のみ利用されますが、現在は利用していませんし、動作の解析もしていません。