ipptoolfile man page: Document method to reference collection members and logical operators for predicates

[wifiprintguy]

(Moved here from istopwg/ippsample Issue #274 (istopwg/ippsample#274)

The man page for ipptoolfile doesn't seem to clearly include a description of how a test can reference a particular member within a collection, nor does it document what logical operators can be used for the values.

For members of a collection, a "path" is used, like so:

EXPECT finishings-col/baling OF-TYPE collection

It also isn't clear what logical operators the author of a .test file could use in a predicate. For instance, they might want to include an EXPECT directive like so:

EXPECT uri-authentication-supported OF-TYPE keyword IN-GROUP printer-attributes-tag WITH-VALUE 'basic' | 'certificate' | 'digest' | 'negotiate' | 'OAuth 2.0'

(If the latter isn't possible then I'll file a separate enhancement request...)

[michaelrsweet]

OK, so the current man page already says:

Attribute names can specify member attributes by separating the attribute and member names with the forward slash, for example "media-col/media-size/x-dimension".

But I've added an examples section at the bottom of the ipptoolfile man page:

EXAMPLES

Query the "foo-default" and "foo-supported" Printer Description attributes and validate that all of its values are 'bar', 'baz', or 'none':

{
  NAME "Validate 'foo' Attribute"
  OPERATION Get-Printer-Attributes
  GROUP operation-attributes-tag
  ATTR charset attributes-charset utf-8
  ATTR language attributes-natural-language en
  ATTR uri printer-uri $uri
  ATTR keyword requested-attributes media-col-ready
  EXPECT foo-default OF-TYPE keyword IN-GROUP printer-attributes-tag
      COUNT 1 WITH-VALUE "/^(bar|baz|none)$$/"
  EXPECT foo-supported OF-TYPE keyword IN-GROUP printer-attributes-tag
      WITH-ALL-VALUES "/^(bar|baz|none)$$/"
}

Query the "media-col-ready" Printer Status attribute and validate that the collection values contain "media-size" and "media-source" member attributes:

{
  NAME "Validate 'foo' Attribute"
  OPERATION Get-Printer-Attributes
  GROUP operation-attributes-tag
  ATTR charset attributes-charset utf-8
  ATTR language attributes-natural-language en
  ATTR uri printer-uri $uri
  ATTR keyword requested-attributes foo-default,foo-supported
  EXPECT media-col-ready OF-TYPE collection IN-GROUP printer-attributes-tag
  EXPECT-ALL media-col-ready/media-size OF-TYPE collection COUNT 1
  EXPECT-ALL media-col-ready/media-size/x-dimension OF-TYPE integer(1:MAX) COUNT 1
  EXPECT-ALL media-col-ready/media-size/y-dimension OF-TYPE integer(0:MAX) COUNT 1
  EXPECT-ALL media-col-ready/media-source OF-TYPE keyword|name COUNT 1
}

[michaelrsweet]

[master 606e9cc] Add examples to ipptoolfile man page (Issue #32)