diff --git a/cpdfmanual.pdf b/cpdfmanual.pdf index 09bd1f7..b9b0b68 100644 Binary files a/cpdfmanual.pdf and b/cpdfmanual.pdf differ diff --git a/cpdfmanual.tex b/cpdfmanual.tex index fc22891..82febbd 100644 --- a/cpdfmanual.tex +++ b/cpdfmanual.tex @@ -437,7 +437,7 @@ PDF 1.5 introduced a new mechanism for storing objects to save space: object str \noindent Files written with object streams will be set to PDF 1.5 or higher, unless \texttt{-keep-version} is used (see above). \section{Malformed Files} - +\label{fast} There are many malformed PDF files in existence, including many produced by otherwise-reputable applications. \cpdf\ attempts to correct these problems silently. @@ -479,7 +479,7 @@ The \verb!-fast! option may be used with: \begin{framed} \small\noindent Chapter \ref{pages}\\ \noindent\small\verb!-rotate-contents -upright -vflip -hflip!\\ -\small\verb!-shift -scale -scale-to-fit -scale-contents!\\ +\small\verb!-shift -scale-page -scale-to-fit -scale-contents!\\ \small\verb!-show-boxes -hard-box -trim-marks!\\ \noindent Chapter \ref{stamps}\\ @@ -542,6 +542,7 @@ escaped (i.e. written \verb!\\!). \section{Text Encodings} \index{text encodings} +\label{textencodings} Some \texttt{cpdf} commands write text to standard output, or read text from the command line or configuration files. These are: @@ -564,7 +565,7 @@ the command line or configuration files. These are: \noindent Add \verb!-utf8! to use Unicode UTF8, \verb!-stripped! to convert to 7 bit ASCII by dropping any high characters, or \verb!-raw! to perform no -processing. The default is \verb!-stripped!. +processing. The default unless specified in the documentation for an individual operation is \verb!-stripped!. \section{Font Embedding} Use the \texttt{-no-embed-font} to avoid embedding the Standard 14 Font metrics when adding text with \texttt{-add-text}. @@ -710,23 +711,19 @@ The encryption parameters described in Chapter \ref{encryption} may be added to \pagestyle{fancy} \label{pages} \begin{framed} - \small\noindent\verb!cpdf -scale-page " " in.pdf [] -o out.pdf! + \small\noindent\verb!cpdf -scale-page " " [-fast] in.pdf [] -o out.pdf! \vspace{1.5mm} - \small\noindent\verb!cpdf -scale-to-fit " " [-scale-to-fit-scale ]!\\ + \small\noindent\verb!cpdf -scale-to-fit " " [-fast]!\\ + \noindent\verb! [-scale-to-fit-scale ]!\\ \noindent\verb! in.pdf [] -o out.pdf! - %\vspace{1.5mm} - %\small\noindent\verb!cpdf -scale-to-fit-best " " in.pdf [] -o out.pdf! - % - %\vspace{1.5mm} - %\small\noindent\verb!cpdf -scale-to-fit-minus " " in.pdf [] -o out.pdf! - \vspace{1.5mm} - \small\noindent\verb!cpdf -scale-contents [] [] in.pdf [] -o out.pdf! + \small\noindent\verb!cpdf -scale-contents [] [] [-fast]!\\ + \noindent\verb! in.pdf [] -o out.pdf! \vspace{1.5mm} - \small\noindent\verb!cpdf -shift " " in.pdf [] -o out.pdf! + \small\noindent\verb!cpdf -shift " " [-fast] in.pdf [] -o out.pdf! \vspace{1.5mm} \small\noindent\verb!cpdf -rotate in.pdf [] -o out.pdf! @@ -735,16 +732,16 @@ The encryption parameters described in Chapter \ref{encryption} may be added to \small\noindent\verb!cpdf -rotateby in.pdf [] -o out.pdf! \vspace{1.5mm} - \small\noindent\verb!cpdf -rotate-contents in.pdf [] -o out.pdf! + \small\noindent\verb!cpdf -rotate-contents [-fast] in.pdf [] -o out.pdf! \vspace{1.5mm} - \small\noindent\verb!cpdf -upright in.pdf [] -o out.pdf! + \small\noindent\verb!cpdf -upright [-fast] in.pdf [] -o out.pdf! \vspace{1.5mm} - \small\noindent\verb!cpdf -hflip in.pdf [] -o out.pdf! + \small\noindent\verb!cpdf -hflip [-fast] in.pdf [] -o out.pdf! \vspace{1.5mm} - \small\noindent\verb!cpdf -vflip in.pdf [] -o out.pdf! + \small\noindent\verb!cpdf -vflip [-fast] in.pdf [] -o out.pdf! \vspace{1.5mm} \small\noindent\verb!cpdf -mediabox " " in.pdf [] -o out.pdf! @@ -757,20 +754,20 @@ The encryption parameters described in Chapter \ref{encryption} may be added to \small\noindent\verb!cpdf -remove-cropbox in.pdf [] -o out.pdf! \vspace{1.5mm} - (Also \texttt{bleed}, \texttt{art}, and \texttt{trim} versions of these two commands, e.g \texttt{-artbox}, \texttt{-remove-trimbox}) + (Also \texttt{bleed}, \texttt{art}, and \texttt{trim} versions of these two commands, for example \texttt{-artbox}, \texttt{-remove-trimbox}) \vspace{1.5mm} \small\noindent\verb!cpdf -frombox -tobox [-mediabox-if-missing]! \\ \noindent\verb! in.pdf [] -o out.pdf! \vspace{1.5mm} - \small\noindent\verb!cpdf -hard-box in.pdf [] -o out.pdf! + \small\noindent\verb!cpdf -hard-box [-fast] in.pdf [] -o out.pdf! \vspace{1.5mm} - \small\noindent\verb!cpdf -show-boxes in.pdf [] -o out.pdf! + \small\noindent\verb!cpdf -show-boxes [-fast] in.pdf [] -o out.pdf! \vspace{1.5mm} - \small\noindent\verb!cpdf -trim-marks in.pdf [] -o out.pdf! + \small\noindent\verb!cpdf -trim-marks [-fast] in.pdf [] -o out.pdf! \end{framed} @@ -1193,7 +1190,7 @@ the file is loaded. For example, upon executing By default, \cpdf\ converts unicode to ASCII text, dropping characters outside the ASCII range. To prevent this, and return unicode UTF8 output, add the \texttt{-utf8} option to the command. To prevent any processing, use the -\texttt{-raw} option. +\texttt{-raw} option. See Section \ref{textencodings} for more information. \section{Remove Bookmarks} \label{removebookmarks} @@ -1311,15 +1308,15 @@ the file using a different page range each time. \begin{framed} \noindent\small\verb!cpdf -stamp-on source.pdf!\\ \noindent\small\verb! [-scale-stamp-to-fit] [] [-relative-to-cropbox] !\\ - \noindent\small\verb! in.pdf [] -o out.pdf! + \noindent\small\verb! in.pdf [] [-fast] -o out.pdf! \vspace{1.5mm} \noindent\small\verb!cpdf -stamp-under source.pdf!\\ \noindent\small\verb! [-scale-stamp-to-fit] [] [-relative-to-cropbox]!\\ - \noindent\small\verb! in.pdf [] -o out.pdf! + \noindent\small\verb! in.pdf [] [-fast] -o out.pdf! \vspace{1.5mm} - \noindent\small\verb!cpdf -combine-pages over.pdf under.pdf -o out.pdf! + \noindent\small\verb!cpdf -combine-pages over.pdf under.pdf [-fast] -o out.pdf! \vspace{1.5mm} \noindent\small\begin{verbatim}cpdf ([-add-text | -add-rectangle ]) @@ -1338,12 +1335,17 @@ the file using a different page range each time. [-opacity ] [-midline] [-topline] + [-fast] in.pdf [] -o out.pdf\end{verbatim} \noindent See also positioning commands below. \vspace{1.5mm} \noindent\small\verb!cpdf -remove-text in.pdf [] -o out.pdf! + + \vspace{1.5mm} + \noindent\small NB: See discussion of \texttt{-fast} in Section \ref{fast}. \end{framed} + \section{Add a Watermark or Logo} The \texttt{-stamp-on} and \texttt{-stamp-under} operations stamp the first page of a source PDF onto or under each page in the given range of the input @@ -1648,10 +1650,10 @@ This can be used to blank out or highlight part of the document. The following p \chapter{Multipage Facilities}\pagestyle{fancy}\label{multipage} \begin{framed} - \small\noindent\verb!cpdf -twoup-stack in.pdf -o out.pdf! + \small\noindent\verb!cpdf -twoup-stack [-fast] in.pdf -o out.pdf! \vspace{1.5mm} - \small\noindent\verb!cpdf -twoup in.pdf -o out.pdf! + \small\noindent\verb!cpdf -twoup [-fast] in.pdf -o out.pdf! \vspace{1.5mm} \small\noindent\verb!cpdf -pad-before in.pdf [] [-pad-with pad.pdf] -o out.pdf! @@ -1674,6 +1676,8 @@ This can be used to blank out or highlight part of the document. The following p page, rotating them 90 degrees to do so. The new mediabox is thus larger. The \texttt{-twoup} operation does the same, but scales the new sides down so that the media box is unchanged. +NB: See discussion of \texttt{-fast} in section \ref{fast}. + \section{Inserting Blank Pages} \index{blank pages!inserting} Sometimes, for instance to get a printing arrangement right, it's useful to @@ -1731,7 +1735,7 @@ The \texttt{-pad-multiple-before n} operation adds the padding pages at the begi \section{List Annotations} \index{annotations!listing} The \texttt{-list-annotations} operation prints the textual content of any -annotations on the selected pages to standard output. Each annotation is preceded by the page number and followed by a newline. +annotations on the selected pages to standard output. Each annotation is preceded by the page number and followed by a newline. See Section \ref{textencodings} for more information on text encodings in the output of this operation. \begin{framed} \small\verb!cpdf -list-annotations in.pdf > annots.txt! @@ -1781,7 +1785,7 @@ given page range. \small\noindent\verb!cpdf -pages in.pdf! \vspace{1.5mm} - \small\noindent\verb!cpdf -set-title in.pdf -o out.pdf!\\ + \small\noindent\verb!cpdf -set-title <title of document> [-raw] in.pdf -o out.pdf!\\ (Also \texttt{-set-author} etc. See Section \ref{setdocinfo}.) \vspace{1.5mm} @@ -1877,7 +1881,7 @@ XMP dc:title: AI6\end{verbatim}}\end{framed} \noindent The details of the format for creation and modification dates can be found in Appendix~\ref{dates}. -By default, cpdf strips to ASCII, discarding character codes in excess of 127. In order to preserve the original unicode, add the \texttt{-utf8} option. To disable all postprocessing of the string, add \texttt{-raw}. +By default, cpdf strips to ASCII, discarding character codes in excess of 127. In order to preserve the original unicode, add the \texttt{-utf8} option. To disable all postprocessing of the string, add \texttt{-raw}. See Section \ref{textencodings} for more information. \vspace{4mm} The \texttt{-page-info} operation prints the page label, media box and other boxes @@ -2142,6 +2146,13 @@ The \texttt{-dump-attachments} operation, when given a PDF file and a directory \small\verb!cpdf -dump-attached-files in.pdf -o /home/fred/attachments! \end{framed} +Unless the \texttt{-raw} option is given, the filenames are stripped of dubious special characters before writing. It is converted from unicode to 7 bit ASCII, and the following characters are removed, in addition to any character with ASCII code less than 32: + \begin{framed} + \centering + \verb! / ? < > \ : * | " ^ + =! + \end{framed} + + \chapter{Working with Images} \begin{framed} \noindent\small\verb!cpdf -image-resolution <minimum resolution> in.pdf [<range>]!