<?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="sv">
  <bookinfo>
    <title>Handbok för GTK-Doc</title>
    <edition>1.24.1</edition>
    <abstract role="description"><para>Användarhandbok för utvecklare med användningsinstruktioner för GTK-Doc.</para></abstract>
    <authorgroup>
      <author><firstname>Chris</firstname> <surname>Lyttle</surname> <affiliation> <address> <email>chris@wilddev.net</email> </address> </affiliation></author>
      <author><firstname>Dan</firstname> <surname>Mueth</surname> <affiliation> <address> <email>d-mueth@uchicago.edu</email> </address> </affiliation></author>
      <author><firstname>Stefan</firstname> <surname>Sauer (Kost)</surname> <affiliation> <address> <email>ensonic@users.sf.net</email> </address> </affiliation></author>
    </authorgroup>
    <publisher role="maintainer"><publishername>GTK-Doc-projektet</publishername> <address><email>gtk-doc-list@gnome.org</email></address></publisher>
    <copyright><year>2000, 2005</year> <holder>Dan Mueth and Chris Lyttle</holder></copyright>
    <copyright><year>2007-2019</year> <holder>Stefan Sauer (Kost)</holder></copyright>

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

    <legalnotice>
      <para>Tillstånd att kopiera, distribuera och/eller modifiera detta dokument ges under villkoren i <citetitle>GNU Free Documentation License</citetitle>, version 1.1 eller senare, utgivet av Free Software Foundation utan standardavsnitt och omslagstexter.  En kopia av licensen finns <link linkend="fdl">inkluderad</link>.</para>
      <para>Flera namn på produkter och tjänster är registrerade varumärken. I de fall dessa namn förekommer i GNOME-dokumentation - och medlemmarna i GNOME-dokumentationsprojektet är medvetna om dessa varumärken - är de skrivna med versaler eller med inledande versal.</para>
    </legalnotice>

    <revhistory>
      <revision><revnumber>1.33.0</revnumber> <date>1 okt 2020</date> <authorinitials>mc</authorinitials> <revremark>gtk4-version</revremark></revision>
      <revision><revnumber>1.32.1</revnumber> <date>15 aug 2019</date> <authorinitials>ss</authorinitials> <revremark>utveckling</revremark></revision>
      <revision><revnumber>1.32</revnumber> <date>15 aug 2019</date> <authorinitials>ss</authorinitials> <revremark>snabb fixutgåva</revremark></revision>
      <revision><revnumber>1.31</revnumber> <date>05 aug 2019</date> <authorinitials>ss</authorinitials> <revremark>omstrukturering och större testtäckning</revremark></revision>
      <revision><revnumber>1.30</revnumber> <date>08 maj 2019</date> <authorinitials>ss</authorinitials> <revremark>större testtäckning</revremark></revision>
      <revision><revnumber>1.29</revnumber> <date>28 aug 2018</date> <authorinitials>ss</authorinitials> <revremark>programfixar</revremark></revision>
      <revision><revnumber>1.28</revnumber> <date>24 mar 2018</date> <authorinitials>ss</authorinitials> <revremark>programfixar</revremark></revision>
      <revision><revnumber>1.27</revnumber> <date>07 dec 2017</date> <authorinitials>ss</authorinitials> <revremark>finjustering av python-porteringen</revremark></revision>
      <revision><revnumber>1.26</revnumber> <date>11 aug 2017</date> <authorinitials>ss</authorinitials> <revremark>portera alla verktyg från perl/bash till python</revremark></revision>
      <revision><revnumber>1.25</revnumber> <date>21 mars 2016</date> <authorinitials>ss</authorinitials> <revremark>programfixar, uppstädning av tester</revremark></revision>
      <revision><revnumber>1.24</revnumber> <date>29 maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfix</revremark></revision>
      <revision><revnumber>1.23</revnumber> <date>17 maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfix</revremark></revision>
      <revision><revnumber>1.22</revnumber> <date>07 maj 2015</date> <authorinitials>ss</authorinitials> <revremark>programfixar, borttagning av föråldrade funktioner</revremark></revision>
      <revision><revnumber>1.21</revnumber> <date>17 jul 2014</date> <authorinitials>ss</authorinitials> <revremark>programfixar, borttagning av föråldrade funktioner</revremark></revision>
      <revision><revnumber>1.20</revnumber> <date>16 feb 2014</date> <authorinitials>ss</authorinitials> <revremark>programfixar, stöd för markdown, stilförbättringar</revremark></revision>
      <revision><revnumber>1.19</revnumber> <date>05 jun 2013</date> <authorinitials>ss</authorinitials> <revremark>programfixar</revremark></revision>
      <revision><revnumber>1.18</revnumber> <date>14 sep 2011</date> <authorinitials>ss</authorinitials> <revremark>programfixar, uppsnabbningar, stöd för markdown</revremark></revision>
      <revision><revnumber>1.17</revnumber> <date>26 feb 2011</date> <authorinitials>sk</authorinitials> <revremark>brådskande programfixuppdatering</revremark></revision>
      <revision><revnumber>1.16</revnumber> <date>14 jan 2011</date> <authorinitials>sk</authorinitials> <revremark>programfixar, layoutförbättringar</revremark></revision>
      <revision><revnumber>1.15</revnumber> <date>21 maj 2010</date> <authorinitials>sk</authorinitials> <revremark>program- och regressionsfixar</revremark></revision>
      <revision><revnumber>1.14</revnumber> <date>28 mars 2010</date> <authorinitials>sk</authorinitials> <revremark>programfixar och prestandaförbättringar</revremark></revision>
      <revision><revnumber>1.13</revnumber> <date>18 december 2009</date> <authorinitials>sk</authorinitials> <revremark>uppdatering på grund av trasigt tar-arkiv</revremark></revision>
      <revision><revnumber>1.12</revnumber> <date>18 december 2009</date> <authorinitials>sk</authorinitials> <revremark>nya verktygsfunktioner och programfixar</revremark></revision>
      <revision><revnumber>1.11</revnumber> <date>16 november 2008</date> <authorinitials>mal</authorinitials> <revremark>GNOME doc-utils migration</revremark></revision>
    </revhistory>

  
    <othercredit class="translator">
      <personname>
        <firstname>Sebastian Rasmussen</firstname>
      </personname>
      <email>sebras@gmail.com</email>
    </othercredit>
    <copyright>
      
        <year>2016</year>
      
      <holder>Sebastian Rasmussen</holder>
    </copyright>
  
    <othercredit class="translator">
      <personname>
        <firstname>Daniel Nylander</firstname>
      </personname>
      <email>po@danielnylander.se</email>
    </othercredit>
    <copyright>
      
        <year>2009</year>
      
      <holder>Daniel Nylander</holder>
    </copyright>
  
    <othercredit class="translator">
      <personname>
        <firstname>Marcus Rejås och Alexander Nordström</firstname>
      </personname>
      <email>info@se.linux.org</email>
    </othercredit>
    <copyright>
      
        <year>2004</year>
      
      <holder>Marcus Rejås och Alexander Nordström</holder>
    </copyright>
  </bookinfo>

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

  <chapter id="introduction">
    <title>Introduktion</title>

    <para>Detta kapitel introducerar GTK-Doc och ger en överblick över vad det är och hur det används.</para>

    <sect1 id="whatisgtkdoc">
      <title>Vad är GTK-Doc?</title>

      <para>GTK-Doc används för att dokumentera C-kod. Det används vanligen för att dokumentera det publika API:t för bibliotek, såsom GLib-baserade bibliotek, men det kan också användas för att dokumentera programkod.</para>
    </sect1>

    <sect1 id="howdoesgtkdocwork">
      <title>Hur fungerar GTK-Doc?</title>

      <para>GTK-Doc fungerar genom att läsa speciellt formaterade kommentarsblock placerade inuti källkodsfilerna för att dokumentera symboler som funktioner, makron, struturer, uppräkningar o.s.v. (notera dock att GTK-Doc endast kommer att dokumentera symboler som deklarerats i huvudfiler; det kommer inte att producera utdata för statiska funktioner).</para>

      <para>GTK-Doc läser även mallfiler där dokumentation också kan läggas till.</para>

      <para>GTK-Doc består av ett antal program som vart och ett utför olika steg i processen.</para>

      <para>Huvudstegen är:</para>

      <orderedlist>

        <listitem>
          <para><guilabel>Skriva dokumentationen.</guilabel> Författaren fyller i källkodsfilerna med dokumentation för varje funktion, makro, struct eller union, o.s.v.</para>
        </listitem>

        <listitem>
          <para><guilabel>Samla ihop information om koden.</guilabel> <application>gtkdoc-scan</application> söker genom huvudfilerna för koden och letar efter deklarationer av funktioner, makron, uppräkningar, strukturer och unioner. Det skapar sedan filen <filename>&lt;module&gt;-decl-list.txt</filename> som innehåller en lista över deklarationerna, och placerar dem i avsnitt efter vilken huvudfil de finns i. Vid första körningen kommer denna fil att kopieras till <filename>&lt;module&gt;-sections.txt</filename>. Författaren kan, genom att omarrangera avsnitten och ändra ordningen för deklarationerna inom dem, framställa den önskade, slutgiltiga ordningen. Den andra filen det genererar är <filename>&lt;module&gt;-decl.txt</filename>. Denna fil innehåller de fullständiga deklarationerna som hittats av detektorn. Om man av något skäl vill att vissa symboler ska visas i dokumentation då den fullständiga deklarationen inte kan hittas av detektorn, eller om deklarationen ska visas annorlunda, kan man placera rader liknande de som finns i <filename>&lt;module&gt;-decl.txt</filename> i <filename>&lt;module&gt;-overrides.txt</filename>.</para>
         <para><application>gtkdoc-scangobj</application> kan också användas för att dynamiskt fråga ett bibliotek om vilka GObject-underklasser det exporterar. Det sparar information om varje objekts position i klasshierarkin och om vilka GObject-egenskaper och signaler det tillhandahåller.</para>
         <para><application>gtkdoc-scanobj</application> bör inte användas längre. Det behövdes tidigare när GObject fortfarande var GtkObject inuti GTK.</para>
        </listitem>

        <listitem>
          <para><guilabel>Generera XML och HTML/PDF.</guilabel> <application>gtkdoc-mkdb</application> förvandlar mallfilerna till XML-filer i underkatalogen <filename class="directory">xml/</filename>. Om källkoden innehåller dokumentation för symboler i speciella kommentarsblock, så kommer denna att sammanfogas här. Om det inte finns några tmpl-filer som används så kommer det endast att läsa dokumentation från källkoden och introspektionsdata.</para>
          <para><application>gtkdoc-mkhtml</application> förvandlar XML-filer till HTML-filer i underkatalogen <filename class="directory">html/</filename>. På samma sätt förvandlar <application>gtkdoc-mkpdf</application> XML-filerna till ett PDF-dokument kallat <filename>&lt;package&gt;.pdf</filename>.</para>
          <para>Filer i <filename class="directory">xml/</filename>- och <filename class="directory">html/</filename>-katalogerna skrivs alltid över. Man bör aldrig redigera dem direkt.</para>
        </listitem>

        <listitem>
          <para><guilabel>Fixa korsreferenser mellan dokument.</guilabel> Efter att ha installerat HTML-filerna kan <application>gtkdoc-fixxref</application> köras för att fixa korsreferenser mellan separata dokument. Till exempel GTK-dokumentationen innehåller många korsreferenser till typer som dokumenterats i GLib-manualen.</para>
          <para>När tar-arkivet med källkod skapas för distribution, förvandlar <application>gtkdoc-rebase</application> alla externa länkar till webblänkar. När (förgenererad) distribuerad dokumentation installeras kommer samma program att försöka att förvandla länkarna tillbaka till lokala länkar (där dokumentationen finns installerad).</para>
        </listitem>
      </orderedlist>

    </sect1>

    <sect1 id="gettinggtkdoc">
      <title>Hämta GTK-Doc</title>

      <sect2 id="requirements">
        <title>Krav</title>
        <para><guilabel>python 2/3</guilabel> - huvudskripten är skrivna i python.</para>
        <para><guilabel>xsltproc</guilabel> - xslt-processorn från libxslt <ulink url="http://xmlsoft.org/XSLT/" type="http">xmlsoft.org/XSLT/</ulink></para>
        <para><guilabel>docbook-xsl</guilabel> - docbook xsl-stilmallar <ulink url="http://sourceforge.net/projects/docbook/files/docbook-xsl/" type="http">sourceforge.net/projects/docbook/files/docbook-xsl</ulink></para>
        <para>Endera av <guilabel>source-highlight</guilabel>, <guilabel>highlight</guilabel> eller <guilabel>vim</guilabel> - valfritt - används för syntaxfärgning av exempel</para>
      </sect2>
    </sect1>

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

      <para>Historiskt användes GTK-Doc för att generera mallfiler från källkoden. Dessa mallfiler kunde användas av utvecklare för att ange API-dokumentationen. Detta tillvägagångssätt var ganska obekvämt då det krävde att genererade filer hölls under versionshantering. Sedan GTK-Doc 1.9 är det möjligt att placera all API-information i källkodskommentarer, vilket gör mallstödet föråldrat. I version 1.26 har mallstödet tagits bort.</para>

      <para>(FIXME)</para>

      <para>(författare, webbsidor, sändlistor, licens, framtida planer, jämförelse med andra liknande system.)</para>

    </sect1>

    <sect1 id="aboutthismanual">
      <title>Om denna handbok</title>

      <para>(FIXME)</para>

      <para>(vem är den avsett för, var kan du få tag i den, licens)</para>

    </sect1>

  </chapter>

  <chapter id="settingup">
    <title>Projektkonfiguration</title>

    <para>Detta kapitel beskriver stegen som är nödvändiga för att integrera GTK-Doc i ditt projekt. Integreringen av GTK-Doc till ett projekt inkluderar följande steg:</para>

    <itemizedlist>
      <listitem>
        <para>Förberedelse av katalogstrukturen och skapande av konfigurationsfiler som krävs för din GTK-Doc-dokumentation (se <link linkend="settingup_docfiles"> Att ställa in en skelettstruktur för dokumentation</link>).</para>
      </listitem>
      <listitem>
        <para>Justering av byggsystemet för att bygga din dokumentation med GTK-Doc-verktygen. Flera byggsystem stöds, i denna handbok beskriver vi hur GTK-Doc kan integreras med <link linkend="settingup_autotools">Autotools</link>, <link linkend="settingup_cmake">CMake</link> och <link linkend="settingup_plain_makefiles">vanliga Makefiler</link>.</para>
      </listitem>
      <listitem>
        <para>Tillägg av GTK-Doc-specifika filer till versionshantering och att bestämma vilka filer som ska ignoreras (se <link linkend="settingup_vcs"> Integrering med versionshanteringssystem</link>).</para>
      </listitem>
    </itemizedlist>

    <para>De följande avsnitten utgår från att vi arbetar på ett projekt som kallas <code>meep</code>. Detta projekt innehåller två paket (eller moduler), ett bibliotek som kallas <code>libmeep</code> och ett program för slutanvändare som kallas <code>meeper</code>.</para>

    <sect1 id="settingup_docfiles">
      <title>Att ställa in en skelettstruktur för dokumentation</title>

      <para>En vanlig konvention är att placera dokumentation i en mapp kallad <code>docs</code> i toppnivåkatalogen för ditt projekt. Vi skiljer vanligen mellan <emphasis>referensdokumentation</emphasis> som är avsedd för utvecklare och en <emphasis>användarhandbok</emphasis> som är avsedd för slutanvändare. Konventionen är återigen att ha olika mappar för båda. Vi placerar vanligen referensdokumentationen i en mapp med namnet <code>reference</code> handboken för slutanvändare i en mapp med namnet <code>help</code>. Enligt konventionen ovan skulle dokumentationen för vårt paket <code>libmeep</code> placeras i: <code>docs/reference/libmeep</code>. För paket med bara ett bibliotek eller program kan dokumentationen också placeras direkt i <code>docs/reference</code>. Det är inte obligatoriskt att använda konventionen ovan, men om du väljer att använda en annan katalogstruktur måste du anpassa din konfiguration för byggsystemet så att den matchar din katalogstruktur.</para>

      <para>I avsnitten som följer kommer vi anta en katalogstruktur för vårt projekt <emphasis>meep</emphasis> som följer konventionerna ovan. <example>
          <title>Exempel på katalogstruktur för projektet <emphasis>meep</emphasis></title>
          <programlisting>
meep/
  docs/
    reference/  # referensdokumentation
      libmeep/
      meeper/
    help/       # valfritt: användarhandbok
      meeper/
  src/
    libmeep/
    meeper/
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="settingup_autotools">
      <title>Integrering med Autotools</title>
      <para>Integrering av GTK-Doc i ett autotools-baserat byggsystem kräver följande steg:</para>
      <itemizedlist>
        <listitem>
          <para>Säkerställ att <application>gtkdocize</application> körs en gång innan skriptet <filename>configure</filename>. Om skriptet <filename>autogen.sh</filename> finns tillgängligt, justera det så att det söker efter GTK-Doc och lägg till ett anrop till <application>gtkdocize</application>.</para>

          <para>Huvudsyftet med <application>gtkdocize</application> är att göra Makefilen <filename>gtk-doc.make</filename> och makrodefinitionsfilen <filename>gtk-doc.m4</filename> tillgängliga för byggsystemet, antingen genom att kopiera eller länka in dem i projektet.</para>
        </listitem>
        <listitem>
          <para>Lägg till de nödvändiga <application>autoconf</application>-makrona till <filename>configure.ac</filename> för att aktivera GTK-Doc i ditt byggsystem för att tillåta konfiguration av GTK-Doc via det genererade <filename>configure</filename>-skriptet.</para>
          <para>Bland andra med register flaggan <code>--enable-gtk-doc</code> med <filename>configure</filename>-skriptet.</para>
        </listitem>
        <listitem>
          <para>Skapa ett <application>automake</application>-skript för varje program eller bibliotek i ditt projekt. I exemplet som används i denna dokumentation tillämpas detta steg för både <code>meeper</code> och <code>libmeep</code>.</para>
        </listitem>
      </itemizedlist>

      <para>I de följande avsnitten utför vi stegen ovan i omvänd ordning. Vi börjar med <application>automake</application>-skripten och arbetar vår väg upp till <filename>configure.ac</filename> och <filename>autogen.sh</filename>. Sedan visar vi hur Gtk-Doc aktiveras i byggsystemet och hur dokumentationen byggs.</para>

      <sect2 id="settingup_automake">
        <title>Integrering med automake</title>

        <para>Kopiera först <filename>Makefile.am</filename> från underkatalogen <filename class="directory">examples</filename> från <ulink url="https://gitlab.gnome.org/GNOME/gtk-doc/raw/master/examples/Makefile.am">gtkdoc-sources</ulink> till ditt projekts referensdokumentationskatalog (t.ex. <filename class="directory">docs/reference/&lt;paket&gt;</filename>). En lokal kopia bör finnas tillgänglig under t.ex. <filename>/usr/share/doc/gtk-doc-tools/examples/Makefile.am</filename>. Om du har flera paket, repetera detta för vart och ett.</para>

        <note>
          <simpara>Glöm inte att lägga till varje <filename>Makefile.am</filename> till makrot <function>AC_CONFIG_FILES</function> i <filename>configure.ac</filename>. För <filename>docs/reference/libmeep/Makefile.am</filename> kommer du behöva lägga till posten <filename>docs/reference/libmeep/Makefile</filename> till <function>AC_CONFIG_FILES</function>.</simpara>
        </note>

        <example>
          <title>Exempelkatalogstruktur med <filename>Makefiles.am</filename></title>
          <programlisting>
meep/
  docs/
    reference/  # referensdokumentation
      libmeep/
        Makefile.am
      meeper/
        Makefile.am
    help/       # valfritt: användarhandbok
      meeper/
  src/
    libmeep/
    meeper/
</programlisting>
        </example>

        <para>Härnäst behöver du anpassa de kopierade Makefilerna och tillhandahålla värden för de olika parametrarna i varje <filename>Makefile.am</filename>. Alla inställningarna har en kommentar ovanför som beskriver deras syfte och hur inställningen kan anpassas. De flesta inställningarna används för att tillhandahålla extraflaggor till respektive verktyg för vilket de är aktuella. Varje verktyg har en variabel på formen <option>&lt;VERKTYGSNAMN&gt;_OPTIONS</option> (t.ex. har verktyget <application>gtkdoc-mkhtml</application> en flagga med namnet <code>MKHTML_OPTIONS</code>). Alla verktygen har stöd för <option>--help</option> för att lista de flaggor som stöds.</para>

        <para>Följande lista förklarar de mest relevanta flaggorna. Se <filename>Makefile.am</filename>-exemplet för ytterligare flaggor. <itemizedlist>
            <listitem>
              <para><option>DOC_MODULE</option> används för att tillhandahålla namnet på paketet som dokumenteras (t.ex. <code>meeper</code> eller <code>libmeep</code>).</para>
            </listitem>
            <listitem>
              <para><option>DOC_SOURCE_DIR</option> används för att ange platsen för källkatalogen där GTK-Doc söker efter din API-dokumentation. Detta kommer vanligen vara <code> DOC_SOURCE_DIR=$(top_srcdir)/src </code> eller en underkatalog till den katalogen.</para>
            </listitem>

            <listitem>
              <para><option>HFILE_GLOB</option> och <option>CFILE_GLOB</option> används för beroenden. Varje flagga tar en file-glob (t.ex. <code>HFILE_GLOB=$(top_srcdir)/src/*.c</code>). Dokumentationen kommer att byggas om ifall någon av de matchande filerna ändras.</para>
            </listitem>

            <listitem>
              <para><option>EXTRA_HFILES</option> låter dig ange extra huvudfiler som ska inkluderas då API-dokumentation eftersöks, vilka inte hittas under <code>DOC_SOURCE_DIR</code> (t.ex. <code> EXTRA_HFILES=$(top_srcdir}/contrib/extra.h</code>).</para>
            </listitem>

            <listitem>
              <para><option>IGNORE_HFILES</option> låter dig ange huvudfiler eller kataloger som ska ignoreras då API-dokumentation eftersöks. Använd basnamnet på filen eller katalogen (t.ex. <code> IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder</code>).</para>
            </listitem>

            <listitem>
              <para><option>HTML_IMAGES</option> låter dig ange bildfiler som kommer att kopieras till katalogen <filename>html/</filename> av den genererade dokumentationen. Om din API-dokumentation inkluderar några bilder behöver de läggas till i denna flagga (t.ex. <code> HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png</code>).</para>
            </listitem>

            <listitem>
              <para><option>content_files</option> låter dig ange extrafiler som inkluderas av <code>$(DOC_MAIN_SGML_FILE)</code> (t.ex. <code> content_files=running.xml building.xml changes-2.0.xml</code>).</para>
            </listitem>

            <listitem>
              <para><option>expand_content_files</option> låter dig ange filer där <emphasis>gtk-doc-förkortningar</emphasis> så som <code>#GtkWidget</code> expanderas (t.ex. <code> expand_content_files=running.xml</code>).</para>
            </listitem>
          </itemizedlist></para>

      </sect2>

      <sect2 id="settingup_autoconf">
        <title>Integrering med autoconf</title>

        <para>Integrering med <application>autoconf</application> är väldigt enkel och inkluderar ett obligatoriskt steg och ett ytterligare valfritt (men rekommenderat) steg. Det första steget är att lägga till <function>GTK_DOC_CHECK</function>-makrot till ditt <filename>configure.ac</filename>-skript. Detta registrerar flera konfigurationsflaggor för att aktivera GTK-Doc och låter dig ställa in standardargument för <application>gtkdocize</application>.</para>

        <warning>
          <simpara>Säkerställ att makrot <code>GTK_DOC_CHECK</code> inte är indenterat. Makrot måste inledas på början av raden och får inte börja med blanktecken.</simpara>
        </warning>

        <para>Det andra steget är att lägga till <code>AC_CONFIG_MACRO_DIR(m4)</code> till din <filename>configure.ac</filename>. Detta krävs inte men hjälper <application>gtkdocize</application> att automatiskt kopiera makrodefinitionen (t.ex. <filename>gtk-doc.m4</filename>) som innehåller <function>GTK_DOC_CHECK</function>-makrot till ditt projekts makrokatalog. Utan detta kanske GTK_DOC_CHECK-makrot inte hittas och du skulle behöva explicit berätta för <application>aclocal</application>-verktyget var makrodefinitionsfilen kan hittas.</para>

        <para>
          <example><title>Minimal integrering med autoconf</title>
            <programlisting>
# rekommenderat: ställ in m4-katalog
AC_CONFIG_MACRO_DIR(m4)
# valfritt: registrera gtk-doc i configure
GTK_DOC_CHECK([1.28])
</programlisting>
          </example>
        </para>

        <para>Exemplet ovan fungerar, men skulle kräva att alla utvecklare har gtk-doc installerat. Ett bättre sätt är att göra byggande av dokumentationen valfritt på det sätt som visas i nästa exempel: <example>
            <title>Integrering med valfritt gtk-doc-beroende</title>
            <programlisting>
m4_ifdef([GTK_DOC_CHECK], [
# rekommenderat: ställ in m4-katalog
AC_CONFIG_MACRO_DIR(m4)
# valfritt: registrera gtk-doc i configure
GTK_DOC_CHECK([1.28])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
</programlisting>
          </example></para>

        <para>Det första argumentet används för att leta efter Gtk-Doc-versionen under konfigurationen. Det andra, valfria, argumentet används av <application>gtkdocize</application>. Makrot <symbol>GTK_DOC_CHECK</symbol> lägger också till flera configure-flaggor:</para>

        <orderedlist>
          <listitem><para>--with-html-dir=SÖKVÄG : sökväg till installerad dokumentation</para></listitem>
          <listitem><para>--enable-gtk-doc : använd gtk-doc för att bygga dokumentation [standardvärde=no]</para></listitem>
          <listitem><para>--enable-gtk-doc-html : bygg dokumentation i html-format [standardvärde=yes]</para></listitem>
          <listitem><para>--enable-gtk-doc-pdf : bygg dokumentation i pdf-format [standardvärde=no]</para></listitem>
        </orderedlist>

        <important>
          <para>GTK-Doc är inaktiverat som standard! Kom ihåg att skicka flaggan <option>”--enable-gtk-doc”</option> vid nästa körning av <filename>configure</filename>. Annars kommer förgenererad dokumentation att installeras (vilket är rimligt för användare men inte för utvecklare).</para>
        </important>

        <para>Efter att alla ändringar i <filename>configure.ac</filename> är gjorda, uppdatera filen <filename>configure</filename>. Detta kan göras genom att köra om <code>autogen.sh</code>.</para>
      </sect2>

      <sect2 id="settingup_autogen">
        <title>Integrering med autogen</title>

        <para>De flesta projekt kommer att ha ett <filename>autogen.sh</filename>-skript för att ställa in infrastrukturen för bygget efter utcheckning från ett versionshanteringssystem (så som git eller svn). GTK-Doc kommer med ett skript som heter <application>gtkdocize</application> som kan användas för att kopiera nödvändiga filer som behövs av Gtk-Doc till källkatalogen.</para>

        <para>Det bör köras före autoreconf, autoheader, automake eller autoconf.</para>

        <para>
          <example><title>Köra gtkdocize från autogen.sh</title>
            <programlisting>
gtkdocize || exit 1
</programlisting>
          </example>
        </para>

        <para>
          <example>
            <title>Köra gtkdocize villkorligt från autogen.sh</title>
            <programlisting>
GTKDOCIZE=$(which gtkdocize 2&gt;/dev/null)
if test $? -ne 0; then
  echo "Inget gtk-doc-stöd funnet. Du kan inte bygga dokumentationen."
else
  $GTKDOCIZE || exit 1
fi
</programlisting>
          </example>
        </para>

        <para>När <application>gtkdocize</application> kör kopierar det <filename>gtk-doc.make</filename> till din projektrot (eller den katalog som anges med flaggan <option>--docdir</option>).</para>

        <para><application>gtkdocize</application> söker i ditt <filename>configure.ac</filename>-skript efter makrot <function>GTK_DOC_CHECK</function>. Makrot <function>GTK_DOC_CHECK</function> kan användas för att skicka extra argument till skriptet <application>gtkdocize</application>. den andra parametern i <function>GTK_DOC_CHECK</function>-makrot.</para>

        <para>Alternativt kan ytterligare argument också skickas till <application>gtkdocize</application> via miljövariabeln <function>GTKDOCIZE_FLAGS</function>, eller genom att ange dem direkt till <application>gtkdocize</application> i <filename>autogen.sh</filename>.</para>

      </sect2>

      <sect2 id="settingup_firstrun">
        <title>Köra GTK-Doc från byggsystemet</title>

        <para>Efter de tidigare stegen är det dags att köra bygget. Först måste vi köra om <filename>autogen.sh</filename>. Om detta skript kör configure åt dig, kan du ge det flaggan <option>--enable-gtk-doc</option>. Annars kör manuellt <filename>configure</filename> med denna flagga efteråt.</para>
        <para>Den första körningen av make genererar flera extra filer i doc-katalogerna. De viktiga är <filename>&lt;paket&gt;.types</filename>, <filename>&lt;paket&gt;-docs.xml</filename> (tidigare .sgml), <filename>&lt;paket&gt;-sections.txt</filename>.</para>
        <para>
          <example><title>Att köra dokumentationsbygget</title>
            <programlisting>
./autogen.sh --enable-gtk-doc
make
</programlisting>
          </example>
        </para>

        <para>Nu kan du peka din webbläsare till <filename>docs/reference/&lt;paket&gt;/index.html</filename>. Med denna ursprungliga konfiguration kommer du bara se ett väldigt enkelt dokument. Nästa kapitel kommer att lära dig hur du lägger till API-dokumentation till din kod via speciella kommentarsblock. Kapitlet efteråt introducerar <link linkend="metafiles">ytterligare filer</link> och visar hur <link linkend="metafiles_master">huvudmallen</link> redigeras för att lägga till ytterligare kapitel och avsnitt till dina dokumentationsfiler.</para>

      </sect2>

    </sect1>

    <sect1 id="settingup_cmake">
      <title>Integrering med CMake-byggsystem</title>

      <para>GTK-Doc kommer nu att producera en <filename>GtkDocConfig.cmake</filename>-modul (och motsvarande <filename>GtkDocConfigVersion.cmake</filename>-modul). Detta tillhandahåller ett <literal>gtk_doc_add_module</literal>-kommando som du kan ställa in i din <filename>CMakeLists.txt</filename>-fil.</para>

      <para>Det följande exemplet visar hur du använder detta kommando. <example><title>Exempel på användning av GTK-Doc från CMake</title>
          <programlisting>
find_package(GtkDoc 1.25 REQUIRED)

# Skapa målet doc-libmeep.
gtk_doc_add_module(
   libmeep ${CMAKE_SOURCE_DIR}/libmeep
      XML meep-docs.xml
      LIBRARIES libmeep
)

# Bygg doc-libmeep som standardmålet. Utan detta måste du uttryckligen
# köra något i stil med `make doc-libmeep` för att bygga dokumentationen.
add_custom_target(documentation ALL DEPENDS doc-libmeep)

# Installera dokumentationen. (Detta förutsätter att du använder CMake-modulen
# GNUInstallDirs för att ställa in variabeln CMAKE_INSTALL_DOCDIR korrekt).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
        DESTINATION ${CMAKE_INSTALL_DOCDIR})
</programlisting>
        </example></para>
    </sect1>

    <sect1 id="settingup_plain_makefiles">
      <title>Integrering med vanliga makefiler eller andra byggsystem</title>

      <para>I det fall man inte vill använda automake och därför inte heller <filename>gtk-doc.mak</filename> kommer man att behöva anropa gtkdoc-verktygen i rätt ordning i sina egna makefiler (eller andra byggverktyg).</para>

      <para>
        <example><title>Byggsteg för dokumentation</title>
          <programlisting>
DOC_MODULE=meep
// källkod har ändrats
gtkdoc-scan --module=$(DOC_MODULE) &lt;källkodskatalog&gt;
gtkdoc-scangobj --module=$(DOC_MODULE)
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=&lt;källkodskatalog&gt;
// xml-filer har ändrats
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>Man kommer att behöva titta i <filename>Makefile.am</filename> och <filename>gtk-doc.mak</filename> för att plocka ut de extra flaggor som behövs.</para>
    </sect1>

    <sect1 id="settingup_vcs">
      <title>Integrering med versionshanteringssystem</title>

      <para>Som en tumregel är det filerna du redigerar som bör versionshanteras. För typiska projekt är det följande filer: <filename>&lt;paket&gt;.types</filename>, <filename>&lt;paket&gt;-docs.xml</filename> (tidigare .sgml), <filename>&lt;paket&gt;-sections.txt</filename>, <filename>Makefile.am</filename>.</para>
      <para>Filer i katalogerna <filename>xml/</filename> och <filename>html/</filename> bör inte versionshanteras. Detsamma gäller <filename>.stamp</filename>-filerna.</para>
    </sect1>

  </chapter>

  <chapter id="documenting">
    <title>Att dokumentera koden</title>

    <para>GTK-Doc använder källkodskommentarer med en speciell syntax för koddokumentation. Vidare så hämtar det information om din projektstruktur från olika källor. Under nästa avsnitt kommer du att hitta information om syntaxen i kommentarerna.</para>

    <para>GTK-Doc-detektorn kan hantera majoriteten av C-huvuden bra. I det fall när du får varningar från detektorn som ser ut som ett specialfall, kan du tipsa GTK-Doc att hoppa över dem. <example><title>GTK-Doc-kommentarsblock</title>
        <programlisting>
#ifndef __GTK_DOC_IGNORE__
/* unparseable code here */
#endif
</programlisting>
      </example></para>

    <note>
      <title>Begränsningar</title>
      <para>Notera att GTK-Doc har stöd för <code>#ifndef(__GTK_DOC_IGNORE__)</code> men inte <code>#if !defined(__GTK_DOC_IGNORE__)</code> eller andra kombinationer.</para>
    </note>

    <!--  -->

    <sect1 id="documenting_syntax">
      <title>Dokumentationskommentarer</title>

      <para>En flerradskommentar som börjar med en extra ”*” markerar ett dokumentationsblock som kommer att hanteras av GTK-Doc-verktygen. <example><title>GTK-Doc-kommentarsblock</title>
          <programlisting>
/**
 * identifierare:
 * dokumentation …
 */
</programlisting>
        </example></para>

      <para>'Identifierare' är en rad med namnet på det objekt som kommentaren är relaterad till. Syntaxen skiljer sig lite beroende på objekt. (TODO lägg till tabell som visar identifierare)</para>

      <para>Blocket 'dokumentation' skiljer sig också för varje symboltyp. Symboltyper som får parametrar så som funktioner eller makron har en parameterbeskrivning först, åtföljd av en blankrad (bara en ”*”). Efteråt följer den detaljerade beskrivningen. Alla rader (utanför programlistningar och CDATA-avsnitt) som endast innehåller ” *” (blanksteg-asterisk) konverteras till styckeavgränsare. Om du inte vill ha en styckeavgränsare, ändra till ” *  ” (blanksteg-asterisk-blanksteg-blanksteg). Detta är användbart i förformaterad text (kodlistningar).</para>

      <tip>
        <para>När du dokumenterar kod, beskriv två aspekter: <itemizedlist>
             <listitem>
               <para>Vad är detta: Namnet på en klass eller en funktion kan ibland vara vilseledande för personer med annan bakgrund.</para>
             </listitem>
             <listitem>
               <para>Vad gör det: Berättar om vanliga användningsfall. Sätter det i relation med det andra API:t.</para>
             </listitem>
           </itemizedlist></para>
      </tip>

      <para>En fördel med hypertext framför vanlig text är möjligheten att ha länkar i dokumentet. Att skriva korrekta taggar för en länk kan dock vara tröttsamt. GTK-Doc hjälper då till med att tillhandahålla flera användbara förkortningar. <itemizedlist>
          <listitem>
            <para>Använd funktion() för att referera till funktioner eller makron som tar argument.</para>
          </listitem>
          <listitem>
            <para>Använd @param för att referera till parametrar. Använd också detta när du refererar till parametrar för andra funktioner, relaterade till den som beskrivs.</para>
          </listitem>
          <listitem>
            <para>Använd %konstant för att referera till en konstant, t.ex. %G_TRAVERSE_LEAFS.</para>
          </listitem>
          <listitem>
            <para>Använd #symbol för att referera till andra typer av symboler, t.ex. strukturer eller uppräkningar och makron som inte tar argument.</para>
          </listitem>
          <listitem>
            <para>Använd #Objekt::signal för att referera till en GObject-signal.</para>
          </listitem>
          <listitem>
            <para>Använd #Objekt:egenskap för att referera till en GObject-egenskap.</para>
          </listitem>
          <listitem>
            <para>Använd #Struktur.fält för att referera till ett fält inuti en struktur och #GObjectKlass.foo_bar() för att referera till en virtuell metod.</para>
          </listitem>
        </itemizedlist></para>

      <tip>
        <para>Om du behöver använda specialtecken ”&lt;”, ”&gt;”, ”()”, ”@”, ”%” eller ”#” i din dokumentation utan att GTK-Doc ändrar dem kan du använda XML-entiteterna ”&amp;lt;”, ”&amp;gt;”, ”&amp;lpar;”, ”&amp;rpar;”, ”&amp;commat;”, ”&amp;percnt;” respektive ”&amp;num;” eller använda kontrollsekvensen ”\”.</para>
      </tip>

      <para>DocBook kan mer än bara länkar. Du kan också ha listor, exempel, rubriker och bilder. Från och med version 1.20, är det föredragna sättet att använda en delmängd av den grundläggande textformateringssyntaxen som kallas <ulink url="http://daringfireball.net/projects/markdown/">Markdown</ulink>. Äldre GTK-Doc-versioner kommer dokumentation som inkluderar markdown att renderas som den är. Till exempel kommer listobjekt att visas som att de börjar med ett bindestreck.</para>

      <para>Då markdown numera föredras kan du blanda båda. En begränsning här är att du kan använda docbook-xml inuti markdown, men markdown inuti docbook-xml stöds inte.</para>

      <para>I äldre GTK-Doc-versioner var du tvungen, om du ville ha stöd för ytterligare formatering, att aktivera användningen av docbook-XML-taggar inuti dok-kommentarer genom att lägga till <option>--xml-mode</option> (eller <option>--sgml-mode</option>) i variabeln <symbol>MKDB_OPTIONS</symbol> inuti <filename>Makefile.am</filename>.</para>

      <para>
        <example><title>GTK-Doc-kommentarsblock som använder Markdown</title>
          <programlisting>
/**
 * Identifierare:
 *
 * stycke med dokumentation …
 *
 * # Underrubrik #
 *
 * ## Underunderrubrik
 *
 * # Underrubrik med länkankare # {#andra-rubriken}
 *
 * mer dokumentation:
 *
 * - listobjekt 1
 *
 *   Stycke inuti listobjekt.
 *
 * - listobjekt 2
 *
 * 1. numrerat listobjekt
 *
 * 2. ytterligare ett numrerat listobjekt
 *
 * Ett annat stycke. [En länk till GNOME:s webbplats](http://www.gnome.org/)
 *
 * ![en bild](resultatgraf.png)
 *
 * [En länk till rubrikankaret ovan][andra-rubriken]
 *
 * Ett C-exempel:
 * |[&lt;!-- language="C" --&gt;
 * GtkWidget *label = gtk_label_new ("Vackert!");
 * ]|
 */
</programlisting>
        </example>
      </para>

      <para>Fler exempel på vilka markdown-taggar som stöds hittas i <ulink url="https://wiki.gnome.org/Projects/GTK/DocumentationSyntax/Markdown">Referensen för GTK-dokumentationens markdown-syntax</ulink>.</para>

      <tip>
        <para>Som redan nämnts är GTK-Doc avsett för att dokumentera publika API:er. Du kan därför inte skriva dokumentation för statiska symboler. Likväl är det bra att kommentera även dessa symboler. Det hjälper andra utvecklare att förstå din kod. Därför rekommenderar vi att du kommenterar dessa med normala kommentarer (utan den andra ”*” på den första raden). Om funktionen vid ett senare tillfälle måste göras publik är allt du behöver göra att lägga till ytterligare en ”*” i kommentarsblocket och infoga symbolnamnet på rätt ställe i avsnittsfilen.</para>
      </tip>
    </sect1>

    <sect1 id="documenting_sections">
      <title>Dokumentationsavsnitt</title>

      <para>Varje avsnitt av dokumentation innehåller information om en klass eller en modul. För att introducera komponenten kan man skriva ett avsnittsblock. Den korta beskrivningen används också i innehållsförteckningen. Alla @fälten är valfria.</para>

      <para>
        <example><title>Kommentarsblock för avsnitt</title>
          <programlisting>
/**
 * SECTION:meepapp
 * @short_description: programklassen
 * @title: Meep-programmet
 * @section_id:
 * @see_also: #MeepSettings
 * @stability: Stable
 * @include: meep/app.h
 * @image: application.png
 *
 * Programklassen hanterar …
 */
</programlisting>
        </example>
      </para>

      <variablelist>
        <varlistentry>
          <term>SECTION:&lt;namn&gt;</term>
          <listitem>
            <para>Namnet länkar till avsnittsdokumentationen för respektive del i filen <filename>&lt;paket&gt;-sections.txt</filename>. Namnet som anges här bör matcha taggen &lt;FILE&gt; i filen <filename>&lt;paket&gt;-sections.txt</filename>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@short_description</term>
          <listitem>
            <para>En enradsbeskrivning av avsnittet som senare kommer att visas efter länkar i innehållsförteckningen och lägst upp på avsnittssidan.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@title</term>
          <listitem>
            <para>Avsnittstiteln är som standard &lt;namn&gt; från SECTION-deklarationen. Den kan åsidosättas med fältet @title.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@section_id</term>
          <listitem>
            <para>Åsidosätter användningen av titeln som avsnittsidentifierare. För GObjects används &lt;title&gt; som ett section_id och för andra avsnitt är det &lt;MODULE&gt;-&lt;title&gt;.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@see_also</term>
          <listitem>
            <para>En lista över symboler som är relaterade till detta avsnitt.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@stability</term>
          <listitem>
            <para>En informell beskrivning över stabiliteten för detta API. Vi rekommenderar att använda en av dessa termer: <itemizedlist>
                <listitem>
                  <para>Stable - Avsikten med ett stabilt gränssnitt är att möjliggöra för tredje parter att utveckla program mot dessa gränssnitt, släppa dem och vara säkra på att de kommer att köra på alla programfixversioner av produkten (efter den i vilken gränssnittet introducerats, och inom samma huvudversion). Även vid en ny huvudversion förväntas inkompatibla ändringar vara få och vara väl motiverade.</para>
                </listitem>
                <listitem>
                  <para>Unstable - Instabila gränssnitt är experimentella eller i en övergångsfas. De används typiskt för att ge utomstående utvecklare tidig tillgång till ny eller snabbt föränderlig teknologi, eller för att tillhandahålla provisoriska lösningar för ett problem där en mer generell lösning förutses. Inga påståenden görs om endera källkods- eller binärkompatibilitet från en programfixversion till nästa.</para>
                </listitem>
                <listitem>
                  <para>Private - Ett gränssnitt som kan användas inom GNOME-stacken i sig, men som inte dokumenterats för slutanvändare. Sådana funktioner bör endast användas på angivna och dokumenterade sätt.</para>
                </listitem>
                <listitem>
                  <para>Internal - ett gränssnitt som är internt för en modul och inte behöver slutanvändardokumentation. Funktioner som är odokumenterade förutsätts vara interna.</para>
                </listitem>
              </itemizedlist></para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@include</term>
          <listitem>
            <para><literal>#include</literal>-filerna som ska visas i avsnittssammanfattningen (en kommaavgränsad lista), vilket åsidosätter det globala värdet från <link linkend="metafiles_sections">avsnittsfilen</link> eller kommandoraden. Detta objekt är valfritt.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>@image</term>
          <listitem>
            <para>Bilden som ska visas längst upp på referenssidan för detta avsnitt. Detta kommer ofta att vara någon form av diagram för att illustrera det visuella utseendet för en klass eller ett diagram över dess relationer med andra klasser. Detta objekt är valfritt.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <tip>
        <para>För att undvika onödig omkompilering efter dokumentationsändringar, placera avsnittsdokumentationen i c-källkoden där möjligt.</para>
      </tip>

    </sect1>

    <sect1 id="documenting_symbols">
      <title>Dokumentationssymboler</title>

      <para>Varje symbol (funktion, makro, struktur, uppräkning, signal och egenskap) är dokumenterad i ett separat block. Blocket placeras bäst intill definitionen av symbolerna så att det är enkelt att hålla dem synkroniserade. Därför dokumenteras funktioner vanligtvis i c-källkoden och makron, strukturer och uppräkningar i huvudfilen.</para>

      <sect2><title>Generella taggar</title>

        <para>Du kan lägga till versioneringsinformation i alla dokumentationselement för att berätta när ett API introducerats eller blev föråldrat.</para>

        <variablelist><title>Versioneringstaggar</title>
          <varlistentry><term>Since:</term>
            <listitem>
              <para>Beskrivning över från och med vilken version av koden som API:t är tillgängligt.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Deprecated:</term>
            <listitem>
              <para>Stycke som betecknar att denna funktion inte bör användas längre. Beskrivningen bör peka läsaren vidare till det nya API:t.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>Du kan också lägga till stabilitetsinformation för alla dokumentationselement för att indikera huruvida API-stabilitet är garanterad för dem för alla framtida programfix-versioner av projektet.</para>

        <para>Standardvärdet för stabilitetsnivån för alla dokumentations element kan ställas in genom att ange argumentet <option>--default-stability</option> till <application>gtkdoc-mkdb</application> med endera av värdena nedan.</para>

        <variablelist><title>Stabilitetstaggar</title>
          <varlistentry><term>Stability: Stable</term>
            <listitem>
              <para>Markera elementet som stabilt. Detta är för publika API:er som är garanterade att hållas stabila i alla framtida programfix-versioner av projektet.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Stability: Unstable</term>
            <listitem>
              <para>Markera elementet som instabilt. Detta är för publika API:er som är släppta på förhand innan de blivit stabiliserade.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>Stability: Private</term>
            <listitem>
              <para>Markera element som privat. Detta är avsett för gränssnitt som kan användas av tätt sammankopplade moduler, men inte av godtyckliga tredje parter.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <example><title>Generella taggar</title>
          <programlisting>
/**
 * foo_get_bar:
 * @foo: någon foo
 *
 * Hämtar bar från @foo.
 *
 * Returns: bar från @foo
 *
 * Since: 2.6
 * Deprecated: 2.12: Använd foo_baz_get_bar() i stället.
 */
Bar *
foo_get_bar(Foo *foo)
{
…
</programlisting>
        </example>
      </sect2>

      <sect2><title>Noteringar</title>

        <para>Dokumentationsblock kan innehålla noteringstaggar. Dessa taggar kommer att renderas med inforutor som beskriver deras syfte. Taggarna används av GObject Introspection för att generera språkbindningar. En detaljerad lista över vilka taggar som stöds hittas i <ulink url="https://gi.readthedocs.io/en/latest/annotations/giannotations.html" type="http">dokumentationen för GObject Introspection</ulink>.</para>

        <example><title>Noteringar</title>
          <programlisting>
/**
 * foo_get_bar: (notering)
 * @foo: (notering): någon foo
 *
 * Hämtar bar från @foo.
 *
 * Returns: (notering): bar från @foo
 */
...
/**
 * foo_set_bar_using_the_frobnicator: (notering) (an annan notering)
 *                                    (ytterligare en annan notering)
 * @foo: (notering) (en annan notering): någon foo
 *
 * Ställer in bar i @foo.
 */
</programlisting>
        </example>
      </sect2>

      <sect2><title>Kommentarsblock för funktioner</title>

        <para>Kom ihåg att: <itemizedlist>
            <listitem>
              <para>Dokumentera huruvida returnerade objekt, listor, strängar, etc. bör frigöras/avrefereras/släppas.</para>
            </listitem>
            <listitem>
              <para>Dokumentera huruvida parametrar tillåts vara NULL och vad som händer om de är NULL.</para>
            </listitem>
            <listitem>
              <para>Nämn intressanta förvillkor och eftervillkor där lämpligt.</para>
            </listitem>
          </itemizedlist></para>

        <para>Gtk-doc förutsätter att alla symboler (makron, funktioner) som börjar med ”_” är privata. De behandlas på samma sätt som statiska funktioner.</para>

        <example><title>Kommentarsblock för funktioner</title>
          <programlisting>
/**
 * funktionsnamn:
 * @par1:  beskrivning av parameter 1. Dessa kan sträcka sig
 *  över mer än en rad.
 * @par2:  beskrivning av parameter 2
 * @...: en %NULL-terminerad lista av flera bar
 *
 * Funktionsbeskrivningen ska vara här. Du kan använda @par1 för att
 * referera till parametrar så att de färgmarkeras i utdata. Du kan också
 * använda %konstant för konstanter, funktionsnamn2() för funktioner och
 * #GtkWidget för länkar till andra deklarationer (vilka kan vara dokumenterade
 * på annat håll).
 *
 * Returns: ett heltal.
 *
 * Since: 2.2
 * Deprecated: 2.18: Använd annan_funktion() i stället.
 */
</programlisting>
        </example>

        <variablelist><title>Funktions-taggar</title>
          <varlistentry><term>Returns:</term>
            <listitem>
              <para>Stycke som beskriver det returnerade resultatet.</para>
            </listitem>
          </varlistentry>
          <varlistentry><term>@...:</term>
            <listitem>
              <para>Om funktionen har variadiska argument bör du använda denna tagg (@Varargs: fungerar också på grund av historiska skäl).</para>
            </listitem>
          </varlistentry>
        </variablelist>

      </sect2>

      <sect2><title>Kommentarsblock för egenskaper</title>

        <example><title>Kommentarsblock för egenskaper</title>
          <programlisting>
/**
 * EnKomponent:en-egenskap:
 *
 * Här kan du dokumentera en egenskap.
 */
g_object_class_install_property (object_class, PROP_EN_EGENSKAP, …);
</programlisting>
        </example>

      </sect2>

      <sect2><title>Kommentarsblock för signaler</title>

        <para>Kom ihåg att: <itemizedlist>
            <listitem>
              <para>Dokumentera när en signal sänds ut och huruvida den sänds ut före eller efter andra signaler.</para>
            </listitem>
            <listitem>
              <para>Dokumentera vad ett program kan göra i signalhanteraren.</para>
            </listitem>
          </itemizedlist></para>

        <example><title>Kommentarsblock för signaler</title>
          <programlisting>
/**
 * FooWidget::foobariserad:
 * @widget: komponenten som erhåller signalen
 * @foo: någon foo
 * @bar: någon bar
 *
 * Signalen ::foobariserad sänds ut varje gång någon försöker att foobarisera @widget.
 */
foo_signals[FOOBARIZE] =
  g_signal_new ("foobariserad",
                ...
</programlisting>
        </example>

      </sect2>

      <sect2><title>Kommentarsblock för strukturer</title>
        <example><title>Kommentarsblock för strukturer</title>
          <programlisting>
/**
 * FooWidget:
 * @bar: någon #gboolean
 *
 * Detta är den bästa komponenten någonsin.
 */
typedef struct _FooWidget {
  GtkWidget parent_instance;

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

        <para>Använd<code>/*&lt; private &gt;*/</code> före privata strukturfält som du vill gömma. Använd <code>/*&lt; public &gt;*/</code> för det omvända beteendet.</para>

        <para>Om det första fältet är ”g_iface”, ”parent_instance” eller ”parent_class” kommer det att anses vara privat automatiskt och behöver inte nämnas i kommentarsblocket.</para>

        <para>Kommentarsblock för strukturer kan också användas för GObject och GObjectClass. Det är vanligtvis en bra idé att lägga till ett kommentarsblock för en klass om den har virtuella metoder (då detta är sättet på vilket de kan dokumenteras). För GObject i sig kan man använda den relaterade avsnittsdokumentationen, och ha ett separat block för varje instansstruktur vore användbart om instansen har publika fält. En nackdel här är att det skapar två indexposter med samma namn (strukturen och avsnittet).</para>

      </sect2>

      <sect2><title>Kommentarsblock för uppräkningar</title>
        <example><title>Kommentarsblock för uppräkningar</title>
          <programlisting>
/**
 * Something:
 * @SOMETHING_FOO: någonting foo
 * @SOMETHING_BAR: någonting bar
 *
 * Uppräkningsvärden som används för saken, för att specificera saken.
 */
typedef enum {
  SOMETHING_FOO,
  SOMETHING_BAR,
  /*&lt; private &gt;*/
  SOMETHING_COUNT
} Something;
</programlisting>
        </example>

        <para>Använd <code>/*&lt; private &gt;*/</code> före privata uppräkningsvärden som du vill gömma. Använd <code>/*&lt; public &gt;*/</code> för det omvända beteendet.</para>

      </sect2>
    </sect1>


    <sect1 id="documenting_inline_program">
      <title>Infogad programdokumentation</title>
      <para>Du kan dokumentera program och deras kommandoradsgränssnitt med infogad dokumentation.</para>

      <variablelist>
      <title>Taggar</title>

      <varlistentry><term>PROGRAM</term>

      <listitem>
      <para>Definierar början av programdokumentationen.</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@short_description:</term>
      <listitem>
      <para>Definierar en kort beskrivning av programmet. (Valfritt)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@synopsis:</term>
      <listitem>
      <para>Definierar argumenten, eller en lista av argument som programmet kan ta. (Valfritt)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@see_also:</term>
      <listitem>
      <para>Se vidare i manualavsnitt. (Valfritt)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>@arg:</term>
      <listitem>
      <para>Argument som skickas vidare till programmet och deras beskrivningar. (Valfritt)</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>Beskrivning:</term>
      <listitem>
      <para>En längre beskrivning av programmet.</para>
      </listitem>
      </varlistentry>

      <varlistentry>
      <term>Returns:</term>
      <listitem>
      <para>Ange vilka värden programmet returnerar. (Valfritt)</para>
      </listitem>
      </varlistentry>

      </variablelist>

      <sect2>
        <title>Exempel på programdokumentation.</title>
        <example><title>Dokumentationsblock för program</title>
        <programlisting>
/**
 * PROGRAM:test-program
 * @short_description: Ett testprogram
 * @synopsis: test-program [*FLAGGOR*...] --arg1 *arg* *FIL*
 * @see_also: test(1)
 * @--arg1 *arg*: ställ in arg1 på *arg*
 * @--arg2 *arg*: ställ in arg2 på *arg*
 * @-v, --version: Skriv ut versionsinformation
 * @-h, --help: Skriv ut hjälpmeddelandet
 *
 * En längre beskrivning av programmet.
 *
 * Returns: Noll vid framgång, icke-noll vid fel
 */
int main(int argc, char *argv[])
{
	return 0;
}
</programlisting>
        </example>

      </sect2>
    </sect1>

    <sect1 id="documenting_docbook">
      <title>Användbara DocBook-taggar</title>

      <para>Här är några DocBook-taggar som är användbara när man dokumenterar koden.</para>

      <para>För att länka till ett annat avsnitt i GTK-dokumentationen: <informalexample>
          <programlisting>
&lt;link linkend="glib-Hash-Tables"&gt;Hashtabeller&lt;/link&gt;
</programlisting>
        </informalexample> Länkslutet är XGML/XML-id:t för toppnivåobjektet på sidan du vill länka till. För de flesta sidorna är detta för närvarande delen (”gtk”, ”gdk”, ”glib”) och sedan sidans titel (”Hashtabeller”). För komponenter är detta helt enkelt klassnamnet. Blanksteg och understreck konverteras till ”-” för att överensstämma med SGML/XML.</para>

      <para>För att referera till en extern funktion, t.ex. en standardfunktion i C: <informalexample>
          <programlisting>
&lt;function&gt;…&lt;/function&gt;
</programlisting>
        </informalexample></para>

      <para>För att inkludera exempelkod: <informalexample>
          <programlisting>
&lt;example&gt;
  &lt;title&gt;Att använda en GHashTable.&lt;/title&gt;
  &lt;programlisting language="C"&gt;
      ...
  &lt;/programlisting&gt;
&lt;/example&gt;
</programlisting>
        </informalexample> eller möjligen följande, för väldigt korta kodfragment som inte behöver en titel: <informalexample>
          <programlisting>
&lt;informalexample&gt;
  &lt;programlisting language="C"&gt;
  ...
  &lt;/programlisting&gt;
&lt;/informalexample&gt;
</programlisting>
        </informalexample> I båda fallen är språkattributet valfritt och används som ett tips för syntaxmarkeringsmotorn (pygments för html-utmatning). För det senare fallet har GTK-Doc också stöd för en förkortning: <informalexample>
          <programlisting>
|[&lt;!-- language="C" --&gt;
  ...
]|
</programlisting>
        </informalexample></para>

      <para>För att inkludera punktlistor: <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>För att inkludera en not som skiljer sig från texten: <informalexample>
          <programlisting>
&lt;note&gt;
  &lt;para&gt;
    Säkerställ att du frigjort data efter användning.
  &lt;/para&gt;
&lt;/note&gt;
</programlisting>
        </informalexample></para>

      <para>För att refera till en typ: <informalexample>
          <programlisting>
&lt;type&gt;unsigned char&lt;/type&gt;
</programlisting>
        </informalexample></para>

      <para>För att referera till en extern struktur (som inte beskrivs i GTK-dokumentationen): <informalexample>
          <programlisting>
&lt;structname&gt;XFontStruct&lt;/structname&gt;
</programlisting>
        </informalexample></para>

      <para>För att referera till ett fält för en struktur: <informalexample>
          <programlisting>
&lt;structfield&gt;len&lt;/structfield&gt;
</programlisting>
        </informalexample></para>

      <para>För att referera till ett klassnamn kan vi möjligen använda: <informalexample>
          <programlisting>
&lt;classname&gt;GtkWidget&lt;/classname&gt;
</programlisting>
        </informalexample> men du kommer troligt att använda #GtkWidget i stället (för att automatiskt skapa en länk till GtkWidget-sidan - se <link linkend="documenting_syntax">förkortningarna</link>).</para>

      <para>För att betona text: <informalexample>
          <programlisting>
&lt;emphasis&gt;Detta är viktigt&lt;/emphasis&gt;
</programlisting>
        </informalexample></para>

      <para>För filnamn använd: <informalexample>
          <programlisting>
&lt;filename&gt;/home/användare/dokument&lt;/filename&gt;
</programlisting>
        </informalexample></para>

      <para>För att referera till tangenter använd: <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>Fylla i de extra filerna</title>

    <para>Det finns ett antal extra filer som behöver underhållas tillsammans med de infogade källkodskommentarerna: <filename>&lt;paket&gt;.types</filename>, <filename>&lt;paket&gt;-docs.xml</filename> (tidigare .sgml), <filename>&lt;paket&gt;-sections.txt</filename>.</para>

    <sect1 id="metafiles_types">
      <title>Redigera typfilen</title>

      <para>Om ditt bibliotek eller program inkluderar GObject så kommer du att vilja att deras signaler, argument/parametrar och position i hierarkin visas i dokumentationen. Allt du behöver göra är att lista <function>xxx_get_type</function>-funktionerna tillsammans med deras huvudfil i filen <filename>&lt;paket&gt;.types</filename>.</para>

      <para>
        <example><title>Exempel på filen &lt;paket&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>Sedan GTK-Doc 1.8 kan <application>gtkdoc-scan</application> generera denna lista åt dig. Lägg bara till ”--rebuild-types” i SCAN_OPTIONS i <filename>Makefile.am</filename>. Om du använder detta tillvägagångssätt bör du inte distribuera typfilen eller versionshantera den.</para>

    </sect1>

    <sect1 id="metafiles_master">
      <title>Redigera huvuddokumentet</title>

      <para>GTK-Doc producerar dokumentation i DocBook SGML/XML. När infogade källkodskommentarer behandlas genererar GTK-Doc en dokumentationssida per klass eller modul som en separat fil. Huvuddokumentet inkluderar dem och placerar dem i en ordning.</para>

      <para>Även om GTK-Doc skapar en mall för huvuddokumentet åt dig kommer senare körningar inte att röra det igen. Detta innebär att man är fri att strukturera om dokumentationen. Detta inkluderar att gruppera sidor och lägga till extra sidor. GTK-Doc har numera en testsvit där också huvuddokumentet återskapas från grunden. Det är en bra idé att titta på detta då och då för att se om några nya godsaker införts där.</para>

      <tip>
        <para>Skapa inte handledningar som extra dokument. Skriv bara extra kapitel. Fördelen med att bädda in handledningen direkt i ditt biblioteks gränssnittsdokumentation är att det är enkelt att länka från handledningen till symboldokumentationen. Inbäddad är det större chans att handledningen blir uppdaterad tillsammans med biblioteket.</para>
      </tip>

      <para>Så vilka saker ska ändras i huvuddokumentet? I början är det väldigt lite. Det finns en del platshållare (text i hakparenteser) som du bör ta hand om.</para>

      <para>
        <example><title>Huvuddokumentets huvud</title>
          <programlisting>
&lt;bookinfo&gt;
  &lt;title&gt;MODULNAMN handbok&lt;/title&gt;
  &lt;releaseinfo&gt;
    för MODULNAMN [VERSION]
    Den senaste versionen av detta dokument kan hittas på nätet på
    &lt;ulink role="online-location" url="http://[SERVER]/MODULNAMN/index.html"&gt;http://[SERVER]/MODULNAMN/&lt;/ulink&gt;.
  &lt;/releaseinfo&gt;
&lt;/bookinfo&gt;

&lt;chapter&gt;
  &lt;title&gt;[Infoga titel här]&lt;/title&gt;
</programlisting>
        </example>
      </para>

      <para>Dessutom finns det ett antal valfria element som skapas i kommenterad form. Du kan granska dessa och aktivera dem enligt dina egna önskemål.</para>

      <para>
        <example><title>Valfri del i huvuddokumentet</title>
          <programlisting>
  &lt;!-- aktivera detta om du vill använda gobject introspection-noteringar
  &lt;xi:include href="xml/annotation-glossary.xml"&gt;&lt;xi:fallback /&gt;&lt;/xi:include&gt;
  --&gt;
</programlisting>
        </example>
      </para>

      <para>Slutligen behöver du lägga till ett nytt avsnitt när du infogar det. Verktyget <link linkend="modernizing-gtk-doc-1-16">gtkdoc-check</link> kommer att påminna dig om nyligen genererade xml-filer som ännu inte infogats i dokumentationen.</para>

      <para>
        <example><title>Inkludera genererade avsnitt</title>
          <programlisting>
  &lt;chapter&gt;
    &lt;title&gt;mitt bibliotek&lt;/title&gt;
      &lt;xi:include href="xml/object.xml"/&gt;
      ...
</programlisting>
        </example>
      </para>

    </sect1>

    <sect1 id="metafiles_sections">
      <title>Redigera avsnittsfilen</title>

      <para>Avsnittsfilen används för att organisera dokumentationsutdata från GTK-Doc. Här kan man ange vilken symbol som hör till vilken modul eller klass och styra synligheten (publik eller privat).</para>

      <para>Avsnittsfilen är en vanlig textfil med taggar som avgränsar avsnitt. Blankrader ignoreras och rader som börjar med ett ”#” behandlas som kommentarsrader.</para>

      <note>
        <para>Även om taggarna får filen att se ut som xml, är det inte det. Avsluta inte taggar så som &lt;SUBSECTION&gt;.</para>
      </note>

      <para>
        <example><title>Inkludera genererade avsnitt</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>Taggen &lt;FILE&gt; … &lt;/FILE&gt; används för att ange filnamnet, utan något suffix. Om man t.ex. använder ”&lt;FILE&gt;gnome-config&lt;/FILE&gt;” blir resultatet att avsnittsdeklarationerna matas ut i mallfilen <filename>tmpl/gnome-config.sgml</filename>, som kommer att konverteras till DocBook XML-filen <filename>xml/gnome-config.sgml</filename> eller DocBook XML-filen <filename>xml/gnome-config.xml</filename>. (Namnet på HTML-filen baseras på modulnamnet och avsnittstiteln, för GObject baseras det på klassnamnet för GObjectet konverterat till gemener).</para>

      <para>Taggen &lt;TITLE&gt; … &lt;/TITLE&gt; används för att ange titeln på avsnittet. Det är bara användbart före mallar skapas initialt (om de används), eftersom titeln som ställs in i avsnittsfilen åsidosätter denna. Vidare är detta föråldrat om man använder SECTIONS-kommentarer i källkoden.</para>

      <para>Du kan gruppera objekt i avsnittet genom att använda taggen &lt;SUBSECTION&gt;. För närvarande matas en blankrad ut mellan underavsnitt i sammanfattningsavsnittet. Du kan också använda &lt;SUBSECTION Standard&gt; för standard GObject-deklarationer (t.ex. funktioner så som g_object_get_type och makron som G_OBJECT(), G_IS_OBJECT(), etc.). För närvarande utelämnas dessa ur dokumentationen. Du kan också använda &lt;SUBSECTION Private&gt; för privata deklarationer som inte kommer att matas ut (det är ett bekvämt sätt att undvika varningsmeddelanden om oanvända deklarationer). Om ditt bibliotek innehåller privata typer som du inte vill ska dyka upp i objekthierarkin och i listan över implementerade eller krävda gränssnitt, lägg till dem i ett privat avsnitt. Huruvida du vill placera GObject och GObjectClass-liknande strukturer i publika eller standardavsnitt beror på om de har publika poster (variabler, virtuella metoder).</para>

      <para>Du kan också använda &lt;INCLUDE&gt; ... &lt;/INCLUDE&gt; för att ange #include-filerna som ska visas i sammanfattningsavsnitten. Den innehåller en kommaavgränsad lista av #include-filer, utan vinkelparenteser. Om du ställer in det utanför några avsnitt kommer det att påverka alla avsnitt tills slutet på filen. Om du ställer in det inom ett avsnitt kommer det bara att påverka det avsnittet.</para>

    </sect1>

  </chapter>

  <chapter id="reports">
    <title>Kontrollera resultatet</title>

    <para>En GTK-Doc-körning genererar rapportfiler inuti dokumentationskatalogen. De genererade filerna heter: <filename>&lt;paket&gt;-undocumented.txt</filename>, <filename>&lt;paket&gt;-undeclared.txt</filename> och <filename>&lt;paket&gt;-unused.txt</filename>. Alla är vanliga textfiler och kan visas eller efterbehandlas enkelt.</para>

    <para>Filen <filename>&lt;paket&gt;-undocumented.txt</filename> inleds med en sammanfattning över hur mycket dokumentation som skrivits. Under det finns två avsnitt avgränsade av blankrader. Det första avsnittet listar odokumenterade eller ofullständiga symboler. Det andra avsnittet gör detsamma för avsnittsdokumentation. Ofullständiga poster är de som har dokumentation, men där en ny parameter har lagts till.</para>

    <para>Filen <filename>&lt;paket&gt;-undeclared.txt</filename> listar symboler som anges i <filename>&lt;paket&gt;-sections.txt</filename> men inte hittas i källkoden. Kontrollera om de har tagits bort eller om de är felstavade.</para>

    <para>Filen <filename>&lt;paket&gt;-unused.txt</filename> listar symbolnamn där GTK-Doc-detektorn har hittat dokumentation men inte vet var den ska placeras. Detta innebär att symbolen ännu inte har lagts till i filen <filename>&lt;package&gt;-sections.txt</filename>.</para>

    <tip>
      <para>Aktivera eller lägg till raden <option>TESTS=$(GTKDOC_CHECK)</option> i Makefile.am. Om åtminstone GTK-Doc 1.9 finns installerat kommer detta att köra rimlighetskontroller under körning av <command>make check</command>.</para>
    </tip>

    <para>Man kan också titta på filerna som producerats av källkodsdetektorn: <filename>&lt;paket&gt;-decl-list.txt</filename> och <filename>&lt;paket&gt;-decl.txt</filename>. Den första kan jämföras med avsnittsfilen om den underhålls manuellt. Den andra listar alla deklarationer från huvudena. Om en symbol saknas bör man kontrollera om denna filen innehåller den.</para>

    <para>Om projektet är GObject-baserat kan man också titta på filerna som producerats av objekt-detektorn: <filename>&lt;paket&gt;.args.txt</filename>, <filename>&lt;paket&gt;.hierarchy.txt</filename>, <filename>&lt;paket&gt;.interfaces.txt</filename>, <filename>&lt;paket&gt;.prerequisites.txt</filename> och <filename>&lt;paket&gt;.signals.txt</filename>. Om det saknas symboler i någon av dem kan man be GTK-Doc att bibehålla de temporära detektorfilerna för vidare analys, genom att köra det som <command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.</para>
  </chapter>

  <chapter id="modernizing">
    <title>Modernisera dokumentationen</title>

    <para>GTK-Doc har funnits ett tag. I detta avsnitt listar vi nya funktioner tillsammans med vilken version de gjordes tillgängliga.</para>

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

      <para>När man använder xml i stället för sgml, kan man faktiskt kalla huvuddokumentet <filename>&lt;paket&gt;-docs.xml</filename>.</para>

      <para>Denna version har stöd för <option>SCAN_OPTIONS=--rebuild-sections</option> i <filename>Makefile.am</filename>. När detta är aktiverat kommer <filename>&lt;paket&gt;-sections.txt</filename> att autogenereras och kan tas bort från versionshanteringssystemet. Detta fungerar bra för projekt som har en väldigt standardiserad struktur (t.ex. kommer varje .{c,h}-par att skapa ett nytt avsnitt). Om man organiserar ett projekt likt detta kommer den manuella uppdateringen av en avsnittsfil att vara så enkelt som att köra <code>meld &lt;paket&gt;-decl-list.txt &lt;paket&gt;-sections.txt</code>.</para>

      <para>Redan version 1.8 introducerade syntaxen för avsnittsdokumentation i källkoden i stället för separata filer under <filename class="directory">tmpl</filename>. Denna version lägger till flaggor för att kunna ställa om hela dokumentationsmodulen till att inte använda det extra tmpl-byggsteget alls, genom att använda <option>--flavour no-tmpl</option> i <filename>configure.ac</filename>. Om du inte har <filename class="directory">tmpl</filename> incheckat i ditt versionshanteringssystem just nu och inte har gått över än bara lägg till flaggan i <filename>configure.ac</filename> så är du klar.</para>
    </sect1>

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

      <para>Denna version har stöd för <option>SCAN_OPTIONS=--rebuild-types</option> i <filename>Makefile.am</filename>. När det är aktiverat kommer <filename>&lt;package&gt;.types</filename> att autogenereras och kan tas bort från versionshanteringssystemet. När denna funktion används är det viktigt att också ställa in <varname>IGNORE_HFILES</varname> i <filename>Makefile.am</filename> för kod som bara byggs ibland.</para>
    </sect1>

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

      <para>Denna version har stöd för ett nytt verktyg som heter gtkdoc-check. Detta verktyg kan köra en uppsättning kontroller på din dokumentation. Det aktiveras genom att lägga till dessa raderna i slutet av <filename>Makefile.am</filename>. <example><title>Aktivera gtkdoc-check</title>
          <programlisting>
if ENABLE_GTK_DOC
TESTS_ENVIRONMENT = \
  DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
  SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
TESTS = $(GTKDOC_CHECK)
endif
</programlisting>
        </example></para>
    </sect1>

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

      <para>Version 1.18 införde inledande stöd för markdown. Att använda markdown i dokumentationskommentarer är mindre påträngande än att skriva docbook xml. Denna version förbättrar detta väsentligt och lägger till många fler stilar. Avsnittet som beskriver <link linkend="documenting_syntax">kommentarsyntax</link> finnas alla detaljer.</para>
    </sect1>

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

      <para>Makefilerna som skeppas med denna version genererar en entitetsfil vid namn <filename>xml/gtkdocentities.ent</filename> som innehåller entiteter för t.ex. package_name och package_version. Du kan använda detta för att t.ex. i filen main xml undvika att hårdkoda versionsnumret. Nedan finns ett exempel som visar hur entitetsfilen inkluderas i huvudmallen och hur entiteterna används. Entiteterna kan också användas i alla genererade filer, GTK-Doc kommer att använda samma xml-huvud i genererade xml-filer. <example><title>Att använda förgenererade entiteter</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; handbok&lt;/title&gt;
    &lt;releaseinfo&gt;
      för &amp;package_string;.
      Den senaste versionen av detta dokument kan hittas på nätet på
      &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>Dokumentera andra gränssnitt</title>

    <para>Så här långt har vi använt GTK-Doc för att dokumentera API:t för koden. Följande avsnitt innehåller förslag om hur verktyget kan användas för att också dokumentera andra gränssnitt.</para>

    <sect1 id="commandline-interfaces">
      <title>Kommandoradsflaggor och mansidor</title>

      <para>Då man också kan generera mansidor för ett docbook-refentry, låter det som en bra idé att använda det för detta ändamål. På detta sättet kommer gränssnittet att vara en del av referensen och man får mansidan gratis.</para>

      <sect2 id="commandline-interfaces-file">
        <title>Dokumentera verktyget</title>

        <para>Skapa en refentry-fil per verktyg. Om du följer <link linkend="settingup_docfiles">vårt exempel</link> borde vi kalla det <filename>meep/docs/reference/meeper/meep.xml</filename>. För xml-taggarna bör detta användas och man kan studera den genererade filen i xml-underkatalogen så väl som exempel i glib.</para>
      </sect2>

      <sect2 id="commandline-interfaces-configure">
        <title>Lägga till den extra configure-kontrollen</title>

        <para>
          <example><title>Lägga till extra configure-kontroller</title>
            <programlisting>
AC_ARG_ENABLE(man,
              [AC_HELP_STRING([--enable-man],
                              [omgenerera mansidor från Docbook [standardvärde=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>Lägga till de extra makefilsreglerna</title>

        <para>
          <example><title>Lägga till extra configure-kontroller</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>DBus-gränssnitt</title>

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

  </chapter>

  <chapter id="faq">
    <title>Frågor och svar</title>

    <segmentedlist>
      <?dbhtml list-presentation="list"?>
      <segtitle>Fråga</segtitle>
      <segtitle>Svar</segtitle>
      <seglistitem>
        <seg>Ingen klasshierarki.</seg>
        <seg>Objektens <function>xxx_get_type()</function>-funktion har inte matats in i filen <filename>&lt;paket&gt;.types</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Fortfarande ingen klasshierarki.</seg>
        <seg>Saknat eller fel namn i filen <filename>&lt;paket&gt;-sections.txt</filename> (se <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">förklaring</ulink>).</seg>
      </seglistitem>
      <seglistitem>
        <seg>Förbannat, jag har fortfarande ingen klasshierarki.</seg>
        <seg>Är objektnamnet (namnet på instansstrukturen, t.ex. <type>GtkWidget</type>) del av det normala avsnittet (stoppa inte detta i underavsnitt så som Standard eller Private).</seg>
      </seglistitem>
      <seglistitem>
        <seg>Inget symbolindex.</seg>
        <seg>Innehåller <filename>&lt;paket&gt;-docs.{xml,sgml}</filename> ett index som inkluderar det genererade indexet med xi:include?</seg>
      </seglistitem>
      <seglistitem>
        <seg>Symboler är inte länkade till deras dokumentationsavsnitt.</seg>
        <seg>Använder dokumentationskommentaren korrekta taggar (har du lagt till #, % eller ())? Kontrollera om gtkdoc-fixxref varnar om oupplösbara korsreferenser.</seg>
      </seglistitem>
      <seglistitem>
        <seg>En ny klass dyker inte upp i dokumentationen.</seg>
        <seg>Är den nya sidan inkluderad med xi:include från <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>En ny symbol dyker inte upp i dokumentationen.</seg>
        <seg>Är dokumentationskommentaren korrekt formaterad. Leta efter stavfel i början av kommentaren. Kontrollera om gtkdoc-fixxref varnar om oupplösbara korsreferenser. Kontrollera om symbolen finns korrekt listad i <filename>&lt;paket&gt;-sections.txt</filename> i ett publikt avsnitt.</seg>
      </seglistitem>
      <seglistitem>
        <seg>En typ saknas från klasshierarkin.</seg>
        <seg>Om typen finns listad i <filename>&lt;paket&gt;.hierarchy</filename> men inte i <filename>xml/tree_index.sgml</filename>, dubbelkolla då att typen finns korrekt placerad i <filename>&lt;paket&gt;-sections.txt</filename>. Om typinstansen (t.ex. <type>GtkWidget</type>) inte visas eller är markerad privat kommer den inte att visas.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Jag får foldoc-länkar för alla gobject-noteringar.</seg>
        <seg>Kontrollera att <filename>xml/annotation-glossary.xml</filename> är inkluderad med xi:include från <filename>&lt;package&gt;-docs.{xml,sgml}</filename>.</seg>
      </seglistitem>

      <!-- gtk-doc warnings: -->
      <seglistitem>
        <seg>Parameter beskriven i kommentarsblock i källkoden men existerar inte</seg>
        <seg>Kontrollera om prototypen i huvudet har andra parameternamn än i källkoden.</seg>
      </seglistitem>

      <!-- docbook warnings: -->
      <seglistitem>
        <seg>multipla ”ID:n” för begränsat länkslut: XYZ</seg>
        <seg>Symbolen XYZ förekommer två gånger i filen <filename>&lt;paket&gt;-sections.txt</filename>.</seg>
      </seglistitem>
      <seglistitem>
        <seg>Elementtypnamn i namnrymd ”” påträffat i para, men ingen mall matchar.</seg>
        <seg/>
      </seglistitem>
    </segmentedlist>
  </chapter>

  <chapter id="contrib">
    <title>Verktyg relaterade till gtk-doc</title>

    <para>GtkDocPlugin - en insticksmodul för <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink>-integrering som lägger till API-dokumentation till en trac-webbplats och integrerar med trac-sökningen.</para>
    <para>Gtkdoc-depscan - ett verktyg (del av gtk-doc) för att kontrollera använda API mot since-taggar i API:t för att avgöra minsta version som krävs.</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>Version 1.1, mars 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>. Alla är tillåtna kopiera och distribuera ordagranna kopior av detta licensdokument, men att ändra det är ej tillåtet.</para>
    </legalnotice>
  </appendixinfo>
  <title>GNU Free Documentation License</title>

  <sect1 id="fdl-preamble">
    <title>0. BAKGRUND</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>Vi har utformat denna licens för att den skall användas för handböcker till fri programvara, eftersom fri programvara behöver fri dokumentation: ett fritt program bör ha en handbok som erbjuder samma friheter som programmet gör. Men denna licens är inte begränsad till programvaruhandböcker; den kan användas för vilket textverk som helst oavsett ämne eller huruvida det är en utgiven, tryckt bok. Vi rekommenderar denna licens huvudsakligen för alla verk vars syfte är instruktion eller referens.</para>
  </sect1>
  <sect1 id="fdl-section1">
    <title>1. TILLÄMPNINGSOMRÅDE OCH DEFINITIONER</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>Exempel på passande format för transparenta kopior innefattar ren ASCII utan markeringar, Texinfo indataformat, LaTeX indataformat, SGML eller XML som använder en publikt tillgänglig DTD, och standardenlig HTML, PostScript eller PDF utformat för mänsklig förändring. Opaka format innefattar Postscript, PDF, leverantörsspecifika format som bara kan läsas och editeras med leverantörsspecifika ordbehandlare, SGML eller XML för vilket DTD och/eller verktyg för behandling inte finns allmänt tillgängliga, och den maskingenererade HTML som produceras av vissa ordbehandlare enbart avsett som utdata.</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. ORDAGRANN KOPIERING</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>Du äger också låna ut kopior, under samma villkor som ovan, och du äger visa kopior offentligt.</para>
    </sect1>
    
  <sect1 id="fdl-section3">
    <title>3. OMFATTANDE KOPIERING</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>Om de obligatoriska texterna för något omslag är för omfattande för att rymmas i läsbart skick skall du placera de första (så många som får plats) på det egentliga omslaget, och fortsätta med resten på de direkt intilliggande sidorna.</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. FÖRÄNDRINGAR</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>A</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>B</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>D</title>
	  <para>
	    Preserve all the copyright notices of the <link linkend="fdl-document">Document</link>.
	  </para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>E</title>
	  <para>Lägga till en upphovsrättsklausul för dina förändringar angränsande till de andra upphovsrättsklausulerna.</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>G</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>Inkludera en oförändrad kopia av denna licens [Det är den engelska originalversionen som avses].</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>M</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>N</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. KOMBINERA DOKUMENT</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. SAMLINGAR AV DOKUMENT</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>Du äger lyfta ut ett dokument från en sådan samling, och sprida det enskilt under GNU Free Documentation License, förutsatt att du lägger till en kopia av denna licens [den engelska originalversionen] i det utlyfta dokumentet, och följer villkoren för ordagrann kopiering i denna licens för det utlyfta dokumentet i alla andra avseenden.</para>
    </sect1>
    
  <sect1 id="fdl-section7">
    <title>7. SAMMANSLAGNING MED OBEROENDE VERK</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. ÖVERSÄTTNING</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. UPPHÖRANDE</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. FRAMTIDA VERSIONER AV DENNA LICENS</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>TILLÄGG</title>
    <para>För att använda GNU Free Documentation License för ett dokument du har skrivit, inkludera en kopia av licensen [det engelska originalet] i dokumentet och placera följande copyrightklausul omedelbart efter titelsidan:</para>
    
    <blockquote>
      <para>Copyright © YEAR YOUR NAME.</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>
