help/manual/C/index.docbook

   1 <?xml version="1.0" standalone="no"?>
   2 <?xml-stylesheet type="text/xml" href="params.xsl"?>
   3 <!-- vim: set ai tw=80 ts=3 sw=3: -->
   4 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "
   5               http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   6
   7 <!ENTITY FDL SYSTEM "fdl-appendix.xml">
   8 <!ENTITY FDLlink "<link linkend='fdl'>included</link>">
   9 ]><!-- =============Document Header ============================= -->
  10 <book id="index">
  11   <bookinfo>
  12     <title>GTK-Doc Manual</title>
  13     <edition>1.24.1</edition>
  14     <abstract role="description"><para>User manual for developers with instructions of GTK-Doc usage.</para></abstract>
  15     <authorgroup>
  16       <author>
  17         <firstname>Chris</firstname>
  18         <surname>Lyttle</surname>
  19         <affiliation>
  20           <address>
  21             <email>chris@wilddev.net</email>
  22           </address>
  23         </affiliation>
  24       </author>
  25       <author>
  26         <firstname>Dan</firstname>
  27         <surname>Mueth</surname>
  28         <affiliation>
  29           <address>
  30             <email>d-mueth@uchicago.edu</email>
  31           </address>
  32         </affiliation>
  33       </author>
  34       <author>
  35         <firstname>Stefan</firstname>
  36         <surname>Sauer (Kost)</surname>
  37         <affiliation>
  38           <address>
  39             <email>ensonic@users.sf.net</email>
  40           </address>
  41         </affiliation>
  42       </author>
  43     </authorgroup>
  44     <publisher role="maintainer">
  45       <publishername>GTK-Doc project</publishername>
  46       <address><email>gtk-doc-list@gnome.org</email></address>
  47     </publisher>
  48     <copyright>
  49       <year>2000, 2005</year>
  50       <holder>Dan Mueth and Chris Lyttle</holder>
  51     </copyright>
  52     <copyright>
  53       <year>2007-2015</year>
  54       <holder>Stefan Sauer (Kost)</holder>
  55     </copyright>
  56
  57     <!-- translators: uncomment this:
  58     <copyright>
  59       <year>2000</year>
  60       <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  61     </copyright>
  62     -->
  63
  64     <legalnotice>
  65       <para>
  66         Permission is granted to copy, distribute and/or modify this
  67         document under the terms of the <citetitle>GNU Free Documentation
  68         License</citetitle>, Version 1.1 or any later version published
  69         by the Free Software Foundation with no Invariant Sections, no
  70         Front-Cover Texts, and no Back-Cover Texts. A copy of the license
  71         is &FDLlink;.
  72       </para>
  73       <para>
  74         Many of the names used by companies to distinguish their products and
  75         services are claimed as trademarks. Where those names appear in any
  76         GNOME documentation, and those trademarks are made aware to the members
  77         of the GNOME Documentation Project, the names have been printed in caps
  78         or initial caps.
  79       </para>
  80     </legalnotice>
  81
  82     <revhistory>
  83       <revision>
  84          <revnumber>1.28.1</revnumber>
  85          <date>24 Mar 2018</date>
  86          <authorinitials>ss</authorinitials>
  87          <revremark>development</revremark>
  88       </revision>
  89       <revision>
  90          <revnumber>1.28</revnumber>
  91          <date>24 Mar 2018</date>
  92          <authorinitials>ss</authorinitials>
  93          <revremark>bug fixes</revremark>
  94       </revision>
  95       <revision>
  96          <revnumber>1.27</revnumber>
  97          <date>07 Dec 2017</date>
  98          <authorinitials>ss</authorinitials>
  99          <revremark>fine tuning of the python port</revremark>
 100       </revision>
 101       <revision>
 102          <revnumber>1.26</revnumber>
 103          <date>11 Aug 2017</date>
 104          <authorinitials>ss</authorinitials>
 105          <revremark>port all tools from perl/bash to python</revremark>
 106       </revision>
 107       <revision>
 108         <revnumber>1.25</revnumber>
 109         <date>21 March 2016</date>
 110         <authorinitials>ss</authorinitials>
 111         <revremark>bug fixes, test cleanups</revremark>
 112       </revision>
 113       <revision>
 114         <revnumber>1.24</revnumber>
 115         <date>29 May 2015</date>
 116         <authorinitials>ss</authorinitials>
 117         <revremark>bug fix</revremark>
 118       </revision>
 119       <revision>
 120         <revnumber>1.23</revnumber>
 121         <date>17 May 2015</date>
 122         <authorinitials>ss</authorinitials>
 123         <revremark>bug fix</revremark>
 124       </revision>
 125       <revision>
 126         <revnumber>1.22</revnumber>
 127         <date>07 May 2015</date>
 128         <authorinitials>ss</authorinitials>
 129         <revremark>bug fixes, dropping deprecated features</revremark>
 130       </revision>
 131       <revision>
 132         <revnumber>1.21</revnumber>
 133         <date>17 Jul 2014</date>
 134         <authorinitials>ss</authorinitials>
 135         <revremark>bug fixes, dropping deprecated features</revremark>
 136       </revision>
 137       <revision>
 138         <revnumber>1.20</revnumber>
 139         <date>16 Feb 2014</date>
 140         <authorinitials>ss</authorinitials>
 141         <revremark>bug fixes, markdown support, style improvements</revremark>
 142       </revision>
 143       <revision>
 144         <revnumber>1.19</revnumber>
 145         <date>05 Jun 2013</date>
 146         <authorinitials>ss</authorinitials>
 147         <revremark>bug fixes</revremark>
 148       </revision>
 149       <revision>
 150         <revnumber>1.18</revnumber>
 151         <date>14 Sep 2011</date>
 152         <authorinitials>ss</authorinitials>
 153         <revremark>bug fixes, speedups, markdown support</revremark>
 154       </revision>
 155       <revision>
 156         <revnumber>1.17</revnumber>
 157         <date>26 Feb 2011</date>
 158         <authorinitials>sk</authorinitials>
 159         <revremark>urgent bug fix update</revremark>
 160       </revision>
 161       <revision>
 162         <revnumber>1.16</revnumber>
 163         <date>14 Jan 2011</date>
 164         <authorinitials>sk</authorinitials>
 165         <revremark>bugfixes, layout improvements</revremark>
 166       </revision>
 167       <revision>
 168         <revnumber>1.15</revnumber>
 169         <date>21 May 2010</date>
 170         <authorinitials>sk</authorinitials>
 171         <revremark>bug and regression fixes</revremark>
 172       </revision>
 173       <revision>
 174         <revnumber>1.14</revnumber>
 175         <date>28 March 2010</date>
 176         <authorinitials>sk</authorinitials>
 177         <revremark>bugfixes and performance improvements</revremark>
 178       </revision>
 179       <revision>
 180         <revnumber>1.13</revnumber>
 181         <date>18 December 2009</date>
 182         <authorinitials>sk</authorinitials>
 183         <revremark>broken tarball update</revremark>
 184       </revision>
 185       <revision>
 186         <revnumber>1.12</revnumber>
 187         <date>18 December 2009</date>
 188         <authorinitials>sk</authorinitials>
 189         <revremark>new tool features and bugfixes</revremark>
 190       </revision>
 191       <revision>
 192         <revnumber>1.11</revnumber>
 193         <date>16 November 2008</date>
 194         <authorinitials>mal</authorinitials>
 195         <revremark>GNOME doc-utils migration</revremark>
 196       </revision>
 197     </revhistory>
 198
 199   </bookinfo>
 200
 201   <!-- ======== Chapter 1: Introduction ======================== -->
 202
 203   <chapter id="introduction">
 204     <title>Introduction</title>
 205
 206     <para>
 207       This chapter introduces GTK-Doc and gives an overview of what it is and
 208       how it is used.
 209     </para>
 210
 211     <sect1 id="whatisgtkdoc">
 212       <title>What is GTK-Doc?</title>
 213
 214       <para>
 215         GTK-Doc is used to document C code. It is typically used to document the public
 216         API of libraries, such as the GTK+ and GNOME libraries. But it can also be
 217         used to document application code.
 218       </para>
 219     </sect1>
 220
 221     <sect1 id="howdoesgtkdocwork">
 222       <title>How Does GTK-Doc Work?</title>
 223
 224       <para>
 225         GTK-Doc works by using documentation of functions placed inside the source files in
 226         specially-formatted comment blocks, or documentation added to the template files
 227         which GTK-Doc uses (though note that GTK-Doc will only document functions that
 228         are declared in header files; it won't produce output for static functions).
 229       </para>
 230
 231       <para>
 232         GTK-Doc consists of a number of python scripts, each performing a different step
 233         in the process.
 234       </para>
 235
 236       <para>
 237         There are 5 main steps in the process:
 238       </para>
 239
 240       <orderedlist>
 241
 242         <listitem>
 243           <para>
 244             <guilabel>Writing the documentation.</guilabel>
 245
 246             The author fills in the source files with the documentation for each
 247             function, macro, union etc. (In the past information was entered in
 248             generated template files, which is not recommended anymore).
 249           </para>
 250         </listitem>
 251
 252         <listitem>
 253           <para>
 254             <guilabel>Gathering information about the code.</guilabel>
 255
 256             <application>gtkdoc-scan</application> scans the header files of the
 257             code looking for declarations of functions, macros, enums, structs, and unions.
 258             It creates the file <filename>&lt;module&gt;-decl-list.txt</filename> containing a list of the
 259             declarations, placing them into sections according to which header file they
 260             are in. On the first run this file is copied to <filename>&lt;module&gt;-sections.txt</filename>.
 261             The author can rearrange the sections, and the order of the
 262             declarations within them, to produce the final desired order.
 263             The second file it generates is <filename>&lt;module&gt;-decl.txt</filename>.
 264             This file contains the full declarations found by the scanner. If for
 265             some reason one would like some symbols to show up in the docs, where
 266             the full declaration cannot be found by the scanner or the declaration
 267             should appear differently, one can place entities similar to the ones in
 268             <filename>&lt;module&gt;-decl.txt</filename> into <filename>&lt;module&gt;-overrides.txt</filename>.
 269          </para>
 270          <para>
 271             <application>gtkdoc-scangobj</application> can also be used to dynamically query a library about
 272             any GObject subclasses it exports. It saves information about each
 273             object's position in the class hierarchy and about any GObject properties
 274             and signals it provides.
 275           </para>
 276          <para>
 277             <application>gtkdoc-scanobj</application> should not be used anymore.
 278             It was needed in the past when GObject was still GtkObject inside gtk+.
 279          </para>
 280         </listitem>
 281
 282         <listitem>
 283           <para>
 284             <guilabel>Generating the XML and HTML/PDF.</guilabel>
 285
 286             <application>gtkdoc-mkdb</application> turns the template files into
 287             XML files in the <filename class='directory'>xml/</filename> subdirectory.
 288             If the source code contains documentation on functions, using the
 289             special comment blocks, it gets merged in here. If there are no tmpl files used
 290             it only reads docs from sources and introspection data.
 291           </para>
 292           <para>
 293             <application>gtkdoc-mkhtml</application> turns the XML files into HTML
 294             files in the <filename class='directory'>html/</filename> subdirectory.
 295             Likewise <application>gtkdoc-mkpdf</application> turns the XML files into a PDF
 296             document called <filename>&lt;package&gt;.pdf</filename>.
 297           </para>
 298           <para>
 299             Files in <filename class='directory'>xml/</filename> and
 300             <filename class='directory'>html/</filename> directories are always
 301             overwritten. One should never edit them directly.
 302           </para>
 303         </listitem>
 304
 305         <listitem>
 306           <para>
 307             <guilabel>Fixing up cross-references between documents.</guilabel>
 308
 309             After installing the HTML files, <application>gtkdoc-fixxref</application> can be run to fix up any
 310             cross-references between separate documents. For example, the GTK+
 311             documentation contains many cross-references to types documented in the GLib manual.
 312
 313             When creating the source tarball for distribution, <application>gtkdoc-rebase</application>
 314             turns all external links into web-links. When installing distributed (pregenerated) docs
 315             the same application will try to turn links back to local links
 316             (where those docs are installed).
 317           </para>
 318         </listitem>
 319       </orderedlist>
 320
 321     </sect1>
 322
 323     <sect1 id="gettinggtkdoc">
 324       <title>Getting GTK-Doc</title>
 325
 326       <sect2 id="requirements">
 327         <title>Requirements</title>
 328         <para>
 329           <guilabel>python 2/3</guilabel> - the main scripts are written in python.
 330         </para>
 331         <para>
 332           <guilabel>xsltproc</guilabel> - the xslt processor from libxslt
 333           <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink>
 334         </para>
 335         <para>
 336           <guilabel>docbook-xsl</guilabel> - the docbook xsl stylesheets
 337           <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink>
 338         </para>
 339         <para>
 340           One of <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> or
 341           <guilabel>vim</guilabel> - optional - used for syntax highlighting of examples
 342         </para>
 343       </sect2>
 344     </sect1>
 345
 346     <sect1 id="aboutgtkdoc">
 347       <title>About GTK-Doc</title>
 348
 349       <para>
 350         (FIXME)
 351       </para>
 352
 353       <para>
 354         (History, authors, web pages, mailing list, license, future plans,
 355         comparison with other similar systems.)
 356       </para>
 357
 358     </sect1>
 359
 360     <sect1 id="aboutthismanual">
 361       <title>About this Manual</title>
 362
 363       <para>
 364         (FIXME)
 365       </para>
 366
 367       <para>
 368         (who it is meant for, where you can get it, license)
 369       </para>
 370
 371     </sect1>
 372
 373   </chapter>
 374
 375   <chapter id="settingup">
 376     <title>Setting up your project</title>
 377
 378     <para>
 379       The next sections describe what steps to perform to integrate GTK-Doc into
 380       your project. Theses sections assume we work on a project called 'meep'.
 381       This project contains a library called 'libmeep' and
 382       an end-user app called 'meeper'. We also assume you will be using autoconf
 383       and automake. In addition section <link linkend="plain_makefiles">plain
 384       makefiles or other build systems</link> will describe the basics needed to
 385       work in a different build setup.
 386     </para>
 387
 388     <sect1 id="settingup_docfiles">
 389       <title>Setting up a skeleton documentation</title>
 390
 391       <para>
 392         Under your top-level project directory create folders called docs/reference
 393         (this way you can also have docs/help for end-user documentation).
 394         It is recommended to create another subdirectory with the name of the doc-package.
 395         For packages with just one library this step is not necessary.
 396       </para>
 397
 398       <para>
 399         This can then look as shown below:
 400         <example><title>Example directory structure</title>
 401           <programlisting><![CDATA[
 402 meep/
 403   docs/
 404     reference/
 405       libmeep/
 406       meeper/
 407   src/
 408     libmeep/
 409     meeper/
 410 ]]></programlisting>
 411         </example>
 412       </para>
 413     </sect1>
 414
 415     <sect1 id="settingup_autoconf">
 416       <title>Integration with autoconf</title>
 417
 418       <para>
 419         Very easy! Just add one line to your <filename>configure.ac</filename> script.
 420       </para>
 421
 422       <para>
 423         <example><title>Integration with autoconf</title>
 424           <programlisting><![CDATA[
 425 # check for gtk-doc
 426 GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
 427 ]]></programlisting>
 428         </example>
 429       </para>
 430
 431       <para>
 432         This will require all developers to have gtk-doc installed. If it is
 433         okay for your project to have optional api-doc build setup, you can
 434         solve this as below. Keep it as is, as gtkdocize is looking for
 435         <function>GTK_DOC_CHECK</function>  at the start of a line.
 436         <example><title>Keep gtk-doc optional</title>
 437           <programlisting><![CDATA[
 438 # check for gtk-doc
 439 m4_ifdef([GTK_DOC_CHECK], [
 440 GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
 441 ],[
 442 AM_CONDITIONAL([ENABLE_GTK_DOC], false)
 443 ])
 444 ]]></programlisting>
 445         </example>
 446       </para>
 447
 448       <para>
 449         The first argument is used to check for the gtkdocversion at configure time.
 450         The 2nd, optional argument is used by <application>gtkdocize</application>.
 451         The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure switches:
 452       </para>
 453       <orderedlist>
 454         <listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>
 455         <listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>
 456         <listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>
 457         <listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>
 458       </orderedlist>
 459
 460       <important>
 461         <para>
 462           GTK-Doc is disabled by default! Remember to pass the option
 463           <option>'--enable-gtk-doc'</option> to the next
 464           <filename>configure</filename> run. Otherwise pregenerated documentation is installed
 465           (which makes sense for users but not for developers).
 466         </para>
 467       </important>
 468
 469       <para>
 470         Furthermore it is recommended that you have the following line inside
 471         your <filename>configure.ac</filename> script.
 472         This allows <application>gtkdocize</application> to automatically copy the
 473         macro definition for <function>GTK_DOC_CHECK</function> to your project.
 474       </para>
 475
 476       <para>
 477         <example><title>Preparation for gtkdocize</title>
 478           <programlisting><![CDATA[
 479 AC_CONFIG_MACRO_DIR(m4)
 480 ]]></programlisting>
 481         </example>
 482       </para>
 483       <para>
 484         After all changes to <filename>configure.ac</filename> are made, update
 485         the <filename>configure</filename> file. This can be done by re-running
 486         <code>autoreconf -i</code> or <code>autogen.sh</code>.
 487       </para>
 488     </sect1>
 489
 490     <sect1 id="settingup_automake">
 491       <title>Integration with automake</title>
 492
 493       <para>
 494         First copy the <filename>Makefile.am</filename> from the
 495         <filename class='directory'>examples</filename> sub directory of the
 496         <ulink url="https://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink>
 497         to your project's API documentation directory (
 498         <filename class='directory'>./docs/reference/&lt;package&gt;</filename>).
 499         A local copy should be available under e.g.
 500         <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>.
 501         If you have multiple doc-packages repeat this for each one.
 502       </para>
 503
 504       <para>
 505         The next step is to edit the settings inside the <filename>Makefile.am</filename>.
 506         All the settings have a comment above that describes their purpose.
 507         Most settings are extra flags passed to the respective tools. Every tool
 508         has a variable of the form <option>&lt;TOOLNAME&gt;_OPTIONS</option>.
 509         All the tools support <option>--help</option> to list the supported
 510         parameters.
 511       </para>
 512
 513       <!-- FIXME: explain options ? -->
 514
 515     </sect1>
 516
 517     <sect1 id="settingup_autogen">
 518       <title>Integration with autogen</title>
 519
 520       <para>
 521         Most projects will have an <filename>autogen.sh</filename> script to
 522         setup the build infrastructure after a checkout from version control
 523         system (such as cvs/svn/git). GTK-Doc comes with a tool called
 524         <application>gtkdocize</application> which can be used in such a script.
 525         It should be run before autoheader, automake or autoconf.
 526       </para>
 527
 528       <para>
 529         <example><title>Running gtkdocize from autogen.sh</title>
 530           <programlisting><![CDATA[
 531 gtkdocize || exit 1
 532 ]]></programlisting>
 533         </example>
 534       </para>
 535
 536       <para>
 537         When running <application>gtkdocize</application> it copies
 538         <filename>gtk-doc.make</filename> to your project root (or any directory
 539         specified by the <option>--docdir</option> option).
 540         It also checks you configure script for the <function>GTK_DOC_CHECK</function>
 541         invocation. This macro can be used to pass extra parameters to
 542         <application>gtkdocize</application>.
 543       </para>
 544
 545       <para>
 546         Historically GTK-Doc was generating template files where developers entered the docs.
 547         This turned out to be not so good (e.g. the need for having generated
 548         files under version control).
 549         Since GTK-Doc 1.9 the tools can get all the information from source comments
 550         and thus the templates can be avoided. We encourage people to keep
 551         documentation in the code. <application>gtkdocize</application> supports now
 552         a <option>--flavour no-tmpl</option> option that chooses a makefile that skips
 553         tmpl usage totally. Besides adding the option directly to the command
 554         invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>
 555         or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.
 556         If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,
 557         please remove the directory (e.g. from version control system).
 558       </para>
 559     </sect1>
 560
 561     <sect1 id="settingup_firstrun">
 562       <title>Running the doc build</title>
 563
 564       <para>
 565         After the previous steps it's time to run the build. First we need to
 566         rerun <filename>autogen.sh</filename>. If this script runs configure for
 567         you, then give it the <option>--enable-gtk-doc</option> option.
 568         Otherwise manually run <filename>configure</filename> with this option
 569         afterwards.
 570       </para>
 571       <para>
 572         The first make run generates several additional files in the doc-directories.
 573         The important ones are:
 574         <filename>&lt;package&gt;.types</filename>,
 575         <filename>&lt;package&gt;-docs.xml</filename> (in the past .sgml),
 576         <filename>&lt;package&gt;-sections.txt</filename>.
 577       </para>
 578       <para>
 579         <example><title>Running the doc build</title>
 580           <programlisting><![CDATA[
 581 ./autogen.sh --enable-gtk-doc
 582 make
 583 ]]></programlisting>
 584         </example>
 585       </para>
 586       <para>
 587         Now you can point your browser to <filename>docs/reference/&lt;package&gt;/index.html</filename>.
 588         Yes, it's a bit disappointing still. But hang-on, during the next chapter we
 589         tell you how to fill the pages with life.
 590       </para>
 591     </sect1>
 592
 593     <sect1 id="settingup_vcs">
 594       <title>Integration with version control systems</title>
 595
 596       <para>
 597         As a rule of thumb, it's the files you edit which should go under
 598         version control. For typical projects it's these files:
 599         <filename>&lt;package&gt;.types</filename>,
 600         <filename>&lt;package&gt;-docs.xml</filename> (in the past .sgml),
 601         <filename>&lt;package&gt;-sections.txt</filename>,
 602         <filename>Makefile.am</filename>.
 603       </para>
 604       <para>
 605         Files in the <filename>xml/</filename> and <filename>html/</filename>
 606         directories should not go under version control. Neither should any of
 607         the <filename>.stamp</filename> files.
 608       </para>
 609     </sect1>
 610
 611     <sect1 id="plain_makefiles">
 612       <title>Integration with plain makefiles or other build systems</title>
 613
 614       <para>
 615         In the case one does not want to use automake and therefore
 616         <filename>gtk-doc.mak</filename> one will need to call the gtkdoc tools
 617         in the right order in own makefiles (or other build tools).
 618       </para>
 619
 620       <para>
 621         <example><title>Documentation build steps</title>
 622           <programlisting><![CDATA[
 623 DOC_MODULE=meep
 624 // sources have changed
 625 gtkdoc-scan --module=$(DOC_MODULE) <source-dir>
 626 gtkdoc-scangobj --module=$(DOC_MODULE)
 627 gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>
 628 // xml files have changed
 629 mkdir html
 630 cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
 631 gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
 632 ]]></programlisting>
 633         </example>
 634       </para>
 635
 636       <para>
 637         One will need to look at the <filename>Makefile.am</filename> and
 638         <filename>gtk-doc.mak</filename> to pick the extra options needed.
 639       </para>
 640     </sect1>
 641
 642     <sect1 id="cmake">
 643        <title>Integration with CMake build systems</title>
 644
 645        <para>
 646           GTK-Doc now provides a <filename>GtkDocConfig.cmake</filename> module
 647           (and the corresponding <filename>GtkDocConfigVersion.cmake</filename>
 648           module). This provides a <literal>gtk_doc_add_module</literal>
 649           command that you can set in your <filename>CMakeLists.txt</filename>
 650           file.
 651        </para>
 652
 653        <para>
 654           The following example shows how to use this command.
 655           <example><title>Example of using GTK-Doc from CMake</title>
 656              <programlisting><![CDATA[
 657 find_package(GtkDoc 1.25 REQUIRED)
 658
 659 # Create the doc-libmeep target.
 660 gtk_doc_add_module(
 661    libmeep ${CMAKE_SOURCE_DIR}/libmeep
 662       XML meep-docs.xml
 663       LIBRARIES libmeep
 664 )
 665
 666 # Build doc-libmeep as part of the default target. Without this, you would
 667 # have to explicitly run something like `make doc-libmeep` to build the docs.
 668 add_custom_target(documentation ALL DEPENDS doc-libmeep)
 669
 670 # Install the docs. (This assumes you're using the GNUInstallDirs CMake module
 671 # to set the CMAKE_INSTALL_DOCDIR variable correctly).
 672 install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
 673         DESTINATION ${CMAKE_INSTALL_DOCDIR})
 674 ]]></programlisting>
 675          </example>
 676        </para>
 677      </sect1>
 678   </chapter>
 679
 680   <chapter id="documenting">
 681     <title>Documenting the code</title>
 682
 683     <para>
 684       GTK-Doc uses source code comment with a special syntax for code documentation.
 685       Further it retrieves information about your project structure from other
 686       sources. During the next section you will find all information about the
 687       syntax of the comments.
 688     </para>
 689
 690     <note>
 691       <title>Documentation placement</title>
 692       <para>
 693         In the past most documentation had to be filled into files residing
 694         inside the <filename>tmpl</filename> directory. This has the
 695         disadvantages that the information is often not updated and also that
 696         the file tend to cause conflicts with version control systems.
 697       </para>
 698       <para>
 699         The avoid the aforementioned problems we suggest putting the
 700         documentation inside the sources. This manual will only describe this
 701         way of documenting code.
 702       </para>
 703     </note>
 704
 705     <para>
 706       The scanner can handle the majority of C headers fine. In the case of
 707       receiving warnings from the scanner that look like a special case, one can
 708       hint GTK-Doc to skip over them.
 709       <example><title>GTK-Doc comment block</title>
 710         <programlisting><![CDATA[
 711 #ifndef __GTK_DOC_IGNORE__
 712 /* unparseable code here */
 713 #endif
 714 ]]></programlisting>
 715       </example>
 716     </para>
 717
 718     <note>
 719       <title>Limitations</title>
 720       <para>
 721         Note, that GTK-Doc's supports
 722         <code>#ifndef(__GTK_DOC_IGNORE__)</code> but not
 723         <code>#if !defined(__GTK_DOC_IGNORE__)</code> or other combinations.
 724       </para>
 725     </note>
 726
 727     <!--  -->
 728
 729     <sect1 id="documenting_syntax">
 730       <title>Documentation comments</title>
 731
 732       <para>
 733         A multiline comment that starts with an additional '*' marks a
 734         documentation block that will be processed by the GTK-Doc tools.
 735         <example><title>GTK-Doc comment block</title>
 736           <programlisting><![CDATA[
 737 /**
 738  * identifier:
 739  * documentation ...
 740  */
 741 ]]></programlisting>
 742         </example>
 743       </para>
 744
 745       <para>
 746         The 'identifier' is one line with the name of the item the comment is
 747         related to. The syntax differs a little depending on the item.
 748         (TODO add table showing identifiers)
 749       </para>
 750
 751       <para>
 752         The 'documentation' block is also different for each symbol type. Symbol
 753         types that get parameters such as functions or macros have the parameter
 754         description first followed by a blank line (just a '*').
 755         Afterwards follows the detailed description. All lines (outside program
 756         listings and CDATA sections) just containing a ' *' (blank-asterisk) are
 757         converted to paragraph breaks.
 758         If you don't want a paragraph break, change that into ' *  '
 759         (blank-asterisk-blank-blank). This is useful in preformatted text (code
 760         listings).
 761       </para>
 762
 763       <tip>
 764         <para>
 765           When documenting code, describe two aspects:
 766           <itemizedlist>
 767              <listitem>
 768                <para>
 769                  What it is: The name for a class or function can sometimes
 770                  be misleading for people coming from a different background.
 771                 </para>
 772              </listitem>
 773              <listitem>
 774                <para>
 775                  What it does: Tell about common uses. Put it in relation
 776                  with the other API.
 777                </para>
 778              </listitem>
 779            </itemizedlist>
 780         </para>
 781       </tip>
 782
 783       <para>
 784         One advantage of hyper-text over plain-text is the ability to have links
 785         in the document. Writing the correct markup for a link can be tedious
 786         though. GTK-Doc comes to help by providing several useful abbreviations.
 787         <itemizedlist>
 788           <listitem>
 789             <para>
 790               Use function() to refer to functions or macros which take arguments.
 791             </para>
 792           </listitem>
 793           <listitem>
 794             <para>
 795               Use @param to refer to parameters. Also use this when referring to
 796               parameters of other functions, related to the one being described.
 797             </para>
 798           </listitem>
 799           <listitem>
 800             <para>
 801               Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.
 802             </para>
 803           </listitem>
 804           <listitem>
 805             <para>
 806               Use #symbol to refer to other types of symbol, e.g. structs and
 807               enums and macros which don't take arguments.
 808             </para>
 809           </listitem>
 810           <listitem>
 811             <para>
 812               Use #Object::signal to refer to a GObject signal.
 813             </para>
 814           </listitem>
 815           <listitem>
 816             <para>
 817               Use #Object:property to refer to a GObject property.
 818             </para>
 819           </listitem>
 820           <listitem>
 821             <para>
 822               Use #Struct.field to refer to a field inside a structure and
 823               #GObjectClass.foo_bar() to refer to a vmethod.
 824             </para>
 825           </listitem>
 826         </itemizedlist>
 827       </para>
 828
 829       <tip>
 830         <para>
 831           If you need to use the special characters '&lt;', '&gt;', '()', '@',
 832           '%', or '#' in your documentation without GTK-Doc changing them you
 833           can use the XML entities "&amp;lt;", "&amp;gt;", "&amp;lpar;",
 834           "&amp;rpar;", "&amp;commat;", "&amp;percnt;" and "&amp;num;"
 835           respectively or escape them with a backslash '\'.
 836         </para>
 837       </tip>
 838
 839       <para>
 840         DocBook can do more than just links. One can also have lists,
 841         examples, headings, and images. As of version 1.20, the
 842         preferred way is to use a subset of the basic text formatting
 843         syntax called
 844         <ulink url="http://daringfireball.net/projects/markdown/">Markdown</ulink>.
 845         On older GTK-Doc versions any documentation that includes
 846         Markdown will be rendered as is.  For example, list items will
 847         appear as lines starting with a dash.
 848       </para>
 849
 850       <para>
 851         While markdown is now preferred one can mix both. One limitation here is
 852         that one can use docbook xml within markdown, but markdown within
 853         docbook xml is not supported.
 854       </para>
 855
 856       <para>
 857         In older GTK-Doc releases, if you need support for additional
 858         formatting, you would need to enable the usage of docbook
 859         XML tags inside doc-comments by putting <option>--xml-mode</option>
 860         (or <option>--sgml-mode</option>) in the variable
 861         <symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</filename>.
 862       </para>
 863
 864       <para>
 865         <example><title>GTK-Doc comment block using Markdown</title>
 866           <programlisting><![CDATA[
 867 /**
 868  * identifier:
 869  *
 870  * documentation paragraph ...
 871  *
 872  * # Sub Heading #
 873  *
 874  * ## Second Sub Heading
 875  *
 876  * # Sub Heading With a Link Anchor # {#heading-two}
 877  *
 878  * more documentation:
 879  *
 880  * - list item 1
 881  *
 882  *   Paragraph inside a list item.
 883  *
 884  * - list item 2
 885  *
 886  * 1. numbered list item
 887  *
 888  * 2. another numbered list item
 889  *
 890  * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)
 891  *
 892  * ![an inline image](plot-result.png)
 893  *
 894  * [A link to the heading anchor above][heading-two]
 895  *
 896  * A C-language example:
 897  * |[<!-- language="C" -->
 898  * GtkWidget *label = gtk_label_new ("Gorgeous!");
 899  * ]|
 900  */
 901 ]]></programlisting>
 902         </example>
 903       </para>
 904
 905       <para>
 906         More examples of what markdown tags are supported can be found in the
 907         <ulink url="https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown">GTK+ Documentation Markdown Syntax Reference</ulink>.
 908       </para>
 909
 910       <tip>
 911         <para>
 912           As already mentioned earlier GTK-Doc is for documenting public API. Thus
 913           one cannot write documentation for static symbols. Nevertheless it is good
 914           to comment those symbols too. This helps other to understand you code.
 915           Therefore we recommend to comment these using normal comments (without the
 916           2nd '*' in the first line).
 917           If later the function needs to be made public, all one needs to do is to
 918           add another '*' in the comment block and insert the symbol name at the
 919           right place inside the sections file.
 920         </para>
 921       </tip>
 922     </sect1>
 923
 924     <sect1 id="documenting_sections">
 925       <title>Documenting sections</title>
 926
 927       <para>
 928         Each section of the documentation contains information about one class
 929         or module. To introduce the component one can write a section block.
 930         The short description is also used inside the table of contents.
 931         All the @fields are optional.
 932       </para>
 933
 934       <para>
 935         <example><title>Section comment block</title>
 936           <programlisting><![CDATA[
 937 /**
 938  * SECTION:meepapp
 939  * @short_description: the application class
 940  * @title: Meep application
 941  * @section_id:
 942  * @see_also: #MeepSettings
 943  * @stability: Stable
 944  * @include: meep/app.h
 945  * @image: application.png
 946  *
 947  * The application class handles ...
 948  */
 949 ]]></programlisting>
 950         </example>
 951       </para>
 952
 953       <variablelist>
 954         <varlistentry>
 955           <term>SECTION:&lt;name&gt;</term>
 956           <listitem>
 957             <para>
 958               The name links the section documentation to the respective part in
 959               the <filename>&lt;package&gt;-sections.txt</filename> file. The
 960               name given here should match the &lt;FILE&gt; tag in the
 961               <filename>&lt;package&gt;-sections.txt</filename> file.
 962             </para>
 963           </listitem>
 964         </varlistentry>
 965         <varlistentry>
 966           <term>@short_description</term>
 967           <listitem>
 968             <para>
 969               A one line description of the section, that later will appear after
 970               the links in the TOC and at the top of the section page.
 971             </para>
 972           </listitem>
 973         </varlistentry>
 974         <varlistentry>
 975           <term>@title</term>
 976           <listitem>
 977             <para>
 978               The section title defaults to &lt;name&gt; from the SECTION
 979               declaration. It can be overridden with the @title field.
 980             </para>
 981           </listitem>
 982         </varlistentry>
 983         <varlistentry>
 984           <term>@section_id</term>
 985           <listitem>
 986             <para>
 987               Overrides the use of title as a section identifier. For GObjects
 988               the &lt;title&gt; is used as a section_id and for other sections
 989               it is &lt;MODULE&gt;-&lt;title&gt;.
 990             </para>
 991           </listitem>
 992         </varlistentry>
 993         <varlistentry>
 994           <term>@see_also</term>
 995           <listitem>
 996             <para>
 997               A list of symbols that are related to this section.
 998             </para>
 999           </listitem>
1000         </varlistentry>
1001         <varlistentry>
1002           <term>@stability</term>
1003           <listitem>
1004             <para>
1005               An informal description of the stability level this API has.
1006               We recommend the use of one of these terms:
1007               <itemizedlist>
1008                 <listitem>
1009                   <para>
1010                     Stable
1011                     - The intention of a Stable interface is to enable arbitrary
1012                     third parties to develop applications to these interfaces,
1013                     release them, and have confidence that they will run on all
1014                     minor releases of the product (after the one in which the
1015                     interface was introduced, and within the same major release).
1016                     Even at a major release, incompatible changes are expected
1017                     to be rare, and to have strong justifications.
1018                   </para>
1019                 </listitem>
1020                 <listitem>
1021                   <para>
1022                     Unstable
1023                     - Unstable interfaces are experimental or transitional.
1024                     They are typically used to give outside developers early
1025                     access to new or rapidly changing technology, or to provide
1026                     an interim solution to a problem where a more general
1027                     solution is anticipated.
1028                     No claims are made about either source or binary
1029                     compatibility from one minor release to the next.
1030                   </para>
1031                 </listitem>
1032                 <listitem>
1033                   <para>
1034                     Private
1035                     - An interface that can be used within the GNOME stack
1036                     itself, but that is not documented for end-users. Such
1037                     functions should only be used in specified and documented
1038                     ways.
1039                   </para>
1040                 </listitem>
1041                 <listitem>
1042                   <para>
1043                     Internal
1044                     - An interface that is internal to a module and does not
1045                     require end-user documentation. Functions that are
1046                     undocumented are assumed to be Internal.
1047                   </para>
1048                 </listitem>
1049               </itemizedlist>
1050             </para>
1051           </listitem>
1052         </varlistentry>
1053         <varlistentry>
1054           <term>@include</term>
1055           <listitem>
1056             <para>
1057               The <literal>#include</literal> files to show in the section
1058               synopsis (a comma separated list), overriding the global
1059               value from the <link linkend="metafiles_sections">section
1060               file</link> or command line.  This item is optional.
1061             </para>
1062           </listitem>
1063         </varlistentry>
1064         <varlistentry>
1065           <term>@image</term>
1066           <listitem>
1067             <para>
1068               The image to display at the top of the reference page for this
1069               section.  This will often be some sort of a diagram to illustrate
1070               the visual appearance of a class or a diagram of its relationship
1071               to other classes.  This item is optional.
1072             </para>
1073           </listitem>
1074         </varlistentry>
1075       </variablelist>
1076
1077       <tip>
1078         <para>
1079           To avoid unnecessary recompilation after doc-changes put the section
1080           docs into the c-source where possible.
1081         </para>
1082       </tip>
1083
1084     </sect1>
1085
1086     <sect1 id="documenting_symbols">
1087       <title>Documenting symbols</title>
1088
1089       <para>
1090         Each symbol (function, macro, struct, enum, signal and property) is
1091         documented in a separate block. The block is best placed close to the
1092         definition of the symbols so that it is easy to keep them in sync.
1093         Thus functions are usually documented in the c-source and macros,
1094         structs and enums in the header file.
1095       </para>
1096
1097       <sect2><title>General tags</title>
1098
1099         <para>
1100           You can add versioning information to all documentation elements to tell
1101           when an API was introduced, or when it was deprecated.
1102         </para>
1103
1104         <variablelist><title>Versioning Tags</title>
1105           <varlistentry><term>Since:</term>
1106             <listitem>
1107               <para>
1108                 Description since which version of the code the API is available.
1109               </para>
1110             </listitem>
1111           </varlistentry>
1112           <varlistentry><term>Deprecated:</term>
1113             <listitem>
1114               <para>
1115                 Paragraph denoting that this function should no be used anymore.
1116                 The description should point the reader to the new API.
1117               </para>
1118             </listitem>
1119           </varlistentry>
1120         </variablelist>
1121
1122         <para>
1123           You can also add stability information to all documentation elements
1124           to indicate whether API stability is guaranteed for them for all
1125           future minor releases of the project.
1126         </para>
1127
1128         <para>
1129           The default stability level for all documentation elements can be set
1130           by passing the <option>--default-stability</option> argument to
1131           <application>gtkdoc-mkdb</application> with one of the values below.
1132         </para>
1133
1134         <variablelist><title>Stability Tags</title>
1135           <varlistentry><term>Stability: Stable</term>
1136             <listitem>
1137               <para>
1138                 Mark the element as stable. This is for public APIs which are
1139                 guaranteed to remain stable for all future minor releases of the
1140                 project.
1141               </para>
1142             </listitem>
1143           </varlistentry>
1144           <varlistentry><term>Stability: Unstable</term>
1145             <listitem>
1146               <para>
1147                 Mark the element as unstable. This is for public APIs which are
1148                 released as a preview before being stabilised.
1149               </para>
1150             </listitem>
1151           </varlistentry>
1152           <varlistentry><term>Stability: Private</term>
1153             <listitem>
1154               <para>
1155                 Mark the element as private. This is for interfaces which can be
1156                 used by tightly coupled modules, but not by arbitrary third
1157                 parties.
1158               </para>
1159             </listitem>
1160           </varlistentry>
1161         </variablelist>
1162
1163         <example><title>General tags</title>
1164           <programlisting><![CDATA[
1165 /**
1166  * foo_get_bar:
1167  * @foo: some foo
1168  *
1169  * Retrieves @foo's bar.
1170  *
1171  * Returns: @foo's bar
1172  *
1173  * Since: 2.6
1174  * Deprecated: 2.12: Use foo_baz_get_bar() instead.
1175  */
1176 Bar *
1177 foo_get_bar(Foo *foo)
1178 {
1179 ...
1180 ]]></programlisting>
1181         </example>
1182       </sect2>
1183
1184       <sect2><title>Annotations</title>
1185
1186         <para>
1187           Documentation blocks can contain annotation-tags. These tags will be
1188           rendered with tooltips describing their meaning. The tags are used by
1189           gobject-introspection to generate language bindings. A detailed list
1190           of the supported tags can be found on
1191           <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">the wiki</ulink>.
1192         </para>
1193
1194         <example><title>Annotations</title>
1195           <programlisting><![CDATA[
1196 /**
1197  * foo_get_bar: (annotation)
1198  * @foo: (annotation): some foo
1199  *
1200  * Retrieves @foo's bar.
1201  *
1202  * Returns: (annotation): @foo's bar
1203  */
1204 ...
1205 /**
1206  * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)
1207  *                                    (and another annotation)
1208  * @foo: (annotation) (another annotation): some foo
1209  *
1210  * Sets bar on @foo.
1211  */
1212 ]]></programlisting>
1213         </example>
1214       </sect2>
1215
1216       <sect2><title>Function comment block</title>
1217
1218         <para>
1219           Please remember to:
1220           <itemizedlist>
1221             <listitem>
1222               <para>
1223                 Document whether returned objects, lists, strings, etc, should be
1224                 freed/unrefed/released.
1225               </para>
1226             </listitem>
1227             <listitem>
1228               <para>
1229                 Document whether parameters can be NULL, and what happens if they are.
1230               </para>
1231             </listitem>
1232             <listitem>
1233               <para>
1234                 Mention interesting pre-conditions and post-conditions where appropriate.
1235               </para>
1236             </listitem>
1237           </itemizedlist>
1238         </para>
1239
1240         <para>
1241           Gtk-doc assumes all symbols (macros, functions) starting with '_' are
1242           private. They are treated like static functions.
1243         </para>
1244
1245         <example><title>Function comment block</title>
1246           <programlisting><![CDATA[
1247 /**
1248  * function_name:
1249  * @par1:  description of parameter 1. These can extend over more than
1250  * one line.
1251  * @par2:  description of parameter 2
1252  * @...: a %NULL-terminated list of bars
1253  *
1254  * The function description goes here. You can use @par1 to refer to parameters
1255  * so that they are highlighted in the output. You can also use %constant
1256  * for constants, function_name2() for functions and #GtkWidget for links to
1257  * other declarations (which may be documented elsewhere).
1258  *
1259  * Returns: an integer.
1260  *
1261  * Since: 2.2
1262  * Deprecated: 2.18: Use other_function() instead.
1263  */
1264 ]]></programlisting>
1265         </example>
1266
1267         <variablelist><title>Function tags</title>
1268           <varlistentry><term>Returns:</term>
1269             <listitem>
1270               <para>
1271                 Paragraph describing the returned result.
1272               </para>
1273             </listitem>
1274           </varlistentry>
1275           <varlistentry><term>@...:</term>
1276             <listitem>
1277               <para>
1278                 In case the function has variadic arguments, you should use this
1279                 tag (@Varargs: does also work for historic reasons).
1280               </para>
1281             </listitem>
1282           </varlistentry>
1283         </variablelist>
1284
1285       </sect2>
1286
1287       <sect2><title>Property comment block</title>
1288
1289         <example><title>Property comment block</title>
1290           <programlisting><![CDATA[
1291 /**
1292  * SomeWidget:some-property:
1293  *
1294  * Here you can document a property.
1295  */
1296 g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
1297 ]]></programlisting>
1298         </example>
1299
1300       </sect2>
1301
1302       <sect2><title>Signal comment block</title>
1303
1304         <para>
1305           Please remember to:
1306           <itemizedlist>
1307             <listitem>
1308               <para>
1309                 Document when the signal is emitted and whether it is emitted before
1310                 or after other signals.
1311               </para>
1312             </listitem>
1313             <listitem>
1314               <para>
1315                 Document what an application might do in the signal handler.
1316               </para>
1317             </listitem>
1318           </itemizedlist>
1319         </para>
1320
1321         <example><title>Signal comment block</title>
1322           <programlisting><![CDATA[
1323 /**
1324  * FooWidget::foobarized:
1325  * @widget: the widget that received the signal
1326  * @foo: some foo
1327  * @bar: some bar
1328  *
1329  * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
1330  */
1331 foo_signals[FOOBARIZED] =
1332   g_signal_new ("foobarized",
1333                 ...
1334 ]]></programlisting>
1335         </example>
1336
1337       </sect2>
1338
1339       <sect2><title>Struct comment block</title>
1340         <example><title>Struct comment block</title>
1341           <programlisting><![CDATA[
1342 /**
1343  * FooWidget:
1344  * @bar: some #gboolean
1345  *
1346  * This is the best widget, ever.
1347  */
1348 typedef struct _FooWidget {
1349   GtkWidget parent_instance;
1350
1351   gboolean bar;
1352 } FooWidget;
1353 ]]></programlisting>
1354         </example>
1355
1356         <para>
1357           Use <code>/*&lt; private &gt;*/</code> before the private struct fields
1358           you want to hide. Use <code>/*&lt; public &gt;*/</code> for the reverse
1359           behaviour.
1360         </para>
1361
1362         <para>
1363           If the first field is "g_iface", "parent_instance" or "parent_class"
1364           it will be considered private automatically and doesn't need to be
1365           mentioned in the comment block.
1366         </para>
1367
1368         <para>
1369           Struct comment blocks can also be used for GObjects and GObjectClasses.
1370           It is usually a good idea to add a comment block for a class, if it has
1371           vmethods (as this is how they can be documented). For the GObject
1372           itself one can use the related section docs, having a separate block
1373           for the instance struct would be useful if the instance has public
1374           fields. One disadvantage here is that this creates two index entries
1375           of the same name (the structure and the section).
1376         </para>
1377
1378       </sect2>
1379
1380       <sect2><title>Enum comment block</title>
1381         <example><title>Enum comment block</title>
1382           <programlisting><![CDATA[
1383 /**
1384  * Something:
1385  * @SOMETHING_FOO: something foo
1386  * @SOMETHING_BAR: something bar
1387  *
1388  * Enum values used for the thing, to specify the thing.
1389  */
1390 typedef enum {
1391   SOMETHING_FOO,
1392   SOMETHING_BAR,
1393   /*< private >*/
1394   SOMETHING_COUNT
1395 } Something;
1396 ]]></programlisting>
1397         </example>
1398
1399         <para>
1400           Use <code>/*&lt; private &gt;*/</code> before the private enum values
1401           you want to hide. Use <code>/*&lt; public &gt;*/</code> for the reverse
1402           behaviour.
1403         </para>
1404
1405       </sect2>
1406     </sect1>
1407
1408
1409     <sect1 id="documenting_inline_program">
1410       <title>Inline program documentation</title>
1411       <para>
1412          You can document programs and their commandline interface using inline
1413          documentation.
1414       </para>
1415
1416       <variablelist>
1417       <title>Tags</title>
1418
1419       <varlistentry><term>PROGRAM</term>
1420
1421       <listitem>
1422       <para>
1423          Defines the start of a program documentation.
1424       </para>
1425       </listitem>
1426       </varlistentry>
1427
1428       <varlistentry>
1429       <term>@short_description:</term>
1430       <listitem>
1431       <para>
1432          Defines a short description of the program. (Optional)
1433       </para>
1434       </listitem>
1435       </varlistentry>
1436
1437       <varlistentry>
1438       <term>@synopsis:</term>
1439       <listitem>
1440       <para>
1441          Defines the arguments, or list of arguments that the program can take.
1442          (Optional)
1443       </para>
1444       </listitem>
1445       </varlistentry>
1446
1447       <varlistentry>
1448       <term>@see_also:</term>
1449       <listitem>
1450       <para>
1451           See Also manual page section. (Optional)
1452       </para>
1453       </listitem>
1454       </varlistentry>
1455
1456       <varlistentry>
1457       <term>@arg:</term>
1458       <listitem>
1459       <para>
1460           Argument(s) passed to the program and their description. (Optional)
1461       </para>
1462       </listitem>
1463       </varlistentry>
1464
1465       <varlistentry>
1466       <term>Description:</term>
1467       <listitem>
1468       <para>
1469           A longer description of the program.
1470       </para>
1471       </listitem>
1472       </varlistentry>
1473
1474       <varlistentry>
1475       <term>Returns:</term>
1476       <listitem>
1477       <para>
1478           Specificy what value(s) the program returns. (Optional)
1479       </para>
1480       </listitem>
1481       </varlistentry>
1482
1483       </variablelist>
1484
1485       <sect2>
1486         <title>Example of program documentation.</title>
1487         <example><title>Program documentation block</title>
1488         <programlisting><![CDATA[
1489 /**
1490  * PROGRAM:test-program
1491  * @short_description: A test program
1492  * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
1493  * @see_also: test(1)
1494  * @--arg1 *arg*: set arg1 to *arg*
1495  * @--arg2 *arg*: set arg2 to *arg*
1496  * @-v, --version: Print the version number
1497  * @-h, --help: Print the help message
1498  *
1499  * Long description of program.
1500  *
1501  * Returns: Zero on success, non-zero on failure
1502  */
1503 int main(int argc, char *argv[])
1504 {
1505         return 0;
1506 }
1507 ]]></programlisting>
1508         </example>
1509
1510       </sect2>
1511     </sect1>
1512
1513     <sect1 id="documenting_docbook">
1514       <title>Useful DocBook tags</title>
1515
1516       <para>
1517         Here are some DocBook tags which are most useful when documenting the
1518         code.
1519       </para>
1520
1521       <para>
1522         To link to another section in the GTK docs:
1523
1524         <informalexample>
1525           <programlisting><![CDATA[
1526 <link linkend="glib-Hash-Tables">Hash Tables</link>
1527 ]]></programlisting>
1528         </informalexample>
1529         The linkend is the SGML/XML id on the top item of the page you want to link to.
1530         For most pages this is currently the part ("gtk", "gdk", "glib") and then
1531         the page title ("Hash Tables"). For widgets it is just the class name.
1532         Spaces and underscores are converted to '-' to conform to SGML/XML.
1533       </para>
1534
1535       <para>
1536         To refer to an external function, e.g. a standard C function:
1537         <informalexample>
1538           <programlisting><![CDATA[
1539 <function>...</function>
1540 ]]></programlisting>
1541         </informalexample>
1542       </para>
1543
1544       <para>
1545         To include example code:
1546         <informalexample>
1547           <programlisting><![CDATA[
1548 <example>
1549   <title>Using a GHashTable.</title>
1550   <programlisting>
1551       ...
1552   </programlisting>
1553 </example>
1554 ]]></programlisting>
1555         </informalexample>
1556         or possibly this, for very short code fragments which don't need a title:
1557         <informalexample>
1558           <programlisting><![CDATA[
1559 <informalexample>
1560   <programlisting>
1561   ...
1562   </programlisting>
1563 </informalexample>
1564 ]]></programlisting>
1565         </informalexample>
1566         For the latter GTK-Doc also supports an abbreviation:
1567 <![CDATA[
1568 |[
1569   ...
1570 ]|
1571 ]]>
1572       </para>
1573
1574       <para>
1575         To include bulleted lists:
1576         <informalexample>
1577           <programlisting><![CDATA[
1578 <itemizedlist>
1579   <listitem>
1580     <para>
1581       ...
1582     </para>
1583   </listitem>
1584   <listitem>
1585     <para>
1586       ...
1587     </para>
1588   </listitem>
1589 </itemizedlist>
1590 ]]></programlisting>
1591         </informalexample>
1592       </para>
1593
1594       <para>
1595         To include a note which stands out from the text:
1596         <informalexample>
1597           <programlisting><![CDATA[
1598 <note>
1599   <para>
1600     Make sure you free the data after use.
1601   </para>
1602 </note>
1603 ]]></programlisting>
1604         </informalexample>
1605       </para>
1606
1607       <para>
1608         To refer to a type:
1609         <informalexample>
1610           <programlisting><![CDATA[
1611 <type>unsigned char</type>
1612 ]]></programlisting>
1613         </informalexample>
1614       </para>
1615
1616       <para>
1617         To refer to an external structure (not one described in the GTK docs):
1618         <informalexample>
1619           <programlisting><![CDATA[
1620 <structname>XFontStruct</structname>
1621 ]]></programlisting>
1622         </informalexample>
1623       </para>
1624
1625       <para>
1626         To refer to a field of a structure:
1627         <informalexample>
1628           <programlisting><![CDATA[
1629 <structfield>len</structfield>
1630 ]]></programlisting>
1631         </informalexample>
1632       </para>
1633
1634       <para>
1635         To refer to a class name, we could possibly use:
1636         <informalexample>
1637           <programlisting><![CDATA[
1638 <classname>GtkWidget</classname>
1639 ]]></programlisting>
1640         </informalexample>
1641         but you'll probably be using #GtkWidget instead (to automatically create
1642         a link to the GtkWidget page - see <link linkend="documenting_syntax">the abbreviations</link>).
1643       </para>
1644
1645       <para>
1646         To emphasize text:
1647         <informalexample>
1648           <programlisting><![CDATA[
1649 <emphasis>This is important</emphasis>
1650 ]]></programlisting>
1651         </informalexample>
1652       </para>
1653
1654       <para>
1655         For filenames use:
1656         <informalexample>
1657           <programlisting><![CDATA[
1658 <filename>/home/user/documents</filename>
1659 ]]></programlisting>
1660         </informalexample>
1661       </para>
1662
1663       <para>
1664         To refer to keys use:
1665         <informalexample>
1666           <programlisting><![CDATA[
1667 <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>
1668 ]]></programlisting>
1669         </informalexample>
1670       </para>
1671
1672     </sect1>
1673   </chapter>
1674
1675   <chapter id="metafiles">
1676     <title>Filling the extra files</title>
1677
1678     <para>
1679       There are a couple of extra files, that need to be maintained along with
1680       the inline source code comments:
1681       <filename>&lt;package&gt;.types</filename>,
1682       <filename>&lt;package&gt;-docs.xml</filename> (in the past .sgml),
1683       <filename>&lt;package&gt;-sections.txt</filename>.
1684     </para>
1685
1686     <sect1 id="metafiles_types">
1687       <title>Editing the types file</title>
1688
1689       <para>
1690         If your library or application includes GObjects, you want
1691         their signals, arguments/parameters and position in the hierarchy to be
1692         shown in the documentation. All you need to do, is to list the
1693         <function>xxx_get_type</function> functions together with their include
1694         inside the <filename>&lt;package&gt;.types</filename> file.
1695       </para>
1696
1697       <para>
1698         <example><title>Example types file snippet</title>
1699           <programlisting><![CDATA[
1700 #include <gtk/gtk.h>
1701
1702 gtk_accel_label_get_type
1703 gtk_adjustment_get_type
1704 gtk_alignment_get_type
1705 gtk_arrow_get_type
1706 ]]></programlisting>
1707         </example>
1708       </para>
1709
1710       <para>
1711         Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this list for you.
1712         Just add "--rebuild-types" to SCAN_OPTIONS in <filename>Makefile.am</filename>. If you
1713         use this approach you should not dist the types file nor have it under version control.
1714       </para>
1715
1716     </sect1>
1717
1718     <sect1 id="metafiles_master">
1719       <title>Editing the master document</title>
1720
1721       <para>
1722         GTK-Doc produces documentation in DocBook SGML/XML. When processing the
1723         inline source comments, the GTK-Doc tools generate one documentation
1724         page per class or module as a separate file. The master document
1725         includes them and place them in an order.
1726       </para>
1727
1728       <para>
1729         While GTK-Doc creates a template master document for you, later runs will
1730         not touch it again. This means that one can freely structure the
1731         documentation. That includes grouping pages and adding extra pages.
1732         GTK-Doc has now a test suite, where also the master-document is recreated from scratch.
1733         Its a good idea to look at this from time to time to see if there are
1734         some new goodies introduced there.
1735       </para>
1736
1737       <tip>
1738         <para>
1739           Do not create tutorials as extra documents. Just write extra chapters.
1740           The benefit of directly embedding the tutorial for your library into
1741           the API documentation is that it is easy to link for the tutorial to
1742           symbol documentation. Apart chances are higher that the tutorial gets
1743           updates along with the library.
1744         </para>
1745       </tip>
1746
1747       <para>
1748         So what are the things to change inside the master document? For a start
1749         is only a little. There are some placeholders (text in square brackets)
1750         there which you should take care of.
1751       </para>
1752
1753       <para>
1754         <example><title>Master document header</title>
1755           <programlisting><![CDATA[
1756 <bookinfo>
1757   <title>MODULENAME Reference Manual</title>
1758   <releaseinfo>
1759     for MODULENAME [VERSION]
1760     The latest version of this documentation can be found on-line at
1761     <ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>.
1762   </releaseinfo>
1763 </bookinfo>
1764
1765 <chapter>
1766   <title>[Insert title here]</title>
1767 ]]></programlisting>
1768         </example>
1769       </para>
1770
1771       <para>
1772         In addition a few option elements are created in commented form. You can
1773         review these and enable them as you like.
1774       </para>
1775
1776       <para>
1777         <example><title>Optional part in the master document</title>
1778           <programlisting><![CDATA[
1779   <!-- enable this when you use gobject introspection annotations
1780   <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
1781   -->
1782 ]]></programlisting>
1783         </example>
1784       </para>
1785
1786       <para>
1787         Finally you need to add new section whenever you introduce one. The
1788         <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> tool will
1789         remind you of newly generated xml files that are not yet included into
1790         the doc.
1791       </para>
1792
1793       <para>
1794         <example><title>Including generated sections</title>
1795           <programlisting><![CDATA[
1796   <chapter>
1797     <title>my library</title>
1798       <xi:include href="xml/object.xml"/>
1799       ...
1800 ]]></programlisting>
1801         </example>
1802       </para>
1803
1804     </sect1>
1805
1806     <sect1 id="metafiles_sections">
1807       <title>Editing the section file</title>
1808
1809       <para>
1810         The section file is used to organise the documentation output by
1811         GTK-Doc. Here one specifies which symbol belongs to which module or
1812         class and control the visibility (public or private).
1813       </para>
1814
1815       <para>
1816         The section file is a plain text file with tags delimiting sections.
1817         Blank lines are ignored and lines starting with a '#' are treated as
1818         comment lines.
1819       </para>
1820
1821       <note>
1822         <para>
1823           While the tags make the file look like xml, it is not. Please do not
1824           close tags like &lt;SUBSECTION&gt;.
1825         </para>
1826       </note>
1827
1828       <para>
1829         <example><title>Including generated sections</title>
1830           <programlisting><![CDATA[
1831 <INCLUDE>libmeep/meep.h</INCLUDE>
1832
1833 <SECTION>
1834 <FILE>meepapp</FILE>
1835 <TITLE>MeepApp</TITLE>
1836 MeepApp
1837 <SUBSECTION Standard>
1838 MEEP_APP
1839 ...
1840 MeepAppClass
1841 meep_app_get_type
1842 </SECTION>
1843 ]]></programlisting>
1844         </example>
1845       </para>
1846
1847       <para>
1848         The &lt;FILE&gt; ... &lt;/FILE&gt; tag is used to specify the file name,
1849         without any suffix. For example, using '&lt;FILE&gt;gnome-config&lt;/FILE&gt;'
1850         will result in the section declarations being output in the template
1851         file <filename>tmpl/gnome-config.sgml</filename>, which will be
1852         converted into the DocBook XML file <filename>xml/gnome-config.sgml</filename>
1853         or the DocBook XML file <filename>xml/gnome-config.xml</filename>.
1854         (The name of the HTML file is based on the module name and the section
1855         title, or for GObjects it is based on the GObjects class name converted
1856         to lower case).
1857       </para>
1858
1859       <para>
1860         The &lt;TITLE&gt; ... &lt;/TITLE&gt; tag is used to specify the title of
1861         the section. It is only useful before the templates (if used) are
1862         initially created, since the title set in the template file overrides
1863         this. Also if one uses SECTION comment in the sources, this is obsolete.
1864       </para>
1865
1866       <para>
1867         You can group items in the section by using the &lt;SUBSECTION&gt; tag.
1868         Currently it outputs a blank line between subsections in the synopsis
1869         section.
1870         You can also use &lt;SUBSECTION Standard&gt; for standard GObject
1871         declarations (e.g. the functions like g_object_get_type and macros like
1872         G_OBJECT(), G_IS_OBJECT() etc.).
1873         Currently these are left out of the documentation.
1874         You can also use &lt;SUBSECTION Private&gt; for private declarations
1875         which will not be output (it is a handy way to avoid warning messages
1876         about unused declarations).
1877         If your library contains private types which you don't want to appear in
1878         the object hierarchy and the list of implemented or required interfaces,
1879         add them to a Private subsection.
1880         Whether you would place GObject and GObjectClass like structs in public
1881         or Standard section depends if they have public entries (variables,
1882         vmethods).
1883       </para>
1884
1885       <para>
1886         You can also use &lt;INCLUDE&gt; ... &lt;/INCLUDE&gt; to specify the
1887         #include files which are shown in the synopsis sections.
1888         It contains a comma-separate list of #include files, without the angle
1889         brackets. If you set it outside of any sections, it acts for all
1890         sections until the end of the file. If you set it within a section, it
1891         only applies to that section.
1892       </para>
1893
1894     </sect1>
1895
1896   </chapter>
1897
1898   <chapter id="reports">
1899     <title>Controlling the result</title>
1900
1901     <para>
1902       A GTK-Doc run generates report files inside the documentation directory.
1903       The generated files are named:
1904       <filename>&lt;package&gt;-undocumented.txt</filename>,
1905       <filename>&lt;package&gt;-undeclared.txt</filename> and
1906       <filename>&lt;package&gt;-unused.txt</filename>.
1907       All those are plain text files that can be viewed and postprocessed easily.
1908     </para>
1909
1910     <para>
1911       The <filename>&lt;package&gt;-undocumented.txt</filename> file starts with
1912       the documentation coverage summary. Below are two sections divided by
1913       blank lines. The first section lists undocumented or incomplete symbols.
1914       The second section does the same for section docs. Incomplete entries are
1915       those, which have documentation, but where e.g. a new parameter has been
1916       added.
1917     </para>
1918
1919     <para>
1920       The <filename>&lt;package&gt;-undeclared.txt</filename> file lists symbols
1921       given in the <filename>&lt;package&gt;-sections.txt</filename> but not
1922       found in the sources. Check if they have been removed or if they are
1923       misspelled.
1924     </para>
1925
1926     <para>
1927       The <filename>&lt;package&gt;-unused.txt</filename> file lists symbol
1928       names, where the GTK-Doc scanner has found documentation, but does not
1929       know where to put it. This means that the symbol has not yet been added to
1930       the <filename>&lt;package&gt;-sections.txt</filename> file.
1931     </para>
1932
1933     <tip>
1934       <para>
1935         Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile.am.
1936         If at least GTK-Doc 1.9 is installed, this will run sanity checks during
1937         <command>make check</command> run.
1938       </para>
1939     </tip>
1940
1941     <para>
1942       One can also look at the files produced by the source code scanner:
1943       <filename>&lt;package&gt;-decl-list.txt</filename> and
1944       <filename>&lt;package&gt;-decl.txt</filename>. The first one can be
1945       compared with the section file if that is manually maintained. The second
1946       lists all declarations from the headers. If a symbol is missing one could
1947       check if this file contains it.
1948     </para>
1949
1950     <para>
1951       If the project is GObject based, one can also look into the files produced
1952       by the object scanner:
1953       <filename>&lt;package&gt;.args.txt</filename>,
1954       <filename>&lt;package&gt;.hierarchy.txt</filename>,
1955       <filename>&lt;package&gt;.interfaces.txt</filename>,
1956       <filename>&lt;package&gt;.prerequisites.txt</filename> and
1957       <filename>&lt;package&gt;.signals.txt</filename>. If there are missing
1958       symbols in any of those, one can ask GTK-Doc to keep the intermediate
1959       scanner file for further analysis, by running it as
1960       <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.
1961     </para>
1962   </chapter>
1963
1964   <chapter id="modernizing">
1965     <title>Modernizing the documentation</title>
1966
1967     <para>
1968       GTK-Doc has been around for quite some time. In this section we list new
1969       features together with the version since when it is available.
1970     </para>
1971
1972     <sect1 id="modernizing-gtk-doc-1-9">
1973       <title>GTK-Doc 1.9</title>
1974
1975       <para>
1976         When using xml instead of sgml, one can actually name the master
1977         document <filename>&lt;package&gt;-docs.xml</filename>.
1978       </para>
1979
1980       <para>
1981         This version supports <option>SCAN_OPTIONS=--rebuild-sections</option>
1982         in <filename>Makefile.am</filename>. When this is enabled, the
1983         <filename>&lt;package&gt;-sections.txt</filename> is autogenerated and
1984         can be removed from the vcs. This only works nicely for projects that
1985         have a very regular structure (e.g. each .{c,h} pair will create new
1986         section). If one organize a project close to that updating a manually
1987         maintained section file can be as simple as running
1988         <code>meld &lt;package&gt;-decl-list.txt &lt;package&gt;-sections.txt</code>.
1989       </para>
1990
1991       <para>
1992         Version 1.8 already introduced the syntax for documenting sections in
1993         the sources instead of the separate files under <filename class='directory'>tmpl</filename>.
1994         This version adds options to switch the whole doc module to not use the
1995         extra tmpl build step at all, by using <option>--flavour no-tmpl</option>
1996         in <filename>configure.ac</filename>. If you don't have a <filename class='directory'>tmpl</filename>
1997         checked into your source control system and haven't yet switched, just
1998         add the flag to <filename>configure.ac</filename> and you are done.
1999       </para>
2000     </sect1>
2001
2002     <sect1 id="modernizing-gtk-doc-1-10">
2003       <title>GTK-Doc 1.10</title>
2004
2005       <para>
2006         This version supports <option>SCAN_OPTIONS=--rebuild-types</option> in
2007         <filename>Makefile.am</filename>. When this is enabled, the
2008         <filename>&lt;package&gt;.types</filename> is autogenerated and can be
2009         removed from the vcs. When using this feature it is important to also
2010         setup the <varname>IGNORE_HFILES</varname> in
2011         <filename>Makefile.am</filename> for code that is build conditionally.
2012       </para>
2013     </sect1>
2014
2015     <sect1 id="modernizing-gtk-doc-1-16">
2016       <title>GTK-Doc 1.16</title>
2017
2018       <para>
2019         This version includes a new tool called gtkdoc-check. This tool can run
2020         a set of sanity checks on your documentation. It is enabled by adding
2021         these lines to the end of <filename>Makefile.am</filename>.
2022         <example><title>Enable gtkdoc-check</title>
2023           <programlisting><![CDATA[
2024 if ENABLE_GTK_DOC
2025 TESTS_ENVIRONMENT = \
2026   DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
2027   SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
2028 TESTS = $(GTKDOC_CHECK)
2029 endif
2030 ]]></programlisting>
2031         </example>
2032       </para>
2033     </sect1>
2034
2035     <sect1 id="modernizing-gtk-doc-1-20">
2036       <title>GTK-Doc 1.20</title>
2037
2038       <para>
2039         Version 1.18 brought some initial markdown support. Using markdown in
2040         doc comments is less intrusive than writing docbook xml. This version
2041         improves a lot on this and add a lot more styles. The section that
2042         explains the <link linkend="documenting_syntax">comment syntax</link>
2043         has all the details.
2044       </para>
2045     </sect1>
2046
2047     <sect1 id="modernizing-gtk-doc-1-25">
2048       <title>GTK-Doc 1.25</title>
2049
2050       <para>
2051         The makefiles shipped with this version generate an entity file at <filename>xml/gtkdocentities.ent</filename>,
2052         containing entities for e.g. package_name and package_version. You can
2053         use this e.g. in the main xml file to avoid hardcoding the version
2054         number. Below is an example that shows how the entity file is included
2055         and how the entities are used. The entities can also be used in all
2056         generated files, GTK-Doc will use the same xml header in generated xml
2057         files.
2058         <example><title>Use pre-generated entities</title>
2059           <programlisting><![CDATA[
2060 <?xml version="1.0"?>
2061 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
2062                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
2063 [
2064   <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
2065   <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
2066   %gtkdocentities;
2067 ]>
2068 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
2069   <bookinfo>
2070     <title>&package_name; Reference Manual</title>
2071     <releaseinfo>
2072       for &package_string;.
2073       The latest version of this documentation can be found on-line at
2074       <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
2075     </releaseinfo>
2076   </bookinfo>
2077 ]]></programlisting>
2078         </example>
2079       </para>
2080     </sect1>
2081   </chapter>
2082
2083   <chapter id="documenting-others">
2084     <title>Documenting other interfaces</title>
2085
2086     <para>
2087       So far we have been using GTK-Doc to document the API of code. The next
2088       sections contain suggestions how the tools can be used to document other
2089       interfaces too.
2090     </para>
2091
2092     <sect1 id="commandline-interfaces">
2093       <title>Command line options and man pages</title>
2094
2095       <para>
2096         As one can generate man pages for a docbook refentry as well, it sounds
2097         like a good idea to use it for that purpose. This way the interface is
2098         part of the reference and one gets the man-page for free.
2099       </para>
2100
2101       <sect2 id="commandline-interfaces-file">
2102         <title>Document the tool</title>
2103
2104         <para>
2105           Create one refentry file per tool. Following
2106           <link linkend="settingup_docfiles">our example</link> we would call it
2107           <filename>meep/docs/reference/meeper/meep.xml</filename>. For the xml
2108           tags that should be used and can look at generated file in the xml
2109           subdirectory as well as examples e.g. in glib.
2110         </para>
2111       </sect2>
2112
2113       <sect2 id="commandline-interfaces-configure">
2114         <title>Adding the extra configure check</title>
2115
2116         <para>
2117           <example><title>Extra configure checks</title>
2118             <programlisting><![CDATA[
2119 AC_ARG_ENABLE(man,
2120               [AC_HELP_STRING([--enable-man],
2121                               [regenerate man pages from Docbook [default=no]])],enable_man=yes,
2122               enable_man=no)
2123
2124 AC_PATH_PROG([XSLTPROC], [xsltproc])
2125 AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)
2126 ]]></programlisting>
2127           </example>
2128         </para>
2129       </sect2>
2130
2131       <sect2 id="commandline-interfaces-make">
2132         <title>Adding the extra makefile rules</title>
2133
2134         <para>
2135           <example><title>Extra configure checks</title>
2136             <programlisting><![CDATA[
2137 man_MANS = \
2138        meeper.1
2139
2140 if ENABLE_GTK_DOC
2141 if ENABLE_MAN
2142
2143 %.1 : %.xml
2144         @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
2145
2146 endif
2147 endif
2148
2149 BUILT_EXTRA_DIST = $(man_MANS)
2150 EXTRA_DIST += meep.xml
2151 ]]></programlisting>
2152           </example>
2153         </para>
2154       </sect2>
2155     </sect1>
2156
2157     <sect1 id="dbus-interfaces">
2158       <title>DBus interfaces</title>
2159
2160       <para>
2161         (FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html,
2162 http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)
2163       </para>
2164     </sect1>
2165
2166   </chapter>
2167
2168   <chapter id="faq">
2169     <title>Frequently asked questions</title>
2170
2171     <segmentedlist>
2172       <?dbhtml list-presentation="list"?>
2173       <segtitle>Question</segtitle>
2174       <segtitle>Answer</segtitle>
2175       <seglistitem>
2176         <seg>No class hierarchy.</seg>
2177         <seg>
2178           The objects <function>xxx_get_type()</function> function has not been
2179           entered into the <filename>&lt;package&gt;.types</filename> file.
2180         </seg>
2181       </seglistitem>
2182       <seglistitem>
2183         <seg>Still no class hierarchy.</seg>
2184         <seg>
2185           Missing or wrong naming in <filename>&lt;package&gt;-sections.txt</filename>
2186           file (see <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">explanation</ulink>).
2187         </seg>
2188       </seglistitem>
2189       <seglistitem>
2190         <seg>Damn, I have still no class hierarchy.</seg>
2191         <seg>
2192           Is the object name (name of the instance struct, e.g. <type>GtkWidget</type>)
2193           part of the normal section (don't put this into Standard or Private
2194           subsections).
2195         </seg>
2196       </seglistitem>
2197       <seglistitem>
2198         <seg>No symbol index.</seg>
2199         <seg>
2200           Does the <filename>&lt;package&gt;-docs.{xml,sgml}</filename> contain a
2201           index that xi:includes the generated index?
2202         </seg>
2203       </seglistitem>
2204       <seglistitem>
2205         <seg>Symbols are not linked to their doc-section.</seg>
2206         <seg>
2207           Is the doc-comment using the correct markup (added #,% or ())?
2208           Check if the gtkdoc-fixxref warns about unresolvable xrefs.
2209         </seg>
2210       </seglistitem>
2211       <seglistitem>
2212         <seg>A new class does not appear in the docs.</seg>
2213         <seg>
2214           Is the new page xi:included from
2215           <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.
2216         </seg>
2217       </seglistitem>
2218       <seglistitem>
2219         <seg>A new symbol does not appear in the docs.</seg>
2220         <seg>
2221           Is the doc-comment properly formatted. Check for spelling mistakes in
2222           the begin of the comment. Check if the gtkdoc-fixxref warns about
2223           unresolvable xrefs. Check if the symbol is correctly listed in the
2224           <filename>&lt;package&gt;-sections.txt</filename> in a public subsection.
2225         </seg>
2226       </seglistitem>
2227       <seglistitem>
2228         <seg>A type is missing from the class hierarchy.</seg>
2229         <seg>
2230           If the type is listed in <filename>&lt;package&gt;.hierarchy</filename>
2231           but not in <filename>xml/tree_index.sgml</filename> then double check
2232           that the type is correctly placed in the <filename>&lt;package&gt;-sections.txt</filename>.
2233           If the type instance (e.g. <type>GtkWidget</type>) is not listed or
2234           incidentally marked private it will not be shown.
2235         </seg>
2236       </seglistitem>
2237       <seglistitem>
2238         <seg>I get foldoc links for all gobject annotations.</seg>
2239         <seg>
2240           Check that <filename>xml/annotation-glossary.xml</filename> is
2241           xi:included from <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.
2242         </seg>
2243       </seglistitem>
2244
2245       <!-- gtk-doc warnings: -->
2246       <seglistitem>
2247         <seg>Parameter described in source code comment block but does not exist</seg>
2248         <seg>Check if the prototype in the header has different parameter names as in the source.</seg>
2249       </seglistitem>
2250
2251       <!-- docbook warnings: -->
2252       <seglistitem>
2253         <seg>multiple "IDs" for constraint linkend: XYZ</seg>
2254         <seg>Symbol XYZ appears twice in <filename>&lt;package&gt;-sections.txt</filename> file.</seg>
2255       </seglistitem>
2256       <seglistitem>
2257         <seg>Element typename in namespace '' encountered in para, but no template matches.</seg>
2258         <seg />
2259       </seglistitem>
2260     </segmentedlist>
2261   </chapter>
2262
2263   <chapter id="contrib">
2264     <title>Tools related to gtk-doc</title>
2265
2266     <para>
2267       GtkDocPlugin - a <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink>
2268       integration plugin, that adds API docs to a trac site and integrates with
2269       the trac search.
2270     </para>
2271     <para>
2272       Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since
2273       tags in the API to determine the minimum required version.
2274     </para>
2275
2276   </chapter>
2277
2278   <!-- ======== Appendix: FDL ================================== -->
2279   &FDL;
2280
2281 </book>
2282