Writing-Papers-(Technical).md

+# 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)
+