Graphs at Axional Docs can be done through graphviz, ditaa & sequence diagrams.

Three graph implementation methods are available at Axional Docs:

• graphviz tag: <graph title"...">
• ditaa tag: <ditaa>
• Sequence diagrams tag: <graph-sequence>

# 1 Graphviz

Graphviz is an open source graph visualization software. Graph visualization is a way of representing structural information as diagrams of abstract graphs and networks. It has an important applications in networking, bioinformatics, software engineering, database and web design, machine learning and in visual interfaces for other technical domains.

To utilize graphviz in Axional Docs the tag <graph> </graph> is used. The graphs might be scaled to make them bigger or smaller using the attribute scale. The graphviz layout programs take descriptions of graphs in a simple text language and makes "hierarchical" or layered drawings of directed graphs.
Graphs are written following this structure. Graph or digraph will be selected depending on the situation.

Copy
<graph title='Title of Graph' scale=".6"(optional)>
graph nameOfGraph(optional) {
Code of Graph
}
</graph>

## 1.1 Syntax

### 1.1.1 Graph or Digraph

Graphviz allows us to create two different kind of graph

• Simple Graph: This is an non directed graph (graph)
• Digraph: This is a directed graph (digraph)

A graph must be specified as either a digraph or a graph. Semantically, this indicates whether or not there is a natural direction from one of the edge's nodes to the other. Lexically, a digraph must specify an edge using the edge operator -> while a non directed graph must use --. Operationally, the distinction is used to define different default rendering attributes. For example, edges in a digraph will be drawn, by default, with an arrowhead pointing to the head node. For ordinary graphs, edges are drawn without any arrowheads by default.

#### Simple Graph

To write an non directed graph the option "graph" will be selected and the connections will be written with "--"

Example

Code

Copy
<section title='Graph example'>
<graph title='Non directed graph'>
graph {
NodeA -- NodeB;
}
</graph>
</section>

Graph

### Non directed graph

#### Digraph

To write a directed graph the option "digraph" will be selected and the connections will be written with "->"

Example

Code

Copy
<section title='Graph example'>
<graph title='Directed graph'>
digraph {
NodeA -> NodeB;
}
</graph>
</section>

Graph

### Directed graph

This is an example of a simple digraph

Example

Code

Copy
<section title='Graph example'>
<graph title='Directed graph'>
digraph {
a -> b[label="0.2",weight="0.2"];
c -> b[label="0.6",weight="0.6"];
c -> e[label="0.6",weight="0.6"];
e -> e[label="0.1",weight="0.1"];
e -> b[label="0.7",weight="0.7"];
}
</graph>
</section>

Graph

### 1.1.2 Add Nodes

This is a first example of how graphviz nodes are implemented and how nodes are connected between them.

Example

Code

Copy
<section title='Example 1 Graphviz'>
<graph title='Example 1 Graphviz'>
digraph G {
main -> parse -> execute;
main -> init;
main -> cleanup;
execute -> make_string;
execute -> printf
init -> make_string;
main -> printf;
execute -> compare;
}
</graph>
</section>

Graph

### 1.1.3 Drawing Attributes

The next example shows how to change different drawing attributes

Example

Code

Copy
<section title='Example 2 Graphviz'>
<graph title='Drawing Attributes'>
digraph G {
size ="4,4";
main [shape=box]; /* this is a comment */
main -> parse [weight=8];
parse -> execute;
main -> init [style=dotted];
main -> cleanup;
execute -> { make_string; printf}
init -> make_string;
edge [color=red];
main -> printf [style=bold,label="100 times"];
make_string [label="make a\nstring"];
node [shape=box,style=filled,color=".7 .3 1.0"];
execute -> compare;
cleanup [shape=polygon,sides=5,peripheries=3,color=lightblue,style=filled]; //Other shapes are allowed
}
</graph>
</section>

Graph

### Drawing attributes

After the code line "edge [color=red];": All the other lines rendered are painted in red.
The same happens after "node [shape=box,style=filled,color=".7 .3 1.0"];", all the following found nodes are rendered with this characteristics

### 1.1.4 Subgraphs and Clusters

Subgraphs play three roles in Graphviz. First, a subgraph can be used to represent graph structure, indicating that certain nodes and edges should be grouped together. This is the usual role for subgraphs and typically specifies semantic information about the graph components. It can also provide a convenient shorthand for edges. An edge statement allows a subgraph on both the left and right sides of the edge operator. When this occurs, an edge is created from every node on the left to every node on the right. For example, the specification

A -> {B C}

Is equivalent to:

A -> B
A -> C

In the second role, a subgraph can provide a context for setting attributes. For example, a subgraph could specify that blue is the default color for all nodes defined in it. In the context of graph drawing, a more interesting example is:

subgraph {
rank = same; A; B; C;
} 

This (anonymous) subgraph specifies that the nodes A, B and C should all be placed on the same rank if drawn using dot.
The third role for subgraphs directly involves how the graph will be laid out by certain layout engines. If the name of the subgraph begins with cluster, Graphviz notes the subgraph as a special cluster subgraph. If supported, the layout engine will do the layout so that the nodes belonging to the cluster are drawn together, with the entire drawing of the cluster contained within a bounding rectangle. Note that, for good and bad, cluster subgraphs are not part of the DOT language, but solely a syntactic convention adhered to by certain of the layout engines.

#### Subgraph

The next example shows how make a subgraph

Example

Code

Copy
<section title='Example 3 Graphviz'>
<graph title='Example 3 Graphviz'>
digraph G {
compound=true;
subgraph cluster0 {
a -> b;
a -> c;
b -> d;
c -> d;
}
subgraph cluster1 {
e -> g;
e -> f;
}
b -> f [lhead=cluster1];
d -> e;
c -> g [ltail=cluster0,
c -> e [ltail=cluster0];
d -> h;
}
</graph>
</section>

Graph

### Subgraphs example

Only new nodes are situated inside the subgraph

## 1.2 Graphviz examples

The following section show example of graphviz.

Example

Code

Copy
<section title='Example 4 Graphviz'>
<graph title="Application view">
digraph {
graph [fontsize=10 fontname="Verdana" compound=true];
node  [shape=record fontsize=10 fontname="Verdana" style=filled fillcolor="#99ccff"];
edge  [color=gray];
overlap=scale; # (try to) stretch everything if edges overlap
splines=ortho;

subgraph cluster_1 {
style=dotted;
label="J2EE Server Node #1";

HTTP	 -> Filters;
Filters -> REST;
Filters -> SOAP;
Filters -> Servlet;
REST    -> Application;
SOAP    -> Application;
Servlet -> Application;
Application -> JDBC;
JDBC -> EJBCache;
}

subgraph cluster_db {
label="Databases";
db1
db2
}

internet -> balancer;
balancer -> HTTP;

JDBC     -> db1;
EJBCache -> db1;

JDBC     -> db2;
EJBCache -> db2;

Application [style=filled fillcolor="#00cc00"];
EJBCache    [style=filled fillcolor="#00cc00"];
internet    [style=filled fillcolor="#ff3300" fontcolor="#FFFFFF"];
balancer    [style=filled fillcolor="#ff0066" fontcolor="#FFFFFF"];
db1         [style=filled fillcolor="#cccc00" fontcolor="#FFFFFF" label="Primary DB"];
db2         [style=filled fillcolor="#cccc00" fontcolor="#FFFFFF" label="Replica DB"];
}
</graph>
</section>

Graph

### Example

Example

Code

Copy
<section title='Example 5 Graphviz'>
<graph scale=".8" title="4 tier (Axional Ecom)">
digraph G {
node [shape=record fontsize=10 fontname="Verdana"];
rankdir=LR;
Recursos -> "Front End Server" -> "Back End Server" -> Database
}
</graph>
</section>

Graph

### Example

Example

Code

Copy
<section title='Example 6 Graphviz'>
<graph scale=".6" title="BlockingQueuePool lifecycle">
digraph {
request -> decision

used    [style="fill:#FFBF00"];
free    [style="fill:#01A9DB"];
failed  [style="fill:#FF0000"];
use     [shape=circle, style="fill:#40FF00"]
space   [shape=diamond, label="size < PoolMaxSize ?"];
time_a  [shape=diamond, label="t < AcquireTimeout ?"];
time_c  [shape=diamond, label="t < BornDieTimeout ?"];
subgraph Health {
health1 [shape=diamond, label="Expired ?"];
health2 [shape=diamond, label="used > CheckOutCount ?"];
health3 [shape=diamond, label="Health ok ?"];
}
ofactory  [shape=ellipse, label="Object Factory"];

decision [shape=diamond, label="Exists in free pool ?"];
decision -> free [label="Yes"];
decision -> space [label="No"];

free   ->  health1
health1 -> health2  [label="No"];
health1 -> ofactory [label="Yes"];
health2 -> health3  [label="No"];
health2 -> ofactory [label="Yes"];
health3 -> ofactory [label="No"];
health3 -> used     [label="Yes"];

space -> ofactory  [label="Yes"];
ofactory -> create
create -> time_c
time_c -> used     [label="Yes"];
time_c -> failed   [label="No"];
space -> time_a    [label="No"];
time_a -> failed   [label="No"];
time_a -> decision [label="Yes"];
used  -> use
use -> free
}
</graph>
</section>

Graph

### Example

To test new graphs using graphviz click here or

# 2 Ditaa

Ditaa is a small command-line utility written in Java, that can convert diagrams drawn using ascii art ('drawings' that contain characters that resemble lines like | / - ), into proper bitmap graphics. Ditaa interprets ascii art as a series of open and closed shapes, but it also uses special markup syntax to increase the possibilities of shapes and symbols that can be rendered. This is best illustrated by the following example

To use ditaa in Axional Docs the tag <ditaa> </ditaa> is used.

It may be necessary to install the package "fontconfig" in your Linux operating system. You can use the common package managers:
Copy
yum install fontconfig
Example

Code

Copy
<section title='ditaa1'>
<ditaa>
<![CDATA[
+--------+   +-------+    +-------+
|        | --+ ditaa +--> |       |
|  Text  |   +-------+    |diagram|
|Document|   |!magic!|    |       |
|     {d}|   |  c478 |    |       |
+---+----+   +-------+    +-------+
:                         ^
|       Lots of work      :
+-------------------------+
]]>
</ditaa>
</section>

Result

## 2.1 Syntax

### 2.1.1 Tags

Some tags may be used to set different formats to the different boxes. The tags must be written inside the ASCII box at which they are referring.

Tag Description
{c} decision(Choice)
{d} document
{io} input/output, parallelogram
{mo} manual operation
{o} ellipse, circle
{s} storage
{tr} trapezoid (looks like an inverted {mo} )

Ditaa recognises some tags that change the way a rectangular shape is rendered. All tags are between { and }. See the table below:

Name Original Rendered Comment
Document
+-----+
|{d}  |
|     |
|     |
+-----+
Symbol representing a document.
Storage
+-----+
|{s}  |
|     |
|     |
+-----+
Symbol representing a form of storage, like a database or a hard disk.
Input/Output
+-----+
|{io} |
|     |
|     |
+-----+
Symbol representing input/output.

### 2.1.2 Corners

Corners can be painted as a sharp corner or as a round corner. If you use / and \ to connect corners, they are rendered as round corners. Meanwhile if you use + to connect corners, they are rendered as sharp corners

Example

Code

Copy
<section title='ditaa1'>
<ditaa>
<![CDATA[
/--+
|  |
+--/
]]>
</ditaa>
</section>

Result

### 2.1.3 Colour

Color codes can be used to add color to the diagrams. The syntax of color codes is "cXXX" where "XXX" is a hex number. The first digit of the number represents the red component of the color, the second digit represents green and the third blue (good ol' RGB). See below for an example of use of color codes:

Example

Code

Copy
<section title='ditaa1'>
<ditaa>
<![CDATA[
/----\ /----\
|c33F| |cC02|
|    | |    |
\----/ \----/
/----\ /----\
|c1FF| |c1AB|
|    | |    |
\----/ \----/
]]>
</ditaa>
</section>

Result

Some colours can be called with a human readable color codes:

Example

Code

Copy
<section title='ditaa1'>
<ditaa>
<![CDATA[
/-------------+-------------\
|cRED RED     |cBLU BLU     |
+-------------+-------------+
|cGRE GRE     |cPNK PNK     |
+-------------+-------------+
|cBLK BLK     |cYEL YEL     |
\-------------+-------------/
]]>
</ditaa>
</section>

Result

As you can see above, if a colored shape contains any text, the color of the text is adjusted according to the underlying color. If the underlying color is dark, the text color is changed to white (from the default black).

Note that color codes only apply if they are within closed shapes, and they have no effect anywhere outside.

### 2.1.4 Lines

Lines, connection lines or box lines, can be rendered continuous or dashed. Any element that contain either at least one = (for horizontal lines) or at least one : (for vertical lines) are rendered as dashed lines, otherwise a continuous line will be rendered.

Example

Code

Copy
<section title='ditaa1'>
<ditaa>
<![CDATA[
----+  /----\  +----+  ----+  /----\  +----+
:  |    |  :    |      |  |    |  |    |
|  |    |  |{s} |      |  |    |  |{s} |
v  \-=--+  +----+      v  \----+  +----+
]]>
</ditaa>
</section>

Result

### 2.1.5 Point markers

If * is encountered on a line (but not at the end of the line), it is rendered as a special marker, called the point marker

Example

Code

Copy
<section title='ditaa1'>
<ditaa>
<![CDATA[
*----*
|    |      /--*
*    *      |
|    |  -*--+
*----*
]]>
</ditaa>
</section>

Result

## 2.2 ditaa examples

Now you can find some more complex ditaa examples:

Example

Code

Copy
<section title='ditaa1'>
<ditaa>
<![CDATA[
|                                 |
programmers | maintainers         maintainers | users
|                                 |
+----+----+                        +---+----+
/--------------\        |         |                        |        |
|regular commit+----=---+ default |                        | stable |
\--------------/        |         |                        |        |
|         |                        |        |
/--------------\        |         |                        |        |
|regular commit+----=---+         |                        |        |
\--------------/        |         |                        |        |
|         +-------release merge--->|        |
...                    |         |                        |        |
|         |                        |        |
|         |        /-----------\   |        |
|         |<-merge-+release tag+-=-+        |
|         |        \-----------/   |  cBLU  |
|         |                        |        |
+----------------+   |         |                        |        |
|                |<--+         |                        |        |
| feature branch |   |  cGRE   |                        |        |
|            {d} |   |     {d} |                        |    {d} |
+----+------+----+   |         |        /-----------\   |        |
:      |        |         |<-merge-+hotfix cRED+-=-+        |
|      |        |         |        \-----------/   |        |
|      |        |         |                        |        |
|      +-merge->|         |                        |        |
|               |         |                        |        |
|               +---------+                        +--------+
|
/-------+------\
|regular commit|                           +--------------------+
\--------------/                           |  Glossary          |
|                    |
...                                       | --- branch change  |
| -=- stay on branch |
+--------------------+
]]>
</ditaa>
</section>

Result

Example

Code

Copy
<section title='ditaa1'>
<ditaa>
<![CDATA[
|                                         |
programmers | maintainers                 maintainers | users
|                                         |
+----+----+                                +---+----+
/--------------\         |         |                                |        |
|regular commit+----=----+ default |                                | stable |
\--------------/         |         |                                |        |
|         |                                |        |
/--------------\         |         |                                |        |
|regular commit+----=----+         |                                |        |
\--------------/         |         |                                |        |
|         +------------release merge------>|        |
...                     |         |                                |        |
|         |                                |        |
|         |             /-----------\      |        |
|         |<-merge------+release tag+-=----|        |
|         |             \-----------/      |        |
|         |                                |        |
|         |                                |        |
|         |    /----------------------\    |        |
|         |    |maintained release 1.x+-=--|        |
|         |    \-----------+----------/    |  cBLU  |
+----------------+    |         |                |               |        |
|                |<---+         |                :               |        |
| feature branch |    |  cGRE   |                v               |        |
|            {d} |    |     {d} |        /-----------\           |    {d} |
+----+------+----+    |         |        |hotfix cRED|           |        |
:      |         |         |        \-------+---/           |        |
|      |         |         |                |               |        |
|      |         |         |                :               |        |
|      |         |         |                v               |        |
|      |         |         |     /-------------------\      |        |
|      |         |         |     |release tag 1.(x+1)|      |        |
|      |         |         |     \----------+--------/      |        |
|      |         |         |                |               |        |
|      |         |         |              merge             |        |
|      |         |         |                :               |        |
|      |         |         |                v               |        |
|      |         |         |    /----------------------\    |        |
|      |         |         |    |maintained release 2.y|    |        |
|      |         |         |    \-----------+----------/    |  cBLU  |
|      |         |         |                |               |        |
|      |         |         |                :               |        |
|      |         |         |                v               |        |
|      |         |         | /-------------------\          |        |
|      |         |         | |release tag 2.(y+1)+-=-merge->|        |
|      |         |         | \-------------------/          |        |
|      |         |         |               ...              |        |
|      |         |         |                                |        |
|      +-merge-->|         |<--------merge hotfix-----------+        |
|                |         |                                |        |
|                +---------+                                +--------+
|
/-------+------\
|regular commit|                           +--------------------+
\--------------/                           |  Glossary          |
|                    |
...                                       | --- branch change  |
| -=- stay on branch |
+--------------------+
]]>
</ditaa>
</section>

Result

Example

Code

Copy
<section title='ditaa1'>
<ditaa>
<![CDATA[
|                                 |
programmers | maintainers         maintainers | users
|                                 |
+----+----+                        +---+----+
/--------------\        |         |                        |        |
|regular commit+----=---+ default |   +----------------+   | stable |
\--------------/        |         |   |                |   |        |
|         +-->+  nextrelease   |   |        |
/--------------\        |         |   |  c1AB      {d} |   |        |
|regular commit+----=---+         |   +---+------+-----+   |        |
\--------------/        |         |       |      |         |        |
...                    |         |       :      |         |        |
|         |       |      |         |        |
|         |   /---+---\  |         |        |
|         +-->+ graft |  |         |        |
|         |   \-------/  |         |        |
|         |    ...       |         |        |
|         |              v         |        |
|         |                        |        |
|         |        release merge-->|        |
|         |                        |        |
|         |                        |        |
|         |        /-----------\   |        |
|         |<-merge-+release tag+-=-+        |
|         |        \-----------/   |  cBLU  |
|         |                        |        |
+----------------+   |         |                        |        |
|                |<--+         |                        |        |
| feature branch |   |  cGRE   |                        |        |
|            {d} |   |     {d} |                        |    {d} |
+----+------+----+   |         |        /-----------\   |        |
:      |        |         |<-merge-+hotfix cRED+-=-+        |
|      |        |         |        \-----------/   |        |
|      |        |         |                        |        |
|      +-merge->|         |                        |        |
|               |         |                        |        |
|               +---------+                        +--------+
|
/-------+------\
|regular commit|                           +--------------------+
\--------------/                           |  Glossary          |
|                    |
...                                       | --- branch change  |
| -=- stay on branch |
+--------------------+

]]>
</ditaa>
</section>

Result

# 3 Sequence diagrams

Axional Docs provides a way to print sequence diagrams. The tag graph-sequence is used for this purpose. Each sequence diagram must start with this element.

The following table shows what elements could be included in sequence diagrams.

This element allows users to print sequence diagrams.

<graph-sequence title='title'>    <participant name='name' /> *    <message        from='from'        to='to'        type='solid|dotted|solid_arrow|dotted_arrow|solid_async|dotted_async'        active='yes|no'    /> *    <alt> *        <if expr='expr'> +            <alt /> *            <loop /> *            <message /> *            <note /> *            <opt /> *        </if>    </alt>    <opt expr='expr'> *        <alt /> *        <loop /> *        <message /> *        <note /> *        <opt /> *    </opt>    <loop statement='statement'> *        <alt /> *        <loop /> *        <message /> *        <note /> *        <opt /> *    </loop>    <note        position='right|left|over'        of='of'    /> *</graph-sequence>
Example

Some examples of Axional Docs sequence diagrams

Copy
<graph-sequence title="Alice - John conversation">
<message from="Alice" to="John">Hello John, how are you?</message>
<message from="John"  to="Alice" type='dotted_arrow'>Great!</message>
</graph-sequence>

### Alice - John conversation

sequenceDiagram Alice->>John: Hello John, how are you? John-->>Alice: Great!
Example
Copy
<graph-sequence title="Sequence diagram activation">
<message from="Alice" to="John" active='yes'>Hello John, how are you?</message>
<message from="John"  to="Alice" type='dotted_arrow' active='no'>Great!</message>
</graph-sequence>

<graph-sequence title="Sequence diagram more than one activation">
<message from="Alice" to="John" active='yes'>Hello John, how are you?</message>
<message from="Alice" to="John" active='yes'>John, can you hear me?</message>
<message from="John"  to="Alice" type='dotted_arrow' active='no'>Hi Alice, I can hear you!</message>
<message from="John"  to="Alice" type='dotted_arrow' active='no'>I feel great!</message>
</graph-sequence>

### Sequence diagram activation

sequenceDiagram Alice->>+John: Hello John, how are you? John-->>-Alice: Great!

### Sequence diagram more than one activation

sequenceDiagram Alice->>+John: Hello John, how are you? Alice->>+John: John, can you hear me? John-->>-Alice: Hi Alice, I can hear you! John-->>-Alice: I feel great!
Example
Copy
<graph-sequence title="Sequence diagram note">
<message from="Alice" to="John">Hello John, how are you?</message>
<note position="over" of="Alice,John">A typical interaction</note>
</graph-sequence>

### Sequence diagram note

sequenceDiagram Alice->>John: Hello John, how are you? Note over Alice,John: A typical interaction
Example
Copy
<graph-sequence title="Sequence diagram loop">
<message from="Alice" to="John">Hello John, how are you?</message>
<loop statement='A typical interaction'>
<message from="John" to="Alice">Great!</message>
</loop>
</graph-sequence>

### Sequence diagram loop

sequenceDiagram Alice->>John: Hello John, how are you? loop A typical interaction John->>Alice: Great! end
Example
Copy
<graph-sequence title="Sequence diagram alt">
<message from="Alice" to="Bob">Hello Bob, how are you?</message>
<alt>
<if expr='is sick'>
<message from='Bob' to='Alice'>Not so good :(</message>
</if>
<if expr='Feeling fresh like a daisy'>
<message from='Bob' to='Alice'>Feeling fresh like a daisy</message>
</if>
</alt>
<opt expr="is sick">
<message from="Bob" to="Alice">Not so good :(</message>
</opt>
</graph-sequence>

### Sequence diagram alt

sequenceDiagram Alice->>Bob: Hello Bob, how are you? alt is sick Bob->>Alice: Not so good :( else Feeling fresh like a daisy Bob->>Alice: Feeling fresh like a daisy end opt is sick Bob->>Alice: Not so good :( end
Example
Copy
<graph-sequence title="Sequence diagram three participants example">
<participant name='Alice' />
<participant name='Bob' />
<message from="Alice" to="John">Hello John, how are you?</message>
<loop statement='Healthcheck'>
<message from="John" to="John">Fight against hypochondria</message>
</loop>
<note position="right" of="John">Rational thoughts prevail...</note>
<message from="John" to="Alice">Great!</message>
<message from="John" to="Bob">How about you?</message>
<message from="Bob" to="John">Jolly good!</message>
</graph-sequence>

### Sequence diagram three participants example

sequenceDiagram participant Alice participant Bob Alice->>John: Hello John, how are you? loop Healthcheck John->>John: Fight against hypochondria end Note right of John: Rational thoughts prevail... John->>Alice: Great! John->>Bob: How about you? Bob->>John: Jolly good!