doc/ref-oodml.xml

   1 <?xml version='1.0' ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % myents SYSTEM "entities.inc">
   5 %myents;
   6 ]>
   7
   8 <!-- Object Oriented Data Manipulation Language -->
   9 <reference id="ref-oodml">
  10   <title>Object Oriented Data Manipulation Language (OODML)</title>
  11     <partintro>
  12     <para>
  13       Object Oriented Data Manipulation Language (OODML) provides a Common Lisp
  14       Object System (CLOS) interface to SQL databases. View classes are defined with
  15       the <link linkend="ref-ooddl">OODDL</link> interface and objects are read and
  16       written with the OODML.
  17     </para>
  18     <para>
  19       The main function for reading data with the OODML is the
  20       <link linkend="select"><function>select</function></link> function. The
  21       <function>select</function> is also used in the FDML. However, when <function>select</function>
  22       is given a view class name, it returns a list of instances of view classes.
  23     </para>
  24   </partintro>
  25
  26   <refentry id="db-auto-sync">
  27     <refnamediv>
  28       <refname>*DB-AUTO-SYNC*</refname>
  29       <refpurpose>Enables SQL storage during Lisp object creation.</refpurpose>
  30       <refclass>Variable</refclass>
  31     </refnamediv>
  32     <refsect1>
  33       <title>Value Type</title>
  34       <para>
  35         Boolean
  36       </para>
  37     </refsect1>
  38     <refsect1>
  39       <title>Initial Value</title>
  40       <para>&nil;</para>
  41     </refsect1>
  42     <refsect1>
  43       <title>Description</title>
  44       When this variable is &t; an instance is stored in the SQL database when the instance is created
  45       by <function>make-instance</function>. When this variable is &nil;, which is the default value, &clsql;
  46       behaves like &commonsql;: instances of view classes are stored to the SQL database only when
  47       <link linkend="update-record-from-slots"><function>update-record-from-slots</function></link>
  48       is called.
  49     </refsect1>
  50     <refsect1>
  51       <title>Examples</title>
  52       <screen>
  53         (let ((instance (make-instance 'foo)))
  54           (update-record-from-slots instance))
  55
  56         ;; is equivalent to
  57
  58         (let ((*db-auto-sync* t))
  59           (make-instance 'foo))
  60       </screen>
  61     </refsect1>
  62     <refsect1>
  63       <title>Affected By</title>
  64       <para>None.</para>
  65     </refsect1>
  66     <refsect1>
  67       <title>See Also</title>
  68       <simplelist>
  69         <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
  70       </simplelist>
  71     </refsect1>
  72     <refsect1>
  73       <title>Notes</title>
  74       <para>None.</para>
  75     </refsect1>
  76   </refentry>
  77
  78   <refentry id="default-update-objects-max-len">
  79     <refnamediv>
  80       <refname>*DEFAULT-UPDATE-OBJECTS-MAX-LEN*</refname>
  81       <refpurpose>The default maximum number of objects each query to perform a join</refpurpose>
  82       <refclass>Variable</refclass>
  83     </refnamediv>
  84     <refsect1>
  85       <title>Value Type</title>
  86       <para>
  87         (or null integer)
  88       </para>
  89     </refsect1>
  90     <refsect1>
  91       <title>Initial Value</title>
  92       <para>&nil;</para>
  93     </refsect1>
  94     <refsect1>
  95       <title>Description</title>
  96       <para>
  97         This special variable provides the default value for the
  98         <parameter>max-len</parameter> argument of the function <link
  99         linkend="update-object-joins"><function>update-object-joins</function></link>.
 100       </para>
 101     </refsect1>
 102     <refsect1>
 103       <title>Examples</title>
 104       <screen>
 105         (setq *default-update-objects-max-len* 100)
 106       </screen>
 107     </refsect1>
 108     <refsect1>
 109       <title>Affected By</title>
 110       <para>None.</para>
 111     </refsect1>
 112     <refsect1>
 113       <title>See Also</title>
 114       <para>None.</para>
 115     </refsect1>
 116     <refsect1>
 117       <title>Notes</title>
 118       <para>None.</para>
 119     </refsect1>
 120   </refentry>
 121
 122   <refentry id="delete-instance-records">
 123     <refnamediv>
 124       <refname>DELETE-INSTANCE-RECORDS</refname>
 125       <refpurpose>Delete SQL records represented by a view class object.</refpurpose>
 126       <refclass>Function</refclass>
 127     </refnamediv>
 128     <refsect1>
 129       <title>Syntax</title>
 130       <synopsis>
 131       <function>(delete-instance-records object)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 132     </refsect1>
 133     <refsect1>
 134       <title>Arguments and Values</title>
 135       <variablelist>
 136         <varlistentry>
 137           <term><parameter>object</parameter></term>
 138           <listitem>
 139             <para>
 140               An instance of a view class.
 141             </para>
 142           </listitem>
 143         </varlistentry>
 144       </variablelist>
 145     </refsect1>
 146     <refsect1>
 147       <title>Description</title>
 148       <para>Deletes the records represented by
 149       <parameter>object</parameter> in the appropriate table of the
 150       database associated with <parameter>object</parameter>. If
 151       <parameter>object</parameter> is not yet associated with a
 152       database, an error is signalled.
 153       </para>
 154     </refsect1>
 155     <refsect1>
 156       <title>Examples</title>
 157       <screen>
 158         * (def-view-class tab () ((a :type integer :db-kind :key) (b :type string)))
 159         #&lt;clsql-sys::db-standard-class tab>
 160         * (defvar obj (let ((*db-auto-sync* t))
 161                         (make-instance 'tab :a 5 :b "the string")))
 162         * (start-sql-recording :type :both)
 163         * (delete-instance-records obj)
 164       </screen>
 165     </refsect1>
 166     <refsect1>
 167       <title>Side Effects</title>
 168       <para>
 169         Deletes data from the SQL database.
 170       </para>
 171     </refsect1>
 172     <refsect1>
 173       <title>Affected by</title>
 174       <para>
 175         Permissions granted by the SQL database to the user in the database connection.
 176       </para>
 177     </refsect1>
 178     <refsect1>
 179       <title>Exceptional Situations</title>
 180       <para>
 181         An exception may be signaled if the database connection user does not have
 182         sufficient privileges to modify the database.
 183       </para>
 184     </refsect1>
 185     <refsect1>
 186       <title>See Also</title>
 187       <para>
 188         <simplelist>
 189           <member><link linkend="update-records"><function>update-records</function></link></member>
 190           <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
 191         </simplelist>
 192       </para>
 193     </refsect1>
 194     <refsect1>
 195       <title>Notes</title>
 196       <para>
 197         Instances are referenced in the database by values stored in the key slots. If
 198         <function>delete-records-from-instance</function> is called with an instance of a class that does
 199         not contain any keys, then all records in that table will be deleted.
 200       </para>
 201     </refsect1>
 202   </refentry>
 203
 204   <refentry id="instance-refreshed">
 205     <refnamediv>
 206       <refname>INSTANCE-REFRESHED</refname>
 207       <refpurpose>User hook to call on object refresh.</refpurpose>
 208       <refclass>Generic function</refclass>
 209     </refnamediv>
 210     <refsect1>
 211       <title>Syntax</title>
 212       <synopsis>
 213       <function>(instance-refreshed object)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 214     </refsect1>
 215     <refsect1>
 216       <title>Arguments and Values</title>
 217       <variablelist>
 218         <varlistentry>
 219           <term><parameter>object</parameter></term>
 220           <listitem>
 221             <para>
 222               The view class object which is being refreshed.
 223             </para>
 224           </listitem>
 225         </varlistentry>
 226       </variablelist>
 227     </refsect1>
 228     <refsect1>
 229       <title>Description</title>
 230       <para>Provides a hook which is called within an object oriented
 231       call to <function>select</function> with a non-nil value of
 232       <parameter>refresh</parameter> when the View Class instance
 233       <parameter>object</parameter> has been updated from the
 234       database. A method specialised on
 235       <type>standard-db-object</type> is provided which has no
 236       effects. Methods specialised on particular View Classes can be
 237       used to specify any operations that need to be made on View
 238       Classes instances which have been updated in calls to
 239       <function>select</function>.
 240       </para>
 241     </refsect1>
 242     <refsect1>
 243       <title>Examples</title>
 244       <screen>
 245         <!-- examples -->
 246       </screen>
 247     </refsect1>
 248     <refsect1>
 249       <title>Side Effects</title>
 250       <para>
 251         The user hook function may cause side effects.
 252       </para>
 253     </refsect1>
 254     <refsect1>
 255       <title>Exceptional Situations</title>
 256       <para>
 257         None.
 258       </para>
 259     </refsect1>
 260     <refsect1>
 261       <title>See Also</title>
 262       <para>
 263         <simplelist>
 264           <member><link linkend="select"><function>select</function></link></member>
 265         </simplelist>
 266       </para>
 267     </refsect1>
 268   </refentry>
 269
 270   <refentry id="update-instance-from-records">
 271     <refnamediv>
 272       <refname>UPDATE-INSTANCE-FROM-RECORDS</refname>
 273       <refpurpose>Update slot values from database.</refpurpose>
 274       <refclass>Function</refclass>
 275     </refnamediv>
 276     <refsect1>
 277       <title>Syntax</title>
 278       <synopsis>
 279       <function>(update-instance-from-records object &amp;key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 280     </refsect1>
 281     <refsect1>
 282       <title>Arguments and Values</title>
 283       <variablelist>
 284         <varlistentry>
 285           <term><parameter>object</parameter></term>
 286           <listitem>
 287             <para>
 288               An instance of a view class.
 289             </para>
 290           </listitem>
 291         </varlistentry>
 292         <varlistentry>
 293           <term><parameter>database</parameter></term>
 294           <listitem>
 295             <para>
 296               A database connection.
 297             </para>
 298           </listitem>
 299         </varlistentry>
 300       </variablelist>
 301     </refsect1>
 302     <refsect1>
 303       <title>Description</title>
 304       <para>Updates the slot values of the View Class instance
 305       <parameter>object</parameter> using the attribute values of the
 306       appropriate table of <parameter>database</parameter> which
 307       defaults to the database associated with
 308       <parameter>object</parameter> or, if <parameter>object</parameter> is not associated
 309       with a database, <variable>*default-database*</variable>.  Join slots are updated but
 310       instances of the class on which the join is made are not
 311       updated.
 312       </para>
 313     </refsect1>
 314     <refsect1>
 315       <title>Examples</title>
 316       <screen>
 317         <!-- examples -->
 318       </screen>
 319     </refsect1>
 320     <refsect1>
 321       <title>Side Effects</title>
 322       <para>
 323         Slot values of <parameter>object</parameter> may be modified.
 324       </para>
 325     </refsect1>
 326     <refsect1>
 327       <title>Affected by</title>
 328       <para>
 329         <simplelist>
 330           Data in SQL database.
 331         </simplelist>
 332       </para>
 333     </refsect1>
 334     <refsect1>
 335       <title>Exceptional Situations</title>
 336       <para>
 337         If <parameter>database</parameter> is not able to be read.
 338       </para>
 339     </refsect1>
 340     <refsect1>
 341       <title>See Also</title>
 342       <para>
 343         <simplelist>
 344           <!-- see also -->
 345         </simplelist>
 346       </para>
 347     </refsect1>
 348     <refsect1>
 349       <title>Notes</title>
 350       <para>
 351         <!-- notes -->
 352       </para>
 353     </refsect1>
 354   </refentry>
 355
 356   <refentry id="update-objects-joins">
 357     <refnamediv>
 358       <refname>UPDATE-OBJECTS-JOINS</refname>
 359       <refpurpose>Updates joined slots of objects.</refpurpose>
 360       <refclass>Function</refclass>
 361     </refnamediv>
 362     <refsect1>
 363       <title>Syntax</title>
 364       <synopsis>
 365       <function>(update-objects-joins objects &amp;key (slots t) (force-p t) class-name (max-len *default-update-objects-max-len*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 366     </refsect1>
 367     <refsect1>
 368       <title>Arguments and Values</title>
 369       <variablelist>
 370         <varlistentry>
 371           <term><parameter>objects</parameter></term>
 372           <listitem>
 373             <para>
 374               A list of instances of a view class.
 375             </para>
 376           </listitem>
 377         </varlistentry>
 378         <varlistentry>
 379           <term><parameter>slots</parameter></term>
 380           <listitem>
 381             <para>
 382             </para>
 383           </listitem>
 384         </varlistentry>
 385         <varlistentry>
 386           <term><parameter>force-p</parameter></term>
 387           <listitem>
 388             <para>
 389             </para>
 390           </listitem>
 391         </varlistentry>
 392         <varlistentry>
 393           <term><parameter>class-name</parameter></term>
 394           <listitem>
 395             <para>
 396               A list of instances of a view class.
 397             </para>
 398           </listitem>
 399         </varlistentry>
 400         <varlistentry>
 401           <term><parameter>max-len</parameter></term>
 402           <listitem>
 403             <para>
 404             </para>
 405           </listitem>
 406         </varlistentry>
 407       </variablelist>
 408     </refsect1>
 409     <refsect1>
 410       <title>Description</title>
 411       <para>Updates from the records of the appropriate database
 412       tables the join slots specified by <parameter>slots</parameter>
 413       in the supplied list of View Class instances
 414       <parameter>objects</parameter>. <parameter>slots</parameter>
 415       when &t; means that all join slots with :retrieval :immediate
 416       are updated. <parameter>class-name</parameter> is used to
 417       specify the View Class of all instance in
 418       <parameter>objects</parameter>, when &nil; then the class of the
 419       first instance in <parameter>objects</parameter> is
 420       used. <parameter>force-p</parameter> when &t; means that all
 421       join slots are updated whereas a value of &nil; means that only
 422       unbound join slots are updated. <parameter>max-len</parameter>
 423       when non-nil specifies that
 424       <function>update-object-joins</function> may issue multiple
 425       database queries with a maximum of
 426       <parameter>max-len</parameter> instances updated in each query.
 427       </para>
 428     </refsect1>
 429     <refsect1>
 430       <title>Examples</title>
 431       <screen>
 432         <!-- examples -->
 433       </screen>
 434     </refsect1>
 435     <refsect1>
 436       <title>Side Effects</title>
 437       <para>
 438         <!-- side effects -->
 439       </para>
 440     </refsect1>
 441     <refsect1>
 442       <title>Affected by</title>
 443       <para>
 444         <simplelist>
 445           <!-- affected by -->
 446         </simplelist>
 447       </para>
 448     </refsect1>
 449     <refsect1>
 450       <title>Exceptional Situations</title>
 451       <para>
 452         <!-- execeptional situations -->
 453       </para>
 454     </refsect1>
 455     <refsect1>
 456       <title>See Also</title>
 457       <para>
 458         <simplelist>
 459           <!-- see also -->
 460         </simplelist>
 461       </para>
 462     </refsect1>
 463     <refsect1>
 464       <title>Notes</title>
 465       <para>
 466         <!-- notes -->
 467       </para>
 468     </refsect1>
 469   </refentry>
 470
 471   <refentry id="update-record-from-slot">
 472     <refnamediv>
 473       <refname>UPDATE-RECORD-FROM-SLOT</refname>
 474       <refpurpose>Updates database from slot value.</refpurpose>
 475       <refclass>Function</refclass>
 476     </refnamediv>
 477     <refsect1>
 478       <title>Syntax</title>
 479       <synopsis>
 480       <function>(update-record-from-slot object slot &amp;key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 481     </refsect1>
 482     <refsect1>
 483       <title>Arguments and Values</title>
 484       <variablelist>
 485         <!-- arguments and values -->
 486       </variablelist>
 487     </refsect1>
 488     <refsect1>
 489       <title>Description</title>
 490       <para>Updates the value stored in the column represented by the
 491       slot, specified by the CLOS slot name
 492       <parameter>slot</parameter>, of View Class instance
 493       <parameter>object</parameter>. <parameter>database</parameter>
 494       specifies the database in which the update is made only if
 495       <parameter>object</parameter> is not associated with a
 496       database. In this case, a record is created in
 497       <parameter>database</parameter> and the attribute represented by
 498       <parameter>slot</parameter> is initialised from the value of the
 499       supplied slots with other attributes having default
 500       values. Furthermore, <parameter>object</parameter> becomes
 501       associated with <parameter>database</parameter>.
 502       </para>
 503     </refsect1>
 504     <refsect1>
 505       <title>examples</title>
 506       <screen>
 507         <!-- examples -->
 508       </screen>
 509     </refsect1>
 510     <refsect1>
 511       <title>side effects</title>
 512       <para>
 513         modifies sql database.
 514       </para>
 515     </refsect1>
 516     <refsect1>
 517       <title>affected by</title>
 518       <para>
 519         <simplelist>
 520           <!-- affected by -->
 521         </simplelist>
 522       </para>
 523     </refsect1>
 524     <refsect1>
 525       <title>exceptional situations</title>
 526       <para>
 527         if a database error occurs.
 528       </para>
 529     </refsect1>
 530     <refsect1>
 531       <title>see also</title>
 532       <para>
 533         <simplelist>
 534           <!-- see also -->
 535         </simplelist>
 536       </para>
 537     </refsect1>
 538     <refsect1>
 539       <title>notes</title>
 540       <para>
 541         <!-- notes -->
 542       </para>
 543     </refsect1>
 544   </refentry>
 545
 546   <refentry id="update-record-from-slots">
 547     <refnamediv>
 548       <refname>update-record-from-slots</refname>
 549       <refpurpose>update database from slots of view class object.</refpurpose>
 550       <refclass>function</refclass>
 551     </refnamediv>
 552     <refsect1>
 553       <title>syntax</title>
 554       <synopsis>
 555       <function>(update-record-from-slots object slots &amp;key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 556     </refsect1>
 557     <refsect1>
 558       <title>arguments and values</title>
 559       <variablelist>
 560         <!-- arguments and values -->
 561       </variablelist>
 562     </refsect1>
 563     <refsect1>
 564       <title>description</title>
 565       <para>updates the values stored in the columns represented by
 566       the slots, specified by the clos slot names
 567       <parameter>slots</parameter>, of view class instance
 568       <parameter>object</parameter>. <parameter>database</parameter>
 569       specifies the database in which the update is made only if
 570       <parameter>object</parameter> is not associated with a
 571       database. In this case, a record is created in the appropriate
 572       table of <parameter>database</parameter> and the attributes
 573       represented by <parameter>slots</parameter> are initialised from
 574       the values of the supplied slots with other attributes having
 575       default values. Furthermore, <parameter>object</parameter>
 576       becomes associated with <parameter>database</parameter>.
 577       </para>
 578     </refsect1>
 579     <refsect1>
 580       <title>Examples</title>
 581       <screen>
 582         <!-- examples -->
 583       </screen>
 584     </refsect1>
 585     <refsect1>
 586       <title>Side Effects</title>
 587       <para>
 588         Modifies the SQL database.
 589       </para>
 590     </refsect1>
 591     <refsect1>
 592       <title>Affected by</title>
 593       <para>
 594         <simplelist>
 595           <!-- affected by -->
 596         </simplelist>
 597       </para>
 598     </refsect1>
 599     <refsect1>
 600       <title>Exceptional Situations</title>
 601       <para>
 602         <!-- execeptional situations -->
 603       </para>
 604     </refsect1>
 605     <refsect1>
 606       <title>See Also</title>
 607       <para>
 608         <simplelist>
 609           <!-- see also -->
 610         </simplelist>
 611       </para>
 612     </refsect1>
 613     <refsect1>
 614       <title>Notes</title>
 615       <para>
 616         <!-- notes -->
 617       </para>
 618     </refsect1>
 619   </refentry>
 620
 621
 622   <refentry id="update-records-from-instance">
 623     <refnamediv>
 624       <refname>UPDATE-RECORDS-FROM-INSTANCE</refname>
 625       <refpurpose>Update database from view class object.</refpurpose>
 626       <refclass>Function</refclass>
 627     </refnamediv>
 628     <refsect1>
 629       <title>Syntax</title>
 630       <synopsis>
 631       <function>(update-records-from-instance object &amp;key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 632     </refsect1>
 633     <refsect1>
 634       <title>Arguments and Values</title>
 635       <variablelist>
 636         <!-- arguments and values -->
 637       </variablelist>
 638     </refsect1>
 639     <refsect1>
 640       <title>Description</title>
 641       <para>Using an instance of a View Class,
 642       <parameter>object</parameter>, update the table that stores its
 643       instance data. <parameter>database</parameter> specifies the
 644       database in which the update is made only if
 645       <parameter>object</parameter> is not associated with a
 646       database. In this case, a record is created in the appropriate
 647       table of <parameter>database</parameter> using values from the
 648       slot values of <parameter>object</parameter>, and
 649       <parameter>object</parameter> becomes associated with
 650       <parameter>database</parameter>.
 651       </para>
 652     </refsect1>
 653     <refsect1>
 654       <title>Examples</title>
 655       <screen>
 656         <!-- examples -->
 657       </screen>
 658     </refsect1>
 659     <refsect1>
 660       <title>Side Effects</title>
 661       <para>
 662         <!-- side effects -->
 663       </para>
 664     </refsect1>
 665     <refsect1>
 666       <title>Affected by</title>
 667       <para>
 668         <simplelist>
 669           <!-- affected by -->
 670         </simplelist>
 671       </para>
 672     </refsect1>
 673     <refsect1>
 674       <title>Exceptional Situations</title>
 675       <para>
 676         <!-- execeptional situations -->
 677       </para>
 678     </refsect1>
 679     <refsect1>
 680       <title>See Also</title>
 681       <para>
 682         <simplelist>
 683           <!-- see also -->
 684         </simplelist>
 685       </para>
 686     </refsect1>
 687     <refsect1>
 688       <title>Notes</title>
 689       <para>
 690         <!-- notes -->
 691       </para>
 692     </refsect1>
 693   </refentry>
 694
 695   <refentry id="update-slot-from-record">
 696     <refnamediv>
 697       <refname>UPDATE-SLOT-FROM-RECORD</refname>
 698       <refpurpose>Update objects slot from database.</refpurpose>
 699       <refclass>Function</refclass>
 700     </refnamediv>
 701     <refsect1>
 702       <title>Syntax</title>
 703       <synopsis>
 704       <function>(update-slot-from-record object slot &amp;key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 705     </refsect1>
 706     <refsect1>
 707       <title>Arguments and Values</title>
 708       <variablelist>
 709         <!-- arguments and values -->
 710       </variablelist>
 711     </refsect1>
 712     <refsect1>
 713       <title>Description</title>
 714       <para>Updates the slot value, specified by the CLOS slot name
 715       <parameter>slot</parameter>, of the View Class instance
 716       <parameter>object</parameter> using the attribute values of the
 717       appropriate table of <parameter>database</parameter> which
 718       defaults to the database associated with
 719       <parameter>object</parameter> or, if
 720       <parameter>object</parameter> is not associated with a database,
 721       <variable>*default-database*</variable>.  Join slots are updated
 722       but instances of the class on which the join is made are not
 723       updated.
 724       </para>
 725     </refsect1>
 726     <refsect1>
 727       <title>Examples</title>
 728       <screen>
 729         <!-- examples -->
 730       </screen>
 731     </refsect1>
 732     <refsect1>
 733       <title>Side Effects</title>
 734       <para>
 735         Modifies the slot value of the object.
 736       </para>
 737     </refsect1>
 738     <refsect1>
 739       <title>Affected by</title>
 740       <para>
 741         <simplelist>
 742           <member>Data in SQL database.</member>
 743         </simplelist>
 744       </para>
 745     </refsect1>
 746     <refsect1>
 747       <title>Exceptional Situations</title>
 748       <para>
 749         SQL access errors.
 750       </para>
 751     </refsect1>
 752     <refsect1>
 753       <title>See Also</title>
 754       <para>
 755         <simplelist>
 756           <!-- see also -->
 757         </simplelist>
 758       </para>
 759     </refsect1>
 760     <refsect1>
 761       <title>Notes</title>
 762       <para>
 763         <!-- notes -->
 764       </para>
 765     </refsect1>
 766   </refentry>
 767
 768 </reference>