<?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="sr">
  <bookinfo>
    <title>Упутство за ГТК-док</title>
    <edition>1.24.1</edition>
    <abstract role="description"><para>Корисничко упутство за програмере са упутствима за употребу ГТК-дока.</para></abstract>
    <authorgroup>
      <author><firstname>Крис</firstname> <surname>Лајтл</surname> <affiliation> <address> <email>chris@wilddev.net</email> </address> </affiliation></author>
      <author><firstname>Ден</firstname> <surname>Мует</surname> <affiliation> <address> <email>d-mueth@uchicago.edu</email> </address> </affiliation></author>
      <author><firstname>Штефан</firstname> <surname>Зауер (Кост)</surname> <affiliation> <address> <email>ensonic@users.sf.net</email> </address> </affiliation></author>
    </authorgroup>
    <publisher role="maintainer"><publishername>Пројекат ГТК-док</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
    <copyright><year>2000, 2005</year> <holder>Ден Мует и Крис Лајтл</holder></copyright>
    <copyright><year>2007-2019</year> <holder>Штефан Зауер (Кост)</holder></copyright>

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

    <legalnotice>
      <para>Дозвољено је умножавање, дељење и/или мењање овог документа под условима <citetitle>ГНУ-ове лиценце за слободну документацију</citetitle>, верзије 1.1 или било које новије верзије коју објави Задужбина слободног софтвера без непроменљивих одељака, без текста на насловној страни и без текста на задњој страни. Примерак лиценце је <link linkend="fdl">укључен</link>.</para>
      <para>Многи називи које компаније користе да би разликовале своје производе и услуге су заштићени као робне марке. На местима где се ти називи појављују у било којој Гномовој документацији, а чланови Гномовог пројекта документације су обавештени о тим робним маркама, називи су штампани великим словима или са почетним великим словом.</para>
    </legalnotice>

    <revhistory>
      <revision><revnumber>1.33.0</revnumber> <date>1. окт 2020.</date> <authorinitials>mc</authorinitials> <revremark>издање за гтк4</revremark></revision>
      <revision><revnumber>1.32.1</revnumber> <date>15. авг 2019.</date> <authorinitials>ss</authorinitials> <revremark>развојно издање</revremark></revision>
      <revision><revnumber>1.32</revnumber> <date>15. авг 2019.</date> <authorinitials>ss</authorinitials> <revremark>издање са хитном исправком</revremark></revision>
      <revision><revnumber>1.31</revnumber> <date>5. авг 2019.</date> <authorinitials>ss</authorinitials> <revremark>прераде кода и већа покривеност тестовима</revremark></revision>
      <revision><revnumber>1.30</revnumber> <date>8. мај 2019.</date> <authorinitials>ss</authorinitials> <revremark>већа покривеност тестовима</revremark></revision>
      <revision><revnumber>1.29</revnumber> <date>28. авг 2018.</date> <authorinitials>ss</authorinitials> <revremark>исправке грешака</revremark></revision>
      <revision><revnumber>1.28</revnumber> <date>24. мар 2018.</date> <authorinitials>ss</authorinitials> <revremark>исправке грешака</revremark></revision>
      <revision><revnumber>1.27</revnumber> <date>7. дец 2017.</date> <authorinitials>ss</authorinitials> <revremark>фино подешавање преноса на пајтон</revremark></revision>
      <revision><revnumber>1.26</revnumber> <date>11. авг 2017.</date> <authorinitials>ss</authorinitials> <revremark>пренос свих алата са перла/баша на пајтон</revremark></revision>
      <revision><revnumber>1.25</revnumber> <date>21. март 2016.</date> <authorinitials>ss</authorinitials> <revremark>исправке грешака, чишћење тестова</revremark></revision>
      <revision><revnumber>1.24</revnumber> <date>29. мај 2015.</date> <authorinitials>ss</authorinitials> <revremark>исправка грешке</revremark></revision>
      <revision><revnumber>1.23</revnumber> <date>17. мај 2015.</date> <authorinitials>ss</authorinitials> <revremark>исправка грешке</revremark></revision>
      <revision><revnumber>1.22</revnumber> <date>07. мај 2015.</date> <authorinitials>ss</authorinitials> <revremark>исправке грешака, одбацивање застарелих могућности</revremark></revision>
      <revision><revnumber>1.21</revnumber> <date>17. јул 2014.</date> <authorinitials>ss</authorinitials> <revremark>исправке грешака, одбацивање застарелих могућности</revremark></revision>
      <revision><revnumber>1.20</revnumber> <date>16. фебруар 2014.</date> <authorinitials>ss</authorinitials> <revremark>исправке грешака, подршка за маркдаун, побољшања стила</revremark></revision>
      <revision><revnumber>1.19</revnumber> <date>05. јун 2013.</date> <authorinitials>ss</authorinitials> <revremark>исправке грешака</revremark></revision>
      <revision><revnumber>1.18</revnumber> <date>14. септембар 2011.</date> <authorinitials>ss</authorinitials> <revremark>исправке грешака, убрзања, подршка за маркдаун</revremark></revision>
      <revision><revnumber>1.17</revnumber> <date>26. фебруар 2011.</date> <authorinitials>sk</authorinitials> <revremark>хитно ажурирање исправке грешке</revremark></revision>
      <revision><revnumber>1.16</revnumber> <date>14. јануар 2011.</date> <authorinitials>sk</authorinitials> <revremark>исправке грешака, побољшања распореда</revremark></revision>
      <revision><revnumber>1.15</revnumber> <date>21. мај 2010.</date> <authorinitials>sk</authorinitials> <revremark>исправке грешака и регресија</revremark></revision>
      <revision><revnumber>1.14</revnumber> <date>28. март 2010.</date> <authorinitials>sk</authorinitials> <revremark>исправке грешака и побољшања учинка</revremark></revision>
      <revision><revnumber>1.13</revnumber> <date>18. децембар 2009.</date> <authorinitials>sk</authorinitials> <revremark>ажурирање оштећене тар архиве</revremark></revision>
      <revision><revnumber>1.12</revnumber> <date>18. децембар 2009.</date> <authorinitials>sk</authorinitials> <revremark>нове могућности алата и исправке грешака</revremark></revision>
      <revision><revnumber>1.11</revnumber> <date>16. новембар 2008.</date> <authorinitials>mal</authorinitials> <revremark>прелазак на Гномове алатке документације</revremark></revision>
    </revhistory>

  </bookinfo>

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

  <chapter id="introduction">
    <title>Увод</title>

    <para>Ово поглавље уводи ГТК-док и даје преглед шта је он и како се користи.</para>

    <sect1 id="whatisgtkdoc">
      <title>Шта је ГТК-док?</title>

      <para>ГТК-док се користи за документовање Ц кода. Обично се користи за документовање јавног АПИ-ја библиотека, као што су библиотеке засноване на ГЛиб-у, али се такође може користити за документовање кода програма.</para>
    </sect1>

    <sect1 id="howdoesgtkdocwork">
      <title>Како ГТК-док ради?</title>

      <para>ГТК-док ради тако што чита посебно обликоване блокове коментара постављене унутар изворних датотека ради документовања симбола као што су функције, макрои, структуре, набрајања итд. (иако имајте у виду да ће за већину врста симбола ГТК-док документовати само симболе који су објављени у датотекама заглавља; на пример, неће произвести излаз за статичке функције).</para>

      <para>ГТК-док такође чита датотеке шаблона где се документација такође може додати.</para>

      <para>ГТК-Док се састоји од низа програма, од којих сваки обавља различит корак у процесу.</para>

      <para>Главни кораци су:</para>

      <orderedlist>

        <listitem>
          <para><guilabel>Писање документације.</guilabel> Аутор попуњава изворне датотеке документацијом за сваку функцију, макро, структуру или унију, итд.</para>
        </listitem>

        <listitem>
          <para><guilabel>Прикупљање података о коду.</guilabel> <application>gtkdoc-scan</application> прегледа датотеке заглавља кода тражећи декларације функција, макроа, набрајања, структура и унија. Прави датотеку <filename>&lt;module&gt;-decl-list.txt</filename> која садржи списак декларација, смештајући их у одељке према томе у којој се датотеци заглавља налазе. При првом покретању ова датотека се копира у <filename>&lt;module&gt;-sections.txt</filename>. Аутор може преуредити одељке и редослед декларација унутар њих како би добио коначни жељени поредак. Друга датотека коју генерише је <filename>&lt;module&gt;-decl.txt</filename>. Ова датотека садржи потпуне декларације које је пронашао прегледач. Ако из неког разлога желите да се неки симболи појаве у документацији, а прегледач не може да пронађе потпуну декларацију или би декларација требало да изгледа другачије, можете поставити ставке сличне онима у <filename>&lt;module&gt;-decl.txt</filename> у <filename>&lt;module&gt;-overrides.txt</filename>.</para>
         <para><application>gtkdoc-scangobj</application> се такође може користити за динамички упит библиотеци о свим подкласама Г-објекта (GObject) које она извози. Сачуваће податке о положају сваког објекта у хијерархији класа и о свим својствима и сигналима Г-објекта које пружа.</para>
         <para><application>gtkdoc-scanobj</application> више не би требало користити. Био је потребан у прошлости када је GObject још увек био GtkObject унутар ГТК-а.</para>
        </listitem>

        <listitem>
          <para><guilabel>Стварање XML-а и HTML-а/PDF-а.</guilabel> <application>gtkdoc-mkdb</application> претвара датотеке шаблона у XML датотеке у <filename class="directory">xml/</filename> поддиректоријуму. Ако изворни код садржи документацију за симболе, користећи посебне блокове коментара, она се овде стапа. Ако се не користе tmpl датотеке, он само чита документацију из извора и података интроспекције.</para>
          <para><application>gtkdoc-mkhtml</application> претвара XML датотеке у HTML датотеке у <filename class="directory">html/</filename> поддиректоријуму. Исто тако <application>gtkdoc-mkpdf</application> претвара XML датотеке у PDF документ под називом <filename>&lt;package&gt;.pdf</filename>.</para>
          <para>Датотеке у <filename class="directory">xml/</filename> и <filename class="directory">html/</filename> директоријумима се увек преписују. Никада их не треба директно уређивати.</para>
        </listitem>

        <listitem>
          <para><guilabel>Исправљање унакрсних референци између докумената.</guilabel> Након инсталирања HTML датотека, може се покренути <application>gtkdoc-fixxref</application> ради исправљања унакрсних референци између засебних докумената. На пример, ГТК документација садржи многе унакрсне референце на врсте документоване у ГЛиб (GLib) приручнику.</para>
          <para>Приликом прављења изворне архиве (tarball) за дистрибуцију, <application>gtkdoc-rebase</application> претвара све спољне везе у веб-везе. Приликом инсталирања дистрибуиране (унапред генерисане) документације, исти програм ће покушати да врати везе на локалне везе (тамо где је та документација инсталирана).</para>
        </listitem>
      </orderedlist>

    </sect1>

    <sect1 id="gettinggtkdoc">
      <title>Набављање ГТК-Дока</title>

      <sect2 id="requirements">
        <title>Захтеви</title>
        <para><guilabel>пајтон 2/3</guilabel> — главне скрипте су написане у пајтону.</para>
        <para><guilabel>xsltproc</guilabel> — XSLT процесор из libxslt-а <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink></para>
        <para><guilabel>docbook-xsl</guilabel> — DocBook XSL стилски листови <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink></para>
        <para>Један од <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> или <guilabel>vim</guilabel> — опционо — користи се за истицање синтаксе у примерима</para>
      </sect2>
    </sect1>

    <sect1 id="aboutgtkdoc">
      <title>О ГТК-Доку</title>

      <para>Историјски гледано, ГТК-Док је коришћен за генерисање датотека шаблона из изворног кода. Ове датотеке шаблона су програмери могли користити за унос АПИ документације. Овај приступ је био прилично незгодан јер је захтевао чување генерисаних датотека под контролом верзија. Од верзије ГТК-Док 1.9 постало је могуће поставити све АПИ податке у изворне коментаре, што је подршку за шаблоне учинило застарелом. У верзији 1.26 подршка за шаблоне је уклоњена.</para>

      <para>(ПОПРАВИМЕ)</para>

      <para>(аутори, веб странице, дописна листа, лиценца, будући планови, поређење са другим сличним системима.)</para>

    </sect1>

    <sect1 id="aboutthismanual">
      <title>О овом приручнику</title>

      <para>(ПОПРАВИМЕ)</para>

      <para>(коме је намењен, где га можете набавити, лиценца)</para>

    </sect1>

  </chapter>

  <chapter id="settingup">
    <title>Подешавање пројекта</title>

    <para>Ово поглавље описује кораке који су неопходни за интегрисање Гтк-документације (GTK-Doc) у ваш пројекат. Интеграција Гтк-документације у пројекат укључује следеће кораке:</para>

    <itemizedlist>
      <listitem>
        <para>Припрема структуре директоријума и стварање потребних датотека подешавања за вашу Гтк-документацију (погледајте <link linkend="settingup_docfiles">Постављање скелета документације</link>).</para>
      </listitem>
      <listitem>
        <para>Прилагођавање система изградње за изградњу ваше документације помоћу алата Гтк-документације. Подржано је више система изградње, у овом приручнику описујемо како да интегришете Гтк-документацију са <link linkend="settingup_autotools">Ауто-алатима (Autotools)</link>, <link linkend="settingup_cmake">Ц-мејком (CMake)</link> и <link linkend="settingup_plain_makefiles">обичним Мејк-датотекама (Makefiles)</link>.</para>
      </listitem>
      <listitem>
        <para>Додавање датотека специфичних за Гтк-документацију у систем за управљање верзијама и одлучивање о томе које датотеке треба занемарити (погледајте <link linkend="settingup_vcs">Интеграција са системима за управљање верзијама</link>).</para>
      </listitem>
    </itemizedlist>

    <para>Следећи одељци претпостављају да радимо на пројекту под називом <code>meep</code>. Овај пројекат садржи два пакета (или модула), библиотеку под називом <code>libmeep</code> и апликацију за крајњег корисника под називом <code>meeper</code>.</para>

    <sect1 id="settingup_docfiles">
      <title>Постављање скелета документације</title>

      <para>Уобичајена конвенција је да се документација постави у фасциклу под називом <code>docs</code> унутар главног директоријума вашег пројекта. Обично разликујемо <emphasis>референтну документацију</emphasis> намењену програмерима и <emphasis>кориснички приручник</emphasis> намењен крајњим корисницима. Опет, конвенција је да постоје посебне фасцикле за оба. Обично референтну документацију стављамо у фасциклу под називом <code>reference</code>, а кориснички приручник у фасциклу под називом <code>help</code>. Према горе наведеној конвенцији, документација за наш пакет <code>libmeep</code> била би постављена у: <code>docs/reference/libmeep</code>. За пакете са само једном библиотеком или апликацијом, документација би се такође могла поставити директно у <code>docs/reference</code>. Није обавезно користити горе наведену конвенцију, али ако изаберете другачију структуру директоријума, морате прилагодити подешавања вашег система изградње како би одговарала вашој структури директоријума.</para>

      <para>У следећим одељцима претпоставићемо структуру директоријума за наш пројекат <emphasis>meep</emphasis> који користи горе наведене конвенције. <example>
          <title>Пример структуре директоријума пројекта <emphasis>meep</emphasis></title>
          <programlisting>
meep/
  docs/
    reference/  # референтна документација
      libmeep/
      meeper/
    help/       # опционо: кориснички приручник
      meeper/
  src/
    libmeep/
    meeper/
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="settingup_autotools">
      <title>Интеграција са Ауто-алатима (Autotools)</title>
      <para>Интеграција Гтк-документације у систем изградње заснован на Ауто-алатима захтева следеће кораке:</para>
      <itemizedlist>
        <listitem>
          <para>Осигурајте да се <application>gtkdocize</application> покрене једном пре скрипте <filename>configure</filename>. Ако је присутна скрипта <filename>autogen.sh</filename>, прилагодите је тако да проверава Гтк-документацију и додајте позив за <application>gtkdocize</application>.</para>

          <para>Главна сврха програма <application>gtkdocize</application> је да учини <filename>gtk-doc.make</filename> Мејк-датотеку и <filename>gtk-doc.m4</filename> датотеку дефиниције макроа доступним систему изградње, било копирањем или повезивањем у пројекат.</para>
        </listitem>
        <listitem>
          <para>Додајте неопходне <application>autoconf</application> макрое у <filename>configure.ac</filename> да бисте омогућили ГТК-док у вашем систему изградње и омогућили подешавање ГТК-дока путем генерисане <filename>configure</filename> скрипте.</para>
          <para>Између осталих, региструје опцију <code>--enable-gtk-doc</code> код <filename>configure</filename> скрипте.</para>
        </listitem>
        <listitem>
          <para>Направите <application>automake</application> скрипту за сваки програм или библиотеку у вашем пројекту. У примеру који се користи у овој документацији, овај корак се односи и на <code>meeper</code> и на <code>libmeep</code>.</para>
        </listitem>
      </itemizedlist>

      <para>У следећим одељцима, извршићемо горе наведене кораке обрнутим редоследом. Почињемо са <application>automake</application> скриптама и настављамо до <filename>configure.ac</filename> и <filename>autogen.sh</filename>. Затим показујемо како да омогућите Гтк-док у систему изградње и како да изградите документацију.</para>

      <sect2 id="settingup_automake">
        <title>Интеграција са аутомејком</title>

        <para>Прво копирајте <filename>Makefile.am</filename> из поддиректоријума <filename class="directory">examples</filename> са <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am"> gtkdoc-sources</ulink> у директоријум референтне документације вашег пројекта (нпр. <filename class="directory">docs/reference/&lt;package&gt;</filename>). Локална копија би требало да буде доступна под нпр. <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Ако имате више пакета, поновите ово за сваки од њих.</para>

        <note>
          <simpara>Не заборавите да додате сваки <filename>Makefile.am</filename> у <function>AC_CONFIG_FILES</function> макро у <filename>configure.ac</filename>. За <filename>docs/reference/libmeep/Makefile.am</filename> мораћете да додате унос <filename>docs/reference/libmeep/Makefile</filename> у <function>AC_CONFIG_FILES</function>.</simpara>
        </note>

        <example>
          <title>Пример структуре директоријума са <filename>Makefiles.am</filename></title>
          <programlisting>
meep/
  docs/
    reference/  # референтна документација
      libmeep/
        Makefile.am
      meeper/
        Makefile.am
    help/       # опционално: корисничко упутство
      meeper/
  src/
    libmeep/
    meeper/
</programlisting>
        </example>

        <para>Затим треба да прилагодите копиране датотеке Makefile и обезбедите вредности за различите параметре у сваком <filename>Makefile.am</filename>. Сва подешавања имају коментар изнад који описује њихову сврху и како да их прилагодите. Већина подешавања се користи за достављање додатних опција одговарајућим алатима на које се односе. Сваки алат има променљиву облика <option>&lt;TOOLNAME&gt;_OPTIONS</option> (нпр. алат <application>gtkdoc-mkhtml</application> има опцију под називом <code>MKHTML_OPTIONS</code>). Сви алати подржавају <option>--help</option> за исписивање подржаних опција.</para>

        <para>Следећи списак објашњава најрелевантније опције. Погледајте пример <filename>Makefile.am</filename> за додатне опције. <itemizedlist>
            <listitem>
              <para><option>DOC_MODULE</option> се користи за навођење назива пакета који се документује (нпр. <code>meeper</code> или <code>libmeep</code>).</para>
            </listitem>
            <listitem>
              <para><option>DOC_SOURCE_DIR</option> се користи за навођење путање изворног директоријума у којем ГТК-док тражи вашу АПИ документацију. Ово ће обично бити <code> DOC_SOURCE_DIR=$(top_srcdir)/src </code> или поддиректоријум тог директоријума.</para>
            </listitem>

            <listitem>
              <para><option>HFILE_GLOB</option> и <option>CFILE_GLOB</option> се користе за зависности. Свака опција узима шаблон датотека (нпр. <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>). Документација ће бити поново изграђена ако се било која од подударних датотека промени.</para>
            </listitem>

            <listitem>
              <para><option>EXTRA_HFILES</option> омогућава навођење додатних датотека заглавља које треба укључити приликом скенирања АПИ документације, а које се не налазе под <code>DOC_SOURCE_DIR</code> (нпр. <code> EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).</para>
            </listitem>

            <listitem>
              <para><option>IGNORE_HFILES</option> омогућава навођење датотека заглавља или директоријума које треба занемарити приликом скенирања АПИ документације. Користите основни назив датотеке или директоријума (нпр. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).</para>
            </listitem>

            <listitem>
              <para><option>HTML_IMAGES</option> омогућава навођење датотека слика које ће бити копиране у <filename>html/</filename> директоријум генерисане документације. Ако ваша АПИ документација укључује било какве слике, оне морају бити додате у ову опцију (нпр. <code> HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).</para>
            </listitem>

            <listitem>
              <para><option>content_files</option> омогућава навођење додатних датотека које су укључене у <code>$(DOC_MAIN_SGML_FILE)</code> (нпр. <code> content_files=running.xml building.xml changes-2.0.xml</code>).</para>
            </listitem>

            <listitem>
              <para><option>expand_content_files</option> омогућава навођење датотека у којима се <emphasis>gtk-doc скраћенице</emphasis> као што је <code>#GtkWidget</code> проширују (нпр. <code> expand_content_files=running.xml</code>).</para>
            </listitem>
          </itemizedlist></para>

      </sect2>

      <sect2 id="settingup_autoconf">
        <title>Интеграција са autoconf-ом</title>

        <para>Интеграција са <application>autoconf-ом</application> је врло једноставна и укључује један обавезан корак и додатни опциони (али препоручени) корак. Први корак је додавање <function>GTK_DOC_CHECK</function> макроа у вашу <filename>configure.ac</filename> скрипту. Ово региструје неколико опција подешавања за омогућавање ГТК-Документације и омогућава вам да поставите подразумеване аргументе за <application>gtkdocize</application>.</para>

        <warning>
          <simpara>Уверите се да <code>GTK_DOC_CHECK</code> макро није увучен. Макро мора почети на почетку реда и не би требало да почиње празнином.</simpara>
        </warning>

        <para>Други корак је додавање <code>AC_CONFIG_MACRO_DIR(m4)</code> у ваш <filename>configure.ac</filename>. Ово није обавезно, али помаже <application>gtkdocize-у</application> да аутоматски копира дефиницију макроа (нпр. <filename>gtk-doc.m4</filename>) која садржи <function>GTK_DOC_CHECK</function> макро у директоријум макроа вашег пројекта. Без овога, макро GTK_DOC_CHECK можда неће бити пронађен и морали бисте експлицитно рећи алату <application>aclocal</application> где да пронађе датотеку дефиниције макроа.</para>

        <para>
          <example><title>Минимална интеграција са autoconf-ом</title>
            <programlisting>
# препоручено: поставите m4 директоријум
AC_CONFIG_MACRO_DIR(m4)
# опционо: региструјте gtk-doc у configure
GTK_DOC_CHECK([1.28])
</programlisting>
          </example>
        </para>

        <para>Горњи пример ради, али ће захтевати да сви програмери имају инсталиран gtk-doc. Бољи начин је да изградња документације буде опциона као што је приказано у следећем примеру: <example>
            <title>Интеграција са опционом gtk-doc зависношћу</title>
            <programlisting>
m4_ifdef([GTK_DOC_CHECK], [
# препоручено: поставите m4 директоријум
AC_CONFIG_MACRO_DIR(m4)
# опционо: региструјте gtk-doc у configure
GTK_DOC_CHECK([1.28])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
</programlisting>
          </example></para>

        <para>Први аргумент се користи за проверу издања Гтк-Документације у време подешавања. Други, опциони аргумент користи <application>gtkdocize</application>. Макро <symbol>GTK_DOC_CHECK</symbol> такође додаје неколико прекидача подешавања:</para>

        <orderedlist>
          <listitem><para>--with-html-dir=ПУТАЊА : путања до инсталиране документације</para></listitem>
          <listitem><para>--enable-gtk-doc : користи gtk-doc за изградњу документације [подразумевано=no]</para></listitem>
          <listitem><para>--enable-gtk-doc-html : изгради документацију у html формату [подразумевано=yes]</para></listitem>
          <listitem><para>--enable-gtk-doc-pdf : изгради документацију у pdf формату [подразумевано=no]</para></listitem>
        </orderedlist>

        <important>
          <para>ГТК-Документација је онемогућена по дефолту! Не заборавите да проследите опцију <option>'--enable-gtk-doc'</option> следећем покретању <filename>configure</filename> скрипте. У супротном се инсталира унапред генерисана документација (што има смисла за кориснике, али не и за програмере).</para>
        </important>

        <para>Након што су све измене у <filename>configure.ac</filename> направљене, ажурирајте <filename>configure</filename> датотеку. Ово се може урадити поновним покретањем <code>autogen.sh</code>.</para>
      </sect2>

      <sect2 id="settingup_autogen">
        <title>Интеграција са autogen-ом</title>

        <para>Већина пројеката ће имати <filename>autogen.sh</filename> скрипту за подешавање инфраструктуре изградње након што је пројекат преузет из система за контролу верзија (као што су git или svn). ГТК-Документација долази са скриптом званом <application>gtkdocize</application> која се може користити за копирање неопходних датотека потребних Гтк-Документацији у изворни директоријум.</para>

        <para>Требало би да се покрене пре autoreconf, autoheader, automake или autoconf програма.</para>

        <para>
          <example><title>Покретање gtkdocize-а из autogen.sh</title>
            <programlisting>
gtkdocize || exit 1
</programlisting>
          </example>
        </para>

        <para>
          <example>
            <title>Условно покрените gtkdocize из autogen.sh</title>
            <programlisting>
GTKDOCIZE=$(which gtkdocize 2&gt;/dev/null)
if test $? -ne 0; then
  echo "Није пронађена подршка за gtk-doc. Не можете изградити документацију."
else
  $GTKDOCIZE || exit 1
fi
</programlisting>
          </example>
        </para>

        <para>Када се покрене <application>gtkdocize</application>, он копира <filename>gtk-doc.make</filename> у корен вашег пројекта (или било који директоријум наведен опцијом <option>--docdir</option>).</para>

        <para><application>gtkdocize</application> проверава вашу <filename>configure.ac</filename> скрипту за макро <function>GTK_DOC_CHECK</function>. Макро <function>GTK_DOC_CHECK</function> се може користити за прослеђивање додатних аргумената скрипти <application>gtkdocize</application> преко другог параметра у макроу <function>GTK_DOC_CHECK</function>.</para>

        <para>Алтернативно, додатни аргументи се такође могу проследити програму <application>gtkdocize</application> преко променљиве окружења <function>GTKDOCIZE_FLAGS</function>, или директним навођењем у <filename>autogen.sh</filename>.</para>

      </sect2>

      <sect2 id="settingup_firstrun">
        <title>Извршавање ГТК-документације из система за изградњу</title>

        <para>Након претходних корака, време је за покретање изградње. Прво морамо поново покренути <filename>autogen.sh</filename>. Ако ова скрипта покреће configure уместо вас, тада јој проследите опцију <option>--enable-gtk-doc</option>. У супротном, ручно покрените <filename>configure</filename> са овом опцијом након тога.</para>
        <para>Прво покретање наредбе make генерише неколико додатних датотека у директоријумима документације. Важне су: <filename>&lt;package&gt;.types</filename>, <filename>&lt;package&gt;-docs.xml</filename> (раније .sgml), <filename>&lt;package&gt;-sections.txt</filename>.</para>
        <para>
          <example><title>Покретање изградње документације</title>
            <programlisting>
./autogen.sh --enable-gtk-doc
make
</programlisting>
          </example>
        </para>

        <para>Сада можете усмерити свој веб прегледач на <filename>docs/reference/&lt;package&gt;/index.html</filename>. Са овим почетним подешавањем видећете само врло једноставан документ. Следеће поглавље ће вас научити како да додате АПИ документацију у свој код путем посебних блокова коментара. Поглавље након тога уводи <link linkend="metafiles">додатне датотеке</link> и показује како да уредите <link linkend="metafiles_master">главни шаблон</link> да бисте додали додатна поглавља и одељке својим датотекама документације.</para>

      </sect2>

    </sect1>

    <sect1 id="settingup_cmake">
      <title>Интеграција са CMake системима за изградњу</title>

      <para>ГТК-документација сада пружа <filename>GtkDocConfig.cmake</filename> модул (и одговарајући <filename>GtkDocConfigVersion.cmake</filename> модул). Ово омогућава наредбу <literal>gtk_doc_add_module</literal> коју можете поставити у своју <filename>CMakeLists.txt</filename> датотеку.</para>

      <para>Следећи пример показује како се користи ова наредба. <example><title>Пример коришћења ГТК-документације из CMake-а</title>
          <programlisting>
find_package(GtkDoc 1.25 REQUIRED)

# Create the doc-libmeep target.
gtk_doc_add_module(
   libmeep ${CMAKE_SOURCE_DIR}/libmeep
      XML meep-docs.xml
      LIBRARIES libmeep
)

# Build doc-libmeep as part of the default target. Without this, you would
# have to explicitly run something like `make doc-libmeep` to build the docs.
add_custom_target(documentation ALL DEPENDS doc-libmeep)

# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
# to set the CMAKE_INSTALL_DOCDIR variable correctly).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
        DESTINATION ${CMAKE_INSTALL_DOCDIR})
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="settingup_plain_makefiles">
      <title>Интеграција са обичним make-датотекама или другим системима за изградњу</title>

      <para>У случају да неко не жели да користи automake, а самим тим ни <filename>gtk-doc.mak</filename>, мораће да позове gtkdoc алате у исправном редоследу у сопственим make-датотекама (или другим алатима за изградњу).</para>

      <para>
        <example><title>Кораци изградње документације</title>
          <programlisting>
DOC_MODULE=meep
// извори су измењени
gtkdoc-scan --module=$(DOC_MODULE) &lt;source-dir&gt;
gtkdoc-scangobj --module=$(DOC_MODULE)
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=&lt;source-dir&gt;
// xml датотеке су измењене
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>Требаће погледати у <filename>Makefile.am</filename> и <filename>gtk-doc.mak</filename> како бисте одабрали потребне додатне опције.</para>
    </sect1>

    <sect1 id="settingup_vcs">
      <title>Интеграција са системима за управљање верзијама</title>

      <para>Као опште правило, датотеке које уређујете треба да буду под контролом верзија. За типичне пројекте то су следеће датотеке: <filename>&lt;package&gt;.types</filename>, <filename>&lt;package&gt;-docs.xml</filename> (раније .sgml), <filename>&lt;package&gt;-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
      <para>Датотеке у директоријумима <filename>xml/</filename> и <filename>html/</filename> не би требало да буду под контролом верзија. Исто важи и за било коју од <filename>.stamp</filename> датотека.</para>
    </sect1>

  </chapter>

  <chapter id="documenting">
    <title>Документовање кода</title>

    <para>ГТК-Док користи коментаре у изворном коду са посебном синтаксом за документацију кода. Такође, он преузима информације о структури вашег пројекта из других извора. У следећем одељку наћи ћете све информације о синтакси коментара.</para>

    <para>Скенер ГТК-Дока може добро да обради већину Ц заглавља. У случају добијања упозорења од скенера која изгледају као посебан случај, можете наговестити ГТК-Доку да их прескочи. <example><title>ГТК-Док блок коментара</title>
        <programlisting>
#ifndef __GTK_DOC_IGNORE__
/* код који се не може рашчланити је овде */
#endif
</programlisting>
      </example></para>

    <note>
      <title>Ограничења</title>
      <para>Имајте на уму да ГТК-Док подржава <code>#ifndef(__GTK_DOC_IGNORE__)</code> али не и <code>#if !defined(__GTK_DOC_IGNORE__)</code> или друге комбинације.</para>
    </note>

    <!--  -->

    <sect1 id="documenting_syntax">
      <title>Коментари документације</title>

      <para>Вишередни коментар који почиње са додатним знаком „*“ означава блок документације који ће обрадити алати ГТК-Дока. <example><title>ГТК-Док блок коментара</title>
          <programlisting>
/**
 * идентификатор:
 * документација ...
 */
</programlisting>
        </example></para>

      <para>„Идентификатор“ је један ред са називом ставке на коју се коментар односи. Синтакса се мало разликује у зависности од ставке. (ДА СЕ УРАДИ: додати табелу која приказује идентификаторе)</para>

      <para>Блок „документација“ је такође различит за сваку врсту симбола. Врсте симбола који примају параметре, као што су функције или макрои, имају прво опис параметара након чега следи празан ред (само „*“). Затим следи детаљан опис. Сви редови (изван програмских спискова и CDATA одељака) који садрже само „ *“ (размак-звездица) претварају се у преломе пасуса. Ако не желите прелом пасуса, промените то у „ *  “ (размак-звездица-размак-размак). Ово је корисно у преформатираном тексту (спискови кода).</para>

      <tip>
        <para>Приликом документовања кода, опишите два аспекта: <itemizedlist>
             <listitem>
               <para>Шта је то: Назив класе или функције понекад може бити обмањујући за људе који долазе из другачијег окружења.</para>
             </listitem>
             <listitem>
               <para>Шта ради: Реците нешто о уобичајеним употребама. Ставите га у однос са другим АПИ-јем.</para>
             </listitem>
           </itemizedlist></para>
      </tip>

      <para>Једна предност хипертекста над обичним текстом је могућност поседовања веза у документу. Писање исправног означавања за везу може бити заморно. Гтк-Док прискаче у помоћ пружајући неколико корисних скраћеница. <itemizedlist>
          <listitem>
            <para>Користите function() за упућивање на функције или макрое који примају аргументе.</para>
          </listitem>
          <listitem>
            <para>Користите @param за упућивање на параметре. Такође користите ово када упућујете на параметре других функција, који су повезани са оном која се описује.</para>
          </listitem>
          <listitem>
            <para>Користите %constant за упућивање на константу, нпр. %G_TRAVERSE_LEAFS.</para>
          </listitem>
          <listitem>
            <para>Користите #symbol за упућивање на друге врсте симбола, нпр. структуре и набрајања и макрое који не примају аргументе.</para>
          </listitem>
          <listitem>
            <para>Користите #Object::signal за упућивање на Г-објектни сигнал.</para>
          </listitem>
          <listitem>
            <para>Користите #Object:property за упућивање на Г-објектно својство.</para>
          </listitem>
          <listitem>
            <para>Користите #Struct.field за упућивање на поље унутар структуре и #GObjectClass.foo_bar() за упућивање на виртуелну методу.</para>
          </listitem>
        </itemizedlist></para>

      <tip>
        <para>Ако треба да користите посебне знакове „&lt;“, „&gt;“, „()“, „@“, „%“ или „#“ у вашој документацији а да их Гтк-Док не промени, можете користити ИксМЛ ентитете „&amp;lt;“, „&amp;gt;“, „&amp;lpar;“, „&amp;rpar;“, „&amp;commat;“, „&amp;percnt;“ и „&amp;num;“ респективно или их заштитити контра косом цртом „\“.</para>
      </tip>

      <para>ДокБук може учинити више од самих веза. Такође се могу имати спискови, примери, заглавља и слике. Од верзије 1.20, пожељан начин је коришћење подскупа основне синтаксе форматирања текста званог <ulink url="http://daringfireball.net/projects/markdown/">Маркдаун</ulink>. На старијим верзијама Гтк-Дока свака документација која укључује Маркдаун биће исцртана онако како јесте. На пример, ставке списка ће се појавити као редови који почињу цртицом.</para>

      <para>Иако се маркдаун сада преферира, могу се мешати оба. Једно ограничење овде је да се може користити докбук иксмл унутар маркдауна, али маркдаун унутар докбук иксмла није подржан.</para>

      <para>У старијим издањима Гтк-Дока, ако вам је потребна подршка за додатно форматирање, морали бисте да омогућите коришћење докбук ИксМЛ ознака унутар док-коментара постављањем <option>--xml-mode</option> (или <option>--sgml-mode</option>) у променљиву <symbol>MKDB_OPTIONS</symbol> унутар <filename>Makefile.am</filename>.</para>

      <para>
        <example><title>Гтк-Док блок коментара који користи Маркдаун</title>
          <programlisting>
/**
 * identifier:
 *
 * documentation paragraph ...
 *
 * # Sub Heading #
 *
 * ## Second Sub Heading
 *
 * # Sub Heading With a Link Anchor # {#heading-two}
 *
 * more documentation:
 *
 * - list item 1
 *
 *   Paragraph inside a list item.
 *
 * - list item 2
 *
 * 1. numbered list item
 *
 * 2. another numbered list item
 *
 * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)
 *
 * ![an inline image](plot-result.png)
 *
 * [A link to the heading anchor above][heading-two]
 *
 * A C-language example:
 * |[&lt;!-- language="C" --&gt;
 * GtkWidget *label = gtk_label_new ("Gorgeous!");
 * ]|
 */
</programlisting>
        </example>
      </para>

      <para>Више примера о томе које су маркдаун ознаке подржане можете пронаћи у <ulink url="https://wiki.gnome.org/Projects/GTK/DocumentationSyntax/Markdown">Референцама синтаксе Маркдауна за ГТК документацију</ulink>.</para>

      <tip>
        <para>Као што је већ раније поменуто, Гтк-Док је за документовање јавног АПИ-ја. Стога се не може писати документација за статичке симболе. Ипак, добро је коментарисати и те симболе. Ово помаже другим програмерима да разумеју ваш код. Због тога препоручујемо да их коментаришете користећи обичне коментаре (без друге звездице „*“ у првом реду). Ако касније функција треба да постане јавна, све што треба да урадите је да додате још једну звездицу „*“ у блок коментара и уметнете име симбола на право место унутар датотеке одељака.</para>
      </tip>
    </sect1>

    <sect1 id="documenting_sections">
      <title>Документовање одељака</title>

      <para>Сваки одељак документације садржи информације о једној класи или модулу. За увођење компоненте може се написати блок одељка. Кратак опис се такође користи унутар садржаја. Сва @поља су опционална.</para>

      <para>
        <example><title>Блок коментара одељка</title>
          <programlisting>
/**
 * SECTION:meepapp
 * @short_description: the application class
 * @title: Meep application
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * The application class handles ...
 */
</programlisting>
        </example>
      </para>

      <variablelist>
        <varlistentry>
          <term>SECTION:&lt;назив&gt;</term>
          <listitem>
            <para>Назив повезује документацију одељка са одговарајућим делом у датотеци <filename>&lt;package&gt;-sections.txt</filename>. Овде дати назив треба да се поклапа са ознаком &lt;FILE&gt; у датотеци <filename>&lt;package&gt;-sections.txt</filename>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@кратак_опис</term>
          <listitem>
            <para>Опис одељка у једном реду, који ће се касније појавити након веза у садржају и на врху странице одељка.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@наслов</term>
          <listitem>
            <para>Наслов одељка је подразумевано &lt;назив&gt; из декларације SECTION. Може се преписати пољем @title.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@ид_одељка</term>
          <listitem>
            <para>Преписује употребу наслова као идентификатора одељка. За Г-објекте (GObjects) се &lt;title&gt; користи као ид_одељка (section_id), а за остале одељке то је &lt;MODULE&gt;-&lt;title&gt;.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@види_такође</term>
          <listitem>
            <para>Списак симбола који су повезани са овим одељком.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@стабилност</term>
          <listitem>
            <para>Неформални опис нивоа стабилности који овај АПИ има. Препоручујемо употребу једног од ових термина: <itemizedlist>
                <listitem>
                  <para>Стабилно — Намера стабилног прочеља је да омогући произвољним трећим странама да развијају програме за ова прочеља, да их објављују и да буду сигурни да ће радити на свим мањим издањима производа (након оног у којем је прочеље уведено, и унутар истог главног издања). Чак и код главног издања, очекује се да ће некомпатибилне измене бити ретке и да ће имати јака оправдања.</para>
                </listitem>
                <listitem>
                  <para>Нестабилно — Нестабилна прочеља су експериментална или прелазна. Обично се користе да би се спољним програмерима омогућио рани приступ новој технологији или технологији која се брзо мења, или да би се пружило привремено решење за проблем за који се предвиђа општије решење. Не дају се никакве тврдње о изворној или бинарној компатибилности између два мања издања.</para>
                </listitem>
                <listitem>
                  <para>Приватно — Прочеље које се може користити унутар самог Гномовог стека, али које није документовано за крајње кориснике. Такве функције треба користити само на наведене и документоване начине.</para>
                </listitem>
                <listitem>
                  <para>Унутрашње — Прочеље које је унутрашње за модул и не захтева документацију за крајње кориснике. За функције које нису документоване претпоставља се да су унутрашње.</para>
                </listitem>
              </itemizedlist></para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@укључи</term>
          <listitem>
            <para>Датотеке <literal>#include</literal> које се приказују у сижеу одељка (списак раздвојен зарезима), што преписује општу вредност из <link linkend="metafiles_sections">датотеке одељка</link> или линије наредби. Ова ставка је опциона.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@слика</term>
          <listitem>
            <para>Слика која се приказује на врху референтне странице за овај одељак. Ово ће често бити нека врста дијаграма који илуструје визуелни изглед класе или дијаграм њеног односа са другим класама. Ова ставка је опциона.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <tip>
        <para>Да бисте избегли непотребно поновно превођење након измена у документацији, ставите документацију одељака у Ц изворни код где год је то могуће.</para>
      </tip>

    </sect1>

    <sect1 id="documenting_symbols">
      <title>Документовање симбола</title>

      <para>Сваки симбол (функција, макро, структура, набрајање, сигнал и својство) је документован у засебном блоку. Блок је најбоље поставити близу дефиниције симбола како би се лако одржавали усклађеним. Тако се функције обично документују у Ц изворном коду, а макрои, структуре и набрајања у датотеци заглавља.</para>

      <sect2><title>Опште ознаке</title>

        <para>Можете додати податке о верзионисању свим елементима документације како бисте назначили када је АПИ уведен или када је постао застарео.</para>

        <variablelist><title>Ознаке верзионисања</title>
          <varlistentry><term>Од:</term>
            <listitem>
              <para>Опис од ког издања кода је АПИ доступан.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Застарело:</term>
            <listitem>
              <para>Пасус који означава да ову функцију више не би требало користити. Опис би требало да упути читаоца на нови АПИ.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>Такође можете додати податке о стабилности свим елементима документације како бисте назначили да ли је стабилност АПИ-ја загарантована за њих за сва будућа мања издања пројекта.</para>

        <para>Подразумевани ниво стабилности за све елементе документације може се поставити прослеђивањем аргумента <option>--default-stability</option> програму <application>gtkdoc-mkdb</application> са једном од вредности испод.</para>

        <variablelist><title>Ознаке стабилности</title>
          <varlistentry><term>Стабилност: Стабилно</term>
            <listitem>
              <para>Означите елемент као стабилан. Ово је за јавне АПИ-је за које је загарантовано да ће остати стабилни за сва будућа мања издања пројекта.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Стабилност: Нестабилно</term>
            <listitem>
              <para>Означите елемент као нестабилан. Ово је за јавне АПИ-је који су објављени као преглед пре него што буду стабилизовани.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Стабилност: Приватно</term>
            <listitem>
              <para>Означите елемент као приватан. Ово је за прочеља која могу користити тесно повезани модули, али не и произвољна трећа лица.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <example><title>Опште ознаке</title>
          <programlisting>
/**
 * foo_get_bar:
 * @foo: неки foo
 *
 * Добавља @foo-ов bar.
 *
 * Враћа: @foo-ов bar
 *
 * Од: 2.6
 * Застарело: 2.12: Користите foo_baz_get_bar() уместо овога.
 */
Bar *
foo_get_bar(Foo *foo)
{
...
</programlisting>
        </example>
      </sect2>

      <sect2><title>Забелешке</title>

        <para>Блокови документације могу да садрже ознаке забелешки. Ове ознаке ће бити исцртане са облачићима који описују њихово значење. Ознаке користи Гобјект испитивање (GObject Introspection) за стварање везивања за језике. Детаљан списак подржаних ознака можете пронаћи у <ulink url="https://gi.readthedocs.io/en/latest/annotations/giannotations.html" type="http">документацији Гобјект испитивања</ulink>.</para>

        <example><title>Забелешке</title>
          <programlisting>
/**
 * foo_get_bar: (annotation)
 * @foo: (annotation): some foo
 *
 * Retrieves @foo's bar.
 *
 * Returns: (annotation): @foo's bar
 */
...
/**
 * foo_set_bar_using_the_frobnicator: (annotation) (another annotation)
 *                                    (and another annotation)
 * @foo: (annotation) (another annotation): some foo
 *
 * Sets bar on @foo.
 */
</programlisting>
        </example>
      </sect2>

      <sect2><title>Блок коментара функције</title>

        <para>Запамтите да: <itemizedlist>
            <listitem>
              <para>Документујте да ли враћени објекти, спискови, ниске, итд, треба да буду ослобођени/отпуштени.</para>
            </listitem>
            <listitem>
              <para>Документујте да ли параметри могу бити NULL, и шта се дешава ако јесу.</para>
            </listitem>
            <listitem>
              <para>Спомените занимљиве предуслове и постуслове где је то прикладно.</para>
            </listitem>
          </itemizedlist></para>

        <para>Гтк-док претпоставља да су сви симболи (макрои, функције) који почињу са „_“ приватни. Они се третирају као статичке функције.</para>

        <example><title>Блок коментара функције</title>
          <programlisting>
/**
 * function_name:
 * @par1:  description of parameter 1. These can extend over more than
 * one line.
 * @par2:  description of parameter 2
 * @...: a %NULL-terminated list of bars
 *
 * The function description goes here. You can use @par1 to refer to parameters
 * so that they are highlighted in the output. You can also use %constant
 * for constants, function_name2() for functions and #GtkWidget for links to
 * other declarations (which may be documented elsewhere).
 *
 * Returns: an integer.
 *
 * Since: 2.2
 * Deprecated: 2.18: Use other_function() instead.
 */
</programlisting>
        </example>

        <variablelist><title>Ознаке функције</title>
          <varlistentry><term>Враћа:</term>
            <listitem>
              <para>Пасус који описује враћени резултат.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>@...:</term>
            <listitem>
              <para>У случају да функција има варијабилне аргументе, треба да користите ову ознаку (@Varargs: такође ради из историјских разлога).</para>
            </listitem>
          </varlistentry>
        </variablelist>

      </sect2>

      <sect2><title>Блок коментара својства</title>

        <example><title>Блок коментара својства</title>
          <programlisting>
/**
 * SomeWidget:some-property:
 *
 * Here you can document a property.
 */
g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
</programlisting>
        </example>

      </sect2>

      <sect2><title>Блок коментара сигнала</title>

        <para>Запамтите да: <itemizedlist>
            <listitem>
              <para>Документујте када се сигнал емитује и да ли се емитује пре или после других сигнала.</para>
            </listitem>
            <listitem>
              <para>Документујте шта би апликација могла да уради у руковаоцу сигналом.</para>
            </listitem>
          </itemizedlist></para>

        <example><title>Блок коментара сигнала</title>
          <programlisting>
/**
 * FooWidget::foobarized:
 * @widget: the widget that received the signal
 * @foo: some foo
 * @bar: some bar
 *
 * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
 */
foo_signals[FOOBARIZED] =
  g_signal_new ("foobarized",
                ...
</programlisting>
        </example>

      </sect2>

      <sect2><title>Блок примедбе структуре</title>
        <example><title>Блок примедбе структуре</title>
          <programlisting>
/**
 * FooWidget:
 * @bar: неки #gboolean
 *
 * Ово је најбољи елемент, икада.
 */
typedef struct _FooWidget {
  GtkWidget parent_instance;

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

        <para>Користите <code>/*&lt; private &gt;*/</code> пре приватних поља структуре која желите да сакријете. Користите <code>/*&lt; public &gt;*/</code> за обрнуто понашање.</para>

        <para>Ако је прво поље „g_iface“, „parent_instance“ или „parent_class“, оно ће се сматрати приватним аутоматски и не мора се наводити у блоку примедбе.</para>

        <para>Блокови примедби структуре се такође могу користити за Г-објекте и Г-класе објеката. Обично је добра идеја додати блок примедбе за класу, ако има в-методе (јер се тако могу документовати). За сам Г-објекат може се користити документација повезаног одељка, а посебан блок за саму инстанцу структуре би био користан ако инстанца има јавна поља. Једна мана овде је што ово ствара два уноса индекса истог назива (структура и одељак).</para>

      </sect2>

      <sect2><title>Блок примедбе набрајања</title>
        <example><title>Блок примедбе набрајања</title>
          <programlisting>
/**
 * Something:
 * @SOMETHING_FOO: нешто foo
 * @SOMETHING_BAR: нешто bar
 *
 * Вредности набрајања које се користе за ствар, да би се навела ствар.
 */
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*&lt; private &gt;*/
  SOMETHING_COUNT
} Something;
</programlisting>
        </example>

        <para>Користите <code>/*&lt; private &gt;*/</code> пре приватних вредности набрајања које желите да сакријете. Користите <code>/*&lt; public &gt;*/</code> за обрнуто понашање.</para>

      </sect2>
    </sect1>


    <sect1 id="documenting_inline_program">
      <title>Унутрашња документација програма</title>
      <para>Можете документовати програме и њихово прочеље линије наредби користећи унутрашњу документацију.</para>

      <variablelist>
      <title>Ознаке</title>

      <varlistentry><term>ПРОГРАМ</term>

      <listitem>
      <para>Дефинише почетак документације програма.</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@short_description:</term>
      <listitem>
      <para>Дефинише кратак опис програма. (Опционо)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@synopsis:</term>
      <listitem>
      <para>Дефинише аргументе, или списак аргумената које програм може да прими. (Опционо)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@see_also:</term>
      <listitem>
      <para>Одељак „Такође погледајте“ страница упутства. (Опционо)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@arg:</term>
      <listitem>
      <para>Аргумент(и) прослеђени програму и њихов опис. (Опционо)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>Опис:</term>
      <listitem>
      <para>Дужи опис програма.</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>Враћа:</term>
      <listitem>
      <para>Наведите вредност(и) коју програм враћа. (Опционо)</para>
      </listitem>
      </varlistentry>

      </variablelist>

      <sect2>
        <title>Пример документације програма.</title>
        <example><title>Блок документације програма</title>
        <programlisting>
/**
 * PROGRAM:test-program
 * @short_description: Тест програм
 * @synopsis: test-program [*ОПЦИЈЕ*...] --arg1 *арг* *ДАТОТЕКА*
 * @see_also: test(1)
 * @--arg1 *арг*: постави арг1 на *арг*
 * @--arg2 *арг*: постави арг2 на *арг*
 * @-v, --version: Штампај број издања
 * @-h, --help: Штампај поруку помоћи
 *
 * Дуги опис програма.
 *
 * Returns: Нула у случају успеха, не-нула у случају неуспеха
 */
int main(int argc, char *argv[])
{
	return 0;
}
</programlisting>
        </example>

      </sect2>
    </sect1>

    <sect1 id="documenting_docbook">
      <title>Корисне ДокБук ознаке</title>

      <para>Ево неких ДокБук ознака које су најкорисније приликом документовања кода.</para>

      <para>За повезивање са другим одељком у ГТК документацији: <informalexample>
          <programlisting>
&lt;link linkend="glib-Hash-Tables"&gt;Хеш табеле&lt;/link&gt;
</programlisting>
        </informalexample> „linkend“ је СГМЛ/ИксМЛ ид на горњој ставци странице са којом желите да се повежете. За већину страница ово је тренутно део („gtk“, „gdk“, „glib“), а затим наслов странице („Хеш табеле“). За елементе то је само назив класе. Размаци и доње црте се претварају у „-“ да би били у складу са СГМЛ/ИксМЛ-ом.</para>

      <para>За упућивање на спољну функцију, нпр. стандардну Ц функцију: <informalexample>
          <programlisting>
&lt;function&gt;...&lt;/function&gt;
</programlisting>
        </informalexample></para>

      <para>За укључивање примера кода: <informalexample>
          <programlisting>
&lt;example&gt;
  &lt;title&gt;Коришћење ГХешТабеле.&lt;/title&gt;
  &lt;programlisting language="C"&gt;
      ...
  &lt;/programlisting&gt;
&lt;/example&gt;
</programlisting>
        </informalexample> или можда ово, за веома кратке делове кода којима није потребан наслов: <informalexample>
          <programlisting>
&lt;informalexample&gt;
  &lt;programlisting language="C"&gt;
  ...
  &lt;/programlisting&gt;
&lt;/informalexample&gt;
</programlisting>
        </informalexample> У оба случаја, атрибут језика је опционо и користи се као савет покретачу за истицање синтаксе (pygments за хтмл излаз). За ово друго ГТК-Док такође подржава скраћеницу: <informalexample>
          <programlisting>
|[&lt;!-- language="C" --&gt;
  ...
]|
</programlisting>
        </informalexample></para>

      <para>За укључивање спискова са набрајањем: <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>За укључивање напомене која се издваја из текста: <informalexample>
          <programlisting>
&lt;note&gt;
  &lt;para&gt;
    Обавезно ослободите податке након употребе.
  &lt;/para&gt;
&lt;/note&gt;
</programlisting>
        </informalexample></para>

      <para>За упућивање на врсту: <informalexample>
          <programlisting>
&lt;type&gt;unsigned char&lt;/type&gt;
</programlisting>
        </informalexample></para>

      <para>За упућивање на спољну структуру (не ону описану у ГТК документацији): <informalexample>
          <programlisting>
&lt;structname&gt;XFontStruct&lt;/structname&gt;
</programlisting>
        </informalexample></para>

      <para>За упућивање на поље структуре: <informalexample>
          <programlisting>
&lt;structfield&gt;len&lt;/structfield&gt;
</programlisting>
        </informalexample></para>

      <para>За упућивање на назив класе, могли бисмо евентуално користити: <informalexample>
          <programlisting>
&lt;classname&gt;GtkWidget&lt;/classname&gt;
</programlisting>
        </informalexample> али ћете вероватно користити #GtkWidget уместо тога (за аутоматско прављење везе ка GtkWidget страници — погледајте <link linkend="documenting_syntax">скраћенице</link>).</para>

      <para>За истицање текста: <informalexample>
          <programlisting>
&lt;emphasis&gt;Ово је важно&lt;/emphasis&gt;
</programlisting>
        </informalexample></para>

      <para>За називе датотека користите: <informalexample>
          <programlisting>
&lt;filename&gt;/home/user/documents&lt;/filename&gt;
</programlisting>
        </informalexample></para>

      <para>За упућивање на тастере користите: <informalexample>
          <programlisting>
&lt;keycombo&gt;&lt;keycap&gt;Control&lt;/keycap&gt;&lt;keycap&gt;L&lt;/keycap&gt;&lt;/keycombo&gt;
</programlisting>
        </informalexample></para>

    </sect1>
  </chapter>

  <chapter id="metafiles">
    <title>Попуњавање додатних датотека</title>

    <para>Постоји неколико додатних датотека које треба одржавати заједно са напоменама у изворном коду: <filename>&lt;package&gt;.types</filename>, <filename>&lt;package&gt;-docs.xml</filename> (раније .sgml), <filename>&lt;package&gt;-sections.txt</filename>.</para>

    <sect1 id="metafiles_types">
      <title>Уређивање датотеке врста</title>

      <para>Ако ваша библиотека или програм укључује GObjects, желите да њихови сигнали, аргументи/параметри и положај у хијерархији буду приказани у документацији. Све што треба да урадите јесте да наведете <function>xxx_get_type</function> функције заједно са њиховим укључивањем унутар <filename>&lt;package&gt;.types</filename> датотеке.</para>

      <para>
        <example><title>Пример &lt;package&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>Од ГТК-Дока 1.8 <application>gtkdoc-scan</application> може направити овај списак за вас. Само додајте „--rebuild-types“ у SCAN_OPTIONS у <filename>Makefile.am</filename>. Ако користите овај приступ, не би требало да дистрибуирате датотеку врста нити да је држите под управљањем верзијама.</para>

    </sect1>

    <sect1 id="metafiles_master">
      <title>Уређивање главног документа</title>

      <para>GTK-Doc производи документацију у DocBook SGML/XML формату. Приликом обраде унутрашњих коментара изворног кода, GTK-Doc алати генеришу једну страницу документације по класи или модулу као засебну датотеку. Главни документ их укључује и поставља у одређени редослед.</para>

      <para>Иако GTK-Doc прави шаблон главног документа за вас, каснија покретања га неће поново мењати. То значи да можете слободно структурирати документацију. То укључује груписање страница и додавање додатних страница. GTK-Doc сада има пакет за тестирање, где се такође главни документ поново прави из почетка. Добра је идеја с времена на време погледати ово како бисте видели да ли су тамо уведене неке нове корисне ствари.</para>

      <tip>
        <para>Не правите водиче као посебне документе. Само пишите додатна поглавља. Предност директног уграђивања водича за вашу библиотеку у API документацију је та што је лако повезати водич са документацијом симбола. Осим тога, веће су шансе да ће водич бити ажуриран заједно са библиотеком.</para>
      </tip>

      <para>Дакле, шта су ствари које треба променити унутар главног документа? За почетак, то је само мало. Тамо постоје неки чувари места (текст у квадратним заградама) о којима треба да се побринете.</para>

      <para>
        <example><title>Заглавље главног документа</title>
          <programlisting>
&lt;bookinfo&gt;
  &lt;title&gt;Референтни приручник за MODULENAME&lt;/title&gt;
  &lt;releaseinfo&gt;
    за MODULENAME [VERSION]
    Најновије издање ове документације можете наћи на мрежи на
    &lt;ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html"&gt;http://[SERVER]/MODULENAME/&lt;/ulink&gt;.
  &lt;/releaseinfo&gt;
&lt;/bookinfo&gt;

&lt;chapter&gt;
  &lt;title&gt;[Овде уметните наслов]&lt;/title&gt;
</programlisting>
        </example>
      </para>

      <para>Поред тога, неколико елемената опција је направљено у облику коментара. Можете их прегледати и омогућити их како желите.</para>

      <para>
        <example><title>Опциони део у главном документу</title>
          <programlisting>
  &lt;!-- омогућите ово када користите забелешке Гобјектног испитивања
  &lt;xi:include href="xml/annotation-glossary.xml"&gt;&lt;xi:fallback /&gt;&lt;/xi:include&gt;
  --&gt;
</programlisting>
        </example>
      </para>

      <para>На крају, потребно је да додате нови одељак кад год га уведете. Алат <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> ће вас подсетити на новогенерисане xml датотеке које још нису укључене у документацију.</para>

      <para>
        <example><title>Укључивање генерисаних одељака</title>
          <programlisting>
  &lt;chapter&gt;
    &lt;title&gt;my library&lt;/title&gt;
      &lt;xi:include href="xml/object.xml"/&gt;
      ...
</programlisting>
        </example>
      </para>

    </sect1>

    <sect1 id="metafiles_sections">
      <title>Уређивање датотеке одељака</title>

      <para>Датотека одељака се користи за организовање излаза документације коју генерише GTK-Doc. Овде се наводи који симбол припада ком модулу или класи и контролише се видљивост (јавна или приватна).</para>

      <para>Датотека одељака је обична текстуална датотека са ознакама које разграничавају одељке. Празни редови се занемарују, а редови који почињу са „#“ се третирају као коментари.</para>

      <note>
        <para>Иако ознаке чине да датотека изгледа као xml, она то није. Молимо вас да не затварате ознаке као што је &lt;SUBSECTION&gt;.</para>
      </note>

      <para>
        <example><title>Укључивање генерисаних одељака</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>Ознака &lt;FILE&gt; ... &lt;/FILE&gt; се користи за навођење назива датотеке, без икаквог суфикса. На пример, коришћење „&lt;FILE&gt;gnome-config&lt;/FILE&gt;“ ће довести до тога да декларације одељака буду исписане у датотеци шаблона <filename>tmpl/gnome-config.sgml</filename>, која ће бити претворена у DocBook XML датотеку <filename>xml/gnome-config.sgml</filename> или DocBook XML датотеку <filename>xml/gnome-config.xml</filename>. (Назив HTML датотеке се заснива на називу модула и наслову одељка, или за GObjects се заснива на називу класе GObjects претвореном у мала слова).</para>

      <para>Ознака &lt;TITLE&gt; ... &lt;/TITLE&gt; се користи за навођење наслова одељка. Корисна је само пре него што се шаблони (ако се користе) иницијално направе, пошто наслов постављен у датотеци шаблона преписује овај. Такође, ако се користи коментар SECTION у изворима, ово је застарело.</para>

      <para>Можете груписати ставке у одељку коришћењем ознаке &lt;SUBSECTION&gt;. Тренутно она исписује празну линију између пододељака у одељку сижеа. Такође можете користити &lt;SUBSECTION Standard&gt; за стандардне GObject декларације (нпр. функције као што је g_object_get_type и макрое као што су G_OBJECT(), G_IS_OBJECT() итд.). Тренутно су оне изостављене из документације. Такође можете користити &lt;SUBSECTION Private&gt; за приватне декларације које неће бити исписане (то је згодан начин да избегнете поруке упозорења о некоришћеним декларацијама). Ако ваша библиотека садржи приватне типове за које не желите да се појаве у хијерархији објеката и списку примењених или потребних прочеља, додајте их у пододељак Private. Да ли ћете поставити GObject и GObjectClass налик структурама у јавни или Standard одељак зависи од тога да ли имају јавне уносе (променљиве, виртуелне методе).</para>

      <para>Такође можете користити &lt;INCLUDE&gt; ... &lt;/INCLUDE&gt; да наведете #include датотеке које су приказане у одељцима сижеа. Садржи списак #include датотека раздвојених зарезом, без угаоних заграда. Ако га поставите изван било ког одељка, он дејствује на све одељке до краја датотеке. Ако га поставите унутар одељка, примењује се само на тај одељак.</para>

    </sect1>

  </chapter>

  <chapter id="reports">
    <title>Управљање резултатом</title>

    <para>Покретање ГТК-дока ствара датотеке извештаја унутар директоријума документације. Створене датотеке се зову: <filename>&lt;package&gt;-undocumented.txt</filename>, <filename>&lt;package&gt;-undeclared.txt</filename> и <filename>&lt;package&gt;-unused.txt</filename>. Све су то обичне текстуалне датотеке које се могу лако прегледати и накнадно обрадити.</para>

    <para>Датотека <filename>&lt;package&gt;-undocumented.txt</filename> почиње са сажетком покривености документације. Испод су два одељка раздвојена празним линијама. Први одељак набраја недокументоване или непотпуне симболе. Други одељак чини исто за документацију одељака. Непотпуни уноси су они који имају документацију, али где је нпр. додат нови параметар.</para>

    <para>Датотека <filename>&lt;package&gt;-undeclared.txt</filename> набраја симболе наведене у <filename>&lt;package&gt;-sections.txt</filename> али који нису пронађени у изворима. Проверите да ли су уклоњени или им је назив погрешно написан.</para>

    <para>Датотека <filename>&lt;package&gt;-unused.txt</filename> набраја називе симбола за које је прегледач ГТК-дока пронашао документацију, али не зна где да је постави. То значи да симбол још увек није додат у датотеку <filename>&lt;package&gt;-sections.txt</filename>.</para>

    <tip>
      <para>Омогућите или додајте линију <option>TESTS=$(GTKDOC_CHECK)</option> у Makefile.am. Ако је инсталиран барем ГТК-док 1.9, ово ће покренути провере исправности током покретања <command>make check</command>.</para>
    </tip>

    <para>Може се погледати и у датотеке које је створио прегледач изворног кода: <filename>&lt;package&gt;-decl-list.txt</filename> и <filename>&lt;package&gt;-decl.txt</filename>. Прва се може упоредити са датотеком одељака ако се она ручно одржава. Друга набраја све декларације из заглавља. Ако симбол недостаје, може се проверити да ли га ова датотека садржи.</para>

    <para>Ако је пројекат заснован на Гобјекту, може се погледати и у датотеке које је створио прегледач објеката: <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> и <filename>&lt;package&gt;.signals.txt</filename>. Ако у било којој од њих недостају симболи, можете затражити од ГТК-дока да задржи међу-датотеку прегледача за даљу анализу, тако што ћете га покренути као <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.</para>
  </chapter>

  <chapter id="modernizing">
    <title>Осавремењивање документације</title>

    <para>ГТК-док постоји већ неко време. У овом одељку набрајамо нове могућности заједно са издањем од ког су доступне.</para>

    <sect1 id="modernizing-gtk-doc-1-9">
      <title>ГТК-док 1.9</title>

      <para>Када се користи иксМЛ уместо СГМЛ-а, главни документ се заправо може именовати <filename>&lt;package&gt;-docs.xml</filename>.</para>

      <para>Ово издање подржава <option>SCAN_OPTIONS=--rebuild-sections</option> у <filename>Makefile.am</filename>. Када је ово омогућено, <filename>&lt;package&gt;-sections.txt</filename> се самостално ствара и може се уклонити из система за управљање верзијама. Ово лепо ради само за пројекте који имају врло правилну структуру (нпр. сваки пар .{c,h} ће створити нови одељак). Ако се пројекат организује приближно томе, освежавање ручно одржаване датотеке одељака може бити једноставно као покретање <code>meld &lt;package&gt;-decl-list.txt &lt;package&gt;-sections.txt</code>.</para>

      <para>Издање 1.8 је већ увело синтаксу за документовање одељака у изворима уместо у засебним датотекама под <filename class="directory">tmpl</filename>. Ово издање додаје опције за пребацивање целог модула документације тако да уопште не користи додатни корак изградње „tmpl“, коришћењем <option>--flavour no-tmpl</option> у <filename>configure.ac</filename>. Ако немате <filename class="directory">tmpl</filename> унешен у ваш систем за управљање верзијама и још нисте пребацили, само додајте заставицу у <filename>configure.ac</filename> и готови сте.</para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-10">
      <title>ГТК-док 1.10</title>

      <para>Ово издање подржава <option>SCAN_OPTIONS=--rebuild-types</option> у <filename>Makefile.am</filename>. Када је ово омогућено, <filename>&lt;package&gt;.types</filename> се самостално ствара и може се уклонити из система за управљање верзијама. Када користите ову могућност, важно је такође подесити <varname>IGNORE_HFILES</varname> у <filename>Makefile.am</filename> за код који се гради условно.</para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-16">
      <title>ГТК-док 1.16</title>

      <para>Ово издање укључује нови алат под називом gtkdoc-check. Овај алат може да покрене скуп провера исправности ваше документације. Омогућава се додавањем ових линија на крај датотеке <filename>Makefile.am</filename>. <example><title>Омогући 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>ГТК-Док 1.20</title>

      <para>Издање 1.18 је донело почетну подршку за маркдаун. Коришћење маркдауна у напоменама кода је мање нападно од писања docbook xml-а. Ово издање значајно побољшава ово и додаје много више стилова. Одељак који објашњава <link linkend="documenting_syntax">синтаксу напомена</link> садржи све детаље.</para>
    </sect1>

    <sect1 id="modernizing-gtk-doc-1-25">
      <title>ГТК-Док 1.25</title>

      <para>Датотеке управљања градњом (makefiles) испоручене уз ово издање стварају датотеку ставки у <filename>xml/gtkdocentities.ent</filename>, која садржи ставке за нпр. package_name и package_version. Ово можете користити нпр. у главној xml датотеци како бисте избегли ручно уписивање броја издања. Испод је пример који показује како се датотека ставки укључује у главни шаблон и како се ставке користе. Ставке се такође могу користити у свим створеним датотекама, ГТК-Док ће користити исто xml заглавље у створеним xml датотекама. <example><title>Коришћење унапред створених ставки</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;package_name; Reference Manual&lt;/title&gt;
    &lt;releaseinfo&gt;
      for &amp;package_string;.
      The latest version of this documentation can be found on-line at
      &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>Документовање других прочеља</title>

    <para>До сада смо користили ГТК-Док за документовање АПИ-ја кода. Следећи одељци садржи предлоге како се алати могу користити и за документовање других прочеља.</para>

    <sect1 id="commandline-interfaces">
      <title>Опције линије наредби и man странице</title>

      <para>Како се могу стварати man странице и за docbook refentry, чини се као добра идеја користити га у ту сврху. На тај начин је прочеље део референце и man страница се добија бесплатно.</para>

      <sect2 id="commandline-interfaces-file">
        <title>Документовање алата</title>

        <para>Направите једну refentry датотеку по алату. Пратећи <link linkend="settingup_docfiles">наш пример</link> назвали бисмо је <filename>meep/docs/reference/meeper/meep.xml</filename>. За xml ознаке које треба користити можете погледати створену датотеку у xml пододељку као и примере нпр. у glib-у.</para>
      </sect2>

      <sect2 id="commandline-interfaces-configure">
        <title>Додавање додатне провере подешавања</title>

        <para>
          <example><title>Додатне провере подешавања</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>Додавање додатних правила датотеке управљања градњом</title>

        <para>
          <example><title>Додатне провере подешавања</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>Д-сабирничка прочеља</title>

      <para>(ПОПРАВИМЕ: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)</para>
    </sect1>

  </chapter>

  <chapter id="faq">
    <title>Често постављана питања</title>

    <segmentedlist>
      <?dbhtml list-presentation="list"?>
      <segtitle>Питање</segtitle>
      <segtitle>Одговори</segtitle>
      <seglistitem>
        <seg>Нема хијерархије разреда.</seg>
        <seg>Функција објеката <function>xxx_get_type()</function> није унета у датотеку <filename>&lt;package&gt;.types</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>И даље нема хијерархије разреда.</seg>
        <seg>Недостајуће или погрешно именовање у датотеци <filename>&lt;package&gt;-sections.txt</filename> (погледајте <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">објашњење</ulink>).</seg>
      </seglistitem>
      <seglistitem>
        <seg>Проклетство, и даље немам хијерархију разреда.</seg>
        <seg>Да ли је име објекта (име примерка структуре, нпр. <type>GtkWidget</type>) део нормалног одељка (не стављајте ово у Стандардне или Приватне пододељке).</seg>
      </seglistitem>
      <seglistitem>
        <seg>Нема индекса симбола.</seg>
        <seg>Да ли <filename>&lt;package&gt;-docs.{xml,sgml}</filename> садржи индекс који xi:include-ује генерисани индекс?</seg>
      </seglistitem>
      <seglistitem>
        <seg>Симболи нису повезани са својим одељком документације.</seg>
        <seg>Да ли коментар документације користи исправно означавање (додато #,% или ())? Проверите да ли gtkdoc-fixxref упозорава на нерешиве унакрсне референце (xrefs).</seg>
      </seglistitem>
      <seglistitem>
        <seg>Нови разред се не појављује у документацији.</seg>
        <seg>Да ли је нова страница xi:included из <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Нови симбол се не појављује у документацији.</seg>
        <seg>Да ли је коментар документације правилно обликован. Проверите да ли има правописних грешака на почетку коментара. Проверите да ли gtkdoc-fixxref упозорава на нерешиве унакрсне референце (xrefs). Проверите да ли је симбол исправно наведен у <filename>&lt;package&gt;-sections.txt</filename> у јавном пододељку.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Врста недостаје у хијерархији разреда.</seg>
        <seg>Ако је врста наведена у <filename>&lt;package&gt;.hierarchy</filename> али не и у <filename>xml/tree_index.sgml</filename>, онда двапут проверите да ли је врста исправно постављена у <filename>&lt;package&gt;-sections.txt</filename>. Ако примерак врсте (нпр. <type>GtkWidget</type>) није наведен или је случајно означен као приватан, неће бити приказан.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Добијам foldoc везе за све gobject забелешке.</seg>
        <seg>Проверите да ли је <filename>xml/annotation-glossary.xml</filename> xi:included из <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.</seg>
      </seglistitem>

      <!-- gtk-doc warnings: -->
      <seglistitem>
        <seg>Параметар је описан у блоку коментара изворног кода али не постоји</seg>
        <seg>Проверите да ли прототип у заглављу има другачије називе параметара него у извору.</seg>
      </seglistitem>

      <!-- docbook warnings: -->
      <seglistitem>
        <seg>више „ID-ова“ за везу ограничења: XYZ</seg>
        <seg>Симбол XYZ се појављује два пута у датотеци <filename>&lt;package&gt;-sections.txt</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Елемент „typename“ у именском простору „“ је наишао у пасусу (para), али се ниједан шаблон не подудара.</seg>
        <seg/>
      </seglistitem>
    </segmentedlist>
  </chapter>

  <chapter id="contrib">
    <title>Алати повезани са gtk-doc-ом</title>

    <para>GtkDocPlugin — <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink> прикључак за интеграцију, који додаје API документацију на trac веб сајт и интегрише се са trac претрагом.</para>
    <para>Gtkdoc-depscan — алат (део gtk-doc-а) за проверу коришћеног API-ја у односу на ознаке „since“ у API-ју како би се одредило најмање потребно издање.</para>

  </chapter>

  <!-- ======== Appendix: FDL ================================== -->
  <!--  
     The GNU Free Documentation License 1.1 in DocBook
     Markup by Eric Baudais <baudais@okstate.edu>
     Maintained by the GNOME Documentation Project
     http://developer.gnome.org/projects/gdp
     Version: 1.0.1
     Last Modified: Nov 16, 2000
-->

<appendix id="fdl">
  <appendixinfo>
    <releaseinfo>Издање 1.1, март 2000.</releaseinfo>
    <copyright>
      <year>2000</year><holder>Free Software Foundation, Inc.</holder>
    </copyright>
    <legalnotice id="fdl-legalnotice">
      <para><address>Free Software Foundation, Inc. <street>51 Franklin Street, 
        Suite 330</street>, <city>Boston</city>, <state>MA</state>  
        <postcode>02110-1301</postcode>  <country>USA</country></address> Свакоме је дозвољено да умножава и расподељује дословне примерке овог документа лиценце, али његово мењање није дозвољено.</para>
    </legalnotice>
  </appendixinfo>
  <title>ГНУ-ова Лиценца за слободну документацију</title>

  <sect1 id="fdl-preamble">
    <title>0. ПРЕАМБУЛА</title>
    <para>
      The purpose of this License is to make a manual, textbook, or
      other written document <quote>free</quote> in the sense of
      freedom: to assure everyone the effective freedom to copy and
      redistribute it, with or without modifying it, either
      commercially or noncommercially. Secondarily, this License
      preserves for the author and publisher a way to get credit for
      their work, while not being considered responsible for
      modifications made by others.
    </para>
    
    <para>
      This License is a kind of <quote>copyleft</quote>, which means
      that derivative works of the document must themselves be free in
      the same sense. It complements the GNU General Public License,
      which is a copyleft license designed for free software.
    </para>
    
    <para>Ову лиценцу смо осмислили како бисмо је користили за упутства за слободан софтвер, јер је слободном софтверу потребна слободна документација: слободан програм треба да иде уз упутства која пружају исте слободе као и сам софтвер. Али ова лиценца није ограничена на упутства за софтвер; може се користити за било који текстуални рад, без обзира на предметну материју или на то да ли је објављен као штампана књига. Ову лиценцу препоручујемо првенствено за радове чија је сврха подучавање или референца.</para>
  </sect1>
  <sect1 id="fdl-section1">
    <title>1. ПРИМЕЊИВОСТ И ДЕФИНИЦИЈЕ</title>
    <para id="fdl-document">
      This License applies to any manual or other work that contains a
      notice placed by the copyright holder saying it can be
      distributed under the terms of this License. The
      <quote>Document</quote>, below, refers to any such manual or
      work. Any member of the public is a licensee, and is addressed
      as <quote>you</quote>.
    </para>
    
    <para id="fdl-modified">
      A <quote>Modified Version</quote> of the Document means any work
      containing the Document or a portion of it, either copied
      verbatim, or with modifications and/or translated into another
      language.
    </para>
	
    <para id="fdl-secondary">
      A <quote>Secondary Section</quote> is a named appendix or a
      front-matter section of the <link linkend="fdl-document">Document</link> that deals exclusively
      with the relationship of the publishers or authors of the
      Document to the Document's overall subject (or to related
      matters) and contains nothing that could fall directly within
      that overall subject. (For example, if the Document is in part a
      textbook of mathematics, a Secondary Section may not explain any
      mathematics.)  The relationship could be a matter of historical
      connection with the subject or with related matters, or of
      legal, commercial, philosophical, ethical or political position
      regarding them.
    </para>

    <para id="fdl-invariant">
      The <quote>Invariant Sections</quote> are certain <link linkend="fdl-secondary"> Secondary Sections</link> whose titles
      are designated, as being those of Invariant Sections, in the
      notice that says that the <link linkend="fdl-document">Document</link> is released under this
      License.
    </para>
    
    <para id="fdl-cover-texts">
      The <quote>Cover Texts</quote> are certain short passages of
      text that are listed, as Front-Cover Texts or Back-Cover Texts,
      in the notice that says that the <link linkend="fdl-document">Document</link> is released under this
      License.
    </para>
	
    <para id="fdl-transparent">
      A <quote>Transparent</quote> copy of the <link linkend="fdl-document"> Document</link> means a machine-readable
      copy, represented in a format whose specification is available
      to the general public, whose contents can be viewed and edited
      directly and straightforwardly with generic text editors or (for
      images composed of pixels) generic paint programs or (for
      drawings) some widely available drawing editor, and that is
      suitable for input to text formatters or for automatic
      translation to a variety of formats suitable for input to text
      formatters. A copy made in an otherwise Transparent file format
      whose markup has been designed to thwart or discourage
      subsequent modification by readers is not Transparent.  A copy
      that is not <quote>Transparent</quote> is called
      <quote>Opaque</quote>.
    </para>
    
    <para>Примери погодних формата за провидне примерке укључују обичан ASCII без означавања, Texinfo улазни формат, LaTeX улазни формат, SGML или XML који користе јавно доступан DTD, и једноставан HTML усклађен са стандардима дизајниран за људску измену. Непрозирни формати укључују PostScript, PDF, власничке формате који се могу читати и уређивати само помоћу власничких процесора текста, SGML или XML за које DTD и/или алати за обраду нису опште доступни, и машински генерисан HTML који производе неки процесори текста само за потребе излаза.</para>
    
    <para id="fdl-title-page">
      The <quote>Title Page</quote> means, for a printed book, the
      title page itself, plus such following pages as are needed to
      hold, legibly, the material this License requires to appear in
      the title page. For works in formats which do not have any title
      page as such, <quote>Title Page</quote> means the text near the
      most prominent appearance of the work's title, preceding the
      beginning of the body of the text.
    </para>
  </sect1>
    
  <sect1 id="fdl-section2">
    <title>2. ДОСЛОВНО УМНОЖАВАЊЕ</title>
    <para>
      You may copy and distribute the <link linkend="fdl-document">Document</link> in any medium, either
      commercially or noncommercially, provided that this License, the
      copyright notices, and the license notice saying this License
      applies to the Document are reproduced in all copies, and that
      you add no other conditions whatsoever to those of this
      License. You may not use technical measures to obstruct or
      control the reading or further copying of the copies you make or
      distribute. However, you may accept compensation in exchange for
      copies. If you distribute a large enough number of copies you
      must also follow the conditions in <link linkend="fdl-section3">section 3</link>.
    </para>
    
    <para>Такође можете позајмљивати примерке, под истим горе наведеним условима, и можете јавно приказивати примерке.</para>
    </sect1>
    
  <sect1 id="fdl-section3">
    <title>3. УМНОЖАВАЊЕ У ВЕЋЕМ БРОЈУ</title>
    <para>
      If you publish printed copies of the <link linkend="fdl-document">Document</link> numbering more than 100,
      and the Document's license notice requires <link linkend="fdl-cover-texts">Cover Texts</link>, you must enclose
      the copies in covers that carry, clearly and legibly, all these
      Cover Texts: Front-Cover Texts on the front cover, and
      Back-Cover Texts on the back cover. Both covers must also
      clearly and legibly identify you as the publisher of these
      copies. The front cover must present the full title with all
      words of the title equally prominent and visible. You may add
      other material on the covers in addition. Copying with changes
      limited to the covers, as long as they preserve the title of the
      <link linkend="fdl-document">Document</link> and satisfy these
      conditions, can be treated as verbatim copying in other
      respects.
    </para>
    
    <para>Ако су захтевани текстови за било који омот превише обимни да би стали читко, треба да ставите прве наведене (колико год разумно стане) на сам омот, а остатак наставите на суседним страницама.</para>
    
    <para>
      If you publish or distribute <link linkend="fdl-transparent">Opaque</link> copies of the <link linkend="fdl-document">Document</link> numbering more than 100,
      you must either include a machine-readable <link linkend="fdl-transparent">Transparent</link> copy along with
      each Opaque copy, or state in or with each Opaque copy a
      publicly-accessible computer-network location containing a
      complete Transparent copy of the Document, free of added
      material, which the general network-using public has access to
      download anonymously at no charge using public-standard network
      protocols. If you use the latter option, you must take
      reasonably prudent steps, when you begin distribution of Opaque
      copies in quantity, to ensure that this Transparent copy will
      remain thus accessible at the stated location until at least one
      year after the last time you distribute an Opaque copy (directly
      or through your agents or retailers) of that edition to the
      public.
    </para>
    
    <para>
      It is requested, but not required, that you contact the authors
      of the <link linkend="fdl-document">Document</link> well before
      redistributing any large number of copies, to give them a chance
      to provide you with an updated version of the Document.
    </para>
    </sect1>
    
  <sect1 id="fdl-section4">
    <title>4. ИЗМЕНЕ</title>
    <para>
      You may copy and distribute a <link linkend="fdl-modified">Modified Version</link> of the <link linkend="fdl-document">Document</link> under the conditions of
      sections <link linkend="fdl-section2">2</link> and <link linkend="fdl-section3">3</link> above, provided that you release
      the Modified Version under precisely this License, with the
      Modified Version filling the role of the Document, thus
      licensing distribution and modification of the Modified Version
      to whoever possesses a copy of it. In addition, you must do
      these things in the Modified Version:
    </para>
    
    <itemizedlist mark="opencircle">
      <listitem>
	<formalpara>
	  <title>А</title>
	  <para>
	    Use in the <link linkend="fdl-title-page">Title
	    Page</link> (and on the covers, if any) a title distinct
	    from that of the <link linkend="fdl-document">Document</link>, and from those of
	    previous versions (which should, if there were any, be
	    listed in the History section of the Document). You may
	    use the same title as a previous version if the original
	    publisher of that version gives permission.
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>Б</title>
	  <para>
	    List on the <link linkend="fdl-title-page">Title
	    Page</link>, as authors, one or more persons or entities
	    responsible for authorship of the modifications in the
	    <link linkend="fdl-modified">Modified Version</link>,
	    together with at least five of the principal authors of
	    the <link linkend="fdl-document">Document</link> (all of
	    its principal authors, if it has less than five).
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>C</title>
	  <para>
	    State on the <link linkend="fdl-title-page">Title
	    Page</link> the name of the publisher of the <link linkend="fdl-modified">Modified Version</link>, as the
	    publisher.
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>Н</title>
	  <para>
	    Preserve all the copyright notices of the <link linkend="fdl-document">Document</link>.
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>E</title>
	  <para>Додајте одговарајућу напомену о ауторским правима за ваше измене поред осталих напомена о ауторским правима.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>F</title>
	  <para>
	    Include, immediately after the copyright notices, a
	    license notice giving the public permission to use the
	    <link linkend="fdl-modified">Modified Version</link> under
	    the terms of this License, in the form shown in the
	    Addendum below.
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>и</title>
	  <para>
	    Preserve in that license notice the full lists of <link linkend="fdl-invariant"> Invariant Sections</link> and
	    required <link linkend="fdl-cover-texts">Cover
	    Texts</link> given in the <link linkend="fdl-document">Document's</link> license notice.
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>H</title>
	  <para>Укључите неизмењен примерак ове лиценце.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>I</title>
	  <para>
	    Preserve the section entitled <quote>History</quote>, and
	    its title, and add to it an item stating at least the
	    title, year, new authors, and publisher of the <link linkend="fdl-modified">Modified Version</link> as given on
	    the <link linkend="fdl-title-page">Title Page</link>.  If
	    there is no section entitled <quote>History</quote> in the
	    <link linkend="fdl-document">Document</link>, create one
	    stating the title, year, authors, and publisher of the
	    Document as given on its Title Page, then add an item
	    describing the Modified Version as stated in the previous
	    sentence.
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>J</title>
	  <para>
	    Preserve the network location, if any, given in the <link linkend="fdl-document">Document</link> for public access
	    to a <link linkend="fdl-transparent">Transparent</link>
	    copy of the Document, and likewise the network locations
	    given in the Document for previous versions it was based
	    on. These may be placed in the <quote>History</quote>
	    section.  You may omit a network location for a work that
	    was published at least four years before the Document
	    itself, or if the original publisher of the version it
	    refers to gives permission.
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>K</title>
	  <para>
	    In any section entitled <quote>Acknowledgements</quote> or
	    <quote>Dedications</quote>, preserve the section's title,
	    and preserve in the section all the substance and tone of
	    each of the contributor acknowledgements and/or
	    dedications given therein.
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>L</title>
	  <para>
	    Preserve all the <link linkend="fdl-invariant">Invariant
	    Sections</link> of the <link linkend="fdl-document">Document</link>, unaltered in their
	    text and in their titles.  Section numbers or the
	    equivalent are not considered part of the section titles.
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>ц</title>
	  <para>
	    Delete any section entitled
	    <quote>Endorsements</quote>. Such a section may not be
	    included in the <link linkend="fdl-modified">Modified
	    Version</link>.
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>Н</title>
	  <para>
	    Do not retitle any existing section as
	    <quote>Endorsements</quote> or to conflict in title with
	    any <link linkend="fdl-invariant">Invariant
	    Section</link>.
	  </para>
	</formalpara>
      </listitem>
    </itemizedlist>
    
    <para>
      If the <link linkend="fdl-modified">Modified Version</link>
      includes new front-matter sections or appendices that qualify as
      <link linkend="fdl-secondary">Secondary Sections</link> and
      contain no material copied from the Document, you may at your
      option designate some or all of these sections as invariant. To
      do this, add their titles to the list of <link linkend="fdl-invariant">Invariant Sections</link> in the
      Modified Version's license notice.  These titles must be
      distinct from any other section titles.
    </para>
    
    <para>
      You may add a section entitled <quote>Endorsements</quote>,
      provided it contains nothing but endorsements of your <link linkend="fdl-modified">Modified Version</link> by various
      parties--for example, statements of peer review or that the text
      has been approved by an organization as the authoritative
      definition of a standard.
    </para>
    
    <para>
      You may add a passage of up to five words as a <link linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage
      of up to 25 words as a <link linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of
      the list of <link linkend="fdl-cover-texts">Cover Texts</link>
      in the <link linkend="fdl-modified">Modified Version</link>.
      Only one passage of Front-Cover Text and one of Back-Cover Text
      may be added by (or through arrangements made by) any one
      entity. If the <link linkend="fdl-document">Document</link>
      already includes a cover text for the same cover, previously
      added by you or by arrangement made by the same entity you are
      acting on behalf of, you may not add another; but you may
      replace the old one, on explicit permission from the previous
      publisher that added the old one.
    </para>
    
    <para>
      The author(s) and publisher(s) of the <link linkend="fdl-document">Document</link> do not by this License
      give permission to use their names for publicity for or to
      assert or imply endorsement of any <link linkend="fdl-modified">Modified Version </link>.
    </para>
  </sect1>
    
  <sect1 id="fdl-section5">
    <title>5. КОМБИНОВАЊЕ ДОКУМЕНАТА</title>
    <para>
      You may combine the <link linkend="fdl-document">Document</link>
      with other documents released under this License, under the
      terms defined in <link linkend="fdl-section4">section 4</link>
      above for modified versions, provided that you include in the
      combination all of the <link linkend="fdl-invariant">Invariant
      Sections</link> of all of the original documents, unmodified,
      and list them all as Invariant Sections of your combined work in
      its license notice.
    </para>
    
    <para>
      The combined work need only contain one copy of this License,
      and multiple identical <link linkend="fdl-invariant">Invariant
      Sections</link> may be replaced with a single copy. If there are
      multiple Invariant Sections with the same name but different
      contents, make the title of each such section unique by adding
      at the end of it, in parentheses, the name of the original
      author or publisher of that section if known, or else a unique
      number. Make the same adjustment to the section titles in the
      list of Invariant Sections in the license notice of the combined
      work.
    </para>
    
    <para>
      In the combination, you must combine any sections entitled
      <quote>History</quote> in the various original documents,
      forming one section entitled <quote>History</quote>; likewise
      combine any sections entitled <quote>Acknowledgements</quote>,
      and any sections entitled <quote>Dedications</quote>.  You must
      delete all sections entitled <quote>Endorsements.</quote>
    </para>
    </sect1>
    
  <sect1 id="fdl-section6">
    <title>6. ЗБИРКЕ ДОКУМЕНАТА</title>
    <para>
      You may make a collection consisting of the <link linkend="fdl-document">Document</link> and other documents
      released under this License, and replace the individual copies
      of this License in the various documents with a single copy that
      is included in the collection, provided that you follow the
      rules of this License for verbatim copying of each of the
      documents in all other respects.
    </para>
    
    <para>Можете издвојити појединачни документ из такве збирке и дистрибуисати га појединачно под овом лиценцом, под условом да уметнете примерак ове лиценце у издвојени документ и да се у свим осталим погледима придржавате ове лиценце у вези са дословним умножавањем тог документа.</para>
    </sect1>
    
  <sect1 id="fdl-section7">
    <title>7. СПАЈАЊЕ СА НЕЗАВИСНИМ РАДОВИМА</title>
    <para>
      A compilation of the <link linkend="fdl-document">Document</link> or its derivatives with
      other separate and independent documents or works, in or on a
      volume of a storage or distribution medium, does not as a whole
      count as a <link linkend="fdl-modified">Modified Version</link>
      of the Document, provided no compilation copyright is claimed
      for the compilation.  Such a compilation is called an
      <quote>aggregate</quote>, and this License does not apply to the
      other self-contained works thus compiled with the Document , on
      account of their being thus compiled, if they are not themselves
      derivative works of the Document.  If the <link linkend="fdl-cover-texts">Cover Text</link> requirement of <link linkend="fdl-section3">section 3</link> is applicable to these
      copies of the Document, then if the Document is less than one
      quarter of the entire aggregate, the Document's Cover Texts may
      be placed on covers that surround only the Document within the
      aggregate. Otherwise they must appear on covers around the whole
      aggregate.
    </para>
    </sect1>
    
  <sect1 id="fdl-section8">
    <title>8. ПРЕВОД</title>
    <para>
      Translation is considered a kind of modification, so you may
      distribute translations of the <link linkend="fdl-document">Document</link> under the terms of <link linkend="fdl-section4">section 4</link>. Replacing <link linkend="fdl-invariant"> Invariant Sections</link> with
      translations requires special permission from their copyright
      holders, but you may include translations of some or all
      Invariant Sections in addition to the original versions of these
      Invariant Sections. You may include a translation of this
      License provided that you also include the original English
      version of this License. In case of a disagreement between the
      translation and the original English version of this License,
      the original English version will prevail.
    </para>
    </sect1>
    
  <sect1 id="fdl-section9">
    <title>9. ПРЕСТАНАК ВАЖЕЊА</title>
    <para>
      You may not copy, modify, sublicense, or distribute the <link linkend="fdl-document">Document</link> except as expressly
      provided for under this License. Any other attempt to copy,
      modify, sublicense or distribute the Document is void, and will
      automatically terminate your rights under this License. However,
      parties who have received copies, or rights, from you under this
      License will not have their licenses terminated so long as such
      parties remain in full compliance.
    </para>
    </sect1>
    
  <sect1 id="fdl-section10">
    <title>10. БУДУЋЕ РЕВИЗИЈЕ ОВЕ ЛИЦЕНЦЕ</title>
    <para>
      The <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software
      Foundation</ulink> may publish new, revised versions of the GNU
      Free Documentation License from time to time. Such new versions
      will be similar in spirit to the present version, but may differ
      in detail to address new problems or concerns. See <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.
    </para>
    
    <para>
      Each version of the License is given a distinguishing version
      number. If the <link linkend="fdl-document">Document</link>
      specifies that a particular numbered version of this License
      <quote>or any later version</quote> applies to it, you have the
      option of following the terms and conditions either of that
      specified version or of any later version that has been
      published (not as a draft) by the Free Software Foundation. If
      the Document does not specify a version number of this License,
      you may choose any version ever published (not as a draft) by
      the Free Software Foundation.
    </para>
  </sect1>

  <sect1 id="fdl-using">
    <title>Додатак</title>
    <para>Да бисте користили ову лиценцу у документу који сте написали, укључите примерак лиценце у документ и ставите следећа обавештења о ауторским правима и лиценци одмах након насловне стране:</para>
    
    <blockquote>
      <para>Ауторска права ГОДИНА ВАШЕ ИМЕ.</para>
      <para>
	Permission is granted to copy, distribute and/or modify this
	document under the terms of the GNU Free Documentation
	License, Version 1.1 or any later version published by the
	Free Software Foundation; with the <link linkend="fdl-invariant">Invariant Sections</link> being LIST
	THEIR TITLES, with the <link linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST,
	and with the <link linkend="fdl-cover-texts">Back-Cover
	Texts</link> being LIST.  A copy of the license is included in
	the section entitled <quote>GNU Free Documentation
	License</quote>.
      </para>
    </blockquote>
      
    <para>
      If you have no <link linkend="fdl-invariant">Invariant
      Sections</link>, write <quote>with no Invariant Sections</quote>
      instead of saying which ones are invariant.  If you have no
      <link linkend="fdl-cover-texts">Front-Cover Texts</link>, write
      <quote>no Front-Cover Texts</quote> instead of
      <quote>Front-Cover Texts being LIST</quote>; likewise for <link linkend="fdl-cover-texts">Back-Cover Texts</link>.
    </para>
    
    <para>
      If your document contains nontrivial examples of program code,
      we recommend releasing these examples in parallel under your
      choice of free software license, such as the <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public
      License</ulink>, to permit their use in free software.
    </para>
  </sect1>
</appendix>  








</book>
