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