This file is indexed.

/usr/share/help/sv/gtk-doc-manual/index.docbook is in gtk-doc-tools 1.27-3.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
<?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-2015</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.27</revnumber>
         <date>07 Dec 2017</date>
         <authorinitials>ss</authorinitials>
         <revremark>fine tuning of the python port</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 GTK+- och GNOME-biblioteken. 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 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).</para>

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

      <para>Det finns 5 huvudsteg i processen:</para>

      <orderedlist>

        <listitem>
          <para><guilabel>Skriva dokumentationen.</guilabel> Författaren fyller i källkodsfilerna med dokumentation för varje funktion, makro, union, etc. (Tidigare matades informationen in i genererade mallfiler, något som inte rekommenderas längre).</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 ö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.</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. 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 (i de fall 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>(FIXME)</para>

      <para>(Historia, 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>Att ställa in ditt projekt</title>

    <para>De följande avsnitten beskriver vilka steg du måste utföra för att integrera GTK-Doc i ditt projekt. Dessa avsnitt förutsätter att vi arbetar på ett projekt kallat ”meep”. Detta projekt innehåller ett bibliotek kallat ”libmeep” och ett slutanvändarprogram kallat ”meeper”. Vi förutsätter också att du kommer att använda autoconf och automake. Dessutom kommer avsnittet <link linkend="plain_makefiles">vanliga makefiler eller andra byggsystem</link> att beskriva de grundläggande sakerna som behöver fungera i ett annat byggsystem.</para>

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

      <para>Under toppnivåkatalogen för ditt projekt, skapa mappar kallade docs/reference (på detta sättet kan du också ha docs/help för slutanvändardokumentation). Det rekommenderas att skapa en annan underkatalog med namnet på dokumentations-paketet. För paket med bara ett bibliotek är detta steg inte nödvändigt.</para>

      <para>Detta kan se ut enligt nedan: <example><title>Exempel på katalogstruktur</title>
          <programlisting>
meep/
  docs/
    reference/
      libmeep/
      meeper/
  src/
    libmeep/
    meeper/
</programlisting>
        </example></para>
    </sect1>

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

      <para>Väldigt enkelt! Bara lägg till en rad till ditt <filename>configure.ac</filename>-skript.</para>

      <para>
        <example><title>Integrering med autoconf</title>
          <programlisting>
# check for gtk-doc
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
</programlisting>
        </example>
      </para>

      <para>Detta kommer att kräva att alla utvecklare har gtk-doc installerat. Om det är okej för ditt projekt att ha ett valfritt api-dokumentation bygge, kan du lösa det enligt nedan. Behåll det som det är eftersom gtkdocize letar efter <function>GTK_DOC_CHECK</function> i början på en rad. <example><title>Låt gtk-doc vara valfritt</title>
          <programlisting>
# check for gtk-doc
m4_ifdef([GTK_DOC_CHECK], [
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])
</programlisting>
        </example></para>

      <para>Det första argumentet används för att leta efter gtkdoc-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>Vidare rekommenderas det att du har följande rad i ditt <filename>configure.ac</filename>-skript. Den låter <application>gtkdocize</application> automatiskt kopiera makrodefinitionen för <function>GTK_DOC_CHECK</function> till ditt projekt.</para>

      <para>
        <example><title>Förberedelse för gtkdocize</title>
          <programlisting>
AC_CONFIG_MACRO_DIR(m4)
</programlisting>
        </example>
      </para>
      <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>autoreconf -i</code> eller <code>autogen.sh</code>.</para>
    </sect1>

    <sect1 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://git.gnome.org/browse/gtk-doc/tree/examples/Makefile.am">gtkdoc-sources</ulink> till ditt projekts API-dokumentationskatalog ( <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 dok-paket, repetera detta för vart och ett.</para>

      <para>Nästa steg är att redigera inställningarna inuti <filename>Makefile.am</filename>. Alla inställningarna har en kommentar ovanför som beskriver deras syfte. De flesta inställningarna är extraflaggor som skickas till respektive verktyg. Varje verktyg har en variabel på formen <option>&lt;VERKTYGSNAMN&gt;_OPTIONS</option>. Alla verktygen har stöd för <option>--help</option> för att lista de parametrar som stöds.</para>

      <!-- FIXME: explain options ? -->

    </sect1>

    <sect1 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 cvs/svn/git). GTK-Doc tillhandahåller ett verktyg som heter <application>gtkdocize</application> som kan användas i ett sådant skript. Det bör köras före autoheader, automake eller autoconf.</para>

      <para>
        <example><title>Köra gtkdocize från autogen.sh</title>
          <programlisting>
gtkdocize || exit 1
</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>). Det kontrollerar också ditt configure-skript efter ett anrop till <function>GTK_DOC_CHECK</function>. Detta makro kan användas för att skicka extra parametrar till <application>gtkdocize</application>.</para>

      <para>Historiskt genererade GTK-Doc mallfiler i vilka utvecklare skrev in dokumentationen. Detta visade sig inte vara så bra (t.ex. på grund av behovet att ha genererade filer under versionskontroll). Sedan GTK-Doc 1.9 kan verktygen hämta all information från källkodskommentarer och mallar kan därför undvikas. Vi rekommenderar att hålla dokumentationen i koden. <application>gtkdocize</application> har nu stöd för flaggan <option>--flavour no-tmpl</option> som väljer en makefil som hoppar över tmpl-användning helt. Förutom att lägga till flaggan direkt vid körning av kommandot, kan den också läggas till i en miljövariabel kallad <symbol>GTKDOCIZE_FLAGS</symbol> eller inställd som en andra parameter i makrot <symbol>GTK_DOC_CHECK</symbol> i configure-skriptet. Om du inte har ändrat någon fil i tmpl för hand och migrerar från äldre gtkdoc-versioner, ta bort katalogen (t.ex. från versionshanteringssystemet).</para>
    </sect1>

    <sect1 id="settingup_firstrun">
      <title>Att köra dokumentationsbygget</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>Du kan nu peka din webbläsare till <filename>docs/reference/&lt;paket&gt;/index.html</filename>. Ja, den är fortfarande lite sorglig. Men häng kvar, i nästa kapitel kommer vi att berätta för dig hur du fyller sidorna med liv.</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>

    <sect1 id="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="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>
  </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>

    <note>
      <title>Dokumentationsplacering</title>
      <para>Tidigare var det tvunget att fylla i största delen av dokumentationen i filer som fanns i katalogen <filename>tmpl</filename>. Detta hade nackdelen att informationen ofta inte uppdaterades och att filen också ofta orsakade konflikter med versionshanteringssystem.</para>
      <para>För att undvika de nämnda problemen föreslår vi att placera dokumentationen i källkoden. Denna manual kommer endast att beskriva detta sättet att dokumentera kod.</para>
    </note>

    <para>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%2B/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 dessa symboler. Det hjälper andra att förstå din kod. Därför rekommenderar vi att du kommenterar dessa med normala kommenterar (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() istä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 som verktygstips 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å <ulink url="http://live.gnome.org/GObjectIntrospection/Annotations" type="http">wikisidan</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() istä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 hashtabell.&lt;/title&gt;
  &lt;programlisting&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&gt;&lt;/programlisting&gt;
&lt;/informalexample&gt;
</programlisting>
        </informalexample> För det senare fallet har GTK-Doc också stöd för förkortningen: |[ … ]|</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 istä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;package&gt;.types</filename>.</para>

      <para>
        <example><title>Exempel på typfilsnutt</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 istä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 istä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 och hur entiteter 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>Syftet med denna licens är att göra en handbok, bok, eller annat praktiskt och användbart dokument <quote>fritt</quote> 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.</para>
    
    <para>Denna Licens är en sorts <quote>copyleft</quote>, 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.</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">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]. <quote>Dokument</quote> nedan syftar på godtycklig handbok eller verk. Var och en är licenstagare och benämns som <quote>du</quote>.</para>
    
    <para id="fdl-modified">En <quote>förändrad version</quote> 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.</para>
	
    <para id="fdl-secondary">Ett <quote>sekundärt avsnitt</quote> är en märkt bilaga eller förord till <link linkend="fdl-document">dokumentet</link> 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.</para>

    <para id="fdl-invariant">De <quote>oföränderliga avsnitten</quote> är <link linkend="fdl-secondary">sekundära avsnitt</link> vars titlar är angivna som oföränderliga avsnitt i meddelandet som stadgar att <link linkend="fdl-document">dokumentet</link> är utgivet under denna licens [det engelska originalet].</para>
    
    <para id="fdl-cover-texts"><quote>Omslagstexterna</quote> är speciella korta ordföljder som är listade som framsidestexter eller baksidestexter i meddelandet som stadgar att <link linkend="fdl-document">dokumentet</link> är utgivet under denna licens [det engelska originalet].</para>
	
    <para id="fdl-transparent">En <quote>transparent</quote> kopia av <link linkend="fdl-document">dokumentet</link> ä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 <quote>transparent</quote> kallas <quote>opak</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"><quote>Titelsidan</quote> 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 <quote>titelsida</quote> den text som är närmast den mest framstående förekomsten av verkets titel, föregående den huvudsakliga textmassan.</para>
  </sect1>
    
  <sect1 id="fdl-section2">
    <title>2. ORDAGRANN KOPIERING</title>
    <para>Du äger kopiera och sprida <link linkend="fdl-document">dokumentet</link> 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 <link linkend="fdl-section3">paragraf 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>Om du publicerar tryckta kopior (eller kopior i medier som normalt har tryckta omslag) av <link linkend="fdl-document">dokumentet</link>, i en upplaga överstigande 100 exemplar, och dokumentets licensmeddelande kräver <link linkend="fdl-cover-texts">omslagstexter</link>, 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 <link linkend="fdl-document">dokumentets</link> titel och i övrigt uppfyller dessa krav kan anses vara ordagrann kopiering i andra avseenden.</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>Om du publicerar <link linkend="fdl-transparent">opaka</link> kopior av <link linkend="fdl-document">dokumentet</link> i upplagor om mer än 100, måste du antingen bifoga en maskinläsbar <link linkend="fdl-transparent">transparent</link> 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.</para>
    
    <para>Det är önskvärt, men inte ett krav, att du kontaktar författarna till <link linkend="fdl-document">dokumentet</link> 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.</para>
    </sect1>
    
  <sect1 id="fdl-section4">
    <title>4. FÖRÄNDRINGAR</title>
    <para>Du äger kopiera och sprida en <link linkend="fdl-modified">förändrad version</link> av <link linkend="fdl-document">dokumentet</link> under de villkor som beskrivs i paragraf <link linkend="fdl-section2">2</link> och <link linkend="fdl-section3">3</link> 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:</para>
    
    <itemizedlist mark="opencircle">
      <listitem>
	<formalpara>
	  <title>A</title>
	  <para><link linkend="fdl-title-page">titelsidan</link> (och omslagen om det finns några) använda en titel skild från den som [original]<link linkend="fdl-document">dokumentet</link> 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.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>B</title>
	  <para>Lista på <link linkend="fdl-title-page">titelsidan</link>, som författare, en eller flera personer eller juridiska personer som ansvarat för förändringarna i den <link linkend="fdl-modified">förändrade versionen</link>, tillsammans med minst fem av de huvudsakliga författarna av <link linkend="fdl-document">dokumentet</link> (alla dess huvudsakliga författare, om det har mindre än fem).</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>C</title>
	  <para>Ange namnet på utgivaren av den <link linkend="fdl-modified">förändrade versionen</link>, som utgivare, på <link linkend="fdl-title-page">titelsidan</link>.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>D</title>
	  <para>Bibehålla <link linkend="fdl-document">dokumentets</link> alla upphovsrättsklausuler.</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>Direkt efter upphovsrättsklausulerna innefatta ett meddelande som ger allmänheten tillstånd att använda den <link linkend="fdl-modified">förändrade versionen</link> under villkoren i denna licens [det engelska originalet] i den form som visas i Tillägg nedan.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>G</title>
	  <para>I meddelandet om licensen bevara den fullständiga listan över <link linkend="fdl-invariant">oföränderliga avsnitt</link> och obligatoriska <link linkend="fdl-cover-texts">omslagstexter</link> som finns i <link linkend="fdl-document">dokumentets</link> meddelande om licensen.</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>Bevara avsnittet med titeln <quote>historik</quote> (History), bevara dess titel och lägg i avsnittet till en post med åtminstone titeln, året, nya författare och utgivaren av den <link linkend="fdl-modified">förändrade versionen</link> så som angivet på <link linkend="fdl-title-page">titelsidan</link>. Om det inte finns något avsnitt med titeln <quote>historik</quote> (History) i <link linkend="fdl-document">dokumentet</link> 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.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>J</title>
	  <para>Bevara den nätverksadress, om det finns någon, angiven i <link linkend="fdl-document">dokumentet</link> till den allmänt tillgängliga <link linkend="fdl-transparent">transparenta</link> kopian av dokumentet, och likaså nätverksadresserna till de föregående versioner som dokumentet baseras på. Dessa får placeras i avsnittet <quote>historik</quote> (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.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>K</title>
	  <para>För alla avsnitt med titlarna <quote>tillkännagivanden</quote> (Acknowledgements) eller <quote>dedikationer</quote> (Dedications), bevara titeln på avsnittet, och bevara allt innehåll och prägel på alla tillkännagivanden och/eller dedikationer gjorda av varje bidragsgivare.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>L</title>
	  <para>Bevara alla <link linkend="fdl-invariant">oföränderliga avsnitt</link> i <link linkend="fdl-document">dokumentet</link> oförändrade till text och titel. Avsnittsnummer eller motsvarande anses inte tillhöra avsnittets titel.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>M</title>
	  <para>Radera varje avsnitt med titeln <quote>endossering</quote> (Endorsements). Ett sådant avsnitt får inte inkluderas i en <link linkend="fdl-modified">förändrad version</link>.</para>
	</formalpara>
      </listitem>
      
      <listitem>
	<formalpara>
	  <title>N</title>
	  <para>Inte byta titel på något existerande avsnitt så att det blir <quote>endossering</quote> (Endorsements) eller så att titeln kan förväxlas med något <link linkend="fdl-invariant">oföränderligt avsnitt</link>.</para>
	</formalpara>
      </listitem>
    </itemizedlist>
    
    <para>Om den <link linkend="fdl-modified">förändrade versionen</link> innehåller nya framsidestexter eller bilagor som är att anses som <link linkend="fdl-secondary">sekundära avsnitt</link> 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 <link linkend="fdl-invariant">oföränderliga avsnitt</link> i den förändrade versionens licensmeddelande. Dessa titlar måste vara skilda från alla andra avsnitts titlar.</para>
    
    <para>Du äger lägga till ett avsnitt med titeln <quote>endossering</quote> (Endorsements), förutsatt att det inte innehåller något annat än endosseringar för din <link linkend="fdl-modified">förändrade version</link> 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.</para>
    
    <para>Du äger lägga till ett textavsnitt på upp till fem ord som <link linkend="fdl-cover-texts">framsidestext</link>, och ett textavsnitt på upp till 25 ord som <link linkend="fdl-cover-texts">baksidestext</link> i listan över <link linkend="fdl-cover-texts">omslagstexter</link> i den <link linkend="fdl-modified">förändrade versionen</link>. 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 <link linkend="fdl-document">dokumentet</link> 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.</para>
    
    <para>Författaren (författarna) och utgivaren (utgivarna) av <link linkend="fdl-document">dokumentet</link> 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 <link linkend="fdl-modified">förändrad version</link>.</para>
  </sect1>
    
  <sect1 id="fdl-section5">
    <title>5. KOMBINERA DOKUMENT</title>
    <para>Du äger kombinera <link linkend="fdl-document">dokumentet</link> med andra dokument som är utgivna under denna licens, under de villkor som definieras i <link linkend="fdl-section4">paragraf 4</link> av GNU Free Documentation License för förändrade versioner, förutsatt att du, i det kombinerade dokumentet, innefattar alla <link linkend="fdl-invariant">oföränderliga avsnitt</link> 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.</para>
    
    <para>Det kombinerade verket behöver bara innehålla en enstaka kopia av denna licens [engelska originalversionen], och flera identiska <link linkend="fdl-invariant">oföränderliga stycken</link> 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.</para>
    
    <para>I det kombinerade verket måste du kombinera alla avsnitt med titlarna <quote>historik</quote> (History) i de ursprungliga dokumenten, till ett avsnitt med titeln <quote>historik</quote> (History); på samma sätt skall alla avsnitt med titlarna <quote>tillkännagivanden</quote> (Acknowledgements), alla avsnitt med titlarna <quote>dedikationer</quote> (Dedications) kombineras. Du måste ta bort alla avsnitt med titlarna <quote>endossering</quote> (Endorsements).</para>
    </sect1>
    
  <sect1 id="fdl-section6">
    <title>6. SAMLINGAR AV DOKUMENT</title>
    <para>Du äger skapa en samling bestående av <link linkend="fdl-document">dokumentet</link> 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.</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>En samling av <link linkend="fdl-document">dokumentet</link> eller av dess derivat med andra separata och oberoende dokument eller verk, på eller i en lagringsvolym eller ett spridningsmedium, kallas för en <quote>sammanslagning</quote> 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å <link linkend="fdl-cover-texts">omslagstexter</link> enligt <link linkend="fdl-section3">paragraf 3</link> ä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.</para>
    </sect1>
    
  <sect1 id="fdl-section8">
    <title>8. ÖVERSÄTTNING</title>
    <para>Översättning anses vara en sorts förändring, så du äger sprida översättningar av <link linkend="fdl-document">dokumentet</link> enligt de villkor som sätts i <link linkend="fdl-section4">paragraf 4</link>. <link linkend="fdl-invariant">Oföränderliga avsnitt</link> 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.</para>
    </sect1>
    
  <sect1 id="fdl-section9">
    <title>9. UPPHÖRANDE</title>
    <para>Du äger inte kopiera, förändra, omlicensiera eller sprida <link linkend="fdl-document">dokumentet</link> 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.</para>
    </sect1>
    
  <sect1 id="fdl-section10">
    <title>10. FRAMTIDA VERSIONER AV DENNA LICENS</title>
    <para><ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software Foundation</ulink> 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 <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.</para>
    
    <para>Varje version av licensen ges ett unikt versionsnummer. Om <link linkend="fdl-document">dokumentet</link> stadgar att en specifik numrerad version av denna licens <quote>eller valfri senare version</quote> 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.</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>Om du inte har några <link linkend="fdl-invariant">oföränderliga avsnitt</link>, skriv <quote>with no Invariant Sections</quote> istället för att ange vilka som är oföränderliga. Om du inte har några <link linkend="fdl-cover-texts">framsidestexter</link>, skriv <quote>no Front-Cover Texts</quote> istället för <quote>Front-Cover Texts being LIST</quote>; såväl som för <link linkend="fdl-cover-texts">baksidestexter</link>.</para>
    
    <para>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 <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html">GNU General Public License</ulink>, för att möjliggöra deras användning i fri programvara.</para>
  </sect1>
</appendix>  








</book>