scanpages (15may14)

git-svn-id: svn://tug.org/texlive/trunk@34050 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 38 insertions, 31 deletions

diff --git a/Master/texmf-dist/doc/latex/scanpages/README b/Master/texmf-dist/doc/latex/scanpages/README
index a852ce319d0..8103279002a 100644
--- a/Master/texmf-dist/doc/latex/scanpages/README
+++ b/Master/texmf-dist/doc/latex/scanpages/README
@@ -16,8 +16,12 @@ LaTeX package scanpages
  #
  # This work consists of the files scanpages.sty, replicate.py and replicate.plist.
  
-Version: 1.02
-Changes in version 1.01
+Version: 1.03, 2014/05/01
+
+Changes in version 1.03
+Corrected a number of issues in scanpages.sty and its documentation so that the package now works as documented.
+
+Changes in version 1.02
 Corrected documentation and modified the scripts to handle text documents using carriage return for end-of-line.
 
 Changes in version 1.01
diff --git a/Master/texmf-dist/doc/latex/scanpages/scanpages-doc.pdf b/Master/texmf-dist/doc/latex/scanpages/scanpages-doc.pdf
index b6c8a4d806d..ec111b10e0e 100644
--- a/Master/texmf-dist/doc/latex/scanpages/scanpages-doc.pdf
+++ b/Master/texmf-dist/doc/latex/scanpages/scanpages-doc.pdf
diff --git a/Master/texmf-dist/doc/latex/scanpages/scanpages-doc.tex b/Master/texmf-dist/doc/latex/scanpages/scanpages-doc.tex
index 403ae840c71..709b7f7be22 100644
--- a/Master/texmf-dist/doc/latex/scanpages/scanpages-doc.tex
+++ b/Master/texmf-dist/doc/latex/scanpages/scanpages-doc.tex
@@ -24,12 +24,12 @@
 \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.)
+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, and extraneous marks will likely appear, so each page may 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;
+The $x$ and $y$ coordinates {\tt llx, lly} of the lower left corner of the image region (the part you want to  import) relative to the lower left corner of the scanned page;
 \item the width {\tt w} of the image region;
 \item the height {\tt h} of the image region. 
 \end{itemize}
@@ -50,20 +50,19 @@ The package creates then a destination box centered horizontally and vertically
 \scanpage[rot=-1,page=1,dx=20,dy=15]{scan-0}
 %\index{}
 %\put(450,250){Is this assertion correct?}
-\endpicture
-\newpage
+\endpicture\endgroup\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.
+{\tt page=1} selects the first page of the file {\tt scan-0.pdf}. This option may be omitted is 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.
+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|.
 \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.
@@ -85,8 +84,7 @@ Making more than a few entries by copy and paste, updating the indices, is quite
 %%Begin page NNN0
 %\scanpage[rot=0,dx=NNN2,dy=0,page=NNN0]{pic}
 %%\index{}
-%\endpicture
-%\newpage
+%\endpicture\endgroup\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=|
@@ -96,14 +94,12 @@ The fragment \verb|{NNN,0:1+1,1:2+-2,2:[-200+300],3:1+1(3)}| means that variable
 %Begin page 1
 \scanpage[rot=0,dx=-200,dy=0,page=1]{pic}
 %\index{}
-\endpicture
-\newpage
+\endpicture\endgroup\newpage
 
 %Begin page 2
 \scanpage[rot=0,dx=300,dy=0,page=2]{pic}
 %\index{}
-\endpicture
-\newpage
+\endpicture\endgroup\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.) 
  
@@ -112,15 +108,14 @@ The fragment \verb|{NNN,0:1+1,1:2+-2,2:[-200+300],3:1+1(3)}| means that variable
 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:
+Scanning software often places each scanned page in a separate file with names like {\tt scan-001.jpg}, {\tt scan-002.jpg}. In 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
+%\endpicture\endgroup\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}
@@ -129,10 +124,17 @@ Scanning software often places each scanned page in a separate file with names l
 %%Begin page NNN0
 %\scanpage[rot=0,dx=NNN1,dy=0]{NNN2-NNN3}
 %%\index{}
-%\endpicture
-%\newpage
+%\endpicture\endgroup\newpage
 \end{verbatim}
 \end{itemize}
+\section{Whiting out scan artifacts}
+Use a white rectangular box to overwrite scan artifacts. The simplest method may  be to use \verb|\rule|, like this:
+\begin{verbatim}
+\put(150,200){% lower left corner at (150,200)
+{\color{white}\rule{10pt}{5pt}}% solid white rect 10pt wide, 5pt high
+} 
+\end{verbatim}
+
 \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}
diff --git a/Master/texmf-dist/tex/latex/scanpages/scanpages.sty b/Master/texmf-dist/tex/latex/scanpages/scanpages.sty
index edda1901709..5d24e8625e0 100644
--- a/Master/texmf-dist/tex/latex/scanpages/scanpages.sty
+++ b/Master/texmf-dist/tex/latex/scanpages/scanpages.sty
@@ -5,16 +5,16 @@
 % Copyright (c) 2014 by Michael Sharpe, msharpe at ucsd dot edu;
 % This is free software, subject to the LATEX Project Public License.
 
-\def\fileversion{1.02}
-\def\filedate{2014/04/24}
+\def\fileversion{1.03}
+\def\filedate{2014/05/01}
 \ProvidesPackage{scanpages.sty}[\filedate\space v\fileversion]
 
-\message{`scanpages' v\fileversion, \filedate\space Macros to help create documents from scanned pages(msharpe)}
+\message{`scanpages' v\fileversion, \filedate\space Macros to help create documents from scanned pages (msharpe)}
 %
 \RequirePackage{ifpdf}
 \RequirePackage{pgffor}
 \RequirePackage{xcolor}
-\RequirePackage{keyval}
+\RequirePackage{xkeyval}
 \RequirePackage{fp-basic}
 \RequirePackage{graphicx}
 \RequirePackage{etoolbox}
@@ -43,6 +43,7 @@
   \x}
 \ProcessOptions*
 
+\newcount\scanp@pgcnt
 \setlength\unitlength{1bp}
 \long\def\putn(#1,#2)#3{%
   \@killglue%
@@ -69,6 +70,7 @@
 \newdimen\scanp@xlbp\newdimen\scanp@ylbp\newdimen\scanp@xrbp\newdimen\scanp@yrbp\newdimen\@dima
 %
 \def\initviewport#1#2#3#4#5{% srcscale,llx,lly,srcw,srch
+\scanp@pgcnt=\z@
 \FPdiv\scanp@invscale{1.0}{\scanp@srcscale}
 \scanp@setlength{\scanp@swdim}{\scanp@srcw}
 \scanp@setlength{\scanp@shdim}{\scanp@srch}
@@ -95,7 +97,7 @@
 \newdimen\scanp@dxdim\newdimen\scanp@dydim
 
 \def\scanpage{\@ifnextchar[\scanpage@i{\scanpage@i[]}}
-\def\scanpage@i[#1]#2{{\setkeys{scanpi}{#1}% 
+\def\scanpage@i[#1]#2{\advance\scanp@pgcnt\@ne\begingroup\setkeys{scanpi}{#1}% 
 \edef\scanp@head{\noexpand\vspace*{\scanp@yindent}\noexpand\noindent\noexpand\hspace*{\scanp@xindent}\noexpand\picture(\strip@pt\scanp@dwdimbp,\strip@pt\scanp@dhdimbp)}
 %\edef\@x{\strip@pt\scanp@dwdimbp}\edef\@y{\strip@pt\scanp@dhdimbp}
 %\vspace*{\the\scanp@yindent}\noindent\hspace*{\scanp@xindent}\picture(\@x,\@y)
@@ -112,11 +114,9 @@
 \if\scanp@srcscale\scanp@origscale\else\edef\scanp@cmd{scale=\scanp@srcscale,\scanp@cmd}\fi
 \ifdefvoid{\scanp@page}{}{\edef\scanp@cmd{page=\scanp@page,\scanp@cmd}}
 \edef\scanp@cmd{\noexpand\scanp@head\noexpand\put(0,0){\noexpand\includegraphics[\scanp@cmd}}
-%\show\scanp@cmd%
-\scanp@cmd
-\thegrid{\strip@pt\scanp@dwdimbp}{\strip@pt\scanp@dwdimbp}
-\endpicture
-\newpage}}
+\scanp@cmd % \begingroup, start \picture, \put pdf at (0,0)
+\thegrid{\strip@pt\scanp@dwdimbp}{\strip@pt\scanp@dhdimbp}
+}
 
 \ifscanp@nogrid\def\thegrid#1#2{}\else%
 \long\def\thegrid#1#2{\edef\scanp@gcmd{\noexpand\put(0,0){\noexpand\line(1,0){#1}}
@@ -135,9 +135,10 @@
   }
 \foreach\x in {-300,-250,...,550}{%
   \put(\x,-500){\color{red!50}\line(0,1){1500}}%
-  \put(\x,-15){\x}%
+  \put(\x,-15){\x}}
+\put(0,-30){\color{blue}Page \the\scanp@pgcnt}%
 \scanp@gcmd%
-}}
+}
 \fi % end \ifscanp@nogrid
 
 \endinput
\ No newline at end of file