hexapdf 0.2.0 → 0.3.0

data/lib/hexapdf/type/info.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/type/names.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/type/object_stream.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/type/page.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/type/page_tree_node.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -115,6 +115,9 @@ module HexaPDF
       #
       # Must be called on the root of the page tree, otherwise the /Count entries are not
       # correctly updated!
+      #
+      # If an existing page is inserted, it may be necessary to use Page#copy_inherited_values
+      # before insertion so that the page dictionary contains all necessary information.
       def insert_page(index, page = nil)
         page ||= new_page
         index = self[:Count] + index + 1 if index < 0
@@ -147,6 +150,8 @@ module HexaPDF
       end
 
       # Adds the page or a new empty page at the end and returns it.
+      #
+      # See: #insert_page
       def add_page(page = nil)
         insert_page(-1, page)
       end

data/lib/hexapdf/type/resources.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/type/trailer.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -88,7 +88,7 @@ module HexaPDF
       # Updates the second part of the /ID field (the first part should always be the same for a
       # PDF file, the second part should change with each write).
       def update_id
-        if !value[:ID]
+        if !value[:ID].kind_of?(Array)
           set_random_id
         else
           value[:ID][1] = Digest::MD5.digest(rand.to_s)

data/lib/hexapdf/type/viewer_preferences.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/type/xref_stream.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -119,20 +119,24 @@ module HexaPDF
       def parse_xref_section(index, w)
         xref = XRefSection.new
 
-        entry_size = w.inject(:+)
         data = stream
-        pos_in_data = 0
+        start_pos = end_pos = 0
 
-        index.each_slice(2) do |first_oid, number_of_entries|
-          number_of_entries.times do |i|
-            oid = first_oid + i
+        w0 = w[0]
+        w1 = w[1]
+        w2 = w[2]
 
+        index.each_slice(2) do |first_oid, number_of_entries|
+          first_oid.upto(first_oid + number_of_entries - 1) do |oid|
             # Default for first field: type 1
-            type_field = (w[0] == 0 ? TYPE_IN_USE : bytes_to_int(data, pos_in_data, w[0]))
+            end_pos = start_pos + w0
+            type_field = (w0 == 0 ? TYPE_IN_USE : bytes_to_int(data, start_pos, end_pos))
             # No default available for second field
-            field2 = bytes_to_int(data, pos_in_data + w[0], w[1])
+            start_pos = end_pos + w1
+            field2 = bytes_to_int(data, end_pos, start_pos)
             # Default for third field is 0 for type 1, otherwise it needs to be specified!
-            field3 = bytes_to_int(data, pos_in_data + w[0] + w[1], w[2])
+            end_pos = start_pos + w2
+            field3 = (w2 == 0 ? 0 : bytes_to_int(data, start_pos, end_pos))
 
             case type_field
             when TYPE_IN_USE
@@ -144,22 +148,22 @@ module HexaPDF
             else
               nil # Ignore entry as per PDF1.7 s7.5.8.3
             end
-            pos_in_data += entry_size
+            start_pos = end_pos
           end
         end
 
         xref
       end
 
-      # Converts +length+ bytes from the +start+ index from the +string+ to an integer.
+      # Converts the bytes of the string from the start index to the end index to an integer.
       #
-      # The bytes are converted in the big-endian way. If +length+ is zero, zero is returned.
-      def bytes_to_int(string, start, length)
-        result = 0
-        end_index = start + length
-        while start < end_index
-          result = (result << 8) | string.getbyte(start)
-          start += 1
+      # The bytes are converted in the big-endian way.
+      def bytes_to_int(string, start_index, end_index)
+        result = string.getbyte(start_index)
+        start_index += 1
+        while start_index < end_index
+          result = (result << 8) | string.getbyte(start_index)
+          start_index += 1
         end
         result
       end

data/lib/hexapdf/utils/bit_field.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/utils/bit_stream.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -38,9 +38,9 @@ module HexaPDF
 
     # Helper class for reading variable length integers from a bit stream.
     #
-    # This class allows one to read integers with a variable width of up to 16 bit from a bit
-    # stream using the #read method. The data from where these bits are read, can be set on
-    # intialization and additional data can later be appended.
+    # This class allows one to read integers with a variable width from a bit stream using the #read
+    # method. The data from where these bits are read, can be set on intialization and additional
+    # data can later be appended.
     class BitStreamReader
 
       # Creates a new object, optionally providing the string from where the bits should be read.
@@ -53,9 +53,12 @@ module HexaPDF
 
       # Appends some data to the string from where bits are read.
       def append_data(str)
-        @data = @data[@pos, @data.length - @pos] << str
+        @data.slice!(0, @pos)
+        @data << str
         @pos = 0
+        self
       end
+      alias :<< :append_data
 
       # Returns the number of remaining bits that can be read.
       def remaining_bits
@@ -64,43 +67,24 @@ module HexaPDF
 
       # Returns +true+ if +bits+ number of bits can be read.
       def read?(bits)
-        fill_bit_cache
-        @available_bits >= bits
+        remaining_bits >= bits
       end
 
       # Reads +bits+ number of bits.
       #
-      # Raises an exception if not enough bits are available for reading.
+      # Returns +nil+ if not enough bits are available for reading.
       def read(bits)
-        fill_bit_cache
-        raise HexaPDF::Error, "Not enough bits available for reading" if @available_bits < bits
-
+        while @available_bits < bits
+          @bit_cache = (@bit_cache << 8) | (@data.getbyte(@pos) || return)
+          @pos += 1
+          @available_bits += 8
+        end
         @available_bits -= bits
-        result = @bit_cache >> @available_bits
+        result = (@bit_cache >> @available_bits)
         @bit_cache &= (1 << @available_bits) - 1
-
         result
       end
 
-      private
-
-      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).
-      def fill_bit_cache
-        return unless @available_bits <= 16 && @pos != @data.size
-
-        l = case @data.size - @pos
-            when FOUR_TO_INFINITY then 4
-            when 2, 3 then 2
-            else 1
-            end
-        @bit_cache = (@bit_cache << 8 * l) | @data[@pos, l].unpack(LENGTH_TO_TYPE[l]).first
-        @pos += l
-        @available_bits += 8 * l
-      end
-
     end
 
     # Helper class for writing out variable length integers one after another as bit stream.

data/lib/hexapdf/utils/lru_cache.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/utils/math_helpers.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/utils/object_hash.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/utils/pdf_doc_encoding.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/utils/sorted_tree_node.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/version.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -34,6 +34,6 @@
 module HexaPDF
 
   # The version of HexaPDF.
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.3.0'.freeze
 
 end

data/lib/hexapdf/writer.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -103,6 +103,7 @@ module HexaPDF
       end
 
       trailer = rev.trailer.value.dup
+      trailer.delete(:XRefStm)
       if previous_xref_pos
         trailer[:Prev] = previous_xref_pos
       else

data/lib/hexapdf/xref_section.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2016 Thomas Leitner
+# Copyright (C) 2014-2017 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -121,6 +121,11 @@ module HexaPDF
       self[oid, 0] = self.class.compressed_entry(oid, objstm, pos)
     end
 
+    # Merges the entries from the given cross-reference section into this one.
+    def merge!(xref_section)
+      xref_section.each {|oid, gen, data| self[oid, gen] = data}
+    end
+
     # :call-seq:
     #   xref_section.each_subsection {|sub| block }   -> xref_section
     #   xref_section.each_subsection                  -> Enumerator

data/man/man1/hexapdf.1

@@ -15,13 +15,19 @@ Using the hexapdf application the following tasks can be performed with PDF file
 .sp
 .PD 0
 .IP \(bu 4
-Extracting embedded files (see the \fBextract\fP command)
+Extracting embedded files (see the \fBfiles\fP command)
+.IP \(bu 4
+Extracting images (see the \fBimages\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
+Merging multiple PDF files into one (see the \fBmerge\fP command)
+.IP \(bu 4
 Modifying an existing PDF file (see the \fBmodify\fP command)
+.IP \(bu 4
+Optimizing the file size of a PDF file (see the \fBoptimize\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\.
@@ -33,93 +39,13 @@ Show the version of the hexapdf application and exit\.
 .P
 These options are available on every command (except if they are overridden):
 .TP
+\fB\-\-[no\-]force\fP
+Force overwriting existing files\. Default: \fIfalse\fP\&\.
+.TP
 \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\.
-.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\fP for the \fBextract\fP command is sufficient\.
-.SS "extract"
-Synopsis: \fBextract\fP [\fBOPTIONS\fP] \fIFILE\fP
-.P
-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\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\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\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\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\fP [\fBOPTIONS\fP] \fIFILE\fP
-.P
-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\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\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 native PDF syntax\.
-.TP
-\fB\-t\fP, \fB\-\-trailer\fP
-Show the trailer dictionary\.
-.TP
-\fB\-c\fP, \fB\-\-page\-count\fP
-Print the number of pages\.
-.TP
-\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\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\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\fP
-Modifies \fB\-\-stream\fP to show the raw stream data instead of the filtered one\.
-.TP
-\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\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
-Input file related options:
-.TP
-\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\-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\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\.
+.SS "Optimization Options"
+Theses options can only be used with the \fBmerge\fP, \fBmodify\fP and \fBoptimize\fP commands and control optimization aspects when writing an output PDF file\. Note that the defaults maybe different depending on the command\.
 .TP
 \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\&\.
@@ -135,8 +61,10 @@ Defines how streams should be treated: \fIcompress\fP will compress them when po
 .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\&\.
+.SS "Encryption Options"
+These options can only be used with the \fBmerge\fP and \fBmodify\fP commands and control if and how an output PDF file should be encrypted\. All options except \fB\-\-decrypt\fP automatically enable \fB\-\-encrypt\fP\&\.
 .P
-Output file encryption related options (all options except \fB\-\-decrypt\fP automatically enable \fB\-\-encrypt\fP):
+Note that if a password is needed to open the input file and if encryption parameters are changed, the provided password is not automatically used for the output file!
 .TP
 \fB\-\-decrypt\fP
 Remove any encryption\.
@@ -153,7 +81,7 @@ If neither \fB\-\-decrypt\fP nor \fB\-\-encrypt\fP are specified, the existing e
 .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\.
+The owner password to be set on the output file\. 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\.
@@ -162,14 +90,14 @@ 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\.
+The user password to be set on the output file\. 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\&\.
+The encryption algorithm to use on the output file\. 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\&\.
@@ -182,7 +110,7 @@ Note: Using 256bit AES encryption can lead to problems viewing the PDF in many a
 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:
+A comma separated list of permissions to be set on the output file:
 .RS
 .TP
 \fIprint\fP
@@ -209,6 +137,159 @@ allow page modifications and bookmark creation
 \fIhigh_quality_print\fP
 allow high quality printing
 .RE
+.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\.
+.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 \fBf\fP for the \fBfiles\fP command is sufficient\. The same is true for long option names and option values\.
+.SS "files"
+Synopsis: \fBfiles\fP [\fBOPTIONS\fP] \fIPDF\fP
+.P
+This command extracts embedded files from the \fIPDF\fP\&\. If the \fB\-\-extract\fP option is not specified, the indices and names of the embedded files are just listed\.
+.TP
+\fB\-e\fP [\fIA,B,C,\.\.\.\fP], \fB\-\-extract\fP [\fIA,B,C,\.\.\.\fP]
+The indices of the embedded files that should be extracted\. The value \fI0\fP can be used to extract all embedded files\.
+.TP
+\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\fP \fIPASSWORD\fP, \fB\-\-password\fP \fIPASSWORD\fP
+The password to decrypt the \fIPDF\fP\&\. Use \fB\-\fP for \fIPASSWORD\fP for reading it from standard input\.
+.SS "help"
+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 "images"
+Synopsis: \fBimages\fP [\fBOPTIONS\fP] \fIPDF\fP
+.P
+This command extracts images from the \fIPDF\fP\&\. If the \fB\-\-extract\fP option is not specified, the images are listed with their indices and additional information, sorted by page number\. The \fB\-\-extract\fP option can then be used to extract one or more images, saving them to files called \fBPREFIX\-N\.EXT\fP where the prefix can be set via \fB\-\-prefix\fP, \fIN\fP is the image index and \fIEXT\fP is either png, jpg or jpx\.
+.TP
+\fB\-e\fP [\fIA,B,C,\.\.\.\fP], \fB\-\-extract\fP [\fIA,B,C,\.\.\.\fP]
+The indices of the images that should be extracted\. Use \fI0\fP or no value to extract all images\.
+.TP
+\fB\-\-prefix\fP \fIPREFIX\fP
+The prefix to use when saving images\. May include directories\. Defaults to \fIimage\fP\&\.
+.TP
+\fB\-s\fP, \fB\-\-[no\-]search\fP
+Search the whole PDF file instead of the standard locations, that is, images referenced by pages\. Defaults to \fIfalse\fP\&\.
+.TP
+\fB\-p\fP \fIPASSWORD\fP, \fB\-\-password\fP \fIPASSWORD\fP
+The password to decrypt the \fIPDF\fP\&\. Use \fB\-\fP for \fIPASSWORD\fP for reading it from standard input\.
+.P
+The following information is shown for each image when listing images:
+.RS
+.TP
+\fBindex\fP
+The image index needed when this image should be extracted\.
+.TP
+\fBpage\fP
+The page number on which this image appears\.
+.TP
+\fBoid\fP
+The PDF internal object identifier consisting of the object and generation numbers\.
+.TP
+\fBwidth\fP
+The width of the image in pixels\.
+.TP
+\fBheight\fP
+The height of the image in pixels\.
+.TP
+\fBcolor\fP
+The color space used for the image\. Either gray, rgb, cmyk or other\.
+.TP
+\fBcomp\fP
+The number of color components\.
+.TP
+\fBbpc\fP
+The number of bits per color component\.
+.TP
+\fBtype\fP
+The image type\. Either jpg (JPEG), jp2 (JPEG2000), ccitt (CCITT Group 3 or 4 Fax), jbig2 (JBIG2) or png (PNG)\.
+.TP
+\fBwritable\fP
+Either true or false depending on whether hexapdf supports the image format\.
+.RE
+.SS "info"
+Synopsis: \fBinfo\fP [\fBOPTIONS\fP] \fIFILE\fP
+.P
+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\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\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 PDF trailer 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\-\-catalog\fP
+Show the PDF catalog dictionary\.
+.TP
+\fB\-c\fP, \fB\-\-page\-count\fP
+Print the number of pages\.
+.TP
+\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\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\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\fP
+Modifies \fB\-\-stream\fP to show the raw stream data instead of the filtered one\.
+.TP
+\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 "merge"
+Synopsis: \fBmerge\fP [\fBOPTIONS\fP] { \fIINPUT\fP | \fB\-\-empty\fP } [\fIINPUT\fP]\.\.\. \fIOUTPUT\fP
+.P
+This command merges pages from multiple PDFs into one output file which can optionally be encrypted/decrypted and optimized in various ways\.
+.P
+The first input file is the primary file from which meta data like file information, outlines, etc\. are taken from\. Alternatively, it is possible to start with an empty PDF file by using \fB\-\-empty\fP\&\. The order of 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\.
+.TP
+\fB\-p\fP \fIPASSWORD\fP, \fB\-\-password\fP \fIPASSWORD\fP
+The password to decrypt the last input file\. 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 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
+Additionally, the \fBOptimization Options\fP and \fBEncryption Options\fP can be used\.
+.SS "modify"
+Synopsis: \fBmodify\fP [\fBOPTIONS\fP] \fIINPUT\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/or rotate them\. The output file can also be encrypted/decrypted and optimized in various ways\.
+.TP
+\fB\-p\fP \fIPASSWORD\fP, \fB\-\-password\fP \fIPASSWORD\fP
+The password to decrypt the \fIINPUT\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 \fIINPUT\fP 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 \fIFILE\fP, \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\.
+.P
+Additionally, the \fBOptimization Options\fP and \fBEncryption Options\fP can be used\.
+.SS "optimize"
+Synopsis: \fBoptimize\fP [\fBOPTIONS\fP] \fIINPUT\fP \fIOUTPUT\fP
+.P
+This command uses several optimization strategies to reduce the file size of the PDF file\.
+.P
+By default, all strategies except page compression are used since page compression may take a very long time without much benefit\.
+.TP
+\fB\-p\fP \fIPASSWORD\fP, \fB\-\-password\fP \fIPASSWORD\fP
+The password to decrypt the \fIINPUT\fP\&\. Use \fB\-\fP for \fIPASSWORD\fP for reading it from standard input\.
+.P
+The \fBOptimization Options\fP can be used with this command\. Note that the defaults are changed to provide good compression out of the box\.
 .SS "version"
 This command shows the version of the hexapdf application\. It is an alternative to using the global \fB\-\-version\fP option\.
 .SH "PAGES SPECIFICATION"
@@ -252,43 +333,41 @@ Examples:
 \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
+.SH "EXAMPLES"
+.SS "merge"
+\fBhexapdf merge input1\.pdf input2\.pdf input3\.pdf output\.pdf\fP
 .br
-\fBhexapdf modify \-e \-f input1\.pdf \-f input2\.pdf \-f input3\.pdf output\.pdf\fP
+\fBhexapdf merge \-e input1\.pdf input2\.pdf 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\.
+\fBhexapdf merge odd\.pdf even\.pdf \-\-interleave combined\.pdf\fP
 .P
-\fBhexapdf modify \-f input\.pdf \-i 1\-5,7\-10,12\-e output\.pdf\fP
+Page interleaving: Takes alternately 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\.
+.SS "modify"
+\fBhexapdf modify 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\&\.
+Page removal: Remove the pages 6 and 11 from the \fBinput\.pdf\fP\&\.
 .P
-\fBhexapdf modify \-f input\.pdf \-i 1r,2\-ed output\.pdf\fP
+\fBhexapdf modify 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
+\fBhexapdf modify input\.pdf \-\-user\-password my_pwd \-\-permissions print output\.pdf\fP
+.P
+Encryption: Create the \fBoutput\.pdf\fP from the \fBinput\.pdf\fP so that a password is needed to open it, and only allow printing\.
 .P
-Encryption: Encrypt the \fBoutput\.pdf\fP so that a password is needed to open it, and only allow printing\.
+\fBhexapdf modify input\.pdf \-p input_password \-\-decrypt output\.pdf\fP
 .P
-\fBhexapdf modify \-f input\.pdf \-p input_password \-\-decrypt output\.pdf\fP
+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 input file\.
+.SS "optimize"
+\fBhexapdf optimize input\.pdf 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
+Optimization: Compress the \fBinput\.pdf\fP to get a smaller file size\.
+.SS "files"
+\fBhexapdf files input\.pdf\fP
 .br
-\fBhexapdf extract input\.pdf \-i 1\fP
+\fBhexapdf files 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"
@@ -300,7 +379,7 @@ File information: Show general information about the PDF file, like PDF version,
 .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\.
+Inspect a PDF: These commands can be used to inspect the internal object structure of a PDF file\. The first command shows the PDF trailer object\. 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"