summaryrefslogtreecommitdiff
path: root/support/copac-clean/copac-clean.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/copac-clean/copac-clean.tex
Initial commit
Diffstat (limited to 'support/copac-clean/copac-clean.tex')
-rw-r--r--support/copac-clean/copac-clean.tex339
1 files changed, 339 insertions, 0 deletions
diff --git a/support/copac-clean/copac-clean.tex b/support/copac-clean/copac-clean.tex
new file mode 100644
index 0000000000..0a94952f51
--- /dev/null
+++ b/support/copac-clean/copac-clean.tex
@@ -0,0 +1,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}
+