Things seem to go in cycles. Writing a document using old-fashioned tools like TROFF or LaTeX is like knowing a secret code. Visual editors quickly took over, although even WordStar had some “dot commands” that you put in as text. Then HTML showed up and we were back to coding formatting as text strings.
Fast forward to the present, and HTML’s ubiquity makes that seem normal. Sure, there are visual editors, but it seems perfectly normal now to write <b> for bold text. However, as HTML grows to handle more tasks it also gets more complex. That’s led to the creation of things like Markdown which is just for simple text formatting.
Sometimes pictures and diagrams are critical for documenting complex software and hardware. Sure, there’s plenty of visual ways to do drawings. Mermaid aims to bring simple text markup to your graphical diagram creation. Diagrams like this one:
This doesn’t show off all of Mermaid’s capabilities, which it inheirits from d3. For example, you can set CSS styles and even allow JavaScript integration to make your diagrams interactive. On the other hand, things like the diamond decision block are difficult to make look right. We couldn’t figure out how to get a line to connect two columns, either.
Inside the Code
Here’s the markup code for that diagram:
graph TB
id1[Build Super Project]
id2a{Project Working?}
id3>Submit to Tip Line]
id4[Wait for Hackaday post]
id5((Prosper))
id1-->id2a
id2a-->|yes|id3
id2a-->|no|id1
id3-->id4
id4-->id5
About the Code
The “graph LR” line tells Mermaid that the graph goes left to right. The next several lines define all the blocks. You can see that the characters that surround the text give the shape of the node. That is “()” make a rounded box and “(())” makes a circle.
The lines with “–>” in them define the connections between the nodes. You can find a complete reference for the syntax online.
Just Flowcharts?
The system can currently make flow charts, sequence diagrams, and Gantt charts. The documentation is pretty good and you can embed it in a web page. You can also use the online editor live and generate links or SVG files.
There are many ways to get editable markup diagrams into your documentation. For instance, we’ve covered XWave and another timing diagram font where the fonts form the timing diagrams directly. For something more modern, there’s Wavedrom. Mermaid looks like a good complement to these tools, but for flowcharts.
Documentation isn’t always the most fun part of a project. But if you want others to duplicate it, have a record of your accomplishment, and even recall details when you have to fix or augment a system years after you finish it, you need good documentation. Mermaid might be just the tool to help you bang out that good-looking diagram that’s worth a thousand words.
Filed under: software hacks
// from Hackaday http://ift.tt/2k0ENo5
site=blogger">IFTTT
EmoticonEmoticon