s1kd-appcheck(1)                  s1kd-tools                  s1kd-appcheck(1)

NAME
      s1kd-appcheck - Validate applicability of S1000D CSDB objects

SYNOPSIS
             s1kd-appcheck [options] [<object>...]

DESCRIPTION
      The  s1kd-appcheck  tool validates the applicability of S1000D CSDB ob‐
      jects, detecting potential errors that could occur when the  object  is
      filtered.

      By  default,  the tool validates an object against only the product at‐
      tribute and condition values which are explicitly used within  the  ob‐
      ject.   The products check (-t) and full check (-a) modes allow objects
      to be checked for issues with implicit applicability, that is,  product
      attribute  or  condition values which are not explicitly used within an
      object, but may still affect it.

      The s1kd-instance and s1kd-validate tools are used by default  to  per‐
      form the actual validation.

OPTIONS
      -A, --act <file>
             Specify  the  ACT to read product attributes from, and to use to
             find the CCT or PCT.  This will override the ACT reference with‐
             in the individual objects being validated.

      -a, --all
             Validate  objects  against all possible combinations of relevant
             product attribute and condition values as defined in the ACT and
             CCT.   Relevant product attributes and conditions are those that
             are used by an object with any value.

      -b, --brexcheck
             Validate objects with a BREX  check  (using  the  s1kd-brexcheck
             tool) in addition to the schema check.

      -C, --cct <file>
             Specify the CCT to read conditions from.  This will override the
             CCT reference within the ACT.

      -c, --custom
             Perform a customized check.  The default standalone applicabili‐
             ty check is disabled.  This can then be combined with the -s op‐
             tion, to only check that all product attributes  and  conditions
             are  defined  in the ACT and CCT respectively, and/or the -n op‐
             tion, to only check nested applicability annotations.   If  nei‐
             ther  of  these  options  are  specified, no checks will be per‐
             formed.

      -D, --duplicate
             Check for duplicate annotations.

      -d, --dir <dir>
             The directory to start searching for  ACT/CCT/PCT  data  modules
             in.  By default, the current directory is used.

      -e, --exec <cmd>
             The commands used to validate objects.  Multiple commands can be
             used by specifying this option multiple times.  The objects will
             be  passed  to each command on stdin, and the exit status of the
             command will be used to determine if the object is valid (with a
             non-zero  exit status indicating it is invalid).  This overrides
             the default commands (s1kd-validate, and s1kd-brexcheck if -b is
             specified).

      -F, --valid-filenames
             Print the filenames of valid objects.

      -f, --filenames
             Print the filenames of invalid objects.

      -h, -?, --help
             Show help/usage message.

      -K, --filter <cmd>
             The command used to filter objects prior to validation.  The ob‐
             jects will be passed to the command on stdin,  and  the  filters
             will   be   supplied   as   arguments   in   the   form  of  "-s
             <ident>:<type>=<value>".  This  overrides  the  default  command
             (s1kd-instance).

      -k, --args <args>
             The arguments to the filter command when filtering objects prior
             to validation.

      -l, --list
             Treat input as a list of CSDB objects to validate.

      -N, --omit-issue
             Assume that the issue/inwork numbers  are  omitted  from  object
             filenames (they were created with the -N option).

      -n, --nested
             Check  that  all  product attribute and condition values used in
             nested applicability annotations are subsets of the values  used
             in their parents.

      -o, --output-valid
             Output valid CSDB objects to stdout.

      -P, --pct <file>
             Specify the PCT to read product instances from.  This will over‐
             ride the PCT reference in the ACT.

      -p, --progress
             Display a progress bar.

      -q, --quiet
             Quiet mode.  Error messages will not be printed.

      -R, --redundant
             Check for redundant annotations.

      -r, --recursive
             Search for the ACT/CCT/PCT recursively.

      -s, --strict
             Check whether product attributes and conditions used by  an  ob‐
             ject are declared in the ACT and CCT respectively.

      -T, --summary
             Print  a summary of the check after it completes, including sta‐
             tistics on the number of objects that passed/failed the check.

      -t, --products
             Validate objects against the defined  product  instances  within
             the PCT.

      -v, --verbose
             Verbose output.  Specify multiple times to increase the verbosi‐
             ty.

      -x, --xml
             Print an XML report of the check.

      -~, --dependencies
             Check with CCT dependency tests added to  assertions  which  use
             the dependant values.

      -^, --remove-deleted
             Validate  objects  with  elements  that  have  a  change type of
             "delete" removed.

      --version
             Show version information.

      --zenity-progress
             Print progress information in the zenity --progress format.

      <object>...
             Object(s) to validate.

      In addition, the following options allow configuration of the XML pars‐
      er:

      --dtdload
             Load the external DTD.

      --huge Remove any internal arbitrary parser limits.

      --net  Allow network access to load external DTD and entities.

      --noent
             Resolve entities.

      --parser-errors
             Emit errors from parser.

      --parser-warnings
             Emit warnings from parser.

      --xinclude
             Do XInclude processing.

      --xml-catalog <file>
             Use  an  XML catalog when resolving entities.  Multiple catalogs
             may be loaded by specifying this option multiple times.

EXIT STATUS
      0      The check completed successfully,  and  all  CSDB  objects  were
             valid.

      1      The check completed successfully, but some CSDB objects were in‐
             valid.

      2      One or more CSDB objects could not be read.

      3      The number of CSDB objects specified exceeded the available mem‐
             ory.

      4      The commands used to filter and/or validate objects failed to be
             executed.

EXAMPLES
  Standalone validation
      Consider the following data module snippet:

             <dmodule>
             ...
             <applic>
             <displayText>
             <simplePara>Version: A or Version: B</simplePara>
             </displayText>
             <evaluate andOr="or">
             <assert
             applicPropertyIdent="version"
             applicPropertyType="prodattr"
             applicPropertyValues="A"/>
             <assert
             applicPropertyIdent="version"
             applicPropertyType="prodattr"
             applicPropertyValues="B"/>
             </evaluate>
             </applic>
             ...
             <referencedApplicGroup>
             <applic id="app-VersionB">
             <assert applicPropertyIdent="version" applicPropertyType="prodattr"
             applicPropertyValues="B"/>
             </applic>
             </referencedApplicGroup>
             ...
             <levelledPara id="par-0001" applicRefId="app-VersionB">
             <title>Features of version B</title>
             <para>...</para>
             </levelledPara>
             ...
             <levelledPara>
             <title>More information</title>
             <para>...</para>
             <para>Refer to <internalRef internalRefId="par-0001"/>.</para>
             </levelledPara>
             ...
             </dmodule>

      There are two versions of the product, A and B, and the data module  is
      meant to apply to both.

      By itself, the data module is valid:

             $ s1kd-validate -v <DM>
             s1kd-validate: SUCCESS: <DM> validates against schema <url>

      Checking it with this tool, however, reveals an issue:

             $ s1kd-appcheck <DM>
             s1kd-appcheck: ERROR: <DM> is invalid when:
             s1kd-appcheck: ERROR:   prodattr version = A

      When  the  data  module  is  filtered for version A, the first levelled
      paragraph will be removed, which causes the reference to it in the sec‐
      ond levelled paragraph to become broken.

  Full validation
      Consider the following data module snippet:

             <dmodule>
             ...
             <applic>
             <displayText>
             <simplePara>All</simplePara>
             </displayText>
             </applic>
             ...
             <referencedApplicGroup>
             <applic id="app-IcyOrHot">
             <evaluate andOr="or">
             <assert
             applicPropertyIdent="weather"
             applicPropertyType="condition"
             applicPropertyValues="Icy"/>
             <assert
             applicPropertyIdent="weather"
             applicPropertyType="condition"
             applicPropertyValues="Hot"/>
             </applic>
             </referencedApplicGroup>
             ...
             <proceduralStep>
             <para>Locate the handle.</para>
             </proceduralStep>
             <proceduralStep id="stp-0001" applicRefId="app-IcyOrHot">
             <para>Put on gloves prior to touching the handle.</para>
             </proceduralStep>
             <proceduralStep>
             <para>Grab the handle and turn it clockwise.</para>
             </proceduralStep>
             ...
             <proceduralStep>
             <para>Remove the gloves you put on in <internalRef internalRefId="stp-0001"/>.</para>
             </proceduralStep>
             ...
             </dmodule>

      Once again, this data module is valid by itself:

             $ s1kd-validate -v <DM>
             s1kd-validate: SUCCESS: <DM> validates against schema <url>

      This  time,  however, it also initially appears valid when this tool is
      used:

             $ s1kd-appcheck -v <DM>
             s1kd-appcheck: SUCCESS: <DM> passed the applicability check.

      However, now consider this snippet from the CCT:

             <condCrossRefTable>
             ...
             <condType id="weatherType">
             <name>Weather type</name>
             <descr>Possible types of weather conditions.</descr>
             <enumeration applicPropertyValues="Normal"/>
             <enumeration applicPropertyValues="Icy"/>
             <enumeration applicPropertyValues="Hot"/>
             </condType>
             ...
             <cond id="weather" condTypeRefId="weatherType">
             <name>Weather</name>
             <descr>The current weather conditions.</descr>
             </cond>
             ...
             </condCrossRefTable>

      There is a third value for the weather condition which is not explicit‐
      ly  used  within  the  data module, and therefore will not be validated
      against in the default standalone check.  When weather has a  value  of
      Normal,  the  cross-reference in the last step in the example above be‐
      comes broken.

      To catch errors with implicit applicability, the full check (-a) can be
      used  instead, which reads the values to check not from the data module
      itself, but from the ACT and CCT referenced by the data module:

             $ s1kd-appcheck -a <DM>
             s1kd-appcheck: ERROR: <DM> is invalid when:
             s1kd-appcheck: ERROR:   condition weather = Normal

      This can also be fixed by making the applicability of the  data  module
      explicit:

             <applic>
             <displayText>
             <simplePara>Weather: Normal or Weather: Icy or
             Weather: Hot</simplePara>
             </displayText>
             <evaluate andOr="or">
             <assert
             applicPropertyIdent="weather"
             applicPropertyType="condition"
             applicPropertyValues="Normal"/>
             <assert
             applicPropertyIdent="weather"
             applicPropertyType="condition"
             applicPropertyValues="Icy"/>
             <assert
             applicPropertyIdent="weather"
             applicPropertyType="condition"
             applicPropertyValues="Hot"/>
             </evaluate>
             </applic>

      In which case, the standalone check will now also detect the error:

             $ s1kd-appcheck <DM>
             s1kd-appcheck: ERROR: <DM> is invalid when:
             s1kd-appcheck: ERROR:   condition weather = Normal

  Nested applicability annotations
      Consider the following data module snippet:

             <dmodule>
             ...
             <applic>
             <displayText>
             <simplePara>Version: A, B</simplePara>
             </displayText>
             <assert
             applicPropertyIdent="version"
             applicPropertyType="prodattr"
             applicPropertyValues="A"/>
             <assert
             applicPropertyIdent="version"
             applicPropertyType="prodattr"
             applicPropertyValues="B"/>
             </applic>
             ...
             <referencedApplicGroup>
             <applic id="app-C">
             <displayText>
             <simplePara>Version: C</simplePara>
             </displayText>
             <assert
             applicPropertyIdent="version"
             applicPropertyType="prodattr"
             applicPropertyValues="C"/>
             </applic>
             </referencedApplicGroup>
             ...
             <proceduralStep>
             <para>Step A</para>
             </proceduralStep>
             <proceduralStep applicRefId="app-C">
             <para>Step B</para>
             </proceduralStep>
             <proceduralStep>
             <para>Step C</para>
             </proceduralStep>
             ...
             </dmodule>

      Here,  the  whole data module is applicable to versions A and B, but an
      individual step has been made applicable to version C.  Normally,  this
      is  not  reported as an error, since the removal of this step would not
      cause the data module to become invalid:

             $ s1kd-appcheck -v <DM>
             s1kd-appcheck: SUCCESS: <DM> passed the applicability check

      However, the content is essentially useless, since it  will  never  ap‐
      pear.   The  -n option will report when the applicability of an element
      is incompatible with the applicability of any parent  elements  or  the
      whole object:

             $ s1kd-appcheck -n <DM>
             s1kd-appcheck: ERROR: <DM>: proceduralStep on line 62 is applicable
             when prodattr version = C, which is not a subset of the applicability
             of the whole object.

  Redundant applicability annotations
      Consider the following data module snippet:

             <proceduralStep applicRefId="app-A">
             <para>Step A</para>
             <figure applicRefId="app-A">
             ...
             </figure>
             </proceduralStep>

      This  is  technically  correct, but the annotation on the figure can be
      considered redundant, since it has the same applicability as its ances‐
      tor,  and  the  applicability of an element is already inherited by all
      its descendants automatically.

      The -R (--redundant) option will report when  the  applicability  of  a
      nested element is redundant:

             $ s1kd-appcheck -R <DM>
             s1kd-appcheck: ERROR: <DM>: figure on line 85 has the same
             applicability as its parent proceduralStep on line 83 (app-A)

      Currently, this check only detects when the exact same annotation (with
      the same ID) is nested within itself.  In the future, this should  also
      detect redundant logic between different nested annotations.

  Duplicate applicability annotations
      Consider the following data module snippet:

             <referencedApplicGroup>
             <applic id="app-0001">
             <assert applicPropertyIdent="version" applicPropertyType="prodattr" applicPropertyValues="A"/>
             </applic>
             <applic id="app-0002">
             <assert applicPropertyIdent="version" applicPropertyType="prodattr" applicPropertyValues="A"/>
             </referencedApplicGroup>

      These  annotations have duplicate logic, meaning only one is necessary.
      The -D (--duplicate) option will report when an  applicability  annota‐
      tion is a duplicate of another annotation:

             $ s1kd-appcheck -D <DM>
             s1kd-appcheck: ERROR: <DM>: Annotation on line 47 is a duplicate of annotation on line 24.

AUTHORS
      khzae.net.

                                 2024-04-01                  s1kd-appcheck(1)

You are viewing proxied material from khzae.net. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.