There are two new documentation features that have landed for Unison Share, support for mermaid diagrams and LaTeX.
First, let's look at mermaid diagrams. Mermaid diagrams are textual representations for diagrams written in a markdown-inspired syntax. A variety of diagram types are supported, including sequence diagrams, flowcharts, state diagrams and gant charts. The following figure for the TCP 3-way handshake has been written in a ``` mermaid block.
_mermaid1 : Doc
_mermaid1 =
{{
``` mermaid
sequenceDiagram
Note left of Client: Sends SYN
Client->>Server: SYN
Note right of Server: Receives SYN
Note right of Server: Sends SYN + ACK
Server->>Client: SYN + ACK
Note left of Client: Receives SYN + ACK
Note left of Client: Sends ACK
Client->>Server: ACK
Note right of Server: Receives ACK
```
}}The diagram type is indicated as the first line of the block. You can learn more about the syntax for supported diagram types here.
Unison Share will render this diagram as:
sequenceDiagram
Note left of Client: Sends SYN
Client->>Server: SYN
Note right of Server: Receives SYN
Note right of Server: Sends SYN + ACK
Server->>Client: SYN + ACK
Note left of Client: Receives SYN + ACK
Note left of Client: Sends ACK
Client->>Server: ACK
Note right of Server: Receives ACKNext, something for the mathematicians in the room. The Doc format will also render LaTeX, which is commonly used in the technical or scientific communities for typsetting content that would otherwise be frustrating to express in a regular word processor. Imagine opening up your rich text editor to write the following:
f(\relax{x}) = \int_{-\infty}^\infty
\hat{f}(\xi)\,e^{2 \pi i \xi x}
\,d\xiThat would be a nightmare! Instead, you can write the following in LaTeX, like so:
What's going on here?
When writing a Unison Doc, much like when writing standard markdown, the triple backtick codeblock optionally takes a language argument. If the UI sees mermaid, it will use the mermaid.js library to render the diagram, and if it sees latex, it will use the Katex library to transform the given codeblock into its typeset form. The Katex library supports rendering the TeX dialect of LaTeX. A full summary of the supported symbols and functions can be found here.
We'd like to share our immense gratitude to Kento Okura and Simon Højberg for their work on this feature. Thanks for pushing the Doc format forward into new domains!
Give it a try!
Here's a challenge for you: given Alvaro's Unison mermaid diagram library, and the programmatic nature of Docs, can you write a program where the interactions between two entities in a Unison program are self-documenting? For example, you could render when a client calls a server or write a tool for showing how many times an algorithm passes through a basic collection. It's possible to programmatically create a fenced codeblock entity in native Unison with the CodeBlock data constructor. It looks something like CodeBlock "mermaid" (Word textualRepresentationOfDiagram). Check out this static example from Unison teammate Cody Allen here on Unison Share for inspiration.
As for the LaTeX functionality, while not everyone is looking for their Good Will Hunting moment, you might be interested in the basic commutative diagram support that the docs now provide. In anticipation of the many functional programming blogs written in the Doc format, we've included a few useful symbols below!
_composition : Doc
_composition =
{{
``` latex
(a \circ b)
```
}}(a \circ b)Basic arrows:
\begin{CD}
@<<<
@AAA
@VVV
@.
@>>>
@=
@|
\end{CD}Labled arrows:
_labeledArrows : Doc
_labeledArrows =
{{
``` latex
\begin{CD}
\text{A} @>label>> \text{B}
\end{CD}
```
}}\begin{CD}
\text{A} @>label>> \text{B}
\end{CD}Adding vertical connections:
\begin{CD}
a @>F>> Fa \\
@VgVV @VVFgV \\
b @>F>> Fb
\end{CD}We hope to see your architecture diagrams, database schemas, mathematical proofs, physics notes, and other wild inventions on Unison Share soon!