Sander Leemans

Academic writing: some style hints

During writing and reviewing, I compiled the following list of style "anti-patterns" and hints:

  1. Woolly language: text that can be removed without changing the meaning of a sentence. For instance: while being either inside or outside, I like to eat ice cream. Better: I like to eat ice cream.
  2. Woolly formalisms: avoid timestamps and identifiers wherever possible. It is not programming, it is formal writing. For instance: an event log is a set of events; each event has a unique timestamp and a trace identifier; a trace is a sequence of events, ordered by timestamp, with the same trace identifier. Better: an event log is a collection of traces, which are sequences of events.
  3. Term switching/avoid synonyms: if two terms refer to the same thing, then the terms should be the same. It makes the text boring, true, but also much easier to understand. For instance: I was sitting on the couch when suddenly our cat joined me on the sofa. Better: I was sitting on the couch when suddenly our cat joined me on the couch.
  4. Figure misplacement (1): \vspace and \hspace: do not fight with Latex's layout system; you'll not win. Use the appropriate length adjustments to save space, such as textfloatsep.
  5. Figure misplacement (2): \begin{figure}[hbtpH!]: if you do not want something to float, then do not make it a float. For best spacing, use [t] or [b], but only at the end of the writing process, just before submission.
  6. Font inflation: use $a$ for variables, $A$ for sets and tuples, and $\mathcal{A}$ for sets of sets. Use $f$ for functions. If running out of letters, use Greek letters. Use \texttt{a} for constants. Do not introduce symbols for universes: if it is necessary to explicitly formally bound a variable (often, this can be done in text), do it from a specific set, not a universe.
  7. Overcapitalisation: capitals drag attention and should be used sparingly. Capitalise the following:
    • In top-level section headers, capitalise the first word and every word that is not a small word (on, in, the, etc.);
    • Names of particular algorithms, formalisms, people, etc.: 'Business Process Management and Notation', `Petri net', `Heuristics Miner';
    • Abbreviations: stochastic labelled Petri net (SLPN);
    • References: `Section 4.1' and `Figure 5'
    Do not capitalise the following:
    • Small words, such as on, in, the, etc.;
    • Lower-level section headers: (only capitalise the first words and proper names);
    • Names of research fields or generic concepts: 'business process management', `directly follows graph', `Petri net';
    • After a colon (:), unless a completely new sentence starts;
    • Multiple references: `sections 4, 5 and 6';
  8. Every float (table/figure/algorithm) must have a caption and be referred to in the text. The caption should end in a period, and be descriptive but short and concise.
  9. Avoid lines within tables at all cost (except between the header and the body). Use the booktabs package to add \toprule, \midrule and \bottomrule. Use white space to separate groups of columns or rows visually. Align every number to the right, and everything else to the left.
  10. Data, information, semantics and behaviour are only used in a singular form: `some data is obtained', `multiple types of behaviour'.
  11. I prefer English (sometimes also called British English), but ensure the dialect of English is consistent. Commas serve to assist readers in understanding the sentence structure (unlike in German, where they are part of the grammar). Use them sparingly; avoid Oxford commas, unless they help avoid confusion.

Latex: BPMN in Tikz

Drawing with Tikz enables consistently styled models. With this Tikz-library, you can draw BPMN elements easily. It is complete up to the elements covered in the courses I teach.

The tikz-bpmn.sty file, as well as a manual.

Tech: OBS & Launchpad

To improve the looks of a webcam on Zoom, one can use the free Open Broadcaster Software (OBS). Different scenes can be used to show your webcam, desktop or a combination of both, and logo overlays are easy as well.

It takes just a few steps to get started on Ubuntu 20.10:
  1. Install OBS
    sudo apt install obs-studio
  2. Set up some scenes: you can include a webcam (hint: add your webcam to a separate scene and reuse that scene, as a webcam can only be in one scene), screen capture, videos, images, ...
  3. Install OBS-v4l2sink, which creates a virtual webcam. I had to download this plug-in and compile it, but this was not hard using the steps on the plug-in's Github page.
  4. Create a virtual webcam, by running once every boot:
    sudo modprobe v4l2loopback video_nr=10 card_label="OBS Video Source" exclusive_caps
  5. Open OBS and select the menu entry "Tools" > "V4L2 Video Output" and choose "/dev/video10" and for video format "YUY2".
  6. Start Zoom, Skype or .... Many programs check for new webcams only on start-up, so you might have to restart it.
  7. Set up a call and select the webcam "OBS Video Source".
Now, your OBS output will be a webcam in Zoom or Skype, and shown to the others in the call. No more "can you see my screen?" and no more half-working virtual backgrounds where your hair disappears in the background.

To switch between scenes, you can set up hotkeys, however for AUD 60, I managed to get my hands on a Novation Launchpad Mini, which is a 9x9 grid of lit buttons, that works via the Midi protocol over USB. I wanted to use this to switch between scenes in OBS, such that I don't have to manually set global keyboard shortcuts press multiple buttons on my keyboard:

  1. Install OBS-Websocket to allow Websocket connections to OBS (releases are available; for Ubuntu 20.10 you'll need the 4.7 .deb version)
  2. Open OBS and select the menu entry "Tools" > "WebSockets Server Settings" and disable authentication.
  3. Download a Java program that I wrote (source) that glues together OBS and the Launchpad. Start OBS and connect the Launchpad before starting this Java program, and it will keep track of the scenes in OBS, lit up selected buttons on the Launchpad, and if you press that button, OBS will switch to the respective scene.

    The Java program uses an OBS-websocket library for Java, and should be cross platform.

  4. To make the whole set-up easy to start and to shut down, we can use a small bash script:
    sudo modprobe v4l2loopback video_nr=10 card_label="OBS Video Source" exclusive_caps
    			#enable the virtual webcam
    
    	{
    	    obs --scene "Intro" #start OBS with the mentioned scene selected
    	    pkill -f "java -jar OBSLaunchpad.jar" #after closing OBS, kill the Java program
    
    	    sleep 1 #give the Java program a chance to shut down
    	    
    	    #find Launchpad hardware port
    	    DEVICE="Launchpad Mini MIDI 1"
    	    PORT=1
    	    while IFS=' ' read dir dev name; do
    		case "$name" in
    		    $DEVICE ) 
    		        PORT=$dev;;
    		esac
    	    done <<< "$(amidi -l)"    
    	    amidi -p $PORT -S B00000 #turn all LEDs off
    	} & 
    
    	sleep 1 #give OBS a chance to start the websocket server
    
    	java -jar OBSLaunchpad.jar #start the Java program
  5. If you want to add functions to the Java program, the Launchpad's developers' reference is a handy resource. Please let me know if you've added some cool extension :)
Ever tried to do this on Windows?

Latex: reduce line breaks in references

If you want to save some serious space and you don't care about readers easily looking up references, you could remove the line breaks from the references as follows:
   	  	\usepackage{paralist}
   	  	\renewenvironment{thebibliography}[1]{%
		\section*{\refname}\inparaenum[{[}1{]}]}{\endinparaenum}
   	  	
(adapted from Stackexchange)

Latex: ORCID symbol

Orcid Latex command to include the green symbol. Include in your preamble with \input{orcid.tex}, and use with \orcid{your Orcid id}.

The file.

Latex: QUT exam class

QUT exam Latex class and template. This class can be used to create exams that adhere to the QUT-exam layout requirements.

The manual.

The class file.

Update 03-09-2019: Added randomisation for answers.
Update 12-04-2019: \printPointsA now does not print points twice anymore.

Latex: thesis class

PhD thesis Latex class, used in my thesis at the Eindhoven University of Technology.

The class file.

The pre-amble config file.

The main file.

There's a handy option in the class declaration: if you add the optional option [chapter=X], it will only compile Chapter X. This saves a lot of time while writing.