Date: Fri, 29 Mar 2024 10:02:06 +0000 (UTC)
Message-ID: <1006152993.6495.1711706526927@2f9704fbf185>
Subject: Exported From Confluence
MIME-Version: 1.0
Content-Type: multipart/related;
boundary="----=_Part_6494_1170433507.1711706526927"
------=_Part_6494_1170433507.1711706526927
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Content-Location: file:///C:/exported.html
This page contains some general guidelines on how to proceed whe=
n preparing a scientific paper (for a workshop, conference, journal, etc). =
The focus here is on the proper use of the Git repositories, in parti=
cular the Papers project. This project contains publicat=
ions and presentations, and is subsequently referred to as "rt papers repos=
itory" or just "papers repository". See Git/Structure =
on how this fits into the rest of the Gitorious project and repository stru=
cture.
Table of Contents
Guidelines for the=
Paper and the Talk
- Two guiding principles should be
- ABSTRACTION means that typesetting instructions should be abstracted ("=
Write Things Once") into macros or general parameter settings. Eg, the form=
at 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 tha=
t is reused by other papers.
- CONSISTENCY means that papers and talks should have a uniform appearanc=
e. This is facilitated by using common style files and common macros (eg, y=
ou should always use the "\eg" macro for writing eg, and should use one com=
mon definition for this macro).
- The standard format for talks is the beamer style used also in the lect=
ures. If for some reason you still prefer to use another format for the tal=
k, 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 u=
se absolute lengths that are not compatible with the paper size used by bea=
mer. (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, e=
g ".2\textwidth".)
Repositories
All files needed for creating a publication are stored in shared reposit=
ories (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".<=
/p>
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 wh=
ich should be used to compile files in the papers repository - see below.=
li>
- 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 p=
roject and contains some latex style files shared by the group, eg "cau-rt.=
sty" (mainly for papers), "beamercustom.sty" (mainly for presentations), "l=
stcustom.sty" (included by the former files) and related files, and is refe=
rred to as "rt latex repository" or just "latex repository".
Local Copies of the R=
epositories
- Everybody's local copies of the papers and bib repostories should resid=
e in the same directory; ie, from within the papers repository, the bib rep=
ository 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 ab=
ove/below).
- Per default, the parent directory of private repository copies should b=
e named "~/shared"; ie, the private repository copies should be named "~/sh=
ared/papers" and "~/shared/bib". However, one should not rely on this namin=
g 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, usin=
g 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 th=
e 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 (conferen=
ce, journal, technical report, or just a presentation - eg for SYNCHRON). H=
enceforth each directory within the paper repository is referred to as "pap=
er directory". There are several paper directories, but just one paper repo=
sitory.
Naming th=
e 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 al=
so the year of publication. Henceforthe this name is referred to as <ven=
ue>.
- 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-YY=
NN", eg "report-0506"
- If there are multiple submissions to the same venue, <venue> shou=
ld be extended accordingly in some meaningful fashion. Per default, this sh=
ould be the login of the first author. If this is still not unique, use som=
e additional extension - but preferrably not just a numbering.
Example: Two submissions to DATE'07 University booth are named "date07-s=
pr" and "date07-xli".
- The tex-file for the paper should be named <venue>.tex - eg "repo=
rt-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 f=
rom, and
- there would be name clashes if multiple papers should for some reason r=
eside in the same directory.
This would be problematic eg when mailing several papers together, or wh=
en making the papers available for download somewhere. Naming the papers ac=
cording to their parent directory ensures that paper names are meaningful a=
nd unique.)
- If the submission procedures require that the submitted paper (typicall=
y the pdf) should be named differently, the source of the paper should stil=
l be named <venue>.tex, and one should still produce <venue>.pd=
f; the submitted file should be a copy of <venue>.pdf. This can be au=
tomated by adding an appropriate target to Makefile.local (see below), eg s=
omething like
.PRECIOUS: 118.pdf 118.pdf: sac06.pdf
cp $< $@
The Talk
- For conference papers, the slides for the talk should reside in directl=
y 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 cont=
ain animations, one can do so with "\documentclass[trans]{beamer}". The res=
ulting .pdf should be named <venue>-handout.pdf (see also the note be=
low). The default Makefile already includes a target to generate this versi=
on.
- 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.=
li>
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 possi=
ble. This is nice, but generally overkill for handouts created for electron=
ic download to accompany papers. At some point (Feb 2009), the tea round de=
creed that we give up on this consistency, for sake of simplicity and brevi=
ty. 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 a=
nd Oberseminar are similar, see here =
a>.
Technical Reports
The institute's Technical Reports ("Technische Berichte") include a stan=
dardized title page; see ifireport/ifireport.sty in the latex repository. U=
nfortunately, there is no macro (yet?) to include directly in <venue>=
.tex to generate the title page; this title page must be generated separate=
ly. The source for the title page should be named <venue>-title.tex.<=
/p>
One way to generate the full report, including the title page, is to sep=
arately create two pdfs (<venue>.pdf and <venue>-title.pdf), an=
d then to collate them. One way to do this is described in http://www.informatik.uni-kiel.de/reports/guidelines.html<=
/a>, using dvips, ps2pdf and texexec. The Makefile contains one target (%-a=
ll.pdf) to achieve the same, using pdfmerge. This works, but has disadvanta=
ges:
- 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=3D1x1,pages=3D-=
]{<venue>-title.pdf} \setcounter{page}{1}
- ensure that the title is regenerated when needed - eg by creating a Mak=
efile.local that contains the rule
<venue>.pdf: <venue>-title.pdf
What Should Go i=
nto the Paper Directory
- <venue>[-talk].tex, <venue>[-talkhandout].pdf<=
/li>
- All other files produced directly by the authors - ie, other tex-source=
s (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. (excludi=
ng personal booking information).
What should N=
OT go into the paper directory
- Intermediate files - .aux, .bbl, .toc, etc.
- Style files etc. that are part of the tex-installation - ie, part of Te=
X-Live
The Bib=
liography - Guidelines for bibtex Entries
Bib files
In general, one should try to not use a "personal" bi=
b file for a paper or a thesis, but use one of the shared bib files that ar=
e in the Git bib repository. (See Git/Structure =
;) The rationale is that this makes it easier to share entries and to k=
eep 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:=
p>
- 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)
.bib:publicationsby">pub-<user&g=
t;.bib: publications by <user>
This contains publications that are not included in p=
ub-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: s=
tudent theses
This contains student theses (Bachelor/Master/Studien).
For the formatting of "Masterarbeiten", see eg. Wechselberg15. In partic=
ular:
- The entry type is MastersThesis
- school =3D {Kiel University, Department of Computer Science}
- type =3D {Master thesis}
- If the work is not submitted yet, add a note "To appear"; otherwise, ad=
d 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 s=
hould go to pub-*.bib or rts-arbeiten.bib. In case you have an electronic v=
ersion 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 stor=
e the paper in the group's Digital Lib=
rary .
Language and text coding
The language is english, as this is the language of most papers using th=
ese entries. That means:
- Instead of "Institut f=C3=BCr Informatik" use "Department of Computer S=
cience"
- Instead of "Technischer Bericht" use "Technical Report"
- Instead of "Christian-Albrechts-Universit{\"a}t zu Kiel" use "Kiel Univ=
ersity"
To write german umlauts and other special characters use the standard te=
x coding i.e. {\"a}, {\"o}, {\"u}, {\ss}
Keys
The key should be generated according to the following format
<N1>[<N2>][+]<YY>[<CT>], with
<N1> :=3D Last name of first author, capitalized, blanks eliminate=
d
<N2> :=3D First letter(s) of last names of 2nd - 4th author (if mo=
re than 1 author) Note: there should be one letter for each part of the las=
t name eg. "Sangiovanni-Vincentelli" becomes "SV" (not just "S"), "von Hanx=
leden" becomes "vH" (not just "H")
+ indicates more than 4 authors
<YY> :=3D last 2 (not 4!) digits of year of publication
<CT> :=3D alphabetic counter to resolve identical keys (a, ... z, =
aa, ab, ...)
If there are no conflicts (<CT>-field empty), this scheme should a=
llow 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 chec=
ker may assume that the citations here do not span more than 100 years :-)<=
/li>
- If the above are identical, the <CT>-part of key. Eg: Edwards99, =
Edwards02, Edwards02a, Edwards02b, Edwards03, EdwardsHvHS05, EdwardsKH04
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 f=
or public download and did not appear in archival journals or established c=
onference/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 in=
clude the URL.
A URL should be included like this:
note =3D {\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 d=
efined 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 guidelin=
es 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 publicatio=
n itself
- For portability, month entries should use abbreviations; use the `#'-op=
erator to concatenate. For example: month =3D sep # "/" # oct, or: month =
=3D "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 Mak=
efile should be used, which resides in the make repository. To implement th=
is, each paper directory should contain a Makefile that just contains an in=
clude command, with a relative reference to the Makefile in the make reposi=
tory. 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 defau=
lt 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 sti=
ll 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 th=
e 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 .pdf=
s.
and reference <venue>.pdf in the "pdf" field of the bib-entry.
(note the different target directories) and reference <venue>-talk=
.pdf in the "urltalk" field of the bib-entry. If you prefer to post the sli=
des without animation, you may replace <venue>-talk.pdf with <venu=
e>-handout.pdf.
- Once you have pushed your changes to pub-rts.bib, the update of the pub=
lication page is then triggered by
=09ssh biblio@rtsys.informatik.uni-kiel.de "(cd ~/git/b=
ib; git pull)"
=09ssh biblio@rtsys.informatik.uni-kiel.de "(cd ~/bib; make cleanhtml)"
=09ssh biblio@rtsys.informatik.uni-kiel.de "(cd ~/bib; make)"
- The default Makefile assists with these steps with the "%p", "%pt" and =
"bibhtml" targets
------=_Part_6494_1170433507.1711706526927--