Rtsys Group Wiki
Page tree
Skip to end of metadata
Go to start of metadata

This page contains some general guidelines on how to proceed when preparing a scientific paper (for a workshop, conference, journal, etc). The focus here is on the proper use of the Git repositories, in particular the Papers project. This project contains publications and presentations, and is subsequently referred to as "rt papers repository" or just "papers repository". See Git/Structure on how this fits into the rest of the Gitorious project and repository structure.

Table of Contents

Guidelines for the Paper and the Talk

  • Two guiding principles should be
    • abstraction
    • consistency
  • ABSTRACTION means that typesetting instructions should be abstracted ("Write Things Once") into macros or general parameter settings. Eg, the format of listings should be specified as much as possible in just one place - at the beginning of <venue>.tex, or, even better, in a style file that is reused by other papers.
  • CONSISTENCY means that papers and talks should have a uniform appearance. This is facilitated by using common style files and common macros (eg, you should always use the "\eg" macro for writing eg, and should use one common definition for this macro).
  • The standard format for talks is the beamer style used also in the lectures. If for some reason you still prefer to use another format for the talk, then at least the tex-source (<venue>-talk.tex - see below) should be written in a way compatible with the beamer style. Eg, you should not use absolute lengths that are not compatible with the paper size used by beamer. (In general it is not a good style to use absolute lengths to specify the size and placement of objects, you should instead use relative sizes, eg ".2\textwidth".)

Repositories

All files needed for creating a publication are stored in shared repositories (git). When you start writing a paper, start in a shared repository; don't start in your personal account to migrate to the repository "later".

The bib Repository

  • The bib repository is part of the Resources project, and is referred to as "rt bib repository" or just "bib repository".
  • The bib repository contains the bibliography maintained by the rt group, "cau-rt.bib", and some other files for validating the repository ("cau-rt-test.tex" etc.)
  • The bib repository also contains a "Makefile", which is the Makefile which should be used to compile files in the papers repository - see below.
  • The submission procedures may require that the .bbl is pasted into the .tex. The bib repository contains a script "insertbbl" that does just that. This can be used eg. in a Makefile.local as follows:

.PRECIOUS: asplos037-li.tex asplos037-li.tex: asplos06.tex

insertbbl asplos06.tex asplos037-li.tex

Note: to use this, you must have the bib repository on your PATH.

The latex Repository

  • The latex repository is also part of the Resources project and contains some latex style files shared by the group, eg "cau-rt.sty" (mainly for papers), "beamercustom.sty" (mainly for presentations), "lstcustom.sty" (included by the former files) and related files, and is referred to as "rt latex repository" or just "latex repository".

Local Copies of the Repositories

  • Everybody's local copies of the papers and bib repostories should reside in the same directory; ie, from within the papers repository, the bib repository can be reached with "../bib", and vice versa. One should be able to rely on this, eg when including the Makefile in the bib-repository (see above/below).
  • Per default, the parent directory of private repository copies should be named "~/shared"; ie, the private repository copies should be named "~/shared/papers" and "~/shared/bib". However, one should not rely on this naming scheme.
  • Things are a little different for the latex repository. This should be placed such that they can be found by the local TeX-Live installation, using the standard texhash procedure. The recommended place for the local copy of the latex repository is

~/texmf/tex/latex/shared

Eg, beamercustom.sty would then be found (after checking out/updating the local copy of the latex repository and running "texhash") under

~/texmf/tex/latex/shared/latex/beamer/beamercustom.sty

Structure and Naming Conventions

  • Each directory within the paper repository contains one paper (conference, journal, technical report, or just a presentation - eg for SYNCHRON). Henceforth each directory within the paper repository is referred to as "paper directory". There are several paper directories, but just one paper repository.

Naming the paper repository and paper tex-file

  • Each paper has its own Git repository in the Papers project, whose name should indicate the venue where it is published, and also the year of publication. Henceforthe this name is referred to as <venue>.
  • Per default the year should be abbreviated to the last two digits
  • For conference papers, <venue> should be the abbreviation for the conference - eg "date06", "itsc05"
  • Foe technical reports, the format of <venue> should be "report-YYNN", eg "report-0506"
  • If there are multiple submissions to the same venue, <venue> should be extended accordingly in some meaningful fashion. Per default, this should be the login of the first author. If this is still not unique, use some additional extension - but preferrably not just a numbering.

Example: Two submissions to DATE'07 University booth are named "date07-spr" and "date07-xli".

  • The tex-file for the paper should be named <venue>.tex - eg "report-0506.tex".

(An alternative would be to name the file just something like "paper.tex", which would suffice in principle, as the directory name already uniquely identifies the paper. However, this has the disadvantages that

  • the paper in isolation would not indicate any more where it is coming from, and
  • there would be name clashes if multiple papers should for some reason reside in the same directory.

This would be problematic eg when mailing several papers together, or when making the papers available for download somewhere. Naming the papers according to their parent directory ensures that paper names are meaningful and unique.)

  • If the submission procedures require that the submitted paper (typically the pdf) should be named differently, the source of the paper should still be named <venue>.tex, and one should still produce <venue>.pdf; the submitted file should be a copy of <venue>.pdf. This can be automated by adding an appropriate target to Makefile.local (see below), eg something like

.PRECIOUS: 118.pdf 118.pdf: sac06.pdf

cp $< $@

The Talk

  • For conference papers, the slides for the talk should reside in directly in the paper repository (not in a subdirectory).
  • The tex file for the slides should be named <venue>-talk.tex - eg "date06-talk.tex".
  • If one wants to create another version of the slides that does not contain animations, one can do so with "\documentclass[trans]{beamer}". The resulting .pdf should be named <venue>-handout.pdf (see also the note below). The default Makefile already includes a target to generate this version.
  • Again the unique naming of the talk facilitates using the talk outside of this paper repository, eg for distributing it via mail or www.
  • The beamer customization files should come from the latex repository.

Note: <venue>-handout.pdf used to be called <venue>-talk-trans.pdf, to be consistent with the convention used for the lecture notes in course work. There, one also has a *-handout.pdf, but this is more than just a talk without animations - eg, it uses a different, printer friendly coloring scheme and suppresses empty note pages if possible. This is nice, but generally overkill for handouts created for electronic download to accompany papers. At some point (Feb 2009), the tea round decreed that we give up on this consistency, for sake of simplicity and brevity. The result is that there are two rules in the Makefile for generating a *-handout.pdf:

  • Rule 1) looks for a *-talk.tex and just strips away animations
  • Rule 2) just looks for a *.tex and does the paper and ink saving.

Rule 1) is the default to be used for papers and seminar presentations, Rule 2) is the rule used for lecture notes.

Another note: naming conventions for the seminar and Oberseminar are similar, see here .

Technical Reports

The institute's Technical Reports ("Technische Berichte") include a standardized title page; see ifireport/ifireport.sty in the latex repository. Unfortunately, there is no macro (yet?) to include directly in <venue>.tex to generate the title page; this title page must be generated separately. The source for the title page should be named <venue>-title.tex.

One way to generate the full report, including the title page, is to separately create two pdfs (<venue>.pdf and <venue>-title.pdf), and then to collate them. One way to do this is described in  http://www.informatik.uni-kiel.de/reports/guidelines.html, using dvips, ps2pdf and texexec. The Makefile contains one target (%-all.pdf) to achieve the same, using pdfmerge. This works, but has disadvantages:

  • one extra pdf is generated
  • pdfmerge takes a couple of seconds, esp. for larger files

Hence, a suggested alternative to using this target is to

  • still generate an extra <venue>-title.pdf
  • include this <venue>-title.pdf in the main <venue>.pdf - eg with
\usepackage{pdfpages} \begin{document} \includepdf[nup=1x1,pages=-]{<venue>-title.pdf} \setcounter{page}{1}
  • ensure that the title is regenerated when needed - eg by creating a Makefile.local that contains the rule

<venue>.pdf: <venue>-title.pdf

What Should Go into the Paper Directory

  • <venue>[-talk].tex, <venue>[-talkhandout].pdf
  • All other files produced directly by the authors - ie, other tex-sources (such as <venue>-title.tex, see the note on Technical Reports above) and style files created/modified specifically for this paper.
  • The Makefile - see below.

Optional Contents

Optional files:

  • Makefile.local (see below)
  • Call for Papers, which should be named <venue>-cfp.{txt|pdf|html}

Optional sub-directories:

  • "instructions", containing author instructions.
  • "images", containing graphics included in a paper (ps|pdf|jpg|...)
  • "reviews", containing external reviews.
  • "travel-info", containing maps, public transit schedules, etc. (excluding personal booking information).

What should NOT go into the paper directory

  • Intermediate files - .aux, .bbl, .toc, etc.
  • Style files etc. that are part of the tex-installation - ie, part of TeX-Live

The Bibliography - Guidelines for bibtex Entries

Bib files

In general, one should try to not use a "personal" bib file for a paper or a thesis, but use one of the shared bib files that are in the Git bib repository. (See Git/Structure ) The rationale is that this makes it easier to share entries and to keep them consistent.

The bib repository includes the following files:

pub-rts.bib: publications of the rt group

This file should contain proper publications, as they should appear for example in the Almanach or in the "publications" web page. This includes:

  • books, book chapters, journal/conference/workshop papers
  • technical reports
  • dissertations

This does not include pretty much everything else, in particular

  • submitted, but not (yet) accepted papers
  • project reports
  • seminar presentations
  • Bachelor-/Master-/Studien-/Diplomarbeiten ("student works")

If you want to reference such documents that are excluded here, you can include them in cau-rt.bib or rts-arbeiten.bib (for student works)

pub-<user>.bib: publications by <user>

This contains publications that are not included in pub-rts.bib. This includes

  • Publications authored before joining the rt group.
  • Student works (which are also listed in rts-arbeiten.bib).

The publication web page of <user> is extracted from the union of pub-rts.bib and pub-<user>.bib.

rts-arbeiten.bib: student theses

This contains student theses (Bachelor/Master/Studien).

For the formatting of "Masterarbeiten", see eg. Wechselberg15. In particular:

  • The entry type is MastersThesis
  • school = {Kiel University, Department of Computer Science}
  • type = {Master thesis}
  • If the work is not submitted yet, add a note "To appear"; otherwise, add the month accordingly to the date of submission.
  • There is no note "unpublished".

cau-rt.bib: publications outside of the rt group

This file contains references used by the group, excluding publications and student works produced by the group itself - these should go to pub-*.bib or rts-arbeiten.bib. In case you have an electronic version of a referenced paper, and that paper was not trivially available on the web, you should consider to not just add a bib entry, but also to store the paper in the group's Digital Library .

Language and text coding

The language is english, as this is the language of most papers using these entries. That means:

  • Instead of "Institut für Informatik" use "Department of Computer Science"
  • Instead of "Technischer Bericht" use "Technical Report"
  • Instead of "Christian-Albrechts-Universit{\"a}t zu Kiel" use "Kiel University"

To write german umlauts and other special characters use the standard tex coding i.e. {\"a}, {\"o}, {\"u}, {\ss}

Keys

The key should be generated according to the following format

<N1>[<N2>][+]<YY>[<CT>], with

<N1> := Last name of first author, capitalized, blanks eliminated

<N2> := First letter(s) of last names of 2nd - 4th author (if more than 1 author) Note: there should be one letter for each part of the last name eg. "Sangiovanni-Vincentelli" becomes "SV" (not just "S"), "von Hanxleden" becomes "vH" (not just "H")

+ indicates more than 4 authors

<YY> := last 2 (not 4!) digits of year of publication

<CT> := alphabetic counter to resolve identical keys (a, ... z, aa, ab, ...)

If there are no conflicts (<CT>-field empty), this scheme should allow correct citing without having to look up the key in the bib-file.

Order of entries

The entries should appear in the bib file in the following order:

  • Lexical ordering of the key except that (implicity) the hidden first two digits of the year should be considered as well

This implies:

  • Alphabetical by (all) authors
  • For the same author combination, year of publication except that 99 comes before 00 (If this is checked automatically, the checker may assume that the citations here do not span more than 100 years :-)
  • If the above are identical, the <CT>-part of key. Eg: Edwards99, Edwards02, Edwards02a, Edwards02b, Edwards03, EdwardsHvHS05, EdwardsKH04

Comments

Comments should be added for the following

  • AAA ... ZZZ denote the letters of last names of first authors
  • Last names of first authors (once)
  • login of bib-creator + date (format YYYY-MM-DD) + "DL", if cached in Digital Library ?
  • URL, for downloadable papers
  • OPTIONAL: additional info, e.g. usage in a seminar

URLs

It can be helpful to include a URL for publications that are available for public download and did not appear in archival journals or established conference/workshop venues. There are bibtex styles that make use of a field "url" for just this purpose. However, most of the standard bib styles just ignore this field. Therefore, to have bib entries as portable as possible, we advocate to use the "note" field (which is generally not ignored) to include the URL.

A URL should be included like this:

note = {\url{ http://the.host.with.some/paper.pdf}}

Of course, the note may still contain additional information as well.

The one prerequisite for this to work is that the \url macro has to be defined before the \bibliography command appears in the .tex source. This is typically done by including the url package.

Note that this convention gives you full flexibility on how URLs should appear in the bibliography. This includes the option to not list any urls, by redefining the \url macro accordingly.

Further guidelines for adding entries

  • In general, entries should be as complete as possible
  • If known, first names of authors should be included
  • Titles should be capitalized iff they are capitalized in the publication itself
  • For portability, month entries should use abbreviations; use the `#'-operator to concatenate. For example: month = sep # "/" # oct, or: month = "1.~" # apr

The Makefile

  • To compile a paper or presentation, a Makefile can be used. However, to avoid re-inventing the wheel and for a common user interface, a common Makefile should be used, which resides in the make repository. To implement this, each paper directory should contain a Makefile that just contains an include command, with a relative reference to the Makefile in the make repository. Ie, the Makefile in a paper directory should just contain the line

include ../../make/Tex.makefile

  • Deviations from this Makefile or customizations (eg, specifying a default target) should be contained in "Makefile.local", which, if it exists, is included by the Makefile in the bib repository. Note: as Makefile.local is still part of the repository, the customizations in Makefile.local are still shared by all users. If you really, really need customizations just for yourself, you should find some other way to incorporate them - eg by adding new targets or variables to the Makefile.

Making the Paper/Talk Available for Electronic Download

  • Congratulations - your paper has been accepted! Now you should share the joy by making it available via the group's publication page. This is done by posting the .pdfs for the paper and also for the talk, if there is any, and by adding an entry for the paper to pub-rts.bib that links to the .pdfs.
  • To make the paper available for download, post it with
    scp <venue>.pdf biblio@rtsys.informatik.uni-kiel.de:/home/biblio/public_html/downloads/papers

and reference <venue>.pdf in the "pdf" field of the bib-entry.

  • To make the slides available for download, post them with
    scp <venue>-talk.pdf biblio@rtsys.informatik.uni-kiel.de:/home/biblio/public_html/downloads/talks

(note the different target directories) and reference <venue>-talk.pdf in the "urltalk" field of the bib-entry. If you prefer to post the slides without animation, you may replace <venue>-talk.pdf with <venue>-handout.pdf.

  • Once you have pushed your changes to pub-rts.bib, the update of the publication page is then triggered by
	ssh biblio@rtsys.informatik.uni-kiel.de "(cd ~/git/bib; git pull)"
	ssh biblio@rtsys.informatik.uni-kiel.de "(cd ~/bib; make cleanhtml)"
	ssh biblio@rtsys.informatik.uni-kiel.de "(cd ~/bib; make)"
  • The default Makefile assists with these steps with the "%p", "%pt" and "bibhtml" targets
  • No labels