README.md 6.92 KB
Newer Older
Alessandra Gorla's avatar
Alessandra Gorla committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
imdea-se-bib:  collection of BibTeX bibliography files
======================================================

This project is a fork of forked of the plume-bib project from Michael
D. Ernst: https://github.com/mernst/plume-bib

To obtain the bibliographies, run:

   git clone https://gitlab.software.imdea.org/alessandra.gorla/imdea-se-bib.git

This is a set of BibTeX bibliographies.  You can re-use them rather than
having to re-type or download.  Re-typing or downloading bibliography
entries is a notorious source of errors.  For example, even the ACM Digital
Library often has incorrect capitalization, or gives a SIGPLAN Notices
reference when the conference proceedings would be more appropriate.

Here are some other features:

 * Short and long versions of names, locations, and dates for
   conferences, journals, etc.  The short (abbreviated) version is
   convenient if your paper is nearing its page limit.  Changing
   between the two versions only requires a tiny change to your LaTeX
   file (see below), and no changes to any bib files.
   
 * Consistent naming convention for citation keys: last name of first
   author, followed by last initial of each other author, followed by
   year.  This makes the citation more recognizable in your LaTeX
   source, and avoids duplicates.
   
 * Searchable via the bibfind tool.  For instance, `bibfind keyword1
   keyword2` displays all the bibliographies with all the keywords,
   either in the entries in the comments.  (This is why there are no
   blank lines in the comments that abut some bib entries: the search
   tool considers each blank line to start a new entry.  We may lift
   that restriction in the future.)

You can obtain the bibliographies by running the command
`git clone https://gitlab.software.imdea.org/alessandra.gorla/imdea-se-bib.git`
but you do not need to -- see below for how to set your build system to
automatically obtain and/or update a copy.

You can also set the `IMDEASEBIB` environment variable to the location of your
clone (usually a directory named bib), so that you will have just one clone
rather than one for each paper you write.


USAGE
-----

To choose the abbreviated (short) or unabbreviated (long) version of the
bibliography strings, use one of these commands in your LaTeX file:

53
54
55
56
57
58
59
60
61
62
Most complete option. It will use full strings for journals
(`bibstring-unabbrev`) and full proceedings info for conferences
(`crossrefs`).

     \bibliography{bibstring-unabbrev,...,crossrefs}

No month and address option. It will use short strings for journals
(`bibstring-abbrev`) and full proceedings info for conferences, but
omitting months and addresses.  (`crossrefs-abbrev`).

Alessandra Gorla's avatar
Alessandra Gorla committed
63
    \bibliography{bibstring-abbrev,...,crossrefs-abbrev}
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

Abbreviations option. It will use short strings for journals
(`bibstring-abbrev`) and will shorten some words in the proceedings
info for conferences (e.g. Proceedings --> Proc., Conference -->
Conf.) as in `crossrefs-abbrevv`. 

    \bibliography{bibstring-abbrev,...,crossrefs-abbrevv}

Super-compressed option. It will use short strings for journals
(`bibstring-abbrev`) and will shorten proceedings for conferences
leaving only acronyms.  (e.g. ICSE 2017: Proceedings of the
International Conference...--> ICSE 2017), as in
`crossrefs-super-abbrev`.

    \bibliography{bibstring-abbrev,...,crossrefs-super-abbrev}
Alessandra Gorla's avatar
Alessandra Gorla committed
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192

When using the bibliographies, add near the top of your LaTeX document:

    \usepackage{url}

This defines the `\url` command used in the bibliographies.  To make URLs use
a slightly narrower font (the regular `tt` font is very wide), use:

    \usepackage{pslatex}

or, to use a smaller font, use:

    \usepackage{relsize}
    \def\UrlFont{\smaller\ttfamily}


EDITING AND ADDING ENTRIES
--------------------------

Changes, corrections, and additions are welcome.

When adding new bibliography entries, please create an entry in
`crossrefs.bib` for conferences, and create bibliography strings in
`bibstring-master` for journal/institution names and abbreviations.

For consistency, please start each new bibliography entry with "@" in the
first column, and end the entry with "}" on its own line.

If you make changes but you lack write access to the Git repository
then please submit a pull request, or email a patch (a diff file) with
your changes to Alessandra Gorla <alessandra.gorla@imdea.org>.


SETUP -- if you use a Makefile to process your paper
----------------------------------------------------

1. Add "bib" as a dependency for the rule that calls bibtex; for example,
   make "bib" a dependency for the myfile.bbl target.  If no rule calls
   bibtex, you can skip this step.
2. Add "bib-update" as a dependency of your default target (such as "all").
3. Add the following rules to your Makefile.

    export BIBINPUTS ?= .:bib
    bib:
    ifdef IMDEASEBIB
	    ln -s ${IMDEASEBIB} $@
    else
	    git clone https://gitlab.software.imdea.org/alessandra.gorla/imdea-se-bib.git $@
    endif
    .PHONY: bib-update
    bib-update: bib
    # Even if this command fails, it does not terminate the make job.
    # However, to skip it, invoke make as:  make NOGIT=1 ...
    ifndef NOGIT
	    -(cd bib && git pull && make)
    endif


SETUP -- non-Makefile version
-----------------------------

If you have previously cloned plume-bib and set the IMDEASEBIB environment
variable, there is nothing to do.  Otherwise, run this command:

    cd; git clone https://gitlab.software.imdea.org/alessandra.gorla/imdea-se-bib.git bib

Then, set the IMDEASEBIB environment variable to $HOME/bib and
add the "bib" directory to your BIBINPUTS environment variable.

bash syntax:

    export IMDEASEBIB=$HOME/bib
    export BIBINPUTS=.:${IMDEASEBIB}:..:


SETUP -- miscellaneous details
------------------------------

For the bibfind command, see
https://github.com/mernst/uwisdom/blob/wiki/README.adoc .
The bibfind command uses the `bibroot` file in the `imdea-se-bib` directory.

If you wish to have only a single copy of the bibliographies on your
computer, you can clone the repository just once and set the IMDEASEBIB
environment variable.  Then your Makefile will create (or you can make by
hand) a symbolic link from any directories where you are writing a paper.

Note for miktex users:
The bibtex that is supplied with miktex (the popular Windows implementation)
does not support the BIBINPUTS variable. You need to modify the miktex
configuration.  In file `...\miktex\config\miktex.ini`, edit this entry:

    Input Dirs=searchpath
    (search path for BibTeX input files -- both databases and style files).


INVOKING BIBTEX: crossref and -min-crossrefs=9999
-------------------------------------------------

imdea-se-bib's .bib files use `@crossref`.  To avoid outut like

    [1] Brun et al.  Paper title.  In [2].
    [2] Proceedings of ESEC/FSE 2011.  Szeged, Hungary, Sep. 7--9, 2011.

you need to pass the -min-crossrefs=9999 command-line option to BibTeX; for
example:

    bibtex -min-crossrefs=9999 mypaper


LICENSE
-------

Uses the Creative Commons Attribution ("CC-BY") license.  See file LICENSE.