Update documentation for new URI content validation predicates (Issue #…

…22)
OpenPrinting · Jan 28, 2023 · 17316a3 · 17316a3
1 parent 4697a86
commit 17316a3
Show file tree

Hide file tree

Showing 8 changed files with 216 additions and 182 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -22,7 +22,9 @@ libcups v3.0b1 (Month DD, YYYY)
 - Added a roll to the default color ippeveprinter printer.
 - Added new DNS-SD API (Issue #19)
 - Added new PWG media sizes.
-- Added new `EXPECT-ALL-VALUES-FROM` predicate for ipptool files (Issue #20)
+- Added new `WITH-ALL-VALUES-FROM` predicate for ipptool files (Issue #20)
+- Added new `SAVE-ALL-CONTENT`, `WITH-ALL-CONTENT`, and `WITH-ALL-MIME-TYPES`
+  predicates for ipptool files (Issue #22)
 - Added, modernized, and promoted the localization interfaces to public API
   (Issue #24)
 - Added public JSON API (Issue #31)

diff --git a/doc/ippevepcl.html b/doc/ippevepcl.html
@@ -16,7 +16,7 @@
   text-align: justify;
 }
 --></style>
-    <meta name="creator" content="mantohtml v2.0">
+    <meta name="creator" content="mantohtml v2022.1005">
     <title>Documentation</title>
   </head>
   <body>
@@ -47,7 +47,7 @@ <h2 id="ippevepclps-7.description">Description</h2>
 Status and progress messages are sent to the standard error.
 </p>
     <p><strong>ippevepcl</strong>
-prints to B&amp;W HP PCL laser printers and supports printing of HP PCL (application/vnd.hp-pcl), PWG Raster (image/pwg-raster), and Apple Raster (image/urf) print files.
+prints to B&W HP PCL laser printers and supports printing of HP PCL (application/vnd.hp-pcl), PWG Raster (image/pwg-raster), and Apple Raster (image/urf) print files.
 </p>
     <p><strong>ippeveps</strong>
 print to Adobe PostScript printers and supports printing of PDF (application/pdf), PostScript (application/postscript), JPEG (image/jpeg), PWG Raster (image/pwg-raster), and Apple Raster (image/urf) print files.

diff --git a/doc/ippeveprinter.html b/doc/ippeveprinter.html
@@ -16,7 +16,7 @@
   text-align: justify;
 }
 --></style>
-    <meta name="creator" content="mantohtml v2.0">
+    <meta name="creator" content="mantohtml v2022.1005">
     <title>Documentation</title>
   </head>
   <body>
@@ -113,7 +113,7 @@ <h2 id="ippeveprinter-1.options">Options</h2>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--pam-service </strong><em>service</em><br>
 Set the PAM service name.
-The default service is &quot;cups&quot;.
+The default service is "cups".
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--version</strong><br>
 Show the CUPS version.
@@ -128,25 +128,25 @@ <h2 id="ippeveprinter-1.options">Options</h2>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-D </strong><em>device-uri</em><br>
 Set the device URI for print output.
-The URI can be a filename, directory, or a network socket URI of the form &quot;socket://ADDRESS[:PORT]&quot; (where the default port number is 9100).
+The URI can be a filename, directory, or a network socket URI of the form "socket://ADDRESS[:PORT]" (where the default port number is 9100).
 When specifying a directory,
 <strong>ippeveprinter</strong>
 will create an output file using the job ID and name.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-F </strong><em>output-type/subtype[,...]</em><br>
 Specifies the output MIME media type.
-The default is &quot;application/postscript&quot; when the <strong>-P</strong> option is specified.
+The default is "application/postscript" when the <strong>-P</strong> option is specified.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-M </strong><em>manufacturer</em><br>
 Set the manufacturer of the printer.
-The default is &quot;Example&quot;.
+The default is "Example".
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-P </strong><em>filename.ppd</em><br>
 Load printer attributes from the specified PPD file.
 This option is typically used in conjunction with the
 <strong>ippeveps</strong>(7)
 
-printer command (&quot;-c ippeveps&quot;).
+printer command ("-c ippeveps").
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-V 1.1</strong><br>
 </p>
@@ -156,13 +156,13 @@ <h2 id="ippeveprinter-1.options">Options</h2>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-c </strong><em>command</em><br>
 Run the specified command for each document that is printed.
-If &quot;command&quot; is not an absolute path (&quot;/path/to/command&quot;),
+If "command" is not an absolute path ("/path/to/command"),
 <strong>ippeveprinter</strong>
-looks for the command in the &quot;command&quot; subdirectory of the CUPS binary directory, typically /usr/lib/cups/command or /usr/libexec/cups/command.
+looks for the command in the "command" subdirectory of the CUPS binary directory, typically /usr/lib/cups/command or /usr/libexec/cups/command.
 The
 <strong>cups-config</strong>(1)
 
-command can be used to discover the correct binary directory (&quot;cups-config --serverbin&quot;).
+command can be used to discover the correct binary directory ("cups-config --serverbin").
 In addition, the CUPS_SERVERBIN environment variable can be used to override the default location of this directory - see the
 <strong>cups</strong>(1)
 
@@ -190,7 +190,7 @@ <h2 id="ippeveprinter-1.options">Options</h2>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-m </strong><em>model</em><br>
 Specifies the model name of the printer.
-The default is &quot;Printer&quot;.
+The default is "Printer".
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-n </strong><em>hostname</em><br>
 Specifies the hostname that is reported by the server.
@@ -209,12 +209,12 @@ <h2 id="ippeveprinter-1.options">Options</h2>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-r </strong><em>subtype[,subtype]</em><br>
 Specifies the DNS-SD subtype(s) to advertise.
 Separate multiple subtypes with a comma.
-The default is &quot;_print&quot;.
+The default is "_print".
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-s </strong><em>speed[,color-speed]</em><br>
 Specifies the printer speed in pages per minute.
 If two numbers are specified and the second number is greater than zero, the server will report support for color printing.
-The default is &quot;10,0&quot;.
+The default is "10,0".
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-v[vvv]</strong><br>
 Be (very) verbose when logging activity to standard error.
@@ -234,17 +234,17 @@ <h2 id="ippeveprinter-1.conforming-to">Conforming To</h2>
 </p>
     <h2 id="ippeveprinter-1.environment">Environment</h2>
 <p><strong>ippeveprinter</strong>
-adds environment variables starting with &quot;IPP_&quot; for all IPP Job attributes in the print request.
-For example, when executing a command for an IPP Job containing the &quot;media&quot; Job Template attribute, the &quot;IPP_MEDIA&quot; environment variable will be set to the value of that attribute.
+adds environment variables starting with "IPP_" for all IPP Job attributes in the print request.
+For example, when executing a command for an IPP Job containing the "media" Job Template attribute, the "IPP_MEDIA" environment variable will be set to the value of that attribute.
 </p>
-    <p>In addition, all IPP &quot;xxx-default&quot; and &quot;pwg-xxx&quot; Printer Description attributes are added to the environment.
-For example, the &quot;IPP_MEDIA_DEFAULT&quot; environment variable will be set to the default value for the &quot;media&quot; Job Template attribute.
+    <p>In addition, all IPP "xxx-default" and "pwg-xxx" Printer Description attributes are added to the environment.
+For example, the "IPP_MEDIA_DEFAULT" environment variable will be set to the default value for the "media" Job Template attribute.
 </p>
     <p>Enumerated values are converted to their keyword equivalents.
-For example, a &quot;print-quality&quot; Job Template attribute with a enum value of 3 will become the &quot;IPP_PRINT_QUALITY&quot; environment variable with a value of &quot;draft&quot;.
-This string conversion only happens for standard Job Template attributes, currently &quot;finishings&quot;, &quot;orientation-requested&quot;, and &quot;print-quality&quot;.
+For example, a "print-quality" Job Template attribute with a enum value of 3 will become the "IPP_PRINT_QUALITY" environment variable with a value of "draft".
+This string conversion only happens for standard Job Template attributes, currently "finishings", "orientation-requested", and "print-quality".
 </p>
-    <p>Finally, the &quot;CONTENT_TYPE&quot; environment variable contains the MIME media type of the document being printed, the &quot;DEVICE_URI&quot; environment variable contains the device URI as specified with the &quot;-D&quot; option, the &quot;OUTPUT_FORMAT&quot; environment variable contains the output MIME media type, and the &quot;PPD&quot; environment variable contains the PPD filename as specified with the &quot;-P&quot; option.
+    <p>Finally, the "CONTENT_TYPE" environment variable contains the MIME media type of the document being printed, the "DEVICE_URI" environment variable contains the device URI as specified with the "-D" option, the "OUTPUT_FORMAT" environment variable contains the output MIME media type, and the "PPD" environment variable contains the PPD filename as specified with the "-P" option.
 </p>
     <h2 id="ippeveprinter-1.command-output">Command Output</h2>
 <p>Unless they communicate directly with a printer, print commands send printer-ready data to the standard output.
@@ -255,41 +255,41 @@ <h2 id="ippeveprinter-1.command-output">Command Output</h2>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ATTR: </strong><em>attribute=value[ attribute=value]</em><br>
 Sets the named attribute(s) to the given values.
-Currently only the &quot;job-impressions&quot; and &quot;job-impressions-completed&quot; Job Status attributes and the &quot;marker-xxx&quot;, &quot;printer-alert&quot;, &quot;printer-alert-description&quot;, &quot;printer-supply&quot;, and &quot;printer-supply-description&quot; Printer Status attributes can be set.
+Currently only the "job-impressions" and "job-impressions-completed" Job Status attributes and the "marker-xxx", "printer-alert", "printer-alert-description", "printer-supply", and "printer-supply-description" Printer Status attributes can be set.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>DEBUG: </strong><em>Debugging message</em><br>
 Logs a debugging message if at least two -v's have been specified.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ERROR: </strong><em>Error message</em><br>
-Logs an error message and copies the message to the &quot;job-state-message&quot; attribute.
+Logs an error message and copies the message to the "job-state-message" attribute.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>INFO: </strong><em>Informational message</em><br>
-Logs an informational/progress message if -v has been specified and copies the message to the &quot;job-state-message&quot; attribute unless an error has been reported.
+Logs an informational/progress message if -v has been specified and copies the message to the "job-state-message" attribute unless an error has been reported.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>STATE: </strong><em>keyword[,keyword,...]</em><br>
-Sets the printer's &quot;printer-state-reasons&quot; attribute to the listed keywords.
+Sets the printer's "printer-state-reasons" attribute to the listed keywords.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>STATE: -</strong><em>keyword[,keyword,...]</em><br>
-Removes the listed keywords from the printer's &quot;printer-state-reasons&quot; attribute.
+Removes the listed keywords from the printer's "printer-state-reasons" attribute.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>STATE: +</strong><em>keyword[,keyword,...]</em><br>
-Adds the listed keywords to the printer's &quot;printer-state-reasons&quot; attribute.
+Adds the listed keywords to the printer's "printer-state-reasons" attribute.
 </p>
     <h2 id="ippeveprinter-1.examples">Examples</h2>
 <p>Run
 <strong>ippeveprinter</strong>
 with a service name of My Cool Printer:
 </p>
     <pre>
-    ippeveprinter &quot;My Cool Printer&quot;
+    ippeveprinter "My Cool Printer"
 </pre>
     <p>Run the
 <strong>file</strong>(1)
 
 command whenever a job is sent to the server:
 </p>
     <pre>
-    ippeveprinter -c /usr/bin/file &quot;My Cool Printer&quot;
+    ippeveprinter -c /usr/bin/file "My Cool Printer"
 </pre>
     <h2 id="ippeveprinter-1.see-also">See Also</h2>
 <p><strong>ippevepcl</strong>(7),

diff --git a/doc/ippfind.html b/doc/ippfind.html
@@ -16,7 +16,7 @@
   text-align: justify;
 }
 --></style>
-    <meta name="creator" content="mantohtml v2.0">
+    <meta name="creator" content="mantohtml v2022.1005">
     <title>Documentation</title>
   </head>
   <body>
@@ -95,7 +95,7 @@ <h3 id="ippfind-1.description.expressions">Expressions</h3>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-l</strong><br>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--ls</strong><br>
-Lists attributes returned by Get-Printer-Attributes for IPP printers and traditional <em>find</em> &quot;-ls&quot; output for HTTP URLs.
+Lists attributes returned by Get-Printer-Attributes for IPP printers and traditional <em>find</em> "-ls" output for HTTP URLs.
 The result is true if the URI is accessible, false otherwise.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--local</strong><br>
@@ -161,7 +161,7 @@ <h3 id="ippfind-1.description.expressions">Expressions</h3>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--exec </strong><em>utility </em>[ <em>argument </em>... ] <strong>;</strong><br>
 Executes the specified program if the current result is true.
-&quot;{foo}&quot; arguments are replaced with the corresponding value - see SUBSTITUTIONS below.
+"{foo}" arguments are replaced with the corresponding value - see SUBSTITUTIONS below.
 </p>
     <p>Expressions may also contain modifiers:
 </p>
@@ -182,30 +182,30 @@ <h3 id="ippfind-1.description.expressions">Expressions</h3>
 Logical OR of expressions.
 </p>
     <h3 id="ippfind-1.description.substitutions">Substitutions</h3>
-<p>The substitutions for &quot;{foo}&quot; in <em>-e</em> and <em>--exec</em> are:
+<p>The substitutions for "{foo}" in <em>-e</em> and <em>--exec</em> are:
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>{service_domain}</strong><br>
-Domain name, e.g., &quot;example.com.&quot;, &quot;local.&quot;, etc.
+Domain name, e.g., "example.com.", "local.", etc.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>{service_hostname}</strong><br>
-Fully-qualified domain name, e.g., &quot;printer.example.com.&quot;, &quot;printer.local.&quot;, etc.
+Fully-qualified domain name, e.g., "printer.example.com.", "printer.local.", etc.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>{service_name}</strong><br>
-Service instance name, e.g., &quot;My Fine Printer&quot;.
+Service instance name, e.g., "My Fine Printer".
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>{service_port}</strong><br>
 Port number for server, typically 631 for IPP and 80 for HTTP.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>{service_regtype}</strong><br>
-DNS-SD registration type, e.g., &quot;_ipp._tcp&quot;, &quot;_http._tcp&quot;, etc.
+DNS-SD registration type, e.g., "_ipp._tcp", "_http._tcp", etc.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>{service_scheme}</strong><br>
-URI scheme for DNS-SD registration type, e.g., &quot;ipp&quot;, &quot;http&quot;, etc.
+URI scheme for DNS-SD registration type, e.g., "ipp", "http", etc.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>{}</strong><br>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>{service_uri}</strong><br>
-URI for service, e.g., &quot;ipp://printer.local./ipp/print&quot;, &quot;<a href="http://printer.local./&quot;">http://printer.local./&quot;</a>, etc.
+URI for service, e.g., "ipp://printer.local./ipp/print", "<a href="http://printer.local./&quot;">http://printer.local./&quot;</a>, etc.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>{txt_</strong><em>key</em><strong>}</strong><br>
 Value of TXT record <em>key</em> (lowercase).
@@ -232,7 +232,7 @@ <h2 id="ippfind-1.options">Options</h2>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-V </strong><em>version</em><br>
 Specifies the IPP version when listing.
-Supported values are &quot;1.1&quot;, &quot;2.0&quot;, &quot;2.1&quot;, and &quot;2.2&quot;.
+Supported values are "1.1", "2.0", "2.1", and "2.2".
 </p>
     <h2 id="ippfind-1.exit-status">Exit Status</h2>
 <p><strong>ippfind</strong> returns 0 if the result for all processed expressions is true, 1 if the result of any processed expression is false, 2 if browsing or any query or resolution failed, 3 if an undefined option or invalid expression was specified, and 4 if it ran out of memory.
@@ -241,25 +241,25 @@ <h2 id="ippfind-1.environment">Environment</h2>
 <p>When executing a program, <strong>ippfind</strong> sets the following environment variables for the matching service registration:
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>IPPFIND_SERVICE_DOMAIN</strong><br>
-Domain name, e.g., &quot;example.com.&quot;, &quot;local.&quot;, etc.
+Domain name, e.g., "example.com.", "local.", etc.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>IPPFIND_SERVICE_HOSTNAME</strong><br>
-Fully-qualified domain name, e.g., &quot;printer.example.com.&quot;, &quot;printer.local.&quot;, etc.
+Fully-qualified domain name, e.g., "printer.example.com.", "printer.local.", etc.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>IPPFIND_SERVICE_NAME</strong><br>
-Service instance name, e.g., &quot;My Fine Printer&quot;.
+Service instance name, e.g., "My Fine Printer".
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>IPPFIND_SERVICE_PORT</strong><br>
 Port number for server, typically 631 for IPP and 80 for HTTP.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>IPPFIND_SERVICE_REGTYPE</strong><br>
-DNS-SD registration type, e.g., &quot;_ipp._tcp&quot;, &quot;_http._tcp&quot;, etc.
+DNS-SD registration type, e.g., "_ipp._tcp", "_http._tcp", etc.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>IPPFIND_SERVICE_SCHEME</strong><br>
-URI scheme for DNS-SD registration type, e.g., &quot;ipp&quot;, &quot;http&quot;, etc.
+URI scheme for DNS-SD registration type, e.g., "ipp", "http", etc.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>IPPFIND_SERVICE_URI</strong><br>
-URI for service, e.g., &quot;ipp://printer.local./ipp/print&quot;, &quot;<a href="http://printer.local./&quot;">http://printer.local./&quot;</a>, etc.
+URI for service, e.g., "ipp://printer.local./ipp/print", "<a href="http://printer.local./&quot;">http://printer.local./&quot;</a>, etc.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>IPPFIND_TXT_</strong><em>KEY</em><br>
 Values of TXT record <em>KEY</em> (uppercase).