source/texk/web2c/man/pdftosrc.man

   1 .TH pdftosrc 1 "16 June 2015" "Web2C @VERSION@"
   2 .SH NAME
   3 pdftosrc \- extract source file or stream from PDF file
   4 .SH SYNOPSIS
   5 .B pdftosrc
   6 .I PDF-file
   7 .RI [ stream-object-number ]
   8 .SH DESCRIPTION
   9 If only
  10 .I PDF-file
  11 is given as argument,
  12 .B pdftosrc
  13 extracts the embedded source file
  14 from the first found stream object
  15 with /Type /SourceFile within the
  16 .I PDF-file
  17 and writes it to a file with the name /SourceName
  18 as defined in that PDF stream object
  19 (see application example below).
  20
  21 If both
  22 .I PDF-file
  23 and
  24 .I stream-object-number
  25 are given as arguments, and
  26 .I stream-object-number
  27 is positive,
  28 .B pdftosrc
  29 extracts and uncompresses the PDF stream of the object
  30 given by its
  31 .I stream-object-number
  32 from the
  33 .I PDF-file
  34 and writes it to a file named
  35 .IR PDF-file . stream-object-number
  36 with the ending
  37 .B .pdf
  38 or
  39 .B .PDF
  40 stripped from the original
  41 .I PDF-file
  42 name.
  43
  44 A special case is related to XRef object streams that are part
  45 of the PDF standard from PDF-1.5 onward:
  46 If
  47 .I stream-object-number
  48 equals -1,
  49 then
  50 .B pdftosrc
  51 decompresses the XRef stream from the PDF file and writes it
  52 in human-readable PDF cross-reference table format to a file named
  53 .IB PDF-file .xref
  54 (these XRef streams can not be extracted just by giving their object number).
  55
  56 In any case
  57 an existing file with the output file name will be overwritten.
  58 .SH OPTIONS
  59 None.
  60 .SH FILES
  61 Just the executable
  62 .BR pdftosrc .
  63 .SH ENVIRONMENT
  64 None.
  65 .SH DIAGNOSTICS
  66 At success the exit code of
  67 .B pdftosrc
  68 is 0, else 1.
  69
  70 All messages go to stderr.
  71 At program invocation,
  72 .B pdftosrc
  73 issues the current version number of the program
  74 .BR xpdf ,
  75 on which
  76 .B pdftosrc
  77 is based:
  78
  79 .RS
  80 pdftosrc version 3.01
  81
  82 .RE
  83 When
  84 .B pdftosrc
  85 was successful with the output file writing,
  86 one of the following messages will be issued:
  87
  88 .RS
  89 Source file extracted to
  90 .I source-file-name
  91
  92 .RE
  93 or
  94
  95 .RS
  96 Stream object extracted to
  97 .IR PDF-file . stream-object-number
  98
  99 .RE
 100 or
 101
 102 .RS
 103 Cross-reference table extracted to
 104 .IR PDF-file .xref
 105
 106 .RE
 107
 108 .RE
 109 When the object given by the
 110 .I stream-object-number
 111 does not contain a stream,
 112 .B pdftosrc
 113 issues the following error message:
 114
 115 .RS
 116 Not a Stream object
 117
 118 .RE
 119 When the
 120 .I PDF-file
 121 can't be opened, the error message is:
 122
 123 .RS
 124 Error: Couldn't open file
 125 .RI ' PDF-file '.
 126
 127 .RE
 128 When
 129 .B pdftosrc
 130 encounters an invalid PDF file,
 131 the error message (several lines) is:
 132
 133 .RS
 134 Error: May not be a PDF file (continuing anyway)
 135 .RE
 136 .RS
 137 (more lines)
 138 .RE
 139 .RS
 140 Invalid PDF file
 141
 142 .RE
 143 There are also more error messages from
 144 .B pdftosrc
 145 for various kinds of broken PDF files.
 146 .SH NOTES
 147 An embedded source file will be written out unchanged,
 148 i. e. it will not be uncompressed in this process.
 149
 150 Only the stream of the object will be written,
 151 i. e. not the dictionary of that object.
 152
 153 Knowing which
 154 .I stream-object-number
 155 to query requires information about the PDF file
 156 that has to be gained elsewhere,
 157 e. g. by looking into the PDF file with an editor.
 158
 159 The stream extraction capabilities of
 160 .B pdftosrc
 161 (e. g. regarding understood PDF versions and filter types)
 162 follow the capabilities of the underlying
 163 .B xpdf
 164 program version.
 165
 166 Currently the generation number of the stream object
 167 is not supported.
 168 The default value 0 (zero) is taken.
 169
 170 The wording
 171 .I stream-object-number
 172 has nothing to do with the `object streams' introduced
 173 by the Adobe PDF Reference,
 174 5th edition, version 1.6.
 175 .SH EXAMPLES
 176 When using pdftex,
 177 a source file can be embedded into some
 178 .I PDF-file
 179 by using pdftex primitives,
 180 as illustrated by the following example:
 181
 182 \\immediate\\pdfobj
 183 .RE
 184     stream attr {/Type /SourceFile /SourceName (myfile.zip)}
 185 .RS
 186 .RE
 187     file{myfile.zip}
 188 .RS
 189 .RE
 190 \\pdfcatalog{/SourceObject \\the\\pdflastobj\\space 0 R}
 191
 192 Then this zip file can be extracted from the
 193 .I PDF-file
 194 by calling
 195 .B pdftosrc
 196 .IR PDF-file .
 197 .SH BUGS
 198 Not all embedded source files will be extracted,
 199 only the first found one.
 200
 201 Email bug reports to
 202 .B pdftex@tug.org.
 203 .SH SEE ALSO
 204 .BR xpdf (1),
 205 .BR pdfimages (1),
 206 .BR pdftotext (1),
 207 .BR pdftex (1),
 208 .SH AUTHORS
 209 .B pdftosrc
 210 written by Han The Thanh, using
 211 .B xpdf
 212 functionality from Derek Noonburg.
 213
 214 Man page written by Hartmut Henkel.
 215 .SH COPYRIGHT
 216 Copyright (c) 1996-2006 Han The Thanh, <thanh@pdftex.org>
 217
 218 This file is part of pdfTeX.
 219
 220 pdfTeX is free software; you can redistribute it and/or modify
 221 it under the terms of the GNU General Public License as published by
 222 the Free Software Foundation; either version 2 of the License, or
 223 (at your option) any later version.
 224
 225 pdfTeX is distributed in the hope that it will be useful,
 226 but WITHOUT ANY WARRANTY; without even the implied warranty of
 227 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 228 GNU General Public License for more details.
 229
 230 You should have received a copy of the GNU General Public License
 231 along with pdfTeX; if not, write to the Free Software
 232 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA