# Handbok för GTK-Doc

1.24.1

Användarhandbok för utvecklare med användningsinstruktioner för GTK-Doc.

Chris Lyttle

     chris@wilddev.net

Dan Mueth

     d-mueth@uchicago.edu

Stefan Sauer (Kost)

     ensonic@users.sf.net

GTK-Doc-projektet

    gtk-doc-list@gnome.org

2000, 2005 Dan Mueth and Chris Lyttle
2007-2019 Stefan Sauer (Kost)

Tillstånd att kopiera, distribuera och/eller modifiera detta dokument ges under villkoren i GNU Free Documentation License, version 1.1 eller senare, utgivet av Free Software Foundation utan standardavsnitt och omslagstexter. En kopia av licensen finns inkluderad.

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.

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

## Introduktion

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

### Vad är GTK-Doc?

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 GTK+- och GNOME-biblioteken. Men det kan också användas för att dokumentera programkod.

### Hur fungerar GTK-Doc?

GTK-Doc fungerar så att det använder dokumentation för funktioner placerad inuti källkodsfilerna i speciellt formaterade kommentarsblock, eller dokumentation som lagts till i mallfilerna som GTK-Doc använder (notera dock att GTK-Doc endast kommer att dokumentera funktioner som deklarerats i huvudfiler; det kommer inte att producera utdata för statiska funktioner).

GTK-Doc består av ett antal python-skript som vart och ett utför olika steg i processen.

Det finns 5 huvudsteg i processen:

1. Skriva dokumentationen. Författaren fyller i källkodsfilerna med dokumentation för varje funktion, makro, struct eller union, o.s.v.

2. Samla ihop information om koden. gtkdoc-scan söker genom huvudfilerna för koden och letar efter deklarationer av funktioner, makron, uppräkningar, strukturer och unioner. Det skapar sedan filen `<module>-decl-list.txt` 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 `<module>-sections.txt`. 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 `<module>-decl.txt`. 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 `<module>-decl.txt` i `<module>-overrides.txt`.

   gtkdoc-scangobj 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.

   gtkdoc-scanobj bör inte användas längre. Det behövdes tidigare när GObject fortfarande var GtkObject inuti gtk+.

3. Generera XML och HTML/PDF. gtkdoc-mkdb förvandlar mallfilerna till XML-filer i underkatalogen `xml/`. Om källkoden innehåller dokumentation över funktioner 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.

   gtkdoc-mkhtml förvandlar XML-filer till HTML-filer i underkatalogen `html/`. På samma sätt förvandlar gtkdoc-mkpdf XML-filerna till ett PDF-dokument kallat `<package>.pdf`.

   Filer i `xml/`- och `html/`-katalogerna skrivs alltid över. Man bör aldrig redigera dem direkt.

4. Fixa korsreferenser mellan dokument. Efter att ha installerat HTML-filerna kan gtkdoc-fixxref 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. När tar-arkivet med källkod skapas för distribution, förvandlar gtkdoc-rebase 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 (i de fall där dokumentationen finns installerad).

### Hämta GTK-Doc

#### Krav

python 2/3 - huvudskripten är skrivna i python.

xsltproc - xslt-processorn från libxslt xmlsoft.org/XSLT/

docbook-xsl - docbook xsl-stilmallar sourceforge.net/projects/docbook/files/docbook-xsl

Endera av source-highlight, highlight eller vim - valfritt - används för syntaxfärgning av exempel

### Om GTK-Doc

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.

(FIXME)

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

### Om denna handbok

(FIXME)

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

## Projektkonfiguration

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:

- Förberedelse av katalogstrukturen och skapande av konfigurationsfiler som krävs för din GTK-Doc-dokumentation (se Att ställa in en skelettstruktur för dokumentation).

- 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 Autotools, CMake och vanliga Makefiler.

- Tillägg av GTK-Doc-specifika filer till versionshantering och att bestämma vilka filer som ska ignoreras (se Integrering med versionshanteringssystem).

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

### Att ställa in en skelettstruktur för dokumentation

En vanlig konvention är att placera dokumentation i en mapp kallad `docs` i toppnivåkatalogen för ditt projekt. Vi skiljer vanligen mellan referensdokumentation som är avsedd för utvecklare och en användarhandbok 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 `reference` handboken för slutanvändare i en mapp med namnet `help`. Enligt konventionen ovan skulle dokumentationen för vårt paket `libmeep` placeras i: `docs/reference/libmeep`. För paket med bara ett bibliotek eller program kan dokumentationen också placeras direkt i `docs/reference`. 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.

I avsnitten som följer kommer vi anta en katalogstruktur för vårt projekt meep som följer konventionerna ovan.

Exempel på katalogstruktur för projektet meep

    meep/
      docs/
        reference/  # referensdokumentation
          libmeep/
          meeper/
        help/       # valfritt: användarhandbok
          meeper/
      src/
        libmeep/
        meeper/

### Integrering med Autotools

Integrering av GTK-Doc i ett autotools-baserat byggsystem kräver följande steg:

- Säkerställ att gtkdocize körs en gång innan skriptet `configure`. Om skriptet `autogen.sh` finns tillgängligt, justera det så att det söker efter GTK-Doc och lägg till ett anrop till gtkdocize.

  Huvudsyftet med gtkdocize är att göra Makefilen `gtk-doc.make` och makrodefinitionsfilen `gtk-doc.m4` tillgängliga för byggsystemet, antingen genom att kopiera eller länka in dem i projektet.

- Lägg till de nödvändiga autoconf-makrona till `configure.ac` för att aktivera GTK-Doc i ditt byggsystem för att tillåta konfiguration av GTK-Doc via det genererade `configure`-skriptet.

  Bland andra med register flaggan `--enable-gtk-doc` med `configure`-skriptet.

- Skapa ett automake-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 `meeper` och `libmeep`.

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

#### Integrering med automake

Kopiera först `Makefile.am` från underkatalogen `examples` från gtkdoc-sources till ditt projekts referensdokumentationskatalog (t.ex. `docs/reference/<paket>`). En lokal kopia bör finnas tillgänglig under t.ex. `/usr/share/doc/gtk-doc-tools/examples/Makefile.am`. Om du har flera paket, repetera detta för vart och ett.

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

Exempelkatalogstruktur med `Makefiles.am`

    meep/
      docs/
        reference/  # referensdokumentation
          libmeep/
            Makefile.am
          meeper/
            Makefile.am
        help/       # valfritt: användarhandbok
          meeper/
      src/
        libmeep/
        meeper/

Härnäst behöver du anpassa de kopierade Makefilerna och tillhandahålla värden för de olika parametrarna i varje `Makefile.am`. 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 `<VERKTYGSNAMN>_OPTIONS` (t.ex. har verktyget gtkdoc-mkhtml en flagga med namnet `MKHTML_OPTIONS`). Alla verktygen har stöd för `--help` för att lista de flaggor som stöds.

Följande lista förklarar de mest relevanta flaggorna. Se `Makefile.am`-exemplet för ytterligare flaggor.

- `DOC_MODULE` används för att tillhandahålla namnet på paketet som dokumenteras (t.ex. `meeper` eller `libmeep`).

- `DOC_SOURCE_DIR` 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 `DOC_SOURCE_DIR=$(top_srcdir)/src` eller en underkatalog till den katalogen.

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

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

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

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

- `content_files` låter dig ange extrafiler som inkluderas av `$(DOC_MAIN_SGML_FILE)` (t.ex. `content_files=running.xml building.xml changes-2.0.xml`).

- `expand_content_files` låter dig ange filer där gtk-doc-förkortningar så som `#GtkWidget` expanderas (t.ex. `expand_content_files=running.xml`).

#### Integrering med autoconf

Integrering med autoconf ä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 `GTK_DOC_CHECK`-makrot till ditt `configure.ac`-skript. Detta registrerar flera konfigurationsflaggor för att aktivera GTK-Doc och låter dig ställa in standardargument för gtkdocize.

Säkerställ att makrot `GTK_DOC_CHECK` inte är indenterat. Makrot måste inledas på början av raden och får inte börja med blanktecken.

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

Minimal integrering med autoconf

    # rekommenderat: ställ in m4-katalog
    AC_CONFIG_MACRO_DIR(m4)
    # valfritt: registrera gtk-doc i configure
    GTK_DOC_CHECK([1.28])

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:

Integrering med valfritt gtk-doc-beroende

    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)
    ])

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

1. --with-html-dir=SÖKVÄG : sökväg till installerad dokumentation

2. --enable-gtk-doc : använd gtk-doc för att bygga dokumentation [standardvärde=no]

3. --enable-gtk-doc-html : bygg dokumentation i html-format [standardvärde=yes]

4. --enable-gtk-doc-pdf : bygg dokumentation i pdf-format [standardvärde=no]

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

Efter att alla ändringar i `configure.ac` är gjorda, uppdatera filen `configure`. Detta kan göras genom att köra om `autogen.sh`.

#### Integrering med autogen

De flesta projekt kommer att ha ett `autogen.sh`-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 gtkdocize som kan användas för att kopiera nödvändiga filer som behövs av Gtk-Doc till källkatalogen.

Det bör köras före autoreconf, autoheader, automake eller autoconf.

Köra gtkdocize från autogen.sh

    gtkdocize || exit 1

Köra gtkdocize villkorligt från autogen.sh

    GTKDOCIZE=$(which gtkdocize 2>/dev/null)
    if test $? -ne 0; then
      echo "Inget gtk-doc-stöd funnet. Du kan inte bygga dokumentationen."
    else
      $GTKDOCIZE || exit 1
    fi

När gtkdocize kör kopierar det `gtk-doc.make` till din projektrot (eller den katalog som anges med flaggan `--docdir`).

gtkdocize söker i ditt `configure.ac`-skript efter makrot `GTK_DOC_CHECK`. Makrot `GTK_DOC_CHECK` kan användas för att skicka extra argument till skriptet gtkdocize. den andra parametern i `GTK_DOC_CHECK`-makrot.

Alternativt kan ytterligare argument också skickas till gtkdocize via miljövariabeln `GTKDOCIZE_FLAGS`, eller genom att ange dem direkt till gtkdocize i `autogen.sh`.

#### Köra GTK-Doc från byggsystemet

Efter de tidigare stegen är det dags att köra bygget. Först måste vi köra om `autogen.sh`. Om detta skript kör configure åt dig, kan du ge det flaggan `--enable-gtk-doc`. Annars kör manuellt `configure` med denna flagga efteråt.

Den första körningen av make genererar flera extra filer i doc-katalogerna. De viktiga är `<paket>.types`, `<paket>-docs.xml` (tidigare .sgml), `<paket>-sections.txt`.

Att köra dokumentationsbygget

    ./autogen.sh --enable-gtk-doc
    make

Nu kan du peka din webbläsare till `docs/reference/<paket>/index.html`. 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 ytterligare filer och visar hur huvudmallen redigeras för att lägga till ytterligare kapitel och avsnitt till dina dokumentationsfiler.

### Integrering med CMake-byggsystem

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

Det följande exemplet visar hur du använder detta kommando.

Exempel på användning av GTK-Doc från CMake

    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})

### Integrering med vanliga makefiler eller andra byggsystem

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

Byggsteg för dokumentation

    DOC_MODULE=meep
    // källkod har ändrats
    gtkdoc-scan --module=$(DOC_MODULE) <källkodskatalog>
    gtkdoc-scangobj --module=$(DOC_MODULE)
    gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<källkodskatalog>
    // xml-filer har ändrats
    mkdir html
    cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
    gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html

Man kommer att behöva titta i `Makefile.am` och `gtk-doc.mak` för att plocka ut de extra flaggor som behövs.

### Integrering med versionshanteringssystem

Som en tumregel är det filerna du redigerar som bör versionshanteras. För typiska projekt är det följande filer: `<paket>.types`, `<paket>-docs.xml` (tidigare .sgml), `<paket>-sections.txt`, `Makefile.am`.

Filer i katalogerna `xml/` och `html/` bör inte versionshanteras. Detsamma gäller `.stamp`-filerna.

## Att dokumentera koden

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.

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.

GTK-Doc-kommentarsblock

    #ifndef __GTK_DOC_IGNORE__
    /* unparseable code here */
    #endif

Begränsningar

Notera att GTK-Doc har stöd för `#ifndef(__GTK_DOC_IGNORE__)` men inte `#if !defined(__GTK_DOC_IGNORE__)` eller andra kombinationer.

### Dokumentationskommentarer

En flerradskommentar som börjar med en extra ”*” markerar ett dokumentationsblock som kommer att hanteras av GTK-Doc-verktygen.

GTK-Doc-kommentarsblock

    /**
     * identifierare:
     * dokumentation …
     */

'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)

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).

När du dokumenterar kod, beskriv två aspekter:

- Vad är detta: Namnet på en klass eller en funktion kan ibland vara vilseledande för personer med annan bakgrund.

- Vad gör det: Berättar om vanliga användningsfall. Sätter det i relation med det andra API:t.

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.

- Använd funktion() för att referera till funktioner eller makron som tar argument.

- 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.

- Använd %konstant för att referera till en konstant, t.ex. %G_TRAVERSE_LEAFS.

- Använd #symbol för att referera till andra typer av symboler, t.ex. strukturer eller uppräkningar och makron som inte tar argument.

- Använd #Objekt::signal för att referera till en GObject-signal.

- Använd #Objekt:egenskap för att referera till en GObject-egenskap.

- 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.

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

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 Markdown. Ä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.

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.

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 `--xml-mode` (eller `--sgml-mode`) i variabeln MKDB_OPTIONS inuti `Makefile.am`.

GTK-Doc-kommentarsblock som använder Markdown

    /**
     * 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:
     * |[<!-- language="C" -->
     * GtkWidget *label = gtk_label_new ("Vackert!");
     * ]|
     */

Fler exempel på vilka markdown-taggar som stöds hittas i Referensen för GTK-dokumentationens markdown-syntax.

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.

### Dokumentationsavsnitt

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.

Kommentarsblock för avsnitt

    /**
     * SECTION:meepapp
     * @short_description: programklassen
     * @title: Meep-programmet
     * @section_id:
     * @see_also: #MeepSettings
     * @stability: Stable
     * @include: meep/app.h
     * @image: application.png
     *
     * Programklassen hanterar …
     */

SECTION:<namn>

  Namnet länkar till avsnittsdokumentationen för respektive del i filen `<paket>-sections.txt`. Namnet som anges här bör matcha taggen <FILE> i filen `<paket>-sections.txt`.

@short_description

  En enradsbeskrivning av avsnittet som senare kommer att visas efter länkar i innehållsförteckningen och lägst upp på avsnittssidan.

@title

  Avsnittstiteln är som standard <namn> från SECTION-deklarationen. Den kan åsidosättas med fältet @title.

@section_id

  Åsidosätter användningen av titeln som avsnittsidentifierare. För GObjects används <title> som ett section_id och för andra avsnitt är det <MODULE>-<title>.

@see_also

  En lista över symboler som är relaterade till detta avsnitt.

@stability

  En informell beskrivning över stabiliteten för detta API. Vi rekommenderar att använda en av dessa termer:

  - 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.

  - 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.

  - 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.

  - 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.

@include

  `#include`-filerna som ska visas i avsnittssammanfattningen (en kommaavgränsad lista), vilket åsidosätter det globala värdet från avsnittsfilen eller kommandoraden. Detta objekt är valfritt.

@image

  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.

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

### Dokumentationssymboler

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.

#### Generella taggar

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

Versioneringstaggar

Since:

  Beskrivning över från och med vilken version av koden som API:t är tillgängligt.

Deprecated:

  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.

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.

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

Stabilitetstaggar

Stability: Stable

  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.

Stability: Unstable

  Markera elementet som instabilt. Detta är för publika API:er som är släppta på förhand innan de blivit stabiliserade.

Stability: Private

  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.

Generella taggar

    /**
     * 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() istället.
     */
    Bar *
    foo_get_bar(Foo *foo)
    {
    …

#### Noteringar

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 på wikisidan.

Noteringar

    /**
     * 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.
     */

#### Kommentarsblock för funktioner

Kom ihåg att:

- Dokumentera huruvida returnerade objekt, listor, strängar, etc. bör frigöras/avrefereras/släppas.

- Dokumentera huruvida parametrar tillåts vara NULL och vad som händer om de är NULL.

- Nämn intressanta förvillkor och eftervillkor där lämpligt.

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.

Kommentarsblock för funktioner

    /**
     * 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() istället.
     */

Funktions-taggar

Returns:

  Stycke som beskriver det returnerade resultatet.

@...:

  Om funktionen har variadiska argument bör du använda denna tagg (@Varargs: fungerar också på grund av historiska skäl).

#### Kommentarsblock för egenskaper

Kommentarsblock för egenskaper

    /**
     * EnKomponent:en-egenskap:
     *
     * Här kan du dokumentera en egenskap.
     */
    g_object_class_install_property (object_class, PROP_EN_EGENSKAP, …);

#### Kommentarsblock för signaler

Kom ihåg att:

- Dokumentera när en signal sänds ut och huruvida den sänds ut före eller efter andra signaler.

- Dokumentera vad ett program kan göra i signalhanteraren.

Kommentarsblock för signaler

    /**
     * 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",
                    ...

#### Kommentarsblock för strukturer

Kommentarsblock för strukturer

    /**
     * FooWidget:
     * @bar: någon #gboolean
     *
     * Detta är den bästa komponenten någonsin.
     */
    typedef struct _FooWidget {
      GtkWidget parent_instance;

      gboolean bar;
    } FooWidget;

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

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.

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).

#### Kommentarsblock för uppräkningar

Kommentarsblock för uppräkningar

    /**
     * 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,
      /*< private >*/
      SOMETHING_COUNT
    } Something;

Använd `/*< private >*/` före privata uppräkningsvärden som du vill gömma. Använd `/*< public >*/` för det omvända beteendet.

### Infogad programdokumentation

Du kan dokumentera program och deras kommandoradsgränssnitt med infogad dokumentation.

Taggar

PROGRAM

  Definierar början av programdokumentationen.

@short_description:

  Definierar en kort beskrivning av programmet. (Valfritt)

@synopsis:

  Definierar argumenten, eller en lista av argument som programmet kan ta. (Valfritt)

@see_also:

  Se vidare i manualavsnitt. (Valfritt)

@arg:

  Argument som skickas vidare till programmet och deras beskrivningar. (Valfritt)

Beskrivning:

  En längre beskrivning av programmet.

Returns:

  Ange vilka värden programmet returnerar. (Valfritt)

#### Exempel på programdokumentation.

Dokumentationsblock för program

    /**
     * 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;
    }

### Användbara DocBook-taggar

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

För att länka till ett annat avsnitt i GTK-dokumentationen:

    <link linkend="glib-Hash-Tables">Hashtabeller</link>

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.

För att referera till en extern funktion, t.ex. en standardfunktion i C:

    <function>…</function>

För att inkludera exempelkod:

    <example>
      <title>Att använda en GHashTable.</title>
      <programlisting language="C">
          ...
      </programlisting>
    </example>

eller möjligen följande, för väldigt korta kodfragment som inte behöver en titel:

    <informalexample>
      <programlisting language="C">
      ...
      </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:

    |[<!-- language="C" -->
      ...
    ]|

För att inkludera punktlistor:

    <itemizedlist>
      <listitem>
        <para>
          …
        </para>
      </listitem>
      <listitem>
        <para>
          …
        </para>
      </listitem>
    </itemizedlist>

För att inkludera en not som skiljer sig från texten:

    <note>
      <para>
        Säkerställ att du frigjort data efter användning.
      </para>
    </note>

För att refera till en typ:

    <type>unsigned char</type>

För att referera till en extern struktur (som inte beskrivs i GTK-dokumentationen):

    <structname>XFontStruct</structname>

För att referera till ett fält för en struktur:

    <structfield>len</structfield>

För att referera till ett klassnamn kan vi möjligen använda:

    <classname>GtkWidget</classname>

men du kommer troligt att använda #GtkWidget istället (för att automatiskt skapa en länk till GtkWidget-sidan - se förkortningarna).

För att betona text:

    <emphasis>Detta är viktigt</emphasis>

För filnamn använd:

    <filename>/home/användare/dokument</filename>

För att referera till tangenter använd:

    <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>

## Fylla i de extra filerna

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

### Redigera typfilen

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 `xxx_get_type`-funktionerna tillsammans med deras huvudfil i filen `<paket>.types`.

Exempel på filen <paket>.types

    #include <gtk/gtk.h>

    gtk_accel_label_get_type
    gtk_adjustment_get_type
    gtk_alignment_get_type
    gtk_arrow_get_type

Sedan GTK-Doc 1.8 kan gtkdoc-scan generera denna lista åt dig. Lägg bara till ”--rebuild-types” i SCAN_OPTIONS i `Makefile.am`. Om du använder detta tillvägagångssätt bör du inte distribuera typfilen eller versionshantera den.

### Redigera huvuddokumentet

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.

Ä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.

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.

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.

Huvuddokumentets huvud

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

    <chapter>
      <title>[Infoga titel här]</title>

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

Valfri del i huvuddokumentet

      <!-- aktivera detta om du vill använda gobject introspection-noteringar
      <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
      -->

Slutligen behöver du lägga till ett nytt avsnitt när du infogar det. Verktyget gtkdoc-check kommer att påminna dig om nyligen genererade xml-filer som ännu inte infogats i dokumentationen.

Inkludera genererade avsnitt

      <chapter>
        <title>mitt bibliotek</title>
          <xi:include href="xml/object.xml"/>
          ...

### Redigera avsnittsfilen

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).

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

Även om taggarna får filen att se ut som xml, är det inte det. Avsluta inte taggar så som <SUBSECTION>.

Inkludera genererade avsnitt

    <INCLUDE>libmeep/meep.h</INCLUDE>

    <SECTION>
    <FILE>meepapp</FILE>
    <TITLE>MeepApp</TITLE>
    MeepApp
    <SUBSECTION Standard>
    MEEP_APP
    ...
    MeepAppClass
    meep_app_get_type
    </SECTION>

Taggen <FILE> … </FILE> används för att ange filnamnet, utan något suffix. Om man t.ex. använder ”<FILE>gnome-config</FILE>” blir resultatet att avsnittsdeklarationerna matas ut i mallfilen `tmpl/gnome-config.sgml`, som kommer att konverteras till DocBook XML-filen `xml/gnome-config.sgml` eller DocBook XML-filen `xml/gnome-config.xml`. (Namnet på HTML-filen baseras på modulnamnet och avsnittstiteln, för GObject baseras det på klassnamnet för GObjectet konverterat till gemener).

Taggen <TITLE> … </TITLE> 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.

Du kan gruppera objekt i avsnittet genom att använda taggen <SUBSECTION>. För närvarande matas en blankrad ut mellan underavsnitt i sammanfattningsavsnittet. Du kan också använda <SUBSECTION Standard> 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 <SUBSECTION Private> 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).

Du kan också använda <INCLUDE> ... </INCLUDE> 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.

## Kontrollera resultatet

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

Filen `<paket>-undocumented.txt` 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.

Filen `<paket>-undeclared.txt` listar symboler som anges i `<paket>-sections.txt` men inte hittas i källkoden. Kontrollera om de har tagits bort eller om de är felstavade.

Filen `<paket>-unused.txt` 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 `<package>-sections.txt`.

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

Man kan också titta på filerna som producerats av källkodsdetektorn: `<paket>-decl-list.txt` och `<paket>-decl.txt`. 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.

Om projektet är GObject-baserat kan man också titta på filerna som producerats av objekt-detektorn: `<paket>.args.txt`, `<paket>.hierarchy.txt`, `<paket>.interfaces.txt`, `<paket>.prerequisites.txt` och `<paket>.signals.txt`. 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 `GTK_DOC_KEEP_INTERMEDIATE=1 make`.

## Modernisera dokumentationen

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

### GTK-Doc 1.9

När man använder xml istället för sgml, kan man faktiskt kalla huvuddokumentet `<paket>-docs.xml`.

Denna version har stöd för `SCAN_OPTIONS=--rebuild-sections` i `Makefile.am`. När detta är aktiverat kommer `<paket>-sections.txt` 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 `meld <paket>-decl-list.txt <paket>-sections.txt`.

Redan version 1.8 introducerade syntaxen för avsnittsdokumentation i källkoden istället för separata filer under `tmpl`. 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 `--flavour no-tmpl` i `configure.ac`. Om du inte har `tmpl` incheckat i ditt versionshanteringssystem just nu och inte har gått över än bara lägg till flaggan i `configure.ac` så är du klar.

### GTK-Doc 1.10

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

### GTK-Doc 1.16

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 `Makefile.am`.

Aktivera gtkdoc-check

    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

### GTK-Doc 1.20

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 kommentarsyntax finnas alla detaljer.

### GTK-Doc 1.25

Makefilerna som skeppas med denna version genererar en entitetsfil vid namn `xml/gtkdocentities.ent` 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.

Att använda förgenererade entiteter

    <?xml version="1.0"?>
    <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
    [
      <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
      <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
      %gtkdocentities;
    ]>
    <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
      <bookinfo>
        <title>&package_name; handbok</title>
        <releaseinfo>
          för &package_string;.
          Den senaste versionen av detta dokument kan hittas på nätet på
          <ulink role="online-location" url="http://[SERVER]/&package_name;/index.html">http://[SERVER]/&package_name;/</ulink>.
        </releaseinfo>
      </bookinfo>

## Dokumentera andra gränssnitt

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.

### Kommandoradsflaggor och mansidor

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.

#### Dokumentera verktyget

Skapa en refentry-fil per verktyg. Om du följer vårt exempel borde vi kalla det `meep/docs/reference/meeper/meep.xml`. 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.

#### Lägga till den extra configure-kontrollen

Lägga till extra configure-kontroller

    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)

#### Lägga till de extra makefilsreglerna

Lägga till extra configure-kontroller

    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 $<

    endif
    endif

    BUILT_EXTRA_DIST = $(man_MANS)
    EXTRA_DIST += meep.xml

### DBus-gränssnitt

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

## Frågor och svar

Fråga Svar
- Ingen klasshierarki. Objektens `xxx_get_type()`-funktion har inte matats in i filen `<paket>.types`.
- Fortfarande ingen klasshierarki. Saknat eller fel namn i filen `<paket>-sections.txt` (se förklaring).
- Förbannat, jag har fortfarande ingen klasshierarki. Är objektnamnet (namnet på instansstrukturen, t.ex. GtkWidget) del av det normala avsnittet (stoppa inte detta i underavsnitt så som Standard eller Private).
- Inget symbolindex. Innehåller `<paket>-docs.{xml,sgml}` ett index som inkluderar det genererade indexet med xi:include?
- Symboler är inte länkade till deras dokumentationsavsnitt. Använder dokumentationskommentaren korrekta taggar (har du lagt till #, % eller ())? Kontrollera om gtkdoc-fixxref varnar om oupplösbara korsreferenser.
- En ny klass dyker inte upp i dokumentationen. Är den nya sidan inkluderad med xi:include från `<package>-docs.{xml,sgml}`.
- En ny symbol dyker inte upp i dokumentationen. Ä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 `<paket>-sections.txt` i ett publikt avsnitt.
- En typ saknas från klasshierarkin. Om typen finns listad i `<paket>.hierarchy` men inte i `xml/tree_index.sgml`, dubbelkolla då att typen finns korrekt placerad i `<paket>-sections.txt`. Om typinstansen (t.ex. GtkWidget) inte visas eller är markerad privat kommer den inte att visas.
- Jag får foldoc-länkar för alla gobject-noteringar. Kontrollera att `xml/annotation-glossary.xml` är inkluderad med xi:include från `<package>-docs.{xml,sgml}`.
- Parameter beskriven i kommentarsblock i källkoden men existerar inte Kontrollera om prototypen i huvudet har andra parameternamn än i källkoden.
- multipla ”ID:n” för begränsat länkslut: XYZ Symbolen XYZ förekommer två gånger i filen `<paket>-sections.txt`.
- Elementtypnamn i namnrymd ”” påträffat i para, men ingen mall matchar.

## Verktyg relaterade till gtk-doc

GtkDocPlugin - en insticksmodul för Trac GTK-Doc-integrering som lägger till API-dokumentation till en trac-webbplats och integrerar med trac-sökningen.

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.

Version 1.1, mars 2000
2000 Free Software Foundation, Inc.

    Free Software Foundation, Inc. 51 Franklin Street,
            Suite 330, Boston, MA
            02110-1301  USA

. Alla är tillåtna kopiera och distribuera ordagranna kopior av detta licensdokument, men att ändra det är ej tillåtet.

## GNU Free Documentation License

### 0. BAKGRUND

Syftet med denna licens är att göra en handbok, bok, eller annat praktiskt och användbart dokument fritt som i frihet: att försäkra var och en den faktiska friheten att kopiera och sprida det vidare, med eller utan förändringar, antingen kommersiellt eller ideellt. Sekundärt bevarar denna licens ett sätt för författaren och förläggaren att få ära för deras arbete utan att de anses vara ansvariga för förändringar gjorda av andra.

Denna Licens är en sorts copyleft, vilket betyder att derivativa verk av detta dokument själva måste vara fria på samma sätt. Den kompletterar GNU General Public License, som är en copyleft-licens utformad för fri programvara.

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.

### 1. TILLÄMPNINGSOMRÅDE OCH DEFINITIONER

Denna licens [det engelska originalet] gäller för varje handbok eller annat verk, oavsett uttrycksform, som innehåller ett meddelande där upphovsrättsinnehavaren stadgat att verket kan spridas enligt villkoren i GNU Free Documentation License. Ett sådant meddelande ger en internationell frihet utan krav på ersättning och utan tidsbegränsning att använda verket under villkoren i denna licens [det engelska originalet]. Dokument nedan syftar på godtycklig handbok eller verk. Var och en är licenstagare och benämns som du.

En förändrad version av dokumentet avser varje verk som innehåller dokumentet eller en del av det, antingen ordagranna kopior, eller med ändringar och/eller översatt till ett annat språk.

Ett sekundärt avsnitt är en märkt bilaga eller förord till dokumentet som exklusivt behandlar förhållandet mellan dokumentets förläggare eller författare och dokumentets huvudsakliga ämne (eller till relaterade ämnen) och som inte innehåller något som direkt faller under det huvudsakliga ämnet. (Således, om dokumentet delvis är en lärobok i matematik så får ett sekundärt avsnitt inte förklara någon matematik.) Förhållandet kan vara en historisk koppling till ämnet eller något relaterat, eller en juridisk, kommersiell, filosofisk, etisk eller politisk ställning till det.

De oföränderliga avsnitten är sekundära avsnitt vars titlar är angivna som oföränderliga avsnitt i meddelandet som stadgar att dokumentet är utgivet under denna licens [det engelska originalet].

Omslagstexterna är speciella korta ordföljder som är listade som framsidestexter eller baksidestexter i meddelandet som stadgar att dokumentet är utgivet under denna licens [det engelska originalet].

En transparent kopia av dokumentet är en maskinläsbar kopia, representerad i ett format vars specifikation finns tillgänglig för allmänheten, som lämpar sig för att revidera dokumentet på ett enkelt sätt med generella textredigeringsprogram eller (för pixelbaserade bilder) generella grafikprogram eller (för ritningar) något väl tillgängligt ritprogram, och som är passande som indata till textformaterare eller för automatisk konvertering till en mängd format som passar som indata till textformaterare. En kopia i ett för övrigt transparent filformat vars markeringar, eller avsaknad av markeringar, har ordnats för att hindra eller motverka att vidare förändring vidtas av läsare är inte transparent. En kopia som inte är transparent kallas opak.

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.

Titelsidan innebär, för en tryckt bok, titelsidan själv, och sådana därpå följande sidor som krävs för att göra det material som enligt denna licens skall synas på titelsidan läsbart. För verk i sådana format som inte har någon egentlig titelsida, avses med titelsida den text som är närmast den mest framstående förekomsten av verkets titel, föregående den huvudsakliga textmassan.

### 2. ORDAGRANN KOPIERING

Du äger kopiera och sprida dokumentet på valfritt medium, antingen kommersiellt eller ideellt, förutsatt att denna licens [det engelska originalet], upphovsrättsklausul, och meddelandet som stadgar att GNU Free Documentation License gäller för dokumentet finns med på alla kopior, och att du inte lägger till några som helst andra villkor än de som ingår i denna licens. Du äger inte vidta tekniska åtgärder för att begränsa eller kontrollera läsande eller vidare kopiering av de kopior du skapar eller sprider. Dock äger du ta emot kompensation i utbyte mot kopior. Om du sprider tillräckligt många kopior måste du också följa villkoren i paragraf 3.

Du äger också låna ut kopior, under samma villkor som ovan, och du äger visa kopior offentligt.

### 3. OMFATTANDE KOPIERING

Om du publicerar tryckta kopior (eller kopior i medier som normalt har tryckta omslag) av dokumentet, i en upplaga överstigande 100 exemplar, och dokumentets licensmeddelande kräver omslagstexter, så måste du förse kopiorna med omslag som, klart och tydligt, visar alla omslagstexter: framsidestexter på framsidan och baksidestexter på baksidan. Båda omslagen måste klart och tydligt identifiera dig som utgivare av dessa kopior. Framsidan måste presentera dokumentets hela titel, med alla ord i titeln lika framträdande och synliga. Du äger lägga till ytterligare stoff på omslagen. Kopiering med förändringar gjorda bara på omslaget, så länge som de bevarar dokumentets titel och i övrigt uppfyller dessa krav kan anses vara ordagrann kopiering i andra avseenden.

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.

Om du publicerar opaka kopior av dokumentet i upplagor om mer än 100, måste du antingen bifoga en maskinläsbar transparent kopia med varje opak kopia, eller ange i eller med varje opak kopia en nätverksadress som är tillgänglig för den allmänna nätverksanvändande massan där man, med öppet standardiserade protokoll, anonymt och utan kostnad kan ladda ner en komplett transparent kopia av dokumentet, utan extra material. Om du väljer det senare alternativet, måste du vidta skäliga åtgärder, när du börjar sprida opaka kopior i kvantitet, för att denna transparenta kopia skall förbli tillgänglig på angivna platsen till åtminstone ett år efter den sista gången du spred en opak kopia (direkt eller via ombud eller återförsäljare) av den utgåvan till allmänheten.

Det är önskvärt, men inte ett krav, att du kontaktar författarna till dokumentet i god tid innan du sprider något större antal kopior, för att ge dem en chans att förse dig med en uppdaterad version av dokumentet.

### 4. FÖRÄNDRINGAR

Du äger kopiera och sprida en förändrad version av dokumentet under de villkor som beskrivs i paragraf 2 och 3 av GNU Free Documentation License, förutsatt att du släpper den förändrade versionen under exakt denna licens, och att den förändrade versionen antar dokumentets roll, och således medger spridning och förändring av den förändrade versionen till envar som erhåller en kopia av den. Utöver detta måste du göra följande med den ändrade versionen:

- A

  På titelsidan (och omslagen om det finns några) använda en titel skild från den som [original]dokumentet har, och skild från tidigare versioners titel (som skall, om det finns några, finnas listade i historikavsnittet i dokumentet). Du äger använda samma titel som det föregående dokumentet om den ursprungliga utgivaren ger sitt tillstånd.

- B

  Lista på titelsidan, som författare, en eller flera personer eller juridiska personer som ansvarat för förändringarna i den förändrade versionen, tillsammans med minst fem av de huvudsakliga författarna av dokumentet (alla dess huvudsakliga författare, om det har mindre än fem).

- C

  Ange namnet på utgivaren av den förändrade versionen, som utgivare, på titelsidan.

- D

  Bibehålla dokumentets alla upphovsrättsklausuler.

- E

  Lägga till en upphovsrättsklausul för dina förändringar angränsande till de andra upphovsrättsklausulerna.

- F

  Direkt efter upphovsrättsklausulerna innefatta ett meddelande som ger allmänheten tillstånd att använda den förändrade versionen under villkoren i denna licens [det engelska originalet] i den form som visas i Tillägg nedan.

- G

  I meddelandet om licensen bevara den fullständiga listan över oföränderliga avsnitt och obligatoriska omslagstexter som finns i dokumentets meddelande om licensen.

- H

  Inkludera en oförändrad kopia av denna licens [Det är den engelska originalversionen som avses].

- I

  Bevara avsnittet med titeln historik (History), bevara dess titel och lägg i avsnittet till en post med åtminstone titeln, året, nya författare och utgivaren av den förändrade versionen så som angivet på titelsidan. Om det inte finns något avsnitt med titeln historik (History) i dokumentet så skapa en med titeln, året, författare och utgivaren av dokumentet så som det står på [original]dokumentets titelsida. Lägg sedan till en post som beskriver den förändrade versionen så som beskrivits ovan.

- J

  Bevara den nätverksadress, om det finns någon, angiven i dokumentet till den allmänt tillgängliga transparenta kopian av dokumentet, och likaså nätverksadresserna till de föregående versioner som dokumentet baseras på. Dessa får placeras i avsnittet historik (History). Du äger utelämna en nätverksadress för ett verk som är publicerat mer än fyra år före dokumentet självt, eller om den ursprunglige utgivaren vars verk nätverksadressen hänvisar till ger sitt tillstånd.

- K

  För alla avsnitt med titlarna tillkännagivanden (Acknowledgements) eller dedikationer (Dedications), bevara titeln på avsnittet, och bevara allt innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda av varje bidragsgivare.

- L

  Bevara alla oföränderliga avsnitt i dokumentet oförändrade till text och titel. Avsnittsnummer eller motsvarande anses inte tillhöra avsnittets titel.

- M

  Radera varje avsnitt med titeln endossering (Endorsements). Ett sådant avsnitt får inte inkluderas i en förändrad version.

- N

  Inte byta titel på något existerande avsnitt så att det blir endossering (Endorsements) eller så att titeln kan förväxlas med något oföränderligt avsnitt.

Om den förändrade versionen innehåller nya framsidestexter eller bilagor som är att anses som sekundära avsnitt och inte innehåller något material kopierat från dokumentet, så äger du, om du vill, benämna några eller samtliga av dessa som oföränderliga. För att göra detta, lägg deras titlar till listan över oföränderliga avsnitt i den förändrade versionens licensmeddelande. Dessa titlar måste vara skilda från alla andra avsnitts titlar.

Du äger lägga till ett avsnitt med titeln endossering (Endorsements), förutsatt att det inte innehåller något annat än endosseringar för din förändrade version från olika aktörer -- till exempel, meddelanden om utförd korrekturläsning eller att texten har godkänts av en organisation som en officiell definition av en standard.

Du äger lägga till ett textavsnitt på upp till fem ord som framsidestext, och ett textavsnitt på upp till 25 ord som baksidestext i listan över omslagstexter i den förändrade versionen. Bara ett textavsnitt med framsidestexter och ett med baksidestexter får läggas till av (eller genom försorg av) en enda juridisk person. Om dokumentet redan innehåller en omslagstext för något av omslagen, tidigare tillagd av dig eller genom försorg av samma juridiska person som du företräder, äger du inte lägga till en till, men du äger ändra den gamla med tillstånd från den tidigare utgivaren som lade till den förra.

Författaren (författarna) och utgivaren (utgivarna) av dokumentet ger inte via denna licens sitt tillstånd att använda sina namn för publicitet eller för att lägga till eller antyda endossering av någon förändrad version.

### 5. KOMBINERA DOKUMENT

Du äger kombinera dokumentet med andra dokument som är utgivna under denna licens, under de villkor som definieras i paragraf 4 av GNU Free Documentation License för förändrade versioner, förutsatt att du, i det kombinerade dokumentet, innefattar alla oföränderliga avsnitt från originaldokumenten, omodifierade, och listar dem som oföränderliga avsnitt i ditt kombinerade verk i dess licensklausul, och att du bevarar alla deras garantiavsägelseklausuler.

Det kombinerade verket behöver bara innehålla en enstaka kopia av denna licens [engelska originalversionen], och flera identiska oföränderliga stycken kan ersättas med en kopia. Om det finns flera oföränderliga stycken med samma namn men olika innehåll, se till att titeln på varje sådant avsnitt är unik genom att i slutet på den, inom parentes, lägga till namnet på den ursprunglige författaren eller utgivaren av det avsnittet om dessa är kända, annars ett unikt nummer. Gör samma justeringar av titlarna i listan över oföränderliga avsnitt i licensklausulen i det kombinerade verket.

I det kombinerade verket måste du kombinera alla avsnitt med titlarna historik (History) i de ursprungliga dokumenten, till ett avsnitt med titeln historik (History); på samma sätt skall alla avsnitt med titlarna tillkännagivanden (Acknowledgements), alla avsnitt med titlarna dedikationer (Dedications) kombineras. Du måste ta bort alla avsnitt med titlarna endossering (Endorsements).

### 6. SAMLINGAR AV DOKUMENT

Du äger skapa en samling bestående av dokumentet och andra dokument som är släppta under GNU Free Documentation License, och ersätta individuella kopior i dokumenten av denna licens med en enda kopia [av den engelska originalversionen] som inkluderas i samlingen, förutsatt att du följer villkoren för ordagrann kopiering i denna licens för varje inkluderat dokument i alla andra avseenden.

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.

### 7. SAMMANSLAGNING MED OBEROENDE VERK

En samling av dokumentet eller av dess derivat med andra separata och oberoende dokument eller verk, på eller i en lagringsvolym eller ett spridningsmedium, kallas för en sammanslagning om den sammanslagna upphovsrätten inte används för att begränsa samlingens användares rättigheter som de enskilda dokumenten medger. När dokumentet ingår i en sådan sammanslagning, gäller inte denna licens de andra verken i samlingen som inte själva är deriverat av dokumentet. Om kravet på omslagstexter enligt paragraf 3 är tillämpligt på dessa kopior av dokumentet, så kan dokumentets omslagstexter, om dokumentet utgör mindre än en fjärdedel av hela samlingen, placeras på det omslag som omger dokumentet inuti samlingen, eller den elektroniska motsvarigheten till omslag om dokumentet är i elektronisk form. Annars måste de synas på det omslag som omger hela samlingen.

### 8. ÖVERSÄTTNING

Översättning anses vara en sorts förändring, så du äger sprida översättningar av dokumentet enligt de villkor som sätts i paragraf 4. Oföränderliga avsnitt som ersätts med översättningar kräver tillstånd från deras upphovsrättsinnehavare, men du äger inkludera översättningar av alla eller vissa av dessa oföränderliga avsnitt tillsammans med originalversionerna av dessa oföränderliga avsnitt. Du äger inkludera en översättning av denna licens, och alla licensklausuler i dokumentet, och alla garantiavsägelser, förutsatt att du också innefattar den engelska originalversionen av denna licens och originalversionerna av dessa klausuler. Skulle det finnas skillnader mellan översättningen och originalversionen av denna licens eller någon klausul så gäller originalversionen.

### 9. UPPHÖRANDE

Du äger inte kopiera, förändra, omlicensiera eller sprida dokumentet annat än enligt villkoren i GNU Free Documentation License. Alla övriga försök att kopiera, modifiera, omlicensiera, eller sprida dokumentet är ogiltiga och kommer automatiskt medföra att du förlorar dina rättigheter enligt denna licens. Tredje man som har mottagit kopior eller rättigheter från dig enligt dessa licensvillkor kommer dock inte att förlora sina rättigheter så länge de följer licensvillkoren.

### 10. FRAMTIDA VERSIONER AV DENNA LICENS

Free Software Foundation kan publicera nya, reviderade versioner av GNU Free Documentation License då och då. Sådana nya versioner kommer att vara likadana i andemening som den nuvarande versionen, men kan skilja i detalj för att behandla nya problem eller angelägenheter. Se http://www.gnu.org/copyleft/.

Varje version av licensen ges ett unikt versionsnummer. Om dokumentet stadgar att en specifik numrerad version av denna licens eller valfri senare version gäller för det, så äger du rätten att följa villkoren enligt antingen den angivna versionen eller vilken senare version som helst som publicerats (inte som utkast) av Free Software Foundation. Om dokumentet inte anger en version av denna licens, äger du välja vilken version som helst som publicerats (inte som utkast) av Free Software Foundation.

### TILLÄGG

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:

> Copyright © YEAR YOUR NAME.

> 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 Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled GNU Free Documentation License.

Om du inte har några oföränderliga avsnitt, skriv with no Invariant Sections istället för att ange vilka som är oföränderliga. Om du inte har några framsidestexter, skriv no Front-Cover Texts istället för Front-Cover Texts being LIST; såväl som för baksidestexter.

Om ditt dokument innehåller icke-triviala exempel med programkod, så rekommenderar vi att du släpper dessa exempel parallellt under en, av dig vald, fri programvarulicens, som till exempel GNU General Public License, för att möjliggöra deras användning i fri programvara.