summaryrefslogtreecommitdiff
path: root/support/pdfcrop/README
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/pdfcrop/README
Initial commit
Diffstat (limited to 'support/pdfcrop/README')
-rw-r--r--support/pdfcrop/README259
1 files changed, 259 insertions, 0 deletions
diff --git a/support/pdfcrop/README b/support/pdfcrop/README
new file mode 100644
index 0000000000..4ea8503d79
--- /dev/null
+++ b/support/pdfcrop/README
@@ -0,0 +1,259 @@
+README for pdfcrop 2012/11/02 v1.38
+
+TABLE OF CONTENTS
+=================
+A. Description
+B. Copyright, Disclaimer, License
+C. Files
+D. Requirements
+E. Installation
+F. User Interface
+G. Restricted Mode
+H. Author
+I. Acknowledgement
+J. Questions, Suggested Improvements
+K. Known Problems
+L. History
+M. ToDo
+
+A. DESCRIPTION
+==============
+PDFCROP takes a PDF file as input, calculates the BoundingBox
+for each page by the help of ghostscript and generates a output
+PDF file with removed margins.
+
+B. COPYRIGHT, DISCLAIMER, LICENSE
+=================================
+Copyright (C) 2002, 2004, 2005, 2008-2012 Heiko Oberdiek.
+
+This program may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.2
+of this license or (at your option) any later version.
+The latest version of this license is in
+ http://www.latex-project.org/lppl.txt
+and version 1.2 or later is part of all distributions of LaTeX
+version 1999/12/01 or later.
+
+C. FILES
+========
+The project `pdfcrop' consists of two files:
+pdfcrop.pl: This perl script is the main program. The extension
+ `.pl' may be omitted.
+README: Documentation, the file you are reading.
+
+Following temporary files are produced if `pdfcrop' is invoked:
+tmp-pdfcrop-*.tex: input file for pdfTeX
+tmp-pdfcrop-*.log: log file of pdfTeX run
+tmp-pdfcrop-*.pdf: result after pdfTeX run
+
+D. REQUIREMENTS
+===============
+* Perl5 (version 5 of the perl interpreter)
+* Ghostscript (>= 8.0 if PDF file contains rotated pages)
+* pdfTeX, version >= 1.0 (because of page selecting and \pdfximage syntax)
+ or XeTeX or LuaTeX.
+
+E. INSTALLATION
+===============
+
+1. Perl script `pdfcrop.pl':
+
+ TDS 1.1 location (TDS means "texmf" tree, see CTAN:tds/tds.pdf):
+ * TDS:scripts/pdfcrop/pdfcrop.pl
+ * and a directory that is part of PATH contains a wrapper script
+ or link with name "pdfcrop".
+
+ Unix
+ * It is allowed to rename `pdfcrop.pl' to `pdfcrop':
+ mv pdfcrop.pl pdfcrop
+ * Ensure that the execute permission is set:
+ chmod +x pdfcrop
+ * Move the file to a directory where the shell can find it
+ (environment variable PATH, e.g. /usr/local/bin/).
+
+ Dos/Windows
+ * See requirements. I do not expect that the perl script
+ run under DOS.
+
+2. Restricted program version `rpdfcrop'
+
+ Generate links or install `pdfcrop.pl' again under the
+ name `rpdfcrop'.
+
+ Prefer `rpdfcrop' if you want to add pdfcrop to the
+ programs that may be executed in TeX's restricted
+ shell escape mode. (This feature is added in TeX Live 2009.)
+ For TeX Live (since 2009) see entry for `shell_escape_commands'
+ in the configuration file `texmf.cnf'.
+
+3. Documentation `README':
+
+ Copy it to an appropriate place, for example
+ `/usr/local/share/doc/pdfcrop/README'.
+ It is allowed to rename it to `pdfcrop.txt'.
+
+ TDS location:
+ somewhere below texmf/doc/... (?)
+ Examples:
+ TDS:doc/support/pdfcrop/README
+ TDS:doc/scripts/pdfcrop/README
+ TDS:doc/scripts/pdfcrop.txt
+ TeXLive 2008 and 2009 put it in
+ TDS:doc/support/pdfcrop/README
+
+F. USER INTERFACE
+=================
+* ToDo: User manual
+* Online help:
+ pdfcrop --help
+* Ghostscript's calculation of the bounding box is faster,
+ if --resolution 72 is used instead of ghostscript's implicite
+ default setting of 4000 DPI (hint from Ionut Georgescu).
+ Of course the calculation with higher resolution settings are
+ more accurate.
+
+G. RESTRICTED MODE
+==================
+Restricted mode is enabled if:
+* option `--restricted' is used,
+* the program is called under the name `rpdfcrop'
+* or the called program name contains `restricted'.
+This mode sets restrictions for the following options:
+* --pdftexcmd: if used, the value must be empty or `pdftex'.
+* --xetexcmd: if used, the value must be empty or `xetex'.
+* --luatexcmd: if used, the value must be empty or `luatex'.
+* --gscmd: if used, the value must
+ * be empty or
+ * be one of the standard names (gs, gswin32c, mgs, gs386 gsos2) or
+ * consists of `gs', followed by a version number and an
+ optional `c' (Ghostscript's convention for `console version').
+
+H. AUTHOR
+=========
+Heiko Oberdiek
+Email: heiko.oberdiek at googlemail.com
+
+I. ACKNOWLEDGEMENT
+==================
+Anthony Williams
+Scott Pakin <pakin at uiuc.edu>
+Ionut Georgescu
+Yves J\"ager
+R (Chandra) Chandrasekhar
+Christian Stapfer
+David Menestrina
+Karl Berry
+
+J. QUESTIONS, SUGGESTED IMPROVEMENTS
+====================================
+If you have questions, problems with `pdfcrop', error reports,
+if you have improvements or want to have additional features,
+please send them to the author.
+
+My environment for developing and testing:
+* linux, SuSE 9.0
+* perl v5.8.1
+* pdfTeX 3.141592-1.40.x
+* Ghostscript 8.x
+
+K. KNOWN PROBLEMS
+=================
+* pdfcrop relies on Ghostscript for the calculation of the
+ Bounding Box. If Ghostscript returns wrong values or
+ cannot process the pdf file, it sometimes helps to try
+ another version of Ghostscript.
+* XeTeX (and pdfTeX < 1.10a) does not allow the setting of the
+ PDF version in a direct way. Thus pdfcrop fixes the PDF version
+ afterwards in the PDF header. Therefore XeTeX warnings as
+ ** WARNING ** Version of PDF file (1.6) is newer
+ than version limit specification.
+ can be safely ignored.
+
+L. HISTORY
+==========
+2002/10/30 v1.0: First release
+2002/10/30 v1.1: Option --hires added.
+2002/11/04 v1.2: "nul" instead of "/dev/null" for windows.
+2002/11/23 v1.3: Use of File::Spec module's "devnull" call.
+2002/11/29 v1.4: Option --papersize added.
+2004/06/24 v1.5: Clear map file entries so that pdfTeX
+ does not touch the fonts.
+2004/06/26 v1.6: Use mgs.exe instead of gswin32c.exe for MIKTEX.
+2005/03/11 v1.7: Support of spaces in file names
+ (open("-|") is used for ghostscript call).
+2008/01/09 v1.8: Fix for moving the temporary file to the output
+ file across file system boundaries.
+2008/04/05 v1.9: Options --resolution and --bbox added.
+2008/07/16 v1.10: Support for XeTeX added with new options
+ --pdftex, --xetex, --xetexcmds.
+2008/07/22 v1.11: Workaround for open("-|").
+2008/07/23 v1.12: Workarounds for the workaround (error detection, ...).
+2008/07/24 v1.13: open("-|")/workaround removed.
+ Input files with unsafe file names are linked/copied
+ to temporary file with safe file name.
+2008/09/12 v1.14: Error detection for invalid Bounding Boxes.
+2009/07/14 v1.15: Fix for negative coordinates in Bounding Boxes
+ (David Menestrina).
+2009/07/17 v1.16: Security fixes:
+ * -dSAFER added for Ghostscript,
+ * -no-shell-escape added for pdfTeX/XeTeX.
+2009/07/17 v1.17: Security fixes:
+ * Backticks and whitespace are forbidden
+ for options --(gs|pdftex|xetex)cmd.
+ * Validation of options --papersize and --resolution.
+2009/07/18 v1.18: * Restricted mode added.
+ * Option --version added.
+2009/09/24 v1.19: * Ghostscript detection rewritten.
+ * Cygwin: `gs' is preferred to `gswin32c'.
+2009/10/06 v1.20: * File name sanitizing in .tex file.
+2009/12/21 v1.21: * Option --ini added for iniTeX mode.
+ * Option --luatex and --luatexcmd added for LuaTeX.
+2009/12/29 v1.22: * Syntax description for option --bbox fixed
+ (Lukas Prochazka).
+2010/01/09 v1.23: * Options --bbox-odd and --bbox-even added.
+2010/08/16 v1.24: * Workaround added for buggy ghostscript ports
+ that print the BoundingBox data twice.
+2010/08/26 v1.25: * Fix for the case that the PDF file contains
+ an entry /CropBox different to /MediaBox.
+ * \pageinclude implemented for XeTeX.
+ * XeTeX: --clip does not die, but this option
+ is ignored, because XeTeX always clip.
+2010/08/26 v1.26: * XeTeX's \XeTeXpdffile expects keyword
+ `media', not `mediabox'.
+ * New option --pdfversion.
+ Default is `auto' that means the PDF version
+ is inherited from the input file. Before
+ pdfcrop has used the TeX engine's default.
+ * Option --luatex fixed (extra empty page at end).
+2010/09/03 v1.27: * Workaround of v1.24 fixed.
+2010/09/06 v1.28: * The Windows registry is searched if Ghostscript
+ is not found via PATH.
+ * Windows only: support of spaces in command
+ names in unrestricted mode.
+2010/09/06 v1.29: * Find the latest Ghostscript version in registry.
+2010/09/15 v1.30: * Warning of pdfTeX because of \pdfobjcompresslevel
+ avoided when reducing \pdfminorversion.
+ * Fix for TeX syntax characters in input file names.
+2010/09/17 v1.31: * Passing the input file name via hex string to TeX.
+ * Again input file names restricted for Ghostscript
+ command line, switch then to symbol link/copy
+ method.
+2011/08/10 v1.32: * Detection for gswin64c.exe added.
+2012/02/01 v1.33: * Input file can be `-' (standard input).
+2012/04/18 v1.34: * Format of option --version changed
+ from naked version number to a line with
+ program name, date and version.
+2012/10/15 v1.35: * Additional debug infos added for Perl version.
+2012/10/16 v1.36: * More error codes added.
+2012/10/16 v1.37: * Extended error messages if available.
+ * Fix for broken v1.36.
+2012/11/02 v1.38: * Fix for unsufficient cleanup, if function `cleanup' is
+ prematurely called in `eval' for `symlink' checking.
+
+
+M. TODO
+=======
+* Description of user interface.
+* Documentation in other formats, eg. man or info pages.
+* Improved error checking.
+* Units support for option --margins.