11/10/2013

Writing format / Style guide

As I write my thesis I keep coming up with questions about the style, layout and formatting that I should use. In many cases I doubt there is a right or wrong answer to the questions I'm asking, however I need to make a decision either way, and be consistent throughout my document. Therefore I've decided to start noting down the questions I'm coming up with and the direction I'm taking, ideally along with reasoned arguments as to why. Hopefully this should serve as a reference for me down the line.

Double spacing after full-stops?

I vividly remember being taught at school to double space after a full stop and single space after a comma, colon or semi-colon. This is a throwback to the days of using typewriters and it is widely regarded as no longer needed. Although it sounds like a slightly larger space can help with readability, modern proportional fonts and processing tools allow for this anyway. The Wikipedia page gives a lot of details on this.

I believe LaTeX can (and does) adjust spacing after a period anyway.

Title case?

What words should be capitalised in a title (e.g. a chapter/section/subsection heading)? "Title case" refers to the practice of capitalising all words in the title except for some subset of short or unimportant words. However what the subset is and whether title case should be used at all does not seem to be clearly defined. Once again the Wikipedia page kicks off discussion on this. It seems that several major publications use sentence case for titles. It seems that its main motivation is as form of emphasis, however it is argued that with the use of modern digital fonts emphasis is more easily added in other ways and that sentence case is easier to read.

Some contributors suggest using title case only for main titles, such as the title of the book and possibly chapters, but using sentence case for lower level headings. I will use title case in this manner, for the title of my PhD and for the chapter titles, but not elsewhere.

Capitalising references?

Throughout my document I make references to other sections and chapters, as well as to figures and tables. Of course I link these properly in my LaTeX source so that hyperlinks are formed, but should I capitalise the word section/chapter/figure/equation? It seems that most, but not all, scholarly articles choose to capitalise in these cases; the argument being, I think, over whether it behaves as a proper noun or not. This raises the question of whether "Page" should be capitalised in cross-references, this would appear very strange and this style does not appear to be in use anywhere. A possible explanation for this is that figures, chapters, etc are 'intentionally' named, whereas pages are not, although this seems somewhat unsatisfactory.

I will capitalise all references except for pages (which I do not expect to use) to fit with the most common useage.

Company, brand and product names?

There does not seem to be a common style in use for formatting these. Most commonly they are presented in standard body text with whatever capitalisation and punctuation the brand commonly uses. At most there may be some specific rules relating to capitalisation for certain publications. However in reading heavily technical work I find that confusion can often arise between technical terminology and product details, therefore it would make sense to be able to show the difference in some way. For example consider the sentences:
" The PID controller is simulated using a Matlab model. The ABB controller is simulated using a parametric model"
Here both "Matlab" and "ABB" are product and company names respectively, whereas "PID" is a technical acronym and "parametric" is a technical term explaining the simulation type. I doubt this distinction would be obvious to anyone unfamiliar with the terminology.

In order to assist with this I would like to apply some formatting convention to highlight company, brand or product names in the text. I have seen one dissertation that used small caps to denote products. This seems to work well as I am not using them for anything else in my document, although it is slightly unfortunate that acronym names do not stand out in this way. 

I am not fully decided on the best way to proceed with this at present.

Indenting paragraphs?

Separating paragraphs in some way to prompt a slight pause whilst reading seems like a sensible writing style. The most common technique for this in printed material is to indent the start of paragraphs, although alternatively an increase in line spacing may be used. As a pause is not required at the start of a new section (or rather, that pause has already been prompted) an indent is typically omitted.

This standard in online material seems to be to use "block text", that is no indents but an increased gap between paragraphs. This makes some sense as there is an infinite space available and there is no confusion over paragraphs breaking across pages

I will be indenting printed paragraphs other than the first and using block text in online materials.

Serif or sans-serif?

Although the jury seems to be out on whether serif fonts are actually any better for print reading, I went with convention and chose a serif font for my thesis.

Table format

As far as possible I followed the excellent recommendations in the booktabs usage guide.

Unit format

I'll be trying to stick with SI units wherever possible in the thesis, although there may be some deviations where other conventions are the industry standard. Where appropriate I'll be using prefixes to avoid long and ugly numbers. LaTeX provides the excellent siunitx package for typesetting units which I will be using heavily. When used in tables and figures to apply to an axis, row or column I will be using a slash to denote the units. This is recommended by the BIPM as the correct method of expressing values for multiple quantities. It effectively divides the title by the units, making the values dimensionless.
However, going against the BIPM advice, I will be including a space before and after the slash, as I feel that this separates it from the axis title - which may be multiple words, and it reduces confusion between the slash and the units themselves. With the slash present all the denominator parts of the units will be referred to as a power of -1.

Scientific notation

Due to the mathematics of my work covering a large number of physical domains, including thermal, mechanical and electrical, I ended up with a relatively large notation section. I also began to run out of letters in the latin and greek alphabets. I therefore ended up using a cursive script to denote thermal parameters, allowing me to reuse some letters.

Figure design

As far as possible I followed the guidance of Tufte in presenting data in my thesis.

Punctuation

http://tex.stackexchange.com/questions/55246/how-to-properly-typeset-all-forms-of-punctuation-used-in-english-language-docume/55911#55911

Acronyms


Line spacing


Margins

This seems to be the subject of as much debate as anything else in typography and formatting! Things I think are worth considering: binding, screen reading, ease of reading, general prettiness. By default LaTeX gives you a larger margin on the outside when you request twosided document. This is to maintain the same distance between text in the centre as it does at the edge. It does not make any allowance for binding.

The "classicthesis" LaTeX style gives really quite a narrow column of text. This style emulates Bringhursts The Elements of Typographic Style, which seems to be regarded by many as the definitive guide to the subject. The classicthesis documentation has this to say:
"The size of the text body is intentionally shaped like it is. It supports both legibility and allows a reasonable amount of information to be on a page. And, no: the lines are not too short."

None of this addressed binding, which seems to be considered separately, however must be allowed for in thesis printing. University guidelines have this to say: "To allow for binding the margin at the binding edge of any page must be not less than 40mm; other margins must be not less than 15mm.".

A further consideration is the fact that the thesis will frequently be viewed in digital format. In this case margins are not necessarily required, and variation in margins between odd and even pages is likely to be distracting. This suggests that specific formatting for two sided printing should be avoided.

As a compromise I will be using equal margins either side of the text. When bound this will produce a narrower inside margin. I will also be placing page numbering at the centre of the page and titles always on the left, this should maintain uniform readability for screen reading. I will use 40mm for both margins, as this is the minimum allowed for the binding margin by the guidelines, this also achieves a 0.62 proportion, not far from the 2/3 often advocated.

The top and bottom margins are allowed to go as low as 15mm, and at this limit the document scrolls very nicely during screen reading. However, it looks unwieldy in printed form. Therefore I've opted for a 25mm margin at the top and a 35mm margin at the bottom, with page numbering placed in the centre of the bottom margin.

Punctuating equations

Punctuate as if they were part of the sentence.
or don't as it may confuse the reader?
Personally I agree with this answer, therefore I shall punctuate equations that are displayed inline, or where the sentence continues below the equation, but I won't use periods to end a sentence within a numbered equation; in this instance I shall try to use a colon prior to the equation.

Related: should notation be introduced in the text flow or in brackets? I introduce them without brackets.

Font

I ended up using LaTeX's default Times font rather than anything too fancy. This was easy and familiar to me and most readers.


Justification

Most technical articles tend to use fully justified text and there is some evidence that this is of benefit to dyslexics. One downside is the increased tendency for justified text to create distracting "rivers" of white space. One improvement is the use of microtypography techniques. These are pretty easy to use in LaTeX and there doesn't seem to be any downsides, so I'll be using them.

Tables and Figures

Tables and figures will appear throughout as soon a practically possible after they are referenced in the text. They will all be centred with a centred caption, Tables will have a caption above, Figures below. Captions will not be punctuated with a final period if they are only a sentence fragment, however they will be if they are a complete sentence or there are multiple sentences. Figures will not have a title above them, the caption below providing all the required information.


This is obviously a work in progress post... but if anyone has comments then I'd love to hear them!

01/08/2013

LaTeX equations split over two columns

Drafting a paper I've just got stuck trying to fit some lengthy equations into a two column document. For some I've gotten away with splitting lines using \begin{split} or \begin{align} environments, but for some it starts to look ridiculous. I also started to run into issues where my \left( and \right) bracket commands didn't like to be split over lines. So I decided that there was no option except spreading the equation over the full page width.

This is actually not particularly straightforward in LaTeX. A reasonable forum discussion on options gives a few suggestions. It seems that it needs to be floated within a figure environment. This is also suggested in a very comprehensive document (p35) on typesetting equations. Unfortunately both of these require manual fiddling with equation numbers and quite a lot of extra code in the document. I've therefore modified their code to define my own environment for a floated equation and used counters to automate the equation numbering.

Preamble:
% for floated 2 column equations
\newcounter{tempEquationCounter}
\newcounter{thisEquationNumber}
\newenvironment{floatEq}
{\setcounter{thisEquationNumber}{\value{equation}}\addtocounter{equation}{1}% record equation as happened and remember number
\begin{figure*}[!t]% float following equation across columns
\normalsize\setcounter{tempEquationCounter}{\value{equation}}% record current equation number in floated location
\setcounter{equation}{\value{thisEquationNumber}}% use previous equation number
}
{\setcounter{equation}{\value{tempEquationCounter}}% set back to equation number in floated location
\hrulefill\vspace*{4pt}% add a horizontal rule separator
\end{figure*}% end float environment

}

In the text simply wrap the standard equation environment in the new environment:
\begin{floatEq}
\begin{equation}
a = b + c
\label{equ:floatedEquation}
\end{equation}
\end{floatEq}

This should float the equation across the whole page and allow LaTeX to fit it in the right place whilst still numbering it as if it appeared where it is defined in the text. Or at least that's what it's achieving for me at the moment!

30/05/2013

More thoughts on thesis documentation...

It's over a year since I put together some thoughts about how documents (PhD theses in particular) get written up. Having just started on the third year of my PhD I need to start compiling all the little bits I've written in the last two years together into something resembling a final thesis format. I can then build this up into a body of work that I can present at the end. This raises the question - how to best go about this process?
First a few conflicting thoughts about the final document I need to produce:
  1. I'd like to write in short concise sections that will either stand on their own, or can be built up into a larger document. I'm concerned that this will not produce a coherent final document though.
  2. I'd like to setup the individual sections in a hierarchy that reflects the hierarchy of the systems they are describing. Unfortunately this is likely to produce far too many levels in the document (when I drew up a draft layout I got to 12 levels!).
  3. I'd like to describe the work down to a level that anyone (even a schoolchild) could understand, however this would probably end up being a massive document that would be too basic for most readers.
I think the problem I have, that lies behind all of this, is that the thesis is really designed to be a document for your examiners to read, cover to cover, in a format that they are familiar and happy with. It will appear printed on paper, be long and probably dull, and, as has been pointed out to me by other people and stated a number of times on the internet, it should "tell a story". A story that took 3 years to write and that a maximum of 3 people will ever actually read.

What I would prefer to write is a document that I could upload to the web and could be referenced and useful to anyone. I've spent some time thinking about how I might be able to cleverly combine the two, but I don't think I'll be able to write just one document to satisfy both aims. So my plan now is to write the thesis in a fairly conventional manner in order to satisfy the requirements for a  PhD, then to later revise this into a format that I prefer. Obviously this second part will be easier if I know what I'm planning during the first part, so here is my initial outline...

Thesis mark I

I'll be using LaTeX for the writing, in whatever document template I'm given (or have to make to fulfill my departments guidelines). I'll try to keep it split into relatively small chunks, but without going to too many levels of subheading (4 max). I plan to keep each chapter in its own subdirectory and include it using the \include command. Within chapters I will break things down again using \input commands to allow me to keep sections and subsections in their own individual tex files.
I'll try to use hyperlinks where possible using \usepackage{hyperref}, using the colorlinks option to avoid the default ugly boxes. By using a subtle colour for the links they shouldn't be too jarring in a printed report (where they will be no use) but obvious enough when read on a computer.
As previously discussed in this blog, I'll try to include figures from matlab and simulink as vector images, stored wherever they are generated. I'll also use a single bibtex reference file for all my references.
As with other work, ongoing revision of the thesis will be controlled using Bazaar. I can include the version used to produce output files within them using vc.tex, which is pretty neat. That way when I have multiple versions printed out and sent to people for comments I hopefully shouldn't lose track of which version they're commenting on!
Latex to Kindle?

Thesis mark II

Latex to html?
html to chd?

I never really finished writing this post, but it gives a flavour of what I was thinking a little while ago when I started writing in earnest!

20/08/2012

TeXworks shortcuts

I use TeXworks as my LaTeX editor currently and I recently discovered a few shortcuts that I'm finding really handy in the preview window:

Shift + click = Zoom in
Alt + click = Zoom out
Ctrl + click = Find paragraph in source code

Hope those few are helpful to someone. Let me know if there are any others that I might find useful!

02/08/2012

Adding bzr files through the cb2bib

I recently described my referencing process where I simultaneously hold reference pdf files in a version control system and keep track of their details in bibtex file. I have also described a problem I've been having with my version control system of choice, Bazaar.

Based on these I decided that there might be a better (more automated) way of adding my references. After a very useful email exchange with the author of cb2bib they confirmed that this should be possible. Now, after a day of messing around and learning about various command-line tools that I hadn't used before, I think I've got it working. Here's how...

First I created a new batch file that I called "bzrAddRef.bat". Here are its contents:


@echo OFF

rem --------------------------------------------------------------------------
rem cb2Bib Tools addition by J. Welford
rem --------------------------------------------------------------------------


echo   bzrAddRef:
echo   cb2Bib script for adding BibTeX files to a Bazaar repository
echo.
echo   Using sed and xargs utilities from:
echo   http://gnuwin32.sourceforge.net
echo.
echo   Path below may need changing to be within the repository
echo.


echo   Processing:
echo.
cd "C:\Users\welf\Documents\literatureReview"
sed -n -e "s|.*file.*=.*{\(.*\)}.*|\"\1\"|p" %1 > bzrRefs.tmp
xargs bzr add <bzrRefs.tmp
del bzrRefs.tmp

Only the last 4 lines are really important. The first one sets the working directory, I don't think it matters what you use as long as you have write access and it is within the repository you want to add to. The next line runs through the current bibtex file and extracts the location of all the references to a temporary file. The next line adds all these files to Bazaar repository. The final line deletes the temporary file. (maybe I could have used a pipe between commands so that the temporary file was not required?)


Some special commands are used that will need to be installed, what you need are: sed.exe (and its dependencies:  regex2.dll, libintl3.dll, libiconv2.dll) and xargs.exe.

Within the settings of cb2bib this batch file can now be pointed at under the "Configure BibTeX" - "External BibTeX Postprocessing" - "Command:" section. Once that is done simply hitting "Alt"+"p" in the cb2bib window should run the batch file and add all the references to version control.

I hope the helps someone! (I presume it could be altered for other version control systems or be called from other applications.)

31/07/2012

My referencing process

I suspect everyone has a subtly different way of doing this, depending on the tools they prefer and the way they like to work. I thought I would document my process as I think it's pretty efficient and has some real advantages, I'm sure there is still plenty of room for improvement though.

Overall aim

As an academic I often need to refer to work done by others, this normally done by noting their published work as a list of references or bibliography at the end of my documents. The most basic way of achieving this would be to have a stack of published books and papers in my drawer that I can refer to and then type in the reference details at the end of the each document I want to write. I'm sure that plenty of people do work this way, but from my point of view I see it as pretty inefficient (lots of printing, lots of sorting, lots of typing, not very portable, an awful pain to change reference styles, etc).

I manage my references entirely in software using a few specific tools. I've mentioned most of them in other posts but I'll go into a bit more detail here on the actual process I use. 

I'm going to split referencing into two separate processes. Firstly, as I'm researching a topic, I tend to gather references to get an idea what I'm doing. Secondly, when I come to document my work I need to search and cite the references I've found.

Tools

Google Scholar is generally my primary resource for finding papers and documents. I also rely on standard Google searches a massive amount and I have a Google alert set up to email me when a few key phrases appear in new articles added to the web.
IEEExplore generally has most of the published work (in terms of papers, Journal articles, etc) that I need to refer to. The University has a subscription to this that allows me to download what I need (otherwise I'd have to pay!).
Pdf format is generally how almost all papers are delivered and the format that I keep them in. I use Foxit reader to read pdf documents. I keep all my reference documents in one big folder rather than worrying about any kind of complex filing system.
I use Bazaar to version control my folder of pdf documents. I've previously discussed how this works and how it allows me to work between different computers, even without installing any software on them.
I use a tool called cb2bib to maintain a list of references in bibtex format. I started off just using this to add references to my bibtex file, but I've found it to also be really good for browsing references and citing whilst writing a document. I changed some of the default setup to help it retrieve data from the net.
I use Latex to typeset most of my work. Within this I can simply point it at the bibtex file for all the details of the references. I have previously mentioned how to use a bibtex file that is not in the same place as the rest latex document.

Gathering references

  1. Search for the document that I need to find using Google, Google Scholar or general web browsing.
  2. Open and read the document to see if it looks relevant and useful. Assuming that it does...
  3. Download the document to my big folder of "third party" references. I tend to use the full title of the work as the save name of the document - this can lead to quite long file names, but it makes it a lot easier to find things!
  4. Add the saved file to my bazaar version control system. This only takes a couple of clicks through  tortoiseBzr menus in windows explorer.
  5. Add the document to my bibtex file using cb2bib. This is a pretty straightforward process:
    1. Open cb2bib, I have a keyboard shortcut setup for this (it should also remember what bibtex file is being used)
    2. Click "import from pdf file"
    3. Click "select files"
    4. Select pdf files saved previously (hold ctrl to select a bunch at once)
    5. Click "process"
    6. The software will try to extract as much info as possible from the pdf file, this probably won't be enough so...
    7. Click Network query to retrieve all the info about the file from the web (this usually works fine, but it's worth checking the results, you may need to give it the right title to start it off)
    8. Click save to add the reference to the bibtex file
  6. The changed bibtex file and added references will need to be "commited" to the version control repository.
UPDATE: I have added now made a batch file that effectively takes the place of step 4 and occurs after step 5 - it can be run after a whole set of references have been input through cd2bib and adds them all to my version control repository using "Alt"+"p".

Citing references

  1. With a Latex document that has a pointer to the bibtex file within it.
  2. Open cb2bib citer (I use a keyboard shortcut) and select the reference(s) required:
    1. [optional] Select the way I want my reference list displayed by pressing "a" (author), "j" (journal), "t" (title) or "y" (year). I find author is usually best.
    2. [optional] Filter the reference list by pressing "f" and then typing what you want to search for ("d" clears the search)
    3. Click on a chosen reference
    4. [optional] Press "o" to open the reference and read it
    5. Press "enter" to cite the reference, a small pen marker will appear next to it (in author view it will appear next to each author for the same paper). Multiple references may be cited by selecting them and pressing "enter". "delete" clears all the selected references.
    6. Press "c" once all the references for citing are selected, this will close the citer window and copy the latex text for the references to the clipboard.
  3. Paste the text into the latex file to include the references at that point in the document.
Although those might seem like a lot of steps it's really pretty straightforward once you get used to it. The only real difficulty is remembering the keyboard commands for cb2bib citer. With this setup I can take all my references with me between machines (even between Linux and Windows) and use the same process everywhere.

Bazaar GUI issue on Windows 7 - adding files using the commandline GUI interface

Due to an unfortunate hard drive issue I recently had cause to swap to a new drive. Along with this came an upgrade from XP to Windows7 (64bit). This was not a real issue, just a bit of hassle moving everything over and re-installing all my applications.

As part of the process I had to re-install Bazaar which I'm using to version control all my work. This appeared to go fine, including the addition of tortoiseBzr to integrate the Bazaar commands into the windows explorer GUI. Unfortunately when I came to use it with my work it gave me an error, I think due to the "special" folders structure in windows7. Here is a copy of the message I posted to the Bazaar user group:

Hi everyone, I hope someone can help me out.

I'm using Bazaar to version control a whole set of different files between a few different machines. On a previous windows XP machine I was able to use the whole user area as my repository and only add the files that I wanted to control.

I have just upgraded to a windows 7 machine (64bit) and there seem to be some issues with the preconfigured folders not being accessible by Bazaar. I have been able to commit files fine, but when I try to open a window to add new files it crashes as it tries to display them, with the error:

bzr: ERROR: [Error 5] Access is denied: u'C:/Users/welf/AppData/Local/Application Data\\*.*'
(It also seems to have issues with "My Music" and similar)

Any thoughts on why it's happening or a way round the problem?

(I suspect that it would work if I had the repository at a lower level without any "windows" folders, but that is not really the way I'd like to work. I don't actually need to version control anything in these folders, so if they can be skipped in some way that would be fine.)

It seems suspiciously similar to an outstanding bug here:
https://bugs.launchpad.net/qbzr/+bug/1012907

The general upshot is that I can't add new files to version control using the GUI, although I seem to be able to do pretty much everything else. I thought I would detail the workaround I'm currently using. It isn't too bad, but wasn't totally obvious, so I thought I would document it in case it was of use to anyone else:
  1. Right click in the folder containing the files and select the "Tortoise Bazaar" menu item, then select "Run command". A GUI window to allow you to run a command will open.
  1. Select "Core" after "Category"
  2. Select "add" after "Command"
  3. Click "Insert filenames...", a file selecting window will open.
  4. Select the files you wish to add (hold 'Ctrl' to select multiple files) and click "Open"
  1. Click "OK" and the status window should tell you that the files have been added
You're now at the same stage as if you'd added the files using the standard GUI. Of course you will still need to perform a commit before the files are part of the repository.

Hope that's useful to someone.


UPDATE: Discussion on a Bazaar email list confirms that the problem I'm seeing is due to the error linked above. Unfortunately a fix does not look imminent therefore I'll have to continue using the command-line method described.