<?xml version="1.0" encoding="UTF-8"?>
<topic version="5.2" xml:id="filtering" xmlns="http://docbook.org/ns/docbook">
  <info>
    <title>About filtering</title>
  </info>

  <itemizedlist>
    <listitem>
      <para>Element <tag class="element">filterin</tag> is best explained by
      an example:</para>

      <programlisting>&lt;module resourceref="MyTopic"/&gt;
&lt;filterin os="mac" userlevel="beginner;intermediate"/&gt;</programlisting>

      <para>The above example means: <emphasis>exclude</emphasis> from the
      contents of realized topic <tag class="attvalue">MyTopic</tag> all the
      elements having a <tag class="attribute">os</tag> attribute not
      containing <tag class="attvalue">mac</tag> and also exclude all the
      elements having a <tag class="attribute">userlevel</tag> attribute not
      containing <tag class="attvalue">beginner</tag> or <tag
      class="attvalue">intermediate</tag>.</para>

      <para>For those who know the <link
      xlink:href="http://docbook.sourceforge.net/release/xsl/current/doc/"
      xmlns:xlink="http://www.w3.org/1999/xlink">DocBook XSL
      stylesheets</link>, this is equivalent to passing parameters
      <literal>profile.os=mac</literal> and
      <literal>profile.userlevel=beginner;intermediate</literal> to the
      profiling stylesheets.</para>

      <para>For example, if resource <tag class="attvalue">MyTopic</tag>
      points to a topic containing:</para>

      <programlisting>&lt;para xml:id="p1" os="windows"&gt;Paragraph #1.&lt;/para&gt;
&lt;para xml:id="p2" os="mac;linux"&gt;Paragraph #2.&lt;/para&gt;
&lt;para xml:id="p3" userlevel="advanced;expert"&gt;Paragraph #3.&lt;/para&gt;
&lt;para xml:id="p4" userlevel="intermediate;advanced"&gt;Paragraph #4.&lt;/para&gt;</programlisting>

      <para>then paragraph <tag class="attvalue">p1</tag> and <tag
      class="attvalue">p3</tag> are excluded from the realized document while
      paragraphs <tag class="attvalue">p2</tag> and <tag
      class="attvalue">p4</tag> are not.</para>
    </listitem>

    <listitem>
      <para>Element <tag class="element">filterout</tag> is best explained by
      an example:</para>

      <programlisting>&lt;module resourceref="MyTopic"/&gt;
&lt;filterout os="mac" userlevel="beginner;intermediate"/&gt;</programlisting>

      <para>The above example means: exclude from the contents of realized
      topic <tag class="attvalue">MyTopic</tag> all the elements having a <tag
      class="attribute">os</tag> attribute containing <tag
      class="attvalue">mac</tag> and no other value and also exclude all the
      elements having a <tag class="attribute">userlevel</tag> attribute
      containing <tag class="attvalue">beginner</tag> and/or <tag
      class="attvalue">intermediate</tag> and no other value.</para>

      <para>For example, if resource <tag class="attvalue">MyTopic</tag>
      points to a topic containing:</para>

      <programlisting>&lt;para xml:id="p1" os="mac"&gt;Paragraph #1.&lt;/para&gt;
&lt;para xml:id="p2" os="mac;linux"&gt;Paragraph #2.&lt;/para&gt;
&lt;para xml:id="p3" userlevel="beginner"&gt;Paragraph #3.&lt;/para&gt;
&lt;para xml:id="p4" userlevel="intermediate;advanced"&gt;Paragraph #4.&lt;/para&gt;</programlisting>

      <para>then paragraph <tag class="attvalue">p1</tag> and <tag
      class="attvalue">p3</tag> are excluded from the realized document while
      paragraphs <tag class="attvalue">p2</tag> and <tag
      class="attvalue">p4</tag> are not.</para>
    </listitem>

    <listitem>
      <para>It's possible to have both <tag class="element">filterin</tag> and
      <tag class="element">filterout</tag> elements for the same effectivity
      attribute. Example:</para>

      <programlisting>&lt;module resourceref="MyTopic"/&gt;
&lt;filterin os="windows;mac"/&gt;
&lt;filterout os="linux"/&gt;</programlisting>

      <para>For example, if resource <tag class="attvalue">MyTopic</tag>
      points to a topic containing:</para>

      <programlisting>&lt;para xml:id="p1" os="linux"&gt;Paragraph #1.&lt;/para&gt;
&lt;para xml:id="p2" os="mac;linux"&gt;Paragraph #2.&lt;/para&gt;
&lt;para xml:id="p3" os="android"&gt;Paragraph #3.&lt;/para&gt;
&lt;para xml:id="p4" os="android;windows"&gt;Paragraph #4.&lt;/para&gt;
&lt;para xml:id="p5" os="android;linux"&gt;Paragraph #5.&lt;/para&gt;</programlisting>

      <para>then paragraph <tag class="attvalue">p1</tag>, <tag
      class="attvalue">p3</tag> and <tag class="attvalue">p5</tag> are
      excluded from the realized document while paragraphs <tag
      class="attvalue">p2</tag> and <tag class="attvalue">p4</tag> are
      not.</para>
    </listitem>

    <listitem>
      <para>Just like <tag class="element">output</tag> elements, <tag
      class="element">filterin</tag> and <tag class="element">filterout</tag>
      elements are considered in order and relevant filters are combined. A
      <tag class="element">filterin</tag> or <tag
      class="element">filterout</tag> element is relevant if it does not have
      an <tag class="element">outputformat</tag> attribute or if its <tag
      class="element">outputformat</tag> attribute matches the output format
      passed as a parameter to the assembly processor.</para>
    </listitem>

    <listitem>
      <para>The sequence of <tag class="element">filterin</tag> and <tag
      class="element">filterout</tag> elements “inherited” from ancestor <tag
      class="element">structure</tag> and <tag class="element">module</tag>s
      and/or directly added to a <tag class="element">module</tag> is combined
      to form a single <tag class="element">filterin</tag> element and a
      single <tag class="element">filterout</tag> element. The resulting
      single <tag class="element">filterin</tag> element and single <tag
      class="element">filterout</tag> element are applied to the <tag
      class="element">module</tag>. Example:</para>

      <programlisting>&lt;filterin os="windows"/&gt;
&lt;filterout userlevel="beginner;intermediate"/&gt;
&lt;filterin os="mac;linux"/&gt;
&lt;filterout os="linux"/&gt;
&lt;filterin userlevel="intermediate;advanced"/&gt;</programlisting>

      <para>The above sequence is equivalent to:</para>

      <programlisting>&lt;filterin os="windows;mac" userlevel="intermediate;advanced"/&gt;
&lt;filterout os="linux" userlevel="beginner"/&gt;</programlisting>
    </listitem>
  </itemizedlist>
</topic>
