diff options
Diffstat (limited to 'Master')
| -rw-r--r-- | Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.pdf | bin | 186254 -> 187176 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/support/pdflatexpicscale/pdflatexpicscale.tex | 286 | ||||
| -rwxr-xr-x | Master/texmf-dist/scripts/pdflatexpicscale/pdflatexpicscale.pl | 42 |
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 Binary files differindex 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; } } |