pdflatexpicscale (2aug16)

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

3 files changed, 311 insertions, 17 deletions

diff --git a/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.pdf b/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.pdf
index 1f8ab3029f0..82088d1f6b6 100644
--- a/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.pdf
+++ b/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.pdf
diff --git a/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.tex b/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.tex
new file mode 100644
index 00000000000..ad3a452f21c
--- /dev/null
+++ b/Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.tex
@@ -0,0 +1,286 @@
+\documentclass[10pt,a4paper]{article}
+\usepackage{hologo} % used for LuaTeX, PdfTeX and PdfLaTeX logos
+\usepackage{graphicx}
+\usepackage{url}
+\title{pdflatexpicscale}
+\author{Peter Willadt\footnote{willadt at t-online.de}}
+\date{2016-08-02}
+\begin{document}
+\maketitle
+
+\begin{abstract}
+  \noindent pdflatexpicscale is software that scales bitmap images to be
+  included into Pdf\LaTeX\ documents down to a size sufficient for printing.
+  This document describes installation and usage.
+\end{abstract}
+
+\tableofcontents
+
+\section{Introduction}
+
+Picture size matters. Digital cameras produce unnecessary large images, this
+leads to excessive download times and wasted processing power in the print
+driver, for example. Tuning images by hand is fine, but it costs lots of time
+and there may be situations where you need e.g. low-res pictures for the web
+and high-res pictures for print. When there are requirements that force the
+size of images in our document to change, the fun will probably be gone.
+
+Hopefully TUGboat will accept an article accompanying this description. 
+
+\section{Installation}
+
+\subsection{Prerequisites}
+
+You have to install ImageMagick and Perl. If you are using Linux, please use
+the tools of your distribution, if they are not already installed. As a
+windows user, you may probably use the official ImageMagick distribution at
+\url{http://www.imagemagick.org/script/download.php}. For Perl, you got more
+options. I have tested pdflatexpicscale with ActiveState ActivePerl, but other
+distributions should work too.
+
+You also need the following Perl modules:  \texttt{File::Basename}, 
+\texttt{File::Spec}, \texttt{File::Copy}, and \texttt{Getopt::Long}. There are
+several ways to get these modules, if you have not got them already:
+
+\begin{itemize}
+\item use your Linux distribution's software manager
+\item use the Perl CPAN module
+\item use ActiveState's \texttt{ppm} software, if you use ActivePerl.
+\end{itemize}
+
+Detailled description of these procedures is beyond the scope of this
+document. 
+
+There are no special requirements for the versions of the software to install,
+but it may be wise to use recent versions, as there have been security flaws
+with ImageMagick. 
+
+\subsection{Installation}
+
+If the prerequisites have been fulfilled (which is perhaps standard for a
+Linux computer), it is sufficient to move the file
+\texttt{pdflatexpicscale.pl} to a place that is included in your PATH and to
+make it executable. Of course, there are alternatives. You may perhaps
+prefer to type\\
+\texttt{perl /path/to/pdflatexpicscale.pl myarticle}\\
+instead.
+
+\section{Basic usage}
+
+\subsection{Preparing your \LaTeX\ file, Part~1}
+
+I will assume that you use the graphicx package to include images. The most
+important point is \emph{not} to give path names when you use
+\verb|\includegraphics|. You do not have to keep all graphics in the current
+directory, as the graphicx package comes with the
+\verb|\graphicspath| directive.
+
+So, if you have all images in the directory where your \LaTeX\ file resides,
+you are done with this. If not, you should undertake the following steps: 
+
+\begin{enumerate}
+\item List every path to images within the \verb|\graphicspath| directive.
+\item Remove the paths from the \verb|\includegraphics| commands.
+\end{enumerate}
+
+Here is an example: If your \LaTeX\ file looks like this:
+
+\begin{verbatim}
+Some text...
+\includegraphics[size=2in]{/home/fred/photo1} 
+Some other text...
+\includegraphics[size=1in]{/srv/www/htdocs/logo} 
+\end{verbatim}
+
+then you should edit it to the following:
+
+\begin{verbatim}
+\graphicspath{{/home/fred/}{/srv/www/htdocs/}}
+Some text...
+\includegraphics[size=2in]{photo1} 
+Some other text...
+\includegraphics[size=1in]{logo} 
+\end{verbatim}
+
+You hopefully do not have distinct pictures with the same name in the listed
+folders. With \verb|\graphicspath| you have to use double braces, even if you
+use only one directory. 
+
+\subsection{Preparing your \LaTeX\ file, Part~2}
+
+As size and resolution of images will change, you should specify the display
+size of your images by means that are independent of the image, e.g. by using 
+something like\\
+\verb|\includegraphics[width=.3\textwidth]{...}|\\
+or\\
+\verb|\includegraphics[width=2cm]{...}|  
+
+\subsection{A complete example}
+
+The workflow looks like this:
+
+\begin{itemize}
+\item Edit your file.
+\item Run Pdf\LaTeX\ on your file.
+\item Create a directory for your scaled pictures.
+\item Run pdflatexpicscale on your file.
+\item Change the \verb|\graphicspath| directive in your file to use the
+  downscaled images.
+\item Run Pdf\LaTeX\ on your file.
+\end{itemize}
+
+Let us assume that your \LaTeX\ document is called \texttt{myarticle.tex},
+that all images reside in the project directory and that you have done the
+preparation steps described above. Let us further assume that you want to
+produce a PDF file suitable for preview with 72~dpi image resolution.
+
+So you create a subdirectory called \texttt{previewpix} and run Pdf\LaTeX\
+like usual on \texttt{myarticle}. Then you issue\\
+\texttt{pdflatexpicscale --printdpi=72 --destdir=previewpix myarticle}
+
+If you are curious, you may insert \texttt{--verbose} anywhere before your
+project name (and before running it). Then you fire up your editor and add the
+following line near the beginning of your \LaTeX\ file:
+
+\verb|\graphicspath{{previewpix/}}|
+
+You may probably check the size of \texttt{myarticle.pdf}.  Then run Pdf\LaTeX\
+again on \texttt{myarticle}. I have told you to use double braces with
+\verb|\graphicspath|, haven't I?  If you still are curious, you can again
+check the size of \texttt{myarticle.pdf}.
+
+When it gets to preparing a print version, you create a directory for images
+with more detail, say \texttt{printpix}. You reset the  \verb|\graphicspath|,
+run Pdf\LaTeX, issue\\
+\texttt{pdflatexpicscale --printdpi=300 --destdir=printpix myarticle}\\
+and set \verb|\graphicspath{{printpix/}}| before the next Pdf\LaTeX\ run.
+
+\section{Advanced usage}
+
+
+\subsection{Excluding files from scaling}
+
+You will probably exclude files from scaling when you think that scaling will
+do damage. You may achieve this by several means. Before you ask. Enumerating
+files to exclude is not really cool, so this is not supported.
+
+\begin{enumerate}
+\item Use \verb|\includegraphics| for this files with full path names. This is
+  uncool, but can be done.
+\item Pack these files into a special source directory. Read the following
+  explanation. 
+\end{enumerate}
+
+It works like this: you create three directories for pictures:
+
+\begin{itemize}
+\item One for images to stay unscaled. Let's call it \texttt{hires}
+\item One for images to scale. Let's call it \texttt{images}
+\item One for downscaled images. Let's call it \texttt{printimg}
+\end{itemize}
+
+Then you use the feature of \verb|\graphicspath| to include several
+directories. Before the first \LaTeX\ run, you say\\
+\verb|\graphicspath{{hires/}{images/}}|
+and after pdflatexpicscale is through, you change it to\\
+\verb|\graphicspath{{hires/}{printimg/}}|
+
+\subsection{Gory details}
+
+pdflatexpicscale reads the log file, not the \LaTeX\ source. So you have to
+run Pdf\LaTeX\ at least once before something can happen.
+
+Pure black-and-white images will be treated different from other picture
+files: They get four times the resolution, as probably every pixel counts. 
+Images that are only a little larger than ideal will not get scaled, but you
+may change this from the command line.
+If an image will not be scaled, it will be just copied to the destination
+directory. 
+
+pdflatexpicscale looks only for the width of images, so if you intend do do
+anisotropic scaling you will not get best results. 
+
+Clipping will not work with pdflatexpicscale. The \emph{graphicx} package
+devises picture size from the picture file, then applies clipping to it and
+afterwards does scaling, rotation and so on. As pdflatexpicscale changes
+pictures (as well dimensions as nominal resolution), clipping results will
+change too, you will end up with a mess. The same thing happens when you do
+not give the figure dimensions in units relying only on document properties
+(like page width). 
+
+\subsection{Command line options}
+
+All command line options have to be prepended by two minus signs. If they take
+arguments, you should add an equal sign and the argument to your option. All
+command line options are optional, but you have to specify a project name.
+
+\paragraph{destdir} followed by \emph{a directory name relative to the current
+directory} specifies where the scaled pictures should go. The default is
+\texttt{printimg}. The directory has to exist, pdflatexpicscale will not
+create directories.
+
+\paragraph{printdpi} followed by the resolution in dpi lets you change the
+target resolution. Default is 300, for online use you may supply 96, e.g.
+
+\paragraph{srcdir} followed by \emph{the directory where your unscaled
+  pictures are} is normally not required, as pdflatexpicscale gets the path
+names from the log file it reads. You may set this option if you have already
+changed the \verb|\graphicspath| and are too lazy to change it again. The
+default is empty.
+
+\paragraph{printdpi} followed by a numer lets you change the range in which
+pictures remain unscaled because they are near the target resolution. Default
+is 20, that means 20~percent. If target resolution is 300~dpi, files up to
+320~dpi get accepted too. Change to 0 if you want no tolerance.
+
+\paragraph{verbose} entertains you by showing what the program is about to
+do. 
+
+\paragraph{version} shows the software version.
+
+Calling pdflatexpicscale without any options and without a project name will
+display a short usage text.
+
+\subsection{Printer testing}
+
+You can---and you should---actually print a file with images scaled to
+distinct resolutions and compare the results. If paper quality matters for you
+(inkjet user?), you should repeat this with different paper.
+
+If you belong to the once-privileged class of people who own a PostScript
+printer, you may copy the file testprinter.ps to your printer. For all other
+folks, this file is useless. Software like Ghostscript will convert the
+rasters to uniform colored areas. Anyway, here is what you should see:
+
+\begin{itemize}
+\item The uppermost part of the page will present squares filled with
+  lines. With my printer, 100~lpi is the best I can get.
+
+\item The middle part of the page shows squares with five levels of gray with
+  dotted raster. The result should be similiar.
+
+\item The bottom of the page is dedicated to the ends of the gray scale. Can
+  you distinguish 94\% gray from white? Or 6\% gray from black?
+
+\end{itemize}
+
+\section{License}
+
+pdflatexpicscale.pl and the accompanying files are subject to the current
+version of the \LaTeX\ project public license.
+
+\section{Bugs, Improvements, and Changes}
+
+Please submit bug reports to the package author (me). I will be glad to make
+the package better.
+
+\subsection{Changelog}
+
+\paragraph{2016-07-28} Upload of first public version to CTAN.
+
+\paragraph{2016-07-31} Reformatted \emph{Gory details} section and added
+information about anisotropic scaling and clipping
+
+\paragraph{2016-08-02} Fixed some typos. Corrected handling of lines wrapped
+in the log file. 
+\end{document}
diff --git a/Master/texmf-dist/scripts/pdflatexpicscale/pdflatexpicscale.pl b/Master/texmf-dist/scripts/pdflatexpicscale/pdflatexpicscale.pl
index 638f0bdd2a7..5e236e4f9b5 100755
--- a/Master/texmf-dist/scripts/pdflatexpicscale/pdflatexpicscale.pl
+++ b/Master/texmf-dist/scripts/pdflatexpicscale/pdflatexpicscale.pl
@@ -1,19 +1,20 @@
 #!/usr/bin/perl -w
 # Scale pictures to be included into a LaTeX generated PDF file.
-# version 0.1 written by peter willadt 
+# version 0.2 written by peter willadt 
 # contact willadt at t-online.de
 # this software is subject to the LaTeX project public license.
 # changes:
-# 2016-08-01 first public release
-
+# 2016-07-27 first public release
+# 2016-08-02 changed regex to prevent problem with long filenames
+# 2016-08-02 changed > to gt (shame on me)
 use strict;
 use File::Basename;
 use File::Spec;
 use File::Copy;
 use Getopt::Long;
 
-my $version = '0.1';
-my $versiondate = '2016-07-28';
+my $version = '0.2';
+my $versiondate = '2016-08-02';
 my $showversion;
 
 my $verbose;
@@ -72,7 +73,7 @@ sub handleImage
     $dstdirs[1] = $printfolderprefix;
     $dstfilename = File::Spec->catfile(@dstdirs, basename($filename));
     if($filename eq $dstfilename){
-	unless ($srcfolder > ' ') {
+	unless ($srcfolder gt ' ') {
 	    printInplaceError($filename);
 	    $skipped++;
 	    return;
@@ -159,25 +160,32 @@ sub readlog
     my $logfilename = shift;
     $logfilename .= '.log';
     my ($picname, $picext, $picwidth, $picheight);
-    my ($picextu, $needsize);
+    my ($picextu, $state, $buffer);
     open LOGFILE, "<$logfilename" or die "Cannot read $logfilename";
-    $needsize = 0;
+    $state = 0;
     while (<LOGFILE>){
-	if (/^Package pdftex\.def Info\: (\S*)\.(\w+) used /){
-	    $picname = $1;
-	    $picext = $2;
-	    ($picextu = $picext) =~ tr/a-z/A-Z/;
-	    if( defined $canhandle{$picextu}){
-		$needsize = 1;
-		next;
+	if (/^Package pdftex\.def\sInfo\:\s/){
+	    $buffer = $_;
+	    unless (/\sused/){
+		chomp $buffer;
+		$buffer .= <LOGFILE>;
+	    }
+	    if($buffer =~ /Info:\s(\S*)\.(\w+)\sused/){
+		$picname = $1;
+		$picext = $2;
+		($picextu = $picext) =~ tr/a-z/A-Z/;
+		if(defined $canhandle{$picextu}){
+		    $state = 1;
+		    next;
+		}
 	    }
 	}
-	next unless ($needsize == 1);
+	next unless ($state == 1);
 	next unless /Requested size: (\d+\.\d+)pt x (\d+\.\d+)pt/;
 	$picwidth  = $1;
 	$picheight = $2;
 	handleImage("$picname.$picext", $picwidth, $picheight);
-	$needsize = 0;
+	$state = 0;
     }
 }