hexapdf 0.1.0 → 0.2.0

data/lib/hexapdf/rectangle.rb

@@ -87,13 +87,20 @@ module HexaPDF
     # upper-right corner.
     def after_data_change
       super
-      unless value.kind_of?(Array) && value.size == 4
+      unless value.kind_of?(Array) && value.size == 4 && value.all? {|i| i.kind_of?(Numeric)}
         raise ArgumentError, "A PDF rectangle structure must contain an array of four numbers"
       end
       value[0], value[2] = value[2], value[0] if value[0] > value[2]
       value[1], value[3] = value[3], value[1] if value[1] > value[3]
     end
 
+    def perform_validation #:nodoc:
+      super
+      unless value.kind_of?(Array) && value.size == 4 && value.all? {|i| i.kind_of?(Numeric)}
+        yield("A PDF rectangle structure must contain an array of four numbers", false)
+      end
+    end
+
   end
 
 end

data/lib/hexapdf/revisions.rb

@@ -169,8 +169,10 @@ module HexaPDF
       @revisions[range].reverse.each_cons(2) do |rev, prev_rev|
         prev_rev.trailer.value.replace(rev.trailer.value)
         rev.each do |obj|
-          prev_rev.delete(obj.oid, mark_as_free: false)
-          prev_rev.add(obj)
+          if obj.data != prev_rev.object(obj)&.data
+            prev_rev.delete(obj.oid, mark_as_free: false)
+            prev_rev.add(obj)
+          end
         end
       end
       _first, *other = *@revisions[range]

data/lib/hexapdf/serializer.rb

@@ -88,7 +88,7 @@ module HexaPDF
       @dispatcher = Hash.new do |h, klass|
         method = nil
         klass.ancestors.each do |ancestor_klass|
-          method = "serialize_#{ancestor_klass.name.downcase.gsub(/::/, '_')}"
+          method = "serialize_#{ancestor_klass.name.to_s.downcase.gsub(/::/, '_')}"
           (h[klass] = method; break) if respond_to?(method, true)
         end
         method
@@ -188,7 +188,7 @@ module HexaPDF
     end
 
     BYTE_IS_DELIMITER = {40 => true, 47 => true, 60 => true, 91 => true, # :nodoc:
-                         41 => true, 62 => true, 93 => true}
+                         41 => true, 62 => true, 93 => true}.freeze
 
     # Serializes an Array object.
     #
@@ -222,7 +222,7 @@ module HexaPDF
       str << ">>".freeze
     end
 
-    STRING_ESCAPE_MAP = {"(" => "\\(", ")" => "\\)", "\\" => "\\\\", "\r" => "\\r"} # :nodoc:
+    STRING_ESCAPE_MAP = {"(" => "\\(", ")" => "\\)", "\\" => "\\\\", "\r" => "\\r"}.freeze # :nodoc:
 
     # Serializes a String object.
     #

data/lib/hexapdf/stream.rb

@@ -71,7 +71,7 @@ module HexaPDF
     #
     # * A Proc object (that is converted to a Fiber when needed) in which case the +offset+ and
     #   value is ignored. The Proc object can also be passed by using a block.
-    def initialize(source =  nil, offset: nil, length: nil, filter: nil, decode_parms: nil, &block)
+    def initialize(source = nil, offset: nil, length: nil, filter: nil, decode_parms: nil, &block)
       if source.nil? && !block_given?
         raise ArgumentError, "Either a source object or a block must be given"
       end
@@ -257,7 +257,8 @@ module HexaPDF
     # :nodoc:
     # A mapping from short name to long name for filters.
     FILTER_MAP = {AHx: :ASCIIHexDecode, A85: :ASCII85Decode, LZW: :LZWDecode,
-                  Fl: :FlateDecode, RL: :RunLengthDecode, CCF: :CCITTFaxDecode, DCT: :DCTDecode}
+                  Fl: :FlateDecode, RL: :RunLengthDecode, CCF: :CCITTFaxDecode,
+                  DCT: :DCTDecode}.freeze
 
     # Validates the /Filter entry so that it contains only long-name filter names.
     def perform_validation

data/lib/hexapdf/task/dereference.rb

@@ -70,7 +70,7 @@ module HexaPDF
           dereference(@doc.trailer)
           @result = []
           @doc.each(current: false) do |obj|
-            if !@seen.key?(obj) && obj.type != :ObjStm && obj.type != :XRef
+            if !@seen.key?(obj.data) && obj.type != :ObjStm && obj.type != :XRef
               @result << obj
             elsif obj.kind_of?(HexaPDF::Stream) && (val = obj.value[:Length]) &&
                 val.kind_of?(HexaPDF::Object) && val.indirect?
@@ -81,8 +81,8 @@ module HexaPDF
       end
 
       def dereference(object) #:nodoc:
-        return object if @seen.key?(object)
-        @seen[object] = true
+        return object if @seen.key?(object.data)
+        @seen[object.data] = true
         recurse(object.value)
         object
       end
@@ -96,8 +96,7 @@ module HexaPDF
         when HexaPDF::Reference
           dereference(@doc.object(val))
         when HexaPDF::Object
-          (val.indirect? ? dereference(val) : recurse(val.value))
-          val
+          dereference(val)
         else
           val
         end

data/lib/hexapdf/task/optimize.rb

@@ -95,8 +95,11 @@ module HexaPDF
 
         oid = 1
         doc.revisions[0].each do |obj|
-          next if obj.null? || unused.include?(obj) || (obj.type == :ObjStm) ||
-            (obj.type == :XRef && xref_streams != :preserve)
+          if obj.null? || unused.include?(obj) || (obj.type == :ObjStm) ||
+              (obj.type == :XRef && xref_streams != :preserve)
+            obj.data.value = nil
+            next
+          end
 
           delete_fields_with_defaults(obj)
           obj.oid = oid
@@ -200,7 +203,7 @@ module HexaPDF
       # Compresses the contents of all pages by parsing and then serializing again. The HexaPDF
       # serializer is already optimized for small output size so nothing else needs to be done.
       def self.compress_pages(doc)
-        doc.pages.each_page do |page|
+        doc.pages.each do |page|
           processor = SerializationProcessor.new
           HexaPDF::Content::Parser.parse(page.contents, processor)
           page.contents = processor.result

data/lib/hexapdf/tokenizer.rb

@@ -56,12 +56,12 @@ module HexaPDF
     # Characters defined as whitespace.
     #
     # See: PDF1.7 s7.2.2
-    WHITESPACE = "\0\t\n\f\r "
+    WHITESPACE = "\0\t\n\f\r ".freeze
 
     # Characters defined as delimiters.
     #
     # See: PDF1.7 s7.2.2
-    DELIMITER = "()<>{}/[]%"
+    DELIMITER = "()<>{}/[]%".freeze
 
     WHITESPACE_MULTI_RE = /[#{WHITESPACE}]+/ # :nodoc:
 
@@ -267,7 +267,7 @@ module HexaPDF
       '(' => "(",
       ')' => ")",
       '\\' => "\\",
-    }
+    }.freeze
 
     # Parses the literal string at the current position.
     #

data/lib/hexapdf/type/file_specification.rb

@@ -107,8 +107,8 @@ module HexaPDF
       # /Unix, /Mac and /DOS).
       def path
         tmp = (self[:UF] || self[:F] || self[:Unix] || self[:Mac] || self[:DOS] || '').dup
-        tmp.gsub!(/\\\//, "/")  # PDF1.7 s7.11.2.1 but / in filename is interpreted as separator!
-        tmp.gsub!(/\\/, "/") # always use slashes instead of back-slashes!
+        tmp.gsub!(/\\\//, "/") # PDF1.7 s7.11.2.1 but / in filename is interpreted as separator!
+        tmp.tr!("\\", "/") # always use slashes instead of back-slashes!
         tmp
       end
 

data/lib/hexapdf/type/form.rb

@@ -32,6 +32,7 @@
 #++
 
 require 'hexapdf/stream'
+require 'hexapdf/content'
 
 module HexaPDF
   module Type
@@ -97,6 +98,24 @@ module HexaPDF
         Content::Parser.parse(contents, processor)
       end
 
+      # Returns the canvas for the form XObject.
+      #
+      # The canvas object is cached once it is created so that its graphics state is correctly
+      # retained without the need for parsing its contents.
+      #
+      # *Note* that a canvas can only be retrieved for initially empty form XObjects!
+      def canvas
+        unless defined?(@canvas)
+          unless stream.empty?
+            raise HexaPDF::Error, "Cannot create a canvas for a form XObjects with contents"
+          end
+          @canvas = Content::Canvas.new(self)
+          self.stream = @canvas.stream_data
+          set_filter(:FlateDecode)
+        end
+        @canvas
+      end
+
     end
 
   end

data/lib/hexapdf/type/page.rb

@@ -97,13 +97,13 @@ module HexaPDF
         Ledger: [0, 0, 792, 1224].freeze,
         Tabloid: [0, 0, 1224, 792].freeze,
         Executive: [0, 0, 522, 756].freeze,
-      }
+      }.freeze
 
       # The inheritable fields.
-      INHERITABLE_FIELDS = [:Resources, :MediaBox, :CropBox, :Rotate]
+      INHERITABLE_FIELDS = [:Resources, :MediaBox, :CropBox, :Rotate].freeze
 
       # The required inheritable fields.
-      REQUIRED_INHERITABLE_FIELDS = [:Resources, :MediaBox]
+      REQUIRED_INHERITABLE_FIELDS = [:Resources, :MediaBox].freeze
 
 
       define_field :Type,                 type: Symbol, required: true, default: :Page
@@ -150,9 +150,9 @@ module HexaPDF
       # See: Dictionary#[]
       def [](name)
         if value[name].nil? && INHERITABLE_FIELDS.include?(name)
-          node = self[:Parent] || (raise InvalidPDFObjectError, "Page has no parent node")
-          node = node[:Parent] while node.value[name].nil? && node.key?(:Parent)
-          node[name] || super
+          node = self
+          node = node[:Parent] while node.value[name].nil? && node[:Parent]
+          node == self || node.value[name].nil? ? super : node[name]
         else
           super
         end
@@ -248,6 +248,21 @@ module HexaPDF
         Content::Parser.parse(contents, processor)
       end
 
+      # Returns the index of the page in the page tree.
+      def index
+        idx = 0
+        node = self
+        while (parent_node = node[:Parent])
+          parent_node[:Kids].each do |kid|
+            kid = document.deref(kid)
+            break if kid.data == node.data
+            idx += (kid.type == :Page ? 1 : kid[:Count])
+          end
+          node = parent_node
+        end
+        idx
+      end
+
       # Returns the requested type of canvas for the page.
       #
       # The canvas object is cached once it is created so that its graphics state is correctly

data/lib/hexapdf/type/page_tree_node.rb

@@ -151,44 +151,37 @@ module HexaPDF
         insert_page(-1, page)
       end
 
-      # Deletes the page at the position specified by the zero-based index and returns it. If an
-      # invalid index is specified, +nil+ is returned.
+      # :call-seq:
+      #   pages.delete_page(page)        -> page or nil
+      #   pages.delete_page(index)       -> page or nil
       #
-      # Negative indices count backwards from the end, i.e. -1 is the last page.
+      # Deletes the given page or the page at the position specified by the zero-based index from
+      # the page tree and returns the deleted page object. If the page was not deleted, +nil+ is
+      # returned.
       #
-      # Must be called on the root of the page tree, otherwise the /Count entries are not
-      # correctly updated!
-      def delete_page(index)
-        index = self[:Count] + index if index < 0
-        return nil if index < 0 || index >= self[:Count]
+      # Note that the page is *not* deleted from the document itself, only from the page tree! This
+      # also means that the /Parent entry of the page is set to +nil+ if deleted.
+      #
+      # Negative indices count backwards from the end, i.e. -1 is the last page.
+      def delete_page(page)
+        page = self.page(page) if page.kind_of?(Integer)
+        return nil unless page && page[:Parent]
 
-        page = nil
-        self[:Count] -= 1
-        self[:Kids].each_with_index do |kid, kid_index|
-          kid = document.deref(kid)
-          if kid.type == :Page && index == 0
-            page = self[:Kids].delete_at(kid_index)
-            document.delete(page)
-            break
-          elsif kid.type == :Page
-            index -= 1
-          elsif index < kid[:Count]
-            page = kid.delete_page(index)
-            if kid[:Count] == 0
-              self[:Kids].delete_at(kid_index)
-              document.delete(kid)
-            elsif kid[:Count] == 1
-              self[:Kids][kid_index] = kid[:Kids][0]
-              kid[:Kids][0][:Parent] = self
-              document.delete(kid)
-            end
-            break
-          else
-            index -= kid[:Count]
-          end
-        end
+        parent = page[:Parent]
+        index = parent[:Kids].index {|kid| document.deref(kid).data == page.data}
 
-        page
+        if index
+          ancestors = [parent]
+          ancestors << parent while (parent = parent[:Parent])
+          return nil unless ancestors.include?(self)
+
+          page[:Parent][:Kids].delete_at(index)
+          page.delete(:Parent)
+          ancestors.each {|node| node[:Count] -= 1 }
+          page
+        else
+          nil
+        end
       end
 
       # :call-seq:

data/lib/hexapdf/utils/bit_stream.rb

@@ -84,7 +84,7 @@ module HexaPDF
 
       private
 
-      LENGTH_TO_TYPE = {4 => 'N', 2 => 'n', 1 => 'C'} # :nodoc:
+      LENGTH_TO_TYPE = {4 => 'N', 2 => 'n', 1 => 'C'}.freeze # :nodoc:
       FOUR_TO_INFINITY = 4..Float::INFINITY # :nodoc:
 
       # Fills the bit cache so that at least 16bit are available (if possible).

data/lib/hexapdf/utils/pdf_doc_encoding.rb

@@ -81,7 +81,7 @@ module HexaPDF
                          \u00e0 \u00e1 \u00e2 \u00e3 \u00e4 \u00e5 \u00e6 \u00e7
                          \u00e8 \u00e9 \u00ea \u00eb \u00ec \u00ed \u00ee \u00ef
                          \u00f0 \u00f1 \u00f2 \u00f3 \u00f4 \u00f5 \u00f6 \u00f7
-                         \u00f8 \u00f9 \u00fa \u00fb \u00fc \u00fd \u00fe \u00ff]
+                         \u00f8 \u00f9 \u00fa \u00fb \u00fc \u00fd \u00fe \u00ff].freeze
 
       # Converts the given string to UTF-8, assuming it contains bytes in PDFDocEncoding.
       def self.convert_to_utf8(str)

data/lib/hexapdf/version.rb

@@ -34,6 +34,6 @@
 module HexaPDF
 
   # The version of HexaPDF.
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'.freeze
 
 end

data/man/man1/hexapdf.1

@@ -1,249 +1,321 @@
-.\" generated with Ronn/v0.7.3
-.\" http://github.com/rtomayko/ronn/tree/0.7.3
-.
-.TH "HEXAPDF" "1" "October 2016" "" ""
-.
-.SH "NAME"
+.\" generated by kramdown
+.TH "HEXAPDF" "1" "November 2016"
+.SH NAME
 hexapdf \- A Versatile PDF Manipulation Application
-.
 .SH "SYNOPSIS"
-\fBhexapdf\fR [\fBOPTIONS\fR] \fBcommand\fR [\fBCOMMAND OPTIONS\fR]\.\.\.
-.
+\fBhexapdf\fP [\fBOPTIONS\fP] \fBcommand\fP [\fBCOMMAND OPTIONS\fP]\.\.\.
 .SH "DESCRIPTION"
-hexapdf is an application for PDF manipulation\. It is part of the hexapdf \fIhttp://hexapdf\.gettalong\.org\fR library which also allows PDF creation, among other things\.
-.
+hexapdf is an application for PDF manipulation\. It is part of the 
+.UR http://hexapdf\.gettalong\.org
+hexapdf
+.UE
+library which also allows PDF creation, among other things\.
 .P
 Using the hexapdf application the following tasks can be performed with PDF files:
-.
-.IP "\(bu" 4
-Extracting embedded files (see the \fBextract\fR command)
-.
-.IP "\(bu" 4
-Showing general information of a PDF file (see the \fBinfo\fR command)
-.
-.IP "\(bu" 4
-Inspecting the internal structure of a PDF file (see the \fBinspect\fR command)
-.
-.IP "\(bu" 4
-Modifying an existing PDF file (see the \fBmodify\fR command)
-.
-.IP "" 0
-.
-.P
-The application contains a built\-in \fBhelp\fR command that can be used to provide a quick reminder of a command\'s purpose and its options\.
-.
+.sp
+.PD 0
+.IP \(bu 4
+Extracting embedded files (see the \fBextract\fP command)
+.IP \(bu 4
+Showing general information of a PDF file (see the \fBinfo\fP command)
+.IP \(bu 4
+Inspecting the internal structure of a PDF file (see the \fBinspect\fP command)
+.IP \(bu 4
+Modifying an existing PDF file (see the \fBmodify\fP command)
+.PD
+.P
+The application contains a built\-in \fBhelp\fP command that can be used to provide a quick reminder of a command\[u2019]s purpose and its options\.
 .SH "OPTIONS"
 The following options can only be used when no command is specified:
-.
 .TP
-\fB\-v\fR, \fB\-\-version\fR
+\fB\-v\fP, \fB\-\-version\fP
 Show the version of the hexapdf application and exit\.
-.
 .P
 These options are available on every command (except if they are overridden):
-.
 .TP
-\fB\-h\fR, \fB\-\-help\fR
+\fB\-h\fP, \fB\-\-help\fP
 Show the help for the application if no command was specified, or the command help otherwise\.
-.
 .SH "COMMANDS"
-hexapdf uses a command\-style interface\. This means that it provides different functionalities depending on the used command and each command can have its own options\.
-.
+hexapdf uses a command\-style interface\. This means that it provides different functionalities depending on the used command, and each command can have its own options\.
 .P
-There is no need to write the full command name for hexapdf to understand it, the only requirement is that is must be unambiguous\. So using \fBe\fR for the \fBextract\fR command is sufficient\.
-.
+There is no need to write the full command name for hexapdf to understand it, the only requirement is that is must be unambiguous\. So using \fBe\fP for the \fBextract\fP command is sufficient\.
 .SS "extract"
-Synopsis: \fBextract\fR [\fBOPTIONS\fR] \fIFILE\fR
-.
+Synopsis: \fBextract\fP [\fBOPTIONS\fP] \fIFILE\fP
 .P
-This command extracts embedded files from the PDF \fIFILE\fR\. If the \fB\-\-indices\fR option is not specified, the names and indices of the embedded files are just listed\.
-.
+This command extracts embedded files from the PDF \fIFILE\fP\&\. If the \fB\-\-indices\fP option is not specified, the names and indices of the embedded files are just listed\.
 .TP
-\fB\-i\fR, \fB\-\-indices\fR \fIA,B,C,\.\.\.\fR
-The indices of the embedded files that should be extract\. The value \fI0\fR can be used to extract all embedded files\.
-.
+\fB\-i\fP \fIA,B,C,\.\.\.\fP, \fB\-\-indices\fP \fIA,B,C,\.\.\.\fP
+The indices of the embedded files that should be extract\. The value \fI0\fP can be used to extract all embedded files\.
 .TP
-\fB\-s\fR, \fB\-\-[no\-]search\fR
-Search the whole PDF file instead of the standard locations, i\.e\. files attached to the document as a whole or to an individual page\. Defaults to \fIfalse\fR\.
-.
+\fB\-s\fP, \fB\-\-[no\-]search\fP
+Search the whole PDF file instead of the standard locations, that is files attached to the document as a whole or to an individual page\. Defaults to \fIfalse\fP\&\.
 .TP
-\fB\-p\fR, \fB\-\-password\fR \fIPASSWORD\fR
-The password to decrypt the PDF \fIFILE\fR\. Use \fB\-\fR for \fIPASSWORD\fR for reading it from standard input\.
-.
+\fB\-p\fP \fIPASSWORD\fP, \fB\-\-password\fP \fIPASSWORD\fP
+The password to decrypt the PDF \fIFILE\fP\&\. Use \fB\-\fP for \fIPASSWORD\fP for reading it from standard input\.
 .SS "help"
-Synopsis: \fBhelp\fR \fICOMMAND\fR\.\.\.
-.
+Synopsis: \fBhelp\fP [\fICOMMAND\fP\.\.\.]
 .P
 This command prints the application help if no arguments are given\. If one or more command names are given as arguments, these arguments are interpreted as a list of commands with sub\-commands and the help for the innermost command is shown\.
-.
 .SS "info"
-Synopsis: \fBinfo\fR [\fBOPTIONS\fR] \fIFILE\fR
-.
+Synopsis: \fBinfo\fP [\fBOPTIONS\fP] \fIFILE\fP
 .P
-This command reads the \fIFILE\fR file and shows general information about it, like author information, PDF version used, encryption information and so on\.
-.
+This command reads the \fIFILE\fP and shows general information about it, like author information, PDF version used, encryption information and so on\.
 .TP
-\fB\-p\fR, \fB\-\-password\fR \fIPASSWORD\fR
-The password to decrypt the PDF \fIFILE\fR\. Use \fB\-\fR for \fIPASSWORD\fR for reading it from standard input\.
-.
+\fB\-p\fP \fIPASSWORD\fP, \fB\-\-password\fP \fIPASSWORD\fP
+The password to decrypt the PDF \fIFILE\fP\&\. Use \fB\-\fP for \fIPASSWORD\fP for reading it from standard input\.
 .SS "inspect"
-Synopsis: \fBinspect\fR [\fBOPTIONS\fR] \fIFILE\fR
-.
+Synopsis: \fBinspect\fP [\fBOPTIONS\fP] \fIFILE\fP
 .P
 This command is useful when one needs to inspect the internal object structure or a stream of a PDF file\.
-.
 .P
-If no option is given, the main PDF object, the catalog, is shown\. Otherwise the various, mutually exclusive display options define what is shown\. If multiple such options are specified only the last one is respected\. Note that PDF objects are always shown in the PDF syntax\.
-.
+If no option is given, the main PDF object, the catalog, is shown\. Otherwise the various, mutually exclusive display options define what is shown\. If multiple such options are specified only the last one is respected\. Note that PDF objects are always shown in the native PDF syntax\.
 .TP
-\fB\-t\fR, \fB\-\-trailer\fR
+\fB\-t\fP, \fB\-\-trailer\fP
 Show the trailer dictionary\.
-.
 .TP
-\fB\-c\fR, \fB\-\-page\-count\fR
+\fB\-c\fP, \fB\-\-page\-count\fP
 Print the number of pages\.
-.
 .TP
-\fB\-\-pages\fR [\fIPAGES\fR]
-Show the pages with their object and generation numbers and their associated content streams\. If a range is specified, only those pages are listed\. See the \fBPAGES SPECIFICATION\fR below for details on the allowed format of \fIPAGES\fR\.
-.
+\fB\-\-pages\fP [\fIPAGES\fP]
+Show the pages with their object and generation numbers and their associated content streams\. If a range is specified, only those pages are listed\. See the \fBPAGES SPECIFICATION\fP below for details on the allowed format of \fIPAGES\fP\&\.
 .TP
-\fB\-o\fR, \fB\-\-object\fR \fIOID\fR[,\fIGEN\fR]
+\fB\-o\fP \fIOID\fP[,\fIGEN\fP], \fB\-\-object\fP \fIOID\fP[,\fIGEN\fP]
 Show the object with the given object and generation numbers\. The generation number defaults to 0 if not given\.
-.
 .TP
-\fB\-s\fR, \fB\-\-stream\fR \fIOID\fR[,\fIGEN\fR]
-Show the filtered stream data (add \fB\-\-raw\fR to get the raw stream data) of the object with the given object and generation numbers\. The generation number defaults to 0 if not given\.
-.
+\fB\-s\fP \fIOID\fP[,\fIGEN\fP], \fB\-\-stream\fP \fIOID\fP[,\fIGEN\fP]
+Show the filtered stream data (add \fB\-\-raw\fP to get the raw stream data) of the object with the given object and generation numbers\. The generation number defaults to 0 if not given\.
 .TP
-\fB\-\-raw\fR
-Modifies \fB\-\-stream\fR to show the raw stream data instead of the filtered one\.
-.
+\fB\-\-raw\fP
+Modifies \fB\-\-stream\fP to show the raw stream data instead of the filtered one\.
 .TP
-\fB\-p\fR, \fB\-\-password\fR \fIPASSWORD\fR
-The password to decrypt the PDF \fIFILE\fR\. Use \fB\-\fR for \fIPASSWORD\fR for reading it from standard input\.
-.
+\fB\-p\fP \fIPASSWORD\fP, \fB\-\-password\fP \fIPASSWORD\fP
+The password to decrypt the PDF \fIFILE\fP\&\. Use \fB\-\fP for \fIPASSWORD\fP for reading it from standard input\.
 .SS "modify"
-Synopsis: \fBmodify\fR [\fBOPTIONS\fR] \fIINPUT_FILE\fR \fIOUTPUT_FILE\fR
-.
+Synopsis: \fBmodify\fP [\fBOPTIONS\fP] { \fB\-\-f\fP \fIINPUT\fP | \fB\-\-empty\fP } \fIOUTPUT\fP
+.P
+This command modifies a PDF file\. It can be used to select pages that should appear in the output file and to add pages from other PDF files (i\.e\. merging PDF files)\. The output file can be encrypted/decrypted and optimized in various ways\.
+.P
+The first input file is the primary file which gets modified, so meta data like file information, outlines, etc\. are taken from it\. Alternatively, it is possible to start with an empty PDF file by using \fB\-\-empty\fP\&\. The order of the options specifying the input files is important as the pages are added in that order\. Note that the \fB\-\-password\fP and \fB\-\-pages\fP options always apply to the last preceeding input file\.
+.P
+An input file can be specified multiple times, using a different \fB\-\-pages\fP option each time\. The \fB\-\-password\fP option, if needed, only needs to be used the first time\.
 .P
-This command modifies a PDF file\. It can be used to encrypt/decrypt a file, to optimize it and remove unused entries and to generate or delete object and cross\-reference streams\.
-.
+Input file related options:
 .TP
-\fB\-p\fR, \fB\-\-password\fR \fIPASSWORD\fR
-The password to decrypt the PDF \fIINPUT_FILE\fR\. Use \fB\-\fR for \fIPASSWORD\fR for reading it from standard input\.
-.
+\fB\-f\fP \fIFILE\fP, \fB\-\-file\fP \fIFILE\fP
+An input file\. At least one input file or \fB\-\-empty\fP needs be used\.
 .TP
-\fB\-\-pages\fR \fIPAGES\fR
-The pages (optionally rotated) that should be included in the \fIOUTPUT_FILE\fR\. See the \fBPAGES SPECIFICATION\fR below for details on the allowed format of \fIPAGES\fR\. Default: \fI1\-e\fR (i\.e\. all pages with no additional rotation applied)\.
-.
+\fB\-p\fP \fIPASSWORD\fP, \fB\-\-password\fP \fIPASSWORD\fP
+The password to decrypt the last input file specified with \fB\-\-file\fP\&\. Use \fB\-\fP for \fIPASSWORD\fP for reading it from standard input\.
+.TP
+\fB\-i\fP \fIPAGES\fP, \fB\-\-pages\fP \fIPAGES\fP
+The pages (optionally rotated) from the last input file specified with the \fB\-\-file\fP option that should be included in the \fIOUTPUT\fP\&\. See the \fBPAGES SPECIFICATION\fP below for details on the allowed format of \fIPAGES\fP\&\. Default: \fI1\-e\fP (i\.e\. all pages with no additional rotation applied)\.
+.TP
+\fB\-e\fP, \fB\-\-empty\fP
+Use an empty file as primary file\. This will lead to an output file that just contains the included pages of the input file and no other data from the input files\.
+.TP
+\fB\-\-interleave\fP
+Interleave the pages from the input files: Takes the first specified page from the first input file, then the first specified page from the second input file, and so on\. After that the same with the second, third, \.\.\. specified pages\. If fewer pages were specified for an input file, the input file is just skipped for the rest of the rounds\.
+.P
+Output file related options:
 .TP
-\fB\-\-embed\fR \fIFILE\fR
-Embed the given file into the \fIOUTPUT_FILE\fR using built\-in features of PDF\. This option can be used multiple times to embed more than one file\.
-.
+\fB\-\-embed\fP \fIFILE\fP
+Embed the given file into the \fIOUTPUT\fP using built\-in features of PDF\. This option can be used multiple times to embed more than one file\.
 .TP
-\fB\-\-[no\-]compact\fR
-Delete unnecessary PDF objects\. This includes merging the base revision and all incremental updates into a single revision\. Default: \fIyes\fR\.
-.
+\fB\-\-[no\-]compact\fP
+Delete unnecessary PDF objects\. This includes merging the base revision and all incremental updates into a single revision\. Default: \fIyes\fP\&\.
 .TP
-\fB\-\-object\-streams MODE\fR
-Defines how object streams should be treated: \fIgenerate\fR will remove all exisiting object streams and generate new ones, \fIdelete\fR will only remove existing object streams and \fIpreserve\fR will do nothing\. Default: \fIpreserve\fR\.
-.
+\fB\-\-object\-streams\fP \fIMODE\fP
+Defines how object streams should be treated: \fIgenerate\fP will remove all exisiting object streams and generate new ones, \fIdelete\fP will only remove existing object streams and \fIpreserve\fP will do nothing\. Default: \fIpreserve\fP\&\.
 .TP
-\fB\-\-xref\-streams MODE\fR
-Defines how cross\-reference streams should be treated: \fIgenerate\fR will add them, \fIdelete\fR will remove them and \fIpreserve\fR will do nothing\. Default: \fIpreserve\fR\.
-.
+\fB\-\-xref\-streams\fP \fIMODE\fP
+Defines how cross\-reference streams should be treated: \fIgenerate\fP will add them, \fIdelete\fP will remove them and \fIpreserve\fP will do nothing\. Default: \fIpreserve\fP\&\.
 .TP
-\fB\-\-streams MODE\fR
-Defines how streams should be treated: \fIcompress\fR will compress them when possible, \fIuncompress\fR will uncompress them when possible and \fIpreserve\fR will do nothing to them\. Default: \fIpreserve\fR\.
-.
+\fB\-\-streams\fP \fIMODE\fP
+Defines how streams should be treated: \fIcompress\fP will compress them when possible, \fIuncompress\fP will uncompress them when possible and \fIpreserve\fP will do nothing to them\. Default: \fIpreserve\fP\&\.
+.TP
+\fB\-\-[no\-]compress\-pages\fP
+Recompress page content streams\. This is a very expensive operation in terms of processing time and won\[u2019]t lead to great file size improvements in many cases\. Default: \fIno\fP\&\.
 .P
-Encryption related options (all options except \fB\-\-decrypt\fR automatically enabled \fB\-\-encrypt\fR):
-.
+Output file encryption related options (all options except \fB\-\-decrypt\fP automatically enable \fB\-\-encrypt\fP):
 .TP
-\fB\-\-decrypt\fR
+\fB\-\-decrypt\fP
 Remove any encryption\.
-.
-.IP
-If neither \fB\-\-decrypt\fR nor \fB\-\-encrypt\fR is specified, the existing encryption configuration is preserved\.
-.
-.TP
-\fB\-\-encrypt\fR
-Encrypt the \fIOUTPUT_FILE\fR\.
-.
-.IP
-If neither \fB\-\-decrypt\fR nor \fB\-\-encrypt\fR is specified, the existing encryption configuration is preserved\.
-.
-.TP
-\fB\-\-owner\-password\fR \fIPASSWORD\fR
-The owner password to be set on the \fIOUTPUT_FILE\fR\. This password is needed when operations not allowed by the permissions need to be done\. It can also be used when opening the PDF file\.
-.
-.IP
-Use \fB\-\fR for \fIPASSWORD\fR for reading it from standard input\.
-.
-.TP
-\fB\-\-user\-password\fR \fIPASSWORD\fR
-The user password to be set on the \fIOUTPUT_FILE\fR\. This password is needed when opening the PDF file\. The application should restrict the operations to those allowed by the permissions\.
-.
-.IP
-Use \fB\-\fR for \fIPASSWORD\fR for reading it from standard input\.
-.
-.TP
-\fB\-\-algorithm\fR \fIALGORITHM\fR
-The encryption algorithm to use on the \fIOUTPUT_FILE\fR\. Allowed algorithms are \fIaes\fR and \fIarc4\fR but \fIarc4\fR should only be used if it is absolutely necessary\. Default: \fIaes\fR\.
-.
-.TP
-\fB\-\-key\-length\fR \fIBITS\fR
-The length of the encryption key in bits\. The allowed values differ based on the chosen algorithm: A number divisible by eight between 40 to 128 for \fIarc4\fR and 128 or 256 for \fIaes\fR\. Default: \fB128\fR
-.
-.TP
-\fB\-\-force\-V4\fR
-Force the use of PDF encryption version 4 if key length is \fI128\fR and algorithm is \fIarc4\fR\. This option is probably only useful for testing the implementation of PDF libraries\' encryption handling\.
-.
-.TP
-\fB\-\-permissions\fR \fIPERMS\fR
-A comma separated list of permissions to be set on the \fIOUTPUT_FILE\fR\.
-.
-.IP
-Possible values: \fIprint\fR (allow printing), \fImodify_content\fR (allow modification of the content of pages), \fIcopy_content\fR (allow text extraction and similar operations), \fImodify_annotation\fR (allow creation and modification of annotations and filling in of forms), \fIfill_in_forms\fR (allow filling in of forms even if \fImodify_annotation\fR is not set), \fIextract_content\fR (allow text and graphics extraction in accessibility cases), \fIassemble_document\fR (allow page modifications and bookmark creation), and \fIhigh_quality_print\fR (allow high quality printing)\.
-.
+.RS
+.P
+If neither \fB\-\-decrypt\fP nor \fB\-\-encrypt\fP are specified, the existing encryption configuration is preserved\.
+.RE
+.TP
+\fB\-\-encrypt\fP
+Encrypt the \fIOUTPUT\fP\&\.
+.RS
+.P
+If neither \fB\-\-decrypt\fP nor \fB\-\-encrypt\fP are specified, the existing encryption configuration is preserved\.
+.RE
+.TP
+\fB\-\-owner\-password\fP \fIPASSWORD\fP
+The owner password to be set on the \fIOUTPUT\fP\&\. This password is needed when operations not allowed by the permissions need to be done\. It can also be used when opening the PDF file\.
+.RS
+.P
+If an owner password is set but no user password, the output file can be opened without a password but the operations are restricted as if a user password were set\.
+.P
+Use \fB\-\fP for \fIPASSWORD\fP for reading it from standard input\.
+.RE
+.TP
+\fB\-\-user\-password\fP \fIPASSWORD\fP
+The user password to be set on the \fIOUTPUT\fP\&\. This password is needed when opening the PDF file\. The application should restrict the operations to those allowed by the permissions\.
+.RS
+.P
+Use \fB\-\fP for \fIPASSWORD\fP for reading it from standard input\.
+.RE
+.TP
+\fB\-\-algorithm\fP \fIALGORITHM\fP
+The encryption algorithm to use on the \fIOUTPUT\fP\&\. Allowed algorithms are \fIaes\fP and \fIarc4\fP but \fIarc4\fP should only be used if it is absolutely necessary for compatibility reasons\. Default: \fIaes\fP\&\.
+.TP
+\fB\-\-key\-length\fP \fIBITS\fP
+The length of the encryption key in bits\. The allowed values differ based on the chosen algorithm: A number divisible by eight between 40 to 128 for \fIarc4\fP and 128 or 256 for \fIaes\fP\&\. Default: \fB128\fP\&\.
+.RS
+.P
+Note: Using 256bit AES encryption can lead to problems viewing the PDF in many applications on various platforms!
+.RE
+.TP
+\fB\-\-force\-V4\fP
+Force the use of PDF encryption version 4 if key length is \fI128\fP and algorithm is \fIarc4\fP\&\. This option is probably only useful for testing the implementation of PDF libraries\[u2019] encryption handling\.
+.TP
+\fB\-\-permissions\fP \fIPERMS\fP
+A comma separated list of permissions to be set on the \fIOUTPUT\fP:
+.RS
+.TP
+\fIprint\fP
+allow printing
+.TP
+\fImodify_content\fP
+allow modification of the content of pages
+.TP
+\fIcopy_content\fP
+allow text extraction and similar operations
+.TP
+\fImodify_annotation\fP
+allow creation and modification of annotations and filling in of forms
+.TP
+\fIfill_in_forms\fP
+allow filling in of forms even if \fImodify_annotation\fP is not set
+.TP
+\fIextract_content\fP
+allow text and graphics extraction in accessibility cases
+.TP
+\fIassemble_document\fP
+allow page modifications and bookmark creation
+.TP
+\fIhigh_quality_print\fP
+allow high quality printing
+.RE
 .SS "version"
-This command shows the version of the hexapdf application\. It is an alternative to using the global \fB\-\-version\fR option\.
-.
+This command shows the version of the hexapdf application\. It is an alternative to using the global \fB\-\-version\fP option\.
 .SH "PAGES SPECIFICATION"
-Some commands allow the specification of pages using a \fIPAGES\fR argument\. This argument is expected to be a comma separated list of single page numbers or page ranges of the form \fISTART\fR\-\fIEND\fR\. The character \'\fBe\fR\' represents the last page and can be used instead of a single number or in a range\. The pages are used in the order in which the are specified\.
-.
+Some commands allow the specification of pages using a \fIPAGES\fP argument\. This argument is expected to be a comma separated list of single page numbers or page ranges of the form \fISTART\fP\-\fIEND\fP\&\. The character \[u2018]\fBe\fP\[u2019] represents the last page and can be used instead of a single number or in a range\. The pages are used in the order in which the are specified\.
+.P
+If the start number of a page range is higher than the end number, the pages are used in the reverse order\.
+.P
+Step values can be used with page ranges\. If a range is followed by \fI/STEP\fP, \fISTEP\fP \- 1 pages are skipped after each used page\.
+.P
+Additionally, the page numbers and ranges can be suffixed with a rotation modifier:
+.sp
+.PD 0
+.TP
+\fBl\fP
+Rotate the page left, that is 90 degrees counterclockwise
+.TP
+\fBr\fP
+Rotate the page right, that is 90 degrees clockwise
+.TP
+\fBd\fP
+Rotate the page 180 degrees
+.TP
+\fBn\fP
+Remove any set page rotation
+.PD
 .P
-Additionally, the page numbers and ranges can be suffixed with a rotation modifier: \fBl\fR (for rotating a page left, i\.e\. 90 degrees counterclockwise), \fBr\fR (for rotating a page right, i\.e\. 90 degrees clockwise), \fBd\fR (for rotating a page 180 degrees) and \fBn\fR (for removing any set page rotation)\. Note that this additional functionality may not be used by all commands\.
-.
+Note that this additional functionality may not be used by all commands (it is used, for example, by the \fBmodify\fP command)\.
 .P
 Examples:
-.
-.IP "\(bu" 4
-\fB1,2,3\fR: The pages one, two and three\.
-.
-.IP "\(bu" 4
-\fB11,4\-9,1,e\fR: The pages eleven, four to nine, one and the last page, in exactly this order\.
-.
-.IP "\(bu" 4
-\fB1\-e\fR: All pages of the document\.
-.
-.IP "\(bu" 4
-\fBe\-1\fR: All pages of the document in reverse order\.
-.
-.IP "\(bu" 4
-\fB1l,2r,3\-5d,6n\fR: The pages one (rotate to the left), two (rotated to the right), three to five (all rotated 180 degrees) and six (any possibly set rotation removed)\.
-.
-.IP "" 0
-.
+.IP \(bu 4
+\fB1,2,3\fP: The pages 1, 2 and 3\.
+.IP \(bu 4
+\fB11,4\-9,1,e\fP: The pages 11, 4 to 9, 1 and the last page, in exactly this order\.
+.IP \(bu 4
+\fB1\-e\fP: All pages of the document\.
+.IP \(bu 4
+\fBe\-1\fP: All pages of the document in reverse order\.
+.IP \(bu 4
+\fB1\-5/2\fP: The pages 1, 3 and 5\.
+.IP \(bu 4
+\fB10\-1/3\fP: The pages 10, 7, 4 and 1\.
+.IP \(bu 4
+\fB1l,2r,3\-5d,6n\fP: The pages 1 (rotated left), 2 (rotated right), 3 to 5 (all rotated 180 degrees) and 6 (any possibly set rotation removed)\.
+.SH "Examples"
+.SS "modify"
+\fBhexapdf modify \-\-file input\.pdf \-\-object\-stream generate output\.pdf\fP
+.br
+\fBhexapdf m \-f input\.pdf \-\-obj g output\.pdf\fP
+.P
+Compressing: Both commands do exactly the same, compressing the \fBinput\.pdf\fP to get a smaller file size\. Howver, the second command uses the feature of abbreviating commands and options to their shortest unambiguous name so that less key presses are required\.
+.P
+\fBhexapdf modify \-f input1\.pdf \-f input2\.pdf \-f input3\.pdf output\.pdf\fP
+.br
+\fBhexapdf modify \-e \-f input1\.pdf \-f input2\.pdf \-f input3\.pdf output\.pdf\fP
+.P
+Merging: In the first case use \fBinput1\.pdf\fP as primary input file and merge the pages from \fBinput2\.pdf\fP and \fBinput3\.pdf\fP into it\. In the second case an empty PDF file is used for merging the pages from the three given input files into it; the resulting output file will not have an meta data or other additional data from the first input file\.
+.P
+\fBhexapdf modify \-f odd\.pdf \-f even\.pdf \-\-interleave combined\.pdf\fP
+.P
+Page interleaving: Takes alternatly a page from \fBodd\.pdf\fP and \fBeven\.pdf\fP to create the output file\. This is very useful if you only have a simplex scanner: First you scan the front sides, creating \fBodd\.pdf\fP, and then you scan the back sides, creating \fBeven\.pdf\fP\&\. With the command the pages can be ordered in the correct way\.
+.P
+\fBhexapdf modify \-f input\.pdf \-i 1\-5,7\-10,12\-e output\.pdf\fP
+.P
+Page removal: Remove the pages 6 and 12 from the \fBinput\.pdf\fP\&\.
+.P
+\fBhexapdf modify \-f input\.pdf \-i 1r,2\-ed output\.pdf\fP
+.P
+Page rotation: Rotate the first page to the right, that is 90 degrees clockwise, and all other pages 180 degrees\.
+.P
+\fBhexapdf modify \-f input\.pdf \-\-user\-password my_pwd \-\-permissions print output\.pdf\fP
+.P
+Encryption: Encrypt the \fBoutput\.pdf\fP so that a password is needed to open it, and only allow printing\.
+.P
+\fBhexapdf modify \-f input\.pdf \-p input_password \-\-decrypt output\.pdf\fP
+.P
+Encryption removal: Create the \fBoutput\.pdf\fP as copy of \fBinput\.pdf\fP but with the encryption removed\. If the \fB\-\-decrypt\fP was not used, the output file would retain the encryption specification of the primary input file\.
+.SS "extract"
+\fBhexapdf extract input\.pdf\fP
+.br
+\fBhexapdf extract input\.pdf \-i 1\fP
+.P
+Embedded files: The first command lists the embedded files in the \fBinput\.pdf\fP, the second one then extracts the embedded file with the index 1\.
+.SS "info"
+\fBhexapdf info input\.pdf\fP
+.P
+File information: Show general information about the PDF file, like PDF version, number of pages, creator, creation date and encryption related information\.
+.SS "inspect"
+\fBhexapdf inspect input\.pdf\fP
+.br
+\fBhexapdf inspect input\.pdf \-o 3\fP
+.P
+Inspect a PDF: These commands can be used to inspect the internal object structure of a PDF file\. The first command shows the PDF catalog object, the main object of a PDF file\. The second one shows the object with the object number 3\.
 .SH "EXIT STATUS"
 The exit status is 0 if no error happened\. Otherwise it is 1\.
-.
 .SH "SEE ALSO"
-The hexapdf website \fIhttp://hexapdf\.gettalong\.org/\fR for more information
-.
+The 
+.UR http://hexapdf\.gettalong\.org
+hexapdf website
+.UE
+for more information\.
 .SH "AUTHOR"
-hexapdf was written by Thomas Leitner \fIt_leitner@gmx\.at\fR\.
-.
+hexapdf was written by Thomas Leitner 
+.MT t_leitner@gmx\.at
+.UE
+\&\.
 .P
-This manual page was written by Thomas Leitner \fIt_leitner@gmx\.at\fR\.
+This manual page was written by Thomas Leitner 
+.MT t_leitner@gmx\.at
+.UE
+\&\.