summaryrefslogtreecommitdiff
path: root/doc/xmlif.xml
blob: 67062ab5d2b4b4e214de2909823405b4f153100f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
<?xml version='1.0'?> <!-- -*- xml -*- -->
<!DOCTYPE refentry PUBLIC
   "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id='xmlif'>
  <refentryinfo>
    <title>xmlif</title>
		<date>April 2009</date>
		<productname>Linux</productname>
    <author>
      <firstname>Eric</firstname>
      <othername role="initial">S.</othername>
      <surname>Raymond</surname>
			<affiliation>
        <address><email>esr@snark.thyrsus.com</email></address>
      </affiliation>
      <contrib>Author of xmlif program</contrib>
    </author>
  </refentryinfo>

  <refmeta>
    <refentrytitle>xmlif</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class='date'>Sept 26 2002</refmiscinfo>
  </refmeta>

  <refnamediv id='name'>
    <refname>xmlif</refname>
    <refpurpose>conditional processing instructions for XML</refpurpose>
  </refnamediv>

  <refsynopsisdiv id='synopsis'>
    <cmdsynopsis>
      <command>xmlif</command> <arg rep='repeat'>attrib=value</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id='description'><title>DESCRIPTION</title>

    <para><application>xmlif</application> filters XML according to
      conditionalizing markup.  This can be useful for formatting one
      of several versions of an XML document depending on conditions
      passed to the command.</para>

    <para>Attribute/value pairs from the command line are matched
      against the attributes associated with certain processing
      instructions in the document.  The instructions are
      <sgmltag>&lt;?xmlif if?&gt;</sgmltag> and its inverse <sgmltag>&lt;?xmlif if
      not?&gt;</sgmltag>, <sgmltag>&lt;?xmlif elif?&gt;</sgmltag> and its
      inverse <sgmltag>&lt;?xmlif elif not?&gt;</sgmltag>,
      <sgmltag>&lt;?xmlif else?&gt;</sgmltag>, and
      <sgmltag>&lt;?xmlif fi?&gt;</sgmltag>.</para>

    <para>Argument/value pairs given on the command line are checked
      against the value of corresponding attributes in the conditional
      processing instructions.  An `attribute match' happens if an
      attribute occurs in both the command-line arguments and the tag,
      and the values match.  An `attribute mismatch' happens if an
      attribute occurs in both the command-line arguments and the tag,
      but the values do not match.</para>

    <para>Spans between <sgmltag>&lt;?xmlif if?&gt;</sgmltag> or
      <sgmltag>&lt;?xmlif elif?&gt;</sgmltag> and the next conditional
      processing instruction at the same nesting level are passed
      through unaltered if there is at least one attribute match and
      no attribute mismatch; spans between <sgmltag>&lt;?xmlif if
      not?&gt;</sgmltag> and <sgmltag>&lt;?xmlif elif not?&gt;</sgmltag> and
      the next conditional processing instruction are passed
      otherwise.  Spans between <sgmltag>&lt;?xmlif else?&gt;</sgmltag> and
      the next conditional-processing tag are passed through only if
      no previous span at the same level has been passed
      through. <sgmltag>&lt;?xmlif if?&gt;</sgmltag> and
      <sgmltag>&lt;?xmlif fi?&gt;</sgmltag> (and their `not' variants) change
      the current nesting level; <sgmltag>&lt;?xmlif else?&gt;</sgmltag> and
      <sgmltag>&lt;?xmlif elif?&gt;</sgmltag> do not.</para>

    <para>All these processing instructions will be removed from the
      output produced. Aside from the conditionalization, all other
      input is passed through untouched; in particular, entity
      references are not resolved.</para>

    <para>Value matching is by string equality, except that "|" in an
      attribute value is interpreted as an alternation character.
      Thus, saying foo='red|blue' on the command line enables
      conditions red and blue.  Saying color='black|white' in a tag
      matches command-line conditions color='black' and
      color='white'.</para>

    <para>Here is an example:

<programlisting>
Always issue this text.
&lt;?xmlif if condition='html'?&gt;
Issue this text if 'condition=html' is given on the command line.
&lt;?xmlif elif condition='pdf|ps'?&gt;
Issue this text if 'condition=pdf' or 'condition=ps'
is given on the command line.
&lt;?xmlif else?&gt;
Otherwise issue this text.
&lt;?xmlif fi?&gt;
Always issue this text.
</programlisting></para>

  </refsect1>

</refentry>