diagramas

propósito

• anotar lo relativo a usar diagramas en jekyll
• lo veo en la plantilla inicial de hugo que usa mermaid
• la web de mermaid.js

inicio

• sigo este tutorial

• un editor on-line

• importante meter la referencia a los css aunque sea a pelo

<link rel="stylesheet" href="/css/mermaid.css" />

• y al javascript al final 😄

<script type="text/javascript" src="https://cdn.rawgit.com/knsv/mermaid/6.0.0/dist/mermaid.js"></script>

• el fuente del diagrama anterior

<div class="mermaid">
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
</div>

• Lo llevo como en el caso de los gráficos en el sitio simplicity-para-javier
• una entrada en castellano en un blog sobre esto

Diagramas con mermaid

• origen

• Como ya he comentado en otras entradas, estoy estudiando para mi examen de grado. He hecho varios intentos de sistematizar el estudio mediante software, pero la verdad es que me ha servido más el formato análogo (leer, destacar, releer, resumir, leer en voz alta, leer el primer texto, revisar código, leer repetir en voz alta, explicar al amigo imaginario, etc). Sin embargo, algo que sí he usado es el lenguaje Mermaid para hacer diagramas. Y precisamente a usar este lenguaje vengo a invitar ahora.

• Uso el editor de textos atom.io al que instalé un paquete con el lenguaje mermaid propiamente tal y otro para pre visualizar los diagramas escritos en mermaid. Otra opción y la que recomiendo para quienes no estén iniciados en estas prácticas, es Haroopad, que trae integrado el soporte para Mermaid (así que no hay que instalar nada más).

• Entrando ya a picar con mermaid que es descrito en su propia página como una forma de generar diagramas y flujos de un modo similar a markdown (esto amerita otro post, pero por lo pronto, adelanto que es una forma muy sencilla de escribir documentos), es decir, está enfocado en la simplicidad. Siguiendo ese mismo ánimo, iré directo al grano.

• A continuación, un ejemplo de código y resultado:

La sintaxis, como se aprecia es muy intuitiva:

• palabracualquiera
  • se puede usar como elemento cualquier palabra única (que no contenga espacios).
• palabra[varias cosas más]
  • palabra será el elemento (para ser referida por otros elementos) pero será visible una frase más larga en el diagrama resultante.
• –>
  • flecha continua entre un elemento y otro.
• -.->
  • flecha punteada entre un elemento y otro.
• –texto–>
  • flecha continua con texto entre un elemento y otro.
• -.texto.->
  • flecha punteada con texto entre un elemento y otro.
• —
  • línea continua entre un elemento y otro.
• -.-
  • línea punteada entre un elemento y otro.

• -.texto.-

  • línea punteada con texto entre un elemento y otro.

• Al comienzo del código, como habrán notado, dice graph TB. Esto es porque mermaid permite también hacer otro tipo de gráficos (como cartas gant, por ejemplo pero en este tutorial me abocaré solo en los diagramas). Esta línea es imprescindible para que se vea el diagrama. TD significa Top Bottom, es decir, de arriba hacia abajo. Podrá usarse también LR (izquierda a derecha), RL (derecha a izquierda), BT (abajo hacia arriba). Ejemplos a continuación:

• Lo último que queda por mencionar son los subgráficos, a los que se les llama con subgraph, seguido de un nombre si se desea (en el primer ejemplo, el subgráfico se llama Materiales; en el segundo, Conversación). Seguido del subgraph se indica todo lo que uno quiere que haya dentro y, para cerrarlo se agrega end. Para hacer un subgráfico dentro de otro basta con agregarlo teniendo su propio end, también dentro del que lo contiene:

• Finalmente, ya teniendo listo el diagrama queda buscar alguna forma de guardarlo para conservarlo en la posterioridad. Las opciones son variadas.

• Guardarlo en formato plano y compartirlo así:

  • pesará muy poco y podrá ser editado en el futuro por quien tenga el archivo. Sin embargo, ese eventual lector tendrá que tener software para visualizar gráficamente el diagrama.

• Pantallazo:

  • siempre útil y ya sabemos como funciona. Tiene la desventaja de que si el diagrama no cabe en la pantalla, va a haber que sacar varios y después unirlos. Muy tedioso.

• Exportar a PNG o SVG (con atom.io):

  • esta opción está mejor. El resultado es de calidad y no pesa mucho (por el formato de los archivos).

• Exportar a HTML (con haroopad):

  • el archivo resultante es un html que puede subirse a un servidor (si tenemos) y ser visto sin mayor mediación por todos. Tiene una pequeña línea al final que dice “powered by Haroopad” o algo así, se quita borrando desde <footer> en adelante en el código html mismo.

• Exportar a PDF (con haroopad):

  • esta opción no está a primera vista, pero se llega a ella seleccionando Imprimir y eligiendo luego Imprimir como pdf.

diagramas y enlaces

• se puede poner un enlace que se ejecuta al hacer click
  • atención pues no funciona exactemente como un link
  • el tooltip sale en la base de la página pero se puede modificar con una programación más complicada.
• ejemplo real

• el código

<div class="mermaid">
graph LR
DOCKER-->VAGRANT
VAGRANT-->APUNTES-VIEJOS-EN-ODT
APUNTES-VIEJOS-EN-ODT-->CONVERTIR-EN-ODT
CONVERTIR-EN-ODT-->USAR-PANDOC
click USAR-PANDOC "/pages/programacion/programacionUtilidades#pandoc" "enlace a como usar pandoc en notas-programacion"
</div>

• mas ejemplos

• diagrama de secuencias

• un diagrama de Gantt

• un diagrama de clases que no se porque no se renderiza bien por que esta en forma experimental

• otra sintaxis

classDiagram
  Class01 <|-- AveryLongClass : Cool
  Class03 *-- Class04
  Class05 o-- Class06
  Class07 .. Class08
  Class09 --> C2 : Where am i?
  Class09 --* C3
  Class09 --|> Class07
  Class07 : equals()
  Class07 : Object[] elementData
  Class01 : size()
  Class01 : int chimp
  Class01 : int gorilla
  Class08 <--> C2: Cool label

• un diagrama de Git que también esta en modo experimental

• no se porque no sale la última línea del gráfico

enlaces de interés

• tema learn