From bd88b96f7b7b21d64d4fb32a2674653a08f8cb38 Mon Sep 17 00:00:00 2001
From: Tor Andersson <tor.andersson@artifex.com>
Date: Mon, 30 Apr 2018 17:23:06 +0200
Subject: Add selector syntax to 'mutool show'.

---
 docs/manual-mutool-show.html | 43 +++++++++++++++++++++++++++++--------------
 1 file changed, 29 insertions(+), 14 deletions(-)

(limited to 'docs')

diff --git a/docs/manual-mutool-show.html b/docs/manual-mutool-show.html
index e9568fed..0805d108 100644
--- a/docs/manual-mutool-show.html
+++ b/docs/manual-mutool-show.html
@@ -25,11 +25,11 @@
 
 <p>
 The show command will print the specified objects and streams to
-stdout.  Streams are decoded and non-printable characters are
+stdout. Streams are decoded and non-printable characters are
 represented with a period by default.
 
 <pre>
-mutool show [options] file.pdf [object numbers ...]
+mutool show [options] file.pdf ( xref | outline | grep | <i>&lt;path&gt;</i> ) *
 </pre>
 
 <p>
@@ -40,29 +40,44 @@ Options:
 <dd> Use the specified password if the file is encrypted.
 <dt> -o file
 <dd> Write output to file instead of stdout.
-<dt> -b
-<dd> Print streams as binary data and omit the object header.
 <dt> -e
 <dd> Print streams in their original encoded (or compressed) form.
+<dt> -b
+<dd> Print streams as binary data, and omit the object.
+<dt> -g
+<dd> Print objects in a one-line form suitable for grep, and omit stream data.
 </dl>
 
 <p>
-Specify objects by number, or use one of the following special names:
+Specify what to show by using one of the following keywords, or specify a path
+to an object:
 
 <dl>
-<dt> 'xref' or 'x'
+<dt> xref
 <dd> Print the cross reference table.
-<dt> 'trailer' or 't'
-<dd> Print the trailer dictionary.
-<dt> 'encrypt' or 'e'
-<dd> Print the encryption dictionary.
-<dt> 'pagetree' or 'p'
+<dt> outline
+<dd> Print the outline (table of contents).
+<dt> pages
 <dd> List the object numbers for every page.
-<dt> 'grep' or 'g'
+<dt> grep
 <dd> Print all the objects in the file in a compact one-line format
 suitable for piping to grep.
-<dt> 'outline' or 'o'
-<dd> Print the outline (table of contents).
+</dl>
+
+<p>
+A path starts with either an object number, a property in the trailer
+dictionary, or the keyword "trailer" or "pages". Separate elements with
+a period '.' or slash '/'.
+Select a page object by using pages/<i>N</i> where N is the page number.
+The first page is number 1.
+
+<dl>
+<dt> Find the number of pages in a document:
+<dd> <tt>mutool show $FILE trailer/Pages/Count</tt>
+<dt> Print the raw content stream of the first page:
+<dd> <tt>mutool show -b $FILE pages/1/Contents</tt>
+<dt> Show all JPEG compressed stream objects:
+<dd> <tt>mutool show $FILE grep | grep '/Filter/DCTDecode'</tt>
 </dl>
 
 </article>
-- 
cgit v1.2.3