There are times when part of the message, the gist, must be communicated to the reader in an out-of-band fashion, so to speak. One way of doing this is to use an epigraph to open a chapter or section, carefully chosen to convey the intended message but in the voice of another author (self-epigraphs are of very bad taste in my opinion).
is the preferred document preparation system of computer scientists, physicists, and mathematicians and if you intend to follow a career into the academia, it’s pretty much unavoidable. One day, you’ll have to learn
. The thing is,
is pretty much like C++: it can do just about anything, but it’s not going to help you do it. You have to rely on the innumerable packages or, if you really can’t find what you need, you can code it yourself. Let us have a look on how to code an epigraph macro in
.
/* no comments (part I) */
25/01/2011Comments have always bothered me. Not that I do not find them useful. It’s that we never know really how to use them properly. They’re also quite hard to maintain so that they follow the current state of the code. Comments tend to be written by the original programmer then never really updated to follow the latest modifications.
In addition to be concise, informative, to-the-point, comments should be written in the most precise language possible, one where words are chosen so that there are no unwanted overtones, no innuendos, and no obscene language. English is the new lingua franca, and this means that comments, in order to achieve collaboration with as many different people as possible, must be written in English. That might be a problem when you’re dealing with non-native speakers.
Read the rest of this entry »