% 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}

