A few weeks ago I was desiging some time-related code, and that code needed to handle “events” happening on various days. Without getting into too much detail, it had to do various things depending on stuff like “did this event happen at least a week after another one” or “how many days after «day zero» did that event happen”. Since there were quite a few rules concerning that, I wanted to document them in a clear, visual way.
I decided that a “timeline diagram” would be a perfect way to visualize these sorts of relationships. Of course, I didn’t want to draw my diagrams on paper and scan them (well, this is actually a viable option – pencil and paper are hard to beat as a UI! – just not what I wanted), so I needed to select some tool. There are many, many tools which can help wit…
A few weeks ago I was desiging some time-related code, and that code needed to handle “events” happening on various days. Without getting into too much detail, it had to do various things depending on stuff like “did this event happen at least a week after another one” or “how many days after «day zero» did that event happen”. Since there were quite a few rules concerning that, I wanted to document them in a clear, visual way.
I decided that a “timeline diagram” would be a perfect way to visualize these sorts of relationships. Of course, I didn’t want to draw my diagrams on paper and scan them (well, this is actually a viable option – pencil and paper are hard to beat as a UI! – just not what I wanted), so I needed to select some tool. There are many, many tools which can help with that – my teammates like Excalidraw a lot, there are many others, both web-based and desktop-based. Me being me, I decided to use Emacs and ASCII art. While I would definitely not call myself an “artist”, I have a sort of history of drawing stuff in Emacs with ASCII characters. Let’s add to that history!
(defun insert-time-axis ()
"Insert a \"time axis\" at point."
(interactive)
(let ((points ()) point (max 0))
(while
(progn
(setq point (read-number
"Time point in days (0 to finish): "))
(push point points)
(when (> point max)
(setq max point))
(plusp point)))
(setq points (sort points))
(unless (bolp)
(insert "\n"))
(dotimes (i (1+ max))
(insert
(if (memq i points)
"| " " ")))
(insert "\n")
(dotimes (i (1+ max))
(insert
(if (memq i points)
"+-" "--")))
(insert "->\n")
(dotimes (i (1+ max))
(insert
(if (memq i points)
(format "%-2d" i) " ")))
(insert " time [days]\n")))
As you can see, this code is exceptionally crude – it’s written in a very imperative style (and there’s nothing wrong with that in this particular case!), with all the setqs and dotimes loops. Also, instead of accepting a list of integers and some clever trickery in the interactive clause, it just doesn’t accept any arguments and uses read-number directly in the body of the function to get the list of numbers to mark with “ticks”. This means my command cannot be used non-interactively – but that’s ok, since I don’t intend to ever use it that way!
I can now say M-x insert-time-axis and type a few numbers, ending them with a zero (which makes sense – I always want a zero on my time axis) and get a “picture” like this:
| | | |
+-------------+-----+-------+-->
0 7 10 14 time [days]
I can then manually edit it to add descriptions to the days marked with ticks etc., for example:
one week
| ten days
start | | two weeks
| | | |
+-------------+-----+-------+-->
0 7 10 14 time [days]
Was it faster to type this command (and make a few editions to the diagram itself) than to learn enough Excalidraw to make this diagram? Maybe, maybe not. Is it more cool to have a little command to create ASCII art timeline diagrams like this? Definitely. Would it be much more complicated to code automatic support for tick labels like the ones I added manually above? A bit, yes. Would it be difficult to write a command to create other diagrams programmatically, say Venn diagrams, or graphs of functions, or flowcharts etc.? Not really – if the diagram is too complex to draw using just plain inserts, I can always resort to calling Artist mode functions like I did several times before.
By the way, in the old days when I worked in academia and used LaTeX extensively, I would have probably used TikZ for diagrams like this. (I very highly recommend reading the section titled “Guidelines on Graphics” in its documentation, even if you do not plan to use TikZ or LaTeX at all – it is a solid collection of very no-nonsense tips on creating graphics in whichever tool you like, aimed especially at scientific or engineering documents.) And in fact, TikZ can create graphics in svg format, so it can be used for web-based documents, too. (Now that I think about it, I might be tempted to write another blog post showing how to draw similar timeline diagrams using TikZ and how to generate them in svg format. We’ll see!) In the meantime, if you ever write an engineering document requiring diagrams of any sort, remember that using Emacs – either interactively, using Picture mode or Artist mode, or programmatically – to draw them with ASCII art is a perfectly viable option.