From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- support/copac-clean/copac-clean.tex | 339 ++++++++++++++++++++++++++++++++++++ 1 file changed, 339 insertions(+) create mode 100644 support/copac-clean/copac-clean.tex (limited to 'support/copac-clean/copac-clean.tex') 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 + + 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} + -- cgit v1.2.3