summaryrefslogtreecommitdiff
path: root/support/copac-clean/copac-clean.tex
blob: 0a94952f5170e9f1cfbc6bff8b01a35474f0b367 (plain)
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
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
% Documentation for copac-clean
% Guido Milanese - guido.milanese@unicatt.it
% Version 0.8
%
\documentclass[a4paper,11pt,english]{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{url}
\renewcommand{\UrlFont}{\footnotesize\tt}
\usepackage{babel}
\usepackage{graphicx}
\usepackage{libertine}
\begin{document}
\title{The copac-clean utility\\
Version 0.8}
\author{Guido Milanese <\url{guido.milanese@unicatt.it}>}
\date{28th August 2015}
\maketitle
\thispagestyle{empty}
%
\begin{abstract}
\noindent{}This standalone utility edits the Copac/BibTeX records,
improving some details and adding some useful fields. The programme is
written using Snobol for editing, tck/tk for a simple GUI and a bash
script as framework. The utility is only available for use under Linux, but could easily be ported to Windows.
\end{abstract}
%
\tableofcontents{}
\enlargethispage{3.3mm}
%
\section{Copac-clean: description and features}
Copac (\url{http://copac.ac.uk}) is one of the best resources for
academics, students, librarians: it unifies more the 70 catalogues of
libraries of the UK, featuring around  «40 million records in 452
languages» (Copac information from \url{http://copac.ac.uk/faq/}). Copac
records can be exported in several formats, including BibTeX. However, some
minor details of the Copac/BibTeX format can be improved, and -- particularly for Biblatex users -- some more fields can be easily added. 

\subsection{Editing}
This is a typical COPAC/BibTeX record:\label{exrecord}
\footnotesize%
\begin{verbatim}
@proceedings{Giannantoni:1996,
author = {Giannantoni, Gabriele. and Gigante, Marcello,},
title= {Epicureismo greco e romano : atti del congresso
        internazionale, Napoli, 19-26 maggio 1995},
series = {Elenchos ; 25 },
series = {Elenchos (series) ; 25. },
address = {[Napoli] : },
publisher = {Bibliopolis,},
year = {c1996.},
size = {3 v. (1128 p.) ; 23 cm.},
language = {English ; French ; German ; Italian},
isbn = {ISBN: 8870883620},
note = {Papers from an international congress 
        held in Naples, 19-26 May 1993.},
note = {Includes bibliographical references (v. 3, p. [1005]-1056)
       and indexes.},
note = {Italian, English, French and German contributions.},
keywords = {Epicurus -- Congresses.},
keywords = {Epicurus -- Influence -- Congresses.},
keywords = {Philosophy, Ancient -- Congresses.},
location = {King's College London ; University of London - ULRLS},
}
\end{verbatim}
\normalsize%
The first problem that any BibTeX user can detect is useless punctuation.
For example:
\footnotesize%
\begin{verbatim}
      author = {Giannantoni, Gabriele. and Gigante, Marcello,},
\end{verbatim}
\normalsize%
should be improved as follows:
\newpage{}
\footnotesize%
\begin{verbatim}
      author = {Giannantoni, Gabriele and Gigante, Marcello},
\end{verbatim}
\normalsize%
The same applies to all the other entries (see e.g. \textsf{year},
\textsf{address}, etc.).
Improving this inaccurate, useless punctuation is the first purpose of this
utility.

See now the \textsf{note} field(s):
\footnotesize%
\begin{verbatim}
    note = {Papers from an international congress 
              held in Naples, 19-26 May 1993.},
      note = {Includes bibliographical references (v. 3, p. [1005]-1056)
              and indexes.},
\end{verbatim}
\normalsize%
In most BibTeX / Biblatex styles the contents of \textsf{note} field is
printed (e.g. «Reprint of the edition Oxford, Oxford U.P. 1976»). The
\textsf{note} field is used by Copac for comments (e.g. if the book
offers a bibliography); for this reason the utility changes
\textsf{note} to \textsf{annote}.

Another change is \textsf{author} if the record type is
\textsf{proceedings} (see the example above). In this case
\textsf{author} is changed to \textsf{editor}. 

\subsection{Hyphenation}
This feature is useful only to Biblatex users. If the field
\textsf{language} features one and only one language, the field is
transformed from \textsf{language} to \textsf{langid}, and the language
name is transformed according to table 2, page 25 of Philipp Lehman's
Biblatex manual, version 3.0, 20.04.2015. If more than one language is
listed, or if the language is not listed in Lehman's table, the field \textsf{language} is left unchanged.
%
\subsection{Location/Address}
Copac/BibTeX records use \textsf{address} for the place of publication and
\textsf{location} for library names. This choice causes problems of
BibTeX/Biblatex compatibility: \textsf{location} is used by Biblatex in
place of the traditional \textsf{address} field, and \textsf{library} is
used for library names. \textsf{Copac-clean} leaves \textsf{address}
unchanged: this gives no problems because BibTeX uses this field normally
and Biblatex interprets it as an alias for \textsf{location}. To avoid
conflicts, \textsf{location} is changed to \textsf{library}, that is
ignored (= not printed), but can be parsed, by BibTeX, and is standard in
Biblatex. See the discussion in
\url{http://tex.stackexchange.com/questions/57720/bibtex-handling-manuscripts}. 

\subsection{New fields}
The Copac/BibTeX format knows only the \textsf{title} fields, but for some
bibliographic styles (e.g. author-title styles, or the traditional ``long''
citations still common in the humanities), a \textsf{shorttitle} field is
necessary. This utility outputs a \textsf{shorttitle} identical to
\textsf{title}, because each user/journal/publisher may have preferences
difficult to standardise. For BibTeX (not Biblatex) bibliographic styles, a
\textsf{booktitle} field is necessary in the case of proceedings,
\emph{Festschriften}, edited books etc. For this reason, if and only if the
record type is \emph{proceedings} a \textsf{booktitle} field is
automatically added -- needless to say, it is identical to
\textsf{title}%
\footnote{These features may be possibly transformed to options:
		  \textsf{shorttitle} is useless for author-date styles, and
		  \textsf{booktitle} is useless for BibTeX users.}%
.

\subsection{Final result}
After running this utility, the example printed at page \pageref{exrecord}
is transformed as follows:
\footnotesize%
\begin{verbatim}
@proceedings{Giannantoni:1996,
		  editor = {Giannantoni, Gabriele and Gigante, Marcello},
		  title = {Epicureismo greco e romano: atti del congresso
		           internazionale, Napoli, 19-26 maggio 1995},
		  booktitle = {Epicureismo greco e romano: atti del congresso
		           internazionale, Napoli, 19-26 maggio 1995},
		  shorttitle = {Epicureismo greco e romano: atti del congresso
		           internazionale, Napoli, 19-26 maggio 1995},
		  series = {Elenchos ; 25},
		  series = {Elenchos (series) ; 25},
		  address = {[Napoli]},
		  publisher = {Bibliopolis},
		  year = {c1996},
		  size = {3 v. (1128 p.) ; 23 cm},
		  langid = {italian},
		  isbn = {ISBN: 8870883620},
		  annote = {Papers from an international congress
		            held in Naples, 19-26 May 1993},
		  annote = {Includes bibliographical references
		           (v. 3, p. [1005]-1056) and indexes},
		  annote = {Italian, English, French and German contributions},
		  keywords = {Epicurus -- Congresses},
		  keywords = {Epicurus -- Influence -- Congresses},
		  keywords = {Philosophy, Ancient -- Congresses},
		   library  = {King's College London ; University of London - ULRLS}}
		  \end{verbatim}
\normalsize%
%
\section{Installation}
\subsection{Dependencies}
The programme requires \textsf{xclip}, a modern \textsf{Snobol}
interpreter, and the \textsf{zenity} GUI tool.
\subsection{xclip}
\textsf{xclip} can be normally installed from the software manager provided
by Linux standard distributions. It is a tiny and efficient command line
utility that can read from clipboard or output to clipboard. The homepage
is \url{http://sourceforge.net/projects/xclip/}.
%
\subsection{zenity}
\textsf{Zenity} is a GTK+ lightweight tool -- standard in most Linux
distributions -- that outputs message windows, error windows and the like. See \url{https://help.gnome.org/users/zenity/stable/}.
%
\subsection{Snobol}
Snobol is a powerful language, with unparalleled string processing
abilities. It is a niche language, but it is very useful to linguists and
handy for text transformations as in the present case: if interested in
Snobol, refer to Phil Budne's page (\url{http://www.snobol4.org/}). I
strongly recommend to install the recent CSNOBOL4 release 2.0 (January 1,
2015) by Phil Budne.  Unfortunately, Snobol is not offered by standard
Linux distributions, but the installation is very easy (the installation
detects if you are on a 32 or 64 bit system):
\begin{enumerate}
		  \item download
					 \url{ftp://ftp.ultimate.com/snobol/snobol4-2.0.tar.gz}
		  \item \footnotesize\texttt{tar zxfv snobol4-2.0}\normalsize 
		  \item \footnotesize\texttt{cd snobol4-2.0}\normalsize
		  \item \footnotesize\texttt{configure}\normalsize
		  \item \footnotesize\texttt{make}\normalsize
		  \item as root (or sudo), run 	 
					 \footnotesize\texttt{make install}\normalsize
		  \item test if it's all right typing \footnotesize\texttt{snobol4
					 -v}\normalsize{} in a shell.
					 You should read a message containing the version number.
\end{enumerate}
%
\section{Installing Copac-clean}
Now copy (1) \textsf{copac-clean.sh} (2) \textsf{copac-clean.sno} (3) \textsf{copac-clean-lib.inc} in the same directory: I would recommend \textsf{/home/yourname/bin/copaclean}. This directory must be in the PATH of your system. Type \texttt{echo \$PATH} in a terminal to know the Path of your system. The script \textsf{copac-clean.sh} must be executable: if not, type \texttt{chmod +x copac-clean.sh}. If you do not have writing permissions on that particular folder as normal user, type \texttt{sudo chmod +x copac-clean.sh} and enter your password, or, on some systems, login as root and type the command.
%
\section{Usage}\label{sec:usage}
\begin{enumerate}
		  \item select \textsf{BibTeX} in the \textsf{Export} drop down menu
					 (at bottom of the page): see fig.~\ref{maltby01}.
		  \item select the whole record, and save it to the clipboard
					 (Ctrl-C is the standard shortcut): see fig.~\ref{maltby02}.
\end{enumerate}
%
\begin{figure}%[!htbp]
\centering{%
\includegraphics[angle=0,scale=.45]{maltby01}
\caption{Selecting BibTeX export from Copac}\label{maltby01}%
}%
\end{figure}
%
%
\begin{figure}%[!htbp]
\centering{%
\includegraphics[angle=0,scale=.45]{maltby02}
\caption{A BibTeX record from Copac}\label{maltby02}%
}%
\end{figure}
%
%
In Ubuntu systems, use \textsf{Alt-F2}: see fig. \ref{runprogram}. Better, copy the provided \textsf{copac-clean.desktop} file to your desktop: the programme should run without any further adaptation.

If you prefer, open a terminal and type
%
\begin{verbatim}
copac-clean.sh
\end{verbatim}
%
\emph{The Copac record must be in your clipboard}! To be sure of this, a clipboard utility as \textsf{glipper}, that controls your clipboard selections, can be useful. If the clipboard is empty or does not hold a copy of the Copac-BibTeX record, you'll get an error message (see fig. \ref{errormessage}.)

If everything goes fine, you'll get a message confirming that the record has been edited (see fig. \ref{okmessage}). 
%
\begin{figure}%[!htbp]
\centering{%
\includegraphics[angle=0,scale=.45]{runprogram}
\caption{Running Copac-clean}\label{runprogram}%
}%
\end{figure}
%
\begin{figure}%[!htbp]
\centering{%
\includegraphics[angle=0,scale=.45]{errormessage}
\caption{Error message: wrong clipboard contents}\label{errormessage}%
}%
\end{figure}
%
%
\begin{figure}%[!htbp]
\centering{%
\includegraphics[angle=0,scale=.45]{okmessage}
\caption{End of transformation}\label{okmessage}%
}%
\end{figure}
%

\subsection{Paste the new version}\label{sec:paste}
Now your clipboard is used by the transformed BibTeX record, not by the old
version (you can check it with \textsf{glipper} or similar utilities).
Paste the new, transformed record in your BibTeX file or in a
\textsf{Jabref} window%
\footnote{%
Documentation on Jabref: \url{http://jabref.sourceforge.net/}.%
}. 
If you use Jabref, click on the name of the database you want to use, and paste the clipboard contents with a simple \texttt{Ctrl-V} or through the \textsf{Modify -- Copy} menu entry.

\section{Bugs and TODO}
List of features that I would like to add:
\begin{enumerate}
\item A Windows version, if requested by users.
\item Choice among Spitbol and Snobol.
\item More flexibility, e.g. \textsf{shorttitle yes/no} and
		  \textsf{booktitle yes/no}.
\end{enumerate}

\section{Acknowledgements}
My warmest thanks to \textsc{Phil Budne} (\url{phil@ultimate.com}) for
making his excellent CSNOBOL available and for his generous help. Many
thanks to the community of Snobol users, and to \textsc{Rafal M. Sulejman}
(\url{http://rms.republika.pl/}) whose \textsf{vim} syntax files are a
daily blessing.
%
\section{History}
\begin{tabular}{l l p{8cm}}
10.09.2013	& version 0.1 & \\
15.09.2013	& version 0.2 & first usable\\
30.10.2013	& version 0.3 & some fields corrected; comments
edited\\
27.12.2013	& version 0.4 & changed author to editor in
proceedings\\
28.12.2013	& version 0.5 & general editing of functions\\
07.01.2014	& version 0.6 & improved check - using langid and
library\\
10.01.2014	& version 0.7 & improved license and documentation\\
28.08.2015	& version 0.8 & changed GUI from tcl/tk to zenity and improved
documentation accordingly; added desktop configuration file\\
\end{tabular}

\section{Author, copyright, license, disclaimer}
\sffamily%
COPAC-CLEAN. Automatic editing of Copac/BibTeX records.\\
    Version 0.8\\
    Copyright (C) 2015  Guido Milanese <guido.milanese@unicatt.it>

	 License: LaTeX Project Public License (LPPL 1.3c)

This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3 of this license or (at your option) any later version.

The latest version of this license is in 
\begin{quote}
		  \url{http://www.latex-project.org/lppl.txt}
\end{quote}
and version 1.3 or later is part of all distributions of LaTeX version 2005/12/01 or later.

This work has the LPPL maintenance status `maintained'.

The Current Maintainer of this work is Guido Milanese.

This work consists of the files copac-clean.desktop,  copac-clean.pdf,  copac-clean.sno, copac-clean-lib.inc,  copac-clean.sh,   copac-clean.tex
\end{document}