Hi, I recently created a new extension on PECL called chdb, and I would like to commit the corresponding documentation.
This would be my first contribution to the PHP documentation, and I lack phpdoc karma. You can find the two patches to 'doc-base' and 'en' attached. Lorenzo Castelli
Index: manual.xml.in =================================================================== --- manual.xml.in (revision 300495) +++ manual.xml.in (working copy) @@ -344,6 +344,7 @@ <set xml:id="refs.remote.other"> <title>&OtherServices;</title> &reference.amqp.book; + &reference.chdb.book; &reference.curl.book; &reference.fam.book; &reference.ftp.book; Index: entities/global.ent =================================================================== --- entities/global.ent (revision 300495) +++ entities/global.ent (working copy) @@ -45,6 +45,7 @@ <!ENTITY url.cairo.dl "http://perisama.net/cairo/"> <!ENTITY url.cc.by "http://creativecommons.org/licenses/by/3.0/"> <!ENTITY url.cert "http://www.cert.org/advisories/CA-1996-11.html"> +<!ENTITY url.cmph "http://cmph.sourceforge.net/"> <!ENTITY url.corba.universe "http://universe-phpext.sourceforge.net/"> <!ENTITY url.cdb "http://cr.yp.to/cdb.html"> <!ENTITY url.cgispec "http://web.archive.org/web/20071018185254/http://hoohoo.ncsa.uiuc.edu/cgi/env.html">
Property changes on: reference/chdb ___________________________________________________________________ Added: svn:ignore + entities.*.xml Index: reference/chdb/chdb.xml =================================================================== --- reference/chdb/chdb.xml (revision 0) +++ reference/chdb/chdb.xml (revision 0) @@ -0,0 +1,67 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<phpdoc:classref xml:id="class.chdb" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <title>The chdb class</title> + <titleabbrev>chdb</titleabbrev> + + <partintro> + +<!-- {{{ chdb intro --> + <section xml:id="chdb.intro"> + &reftitle.intro; + <para> + Represents a loaded chdb file. + </para> + </section> +<!-- }}} --> + + <section xml:id="chdb.synopsis"> + &reftitle.classsynopsis; + +<!-- {{{ Synopsis --> + <classsynopsis> + <ooclass><classname>chdb</classname></ooclass> + +<!-- {{{ Class synopsis --> + <classsynopsisinfo> + <ooclass> + <classname>chdb</classname> + </ooclass> + </classsynopsisinfo> +<!-- }}} --> + + <classsynopsisinfo role="comment">Methods</classsynopsisinfo> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.chdb')/db:refentry/db:refsec...@role='description']/descendant::db:methodsynopsis[1])" /> + </classsynopsis> +<!-- }}} --> + + </section> + + </partintro> + + &reference.chdb.entities.chdb; + +</phpdoc:classref> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> Index: reference/chdb/setup.xml =================================================================== --- reference/chdb/setup.xml (revision 0) +++ reference/chdb/setup.xml (revision 0) @@ -0,0 +1,53 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<chapter xml:id="chdb.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + &reftitle.setup; + + <section xml:id="chdb.requirements"> + &reftitle.required; + <para> + This module uses <link xlink:href="&url.cmph;">cmph</link> (version 0.9) for + providing the perfect hashing function. + </para> + <para> + cmph 0.9 is required to install this module. + </para> + </section> + + <!-- {{{ Installation --> + &reference.chdb.configure; + <!-- }}} --> + + <section xml:id="chdb.configuration"> + &reftitle.runtime; + &no.config; + </section> + + <section xml:id="chdb.resources"> + &reftitle.resources; + &no.resource; + </section> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> Index: reference/chdb/chdb/construct.xml =================================================================== --- reference/chdb/chdb/construct.xml (revision 0) +++ reference/chdb/chdb/construct.xml (revision 0) @@ -0,0 +1,83 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="chdb.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>chdb::__construct</refname> + <refpurpose>Creates a <classname>chdb</classname> instance</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <methodname>chdb::__construct</methodname> + <methodparam><type>string</type><parameter>pathname</parameter></methodparam> + </methodsynopsis> + <para> + Loads a chdb file, by mapping it into memory. + <note> + <para> + While some validity checks are performed on the specified file, they are + mostly there to avoid the possibility of common mistakes (for example, + loading a file which is not a chdb database, or that is somehow + incompatible with the current system). A maliciously crafted chdb file can + thus be dangerous if loaded, so chdb files should be trusted and treated + with the same security protections used for PHP shared libraries. + </para> + </note> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>pathname</parameter></term> + <listitem> + <para> + The name of the file to load. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <para> + Throws an exception in case the chdb file hasn't been successfully loaded. + </para> + <note> + <para> + A valid chdb file might fail to load in case it was created on an + architecture with a different endianness, with a different version of chdb, + or if the file is too big to be mapped into memory (mostly in case of huge + files and 32-bit architectures). In these cases the load will fail by + throwing an exception, but otherwise not performing any illegal operation. + </para> + </note> + </refsect1> + + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> Index: reference/chdb/chdb/get.xml =================================================================== --- reference/chdb/chdb/get.xml (revision 0) +++ reference/chdb/chdb/get.xml (revision 0) @@ -0,0 +1,100 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="chdb.get" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>chdb::get</refname> + <refpurpose>Gets the value associated with a key</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <modifier>public</modifier> <type>string</type><methodname>chdb::get</methodname> + <methodparam><type>string</type><parameter>key</parameter></methodparam> + </methodsynopsis> + <para> + Gets the value associated with a key from a chdb database. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>key</parameter></term> + <listitem> + <para> + The key for which to get the value. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a string containing the value associated with the given + <parameter>key</parameter>, or &null; if not found. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>chdb::get</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$data = array( + 'key1' => 'value1', + 'key2' => 'value2', + // ... +); +chdb_create('data.chdb', $data); + +$chdb = new chdb('data.chdb'); +$value1 = $chdb->get('key1'); +$value2 = $chdb->get('key2'); + +echo $value1, PHP_EOL; +echo $value2, PHP_EOL; + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +value1 +value2 +]]> + </screen> + </example> + </refsect1> + + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> Index: reference/chdb/configure.xml =================================================================== --- reference/chdb/configure.xml (revision 0) +++ reference/chdb/configure.xml (revision 0) @@ -0,0 +1,42 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<section xml:id="chdb.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + &reftitle.install; + + <para> + &pecl.info; + <link xlink:href="&url.pecl.package;chdb">&url.pecl.package;chdb</link> + </para> + + <para> + <link xlink:href="&url.cmph;">cmph</link> (version 0.9) is required + for installing this extension. If cmph is installed in a + non-standard directory, use the + <option role="configure">--with-libcmph-dir=DIR</option> switch, + where DIR is the cmph install prefix. + </para> + +</section> + + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> Index: reference/chdb/versions.xml =================================================================== --- reference/chdb/versions.xml (revision 0) +++ reference/chdb/versions.xml (revision 0) @@ -0,0 +1,34 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> +<!-- + Do NOT translate this file +--> + +<versions> + <!-- Functions --> + <function name='chdb_create' from='PECL chdb >= Unknown'/> + <!-- Methods --> + <function name='chdb::__construct' from='PECL chdb >= Unknown'/> + <function name='chdb::get' from='PECL chdb >= Unknown'/> +</versions> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> Index: reference/chdb/functions/chdb-create.xml =================================================================== --- reference/chdb/functions/chdb-create.xml (revision 0) +++ reference/chdb/functions/chdb-create.xml (revision 0) @@ -0,0 +1,123 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<refentry xml:id="function.chdb-create" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>chdb_create</refname> + <refpurpose>Creates a chdb file</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <type>void</type><methodname>chdb_create</methodname> + <methodparam><type>string</type><parameter>pathname</parameter></methodparam> + <methodparam><type>array</type><parameter>data</parameter></methodparam> + </methodsynopsis> + <para> + <function>chdb_create</function> creates a chdb file containing the + specified key-value pairs. + </para> + <note> + <para> + chdb files are not portable across little-endian and big-endian + environments. Except for that, they are portable across different + architectures. Also compatibility across different versions of chdb is not + guaranteed. + </para> + </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>pathname</parameter></term> + <listitem> + <para> + The name of the file to create. + </para> + <para> + If a file with the same name already exists, it is overwritten. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>data</parameter></term> + <listitem> + <para> + An array containing the key-value pairs to store in the chdb file. + </para> + <para> + Keys and values are converted to strings before being written to the file, + as chdb only support the string type. Note that binary strings are + supported as well, both as keys and values. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.void; + </para> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <para> + Throws an exception in case the chdb file hasn't been successfully created. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>chdb_create</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$data = array( + 'key1' => 'value1', + 'key2' => 'value2', + // ... +); +chdb_create('data.chdb', $data); + +?> +]]> + </programlisting> + <para> + The above example will generate a chdb file named + <literal>data.chdb</literal> and containing the key-value pairs defined in + <varname>$data</varname>. + </para> + </example> + </refsect1> + + +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> Index: reference/chdb/book.xml =================================================================== --- reference/chdb/book.xml (revision 0) +++ reference/chdb/book.xml (revision 0) @@ -0,0 +1,75 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<book xml:id="book.chdb" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>Constant hash database</title> + <titleabbrev>chdb</titleabbrev> + + <preface xml:id="intro.chdb"> + &reftitle.intro; + <para> + CHDB (constant hash database) is a fast key-value database for constant data, + realized by using a memory-mapped file and thus providing the following + functionalities: + <itemizedlist spacing="compact"> + <listitem> + <para> + Extremely fast initial load, regardless of the size of the database. + </para> + </listitem> + <listitem> + <para> + Only the pages of the file which are actually used are loaded from the + disk. + </para> + </listitem> + <listitem> + <para> + Once a page is loaded it is shared across multiple processes. + </para> + </listitem> + <listitem> + <para> + Loaded pages are cached across multiple requests and even process recycling. + </para> + </listitem> + </itemizedlist> + </para> + <para> + A typical use of CHDB is as a faster alternative to defining many PHP + constants. + </para> + <para> + CHDB is internally implemented as a hash-table using a perfect hashing + function, thus guaranteeing worst case O(1) lookup time. + </para> + </preface> + + &reference.chdb.setup; + &reference.chdb.constants; + &reference.chdb.examples; + &reference.chdb.chdb; + &reference.chdb.reference; + +</book> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> Index: reference/chdb/constants.xml =================================================================== --- reference/chdb/constants.xml (revision 0) +++ reference/chdb/constants.xml (revision 0) @@ -0,0 +1,28 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<appendix xml:id="chdb.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + &reftitle.constants; + &no.constants; +</appendix> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> Index: reference/chdb/reference.xml =================================================================== --- reference/chdb/reference.xml (revision 0) +++ reference/chdb/reference.xml (revision 0) @@ -0,0 +1,30 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<reference xml:id="ref.chdb" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>chdb &Functions;</title> + + &reference.chdb.entities.functions; + +</reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> Index: reference/chdb/examples.xml =================================================================== --- reference/chdb/examples.xml (revision 0) +++ reference/chdb/examples.xml (revision 0) @@ -0,0 +1,73 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision$ --> + +<chapter xml:id="chdb.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + &reftitle.examples; + <example> + <title>Creating a chdb file</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$data = array( + 'key1' => 'value1', + 'key2' => 'value2', + // ... +); +chdb_create('data.chdb', $data); + +?> +]]> + </programlisting> + <para> + The above example will generate a chdb file named + <literal>data.chdb</literal> and containing the key-value pairs defined in + <varname>$data</varname>. + </para> + </example> + <example> + <title>Loading and looking up a chdb file</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$chdb = new chdb('data.chdb'); +$value1 = $chdb->get('key1'); +$value2 = $chdb->get('key2'); + +echo $value1, PHP_EOL; +echo $value2, PHP_EOL; + +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +value1 +value2 +]]> + </screen> + </example> +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> Index: appendices/extensions.xml =================================================================== --- appendices/extensions.xml (revision 300444) +++ appendices/extensions.xml (working copy) @@ -21,6 +21,7 @@ <listitem><simpara><xref linkend="book.bcompiler" /></simpara></listitem> <listitem><simpara><xref linkend="book.bzip2" /></simpara></listitem> <listitem><simpara><xref linkend="book.calendar" /></simpara></listitem> + <listitem><simpara><xref linkend="book.chdb" /></simpara></listitem> <listitem><simpara><xref linkend="book.classkit" /></simpara></listitem> <listitem><simpara><xref linkend="book.classobj" /></simpara></listitem> <listitem><simpara><xref linkend="book.com" /></simpara></listitem> @@ -310,6 +311,7 @@ <itemizedlist> <listitem><para><xref linkend="book.bbcode"/></para></listitem> <listitem><para><xref linkend="book.bzip2"/></para></listitem> + <listitem><para><xref linkend="book.chdb"/></para></listitem> <listitem><para><xref linkend="book.crack"/></para></listitem> <listitem><para><xref linkend="book.curl"/></para></listitem> <listitem><para><xref linkend="book.dbase"/></para></listitem> @@ -405,6 +407,7 @@ <listitem><para><xref linkend="book.apd"/></para></listitem> <listitem><para><xref linkend="book.bbcode"/></para></listitem> <listitem><para><xref linkend="book.bcompiler"/></para></listitem> + <listitem><para><xref linkend="book.chdb" /></para></listitem> <listitem><para><xref linkend="book.classkit"/></para></listitem> <listitem><para><xref linkend="book.crack"/></para></listitem> <listitem><para><xref linkend="book.cyrus"/></para></listitem>