Update ippfind documentation with examples, change '-e' to '-x' for --exec.

Add ippfind to the ipptool binary package.

git-svn-id: svn+ssh://src.apple.com/svn/cups/cups.org/trunk@11027 a1ca3aef-8c08-0410-bb20-df032aa958be

diff --git a/CHANGES-IPPTOOL.txt b/CHANGES-IPPTOOL.txt
index 9c0a36fe09a59a3cbf30b8b66e10efe6c176ecdc..c05f4c40f5bd0fda7646f973fed94a1990f3c27a 100644 (file)
--- a/CHANGES-IPPTOOL.txt
+++ b/CHANGES-IPPTOOL.txt
@@ -1,11 +1,12 @@
-CHANGES-IPPTOOL.txt - 2013-05-29
+CHANGES-IPPTOOL.txt - 2013-06-06
 --------------------------------
 
 This file provides a list of changes to the ipptool binary distribution posted
 on cups.org.
 
-2013-05-29
+2013-06-06
 
+       - New ippfind tool now included with ipptool.
        - Added support for automatically extending the timeout when all of the
          request data has not yet been written (all platforms but Windows
          which does not support it...)

diff --git a/CHANGES.txt b/CHANGES.txt
index 002400e603dd87457c18dd5890914b8e0a2913fd..de0c0bab6b8ac7513b6445c00b35ee63ea3aeea3 100644 (file)
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,8 +1,10 @@
-CHANGES.txt - 1.7rc1 - 2013-06-05
+CHANGES.txt - 1.7rc1 - 2013-06-06
 ---------------------------------
 
 CHANGES IN CUPS V1.7rc1
 
+       - Added a new ippfind tool for finding IPP printers and other Bonjour
+         services (<rdar://problem/13876199>)
        - Fixed some issues with conversion of PWG media size names to
          hundredths of millimeters (<rdar://problem/14065748>)
        - The IPP backend could crash on OS X when printing to a Kerberized

diff --git a/IPPTOOL.txt b/IPPTOOL.txt
index 150605766d6ca4a4871a7f934bcb219e53c31799..31d6fe4eece59255da652001cb1b0e37d86f0019 100644 (file)
--- a/IPPTOOL.txt
+++ b/IPPTOOL.txt
@@ -1,4 +1,4 @@
-IPPTOOL.txt - 2013-05-02
+IPPTOOL.txt - 2013-06-06
 ------------------------
 
 See the file CHANGES-IPPTOOL.txt for a list of changes to this software.
@@ -12,8 +12,30 @@ INTRODUCTION
     complex conformance tests and a simple way to query printer, job, and
     subscription attributes.
 
+    CUPS also includes a user program called ippfind that can be used to find
+    IPP printers that have registered themselves using Bonjour (DNS-SD, mDNS,
+    and Zeroconf) and run commands such as ipptool.
 
-BASIC USAGE
+
+IPPFIND BASIC USAGE
+
+    The ippfind command can be used to discover IPP printers on your network.
+    For example, the following command prints the printer URI of registered IPP
+    printers:
+
+        ippfind
+
+    To find all color IPP printers, run:
+
+        ippfind --txt-color T
+
+    To run the IPP Everywhere conformance test file on every registered IPP
+    printer, run the following command instead:
+
+        ippfind --exec ipptool -t '{}' ipp-everywhere.test \;
+
+
+IPPTOOL BASIC USAGE
 
     The ipptool command requires a printer URI and one or more "test" files that
     describe the operations, attributes to display, and expected status and

diff --git a/doc/help/man-ippfind.html b/doc/help/man-ippfind.html
index 32c53985d64f14ac44014ebec6b8bfdcbda4a65e..e614ad4dadeb671d8e6346b04d97fd2252bc5365 100644 (file)
--- a/doc/help/man-ippfind.html
+++ b/doc/help/man-ippfind.html
@@ -26,31 +26,6 @@ ippfind - find internet printing protocol printers
 </b>--help
 <b>ippfind
 </b>--version
-<h2 class="title"><a name="SUPPORTED_REGISTRATION_TYPES">Supported Registration Types</a></h2>
-<i>ippfind</i> supports the following registration types:
-<dl>
-<dt>_http._tcp
-</dt>
-<dd>HyperText Transport Protocol (HTTP, RFC 2616)
-</dd>
-<dt>_https._tcp
-</dt>
-<dd>Secure HyperText Transport Protocol (HTTPS, RFC 2818)
-</dd>
-<dt>_ipp._tcp
-</dt>
-<dd>Internet Printing Protocol (IPP, RFC 2911)
-</dd>
-<dt>_ipps._tcp
-</dt>
-<dd>Secure Internet Printing Protocol (IPPS, draft)
-</dd>
-<dt>_printer._tcp
-</dt>
-<dd>Line Printer Daemon (LPD, RFC 1179)
-
-</dd>
-</dl>
 <h2 class="title"><a name="OPTIONS">Options</a></h2>
 <dl>
 <dt>--help
@@ -80,10 +55,43 @@ ippfind - find internet printing protocol printers
 </dd>
 </dl>
 <h2 class="title"><a name="DESCRIPTION">Description</a></h2>
-<i>ippfind</i> finds printer services registered with the local DNS infrastructure or available through the local links.
+<i>ippfind</i> finds services registered with a DNS server or available through local devices. Its primary purpose is to find IPP printers and show their URIs, show their current status, or run commands. For example, to show the status of all registered IPP printers on your network, run:
+<pre>
+    ippfind --ls
+</pre>
+Similarly, to send a PostScript test page to every PostScript printer, run:
+<pre>
+    ippfind --txt-pdl application/postscript --exec ipptool \
+        -f onepage-letter.ps '{}' print-job.test \;
+</pre>
+
+<h2 class="title"><a name="REGISTRATION_TYPES">Registration Types</a></h2>
+<i>ippfind</i> supports the following registration types:
+<dl>
+<dt>_http._tcp
+</dt>
+<dd>HyperText Transport Protocol (HTTP, RFC 2616)
+</dd>
+<dt>_https._tcp
+</dt>
+<dd>Secure HyperText Transport Protocol (HTTPS, RFC 2818)
+</dd>
+<dt>_ipp._tcp
+</dt>
+<dd>Internet Printing Protocol (IPP, RFC 2911)
+</dd>
+<dt>_ipps._tcp
+</dt>
+<dd>Secure Internet Printing Protocol (IPPS, draft)
+</dd>
+<dt>_printer._tcp
+</dt>
+<dd>Line Printer Daemon (LPD, RFC 1179)
 
+</dd>
+</dl>
 <h2 class="title"><a name="EXPRESSIONS">Expressions</a></h2>
-<i>ippfind</i> supports expressions much like the <i>find(1)</i> utility. However, unlike <i>find</i>, <i>ippfind</i> uses POSIX regular expressions instead of shell filename matching patterns. If -e, --exec, -l, --ls, -p, --print, --print-name, -q, --quiet, or -s is not specified, <i>ippfind</i> adds --print to print the service URI of anything it finds. The following expressions are supported:
+<i>ippfind</i> supports expressions much like the <i>find(1)</i> utility. However, unlike <i>find</i>, <i>ippfind</i> uses POSIX regular expressions instead of shell filename matching patterns. If --exec, -l, --ls, -p, --print, --print-name, -q, --quiet, -s, or -x is not specified, <i>ippfind</i> adds --print to print the service URI of anything it finds. The following expressions are supported:
 <dl>
 <dt>-d regex
 </dt>
@@ -92,17 +100,17 @@ ippfind - find internet printing protocol printers
 </dt>
 <dd>True if the domain matches the given regular expression.
 </dd>
-<dt>-e utility [argument ...] ;
-</dt>
-<dd></dd>
-<dt>--exec utility [argument ...] ;
-</dt>
-<dd>Executes the specified program if the current result is true. "{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below.
-</dd>
 <dt>--false
 </dt>
 <dd>Always false.
 </dd>
+<dt>-h regex
+</dt>
+<dd></dd>
+<dt>--host regex
+</dt>
+<dd>True is the hostname matches the given regular expression.
+</dd>
 <dt>-l
 </dt>
 <dd></dd>
@@ -125,6 +133,13 @@ ippfind - find internet printing protocol printers
 </dt>
 <dd>True if the URI resource path matches the given regular expression.
 </dd>
+<dt>-P number[-number]
+</dt>
+<dd></dd>
+<dt>--port number[-number]
+</dt>
+<dd>True if the port matches the given number or range.
+</dd>
 <dt>-p
 </dt>
 <dd></dd>
@@ -176,6 +191,13 @@ expression.
 </dt>
 <dd>True if the URI matches the given regular expression.
 </dd>
+<dt>-x utility [argument ...] ;
+</dt>
+<dd></dd>
+<dt>--exec utility [argument ...] ;
+</dt>
+<dd>Executes the specified program if the current result is true. "{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below.
+</dd>
 </dl>
 <p>Expressions may also contain modifiers:
 <dl>

diff --git a/man/ippfind.man b/man/ippfind.man
index ae67c3206da9ad0184e4f47da70e2a9e75a9904b..24c5a26609e65cdd5f0af3f29ccec07944a12f9d 100644 (file)
--- a/man/ippfind.man
+++ b/man/ippfind.man
@@ -11,7 +11,7 @@
 .\"   which should have been included with this file.  If this file is
 .\"   file is missing or damaged, see the license at "http://www.cups.org/".
 .\"
-.TH ippfind 1 "CUPS" "5 June 2013" "Apple Inc."
+.TH ippfind 1 "CUPS" "6 June 2013" "Apple Inc."
 .SH NAME
 ippfind - find internet printing protocol printers
 .SH SYNOPSIS
@@ -31,24 +31,6 @@ ippfind - find internet printing protocol printers
 --help
 .B ippfind
 --version
-.SH SUPPORTED REGISTRATION TYPES
-\fIippfind\fR supports the following registration types:
-.TP 5
-_http._tcp
-HyperText Transport Protocol (HTTP, RFC 2616)
-.TP 5
-_https._tcp
-Secure HyperText Transport Protocol (HTTPS, RFC 2818)
-.TP 5
-_ipp._tcp
-Internet Printing Protocol (IPP, RFC 2911)
-.TP 5
-_ipps._tcp
-Secure Internet Printing Protocol (IPPS, draft)
-.TP 5
-_printer._tcp
-Line Printer Daemon (LPD, RFC 1179)
-
 .SH OPTIONS
 .TP 5
 --help
@@ -70,21 +52,42 @@ Specify find timeout in seconds. If 1 or less, \fIippfind\fR stops as soon as it
 Specifies the IPP version when listing. Supported values are 1.1, 2.0, 2.1, and 2.2.
 
 .SH DESCRIPTION
-\fIippfind\fR finds printer services registered with the local DNS infrastructure or available through the local links.
+\fIippfind\fR finds services registered with a DNS server or available through local devices. Its primary purpose is to find IPP printers and show their URIs, show their current status, or run commands. For example, to show the status of all registered IPP printers on your network, run:
+.nf
+    ippfind --ls
+.fi
+Similarly, to send a PostScript test page to every PostScript printer, run:
+.nf
+    ippfind --txt-pdl application/postscript --exec ipptool \\
+        -f onepage-letter.ps '{}' print-job.test \\;
+.fi
+
+.SH REGISTRATION TYPES
+\fIippfind\fR supports the following registration types:
+.TP 5
+_http._tcp
+HyperText Transport Protocol (HTTP, RFC 2616)
+.TP 5
+_https._tcp
+Secure HyperText Transport Protocol (HTTPS, RFC 2818)
+.TP 5
+_ipp._tcp
+Internet Printing Protocol (IPP, RFC 2911)
+.TP 5
+_ipps._tcp
+Secure Internet Printing Protocol (IPPS, draft)
+.TP 5
+_printer._tcp
+Line Printer Daemon (LPD, RFC 1179)
 
 .SH EXPRESSIONS
-\fIippfind\fR supports expressions much like the \fIfind(1)\fR utility. However, unlike \fIfind\fR, \fIippfind\fR uses POSIX regular expressions instead of shell filename matching patterns. If -e, --exec, -l, --ls, -p, --print, --print-name, -q, --quiet, or -s is not specified, \fIippfind\fR adds --print to print the service URI of anything it finds. The following expressions are supported:
+\fIippfind\fR supports expressions much like the \fIfind(1)\fR utility. However, unlike \fIfind\fR, \fIippfind\fR uses POSIX regular expressions instead of shell filename matching patterns. If --exec, -l, --ls, -p, --print, --print-name, -q, --quiet, -s, or -x is not specified, \fIippfind\fR adds --print to print the service URI of anything it finds. The following expressions are supported:
 .TP 5
 -d regex
 .TP 5
 --domain regex
 True if the domain matches the given regular expression.
 .TP 5
--e utility [argument ...] ;
-.TP 5
---exec utility [argument ...] ;
-Executes the specified program if the current result is true. "{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below.
-.TP 5
 --false
 Always false.
 .TP 5
@@ -150,6 +153,11 @@ expression.
 .TP 5
 --uri regex
 True if the URI matches the given regular expression.
+.TP 5
+-x utility [argument ...] ;
+.TP 5
+--exec utility [argument ...] ;
+Executes the specified program if the current result is true. "{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below.
 .PP
 Expressions may also contain modifiers:
 .TP 5

diff --git a/test/ippfind.c b/test/ippfind.c
index d8dfe5f427c2055b0485e2d29d8bf53df0587978..588306059241ff4d99c32fd417276d704cc55990 100644 (file)
--- a/test/ippfind.c
+++ b/test/ippfind.c
@@ -806,37 +806,6 @@ main(int  argc,                            /* I - Number of command-line args */
                  return (IPPFIND_EXIT_MEMORY);
                 break;
 
-            case 'e' :
-               i ++;
-               if (i >= argc)
-               {
-                 _cupsLangPrintf(stderr,
-                                 _("ippfind: Missing program after %s."),
-                                 "-e");
-                 show_usage();
-               }
-
-               if ((temp = new_expr(IPPFIND_OP_EXEC, invert, NULL, NULL,
-                                    argv + i)) == NULL)
-                 return (IPPFIND_EXIT_MEMORY);
-
-               while (i < argc)
-                 if (!strcmp(argv[i], ";"))
-                   break;
-                 else
-                   i ++;
-
-               if (i >= argc)
-               {
-                 _cupsLangPrintf(stderr,
-                                 _("ippfind: Missing semi-colon after %s."),
-                                 "-e");
-                 show_usage();
-               }
-
-               have_output = 1;
-                break;
-
             case 'h' :
                i ++;
                if (i >= argc)
@@ -935,6 +904,37 @@ main(int  argc,                            /* I - Number of command-line args */
                  return (IPPFIND_EXIT_MEMORY);
                 break;
 
+            case 'x' :
+               i ++;
+               if (i >= argc)
+               {
+                 _cupsLangPrintf(stderr,
+                                 _("ippfind: Missing program after %s."),
+                                 "-x");
+                 show_usage();
+               }
+
+               if ((temp = new_expr(IPPFIND_OP_EXEC, invert, NULL, NULL,
+                                    argv + i)) == NULL)
+                 return (IPPFIND_EXIT_MEMORY);
+
+               while (i < argc)
+                 if (!strcmp(argv[i], ";"))
+                   break;
+                 else
+                   i ++;
+
+               if (i >= argc)
+               {
+                 _cupsLangPrintf(stderr,
+                                 _("ippfind: Missing semi-colon after %s."),
+                                 "-x");
+                 show_usage();
+               }
+
+               have_output = 1;
+                break;
+
             default :
                 _cupsLangPrintf(stderr, _("%s: Unknown option \"-%c\"."),
                                 "ippfind", *opt);
@@ -2729,8 +2729,6 @@ show_usage(void)
   _cupsLangPuts(stderr, _("Expressions:"));
   _cupsLangPuts(stderr, _("  -P number[-number]      Match port to number or range."));
   _cupsLangPuts(stderr, _("  -d regex                Match domain to regular expression."));
-  _cupsLangPuts(stderr, _("  -e utility [argument ...] ;\n"
-                          "                          Execute program if true."));
   _cupsLangPuts(stderr, _("  -h regex                Match hostname to regular expression."));
   _cupsLangPuts(stderr, _("  -l                      List attributes."));
   _cupsLangPuts(stderr, _("  -n regex                Match service name to regular expression."));
@@ -2740,6 +2738,8 @@ show_usage(void)
   _cupsLangPuts(stderr, _("  -s                      Print service name if true."));
   _cupsLangPuts(stderr, _("  -t key                  True if the TXT record contains the key."));
   _cupsLangPuts(stderr, _("  -u regex                Match URI to regular expression."));
+  _cupsLangPuts(stderr, _("  -x utility [argument ...] ;\n"
+                          "                          Execute program if true."));
   _cupsLangPuts(stderr, _("  --domain regex          Match domain to regular expression."));
   _cupsLangPuts(stderr, _("  --exec utility [argument ...] ;\n"
                           "                          Execute program if true."));

diff --git a/tools/makeipptoolpkg b/tools/makeipptoolpkg
index df0b1d8c24cc025e85ff6b412bedcc89a22bff34..1428257e460da99f426e67c1c925f0c16a64ff02 100644 (file)
--- a/tools/makeipptoolpkg
+++ b/tools/makeipptoolpkg
@@ -52,7 +52,7 @@ mkdir $pkgdir || exit 1
 
 echo Copying package files
 cp CHANGES-IPPTOOL.txt IPPTOOL.txt LICENSE.txt $pkgdir
-cp doc/help/man-ipptool*.html $pkgdir
+cp doc/help/man-ipp*.html $pkgdir
 cp test/color.jpg $pkgdir
 cp test/create-printer-subscription.test $pkgdir
 cp test/document-*.pdf $pkgdir
@@ -64,6 +64,7 @@ cp test/get-subscriptions.test $pkgdir
 cp test/gray.jpg $pkgdir
 cp test/ipp-[12].*.test $pkgdir
 cp test/ipp-everywhere.test $pkgdir
+cp test/ippfind-static $pkgdir/ippfind
 cp test/ipptool-static $pkgdir/ipptool
 cp test/onepage-*.pdf $pkgdir
 cp test/onepage-*.ps $pkgdir