[トップページへのリンク](https://www.cs.k.tsukuba-tech.ac.jp/labo/sekita/takeshita/training_alone/)
[このページのMarkdownファイルへのリンク](z図による説明トレーニング.md)
本ページは、
[関田、竹下：視覚障害者の利用しやすさを目指したチャート記述法 ─Markdownによる─、筑波技大テクノレポート、vol.31, pp.28-35](https://tsukuba-tech.repo.nii.ac.jp/records/2000105)
を、改訂したものである。
# 視覚障害者の利用しやすいMarkdownによるチャート表現
## 1 概念の表現
概念はチャートの中でのノードに相当し、概念には、他者から観測可能な概念と観測できない概念の２種類がある。
観測可能な概念は四角い枠で囲んで表現し、観測できない概念は楕円もしくは楕円のような角の丸い枠で囲んで表現する。
そして、枠の中に概念の名称を書く。
### 1.1 観測可能な概念
Mermaidでは、flowchartの中で、概念の名称を書けば、四角い枠で囲まれる。
例えば、Mermaidで観測できる「概念Ａ」では、
```
flowchart
概念Ａ
```
により、図１が描画される。
```mermaid
flowchart
概念Ａ
```
**図１ 「概念A」が観測可能であることを表す**
なお同じものを、概念ラベルを付記して、
```
概念ラベル[概念の名称]
```
でも表現可能である。
概念ラベルは、その概念を再び参照する際に用いられる名前であり、単に記述するだけならば短い記号などのほうが複数回記述するときに楽ではある。
しかし、一般に短く単純な記号からは概念の名称を想起しにくく、視覚障害者にとって把握のために遡って見直すことは容易ではないので、なおさら負担が大きい。
そこで、概念ラベルから概念の名称を想起しやすくするために、以下のルール１を推奨する。
### 推奨ルール１ 「概念ラベル」は、「概念の名称」を容易に想起できる要約したもの（同じでも良い）とする
例えば、図１では、
```
flowchart
概念Ａ[概念Ａ]
```
または、
```
flowchart
観可な概念Ａ[概念Ａ]
%% 「観可な」とは「観測可能な」を表す。
```
と記述できる。
ここに、概念ラベルでの「観可な」とは「観測可能な」を表すとし、チャートの中に観測可能な概念と観測不可能な概念とが混在するときには、「観可な」や「観不な」を付けると、枠の形だけでなく、概念ラベルで文字として明記できる。
**コメント行**は、
%%
から始めることで、その行はチャートで表出されなくなる。
### 1.2 観測できない概念
観測できない概念は、枠の形で、観測可能なことを表す四角形から、観測できないことを表す楕円形で表現する。Mermaidのflowchartの中で、
```
概念ラベル([概念の名称])
```
を書けばよい。
例えば、Mermaidで観測できない「概念Ｂ」は、
```
flowchart
概念Ｂ([概念Ｂ])
```
または、
```
flowchart
観不な概念Ｂ([概念Ｂ])
%% 「観不な」とは「観測不可能な」を表す。
```
により、図２が描画される。
```mermaid
flowchart
概念Ｂ([概念Ｂ])
```
**図２ 「概念B」が観測できないことを表す**
なお、概念の名称や以下でのsubgraphの名称などに特殊な役割を持つ文字が含まれてエラーが生じる場合には、**ダブルコーテーション**で名称などを囲めばよい。
## 2 関係や推移の表現
概念間に関係のあることをリンク（線）で表し、関係に向きがあるときは細線の矢印で表す。
また、概念が段階的に推移することを、太い矢印で表す。
Mermaidでは、細線の矢印と太線の矢印とを表現できるが、プレビューした矢印を視覚的に区別することがしばしば困難であるため、ここでは細線と点線とを同じ意味で用いることにし、細線の代わりに点線を用いることにする。
### 2.1 概念間の関係
例えば、「概念Ａ」から「概念Ｂ」に関係があるとき、Mermaidで
flowchart LR
概念Ａ .-> 概念Ｂ
により、図３が描画される。
```mermaid
flowchart LR
概念Ａ .-> 概念Ｂ
```
**図３ 「概念A」から「概念B」に関係のあることを表す**
flowchartの右側の**LR**はLeft to Right の意味であり、矢印の向きを指定するが、複雑なチャートの場合に、矢印の向きを制御することは難しい。プレビューしたときの概念の位置関係は、チャートの内容などに依存する。
その他、**RL**はRight to Left、**TB**はTop to Bottom、**BT**はBottom to Topがある。
Mermaidによる記述は、基本的に概念間の論理的な関係を示すためのものである。
関係に向きがない場合には、記号 **>** の代わりに、 **o** を、点線 .- や太線 == の両側に付けるとよい。例えば、図３において、「概念Ａ」と「概念Ｂ」を点線でつなぐには、Mermaidで
```
flowchart LR
概念Ａ o.-o 概念Ｂ
```
により、図４が描画される。
```mermaid
flowchart LR
概念Ａ o.-o 概念Ｂ
```
**図４ 「概念A」と「概念B」との間に関係のあることを表す**
両方向の向きで関係があることを明記するには、Mermaidで
```flowchart LR
概念Ａ <.-> 概念Ｂ
```
により、図５が描画される。
```mermaid
flowchart LR
概念Ａ <.-> 概念Ｂ
```
**図５ 「概念A」から「概念B」に、「概念B」から「概念A」に、関係のあることを表す**
概念間の関係がどのような関係なのかを明記する場合には、リンク（線や矢印）の後に記号｜を使って関係性を囲んで記述する。
例えば、「概念Ａ」から「概念Ｂ」へ「関係Ｃ」があるとき、Mermaidで
```
flowchart LR
概念Ａ .-> |関係Ｃ|概念Ｂ
```
により、図６が描画される。
```mermaid
flowchart LR
概念Ａ .-> |関係Ｃ|概念Ｂ
```
**図６ 「概念Ａ」から「概念Ｂ」へ「関係Ｃ」があることを表す**
### 2.2 段階の推移
例えば、「段階Ａ」から「段階Ｂ」へ段階が推移したとき太線で関係を示すため、Mermaidで
flowchart LR
段階Ａ ==> 段階Ｂ
により、図７が描画される。
```mermaid
flowchart LR
段階Ａ ==> 段階Ｂ
```
**図７ 「段階Ａ」から「段階Ｂ」へ段階が推移することを表す**
## 3 概念の循環
関係を表すリンクがループ状になっているとき、循環という。
例えば、「概念Ａ」から「概念Ｂ」へ、「概念Ｂ」から「概念Ｃ」へ、「概念Ｃ」から「概念Ａ」へ関係があるとき、Mermaidでは、個々の関係ごとに１行で書き合計３行で書くこともできるが、循環を明記するために１行で、
```
flowchart LR
概念Ａ .-> 概念Ｂ .-> 概念Ｃ .-> 概念Ａ
```
により、図８が描画される。
```mermaid
flowchart LR
概念Ａ .-> 概念Ｂ .-> 概念Ｃ .-> 概念Ａ
```
**図８ 「概念Ａ」、「概念Ｂ」、「概念Ｃ」の関係が循環していることを表す**
### 3.1 循環が部分的に生じている場合
循環が明示されているMermaidの表現（図９）と、概念ＢやＣから複数の概念への関係があることが明示されているMermaidの表現（図10）（1.4参照）がある。どちらがよいかは、作成者の意図（重要度）に基づいて採用するのが良いだろう。
```
flowchart LR
概念Ａ .-> 概念Ｂ .-> 概念Ｃ .-> 概念Ａ
概念Ｂ .-> 概念Ｄ
概念Ｃ .-> 概念Ｅ
%% 概念Ａ、Ｂ、Ｃが循環していることを明記
```
または、
```
flowchart LR
概念Ａ .-> 概念Ｂ
概念Ｂ .-> 概念Ｃ & 概念Ｄ
概念Ｃ .-> 概念Ａ & 概念Ｅ
```
により、図９が描画される。
```mermaid
flowchart LR
概念Ａ .-> 概念Ｂ .-> 概念Ｃ .-> 概念Ａ
概念Ｂ .-> 概念Ｄ
概念Ｃ .-> 概念Ｅ
%% 概念ＢやＣから複数の概念に関係していることを明記
```
**図９ チャートの一部に、概念Ａ、Ｂ、Ｃの循環が存在している図**
## 4 １つの概念が複数の概念へ関係するとき
１つの概念から２つの概念に矢印があるときを考える。
例えば、「概念Ａ」から「概念Ｂ」に関係があり、「概念Ａ」から「概念Ｃ」にも関係があるときを考える。
この場合、２つの関係を２行で記述してもよいが、直ちに複数の概念と関係のあることを把握できるようにするために、以下のルール２を推奨する。
### 推奨ルール２ １つの概念から複数の概念への関係があるときの表記法
概念間の関係を明記する必要がないとき、または、概念間の関係が同一のとき、関係先の複数の概念を記号 **＆** を用いて列記する。
例えば、「概念Ａ」から「概念Ｂ」にも「概念Ｃ」にも関係があり、どのような関係があるかを明記する必要がなければ、Mermaidで、
```
flowchart LR
概念Ａ .-> 概念Ｂ & 概念Ｃ
```
により、図10が描画される。
```mermaid
flowchart LR
概念Ａ .-> 概念Ｂ & 概念Ｃ
```
**図10 「概念Ａ」が「概念B」にも「概念C」にも関係のあることを表す**
「概念Ａ」から「概念Ｂ」にも「概念Ｃ」にも関係があり、同一の関係性Ｄがあるとき、Mermaidで、
```
flowchart LR
概念Ａ .-> |関係性Ｄ|概念Ｂ & 概念Ｃ
```
により、図11が描画される。
```mermaid
flowchart LR
概念Ａ .-> |関係性Ｄ|概念Ｂ & 概念Ｃ
```
**図11 「概念Ａ」が「概念B」にも「概念C」にも同一の関係性Ｄのあることを表す**
## 5 比較
選択枝Ａと選択枝Ｂを比較し、それぞれの選択枝を採用したときにどのような処理に進むのかを示すことを考える。
現在、以下の複数の記述方法を検討中である。
### 5.1 枠の形状をひし形に
比較時の判断を強調するために枠の形状をひし形にすると、
以下では、ひし形に入れる文字を途中で改行することで、ひし形の大きさを小さくできる。改行のためには、
を挿入すればよい。
```
flowchart TD
比較何々{"何々に
ついて" } .-> |比較対象Ａ|Ａの考察
比較何々 .-> |比較対象Ｂ|Ｂの考察
```
により、図12が描画される。
```mermaid
flowchart TD
比較何々{"何々に
ついて" } .-> |比較対象Ａ|Ａの考察
比較何々 .-> |比較対象Ｂ|Ｂの考察
```
**図12 選択のための判断をひし形で表すとき**
### 5.2 枠の形状を六角形に
図12で、スペースを節約するために、ひし形でなく上下の頂点部分を水平にした六角形にすると、
```
flowchart TD
比較何々{{"何々について" }} .-> |比較対象Ａ|Ａの考察
比較何々 .-> |比較対象Ｂ|Ｂの考察
```
とすることもでき、図13が描画される。
```mermaid
flowchart TD
比較何々{{"何々について" }} .-> |比較対象Ａ|Ａの考察
比較何々 .-> |比較対象Ｂ|Ｂの考察
```
**図13 選択のための判断を六角形で表すとき**
## 6 分類
複数の項目を、意味、形状など、各種見地から似ている仲間を近くに集めるという分類を考える。
ここでも検討中の複数の記述方法を示す。
### 6.2 PlantUMLの配置図を使用
PlantUMLの配置図では、階層が深いほど下方に表出される。
またノードの形は各種ある。ここでは角が若干丸い四角形（card）の例を示す。
記号 ~~ は点線を表す。
例えば、項目aとbが見出し1に分類され、項目cが見出し2に分類されるとき、PlantUMLでは、
```
@startuml
card 見出し1
card 見出し2
card 項目a
card 項目b
card 項目c
見出し1 ~~ 項目a
見出し1 ~~ 項目b
見出し2 ~~ 項目c
```
により、図14-1が描画される。
```plantuml
@startuml
card 見出し1
card 見出し2
card 項目a
card 項目b
card 項目c
見出し1 ~~ 項目a
見出し1 ~~ 項目b
見出し2 ~~ 項目c
```
**図14-1 項目aとbが見出し1に分類され、項目cが見出し2に分類されるとき**
項目aとbが見出し1に分類され、項目dは項目bに分類され、項目cが見出し2に分類されるとき、PlantUMLでは、
```
@startuml
card 見出し1
card 見出し2
card 項目a
card 項目b
card 項目c
card 項目d
見出し1 ~~ 項目a
見出し1 ~~ 項目b
見出し2 ~~ 項目c
項目b ~~ 項目d
```
```plantuml
@startuml
card 見出し1
card 見出し2
card 項目a
card 項目b
card 項目c
card 項目d
見出し1 ~~ 項目a
見出し1 ~~ 項目b
見出し2 ~~ 項目c
項目b ~~ 項目d
```
**図14-2 さらに項目dが項目bに分類されるとき**
## 7 見通し
ある数値の変動の概要を視覚的に表現することを考える。
ここでも検討中の複数の記述方法を示す。
### 7.1 Mermaidのjourney diagramを使用
Mermaidでは、journey diagram を使うと、簡潔に表記できる。
journey diagramの見方は、矢印で推移のベースとなっている軸を表し、その下にある顔マークの位置と表情で数値の高さを表す。
例えば、数値の見通しが、現在 1%で、5年後に6%とすると、Mermaidで
```
journey
section 数値の見通し
現在:1:数値１％
５年後:6:数値６％
```
により、図15が描画される。
```mermaid
journey
section 数値の見通し
現在:1:数値１％
５年後:6:数値６％
```
図15 数値の見通しが、現在 1%で、5年後に6%であることを表す
### 7.2 PlantUMLの配置図を使用
上記1.7.1と同じ意味で、「数値１％」から「数値６％」への見通しを右上に向かう太矢印で示すことを考える。
このためにPlantUMLの配置図を使用する。
ただし、「数値１％」の下に「現在」を置き、「数値６％」の下に「５年後」を置くが、さらに、「数値１％」の上に太矢印で連結して「数値６％」を置き、且つ、「現在」の右に矢印で連結して「５年後」を置くことを指定した、若干無理のある配置を指定することで、「数値６％」が「数値１％」の右上に来ることを期待している。
すなわち、PlantUMLで、
```
@startuml
usecase "数値１％"
usecase "数値６％"
rectangle "現在"
rectangle "５年後"
"数値１％" ~~ "現在"
"数値６％" ~~ "５年後"
"数値１％" =u=> "数値６％"
"現在" -r-> "５年後"
@enduml
```
により、図16が描画される。
```plantuml
@startuml
usecase "数値１％"
usecase "数値６％"
rectangle "現在"
rectangle "５年後"
"数値１％" ~~ "現在"
"数値６％" ~~ "５年後"
"数値１％" =u=> "数値６％"
"現在" -r-> "５年後"
@enduml
```
**図16 1.7.1と同じ意味を表すPlantUMLの配置図**
## 8 評価軸
４つの領域をつくり、その中央に評価軸を明記し、複数の項目を配置したい。
しかし、今のところ評価軸をMarkdownで明記することは難しい。
そこで、評価軸を文字から類推してもらう方法を示す。
例えば、評価軸１と２があり、評価軸１が大きく評価軸２が小さいところに項目Aがあり、評価軸１が小さく評価軸２が大きいところに項目Bがあるとする。MermaidのQuadrant Chartを用いると、
```
quadrantChart
title 評価軸１、２における項目Ａ、Ｂの配置
x-axis "評価軸１が小" --> "評価軸１が大"
y-axis "評価軸２が小" --> "評価軸２が大"
"項目Ａ": [0.75, 0.25]
"項目Ｂ": [0.25, 0.75]
```
により、図17が描画される。
```mermaid
quadrantChart
title 評価軸１、２における項目Ａ、Ｂの配置
x-axis "評価軸１が小" --> "評価軸１が大"
y-axis "評価軸２が小" --> "評価軸２が大"
"項目Ａ": [0.75, 0.25]
"項目Ｂ": [0.25, 0.75]
```
**図17 「評価軸１」が大きく「評価軸２」が小さいところに「項目Ａ」があり、「評価軸１」が小さく「評価軸２」が大きいところに「項目Ｂ」があることを表す**
## 9 組織図
階層的に構成されている組織の組織図を考える。
ここでは、PlantUMLの作業分解図wbs (work breakdown structure)を使用して木構造で表現する方法を示す。
例えば、部１には課Ａ、Ｂがあり、部２には、課Ｃがあるとき、PlantUMLの作業分解図で、
```
@startwbs
* 組織名
** 部１
*** 課Ａ
*** 課Ｂ
** 部２
*** 課Ｃ
@endwbs
```
により、図18が描画される。
```plantuml
@startwbs
* 組織名
** 部１
*** 課Ａ
*** 課Ｂ
** 部２
*** 課Ｃ
@endwbs
```
**図18 「部１」には「課Ａ、Ｂ」があり、「部２」には「課Ｃ」がある組織図を表す**
その他、Markdownで階層構造を表現する方法は複数ある。
例えば、前述のPlantUMLのmindmapを使う方法、Mermaidのflowchartのsubgraphを使う方法なども考えられる。
## 10. Markdownからチャートを把握しやすくするための追加推奨ルール
単純な図に対する推奨ルールは、前述の1.1.2や1.4で示した。ここでは、subgraphを複数用いて記述する際に推奨したいルールを示す。
三森ゆりか「ビジネスパーソンのための『言語技術』超入門(2021) 」の第３章にわかりやすく情報を組み立てるポイントが書かれている。これらの中から特に、「包括度の割合に従って優先度を決める。基本的には『大きいものから小さいもの』」と「重要度の高いものから低いもの」と「経過や段階に従って情報を示す」に基づいて、記述していくものとする。
### 推奨ルール３ 大局的なもの後に局所的なものを記述
大局的なものの記述を、細部の局所的な記述よりも優先する。
例えば、subgraphが入れ子構造になっている場合、外側のsubgraphの内側にある詳細なsubgraphの内容は、外側のsubgraphの中に展開して記述することをせず、外側のsubgraphの記述では要素を示すだけにとどめて、各要素の詳細はその後のsubgraphに記述する。
例えば、概念Aには概念a1と概念a2を含み、概念a1には概念a11が含まれることを表すチャート
```mermaid
flowchart LR
subgraph 概念A
概念a1
概念a2
end
subgraph 概念a1
概念a11
end
%% 大局を記述した後に詳細を記述する方法
```
**図19 概念Aには概念a1と概念a2を含み、概念a1には概念a11が含まれるとき**
を記述するときに、
```
flowchart LR
subgraph 概念A
概念a1
概念a2
end
subgraph 概念a1
概念a11
end
%% 大局を記述した後に詳細を記述する方法
```
の記述を推奨し、
```
flowchart LR
subgraph 概念A
subgraph 概念a1
概念a11
end
概念a2
end
%% 対局の中に詳細を記述する方法
```
の記述はできるだけ避けるようにする。
----------------
## お問い合わせ
### **Markdown** についての質問・相談は以下のメールアドレスにどうぞ。
筑波技術大学 保健科学部 情報システム学科 関田巖
E-Mail：sekita＝cs.k.tsukuba-tech.ac.jp([ = ] を [ @ ] にしてください)
### **トレーニング全般**にわたる質問・相談は以下のメールアドレスにどうぞ。
個別ワークのご相談も可能です。
※セルフワークのモニターを募集しています。
筑波技術大学 保健科学部 竹下浩
E-Mail：takeshita＝k.tsukuba-tech.ac.jp([ = ] を [ @ ] にしてください)