A good friend of mine recently finished writing his diploma thesis in mathematics. We often discussed various aspects of his work, ranging from the actual writing process to the creation of figures. This prompted me to gather my notes from my own diploma thesis and I think they may offer some valuable advice for students. My intention is to write several articles, each detailing a certain aspect of creating a diploma thesis. For this first article I want to focus on the writing process, which is probably the integral part of any thesis.

While preparing my thesis, I read a plethora of books about the writing process because I was always intrigued about the (seemingly) ease with which so many people produce so many documents. I was quickly cured of my naivety: Upon closer inspection, many texts turned out to be written rather crappily. Thus, I hoped that by learning about all the rules, my writing would become superb. Unfortunately for all of us, most of the books about writing are also crap. However, I found several texts and book that I personally consider worthwhile. Hence, to start with, here's a list of rules that I recommend following:

Write drunk, revise sober: Since I abhor alcoholic beverages, here's my paraphrased version for mathematics: When writing your first draft, do not worry too much about sectioning, connections to the rest of the text, any redundancies, and so on. However, upon having finished a certain unit of work (a chapter, a section, a subsection, a paragraph), read it again and try to find improvements. In fact, I would suggest an iterative approach: As soon as a single part of the thesis seems to be finished, check how it connects to the rest of the thesis. Fix everything you deem to be incorrect. Rinse and repeat.

This rule is probably the most important rule for any kind of writing endeavour. If you are slightly pedantic and perfectionist (just like me), you will worry too much about things like "How does this section fit in here?", "How should the proofs refer to each other?", "I cannot explain this fact without explaining that fact", and so on. The best course of action is to ignore the nagging little voice inside your head (you do have one, too, haven't you?) and just write something down. Even if you consider it utter rubbish, it is still easier to correct than a blank slate of paper.

Create a leitmotif: In Germany, we also call it roter Faden (literally, read thread), describing a thread that weaves and binds together your thesis. This means that all parts of your thesis should have their justification and their connection. Since you are probably not writing your thesis about several different topics at once, each part needs to have its own justification for being there. When I am reading a thesis or a research paper I like to know why I am reading a certain section. If this motivation is unclear or (even worse) non-existent, reading your material becomes needlessly complicated.

Don't be afraid to remove content: Keeping the leitmotif in mind, some sections are best scrapped after writing them. Yes, you read that correctly. Don't be afraid of removing content after you have written it. If it does not (anymore) into your thesis structure, it will only clutter up your writing. When writing my thesis, for example, I learned that I had to write some disposable content in order to understand a certain topic correctly. Having written down everything, I saw that it would not fit into my thesis. So I scrapped it and much grumbling ensued. But it turned out alright in the end.

Cite correctly: Citing your sources is the bread and butter of any scientific endeavour, but this is not what I am talking about. Rather, I am talking about how to cite your sources: Suppose there is a proof of something magical in a rather large arcane tome, written by Knuth and Feynman (wow!). You are now tempted to writing something akin to "...and for the proof of baz see the magical proof in [FK79]...". Naturally, "[FK79]" refers to a tome with 2435 pages.

From a reader's pointer of view, this is the most vile thing you could have done. While readers are perfectly capable of perusing the index of a book in order to search for the relevant proof, common courtesy dictates being more precise. In addition, citing correctly also helps you find incorrect references. Checking a reference such as "[Mu11], pp. 41--45" for correctness is much less work than browsing "[Mu11]" and check whether the theorem, proof, whatever is included therein.

Learn how to use a dictionary: If English is not your native language, I strongly suggest learning how to use a dictionary. And by dictionary, I mean a printed book and not an online dictionary. Let me expand on this: Mathematically speaking, a dictionary is not a bijective function. Some people, alas, treat it that way. When you are looking for a word, however, you always require a correct context. You need to know how this word is commonly used, whether it is outdated and so on. Be especially vary when searching for homonyms!

This item of advice does not imply that online dictionaries are useless. Just take their results with a grain of doubt and check whether you use your words correctly.

Adapt your punctuation: The rules for using punctuation in English texts are less rigid than the rules for German texts. Use this to your advantage! Try to mimic the way a native speaker would use punctuation. This tells your mind that you are not writing in your native language anymore, thereby making you less error-prone (or so I have convinced myself; this could be complete balderdash, for all I know).

Omit needless words: I am parroting William Strunk's famous advice. Bear this in mind when writing (scientific) texts. No prizes are awarded to those who consciously try to formulate everything as complicated as possible.

Keep your sentences short: This is most relevant for German authors. In German, we are used to construct intricate nested sentences (which are often not understood by our readers; see the previous item). Don't do that when writing English, or your sentences will become ambiguous.

Don't be afraid of using the same word repeatedly: Some of use have been drilled by schoolteachers to avoid repeated usage of the same word. In academic writing, however, this is often unavoidable. And actually, using the same word to signify the same thing helps readers enormously.

Some literature

• Mathematical writing by Knuth, Larrabee, and Roberts: This very readable essay helped
  me a lot when writing my thesis. Knuth gives helpful tips about writing (and formatting) proofs, but also mentions some general writing rules. The essay is available as a book or as a PDF.

• The Elements of Style by Strunk and White: This small book helped improve my writing style. Some of the rules from above are paraphrased from there. The book has had its share of criticism (see an entry in the Language Log, for example), but it's a good start for those who (like me) are overawed by their first large writing project.

• Wie man eine wissenschaftliche Abschlussarbeit schreibt by Eco: Geared towards the humanities and somewhat outdated. Still, this little book contains a wealth of tips and its anecdotal style makes it fun to read.

• A manual for writers of research papers, theses, and dissertations by Turabian: Recent editions have seen substantial updates, so the book is really accurate. For my personal taste, it also focuses too much on the humanities. On the plus side, though, the book covers a lot of different topics, ranging from correct citation rules for URLs to the preparation of graphs and tables.

• Common errors in English usage by Brians: Very useful (even for native speakers, I guess). Don't be deterred by the very tabular look of the book. The lists of incorrect expressions are very fun to read and really help.

Some time ago, I moved my blog from NanoBlogger to ikiwiki. To this end, I wrote a small perl script for handling the conversion. It only requires the modules Date-Manip and HTML-WikiConverter-Markdown. After installing them, you are good to go.

To use the script, copy all your NanoBlogger blog posts (along with their category data) into a folder. Usually, it is sufficient to copy the data folder of your installation. Keep in mind that the *.db files are useful if you want to keep your tag information. With all that set up, set the variable $input_directory to the directory with your NanoBlogger posts and run perl nb2ikiwiki.pl.

The script will automatically parse your blog posts, convert them to the Markdown syntax, apply any tag information (if specified), and store them in folders by years. Each file will be named after a sanitized version of the title of the article it contains.

This conversion process was sufficient for me. Hence, there are no further configuration parameters. You are free to modify the script in any way so that it suits your needs better.

I managed to get my diploma thesis published using HeiDok, the Open Access platform of Heidelberg University. The interested reader is referred to the permanent URL that displays my parvum opus.

While setting up a new system with FreeBSD 9.0, the port of the awesome window manager would not build. More specifically, generating manpages failed with:

xmlto: /usr/ports/x11-wm/awesome/work/awesome-3.4.10/manpages/man1/awesome.1.xml does not validate (status 3)

After some searching, I discovered the solution: Simply install the port textproc/docbook-xml-450 in addition to the dependency textproc/docbook-450 of the awesome window manager.

A few weeks ago, I faced an interesting CMake problem: Our group's software contains several submodules such as kernel, math, etc. The topology module, for which I am responsible, obtained a new dependency. I now wanted to notify all other modules about the inclusion status of this module. If the dependency was not met, the module should not be included. Furthermore, all algorithms depending on the topology module shall not be built, either.

I expected this to be difficult, nay impossible, because CMake does not seem to have the concept of global variables. Instead, I was pleasantly surprised to find out about the option PARENT_SCOPE. This option can be used in SET() statements of subordinate modules to set a variable in the scope of the calling module, i.e. the parent.

Hence, typing

SET(TOPOLOGY_MODULE_AVAILABLE true PARENT_SCOPE)

in the CMakeLists.txt file of the subordinate module solved the problem.

While revising a paper, I stumbled over two interesting LaTeX packages: overpic and SIunits. The former is a great way of "texifying" existing pictures. It shows you a grid as an overlay for the picture and allows you to position arbitrary LaTeX commands (such as short text description) to be positioned within this grid. This is great when the pictures are created in another application such as Inkscape or GIMP, but you still want to use the correct LaTeX fonts or mathematical symbols.

The latter package, SIunits, is the correct way of typesetting SI units. Of course, one could do this manually by using the math mode of TeX, but then one would have to ensure that the units are not shown in italics etc. Going with SIunits is easier: Just type \square\metre, for example, to get the unit of area. It is as simple as that.

More information:

• overpic
• SIunits

Encouraged by Matthias, I decided it was time to introduce my home network to IPv6. It turns out that this was a lot easier than I had expected it to be:

Client setup

For FreeBSD, adding ipv6_enable="YES" to /etc/rc.conf and rebooting was sufficient. Now all interfaces are able to communicate using IPv6.

Router setup

My Soekris router is currently running m0n0wall. With a halfway recent version (1.32), this was spectacularly easy: It boils down to enabling 6to4 on both WAN and LAN interfaces and adding an appropriate rule to the IPv6 part of the firewall. Here are some screenshots with the relevant parts highlighted:

m0n0wall LAN settings

m0n0wall WAN settings

m0n0wall firewall rules

Caveat

The firewall rule is essential. m0n0wall will otherwise block any IPv6 traffic originating from your LAN.

Since I write almost everything in LaTeX these days, be it personal stuff (letters, essays, documentation) or academcial things (papers, reports, my thesis), I was interested how to publish them in other formats. While PDF and Postscript files are great for storage and printing, nothing beats HTML in its simplicity and ubiquity.

So far I tried two different programs, latex2html and tth. They follow the same premise (converting a LaTeX document into a series of HTML files) but differ in their approach.

latex2html

latex2html is a rather old tool. Apparently, it is not updated anymore. Consequently, its output is rather peculiar and it supports HTML 4.0 only. No XHTML and definitely no strict variant. Here is a loose list of my experiences while trying to convert several LaTeX documents:

• I ran into some problems concerning German umlauts (which I specified as "a, for example). latex2html expects these to be specified as \"{a}.
• If latex2html encounters an unknown environment, it falls back to the LaTeX interpreter and generates a picture instead. This is also done when mathematical formulas are involved.
• There is no possibility (to my knowledge) for generating the body of the document only. This makes inclusion of LaTeX content for an existing website harder.
• Theming the generated files is possible, albeit cumbersome.

All in all, latex2html was not enough for my purposes. So the search continued and I eventually arrived at tth.

tth

tth has a very novel approach: Instead of generating images for mathematical formulas, tth tries to generate HTML code that mostly resembles a formula.

All in all, this works quite well. Even with complex documents. Here are my notes:

• By default, a single HTML page is generated. This is done quite fast, even for a larger document.
• tth is very resilient concerning unknown commands. It tries to parse the whole document and simply ignores erroneous sections.
• The layout is represented very well: Tables, sections, it is all there.
• Short formulas are easily readable. For longer formulas, I find the output of tth tedious to read.
• tth is very tunable: There is even an option for generating the body of the document only.

Conclusion

All in all, tth proved to be sufficient for my purposes. Yet, there seems to be a lack of publishing software for LaTeX sources. This is a pity, as publishing documents in several formats at once without many adjustments would be interesting. Another possibility would be to allow rendering of PDF files inside the browser (the currently available plugins are rather disappointing, in my opinion), although I do not like this option as it makes a browser even more bloated. Furthermore, in comparison to PDF, HTML offers still some advantages in readability (especially for disabled readers).

I published a new article about some elementary statistics for the weapons in Doom - The Boardgame. The article is expected to be updated with statistics for the monsters as soon as I have some free time.

It is done. I converted my blog from NanoBlogger to ikiwiki (I will post more details soon). Finally, all my content is managed by one system only. I will try to make use of ikiwiki's capabilities, especially those nice tags, which may now be assigned to blog posts and normal pages. Very nice.

My human readers should not have noticed any differences. I added appropriate RedirectMatch rules to my virtual host configuration. Still, it was impossible for me to retain the old layout. Hence, there are some changes (at least for the moment):

• No more individual feeds per tag
• No more individual archives per tag
• No links to other blogs and homepages
• No recent entries
• No meta information about the blog (number of articles etc.)

I am currently thinking about good ways of managing the content. As soon as I have found a suitable concept, I will reintegrate anything that strikes me as useful. In the meantime, enjoy the positive changes:

• More tags (such as the news tag for articles dealing with new content on my homepage)
• Unified design
• A nice tag cloud
• More usability (at least for me)

Upon rereading the first paragraph, I felt the need to explain my decision about NanoBlogger: The program itself is by no means flawed. However, I have outgrown its intented scope, I guess. NanoBlogger was very nice when the website was a shambles of hand-written HTML. Using ikiwiki was the first step towards the retirement of NanoBlogger: ikiwiki makes it simply too easy to turn any page into blog...

So, thanks to the NanoBlogger developers (deber and n1xt3r). Blogging with NanoBlogger was quite a ride and I still love the concept of posting from the shell (which is what I am doing right now, too...).