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
|
\documentclass[11pt]{article}
\usepackage[margin=1in]{geometry}
\usepackage[parfill]{parskip}% Begin paragraphs with an empty line rather than an indent
\usepackage{graphicx}
\usepackage{amssymb}% do not use with mtpro2 except lite version
%SetFonts
% libertine+newtxmath
\usepackage[lining]{libertine}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage[scaled=.85]{beramono}
\usepackage{amsmath,amsthm}
\usepackage[libertine,bigdelims]{newtxmath}
\usepackage{url}
\useosf
\usepackage[supstfm=libertinesups,%
supscaled=1.2,%
raised=-.13em]{superiors}
%SetFonts
\title{The \textsf{Scanpages} Package}
\author{Michael Sharpe}
\date{\today} % Activate to display a given date or no date
\begin{document}
\maketitle
\section{Briefly}
This package is intended for production of documents based on scanned material in any format acceptable to \textsf{pdflatex} as a graphic inclusion---eg, {\tt pdf}, {\tt png}, {\tt jpg}. For me, the format has been useful when trying to archive pre-\TeX\ documents without converting them to \LaTeX\ source documents but inputting the scanned pages one by one and adding indexing, hyperlinks, a table of contents (You'll have to do this using \verb|\addcontentsline{toc}...|, and if using \textsf{hyperref}, you may need to add \verb|\phantomsection| immediately before \verb|\addcontentsline|), footnotes, marginal notes and the like. What makes scanned documents bothersome is the irregularities introduced by the scanning process. Pages are sometimes skewed and often offset horizontally and/or vertically from one another so each page will potentially need adjustments. The methods of this package are of two types. First, the package {\tt scanpages.sty} contains macros to make it more convenient to perform those adjustments and add adornments. Second, some kind of script is very useful for making the relevant part of the {\tt tex} source, if you are handling more than a few pages of scanned material. For this, there are two almost equivalent scripts included to automate this process as much as possible, one written in \textsf{python}, the other in \textsf{AppleScript.} (The letter may be installed in \TeX Shop's macro menu for completely self-contained usage.)
\section{The \LaTeX\ package}
Starting with a scanned document, you need to measure four dimensions governed by the region you wish to import, and decide on a magnification factor to apply. The region to import from the scan should ideally be a bit larger (10{\tt pt} is a good starting value) than the area typically containing all the data, and perhaps excluding original page numbers. The four critical dimensions are:
\begin{itemize}
\item
The $x$ and $y$ coordinates {\tt llx, lly} of the lower left corner of the image region relative to the lower left corner of the page;
\item the width {\tt w} of the image region;
\item the height {\tt h} of the image region.
\end{itemize}
The package is called using these items as options to the package.
\begin{verbatim}
\usepackage[scale=.9,llx=8cm,lly=12cm,w=3.5in,h=3.5in]{scanpages}
\end{verbatim}
It is not an error to omit one or more of these values, as default values will be substituted:
\begin{itemize}
\item
{\tt llx} and {\tt lly} default to {\tt 1in}.
\item {\tt scale} defaults to {\tt 1.0}.
\item {\tt w} defaults to {\tt 400pt}.
\item {\tt h} defaults to {\tt 600pt}.
\end{itemize}
The package creates then a destination box centered horizontally and vertically in the page and runs \verb|\includegraphics| with appropriate values whenever it sees entries like
\begin{verbatim}
\scanpage[rot=-1,page=1,dx=20,dy=15]{scan-0}
%\index{}
%\put(450,250){Is this assertion correct?}
\endpicture
\newpage
\end{verbatim}
which it interprets as follows:
\begin{itemize}
\item
{\tt rot} is an angle of rotation (degrees) in the mathematically positive sense (counter-clockwise) about the center. You may find it easier to enter {\tt tanrot=0.175}, the tangent of the rotation, as this is more easily estimated from the picture.
\item {\tt page=1} selects the first page of the file {\tt scan-0.pdf}. This option may be omitted if the file contains only one page.
\item {\tt dx} nudges the resulting picture to the right by {\tt 20bp}, and similarly for {\tt dy}. (Actually, {\tt dx} nudges the {\tt viewport} to the left by {\tt 20bp/scale}.) If no unit is provided, {\tt bp} is assumed.
\item Any material following the \verb|\scanpage| line and before \verb|\endpicture| can be used for index entries, table of contents entries, footnotes and the like. As the action is all taking place within a \LaTeX\ {\tt picture} environment, each visible item must be placed in an instruction of the form
\begin{verbatim}
\put(x,y){...}
\end{verbatim}
where {\tt x} and {\tt y} are the purely numeric coordinates with implied unit {\tt 1bp}, which matches that required for dimensions in \verb|\includegraphics|. For example, \verb|\put(10,20){Text and $x$}| makes an L-R box (no line breaks) from the content \verb|Text and $x$| with reference point at is left baseline and translates that reference point to {\tt (10,20)}, which is {\tt 10bp} to the right and {\tt 20bp} above the lower left corner of the picture. You may also use other \LaTeX\ constructs in place of an L-R box---a minipage, a parbox, a makebox or a graphic.
\end{itemize}
The page it produces contains, in addition to the scan material and other embellishments, a superimposed grid with unit {\tt 1bp} and a black box marking the edge of outline of the destination box. After all adjustments are complete, the grid may be suppressed by adding the option {\tt nogrid} to the package option list.
\subsection{Resetting the initial choices}
The options you chose when loading the package may be changed in the middle of a document. Just insert
\begin{verbatim}
\initviewport{<scale>,<llx>,<lly>,<w>,<h>}
\end{verbatim}
to change your initial choice of options. Eg,
\begin{verbatim}
\initviewport{.95,3cm,4cm,8cm,12cm}
\end{verbatim}
will in effect make {\tt scale=.95}, {\tt llx=3cm}, {\tt lly=4cm}, {\tt w=8cm} and {\tt h=12cm}.
\section{Making a source entry for each page}
Making more than a few entries by copy and paste, updating the indices, is quite boring, and I don't see how to manage this in \TeX, hence the need for the external scripts. The scripts operate on a file containing a small template that can generate what you need. I create a block of text like this:
\begin{verbatim}
%Repetitions=100
%Variables={NNN,0:1+1,1:2+-2,2:[-200+300],3:1+1(3)}
%%Begin page NNN0
%\scanpage[rot=0,dx=NNN2,dy=0,page=NNN0]{pic}
%%\index{}
%\endpicture
%\newpage
\end{verbatim}
The \verb|%Repetitions=|
line describes the maximum value of a counter starting at {\tt 1} that controls the iteration. The line \verb|%Variables=|
line is less obvious.
The fragment \verb|{NNN,0:1+1,1:2+-2,2:[-200+300],3:1+1(3)}| means that variables are named {\tt NNN0, NNN1, NNN2, NNN3}. Variable {\tt NNN0} is initially {\tt1}, increments by {\tt1} and so takes successive values {\tt 1,2,...,100}. Variable {\tt NNN1} is initially {\tt2} and increments by {\tt -2}, while variable {\tt NNN2} alternates between {\tt -200} for odd counter values and {\tt300} for even counter values. Variable {\tt NNN3} takes the same value as {\tt NNN0} but prints in a field of length {\tt 3}, padding as necessary on the left with {\tt0}'s so it substitutes successively {\tt 001,002,...,099,100}. (Note that commas, colons and plus signs are simply separators and have no arithmetic significance.) Running the script on this file will append 100 copies, the first two lines omitted, and with one \% stripped and variables replaced by their successive values. The first two resulting items appearing as
\begin{verbatim}
%Begin page 1
\scanpage[rot=0,dx=-200,dy=0,page=1]{pic}
%\index{}
\endpicture
\newpage
%Begin page 2
\scanpage[rot=0,dx=300,dy=0,page=2]{pic}
%\index{}
\endpicture
\newpage
\end{verbatim}
(The variable {\tt NNN1} was created with descriptor {\tt1:2+-2}, has initial value {\tt 2}, decreasing by {\tt 2} at each iteration, but was never used.)
Alternating variables can be useful with a scan taken from a two-sided document, where offsets may be quite different for odd and even pages. Note too that where variables that increment must be integer valued, alternating variables can be alphanumeric. For example, the descriptor {\tt2:[odd+even]} would work as expected.
Two other special forms are available.
\begin{itemize}
\item
Scanning software often places each scanned page in a separate file with names like {\tt scan-001.jpg}, {\tt scan-002.jpg}. To cover this case you need an integer variable padded to three places, which could be produced by the descriptor of the form {\tt 4:1+1(3)} and a pattern like:
\begin{verbatim}
%Repetitions=100
%Variables={NNN,0:1+1,1:2+-2,2:[-200+300],4:1+1(3)}
%%Begin page NNN0
%\scanpage[rot=0,dx=NNN2,dy=0]{scan-NNN4}
%%\index{}
%\endpicture
%\newpage
\end{verbatim}
\item If you are scanning two-sided material, you may end up with odd and even pages each saved in sequences of files like {\tt odd-0001.jpg}, {\tt odd-0002.jpg}, ... ,{\tt even-0001.jpg}, {\tt even-0002.jpg}, ... and in this case it is handy to use a descriptor that ``goes up by halves'' to give the sequence {\tt 0001, 0001, 0002, 0002,...}. The descriptor to use is like {\tt 3:2+1/2(4)}, which starts an internal counter at {\tt 2}, increments it by {\tt1} at each step, and prints half its value, truncated to an integer, and padded to length {\tt 4}. (If the {\tt(4)} had been omitted, there would have been no padding.) So the pattern to replicate would be like:
\begin{verbatim}
%Repetitions=100
%Variables={NNN,0:1+1,1:[20+40],2:[odd+even],3:2+1/2(4)}
%%Begin page NNN0
%\scanpage[rot=0,dx=NNN1,dy=0]{NNN2-NNN3}
%%\index{}
%\endpicture
%\newpage
\end{verbatim}
\end{itemize}
\section{Differences between the scripts}
The AppleScript is meant to work within TeXShop after installation in the TeXShop Macros Menu---see instructions below. It works on the selected part of the file, and its output is placed in the same file, which can be part of a larger document. The \textsf{python} script is meant to run from the command line on a file containing just the pattern text, and produces output in the same file, which can then be copied than into your working {\tt.tex} document. Eg, if you copied the script into a directory on your {\tt PATH} and made it executable
\begin{verbatim}
replicate.py myfile.txt
\end{verbatim}
would read input from and write output to {\tt myfile.txt}. (The script has been tested with \textsf{python} {\tt2.7.4} under MacOS 10.9.2. It should work without modification under Linux but may require some minor changes in Windows using a \textsf{python} from {\tt activestate.com}.)
The two scripts give the same output provided you use variable names that are identical in case to those the one in the \verb|%Variables=|
line. (In the examples above, this was always {\tt NNN}.) The \textsf{python} script is case sensitive, but the AppleScript is not---it will act on any variant like {\tt nnn0} or {\tt NnN1} as well.
\subsection{Installation in TeXShop's Macros Menu}
Select \TeX Shop's Macros Menu and choose the top item---\textsf{Open Macro Editor ... }. Then, from the same menu, choose the second item---\textsf{Add macros from file ...}---and navigate to {\tt replicate.plist} in this distribution. When you choose that file, the AppleScript will be installed under the name \textsf{Replicate} in the Macros Menu.
\end{document}
|
