<?xml version="1.0" encoding="utf-8" standalone="no"?>
<?xml-stylesheet type="text/xml" href="params.xsl"?>
<!-- vim: set ai tw=80 ts=3 sw=3: -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "
              http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY FDL SYSTEM "fdl-appendix.xml">
<!ENTITY FDLlink "<link linkend='fdl'>included</link>">
]>
<!-- =============Document Header ============================= -->
<book id="index" lang="gtk-doc-manual-cs">
  <bookinfo>
    <title>Příručka ke GTK-Doc</title>
    <edition>1.24.1</edition>
    <abstract role="description"><para>Uživatelská příručka pro vývojáře s instrukcemi k používání GTK-Doc.</para></abstract>
    <authorgroup>
      <author><firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation><address><email>chris@wilddev.net</email></address></affiliation></author>
      <author><firstname>Dan</firstname> <surname>Mueth</surname> <affiliation><address><email>d-mueth@uchicago.edu</email></address></affiliation></author>
      <author><firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> <affiliation><address><email>ensonic@users.sf.net</email></address></affiliation></author>
    </authorgroup>
    <publisher role="maintainer"><publishername>Projekt GTK-Doc</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
    <copyright><year>2000, 2005</year> <holder>Dan Mueth and Chris Lyttle</holder></copyright>
    <copyright><year>2007-2019</year> <holder>Stefan Sauer (Kost)</holder></copyright>

    <!-- translators: uncomment this:
    <copyright>
      <year>2000</year>
      <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
    </copyright>
    -->

    <legalnotice>
      <para>Je povoleno kopírovat, šířit a/nebo upravovat tento dokument za podmínek <citetitle>GNU Free Documentation License</citetitle> ve verzi 1.1 nebo v jakékoli další verzi vydané nadací Free Software Foundation, s neměnnými oddíly, bez textů předních desek a bez textů zadních desek. Kopie licence je <link linkend="fdl">součástí</link>.</para>
      <para>Mnoho názvů použitých firmami k zviditelnění produktů nebo služeb jsou ochranné známky. Na místech, kde jsou tyto názvy v dokumentaci použity a členové Dokumentačního projektu GNOME jsou si vědomi skutečnosti, že se jedná o ochrannou známku, je takovýto název psán velkými písmeny celý nebo s velkým písmenem na začátku.</para>
    </legalnotice>

    <revhistory>
      <revision><revnumber>1.33.0</revnumber> <date>1. října 2020</date> <authorinitials>mc</authorinitials> <revremark>verze gtk4</revremark></revision>
      <revision><revnumber>1.32.1</revnumber> <date>15. srpna 2019</date> <authorinitials>ss</authorinitials> <revremark>vývojová verze</revremark></revision>
      <revision><revnumber>1.32</revnumber> <date>15. srpna 2019</date> <authorinitials>ss</authorinitials> <revremark>opravné vydání</revremark></revision>
      <revision><revnumber>1.31</revnumber> <date>5. srpna 2019</date> <authorinitials>ss</authorinitials> <revremark>přepracování a větší pokrytí testy</revremark></revision>
      <revision><revnumber>1.30</revnumber> <date>8. května 2019</date> <authorinitials>ss</authorinitials> <revremark>větší pokrytí testy</revremark></revision>
      <revision><revnumber>1.29</revnumber> <date>28. srpna 2018</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb</revremark></revision>
      <revision><revnumber>1.28</revnumber> <date>24. března 2018</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb</revremark></revision>
      <revision><revnumber>1.27</revnumber> <date>7. prosince 2017</date> <authorinitials>ss</authorinitials> <revremark>detailní vyladění portu v jazyce Python</revremark></revision>
      <revision><revnumber>1.26</revnumber> <date>11. srpen 2017</date> <authorinitials>ss</authorinitials> <revremark>přenesení všech nástrojů z jazyků Perl/Bash do jazyka Python</revremark></revision>
      <revision><revnumber>1.25</revnumber> <date>21. březen 2016</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb, pročištění testů</revremark></revision>
      <revision><revnumber>1.24</revnumber> <date>29. května 2015</date> <authorinitials>ss</authorinitials> <revremark>oprava chyby</revremark></revision>
      <revision><revnumber>1.23</revnumber> <date>17. květen 2015</date> <authorinitials>ss</authorinitials> <revremark>oprava chyby</revremark></revision>
      <revision><revnumber>1.22</revnumber> <date>07. květen 2015</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb, odstranění zastaralých věcí</revremark></revision>
      <revision><revnumber>1.21</revnumber> <date>17. červenec 2014</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb, odstranění zastaralých věcí</revremark></revision>
      <revision><revnumber>1.20</revnumber> <date>16. únor 2014</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb, podpora značkovacího jazyka, vylepšení stylů</revremark></revision>
      <revision><revnumber>1.19</revnumber> <date>05. červen 2013</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb</revremark></revision>
      <revision><revnumber>1.18</revnumber> <date>14. září 2011</date> <authorinitials>ss</authorinitials> <revremark>opravy chyb, zrychlení, podpora značkovacího jazyka</revremark></revision>
      <revision><revnumber>1.17</revnumber> <date>26. únor 2011</date> <authorinitials>sk</authorinitials> <revremark>aktualizace kvůli neodkladné opravě chyby</revremark></revision>
      <revision><revnumber>1.16</revnumber> <date>14. leden 2011</date> <authorinitials>sk</authorinitials> <revremark>opravy chyb, vylepšení vzhledu</revremark></revision>
      <revision><revnumber>1.15</revnumber> <date>21. květen 2010</date> <authorinitials>sk</authorinitials> <revremark>opravy chyb a regresí</revremark></revision>
      <revision><revnumber>1.14</revnumber> <date>28. březen 2010</date> <authorinitials>sk</authorinitials> <revremark>opravy chyb a vylepšení výkonu</revremark></revision>
      <revision><revnumber>1.13</revnumber> <date>18. prosinec 2009</date> <authorinitials>sk</authorinitials> <revremark>aktualizace poškozeného balíčku</revremark></revision>
      <revision><revnumber>1.12</revnumber> <date>18. prosinec 2009</date> <authorinitials>sk</authorinitials> <revremark>nové funkce nástroje a opravy chyb</revremark></revision>
      <revision><revnumber>1.11</revnumber> <date>16. listopad 2008</date> <authorinitials>mal</authorinitials> <revremark>přechod na doc-utils z GNOME</revremark></revision>
    </revhistory>

  </bookinfo>

  <!-- ======== Chapter 1: Introduction ======================== -->

  <chapter id="introduction">
    <title>Úvod</title>

    <para>Tato kapitola je úvodem do GTK-Doc a podává přehled o tom, co to je a jak to použít.</para>

    <sect1 id="whatisgtkdoc">
      <title>Co je to GTK-Doc?</title>

      <para>GTK-Doc se používá k dokumentaci kódu jazyka C. Typické použití je pro dokumentaci veřejného API knihoven, jako jsou knihovny GTK+ a GNOME. Lze jej ale použít i k dokumentaci aplikačního kódu.</para>
    </sect1>

    <sect1 id="howdoesgtkdocwork">
      <title>Jak GTK-Doc pracuje?</title>

      <para>GTK-Doc pracuje na základě dokumentace funkcí umístěné přímo v souborech se zdrojovým kódem ve speciálně formátovaných komentářových blocích, nebo dokumentace přidané do souborů šablon, které GTK-Doc používá (ačkoliv je nutno poznamenat, že GTK-Doc dokumentuje pouze funkce, které jsou deklarované v hlavičkových souborech; pro statické funkce žádný výstup nevytváří).</para>

      <para>GTK-Doc sestává z řady skriptů v jazyce Python, z nichž každý provádí jinou část procesu.</para>

      <para>Celý proces se skládá z pěti hlavních kroků:</para>

      <orderedlist>

        <listitem>
          <para><guilabel>Psaní dokumentace.</guilabel> Autor doplní soubory se zdrojovým kódem s dokumentací pro každou funkci, makro, strukturu, výčet atd.</para>
        </listitem>

        <listitem>
          <para><guilabel>Shromáždění informací o kódu.</guilabel> <application>gtkdoc-scan</application> projde hlavičkové soubory kódu a vyhledá při tom deklarace funkcí, maker, výčtů, struktur a sjednocení. Tím se vytvoří soubor <filename>&lt;module&gt;-decl-list.txt</filename> obsahující seznam deklarací, které jsou rozdělené do oddílů podle hlavičkového souboru, ze kterého pochází. Při prvním spuštění se tento soubor zkopíruje do <filename>&lt;module&gt;-sections.txt</filename>. Autor může změnit uspořádání oddílů a jejich pořadí v rámci deklarací tak, jak to požaduje ve výsledku. Druhý soubor, který se vytvoří, je <filename>&lt;module&gt;-decl.txt</filename>. Tento soubor obsahuje úplné deklarace nalezené při procházení. Pokud byste z nějakého důvodu chtěli v dokumentaci zahrnout symbol, který při procházení nebyl nalezen, nebo jeho deklarace vypadá jinak, můžete jej umístit podobně jako v <filename>&lt;module&gt;-decl.txt</filename> do <filename>&lt;module&gt;-overrides.txt</filename>.</para>
         <para>Dá se také použít <application>gtkdoc-scanobj</application> k dynamickým dotazům do knihoven na podtřídy objektu GObject, které exportují. Tím se uloží informace o pozici každého objektu v hierarchii tříd a o argumentech a signálech objektu GObject, které poskytují.</para>
         <para><application>gtkdoc-scanobj</application> by se ale již používat nemělo. Bylo zapotřebí v minulosti, kdy byl GObject ještě GtkObject v rámci gtk+.</para>
        </listitem>

        <listitem>
          <para><guilabel>Generování XML a HTML/PDF.</guilabel> <application>gtkdoc-mkdb</application> přemění soubory šablon na soubory XML v podsložce <filename class="directory">xml/</filename>. Pokud zdrojový kód obsahuje dokumentaci funkcí za použití speciálních komentářových bloků, tak zde se sloučí. V případě, že není použitý žádný soubor šablon, načte se dokumentace pouze ze zdrojového kódu a introspektivních dat.</para>
          <para><application>gtkdoc-mkhtml</application> převádí soubory XML na soubory HTML v podsložce <filename class="directory">html/</filename>. Obdobně <application>gtkdoc-mkpdf</application> převádí soubory XML na dokument PDF nazvaný <filename>&lt;balíček&gt;.pdf</filename>.</para>
          <para>Soubory ve složkách <filename class="directory">xml/</filename> a <filename class="directory">html/</filename> jsou vždy přepsány. Nikdy by neměly být upravovány přímo.</para>
        </listitem>

        <listitem>
          <para><guilabel>Opravy křížových odkazů mezi dokumenty.</guilabel> Po nainstalování souborů HTML můžete spustit <application>gtkdoc-fixxref</application>, aby se opravily křížové odkazy mezi samostanými dokumenty. Například dokumentace GTK+ obsahuje křížové odkazy na typy zdokumentované v příručce GLib. Když vytváříte zdrojový balíček pro distribuci, <application>gtkdoc-rebase</application> předělá všechny externí odkazy na webové odkazy. Když se distribuovaná (předgenerovaná) dokumentace instaluje, pokusí se tatáž aplikace předělat odkazy zpátky na místní odkazy (na dokumenty, které jsou nainstalované).</para>
        </listitem>
      </orderedlist>

    </sect1>

    <sect1 id="gettinggtkdoc">
      <title>Jak získat GTK-Doc?</title>

      <sect2 id="requirements">
        <title>Požadavky</title>
        <para><guilabel>Python 2/3</guilabel> – hlavní skripty jsou v jazyce Python.</para>
        <para><guilabel>xsltproc</guilabel> – procesor xslt z knihovny libxslt <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink></para>
        <para><guilabel>docbook-xsl</guilabel> – stylopisy XSL pro docbook <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink></para>
        <para>Něco z <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> nebo <guilabel>vim</guilabel> – (volitelné) používá se pro zvýraznění syntaxe u příkladů</para>
      </sect2>
    </sect1>

    <sect1 id="aboutgtkdoc">
      <title>O aplikaci GTK-Doc</title>

      <para>Historicky se GTK-Doc používalo ke generování šablonových souborů ze zdrojových kódů. Tyto šablonové soubory pak mohli vývojáři používat ke vkládání dokumentace k API. Tento postup byl dosti nepohodlný, protože vyžadovat udržování vygenerovaných souborů ve správě verzí. Proto od verze 1.9 přichází GTK-Doc s možností vkládat všechny informace o API do komentářů ve zdrojových kódech, čímž se podpora šablon stává nadbytečnou. Ve verzi 1.26 byla podpora šablon odstraněna.</para>

      <para>(DOPLNIT)</para>

      <para>(autoři, webové stránky, poštovní konference, licence, plány do budoucna, srovnání s ostatními podobnými systémy.)</para>

    </sect1>

    <sect1 id="aboutthismanual">
      <title>O této příručce</title>

      <para>(DOPLNIT)</para>

      <para>(k čemu je určená, kde ji můžete získat, licence)</para>

    </sect1>

  </chapter>

  <chapter id="settingup">
    <title>Nastavení projektu</title>

    <para>Tato kapitola popisuje kroky, které jsou nutné pro integraci GTK-Doc do vašeho projektu. Integrace GTK-Doc do projektu zahrnuje následující kroky:</para>

    <itemizedlist>
      <listitem>
        <para>Přípravu struktury složek a vytvoření požadovaných konfiguračních souborů pro dokumentaci GTK-Doc (viz <link linkend="settingup_docfiles">Nastavení kostry dokumentace</link>).</para>
      </listitem>
      <listitem>
        <para>Přizpůsobení sestavovacího systému, aby sestavoval vaši dokumentaci pomocí nástrojů GTK-Doc. Je podporováno více sestavovacích systémů, v této příručce je popsáno, jak integrovat GTK-Doc s <link linkend="settingup_autotools">Autotools</link>, <link linkend="settingup_cmake">CMake</link> a <link linkend="settingup_plain_makefiles">prostými soubory Makefiles</link>.</para>
      </listitem>
      <listitem>
        <para>Přidání souborů specifických pro GTK-Doc do správy verzí a rozhodnutí, které soubory se mají ignorovat (viz <link linkend="settingup_vcs">Integrace se systémem správy verzí</link>).</para>
      </listitem>
    </itemizedlist>

    <para>Následující oddíly předpokládají, že pracujeme na projektu nazvaném <code>meep</code>. Tento projekt obsahuje dva balíčky (nebo moduly), knihovnu nazvanou <code>libmeep</code> a uživatelskou aplikaci nazvanou <code>meeper</code>.</para>

    <sect1 id="settingup_docfiles">
      <title>Nastavení kostry dokumentace</title>

      <para>Zaběhnutým zvykem je umístit dokumentaci do složky nazvané <code>docs</code> ve složce nejvyšší úrovně projektu. Obvykle rozlišujeme mezi <emphasis>referenční dokumentací</emphasis> zaměřenou na vývojáře a <emphasis>uživatelskou příručkou</emphasis> zaměřenou na koncového uživatele. Opět je zvykem mít zvláštní složku pro každou z obou zmíněných. Obvykle umisťujeme referenční dokumentaci do složky nazvané <code>reference</code> a uživatelskou příručku do složky nazvané <code>help</code>. V souladu se zmíněnými zvyky by dokumentace pro naši knihovnu <code>libmeep</code> byla umístěna do <code>docs/reference/libmeep</code>. U balíčků s jedinou knihovnou nebo referenční dokumentací by bylo možné ji umístit přímo do <code>docs/reference</code>. Není povinné použít uvedenou konvenci, ale pokud se rozhodnete použít jinou strukturu složek, musíte upravit konfiguraci sestavovacího systému, aby se s ní shodoval.</para>

      <para>V následujících oddílech budeme uvažovat strukturu složek pro náš projekt <emphasis>meep</emphasis>, který používá výše uvedené konvence. <example>
          <title>Příklad struktury složek projektu <emphasis>meep</emphasis></title>
          <programlisting>
meep/
  docs/
    reference/  # referenční dokumentace
      libmeep/
      meeper/
    help/       # volitelné: uživatelská příručka
      meeper/
  src/
    libmeep/
    meeper/
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="settingup_autotools">
      <title>Integrace s Autotools</title>
      <para>Integrace GTK-Doc do sestavovacího systému založeného na Autotools vyžaduje následující kroky:</para>
      <itemizedlist>
        <listitem>
          <para>Zajistit, že <application>gtkdocize</application> se spustí právě jednou před skriptem <filename>configure</filename>. Pokud je přítomen skript <filename>autogen.sh</filename>, upravte jej, aby kontroloval GTK-Doc a přidejte volání <application>gtkdocize</application>.</para>

          <para>Hlavním účelem <application>gtkdocize</application> je vytvořit Makefile <filename>gtk-doc.make</filename> a definici makra <filename>gtk-doc.m4</filename> dostupnou sestavovacímu systému, buď zkopírováním do projektu nebo vytvořením odkazu.</para>
        </listitem>
        <listitem>
          <para>Přidat potřebná makra <application>autoconf</application> do <filename>configure.ac</filename>, abyste povolili GTK-Doc v sestavovacím systému a konfigurace GTK-Doc mohla jít přes generovaný skript <filename>configure</filename>.</para>
          <para>Mimo jiné pomocí registrace přepínače <code>--enable-gtk-doc</code> ve skriptu <filename>configure</filename>.</para>
        </listitem>
        <listitem>
          <para>Vytvořit skript <application>automake</application> pro jednotlivé aplikace a knihovny ve svém projektu. V příkladu použitém v této dokumentaci je tento krok použit jak pro <code>meeper</code>, tak pro <code>libmeep</code>.</para>
        </listitem>
      </itemizedlist>

      <para>V následujícím oddíle provedeme výše zmíněné kroky v opačném pořadí. Začneme se skripty <application>automake</application> a budeme postupovat až k <filename>configure.ac</filename> a <filename>autogen.sh</filename>. Pak si ukážeme, jak povolit GTK-Doc v sestavovacím systému a jak sestavit dokumentaci.</para>

      <sect2 id="settingup_automake">
        <title>Integrace s automake</title>

        <para>Jako první nakopírujte <filename>Makefile.am</filename> z podsložky <filename class="directory">examples</filename> ve složce <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">gtkdoc-sources</ulink> do složky s referenční dokumentací svého projektu (např. <filename class="directory">./docs/reference/&lt;package&gt;</filename>). Místní kopie by měla být k dispozici např. pod <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Pokud máte více balíčků s dokumentací, opakujte tento krok pro každý z nich.</para>

        <note>
          <simpara>Nezapomeňte přidat jednotlivé <filename>Makefile.am</filename> do makra <function>AC_CONFIG_FILES</function> v <filename>configure.ac</filename>. Pro <filename>docs/reference/libmeep/Makefile.am</filename> budete potřebovat přidat záznam <filename>docs/reference/libmeep/Makefile</filename> do <function>AC_CONFIG_FILES</function>.</simpara>
        </note>

        <example>
          <title>Příklad struktury složek s <filename>Makefiles.am</filename></title>
          <programlisting>
meep/
  docs/
    reference/  # referenční dokumentace
      libmeep/
        Makefile.am
      meeper/
        Makefile.am
    help/       # volitelné: uživatelská příručka
      meeper/
  src/
    libmeep/
    meeper/
</programlisting>
        </example>

        <para>Dále je třeba přizpůsobit zkopírované soubory Makefile a dodat hodnoty pro různé parametry v jednotlivých <filename>Makefile.am</filename>. Všechna nastavení mají komentáře s popisem svého účelu a jak nastavení přizpůsobit. Většina nastavení má doplňující příznaky předávané do dotyčných nástrojů, které je umí použít. Každý nástroj má proměnnou ve formátu <option>&lt;NÁZEVNÁSTROJE&gt;_OPTIONS</option> (např. nástroj <application>gtkdoc-mkhtml</application> má volbu nazvanou <code>MKHTML_OPTIONS</code>). Všechny nástroje podporují <option>--help</option> pro vypsání podporovaných přepínačů.</para>

        <para>Následující seznam vysvětluje nejpodstatnější volby. Na další volby se podívejte do ukázkového <filename>Makefile.am</filename>. <itemizedlist>
            <listitem>
              <para><option>DOC_MODULE</option> se používá k poskytnutí názvu balíčku, který je dokumentován (např. <code>meeper</code> nebo <code>libmeep</code>).</para>
            </listitem>
            <listitem>
              <para><option>DOC_SOURCE_DIR</option> se používá k určení umístění zdrojové složky, ve které GTK-Doc hledá dokumentaci API. Obvykle to je <code>DOC_SOURCE_DIR=$(top_srcdir)/src </code> nebo podsložka této složky.</para>
            </listitem>

            <listitem>
              <para><option>HFILE_GLOB</option> a <option>CFILE_GLOB</option> se používají pro závislosti. Obě volby přebírají file-glob (např. <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>). Dokumentace se znovu sestaví, když se kterýkoliv z odpovídajících souborů změní.</para>
            </listitem>

            <listitem>
              <para><option>EXTRA_HFILES</option> umožňuje určit dodatečné hlavičkové soubory, které se mají zahrnout při procházení pro dokumentaci k API, a které nejsou k nalezení pod složkou <code>DOC_SOURCE_DIR</code> (např. <code>EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).</para>
            </listitem>

            <listitem>
              <para><option>IGNORE_HFILES</option> umožňuje určit dodatečné hlavičkové soubory nebo složky, které se mají ignorovat při procházení pro dokumentaci k API. Použijte základní název ze souboru nebo složky (např. <code>IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).</para>
            </listitem>

            <listitem>
              <para><option>HTML_IMAGES</option> umožňuje určit soubory s obrázky, které se zkopírují do složky <option>html/</option> s generovanou dokumentací. Pokud jsou součástí vaší dokumentace API nějaké obrázky, je třeba je přidat do této volby (např. <code>HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).</para>
            </listitem>

            <listitem>
              <para><option>content_files</option> umožňuje určit dodatečné soubory, které se mají vložit pomocí <code>$(DOC_MAIN_SGML_FILE)</code> (např. <code>content_files=running.xml building.xml changes-2.0.xml</code>).</para>
            </listitem>

            <listitem>
              <para><option>expand_content_files</option> umožňuje určit soubory, ve kterých jsou rozvinuty <emphasis>zkratky gtk-doc</emphasis>, jako je třeba <code>#GtkWidget</code> (např. <code>expand_content_files=running.xml</code>).</para>
            </listitem>
          </itemizedlist></para>

      </sect2>

      <sect2 id="settingup_autoconf">
        <title>Integrace s autoconf</title>

        <para>Integrace s <application>autoconf</application> je velmi jednoduchá a skládá se z jednoho povinného kroku a dalšího volitelného (ale doporučeného) kroku. Prvním krokem je přidat makro <function>GTK_DOC_CHECK</function> do skriptu <filename>configure.ac</filename>. Tím se zaregistruje několik konfiguračních voleb, které povolí GTK-Doc a umožní vám nastavit výchozí argumenty pro <application>gtkdocize</application>.</para>

        <warning>
          <simpara>Ujistěte se, že makro <code>GTK_DOC_CHECK</code> není odsazené od kraje. Makro musí začínat na začátku řádku a nesmí začínat bílými znaky.</simpara>
        </warning>

        <para>Druhým krokem je přidat do <filename>configure.ac</filename> makro <code>AC_CONFIG_MACRO_DIR(m4)</code>. Není to sice nutné, ale pomůže to <application>gtkdocize</application> automaticky zkopírovat definici makra (např. <filename>gtk-doc.m4</filename>), která obsahuje makro <function>GTK_DOC_CHECK</function>, do složky s makry ve vašem projektu. Bez toho se může stát, že makro <function>GTK_DOC_CHECK</function> nemusí být nalezeno a budete muset nástroji <application>aclocal</application> výslovně uvést, kde soubor s definicí makra najít.</para>

        <para>
          <example><title>Minimální integrace s autoconf</title>
            <programlisting>
# doporučeno: nastaví složku m4
AC_CONFIG_MACRO_DIR(m4)
# volitelné: zaregistruje gtk-doc v configure
GTK_DOC_CHECK([1.28])
</programlisting>
          </example>
        </para>

        <para>Výše uvedený příklad funguje, ale vyžaduje, aby všichni vývojáři měli nainstalováno gtk-doc. Lepším způsobem je zařídit, aby sestavení dokumentace bylo volitelné, jak je ukázáno v následujícím příkladu: <example>
            <title>Integrace s volitelnými závislostttmi gtk-doc</title>
            <programlisting>
m4_ifdef([GTK_DOC_CHECK], [
# doporučeno: nastaví složku m4
AC_CONFIG_MACRO_DIR(m4)
# volitelné: zaregistruje gtk-doc v configure
GTK_DOC_CHECK([1.28])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
</programlisting>
          </example></para>

        <para>První argument se používá ke kontrole verze GTK-Doc v průběhu konfigurace. Druhý, volitelný argument používá nástroj <application>gtkdocize</application>. Makro <symbol>GTK_DOC_CHECK</symbol> také přidává několik přepínačů pro configure:</para>

        <orderedlist>
          <listitem><para>--with-html-dir=CESTA: cesta, kam se má dokumentace nainstalovat</para></listitem>
          <listitem><para>--enable-gtk-doc: použít k sestavení dokumentace gtk-doc [výchozí je ne]</para></listitem>
          <listitem><para>--enable-gtk-doc-html: sestavit dokumentaci ve formátu HTML [výchozí je ano]</para></listitem>
          <listitem><para>--enable-gtk-doc-pdf: sestavit dokumentaci ve formátu PDF [výchozí je ne]</para></listitem>
        </orderedlist>

        <important>
          <para>GTK-Doc je standardně vypnuté! Nezapomeňte zadat přepínač „<option>--enable-gtk-doc</option>“ při dalším spuštění <filename>configure</filename>. Jinak se nainstaluje předgenerovaná dokumentace (která může mít význam pro uživatele, ale ne pro vývojáře).</para>
        </important>

        <para>Po provedení změn v <filename>configure.ac</filename> aktualizujte soubor <filename>configure</filename>. To se dá udělat opětovným spuštěním <code>autogen.sh</code>.</para>
      </sect2>

      <sect2 id="settingup_autogen">
        <title>Integrace s autogen</title>

        <para>Většina projektů má skript <filename>autogen.sh</filename>, který po stažení projektu ze systému pro správu verzí (jako je Git nebo SVN), nastaví infrastrukturu pro sestavení. GTK-Doc se dodává se skriptem nazvaným <application>gtkdocize</application>, který lze použít ke zkopírování nezbytných souborů požadovaných GTK-Doc do zdrojové složky.</para>

        <para>Měl by být spuštěn před autoheader, automake nebo autoconf.</para>

        <para>
          <example><title>Spuštění gtkdocize z autogen.sh</title>
            <programlisting>
gtkdocize || exit 1
</programlisting>
          </example>
        </para>

        <para>
          <example>
            <title>Podmíněné spuštění gtkdocize z autogen.sh</title>
            <programlisting>
GTKDOCIZE=$(which gtkdocize 2&gt;/dev/null)
if test $? -ne 0; then
  echo "No gtk-doc support found. You can't build the docs."
else
  $GTKDOCIZE || exit 1
fi
</programlisting>
          </example>
        </para>

        <para>Když spustíte <filename>gtkdocize</filename>, tak nakopíruje do kořenové složky vašeho projektu (nebo složky určené přepínačem <option>--docdir</option>) soubor <filename>gtk-doc.make</filename>.</para>

        <para><filename>gtkdocize</filename> kontroluje váš skript <filename>configure.ac</filename> ohledně makra <function>GTK_DOC_CHECK</function>. Toto makro můžete použít k předání dalších parametrů do skriptu <application>gtkdocize</application>. Konkrétně k tomu slouží druhý argument makra.</para>

        <para>Alternativně lze další argumenty skriptu <application>gtkdocize</application> předat přes proměnnou prostředí <function>GTKDOCIZE_FLAGS</function> nebo je zadat přímo za volání <application>gtkdocize</application> v <filename>autogen.sh</filename>.</para>

      </sect2>

      <sect2 id="settingup_firstrun">
        <title>Spouštění GTK-Doc ze sestavovacího systému</title>

        <para>Po dokončení předchozích kroků nastal čas spustit sestavení. Nejdříve musíte znovu spustit <filename>autogen.sh</filename>. Pokud tento skript pro vás provádí nastavení, předejte mu přepínač <option>--enable-gtk-doc</option>. Jinak potom ručně spusťte <filename>configure</filename> s tímto přepínačem.</para>
        <para>První make spustí vygenerování několika doplňujících souborů ve složkách doc. Podstatné jsou tyto: <filename>&lt;package&gt;.types</filename>, <filename>&lt;package&gt;-docs.xml</filename> (dříve .sgml) a <filename>&lt;package&gt;-sections.txt</filename>.</para>
        <para>
          <example><title>Sestavení dokumentace</title>
            <programlisting>
./autogen.sh --enable-gtk-doc
make
</programlisting>
          </example>
        </para>

        <para>Nyní si můžete ve svém webovém prohlížeči zobrazit <filename>docs/reference/&lt;package&gt;/index.html</filename>. S tímto počátečním nastavením uvidíte jen velmi jednoduchý dokument. Následující kapitola vás naučí, jak do svého zdrojového kódu přidat dokumentaci k API pomocí speciálních komentářových bloků. Dále pak kapitola seznamuje s <link linkend="metafiles">dodatečnými soubory</link> a ukazuje, jak upravit <link linkend="metafiles_master">hlavní šablonu</link>, abyste do svých souborů s dokumentací dostali doplňující kapitoly a oddíly.</para>

      </sect2>

    </sect1>

    <sect1 id="settingup_cmake">
      <title>Integrace se sestavovacím systémem CMake</title>

      <para>GTK-Doc nyní nabízí modul <filename>GtkDocConfig.cmake</filename> (a příslušný modul <filename>GtkDocConfigVersion.cmake</filename>). Ten poskytuje příkaz <literal>gtk_doc_add_module</literal>, který můžete nastavit ve svém souboru <filename>CMakeLists.txt</filename>.</para>

      <para>Následující příklad ukazuje, jak tento příkaz použít: <example><title>Příklad použití GTK-Doc z CMake</title>
          <programlisting>
find_package(GtkDoc 1.25 REQUIRED)

# Vytvoření cíle doc-libmeep.
gtk_doc_add_module(
   libmeep ${CMAKE_SOURCE_DIR}/libmeep
      XML meep-docs.xml
      LIBRARIES libmeep
)

# Sestavení doc-libmeep jako součásti výchozího cíle. Bez tohoto byste museli
# ručně spouštět něco jako `make doc-libmeep`, aby se dokumentace sestavila.
add_custom_target(documentation ALL DEPENDS doc-libmeep)

# Instalace dokumentace. (Předpokládá to, že používáte modul CMake GNUInstallDirs
# ke správnému nastavení proměnné CMAKE_INSTALL_DOCDIR).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
        DESTINATION ${CMAKE_INSTALL_DOCDIR})
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="settingup_plain_makefiles">
      <title>Integrace s prostými soubory Makefile nebo jinými sestavovacími systémy</title>

      <para>Když někdo nechce používat automake, a tím pádem <filename>gtk-doc.mak</filename>, bude muset volat nástroje gtkdoc ve správném pořadí ve vlastních souborech make (nebo jiných nástrojích).</para>

      <para>
        <example><title>Kroky sestavení dokumentace</title>
          <programlisting>
DOC_MODULE=meep
// sources have changed
gtkdoc-scan --module=$(DOC_MODULE) &lt;zdrojová-složka&gt;
gtkdoc-scangobj --module=$(DOC_MODULE)
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=&lt;zdrojová-složka&gt;
// xml files have changed
mkdir html
cd html &amp;&amp; gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html
</programlisting>
        </example>
      </para>

      <para>Na výběr dalších potřebných voleb se musíte se podívat do <filename>Makefile.am</filename> a <filename>gtk-doc.mak</filename>.</para>
    </sect1>

    <sect1 id="settingup_vcs">
      <title>Integrace se systémem pro správu verzí</title>

      <para>Podle nepsaných pravidel byste soubory, které upravujete, měli udržovat ve správě verzí. U typických projektů to jsou tyto soubory: <filename>&lt;balíček&gt;.types</filename>, <filename>&lt;balíček&gt;-docs.xml</filename> (dříve .sgml), <filename>&lt;balíček&gt;-sections.txt</filename> a <filename>Makefile.am</filename>.</para>
      <para>Soubory ze složek <filename>xml/</filename> a <filename>html/</filename> by neměly být zařazeny do správy verzí. A ani žádné soubory <filename>.stamp</filename>.</para>
    </sect1>

  </chapter>

  <chapter id="documenting">
    <title>Dokumentování v kódu</title>

    <para>GTK-Doc používá pro kód dokumentace komentáře se speciální syntaxí ve zdrojovém kódu. K tomu se ještě získávají informace o struktuře vašeho projektu z dalších zdrojů. V následujícím oddílu najdete všechny informace o syntaxi komentářů.</para>

    <para>Skener GTK-Doc zvládá dobře většinu hlavičkových souborů C. V případě, že od něj obdržíte varování, které vypadá jako speciální případ, můžete GTK-Doc poradit, aby jej přeskakovala. <example><title>Komentářový blok GTK-Doc</title>
        <programlisting>
#ifndef __GTK_DOC_IGNORE__
/* kód zde se nezpracovává */
#endif
</programlisting>
      </example></para>

    <note>
      <title>Omezení</title>
      <para>Uvědomte si, že GTK-Doc podporuje <code>#ifndef(__GTK_DOC_IGNORE__)</code>, ale ne <code>#if !defined(__GTK_DOC_IGNORE__)</code> nebo jiné kombinace.</para>
    </note>

    <!--  -->

    <sect1 id="documenting_syntax">
      <title>Dokumentační komentáře</title>

      <para>Každý víceřádkový komentář, který je označený další „*“ navíc, je dokumentačním blokem a bude zpracovaný nástroji GTK-Doc. <example><title>Komentářový blok GTK-Doc</title>
          <programlisting>
/**
 * identifikátor:
 * dokumentace …
 */
</programlisting>
        </example></para>

      <para>„identifikátor“ je jeden řádek s názvem položky, ke které se komentář vztahuje. Syntaxe se částečně liší podle položky. (DOPLNIT: přidat tabulku se seznamem identifikátorů)</para>

      <para>Blok „dokumentace“ se rovněž liší pro různé typy symbolů. Symboly, které přebírají parametry, jako jsou funkce nebo makra, mají nejdříve popsané parametry, za kterými následuje prázdný řádek (pouze „*“). Za ním pak následuje podrobný popis. Všechny řádky (mimo seznamu programů a oddílu CDATA), které obsahují „ *“ (mezera hvězdička) se převedou na zalomení odstavce. Pokud zalomení odstavce nechcete, změňte to na „ *  “ (mezera hvězdička mezera mezera). To se hodí na text s pevným formátem (výpis kódu).</para>

      <tip>
        <para>Když píšete dokumentaci ke kódu, popište dva aspekty: <itemizedlist>
             <listitem>
               <para>Co to je: Název třídy nebo funkce může být občas matoucí pro lidi, kteří používají něco jiného.</para>
             </listitem>
             <listitem>
               <para>K čemu to je: Uveďte běžném použití. Dejte ho do souvislosti se zbytkem API.</para>
             </listitem>
           </itemizedlist></para>
      </tip>

      <para>Jednou z výhod hypertextu, oproti prostému textu, je možnost mít v dokumentu odkazy. Zápis správných značek pro odkazy může být úmorná práce. GTK-Doc se vám snaží pomoci několika užitečnými zkratkami. <itemizedlist>
          <listitem>
            <para>Použijte funkce() pro odkaz na funkci nebo makro, které mají argumenty.</para>
          </listitem>
          <listitem>
            <para>Použijte @parametr pro odkaz na parametry. Použijte to rovněž, když se odkazujete na parametry jiných funkcí, vztahujících se k popisované funkci.</para>
          </listitem>
          <listitem>
            <para>Použijte %konstanta pro odkaz na konstantu, např. %G_TRAVERSE_LEAFS.</para>
          </listitem>
          <listitem>
            <para>Použijte #symbol pro odkaz na jiný typ symbolu, např. strukturu, výčet a makro, který nemá argumenty.</para>
          </listitem>
          <listitem>
            <para>Použijte #Objekt::signál pro odkaz na signál objektu GObject.</para>
          </listitem>
          <listitem>
            <para>Použijte #Objekt:vlastnost pro odkaz na vlastnost objektu GObject.</para>
          </listitem>
          <listitem>
            <para>Použijte #Struktura.pole pro odkaz na pole uvnitř struktury a #GObjectTřída.neco() pro odkaz na virtuální metodu.</para>
          </listitem>
        </itemizedlist></para>

      <tip>
        <para>V případě, že potřebujete ve své dokumentaci použít speciální znaky „&lt;“, „&gt;“, „()“, „@“, „%“ nebo „#“, aniž by je GTK-Doc změnilo, můžete místo nich použít použít entity XML „&amp;lt;“, „&amp;gt;“, „&amp;lpar;“, „&amp;rpar;“, „&amp;commat;“, „&amp;percnt;“ a „&amp;num;“ nebo únikovou sekvenci se zpětným lomítkem „\“.</para>
      </tip>

      <para>DocBook toho ale umí více, než jen odkazy. Může mít také seznamy, příklady, nadpisy a obrázky. Od verze 1.20 je dána přednost použití jen podmnožiny ze základní syntaxe formátování textu. Tato podmnožina se nazývá <ulink url="http://daringfireball.net/projects/markdown/">Markdown</ulink>. Dokumentace ze starší verze GTK-Doc, která obsahuje Markdown, bude vygenerována tak, jak je. Například položky seznamu se objeví s pomlčkou na začátku.</para>

      <para>I když je markdown v současnosti preferovaný, můžete míchat oba dohromady. Má to jediné omezení v tom, že můžete použít docbook xml v markdown, ale markdown v docbook xml podporován není.</para>

      <para>Když ve starších vydáních GTK-Doc potřebujete podporu pro dodatečné formátování, musíte zapnout použití značek XML pro DocBook uvnitř dokumentačních komentářů pomocí <option>--xml-mode</option> (nebo <option>--sgml-mode</option>) v proměnné <symbol>MKDB_OPTIONS</symbol> v souboru <filename>Makefile.am</filename>.</para>

      <para>
        <example><title>Komentářový blok GTK-Doc používající značkovací jazyk</title>
          <programlisting>
/**
 * identifikátor:
 *
 * odstavec dokumentace…
 *
 * # Podnadpis #
 *
 * ## Podnadpis druhé úrovně
 *
 * # Podnadpis s kotvou pro odkazy # {#heading-two}
 *
 * další dokumentace:
 *
 * - položka seznamu 1
 *
 *   Odstavec v rámci položky seznamu.
 *
 * - položka seznamu 2
 *
 * 1. číslovaná položka seznamu
 *
 * 2. další číslovaná položka seznamu
 *
 * Další odstavec. [Odkazy na webové stránky GNOME](http://www.gnome.org/)
 *
 * ![vložený obrázek](plot-result.png)
 *
 * [Odkaz na nadpis pomocí kotvy uvedené výše][heading-two]
 *
 * Příklad v jazyce C:
 * |[&lt;!-- language="C" --&gt;
 * GtkWidget *label = gtk_label_new ("Paráda!");
 * ]|
 */
</programlisting>
        </example>
      </para>

      <para>Více příkladů k podporovaným značkám Markdown můžete najít v <ulink url="https://wiki.gnome.org/Projects/GTK/DocumentationSyntax/Markdown">Referenční příručce k syntaxi Markdown pro dokumentaci GTK</ulink>.</para>

      <tip>
        <para>Jak již bylo zmíněno dříve, slouží GTK-Doc pro dokumentování veřejného API. Tím pádem nemůžete psát dokumentaci pro statické symboly. Nicméně je vhodné komentovat i tyto symboly. Pomůže to ostatním vývojářům porozumět vašemu kódu. Proto doporučujeme komentovat je pomocí normálních komentářů (bez druhé „*“ na prvním řádku). Pokud je budete v budoucnu chtít předělat na veřejné, jediné co budete muset udělat, je přidat do komentářového bloku jednu „*“ a na správné místo v souboru oddílů vložit název symbolu.</para>
      </tip>
    </sect1>

    <sect1 id="documenting_sections">
      <title>Dokumentování oddílů</title>

      <para>Každý oddíl dokumentace obsahuje informaci o jedné třídě nebo modulu. Můžete do oddílu napsat blok, ve kterém je představíte. Stručný popis se rovněž použije v rámci tabulky s obsahem. Všechna @pole jsou volitelná.</para>

      <para>
        <example><title>Komentářový blok oddílu</title>
          <programlisting>
/**
 * SECTION:meepapp
 * @short_description: třída plikace
 * @title: Aplikace Meep
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * Třída aplikace starající se o…
 */
</programlisting>
        </example>
      </para>

      <variablelist>
        <varlistentry>
          <term>SECTION:&lt;název&gt;</term>
          <listitem>
            <para>Název prováže oddíl dokumentace s příslušnou částí v souboru <filename>&lt;package&gt;-sections.txt</filename>. Zde zadaný název musí odpovídat značce &lt;SOUBOR&gt; v souboru <filename>&lt;package&gt;-sections.txt</filename>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@short_description</term>
          <listitem>
            <para>Jednořádkový popis oddílu, který se později objeví za odkazy v tabulce s obsahem a na začátku stránky oddílu.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@title</term>
          <listitem>
            <para>Název oddílu se standardně zvolí podle &lt;name&gt; v deklaraci SECTION. Lze jej ale určit i přímo v poli @title.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@section_id</term>
          <listitem>
            <para>Přepíše použití názvu jako identifikátoru oddílu. Pro objekty GObject se jako section_id použije &lt;title&gt; a pro ostatní oddíly to je &lt;MODULE&gt;-&lt;title&gt;.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@see_also</term>
          <listitem>
            <para>Seznam symbolů, které se vztahují k tomuto oddílu.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@stability</term>
          <listitem>
            <para>Informační popis úrovně stability tohoto API. Doporučujeme použít jeden z těchto termínů: <itemizedlist>
                <listitem>
                  <para>Stable (stabilní) – Záměrem stabilního rozhraní je umožnit libovolné třetí straně vyvinout aplikace využívající toto rozhraní, vydat je a moci se spolehnout, že poběží na všech podružných vydáních produktu (po té, co je rozhraní vydáno a v rámci stejné hlavní verze). I mezi hlavními vydáními se nekompatibilní změny očekávají zřídka v opravdu odůvodněných případech.</para>
                </listitem>
                <listitem>
                  <para>Unstable (nestabilní) – Nestabilní rozhraní je experimentální a přechodné. Typicky bývá dáno vývojářům k dispozici kvůli včasnému přístupu k novým a rychle se měnícím technologiím nebo kvůli poskytnutí provizorního řešení problému, kdy je předpokládané více obecné řešení. Není žádná záruka ohledně zdrojové či binární kompatibility při přechodu z jedné podružné verze na následujíc.</para>
                </listitem>
                <listitem>
                  <para>Private (soukromé) – Rozhraní, které může být použité v rámci zásobníku GNOME, ale není dokumentované pro koncového uživatele. Takové funkce by se měly používat jen určeným a dokumentovaným způsobem.</para>
                </listitem>
                <listitem>
                  <para>Internal (interní) – Rozhraní, které je určené pro interní potřeby modulu a nevyžaduje dokumentaci pro koncového uživatele. Funkce, které jsou nedokumentované, jsou považované za interní.</para>
                </listitem>
              </itemizedlist></para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@include</term>
          <listitem>
            <para>Seznam souborů z <literal>#include</literal> oddělených čárkou, aby se zobrazily v oddílu anotace. Přepisuje globální hodnotu ze <link linkend="metafiles_sections">souboru oddílů</link> nebo příkazové řádky. Tato položka je volitelná.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@image</term>
          <listitem>
            <para>Obrázek, který se má zobrazit na začátku referenční stránky k tomuto oddílu. Často se jedná o nějaký nákres, který schématicky znázorňuje podobu třídy nebo nákres se vztahy vůči jiným třídám. Tato položka je volitelná.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <tip>
        <para>Aby se po změně dokumentace předešlo rekompilacím, které nejsou nutné, vložte, kde je to možné, dokumentaci oddílu do zdrojového kódu c.</para>
      </tip>

    </sect1>

    <sect1 id="documenting_symbols">
      <title>Dokumentování symbolů</title>

      <para>Každý symbol (funkce, makro, struktura, výčet, signál a vlastnost) se dokumentuje v odděleném bloku. Blok je nejlepší umístit v rámci definice symbolu, protože se tak snadno udržuje synchronizovaný. Z tohoto důvodu se funkce obvykle dokumentují ve zdrojovém kódu C a makra, struktury a výčty v hlavičkovém souboru.</para>

      <sect2><title>Obecné značky</title>

        <para>Informace o verzích můžete přidat ke všem prvkům dokumentace, abyste sdělili, kdy bylo API zavedeno, nebo kdy bylo označeno za zastaralé.</para>

        <variablelist><title>Značky pro verzování</title>
          <varlistentry><term>Since:</term>
            <listitem>
              <para>Popisuje, od které verze kódu je API dostupné.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Deprecated:</term>
            <listitem>
              <para>Odstavec upozorňující, že by se tato funkce neměla nadále používat. Popis by měl čtenáře odkazovat na nové API.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>Můžete také ke všem prvkům dokumentace přidat informaci o stabilitě, abyste dali najevo, že je u API zaručena stabilita pro všechna následující minoritní vydání projektu.</para>

        <para>Výchozí stabilitu pro všechny prvky dokumentace můžete pomocí argumentu <option>--default-stability</option> s jednou u níže uvedených hodnot předat do <application>gtkdoc-mkdb</application>.</para>

        <variablelist><title>Značky pro stabilitu</title>
          <varlistentry><term>Stability: Stable</term>
            <listitem>
              <para>Označuje prvek jako stabilní. Je to určeno pro veřejná API, která zaručují, že zůstanou stabilní po všechna minoritní vydání projektu.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Stability: Unstable</term>
            <listitem>
              <para>Označuje prvek jako nestabilní. Je to určeno pro veřejná API, která jsou vydána jako ukázky před tím, než jsou stabilizována.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Stability: Private</term>
            <listitem>
              <para>Označuje prvek jako soukromý. Je to určeno pro rozhraní, která mohou být použita přímo v modulu, ale ne kterýmikoliv třetími stranami.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <example><title>Obecné značky</title>
          <programlisting>
/**
 * foo_get_bar:
 * @foo: nějaké něco
 *
 * Získá @foo něčeho.
 *
 * Returns: @foo něčeho
 *
 * Since: 2.6
 * Deprecated: 2.12: Místo toho použijte foo_baz_get_bar().
 */
Bar *
foo_get_bar(Foo *foo)
{
...
</programlisting>
        </example>
      </sect2>

      <sect2><title>Anotace</title>

        <para>Dokumentační bloky mohou obsahovat anotační štítky. Tyto štítky budou zpracovány jako vysvětlivky popisující jejich význam. Používají se introspekcí objektu GObjekt k vygenerování vazby na další jazyky. Podrobný seznam podporovaných štítků můžete najít na <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">wiki</ulink>.</para>

        <example><title>Anotace</title>
          <programlisting>
/**
 * foo_get_bar: (annotation)
 * @foo: (annotation): nějaké něco
 *
 * Získá @foo něčeho.
 *
 * Returns: (annotation): @foo něčeho
 */
...
/**
 * foo_set_bar_using_the_frobnicator: (annotation) (annotation)
 *                                    (annotation) …
 * @foo: (annotation) (annotation) …: nějaké něco
 *
 * Nastaví něco na @foo.
 */
</programlisting>
        </example>
      </sect2>

      <sect2><title>Komentářový blok pro funkci</title>

        <para>Nezapomeňte prosím: <itemizedlist>
            <listitem>
              <para>Zdokumentovat, jestli je třeba vracené objekty, seznamy, řetězce apod. uvolnit z paměti.</para>
            </listitem>
            <listitem>
              <para>Zdokumentovat, jestli může parametr být NULL a co se stane, když tomu tak je.</para>
            </listitem>
            <listitem>
              <para>Kde je to vhodné, zmínit úvodní a koncové podmínky.</para>
            </listitem>
          </itemizedlist></para>

        <para>Gtk-doc předpokládá, že všechny symboly (makra, funkce) začínající znakem „_“, jsou soukromé. Potom se s nimi zachází jako se statickými funkcemi.</para>

        <example><title>Komentářový blok pro funkci</title>
          <programlisting>
/**
 * function_name:
 * @par1:  popis parametru 1. Může zabírat více jak
 * jeden řádek.
 * @par2:  popis parametru 2
 * @...:  seznam proměnných parametrů zakončených NULL
 *
 * Zde pokračuje popis funkce. K odkazu na parametr můžete použit @par1,
 * takže bude ve výstupu zvýrazněný. Můžete také použít %constant pro
 * konstanty, function_name() pro funkce a #GtkWidget pro odkazy na jiné
 * deklarace (které mohou být zdokumentované jinde).
 *
 * Returns: celé číslo.
 *
 * Since: 2.2
 * Deprecated: 2.18: Místo toho použijte other_function().
 */
</programlisting>
        </example>

        <variablelist><title>Značky pro funkce</title>
          <varlistentry><term>Returns:</term>
            <listitem>
              <para>Odstavec popisující vracený výsledek.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>@…:</term>
            <listitem>
              <para>Když má funkce proměnný počet argumentů, měli byste použít tuto značku (z historických důvodů funguje i @Varargs:).</para>
            </listitem>
          </varlistentry>
        </variablelist>

      </sect2>

      <sect2><title>Komentářový blok pro vlastnost</title>

        <example><title>Komentářový blok pro vlastnost</title>
          <programlisting>
/**
 * SomeWidget:some-property:
 *
 * Zde vlastnost zdokumentujte.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, …);
</programlisting>
        </example>

      </sect2>

      <sect2><title>Komentářový blok pro signál</title>

        <para>Nezapomeňte prosím: <itemizedlist>
            <listitem>
              <para>Zdokumentovat, kdy je signál vyslán a jestli je vyslána před nebo po ostatních signálech.</para>
            </listitem>
            <listitem>
              <para>Zdokumentovat, co aplikace smí v obsluze signálu provádět.</para>
            </listitem>
          </itemizedlist></para>

        <example><title>Komentářový blok pro signál</title>
          <programlisting>
/**
 * FooWidget::foobarized:
 * @widget: widget, který signál přijímá
 * @foo: nějaké něco
 * @bar: jiné něco
 *
 * Signál ::foobarized je vyslán pokaždé, když někdo zkusí něco s @widget.
 */
foo_signals[FOOBARIZED] =
  g_signal_new ("foobarized",
                ...
</programlisting>
        </example>

      </sect2>

      <sect2><title>Komentářový blok pro strukturu</title>
        <example><title>Komentářový blok pro strukturu</title>
          <programlisting>
/**
 * FooWidget:
 * @bar: nějaká #gboolean
 *
 * Tohle je ten nejlepší widget.
 */
typedef struct _FooWidget {
  GtkWidget parent_instance;

  gboolean bar;
} FooWidget;
</programlisting>
        </example>

        <para>Před privátními poli struktury použijte <code>/*&lt; private &gt;*/</code>, abyste je skryli. K přesně opačnému účelu se používá <code>/*&lt; public &gt;*/</code>.</para>

        <para>Pokud je prvním polem „g_iface“, „parent_instance“ nebo „parent_class“, bude za privátní považováno automaticky a není to zapotřebí zmiňovat v komentářovém bloku.</para>

        <para>Komentářové bloky struktur můžete použít také pro objekty GObject a třídy GObjectClass. Obvykle je rozumné přidat komentářový blok pro třídu, pokud má virtuální metody (protože to je způsob, jakým je lze zdokumentovat). Pro vlastní GObject je možné použít příslušnou dokumentaci oddílu, který bude mít samostatný blok pro strukturu instance, což se může hodit, když má instance veřejná pole. Jedinou nevýhodou je, že se tím vytvoří dvě položky v rejstříku se stejným názvem (struktura a oddíl).</para>

      </sect2>

      <sect2><title>Komentářový blok pro výčty</title>
        <example><title>Komentářový blok pro výčty</title>
          <programlisting>
/**
 * Something:
 * @SOMETHING_FOO: nějaké něco
 * @SOMETHING_BAR: jiné něco
 *
 * Výčtové hodnoty používané pro určení věci.
 */
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*&lt; private &gt;*/
  SOMETHING_COUNT
} Something;
</programlisting>
        </example>

        <para>Před privátními výčtovými hodnotami použijte <code>/*&lt; private &gt;*/</code>, abyste je skryli. K přesně opačnému účelu se používá <code>/*&lt; public &gt;*/</code>.</para>

      </sect2>
    </sect1>


    <sect1 id="documenting_inline_program">
      <title>Dokumentaci k vloženým programům</title>
      <para>Programy a jejich rozhraní příkazového řádku můžete zdokumentovat pomocí vložené dokumentace.</para>

      <variablelist>
      <title>Značky</title>

      <varlistentry><term>PROGRAM</term>

      <listitem>
      <para>Definuje začátek dokumentace k programu.</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@short_description:</term>
      <listitem>
      <para>Definuje krátký popis programu. (volitelné)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@synopsis:</term>
      <listitem>
      <para>Definuje argumenty nebo seznam argumentů, které program přebírá. (volitelné)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@see_also:</term>
      <listitem>
      <para>Část stránky oddílu „Viz také“. (volitelné)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@arg:</term>
      <listitem>
      <para>Argument(y) předávané do programu a jejich popis. (volitelné)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>Description:</term>
      <listitem>
      <para>Úplný popis programu.</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>Returns:</term>
      <listitem>
      <para>Specifikuje, jakou hodnotu či více hodnot program vrací. (volitelné)</para>
      </listitem>
      </varlistentry>

      </variablelist>

      <sect2>
        <title>Příklad dokumentace k programu.</title>
        <example><title>Komentářový blok pro program</title>
        <programlisting>
/**
 * PROGRAM:test-program
 * @short_description: Testovací program
 * @synopsis: test-program [*OPTIONS*...] --arg1 *arg* *FILE*
 * @see_also: test(1)
 * @--arg1 *arg*: nastaví arg1 do *arg*
 * @--arg2 *arg*: nastaví arg2 do *arg*
 * @-v, --version: Vypíše verzi programu
 * @-h, --help: Vypíše nápovědu k programu
 *
 * Úplný popis programu.
 *
 * Returns: Vrací nulu při úspěchu, nenulovou hodnotu při selhání.
 */
int main(int argc, char *argv[])
{
	return 0;
}
</programlisting>
        </example>

      </sect2>
    </sect1>

    <sect1 id="documenting_docbook">
      <title>Užitečné značky DocBook</title>

      <para>Zde jsou některé značky DocBook, které mají pro dokumentaci kódu největší význam.</para>

      <para>Odkaz na jiný oddíl v dokumentaci GTK: <informalexample>
          <programlisting>
&lt;link linkend="glib-Hash-Tables"&gt;Hašovací tabulky&lt;/link&gt;
</programlisting>
        </informalexample> Odkazem je id SGML/XML v první položce stránky, na kterou chcete odkazovat. Pro většinu stránek je to v současnosti část („gtk“, „gdk“, „glib“) a potom název stránky („Hašovací tabulka“). Pro ovládací prvky je to název třídy. Mezery a podtržítka se převedou na „-“, aby to vyhovovalo SGML/XML.</para>

      <para>Odkaz na externí funkci, například standardní funkci C: <informalexample>
          <programlisting>
&lt;function&gt;…&lt;/function&gt;
</programlisting>
        </informalexample></para>

      <para>Vložení ukázky kódu: <informalexample>
          <programlisting>
&lt;example&gt;
  &lt;title&gt;Používání GHashTable.&lt;/title&gt;
  &lt;programlisting language="C"&gt;
      ...
  &lt;/programlisting&gt;
&lt;/example&gt;
</programlisting>
        </informalexample> nebo pro velmi krátké úseky kódu, které nepotřebují nadpisy, je případně možné i: <informalexample>
          <programlisting>
&lt;informalexample&gt;
  &lt;programlisting language="C"&gt;
  ...
  &lt;/programlisting&gt;
&lt;/informalexample&gt;
</programlisting>
        </informalexample> V obou případech je atribut language volitelnáý a je používán jako rada pro program provádějící zvýrazňování syntaxe (pygments pro výstup v html).V novějších verzích GTK-Doc je také podporované zkracování: <informalexample>
          <programlisting>
|[&lt;!-- language="C" --&gt;
  ...
]|
</programlisting>
        </informalexample></para>

      <para>Vložení seznamu s odrážkami: <informalexample>
          <programlisting>
&lt;itemizedlist&gt;
  &lt;listitem&gt;
    &lt;para&gt;
      …
    &lt;/para&gt;
  &lt;/listitem&gt;
  &lt;listitem&gt;
    &lt;para&gt;
      …
    &lt;/para&gt;
  &lt;/listitem&gt;
&lt;/itemizedlist&gt;
</programlisting>
        </informalexample></para>

      <para>Vložení poznámky, která se objeví mimo text: <informalexample>
          <programlisting>
&lt;note&gt;
  &lt;para&gt;
    Ujistěte se, že data po použití uvolníte.
  &lt;/para&gt;
&lt;/note&gt;
</programlisting>
        </informalexample></para>

      <para>Odkaz na typ: <informalexample>
          <programlisting>
&lt;type&gt;unsigned char&lt;/type&gt;
</programlisting>
        </informalexample></para>

      <para>Odkaz na externí strukturu (která není popsaná v dokumentaci GTK): <informalexample>
          <programlisting>
&lt;structname&gt;XFontStruct&lt;/structname&gt;
</programlisting>
        </informalexample></para>

      <para>Odkaz na pole struktury: <informalexample>
          <programlisting>
&lt;structfield&gt;len&lt;/structfield&gt;
</programlisting>
        </informalexample></para>

      <para>Pro odkaz na název třídy by se dal nejspíše použít: <informalexample>
          <programlisting>
&lt;classname&gt;GtkWidget&lt;/classname&gt;
</programlisting>
        </informalexample> ale pravděpodobně místo toho použijete #GtkWidget (aby se automaticky vytvořil odkaz na stránku ovládacího prvku, viz <link linkend="documenting_syntax">zkratky</link>).</para>

      <para>Zvýrazněný text: <informalexample>
          <programlisting>
&lt;emphasis&gt;Toto je důležité&lt;/emphasis&gt;
</programlisting>
        </informalexample></para>

      <para>Pro název souboru použijte: <informalexample>
          <programlisting>
&lt;filename&gt;/home/user/documents&lt;/filename&gt;
</programlisting>
        </informalexample></para>

      <para>Odkaz na použití klávesy: <informalexample>
          <programlisting>
&lt;keycombo&gt;&lt;keycap&gt;Ctrl&lt;/keycap&gt;&lt;keycap&gt;L&lt;/keycap&gt;&lt;/keycombo&gt;
</programlisting>
        </informalexample></para>

    </sect1>
  </chapter>

  <chapter id="metafiles">
    <title>Vyplňování dodatečných souborů</title>

    <para>Mimo komentářů vložených ve zdrojovém kódu je zde ještě pár dodatečných souborů, které je potřeba udržovat:<filename>&lt;balíček&gt;.types</filename>, <filename>&lt;balíček&gt;-docs.xml</filename> (dříve .sgml) a <filename>&lt;balíček&gt;-sections.txt</filename>.</para>

    <sect1 id="metafiles_types">
      <title>Úprava souboru s typy</title>

      <para>Pokud vaše knihovna nebo aplikace vkládá objekty GObject, chcete jejich signály, argumenty/parametry a pozici v hierarchii ukázat v dokumentaci. Vše, co pro to potřebujete udělat, je vypsat funkce <function>xxx_get_type</function> spolu s jejich include v souboru <filename>&lt;balíček&gt;.types</filename>.</para>

      <para>
        <example><title>Příklad souboru &lt;balíček&gt;.types</title>
          <programlisting>
#include &lt;gtk/gtk.h&gt;

gtk_accel_label_get_type
gtk_adjustment_get_type
gtk_alignment_get_type
gtk_arrow_get_type
</programlisting>
        </example>
      </para>

      <para>Od GTK-Doc verze 1.8 vám tento seznam vygeneruje <application>gtkdoc-scan</application>. Stačí jen přidat „--rebuild-types“ do SCAN_OPTIONS v <filename>Makefile.am</filename>. Pokud tento přístup použijete, neměli byste soubor s typy šířit do správy verzí.</para>

    </sect1>

    <sect1 id="metafiles_master">
      <title>Úprava hlavního dokumentu</title>

      <para>GTK-Doc produkuje dokumentaci v SGML/XML standardu DocBook. Když se zpracovávají komentáře vložené ve zdrojovém kódu, generují nástroje GTK-Doc pro každou třídu nebo modul jednu stránku dokumentace jako samostatný soubor. Všechny jsou pak uvedené seřazené v hlavním dokumentu.</para>

      <para>Jakmile pro vás GTK-Doc vytvoří šablonu hlavního dokumentu, při pozdějším spuštění již do ní nezasahuje. To znamená, že můžete dokumentaci bez omezení strukturovat. A to včetně seskupování stránek a přidávání doplňujících stránek. GTK-Doc má v současnosti testovací sadu, ve které je také hlavní dokument vytvořen znovu od začátku. Je dobré se čas od času do něj nahlédnout, jestli se v něm neobjevily nějaké nové věci.</para>

      <tip>
        <para>Nevytvářejte výukové dokumenty (tutorial) jako zvláštní dokumenty. Napište je jako zvláštní kapitolu. Výhodou přímého spojení výukového dokumentu k vaší knihovně s dokumentací API je snadné vytváření odkazů pro symboly. Zvyšuje se tím také šance, že výukový dokument bude reflektovat aktualizace v knihovně.</para>
      </tip>

      <para>Nyní se podívejme, které věci můžete v hlavním dokumentu měnit. Pro začátek je to pouze název. Je zde několik zástupných hodnot (text v hranatých závorkách), o které byste se měli postarat.</para>

      <para>
        <example><title>Hlavička hlavního dokumentu</title>
          <programlisting>
&lt;bookinfo&gt;
  &lt;title&gt;Referenční příručka k NÁZEV_MODULU&lt;/title&gt;
  &lt;releaseinfo&gt;
    pro NÁZEV_MODULU [VERSION]
    Nejvnovější verzi tohoto dokumentu můžete najít on-line na
    &lt;ulink role="online-location" url="http://[SERVER]/NÁZEV_MODULU/index.html"&gt;http://[SERVER]/NÁZEV_MODULU/&lt;/ulink&gt;.
  &lt;/releaseinfo&gt;
&lt;/bookinfo&gt;

&lt;chapter&gt;
  &lt;title&gt;[Insert title here]&lt;/title&gt;
</programlisting>
        </example>
      </para>

      <para>Navíc se vytvoří pár volitelných prvků ve formě komentáře. Můžete si je projít a případně povolit.</para>

      <para>
        <example><title>Volitelná část hlavního dokumentu</title>
          <programlisting>
  &lt;!-- enable this when you use gobject introspection annotations
  &lt;xi:include href="xml/annotation-glossary.xml"&gt;&lt;xi:fallback /&gt;&lt;/xi:include&gt;
  --&gt;
</programlisting>
        </example>
      </para>

      <para>Nakonec musíte přidat nový oddíl, kdekoliv chcete. Nástroj <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> vás upozorní na nově vygenerované soubory XML, které zatím nejsou v dokumentaci zahrnuté.</para>

      <para>
        <example><title>Vkládání generovaných oddílů</title>
          <programlisting>
  &lt;chapter&gt;
    &lt;title&gt;moje knihovna&lt;/title&gt;
      &lt;xi:include href="xml/object.xml"/&gt;
      …
</programlisting>
        </example>
      </para>

    </sect1>

    <sect1 id="metafiles_sections">
      <title>Úprava souboru oddílů</title>

      <para>Soubor oddílů se používá k organizování výstupu dokumentace z GTK-Doc. Zde se určuje, který symbol náleží ke kterému modulu nebo třídě, a řídí se viditelnost (jestli je veřejný nebo soukromý).</para>

      <para>Soubor oddílů je prostý textový soubor, ve kterém jsou oddíly oddělené značkami. Prázdné řádky se ignorují a s řádky začínajícími „#“ se zachází jako s komentářovými řádky.</para>

      <note>
        <para>Přestože díky značkám vypadá soubor podobně jako XML, není tomu tak. Neuzavírejte prosím značky jako je &lt;SUBSECTION&gt;.</para>
      </note>

      <para>
        <example><title>Vkládání generovaných oddílů</title>
          <programlisting>
&lt;INCLUDE&gt;libmeep/meep.h&lt;/INCLUDE&gt;

&lt;SECTION&gt;
&lt;FILE&gt;meepapp&lt;/FILE&gt;
&lt;TITLE&gt;MeepApp&lt;/TITLE&gt;
MeepApp
&lt;SUBSECTION Standard&gt;
MEEP_APP
...
MeepAppClass
meep_app_get_type
&lt;/SECTION&gt;
</programlisting>
        </example>
      </para>

      <para>Značka &lt;FILE&gt; … &lt;/FILE&gt; se používá k určení názvu souboru bez přípony. Například použití „&lt;FILE&gt;gnome-config&lt;/FILE&gt;“ bude mít v deklaracích oddílu za následek výstup do souboru šablony <filename>tmpl/gnome-config.sgml</filename>, který bude převeden do souboru <filename>sgml/gnome-config.sgml</filename> ve formátu DocBook SGML nebo do souboru <filename>xml/gnome-config.xml</filename> ve formátu DocBook XML. (Název souboru HTML vychází z názvu modulu a názvu oddílu, případně pro GObject z názvu třídy GObject převedeného na malá písmena.)</para>

      <para>Značka &lt;TITLE&gt; … &lt;/TITLE&gt; se používá k určení názvu oddílu. To je použitelné pouze dříve, než je poprvé vytvořena šablona (pokud se používá), protože název nastavený v šabloně tento název přepíše. Navíc je považována za zastaralou v případě, že se používá komentář SECTION ve zdrojovém kódu.</para>

      <para>Můžete také seskupovat položky v oddílu pomocí značky &lt;SUBSECTION&gt;. V současnosti způsobí prázdný řádek mezi pododdíly v souhrnné části. Můžete také použít &lt;SUBSECTION Standard&gt; pro standardní deklarace GObject (například funkce jako je g_object_get_type, makra jako G_OBJECT(), G_IS_OBJECT() atd.). V současnosti jsou tyto v dokumentaci vynechané. Můžete také použít &lt;SUBSECTION Private&gt; pro privátní deklarace, které ve výsledku nebudou (jedná se o ruční způsob, jak zabránit varovným hlášením o nepoužitých deklaracích). Pokud vaše knihovna obsahuje privátní typy, u kterých nechcete, aby se objevily v hierarchii objektů a v seznamu implementovaných nebo vyžadovaných rozhraní, přidejte je do pododdílu Private. Jestli umístit struktury jako GObject a GObjectClass do veřejné nebo standardní části záleží na tom, jestli mají veřejné položky (proměnné, virtuální metody).</para>

      <para>Můžete také použít &lt;INCLUDE&gt; ... &lt;/INCLUDE&gt; k určení #include souborů, které jsou zobrazené v souhrnné části. Obsahuje čárkami oddělený seznam jednotlivých #include souborů, bez lomených závorek. Když je nastavíte mimo kterýkoliv oddíl, budou fungovat pro všechny oddíly až do konce souboru. Když je nastavíte v konkrétním oddílu, použijí se jen pro něj.</para>

    </sect1>

  </chapter>

  <chapter id="reports">
    <title>Ovlivnění výsledku</title>

    <para>Spuštění GTK-Doc vygeneruje ve složkách pro dokumentaci soubory s výstupními sestavami. Generované soubory jsou nazvané: <filename>&lt;balíček&gt;-undocumented.txt</filename>, <filename>&lt;balíček&gt;-undeclared.txt</filename> a <filename>&lt;balíček&gt;-unused.txt</filename>. Všechno to jsou prosté textové soubory, které si lze jednoduše prohlížet a zpracovávat je.</para>

    <para>Soubor <filename>&lt;balíček&gt;-undocumented.txt</filename> začíná souhrnnými údaji o dokumentaci. Následují dva oddíly oddělené prázdnými řádky. První oddíl je seznam nezdokumentovaných nebo neúplných symbolů. Druhý oddíl je to stejné, ale pro dokumentace oddílů. Neúplné položky jsou takové, které mají dokumentaci, ale u kterých byl například přidán nový parametr.</para>

    <para>Soubor <filename>&lt;balíček&gt;-undeclared.txt</filename> uvádí symboly, které jsou zadané v <filename>&lt;balíček&gt;-section.txt</filename>, ale nebyly nalezené ve zdrojových kódech. Ověřte, jestli nebyly odstraněny, nebo v nich není překlep.</para>

    <para>Soubor  <filename>&lt;balíček&gt;-unused.txt</filename> uvádí názvy symbolů, které GTK-Doc při procházení dokumentace nalezl, ale neví, kam je zařadit. To znamená, že tyto symboly nejsou zatím zařazené v souboru <filename>&lt;balíček&gt;-section.txt</filename>.</para>

    <tip>
      <para>Povolte nebo přidejte řádek <option>TESTS=($GTKDOC_CHECK)</option> v Makefile.am. Pokud máte nainstalované GTK-Doc ve verzi minimálně 1.9, bude se díky tomu při spuštění <command>make check</command> provádět kontrola správnosti údajů.</para>
    </tip>

    <para>Můžete se také podívat do souborů vytvořených skenerem zdrojového kódu: <filename>&lt;package&gt;-decl-list.txt</filename> a <filename>&lt;package&gt;-decl.txt</filename>. První můžete porovnat se souborem s oddíly, pokud je ručně spravován. Ve druhém jsou uvedené všechny deklarace z hlavičkových souborů. Pokud v dokumentaci schází některý symbol, můžete zkontrolovat, jestli se vyskytuje v tomto souboru.</para>

    <para>Pokud je základem projektu GObject, můžete se také podívat do souborů vytvořených skenerem objektů: <filename>&lt;package&gt;.args.txt</filename>, <filename>&lt;package&gt;.hierarchy.txt</filename>, <filename>&lt;package&gt;.interfaces.txt</filename>, <filename>&lt;package&gt;.prerequisites.txt</filename> a <filename>&lt;package&gt;.signals.txt</filename>. Jestliže v kterémkoliv z nich jsou chybějící symboly, můžete spuštěním <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command> požádat GTK-Doc, aby přechodně zachovat soubor pro pozdější analýzu.</para>
  </chapter>

  <chapter id="modernizing">
    <title>Modernizace dokumentu</title>

    <para>GTK-Doc existuje již nějakou dobu. V této části je uveden seznam nových funkcí spolu s číslem verze, od které je tato funkčnost k dispozici.</para>

    <sect1 id="modernizing-gtk-doc-1-9">
      <title>GTK-Doc 1.9</title>

      <para>Když používáte XML namísto SGML, můžete ve skutečnosti pojmenovat hlavní dokument <filename>&lt;package&gt;-docs.xml</filename>.</para>

      <para>Tato verze podporuje <option>SCAN_OPTIONS=--rebuild-sections</option> v <filename>Makefile.am</filename>. Když je tato volba zapnutá, je <filename>&lt;package&gt;-sections.txt</filename> generován automaticky a můžete jej odstranit ze správy verzí. To funguje hezky je u projektů, které mají pravidelnou strukturu (například jednotlivé páry souboru .c a .h vytvoří nový oddíl). Pokud máte projekt takto pečlivě organizovaný, vystačí si aktualizace ručně spravovaného souboru s oddíly s prostým spuštěním <code>meld &lt;package&gt;-decl-list.txt &lt;package&gt;-sections.txt</code>.</para>

      <para>Již verze 1.18 zavedla syntax pro dokumentování oddílů ve zdrojovém kódu namísto zvláštních souborů ve složce <filename class="directory">tmpl</filename>. Tato verze přidává pomocí <option>--flavour no-tmpl</option> in <filename>configure.ac</filename> volbu pro přepnutí celého modulu dokumentace, aby nepoužíval speciální složku tmp během sestavení. Jestliže nepotřebujete udržovat <filename class="directory">tmpl</filename> v systému pro správu verzí ještě jste zatím přepnutí neprovedli, stačí přidat tuto volbu do <filename>configure.ac</filename> a je to.</para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-10">
      <title>GTK-Doc 1.10</title>

      <para>Tato verze podporuje <option>SCAN_OPTIONS=--rebuild-types</option> v <filename>Makefile.am</filename>. Když je tato volba zapnutá, je <filename>&lt;package&gt;.types</filename> generován automaticky a můžete jej odstranit ze správy verzí. Jestliže tuto funkci využíváte, je důležité nastavit také <varname>IGNORE_HFILES</varname> v <filename>Makefile.am</filename> pro kód, který je sestavován podmíněně.</para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-16">
      <title>GTK-Doc 1.16</title>

      <para>Součástí této verze je nový nástroj s názvem gtkdoc-check. Jeho spuštěním se provede kontrola správnosti vašeho dokumentu. Povolit jej můžete přidáním těchto řádků na konec souboru <filename>Makefile.am</filename>. <example><title>Povolení gtkdoc-check</title>
          <programlisting>
if ENABLE_GTK_DOC
TESTS_ENVIRONMENT = \
  DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
  SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
TESTS = $(GTKDOC_CHECK)
endif
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-20">
      <title>GTK-Doc 1.20</title>

      <para>Verze 1.18 přinesla počáteční podporu pro Markdown. Jeho použití v dokumentačních komentářích je méně rušivé, než zápis XML z DocBook. Tato verze jeho podporu značně vylepšuje a přidává mnohem více stylů. Více podrobností je uvedeno v oddílu, který vysvětluje <link linkend="documenting_syntax">syntax komentářů</link>.</para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-25">
      <title>GTK-Doc 1.25</title>

      <para>Soubory Makefile dodávané s touto verzí generují do <filename>xml/gtkdocentities.ent</filename> soubor s entitami, který obsahuje entity například pro package_name a package_version. Můžete je použít třeba v hlavním souboru XML, abyste nemuseli mít číslo verze zapsané natvrdo. Níže je uveden příklad, jak soubor s entitami vložit do hlavní šablony a jak entity použít. Použít je lze také ve všech generovaných souborech, GTK-Doc bude používat tu samou hlavičku XML v generovaných souborech XML. <example><title>Používání předgenerovaných entit</title>
          <programlisting>
&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  &lt;!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'"&gt;
  &lt;!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent"&gt;
  %gtkdocentities;
]&gt;
&lt;book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"&gt;
  &lt;bookinfo&gt;
    &lt;title&gt;&amp;Referenční příručka k package_name;&lt;/title&gt;
    &lt;releaseinfo&gt;
      for &amp;package_string;.
      Nejnovější verzi této dokumentace můžete najít on-line na
      &lt;ulink role="online-location" url="http://[SERVER]/&amp;package_name;/index.html"&gt;http://[SERVER]/&amp;package_name;/&lt;/ulink&gt;.
    &lt;/releaseinfo&gt;
  &lt;/bookinfo&gt;
</programlisting>
        </example></para>
    </sect1>
  </chapter>

  <chapter id="documenting-others">
    <title>Dokumentování ostatních rozhraní</title>

    <para>Doposud jsme pomocí GTK-Doc dokumentovali API kódu. Následující oddíl obsahuje doporučení, jak se dají nástroje použít také k dokumentování dalších rozhraní.</para>

    <sect1 id="commandline-interfaces">
      <title>Přepínače příkazového řádku a manuálové stránky</title>

      <para>Protože je stejně možné generovat manuálové stránky pro referenční položky DocBook, zní jako dobrý nápad použít to pro tento účel. Tímto způsobem se rozhraní stane součástí referenční příručky a získáte tak bez námahy manuálovou stránku.</para>

      <sect2 id="commandline-interfaces-file">
        <title>Dokumentování nástrojů</title>

        <para>Vytvořte jeden soubor s referenční příručkou pro každý z nástrojů. V <link linkend="settingup_docfiles">našem příkladu</link> by se měl nazývat <filename>meep/docs/reference/meeper/meep.xml</filename>. Na značky XML, který by se měly použít, se podívejte do nějakého ukázkového vygenerovaného souboru v podsložce XML, například v glib.</para>
      </sect2>

      <sect2 id="commandline-interfaces-configure">
        <title>Přidání doplňkových kontrol do configure</title>

        <para>
          <example><title>Dodatečné kontroly nastavení</title>
            <programlisting>
AC_ARG_ENABLE(man,
              [AC_HELP_STRING([--enable-man],
                              [regenerate man pages from Docbook [default=no]])],enable_man=yes,
              enable_man=no)

AC_PATH_PROG([XSLTPROC], [xsltproc])
AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)
</programlisting>
          </example>
        </para>
      </sect2>

      <sect2 id="commandline-interfaces-make">
        <title>Přidání doplňkových pravidel do Makefile</title>

        <para>
          <example><title>Dodatečné kontroly nastavení</title>
            <programlisting>
man_MANS = \
       meeper.1

if ENABLE_GTK_DOC
if ENABLE_MAN

%.1 : %.xml
        @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $&lt;

endif
endif

BUILT_EXTRA_DIST = $(man_MANS)
EXTRA_DIST += meep.xml
</programlisting>
          </example>
        </para>
      </sect2>
    </sect1>

    <sect1 id="dbus-interfaces">
      <title>Rozhraní D-Bus</title>

      <para>(OPRAVIT: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)</para>
    </sect1>

  </chapter>

  <chapter id="faq">
    <title>Často kladené dotazy</title>

    <segmentedlist>
      <?dbhtml list-presentation="list"?>
      <segtitle>Dotaz</segtitle>
      <segtitle>Odpověď</segtitle>
      <seglistitem>
        <seg>Schází hierarchie třídy.</seg>
        <seg>Do souboru <filename>&lt;balíček&gt;.types</filename> nebyla vložena funkce objektu <function>xxx_get_type()</function>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Stále schází hierarchie třídy.</seg>
        <seg>Chybějící nebo nesprávné pojmenování souboru <filename>&lt;balíček&gt;-sections.txt</filename> (viz <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">vysvětlení</ulink>).</seg>
      </seglistitem>
      <seglistitem>
        <seg>Do háje, pořád nemám hierarchii třídy.</seg>
        <seg>Je název objektu (název struktury instance, například <type>GtkWidget</type>) součástí normálního oddílu? (Nedávejte je do pododdílu Standard nebo Private).</seg>
      </seglistitem>
      <seglistitem>
        <seg>Chybí rejstřík symbolů.</seg>
        <seg>Obsahuje <filename>&lt;package&gt;-docs.{xml,sgml}</filename> rejstřík, který vloží pomocí xi:include vygenerovaný rejstřík?</seg>
      </seglistitem>
      <seglistitem>
        <seg>Symbol nemá odkaz do svého oddílu dokumentace.</seg>
        <seg>Používá dokumentační komentář správnou značku (přidané znaky #,% nebo ())? Podívejte se na varování gtkdoc-fixxref o nevyřešených křížových odkazech.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Nová třída se neobjevila v dokumentaci.</seg>
        <seg>Je nový balíček vložený pomocí xi:include z <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Nový symbol se neobjevil v dokumentaci.</seg>
        <seg>Je dokumentační komentář správně naformátovaný? Zkontrolujte překlepy na začátku komentáře. Podívejte se po varováních gtkdoc-fixxref o nevyřešených křížových odkazech. Zkontrolujte, jestli je symbol správně uvedený v <filename>&lt;package&gt;-sections.txt</filename> ve veřejném pododdíle.</seg>
      </seglistitem>
      <seglistitem>
        <seg>V hierarchii třídy schází typ.</seg>
        <seg>Jestliže je typ uvedený v <filename>&lt;package&gt;.hierarchy</filename>, ale není v <filename>xml/tree_index.sgml</filename>, tak raději dvakrát zkontrolujte, jestli je typ správně uvedený v <filename>&lt;package&gt;-sections.txt</filename>. Jestliže instance typu (například <type>GtkWidget</type>) není uvedená, nebo je nedopatřením označení jako privátní, nebude zobrazena.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Vytvořily se mi odkazy na složku s dokumentací pro všechny anotace k GObject</seg>
        <seg>Zkontrolujte, že <filename>xml/annotation-glossary.xml</filename> je vložené pomocí xi:include z <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.</seg>
      </seglistitem>

      <!-- gtk-doc warnings: -->
      <seglistitem>
        <seg>Parametr je v komentářovém bloku zdrojového kódu popsaný, ale neexistuje.</seg>
        <seg>Zkontrolujte, za nemá prototyp v hlavičkovém souboru jiné názvy parametrů, než ve zdrojovém kódu.</seg>
      </seglistitem>

      <!-- docbook warnings: -->
      <seglistitem>
        <seg>Více „ID“ pro tentýž cíl odkazu: XYZ</seg>
        <seg>Symbol XYZ se v souboru <filename>&lt;package&gt;-sections.txt</filename> objevuje dvakrát.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Element typename ve jmenném prostoru '' je uvedený v rodiči, ale neodpovídá mu žádná šablona.</seg>
        <seg/>
      </seglistitem>
    </segmentedlist>
  </chapter>

  <chapter id="contrib">
    <title>Nástroje související s GTK-Doc</title>

    <para>GtkDocPlugin – zásuvný modul pro integraci <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">GTK-Doc do systému Track</ulink>, který přidává dokumentaci k API na sledovací web a integruje ji do vyhledávání.</para>
    <para>Gtkdoc-depscan – nástroj (součást GTK-Doc), který kontroluje použité API vůči štítku since v API, aby určil minimální požadovanou verzi.</para>

  </chapter>

  <!-- ======== Appendix: FDL ================================== -->
  

</book>
