doc/yp2.xml.in

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                     "@DTD_DIR@/docbookx.dtd" [
   4         <!ENTITY oslash "&#x00F8;"> <!-- CIRCLED DIVISION SLASH -->
   5 ]>
   6 <!-- $Id: yp2.xml.in,v 1.1 2006-02-02 18:22:47 mike Exp $ -->
   7 <book id="yp2">
   8  <bookinfo>
   9   <title>YP2 - User's Guide and Reference</title>
  10   <author>
  11    <firstname>Mike</firstname><surname>Taylor</surname>
  12   </author>
  13   <copyright>
  14    <year>2006</year>
  15    <holder>Index Data</holder>
  16   </copyright>
  17   <abstract>
  18    <simpara>
  19     ###
  20     YP2 is ... in need of description :-)
  21    </simpara>
  22   </abstract>
  23  </bookinfo>
  24
  25
  26
  27  <chapter id="introduction">
  28   <title>Introduction</title>
  29
  30
  31   <section>
  32    <title>Overview</title>
  33    <para>
  34     <ulink url="http://indexdata.dk/yp2/">YP2</ulink>
  35     is extremely cool.
  36    </para>
  37    <para>
  38     ### We should probably consider saying a little more by way of
  39     introduction.
  40    </para>
  41   </section>
  42  </chapter>
  43
  44
  45
  46  <chapter id="filters">
  47   <title>Filters</title>
  48
  49
  50   <section>
  51    <title>Introductory notes</title>
  52    <para>
  53     It's useful to think of YP2 as an interpreter providing a small
  54     number of primitives and operations, but operating on a very
  55     complex data type, namely the ``package''.
  56    </para>
  57    <para>
  58     A package represents a Z39.50 or SRW/U request (whether for Init,
  59     Search, Scan, etc.)  together with information about where it came
  60     from.  Packages are created by front-end filters such as
  61     <literal>frontend_net</literal> (see below), which reads them from
  62     the network; other front-end filters are possible.  They then pass
  63     along a route consisting of a sequence of filters, each of which
  64     transforms the package and may also have side-effects such as
  65     generating logging.  Eventually, the route will yield a response,
  66     which is sent back to the origin.
  67    </para>
  68    <para>
  69     There are many kinds of filter: some that are defined statically
  70     as part of YP2, and other that may be provided by third parties
  71     and dynamically loaded.  They all conform to the same simple API
  72     of essentially two methods: <function>configure()</function> is
  73     called at startup time, and is passed a DOM tree representing that
  74     part of the configuration file that pertains to this filter
  75     instance: it is expected to walk that tree extracting relevant
  76     information; and <function>process()</function> is called every
  77     time the filter has to processes a package.
  78    </para>
  79    <para>
  80     While all filters provide the same API, there are different modes
  81     of functionality.  Some filters are sources: they create
  82     packages
  83     (<literal>frontend_net</literal>);
  84     others are sinks: they consume packages and return a result
  85     (<literal>z3950_client</literal>,
  86     <literal>backend_test</literal>,
  87     <literal>http_file</literal>);
  88     the others are true filters, that read, process and pass on the
  89     packages they are fed
  90     (<literal>auth_simple</literal>,
  91     <literal>log</literal>,
  92     <literal>multi</literal>,
  93     <literal>session_shared</literal>,
  94     <literal>template</literal>,
  95     <literal>virt_db</literal>).
  96    </para>
  97   </section>
  98
  99
 100   <section>
 101    <title>Individual filters</title>
 102    <para>
 103     The filters are here named by the string that is used as the
 104     <literal>type</literal> attribute of a
 105     <literal>&lt;filter&gt;</literal> element in the configuration
 106     file to request them, with the name of the class that implements
 107     them in parentheses.
 108    </para>
 109
 110    <section>
 111     <title><literal>auth_simple</literal>
 112         (yp2::filter::AuthSimple)</title>
 113     <para>
 114      Simple authentication and authorisation.  The configuration
 115      specifies the name of a file that is the user register, which
 116      lists <varname>username</varname>:<varname>password</varname>
 117      pairs, one per line, colon separated. When a session begins, it
 118      is rejected unless username and passsword are supplied, and match
 119      a pair in the register.
 120     </para>
 121     <para>
 122      ### discuss authorisation phase
 123     </para>
 124    </section>
 125
 126    <section>
 127     <title><literal>backend_test</literal>
 128         (yp2::filter::Backend_test)</title>
 129     <para>
 130      A sink that provides dummy responses in the manner of the
 131      <literal>yaz-ztest</literal> Z39.50 server.  This is useful only
 132      for testing.
 133     </para>
 134    </section>
 135
 136    <section>
 137     <title><literal>frontend_net</literal>
 138         (yp2::filter::FrontendNet)</title>
 139     <para>
 140      A source that accepts Z39.50 and SRW connections from a port
 141      specified in the configuration, reads protocol units, and
 142      feeds them into the next filter, eventually returning the
 143      result to the origin.
 144     </para>
 145    </section>
 146
 147    <section>
 148     <title><literal>http_file</literal>
 149         (yp2::filter::HttpFile)</title>
 150     <para>
 151      A sink that returns the contents of files from the local
 152      filesystem in response to HTTP requests.  (Yes, Virginia, this
 153      does mean that YP2 is also a Web-server in its spare time.  So
 154      far it does not contain either an email-reader or a Lisp
 155      interpreter, but that day is surely coming.)
 156     </para>
 157    </section>
 158
 159    <section>
 160     <title><literal>log</literal>
 161         (yp2::filter::Log)</title>
 162     <para>
 163      Writes logging information to standard output, and passes on
 164      the package unchanged.
 165     </para>
 166    </section>
 167
 168    <section>
 169     <title><literal>multi</literal>
 170         (yp2::filter::Multi)</title>
 171     <para>
 172      Performs multicast searching.  See the extended discussion of
 173      multi-database searching below.
 174     </para>
 175    </section>
 176
 177    <section>
 178     <title><literal>session_shared</literal>
 179         (yp2::filter::SessionShared)</title>
 180     <para>
 181      When this is finished, it will implement global sharing of
 182      result sets (i.e. between threads and therefore between
 183      clients), but it's not yet done.
 184     </para>
 185    </section>
 186
 187    <section>
 188     <title><literal>template</literal>
 189         (yp2::filter::Template)</title>
 190     <para>
 191      Does nothing at all, merely passing the packet on.  (Maybe it
 192      should be called <literal>nop</literal> or
 193      <literal>passthrough</literal>?)  This exists not to be used, but
 194      to be copied - to become the skeleton of new filters as they are
 195      written.
 196     </para>
 197    </section>
 198
 199    <section>
 200     <title><literal>virt_db</literal>
 201         (yp2::filter::Virt_db)</title>
 202     <para>
 203      Performs virtual database selection.  See the extended discussion
 204      of virtual databases below.
 205     </para>
 206    </section>
 207
 208    <section>
 209     <title><literal>z3950_client</literal>
 210         (yp2::filter::Z3950Client)</title>
 211     <para>
 212      Performs Z39.50 searching and retrieval by proxying the
 213      packages that are passed to it.  Init requests are sent to the
 214      address specified in the <literal>VAL_PROXY</literal> otherInfo
 215      attached to the request: this may have been specified by client,
 216      or generated by a <literal>virt_db</literal> filter earlier in
 217      the route.  Subsequent requests are sent to the same address,
 218      which is remembered at Init time in a Session object.
 219     </para>
 220    </section>
 221   </section>
 222
 223
 224   <section>
 225    <title>Future directions</title>
 226    <para>
 227     Some other filters that do not yet exist, but which would be
 228     useful, are briefly described.  These may be added in future
 229     releases.
 230    </para>
 231
 232    <variablelist>
 233     <varlistentry>
 234      <term><literal>frontend_cli</literal> (source)</term>
 235      <listitem>
 236       <para>
 237        Command-line interface for generating requests.
 238       </para>
 239      </listitem>
 240     </varlistentry>
 241     <varlistentry>
 242      <term><literal>srw2z3950</literal> (filter)</term>
 243      <listitem>
 244       <para>
 245        Translate SRW requests into Z39.50 requests.
 246       </para>
 247      </listitem>
 248     </varlistentry>
 249     <varlistentry>
 250      <term><literal>srw_client</literal> (sink)</term>
 251      <listitem>
 252       <para>
 253        SRW searching and retrieval.
 254       </para>
 255      </listitem>
 256     </varlistentry>
 257     <varlistentry>
 258      <term><literal>sru_client</literal> (sink)</term>
 259      <listitem>
 260       <para>
 261        SRU searching and retrieval.
 262       </para>
 263      </listitem>
 264     </varlistentry>
 265     <varlistentry>
 266      <term><literal>opensearch_client</literal> (sink)</term>
 267      <listitem>
 268       <para>
 269        A9 OpenSearch searching and retrieval.
 270       </para>
 271      </listitem>
 272     </varlistentry>
 273    </variablelist>
 274   </section>
 275  </chapter>
 276
 277
 278
 279  <chapter id="configuration">
 280   <title>Configuration: the YP2 configuration file format</title>
 281
 282
 283   <section>
 284    <title>Introductory notes</title>
 285    <para>
 286     If YP2 is an interpreter providing operations on packages, then
 287     its configuration file can be thought of as a program for that
 288     interpreter.  Configuration is by means of a single file, the name
 289     of which is supplied as the sole command-line argument to the
 290     <command>yp2</command> program.
 291    </para>
 292    <para>
 293     The configuration files are written in XML.  (But that's just an
 294     implementation detail - they could just as well have been written
 295     in YAML or Lisp-like S-expressions, or in a custom syntax.)
 296    </para>
 297    <para>
 298     Since XML has been chosen, an XML schema,
 299     <filename>config.xsd</filename>, is provided for validating
 300     configuration files.  This file is supplied in the
 301     <filename>etc</filename> directory of the YP2 distribution.  It
 302     can be used by (among other tools) the <command>xmllint</command>
 303     program supplied as part of the <literal>libxml2</literal>
 304     distribution:
 305    </para>
 306    <screen>
 307         xmllint --noout --schema etc/config.xsd my-config-file.xml
 308    </screen>
 309    <para>
 310     (A recent version of <literal>libxml2</literal> is required, as
 311     support for XML Schemas is a relatively recent addition.)
 312    </para>
 313   </section>
 314
 315   <section>
 316    <title>Overview of XML structure</title>
 317    <para>
 318     All elements and attributes are in the namespace
 319     <ulink url="http://indexdata.dk/yp2/config/1"/>.
 320     This is most easily achieved by setting the default namespace on
 321     the top-level element, as here:
 322    </para>
 323    <screen>
 324         &lt;yp2 xmlns="http://indexdata.dk/yp2/config/1"&gt;
 325    </screen>
 326    <para>
 327     The top-level element is &lt;yp2&gt;.  This contains a
 328     &lt;start&gt; element, a &lt;filters&gt; element and a
 329     &lt;routes&gt; element, in that order.  &lt;filters&gt; is
 330     optional; the other two are mandatory.  All three are
 331     non-repeatable.
 332    </para>
 333    <para>
 334     The &lt;start&gt; element is empty, but carries a
 335     <literal>route</literal> attribute, whose value is the name of
 336     route at which to start running - analogouse to the name of the
 337     start production in a formal grammar.
 338    </para>
 339    <para>
 340     If present, &lt;filters&gt; contains zero or more &lt;filter&gt;
 341     elements; filters carry a <literal>type</literal> attribute and
 342     contain various elements that provide suitable configuration for
 343     filters of that type.  The filter-specific elements are described
 344     below.  Filters defined in this part of the file must carry an
 345     <literal>id</literal> attribute so that they can be referenced
 346     from elsewhere.
 347    </para>
 348    <para>
 349     &lt;routes&gt; contains one or more &lt;route&gt; elements, each
 350     of which must carry an <literal>id</literal> element.  One of the
 351     routes must have the ID value that was specified as the start
 352     route in the &lt;start&gt; element's <literal>route</literal>
 353     attribute.  Each route contains zero or more &lt;filter&gt;
 354     elements.  These are of two types.  They may be empty, but carry a
 355     <literal>refid</literal> attribute whose value is the same as the
 356     <literal>id</literal> of a filter previously defined in the
 357     &lt;filters&gt; section.  Alternatively, a route within a filter
 358     may omit the <literal>refid</literal> attribute, but contain
 359     configuration elements similar to those used for filters defined
 360     in the &lt;filters&gt; section.
 361    </para>
 362   </section>
 363
 364
 365   <section>
 366    <title>Filter configuration</title>
 367    <para>
 368     All &lt;filter&gt; elements have in common that they must carry a
 369     <literal>type</literal> attribute whose value is one of the
 370     supported ones, listed in the schema file and discussed below.  In
 371     additional, &lt;filters&gt;s occurring the &lt;filters&gt; section
 372     must have an <literal>id</literal> attribute, and those occurring
 373     within a route must have either a <literal>refid</literal>
 374     attribute referencing a previously defined filter or contain its
 375     own configuration information.
 376    </para>
 377    <para>
 378     In general, each filter recognises different configuration
 379     elements within its element, as each filter has different
 380     functionality.  These are as follows:
 381    </para>
 382
 383    <section>
 384     <title><literal>auth_simple</literal></title>
 385     <screen>
 386         &lt;filter type="auth_simple"&gt;
 387           &lt;userRegister&gt;../etc/example.simple-auth&lt;/userRegister&gt;
 388         &lt;/filter&gt;
 389     </screen>
 390    </section>
 391
 392    <section>
 393     <title><literal>backend_test</literal></title>
 394     <screen>
 395         &lt;filter type="backend_test"/&gt;
 396     </screen>
 397    </section>
 398
 399    <section>
 400     <title><literal>frontend_net</literal></title>
 401     <screen>
 402         &lt;filter type="frontend_net"&gt;
 403           &lt;threads&gt;10&lt;/threads&gt;
 404           &lt;port&gt;@:9000&lt;/port&gt;
 405         &lt;/filter&gt;
 406     </screen>
 407    </section>
 408
 409    <section>
 410     <title><literal>http_file</literal></title>
 411     <screen>
 412         &lt;filter type="http_file"&gt;
 413           &lt;mimetypes&gt;/etc/mime.types&lt;/mimetypes&gt;
 414           &lt;area&gt;
 415             &lt;documentroot&gt;.&lt;/documentroot&gt;
 416             &lt;prefix&gt;/etc&lt;/prefix&gt;
 417           &lt;/area&gt;
 418         &lt;/filter&gt;
 419     </screen>
 420    </section>
 421
 422    <section>
 423     <title><literal>log</literal></title>
 424     <screen>
 425         &lt;filter type="log"&gt;
 426           &lt;message&gt;B&lt;/message&gt;
 427         &lt;/filter&gt;
 428     </screen>
 429    </section>
 430
 431    <section>
 432     <title><literal>multi</literal></title>
 433     <screen>
 434         &lt;filter type="multi"/&gt;
 435     </screen>
 436    </section>
 437
 438    <section>
 439     <title><literal>session_shared</literal></title>
 440     <screen>
 441         &lt;filter type="session_shared"&gt;
 442           ### Not yet defined
 443         &lt;/filter&gt;
 444     </screen>
 445    </section>
 446
 447    <section>
 448     <title><literal>template</literal></title>
 449     <screen>
 450         &lt;filter type="template"/&gt;
 451     </screen>
 452    </section>
 453
 454    <section>
 455     <title><literal>virt_db</literal></title>
 456     <screen>
 457         &lt;filter type="virt_db"&gt;
 458           &lt;virtual&gt;
 459             &lt;database&gt;loc&lt;/database&gt;
 460             &lt;target&gt;z3950.loc.gov:7090/voyager&lt;/target&gt;
 461           &lt;/virtual&gt;
 462           &lt;virtual&gt;
 463             &lt;database&gt;idgils&lt;/database&gt;
 464             &lt;target&gt;indexdata.dk/gils&lt;/target&gt;
 465           &lt;/virtual&gt;
 466         &lt;/filter&gt;
 467     </screen>
 468    </section>
 469
 470    <section>
 471     <title><literal>z3950_client</literal></title>
 472     <screen>
 473         &lt;filter type="z3950_client"&gt;
 474           &lt;timeout&gt;30&lt;/timeout&gt;
 475         &lt;/filter&gt;
 476     </screen>
 477    </section>
 478   </section>
 479  </chapter>
 480
 481
 482
 483  <chapter id="multidb">
 484   <title>Virtual database as multi-database searching</title>
 485
 486
 487   <section>
 488    <title>Introductory notes</title>
 489    <para>
 490     Two of YP2's filters are concerned with multiple-database
 491     operations.  Of these, <literal>virt_db</literal> can work alone
 492     to control the routing of searches to one of a number of servers,
 493     while <literal>multi</literal> can work with the output of
 494     <literal>virt_db</literal> to perform multicast searching, merging
 495     the results into a unified result-set.  The interaction between
 496     these two filters is necessarily complex, reflecting the real
 497     complexity of multicast searching in a protocol such as Z39.50
 498     that separates initialisation from searching, with the database to
 499     search known only during the latter operation.
 500    </para>
 501    <para>
 502     ### Much, much more to say!
 503    </para>
 504   </section>
 505  </chapter>
 506
 507
 508
 509  <chapter id="classes">
 510   <title>Classes in the YP2 source code</title>
 511
 512
 513   <section>
 514    <title>Introductory notes</title>
 515    <para>
 516     <emphasis>Stop!  Do not read this!</emphasis>
 517     You won't enjoy it at all.
 518    </para>
 519    <para>
 520     This chapter contains documentation of the YP2 source code, and is
 521     of interest only to maintainers and developers.  If you need to
 522     change YP2's behaviour or write a new filter, then you will most
 523     likely find this chapter helpful.  Otherwise it's a waste of your
 524     good time.  Seriously: go and watch a film or something.
 525     <citetitle>This is Spinal Tap</citetitle> is particularly good.
 526    </para>
 527    <para>
 528     Still here?  OK, let's continue.
 529    </para>
 530    <para>
 531     In general, classes seem to be named big-endianly, so that
 532     <literal>FactoryFilter</literal> is not a filter that filters
 533     factories, but a factory that produces filters; and
 534     <literal>FactoryStatic</literal> is a factory for the statically
 535     registered filters (as opposed to those that are dynamically
 536     loaded).
 537    </para>
 538   </section>
 539
 540   <section>
 541    <title>Individual classes</title>
 542    <para>
 543     The classes making up the YP2 application are here listed by
 544     class-name, with the names of the source files that define them in
 545     parentheses.
 546    </para>
 547
 548    <section>
 549     <title><literal>yp::FactoryFilter</literal>
 550         (<filename>factory_filter.cpp</filename>)</title>
 551     <para>
 552      A factory class that exists primarily to provide the
 553      <literal>create()</literal> method, which takes the name of a
 554      filter class as its argument and returns a new filter of that
 555      type.  To enable this, the factory must first be populated by
 556      calling <literal>add_creator()</literal> for static filters (this
 557      is done by the <literal>FactoryStatic</literal> class, see below)
 558      and <literal>add_creator_dyn()</literal> for filters loaded
 559      dynamically.
 560     </para>
 561    </section>
 562
 563    <section>
 564     <title><literal>yp2::FactoryStatic</literal>
 565         (<filename>factory_static.cpp</filename>)</title>
 566     <para>
 567      A subclass of <literal>FactoryFilter</literal> which is
 568      responsible for registering all the statically defined filter
 569      types.  It does this by knowing about all those filters'
 570      structures, which are listed in its constructor.  Merely
 571      instantiating this class registers all the static classes.  It is
 572      for the benefit of this class that <literal>struct
 573      yp2_filter_struct</literal> exists, and that all the filter
 574      classes provide a static object of that type.
 575     </para>
 576    </section>
 577
 578    <section>
 579     <title><literal>yp2::filter::Base</literal>
 580         (<filename>filter.cpp</filename>)</title>
 581     <para>
 582      The virtual base class of all filters.  The filter API is, on the
 583      surface at least, extremely simple: two methods.
 584      <literal>configure()</literal> is passed a DOM tree representing
 585      that part of the configuration file that pertains to this filter
 586      instance, and is expected to walk that tree extracting relevant
 587      information.  And <literal>process()</literal> processes a
 588      package (see below).  That surface simplicitly is a bit
 589      misleading, as <literal>process()</literal> needs to know a lot
 590      about the <literal>Package</literal> class in order to do
 591      anything useful.
 592     </para>
 593    </section>
 594
 595    <section>
 596     <title><literal>yp2::filter::AuthSimple</literal>,
 597         <literal>Backend_test</literal>, etc.
 598         (<filename>filter_auth_simple.cpp</filename>,
 599          <filename>filter_backend_test.cpp</filename>, etc.)</title>
 600     <para>
 601      Individual filters.  Each of these is implemented by a header and
 602      a source file, named <filename>filter_*.hpp</filename> and
 603      <filename>filter_*.cpp</filename> respectively.  All the header
 604      files should be pretty much identical, in that they declare the
 605      class, including a private <literal>Rep</literal> class and a
 606      member pointer to it, and the two public methods.  The only extra
 607      information in any filter header is additional private types and
 608      members (which should really all be in the <literal>Rep</literal>
 609      anyway) and private methods (which should also remain known only
 610      to the source file, but C++'s brain-damaged design requires this
 611      dirty laundry to be exhibited in public.  Thanks, Bjarne!)
 612     </para>
 613     <para>
 614      The source file for each filter needs to supply:
 615     </para>
 616     <itemizedlist>
 617      <listitem>
 618       <para>
 619        A definition of the private <literal>Rep</literal> class.
 620       </para>
 621      </listitem>
 622      <listitem>
 623       <para>
 624        Some boilerplate constructors and destructors.
 625       </para>
 626      </listitem>
 627      <listitem>
 628       <para>
 629        A <literal>configure()</literal> method that uses the
 630        appropriate XML fragment.
 631       </para>
 632      </listitem>
 633      <listitem>
 634       <para>
 635        Most important, the <literal>process()</literal> method that
 636        does all the actual work.
 637       </para>
 638      </listitem>
 639     </itemizedlist>
 640    </section>
 641
 642    <section>
 643     <title><literal>yp2::Package</literal>
 644         (<filename>package.cpp</filename>)</title>
 645     <para>
 646      Represents a package on its way through the series of filters
 647      that make up a route.  This is essentially a Z39.50 or SRU APDU
 648      together with information about where it came from, which is
 649      modified as it passes through the various filters.
 650     </para>
 651    </section>
 652
 653    <section>
 654     <title><literal>yp2::Pipe</literal>
 655         (<filename>pipe.cpp</filename>)</title>
 656     <para>
 657      This class provides a compatibility layer so that we have an IPC
 658      mechanism that works the same under Unix and Windows.  It's not
 659      particularly exciting.
 660     </para>
 661    </section>
 662
 663    <section>
 664     <title><literal>yp2::RouterChain</literal>
 665         (<filename>router_chain.cpp</filename>)</title>
 666     <para>
 667      ###
 668     </para>
 669    </section>
 670
 671    <section>
 672     <title><literal>yp2::RouterFleXML</literal>
 673         (<filename>router_flexml.cpp</filename>)</title>
 674     <para>
 675      ###
 676     </para>
 677    </section>
 678
 679    <section>
 680     <title><literal>yp2::Session</literal>
 681         (<filename>session.cpp</filename>)</title>
 682     <para>
 683      ###
 684     </para>
 685    </section>
 686
 687    <section>
 688     <title><literal>yp2::ThreadPoolSocketObserver</literal>
 689         (<filename>thread_pool_observer.cpp</filename>)</title>
 690     <para>
 691      ###
 692     </para>
 693    </section>
 694
 695    <section>
 696     <title><literal>yp2::util</literal>
 697         (<filename>util.cpp</filename>)</title>
 698     <para>
 699      A namespace of various small utility functions and classes,
 700      collected together for convenience.  Most importantly, includes
 701      the <literal>yp2::util::odr</literal> class, a wrapper for YAZ's
 702      ODR facilities.
 703     </para>
 704    </section>
 705
 706    <section>
 707     <title><literal>yp2::xml</literal>
 708         (<filename>xmlutil.cpp</filename>)</title>
 709     <para>
 710      A namespace of various XML utility functions and classes,
 711      collected together for convenience.
 712     </para>
 713    </section>
 714   </section>
 715
 716
 717   <section>
 718    <title>Other Source Files</title>
 719    <para>
 720     In addition to the YP2 source files that define the classes
 721     described above, there are a few additional files which are
 722     briefly described here:
 723    </para>
 724    <variablelist>
 725     <varlistentry>
 726      <term><literal>yp2_prog.cpp</literal></term>
 727      <listitem>
 728       <para>
 729        The main function of the <command>yp2</command> program.
 730       </para>
 731      </listitem>
 732     </varlistentry>
 733     <varlistentry>
 734      <term><literal>ex_router_flexml.cpp</literal></term>
 735      <listitem>
 736       <para>
 737        Identical to <literal>yp2_prog.cpp</literal>: it's not clear why.
 738       </para>
 739      </listitem>
 740     </varlistentry>
 741     <varlistentry>
 742      <term><literal>test_*.cpp</literal></term>
 743      <listitem>
 744       <para>
 745        Unit-tests for various modules.
 746       </para>
 747      </listitem>
 748     </varlistentry>
 749    </variablelist>
 750    <para>
 751     ### Still to be described:
 752     <literal>ex_filter_frontend_net.cpp</literal>,
 753     <literal>filter_dl.cpp</literal>,
 754     <literal>plainfile.cpp</literal>,
 755     <literal>tstdl.cpp</literal>.
 756    </para>
 757
 758
 759    <!-- Epilogue -->
 760    <para>
 761     --
 762    </para>
 763    <screen>
 764     <!-- This is just a lame way to get some vertical whitespace at
 765        the end of the document -->
 766
 767
 768
 769
 770    </screen>
 771   </section>
 772  </chapter>
 773 </book>
 774
 775 <!-- Keep this comment at the end of the file
 776 Local variables:
 777 mode: sgml
 778 sgml-omittag:t
 779 sgml-shorttag:t
 780 sgml-minimize-attributes:nil
 781 sgml-always-quote-attributes:t
 782 sgml-indent-step:1
 783 sgml-indent-data:t
 784 sgml-parent-document:nil
 785 sgml-local-catalogs: nil
 786 sgml-namecase-general:t
 787 End:
 788 -->