|
|
|
# Technical Hints for Writing a Paper
|
|
|
|
|
|
|
|
The following principles are meant to make the collaborative development
|
|
|
|
of a paper (written in LaTeX) more efficient. We have successfully used
|
|
|
|
these principles since years and now compiled them here for our students
|
|
|
|
and collaborators in order to make it more efficient for us to ask them
|
|
|
|
to adhere. (This page is originally written by @dbeyer but he received most of the
|
|
|
|
guidelines himself as postdoc from Tom Henzinger.)
|
|
|
|
|
|
|
|
## General Comments
|
|
|
|
|
|
|
|
Treat the source code of a paper as a valuable object that is beeing
|
|
|
|
used, just like program code.
|
|
|
|
Keep the source code clean, readable, and minimal.
|
|
|
|
This really reduces the number of bugs in the document, just like with a
|
|
|
|
good program source code.
|
|
|
|
- Clean: Organize and format the code nicely.
|
|
|
|
- Readable: Structure and organize.
|
|
|
|
- Minimal: Use macros to abbreviate recurring terms, delete
|
|
|
|
unnecessary comments.
|
|
|
|
|
|
|
|
## Editing Text
|
|
|
|
|
|
|
|
- Start each sentence in a new line (makes it easier to move sentences
|
|
|
|
around).
|
|
|
|
- Change line breaks only if you change the text of the line.
|
|
|
|
(Switch off automatic line wrapping of your editor, switch off
|
|
|
|
auto-deletion of white space at the end of line.)
|
|
|
|
- Keep the lines shorter than 80 characters, so that it works with
|
|
|
|
every standard editor.
|
|
|
|
- Avoid tabs, use spaces instead.
|
|
|
|
- Commit everything that is needed to compile the paper.
|
|
|
|
- Check your changes before committing, especially when fixing a text
|
|
|
|
that is considered stable.
|
|
|
|
(Use svn diff, or the Trac web page.)
|
|
|
|
|
|
|
|
## Commenting
|
|
|
|
|
|
|
|
- Use the LaTeX comment symbol '%' for text that you want to keep for
|
|
|
|
later reuse.
|
|
|
|
- Use three of them '%%%' and your name when you want to put
|
|
|
|
explanation for your co-authors.
|
|
|
|
(For example, %%%db: Rick, please prove the following.)
|
|
|
|
- Start each comment on a new line.
|
|
|
|
|
|
|
|
## LaTeX / Macros
|
|
|
|
|
|
|
|
- Use `\newcommand` instead of `\def` (safer, lets you know if already
|
|
|
|
defined).
|
|
|
|
- Use `\cref` and `\Cref` instead of `\ref` in order to get the cross refs
|
|
|
|
consistent.
|
|
|
|
- Use SI to get the gap between quantity and unit right: `\SI{90}{s}`.
|
|
|
|
- Use SI macros for units if you are not sure about unit symbols:
|
|
|
|
`\SI{15}{\minute}`.
|
|
|
|
|
|
|
|
## Writing Style
|
|
|
|
|
|
|
|
- We write "a set S of states", not "a set of states S" (the latter
|
|
|
|
could make the reader think that S is a example single state).
|
|
|
|
- We use "iff" in conditions only, to define someting we use "if".
|
|
|
|
- Replicate vs. reproduce:
|
|
|
|
- We say that results can be reproduced, experiments and
|
|
|
|
runs can be replicated.
|
|
|
|
- Authoritative reference: International Vocabulary of Metrology
|
|
|
|
http://www.bipm.org/utils/common/documents/jcgm/JCGM_200_2012.pdf
|
|
|
|
(Key `MetrologyVocabulary` in https://gitlab.com/sosy-lab/admin/tex/-/blob/master/bib/sw.bib)
|
|
|
|
- repeat: same team with same technical means does the experiment again (check that experiment setup is deterministic and can be replicated by others)
|
|
|
|
- replicate: different team with similar technical means (use same implementation of algorithm; check that implementation works and reported data are valid)
|
|
|
|
- reproduce: different team with different technical means (reimplementation; check that idea works and is not flawed)
|
|
|
|
- ACM uses compatible notions: https://www.acm.org/publications/policies/artifact-review-badging
|
|
|
|
|
|
|
|
|
|
|
|
## Text Style
|
|
|
|
|
|
|
|
- Be careful with spaces and periods:
|
|
|
|
- French spacing: write "John F.\\ Kennedy" in order to avoid the
|
|
|
|
larger space after "F.".
|
|
|
|
- Measures: between numbers and the unit, use the appropriate space
|
|
|
|
"\\,", e.g., 3.3\\,GHz.
|
|
|
|
- Short symbols: write "the state\~\$s\$" and "for all\~\$i\$" and
|
|
|
|
"location\~\$l\$" such that the symbol does not go on next line.
|
|
|
|
Same holds for citations.
|
|
|
|
- Citations:
|
|
|
|
- A reference to literature is gramatically not part of the sentence,
|
|
|
|
always put before period or comma, never use as noun.
|
|
|
|
Bad: "\[3\] says ..." "as described in \[4\]"
|
|
|
|
Good: "... as described by Smith \[4\]."
|
|
|
|
- Always put a ~ in front of a \cite, in order to avoid line breaks
|
|
|
|
before the ref number.
|
|
|
|
- Footnotes:
|
|
|
|
- Footnotes that support a sentence are placed immediately
|
|
|
|
after the period.
|
|
|
|
Footnote that support only a part of the sentence are placed
|
|
|
|
after that part, for example,
|
|
|
|
as in CPA-Seq\,\footnote{...} and UAutomizer\,\footnote{...}.
|
|
|
|
- Spacing: Footnote symbols often look like exponents, therefore,
|
|
|
|
place a \\, before the footnote if it follows a sentence part.
|
|
|
|
|
|
|
|
- Hyphen, dash, and em-dash:
|
|
|
|
- Hyphen is used to connect words in order to ease human parsing:
|
|
|
|
"logic-based, model-checking algorithm".
|
|
|
|
- Dash is used for intervals: "pages 3--17".
|
|
|
|
- Em-dash is used as parenthetic remark in a sentence: "text
|
|
|
|
---remark--- text". Note that there is no space inside of the
|
|
|
|
em-dash, in order to mimic opening and closing.
|
|
|
|
|
|
|
|
## BibTeX File
|
|
|
|
- Use meaningful BibTeX keys (tool or concept, name of an author,
|
|
|
|
perhaps add conference or year).
|
|
|
|
- It is a good idea to write a small excerpt after reading a paper,
|
|
|
|
and store it in the 'note' field; this makes it later easy to find
|
|
|
|
out what this paper is about, and how and why that paper is
|
|
|
|
related.
|
|
|
|
|
|
|
|
## Repository Organization
|
|
|
|
|
|
|
|
### General
|
|
|
|
- Every piece of the paper is exchanged via a version repository.
|
|
|
|
- The main LaTeX file is named "main.tex", and "latex main" or "make"
|
|
|
|
will produce the document.
|
|
|
|
- Once the structure of the paper is quite stable, it is a good idea
|
|
|
|
to break the tex file into several files, one for each section.
|
|
|
|
|
|
|
|
- Add BBL files to the repository. Sometimes we optimize the BBL files
|
|
|
|
for space and don't want to run bibtex anymore. Also, we want to
|
|
|
|
notice in case we accidentally remove a reference.
|
|
|
|
- DOS/Unix headache: In your file `\~/.subversion/config`, add the
|
|
|
|
lines
|
|
|
|
```
|
|
|
|
*.tex = svn:eol-style=native
|
|
|
|
*.bbl = svn:eol-style=native
|
|
|
|
*.png = svn:mime-type=image/png
|
|
|
|
*.jpg = svn:mime-type=image/jpeg
|
|
|
|
*.pdf = svn:mime-type=application/pdf
|
|
|
|
```
|
|
|
|
|
|
|
|
If already too late, ask everybody to commit, take token for the
|
|
|
|
whole paper, and run
|
|
|
|
|
|
|
|
```
|
|
|
|
find ./ -name "*" -exec svn propset svn:eol-style native {} \;
|
|
|
|
svn commit -m "Cleaned up the CF/LF mess."
|
|
|
|
```
|
|
|
|
|
|
|
|
That should clean it up.
|
|
|
|
If this is not done then any change done by a user on the other OS
|
|
|
|
will cause "ghost changes", i.e., lots of lines changed when looking
|
|
|
|
at "svn diff" but they are only due to new line breaks, and it is
|
|
|
|
impossible to track real changes.
|
|
|
|
|
|
|
|
|
|
|
|
### Directory Structure
|
|
|
|
```
|
|
|
|
.
|
|
|
|
|-- documents # folder to keep the documents - submissions, reviews, etc.
|
|
|
|
|-- paper # folder for the paper source
|
|
|
|
|-- talk # folder for the sources of talks
|
|
|
|
```
|
|
|
|
|
|
|
|
### Process
|
|
|
|
|
|
|
|
- apply a tag on every major `stage` of the paper such as paper submission, proceedings, etc.
|
|
|
|
|
|
|
|
Example tag format: `<event>-<YY>-<submission, proceedings, talk>`
|
|
|
|
- create a directory named `documents` which will contain documents (used for interaction with others) related to the paper, e.g., submitted version, reviews, response, copyright, camera ready version.
|
|
|
|
|
|
|
|
Example format for doc name: `<YY>-<event>-<kind>`
|
|
|
|
|
|
|
|
- Branches and merges should typically not be used in order to facilitate change reviews. Merge commits can hide accidental changes because git by default does not show a full diff!
|
|
|
|
To make `git pull` always use rebase, do the following:
|
|
|
|
```
|
|
|
|
git config branch.master.rebase true
|
|
|
|
git config core.autosetuprebase always
|
|
|
|
```
|
|
|
|
|
|
|
|
## An advise that cannot be given often enough
|
|
|
|
|
|
|
|
> I think there is no substitute to a careful reading, in one sitting
|
|
|
|
> from beginning to end, in order to catch inconsistencies (mark them
|
|
|
|
> on paper; fix them later). Just searching for words or patterns
|
|
|
|
> within emacs often introduces more problems than it solves ...
|
|
|
|
|
|
|
|
Tom Henzinger,
|
|
|
|
2006-10-13
|
|
|
|
|
|
|
|
## Useful Links
|
|
|
|
|
|
|
|
- Oliver Strunk. [The Elements of
|
|
|
|
Style](http://www.orwell.ru/library/others/style/english/).
|
|
|
|
- Donald E. Knuth, Tracy L. Larrabee, and Paul M. Roberts.
|
|
|
|
[Mathematical
|
|
|
|
Writing](http://tex.loria.fr/typographie/mathwriting.pdf).
|
|
|
|
- [The Comprehensive LaTeX Symbol
|
|
|
|
List](http://www.ctan.org/tex-archive/info/symbols/comprehensive/symbols-a4.pdf)
|
|
|
|
- [Online help with LaTeX commands
|
|
|
|
](http://www-ti.informatik.uni-tuebingen.de/%7Efrech/latex/ltx-2.html)
|
|
|
|
- [LaTeX web page](http://www.latex-project.org/)
|
|
|
|
- [A one-page intro to
|
|
|
|
LaTeX](http://www.techscribe.co.uk/ta/latex-introduction.pdf)
|
|
|
|
- [The (Not So) Short Introduction to
|
|
|
|
LaTeX2e](http://ctan.tug.org/tex-archive/info/lshort/english/lshort.pdf)
|
|
|
|
- [Subversion book](http://svnbook.red-bean.com/)
|
|
|
|
- [Subversion tutorial](http://artis.imag.fr/%7EXavier.Decoret/resources/svn/index.html)
|
|
|
|
- [Nice software to draw pictures: InkScape](http://www.inkscape.org/)
|
|
|
|
(based on SVG, provides export to EPS and PDF)
|
|
|
|
|
