There are two new documentation features that have landed forUnison Share,support formermaid diagramsandLaTeX.
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``` mermaidblock.
_mermaid1 : base.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 thesyntax 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. Thebase.Docformat 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 Unisonbase.Doc,much like when writingstandard markdown,the triple backtick codeblock optionally takes a language argument. If the UI seesmermaid,it will use themermaid.jslibrary to render the diagram, and if it seeslatex,it will use theKatexlibrary 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 functionscan 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: givenAlvaro'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 theCodeBlockdata constructor. It looks something likeCodeBlock "mermaid" (Word textualRepresentationOfDiagram).Check out this static example from Unison teammate Cody Allenhere on Unison Sharefor 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 thebase.Docformat, we've included a few useful symbols below!
_composition : base.Doc
_composition =
{{
``` latex
(a \circ b)
```
}}(a \circ b)Basic arrows:
\begin{CD}
@<<<
@AAA
@VVV
@.
@>>>
@=
@|
\end{CD}Labled arrows:
_labeledArrows : base.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!