~noskcaj/ubuntu/utopic/gtk-doc/1.21 : revision 27

1

<?xml version="1.0" encoding="utf-8" standalone="no"?>

2

<?xml-stylesheet type="text/xml" href="params.xsl"?>

3

4

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "

5

http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [

6

<!ENTITY FDL SYSTEM "fdl-appendix.xml">

7

<!ENTITY FDLlink "<link linkend='fdl'>included</link>">

8

]>

9

10

11

12

<title>GTK-Doc Manual</title>

13

14

<abstract role="description"><para>User manual for developers with instructions of GTK-Doc usage.</para></abstract>

15

16

17

<firstname>Chris</firstname>

18

<surname>Lyttle</surname>

19

20

21

<email>chris@wilddev.net</email>

22

</address>

23

</affiliation>

24

</author>

25

26

27

<surname>Mueth</surname>

28

29

30

<email>d-mueth@uchicago.edu</email>

31

</address>

32

</affiliation>

33

</author>

34

35

<firstname>Stefan</firstname>

36

37

38

39

<email>ensonic@users.sf.net</email>

40

</address>

41

</affiliation>

42

</author>

43

</authorgroup>

44

45

<publishername>GTK-Doc project</publishername>

46

<address><email>gtk-doc-list@gnome.org</email></address>

47

</publisher>

48

49

50

<holder>Dan Mueth and Chris Lyttle</holder>

51

</copyright>

52

53

54

<holder>Stefan Sauer (Kost)</holder>

55

</copyright>

56

57

<!-- translators: uncomment this:

58

59

60

<holder>ME-THE-TRANSLATOR (Latin translation)</holder>

61

</copyright>

62

-->

63

64

65

<para>

66

Permission is granted to copy, distribute and/or modify this

67

document under the terms of the <citetitle>GNU Free Documentation

68

License</citetitle>, Version 1.1 or any later version published

69

by the Free Software Foundation with no Invariant Sections, no

70

Front-Cover Texts, and no Back-Cover Texts. A copy of the license

71

is <link linkend="fdl">included</link>.

72

</para>

73

<para>

74

Many of the names used by companies to distinguish their products and

75

services are claimed as trademarks. Where those names appear in any

76

GNOME documentation, and those trademarks are made aware to the members

77

of the GNOME Documentation Project, the names have been printed in caps

78

or initial caps.

79

</para>

80

</legalnotice>

81

82

83

84

85

86

87

<revremark>bug fixes</revremark>

88

</revision>

89

90

91

92

93

<revremark>bug fixes, speedups, markdown support</revremark>

94

</revision>

95

96

97

98

99

<revremark>urgent bug fix update</revremark>

100

</revision>

101

102

103

104

105

<revremark>bugfixes, layout improvements</revremark>

106

</revision>

107

108

109

110

111

<revremark>bug and regression fixes</revremark>

112

</revision>

113

114

115

<date>28 March 2010</date>

116

117

<revremark>bugfixes and performance improvements</revremark>

118

</revision>

119

120

121

<date>18 December 2009</date>

122

123

<revremark>broken tarball update</revremark>

124

</revision>

125

126

127

<date>18 December 2009</date>

128

129

<revremark>new tool features and bugfixes</revremark>

130

</revision>

131

132

133

<date>16 November 2008</date>

134

135

<revremark>GNOME doc-utils migration</revremark>

136

</revision>

137

</revhistory>

138

139

</bookinfo>

140

141

142

143

144

145

146

<para>

147

This chapter introduces GTK-Doc and gives an overview of what it is and

148

how it is used.

149

</para>

150

151

152

153

154

<para>

155

GTK-Doc is used to document C code. It is typically used to document the public

156

API of libraries, such as the GTK+ and GNOME libraries. But it can also be

157

used to document application code.

158

</para>

159

</sect1>

160

161

162

163

164

<para>

165

GTK-Doc works by using documentation of functions placed inside the source files in

166

specially-formatted comment blocks, or documentation added to the template files

167

which GTK-Doc uses (though note that GTK-Doc will only document functions that

168

are declared in header files; it won't produce output for static functions).

169

</para>

170

171

<para>

172

GTK-Doc consists of a number of perl scripts, each performing a different step

173

in the process.

174

</para>

175

176

<para>

177

There are 5 main steps in the process:

178

</para>

179

180

181

182

183

<para>

184

<guilabel>Writing the documentation.</guilabel>

185

186

The author fills in the source files with the documentation for each

187

function, macro, union etc. (In the past information was entered in

188

generated template files, which is not recommended anymore).

189

</para>

190

</listitem>

191

192

193

<para>

194

<guilabel>Gathering information about the code.</guilabel>

195

196

<application>gtkdoc-scan</application> scans the header files of the

197

code looking for declarations of functions, macros, enums, structs, and unions.

198

It creates the file <filename><module>-decl-list.txt</filename> containing a list of the

199

declarations, placing them into sections according to which header file they

200

are in. On the first run this file is copied to <filename><module>-sections.txt</filename>.

201

The author can rearrange the sections, and the order of the

202

declarations within them, to produce the final desired order.

203

The second file it generates is <filename><module>-decl.txt</filename>.

204

This file contains the full declarations found by the scanner. If for

205

some reason one would like some symbols to show up in the docs, where

206

the full declaration cannot be found by the scanner or the declaration

207

should appear differently, one can place entities similar to the ones in

208

<filename><module>-decl.txt</filename> into <filename><module>-overrides.txt</filename>.

209

</para>

210

<para>

211

<application>gtkdoc-scangobj</application> can also be used to dynamically query a library about

212

any GObject subclasses it exports. It saves information about each

213

object's position in the class hierarchy and about any GObject properties

214

and signals it provides.

215

</para>

216

<para>

217

<application>gtkdoc-scanobj</application> should not be used anymore.

218

It was needed in the past when GObject was still GtkObject inside gtk+.

219

</para>

220

</listitem>

221

222

223

<para>

224

<guilabel>Generating the "template" files.</guilabel>

225

226

<application>gtkdoc-mktmpl</application> creates a number of files in

227

the <filename class="directory">tmpl/</filename> subdirectory, using the

228

information gathered in the first step. (Note that this can be run

229

repeatedly. It will try to ensure that no documentation is ever lost.)

230

</para>

231

<note>

232

<para>

233

Since GTK-Doc 1.9 the templates can be avoided. We encourage people to keep

234

documentation in the code. <application>gtkdocize</application> supports now

235

a <option>--flavour no-tmpl</option> option that chooses a makefile that

236

skips tmpl usage totally.

237

If you have never changed file in tmpl by hand, please remove the directory

238

(e.g. from version control system).

239

</para>

240

</note>

241

</listitem>

242

243

244

<para>

245

<guilabel>Generating the SGML/XML and HTML/PDF.</guilabel>

246

247

<application>gtkdoc-mkdb</application> turns the template files into

248

SGML or XML files in the <filename class="directory">sgml/</filename>

249

or <filename class="directory">xml/</filename> subdirectory.

250

If the source code contains documentation on functions, using the

251

special comment blocks, it gets merged in here. If there are no tmpl files used

252

it only reads docs from sources and introspection data. We recommend

253

to use Docbook XML.

254

</para>

255

<para>

256

<application>gtkdoc-mkhtml</application> turns the SGML/XML files into HTML

257

files in the <filename class="directory">html/</filename> subdirectory.

258

Likewise <application>gtkdoc-mkpdf</application> turns the SGML/XML files into a PDF

259

document called <filename><package>.pdf</filename>.

260

</para>

261

<para>

262

Files in <filename class="directory">sgml/</filename> or

263

264

directories are always overwritten. One should never edit them directly.

265

</para>

266

</listitem>

267

268

269

<para>

270

<guilabel>Fixing up cross-references between documents.</guilabel>

271

272

After installing the HTML files, <application>gtkdoc-fixxref</application> can be run to fix up any

273

cross-references between separate documents. For example, the GTK+

274

documentation contains many cross-references to types documented in the GLib manual.

275

276

When creating the source tarball for distribution, <application>gtkdoc-rebase</application>

277

turns all external links into web-links. When installing distributed (pregenerated) docs

278

the same application will try to turn links back to local links

279

(where those docs are installed).

280

</para>

281

</listitem>

282

</orderedlist>

283

284

</sect1>

285

286

287

<title>Getting GTK-Doc</title>

288

289

290

<title>Requirements</title>

291

<para>

292

<guilabel>Perl v5</guilabel> - the main scripts are in Perl.

293

</para>

294

<para>

295

<guilabel>DocBook DTD v3.0</guilabel> - This is the DocBook SGML DTD.

296

<ulink url="http://www.ora.com/davenport" type="http">http://www.ora.com/davenport</ulink>

297

</para>

298

<para>

299

<guilabel>Jade v1.1</guilabel> - This is a DSSSL processor for converting SGML to various formats.

300

<ulink url="http://www.jclark.com/jade" type="http">http://www.jclark.com/jade</ulink>

301

</para>

302

<para>

303

<guilabel>Modular DocBook Stylesheets</guilabel>

304

This is the DSSSL code to convert DocBook to HTML (and a few other

305

formats). It's used together with jade.

306

I've customized the DSSSL code slightly, in gtk-doc.dsl, to colour

307

the program code listings/declarations, and to support global

308

cross-reference indices in the generated HTML.

309

<ulink url="http://nwalsh.com/docbook/dsssl" type="http">http://nwalsh.com/docbook/dsssl</ulink>

310

</para>

311

<para>

312

<guilabel>docbook-to-man</guilabel> - if you want to create man pages from the DocBook.

313

I've customized the 'translation spec' slightly, to capitalise section

314

headings and add the 'GTK Library' title at the top of the pages and the

315

revision date at the bottom.

316

There is a link to this on <ulink url="http://www.ora.com/davenport" type="http">http://www.ora.com/davenport</ulink>

317

NOTE: This does not work yet.

318

</para>

319

</sect2>

320

321

322

<title>Installation</title>

323

<para>

324

There is no standard place where the DocBook Modular Stylesheets are installed.

325

</para>

326

<para>

327

GTK-Doc's configure script searches these 3 directories automatically:

328

</para>

329

<para>

330

<filename> /usr/lib/sgml/stylesheets/nwalsh-modular </filename> (used by RedHat)

331

</para>

332

<para>

333

<filename> /usr/lib/dsssl/stylesheets/docbook </filename> (used by Debian)

334

</para>

335

<para>

336

<filename> /usr/share/sgml/docbkdsl </filename> (used by SuSE)

337

</para>

338

<para>

339

If you have the stylesheets installed somewhere else, you need to configure

340

GTK-Doc using the option:

341

<command> --with-dsssl-dir=<PATH_TO_TOPLEVEL_STYLESHEETS_DIR> </command>

342

</para>

343

</sect2>

344

345

</sect1>

346

347

<!-- not realy worth a section

348

349

350

351

<para>

352

(What things GTK-Doc should, and shouldn't, be used for.)

353

(- ???)

354

(- non C-based projects)

355

(+ Tutorials)

356

</para>

357

358

</sect1>

359

-->

360

361

362

<title>About GTK-Doc</title>

363

364

<para>

365

(FIXME)

366

</para>

367

368

<para>

369

(History, authors, web pages, license, future plans,

370

comparison with other similar systems.)

371

</para>

372

373

</sect1>

374

375

376

<title>About this Manual</title>

377

378

<para>

379

(FIXME)

380

</para>

381

382

<para>

383

(who it is meant for, where you can get it, license)

384

</para>

385

386

</sect1>

387

388

</chapter>

389

390

391

<title>Setting up your project</title>

392

393

<para>

394

The next sections describe what steps to perform to integrate GTK-Doc into

395

your project. Theses sections assume we work on a project called 'meep'.

396

This project contains a library called 'libmeep' and

397

an end-user app called 'meeper'. We also assume you will be using autoconf

398

and automake. In addition section <link linkend="plain_makefiles">plain

399

makefiles or other build systems</link> will describe the basics needed to

400

work in a different build setup.

401

</para>

402

403

404

<title>Setting up a skeleton documentation</title>

405

406

<para>

407

Under your top-level project directory create folders called docs/reference

408

(this way you can also have docs/help for end-user documentation).

409

It is recommended to create another subdirectory with the name of the doc-package.

410

For packages with just one library this step is not necessary.

411

</para>

412

413

<para>

414

This can then look as shown below:

415

<example><title>Example directory structure</title>

416

417

<![CDATA[

418

meep/

419

docs/

420

reference/

421

libmeep/

422

meeper/

423

src/

424

libmeep/

425

meeper/

426

]]>

427

</programlisting>

428

</example>

429

</para>

430

</sect1>

431

432

433

<title>Integration with autoconf</title>

434

435

<para>

436

Very easy! Just add one line to your <filename>configure.ac</filename> script.

437

</para>

438

439

<para>

440

<example><title>Integration with autoconf</title>

441

442

<![CDATA[

443

# check for gtk-doc

444

GTK_DOC_CHECK([1.14],[--flavour no-tmpl])

445

]]>

446

</programlisting>

447

</example>

448

</para>

449

450

<para>

451

This will require all developers to have gtk-doc installed. If it is

452

okay for your project to have optional api-doc build setup, you can

453

solve this as below. Keep it as is, as gtkdocize is looking for

454

<function>GTK_DOC_CHECK</function> at the start of a line.

455

<example><title>Keep gtk-doc optional</title>

456

457

<![CDATA[

458

# check for gtk-doc

459

m4_ifdef([GTK_DOC_CHECK], [

460

GTK_DOC_CHECK([1.14],[--flavour no-tmpl])

461

],[

462

AM_CONDITIONAL([ENABLE_GTK_DOC], false)

463

])

464

]]>

465

</programlisting>

466

</example>

467

</para>

468

469

<para>

470

The first argument is used to check for the gtkdocversion at configure time.

471

The 2nd, optional argument is used by <application>gtkdocize</application>.

472

The <symbol>GTK_DOC_CHECK</symbol> macro also adds several configure switches:

473

</para>

474

475

<listitem><para>--with-html-dir=PATH : path to installed docs</para></listitem>

476

<listitem><para>--enable-gtk-doc : use gtk-doc to build documentation [default=no]</para></listitem>

477

<listitem><para>--enable-gtk-doc-html : build documentation in html format [default=yes]</para></listitem>

478

<listitem><para>--enable-gtk-doc-pdf : build documentation in pdf format [default=no]</para></listitem>

479

</orderedlist>

480

481

482

<para>

483

GTK-Doc is disabled by default! Remember to pass the option

484

<option>'--enable-gtk-doc'</option> to the next

485

<filename>configure</filename> run. Otherwise pregenerated documentation is installed

486

(which makes sense for users but not for developers).

487

</para>

488

</important>

489

490

<para>

491

Furthermore it is recommended that you have the following line inside

492

you <filename>configure.ac</filename> script.

493

This allows <application>gtkdocize</application> to automatically copy the

494

macro definition for <function>GTK_DOC_CHECK</function> to your project.

495

</para>

496

497

<para>

498

<example><title>Preparation for gtkdocize</title>

499

500

<![CDATA[

501

AC_CONFIG_MACRO_DIR(m4)

502

]]>

503

</programlisting>

504

</example>

505

</para>

506

</sect1>

507

508

509

<title>Integration with automake</title>

510

511

<para>

512

First copy the <filename>Makefile.am</filename> from the examples subdirectory of the gtkdoc-sources

513

to your project's API documentation directory (

514

<filename class="directory">./docs/reference/<package></filename>).

515

If you have multiple doc-packages repeat this for each one.

516

</para>

517

518

<para>

519

The next step is to edit the settings inside the <filename>Makefile.am</filename>.

520

All the settings have a comment above that describes their purpose.

521

Most settings are extra flags passed to the respective tools. Every tool

522

has a variable of the form <option><TOOLNAME>_OPTIONS</option>.

523

All the tools support <option>--help</option> to list the supported

524

parameters.

525

</para>

526

527

528

529

<para>

530

You may also want to enable GTK-Doc for the distcheck make target. Just

531

add the one line shown in the next example to your top-level

532

<filename>Makefile.am</filename>:

533

</para>

534

535

<para>

536

<example><title>Enable GTK-Doc during make distcheck</title>

537

538

<![CDATA[

539

DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc

540

]]>

541

</programlisting>

542

</example>

543

</para>

544

545

</sect1>

546

547

548

<title>Integration with autogen</title>

549

550

<para>

551

Most projects will have an <filename>autogen.sh</filename> script to

552

setup the build infrastructure after a checkout from version control

553

system (such as cvs/svn/git). GTK-Doc comes with a tool called

554

<application>gtkdocize</application> which can be used in such a script.

555

It should be run before autoheader, automake or autoconf.

556

</para>

557

558

<para>

559

<example><title>Running gtkdocize from autogen.sh</title>

560

561

<![CDATA[

562

gtkdocize || exit 1

563

]]>

564

</programlisting>

565

</example>

566

</para>

567

568

<para>

569

When running <application>gtkdocize</application> it copies

570

<filename>gtk-doc.make</filename> to your project root (or any directory

571

specified by the <option>--docdir</option> option).

572

It also checks you configure script for the <function>GTK_DOC_CHECK</function>

573

invocation. This macro can be used to pass extra parameters to

574

<application>gtkdocize</application>.

575

</para>

576

577

<para>

578

Historically GTK-Doc was generating template files where developers entered the docs.

579

This turned out to be not so good (e.g. the need for having generated

580

files under version control).

581

Since GTK-Doc 1.9 the tools can get all the information from source comments

582

and thus the templates can be avoided. We encourage people to keep

583

documentation in the code. <application>gtkdocize</application> supports now

584

a <option>--flavour no-tmpl</option> option that chooses a makefile that skips

585

tmpl usage totally. Besides adding the option directly to the command

586

invocation, they can be added also to an environment variable called <symbol>GTKDOCIZE_FLAGS</symbol>

587

or set as a 2nd parameter in <symbol>GTK_DOC_CHECK</symbol> macro in the configure script.

588

If you have never changed file in tmpl by hand and migrating from older gtkdoc versions,

589

please remove the directory (e.g. from version control system).

590

</para>

591

</sect1>

592

593

594

<title>Running the doc build</title>

595

596

<para>

597

After the previous steps it's time to run the build. First we need to

598

rerun <filename>autogen.sh</filename>. If this script runs configure for

599

you, then give it the <option>--enable-gtk-doc</option> option.

600

Otherwise manually run <filename>configure</filename> with this option

601

afterwards.

602

</para>

603

<para>

604

The first make run generates several additional files in the doc-directories.

605

The important ones are:

606

<filename><package>.types</filename>,

607

<filename><package>-docs.xml</filename> (in the past .sgml),

608

<filename><package>-sections.txt</filename>.

609

</para>

610

<para>

611

<example><title>Running the doc build</title>

612

613

<![CDATA[

614

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

615

make

616

]]>

617

</programlisting>

618

</example>

619

</para>

620

<para>

621

Now you can point your browser to <filename>docs/reference/<package>/index.html</filename>.

622

Yes, it's a bit disappointing still. But hang-on, during the next chapter we

623

tell you how to fill the pages with life.

624

</para>

625

</sect1>

626

627

628

<title>Integration with version control systems</title>

629

630

<para>

631

As a rule of the thumb, it's those files you edit, that should go under

632

version control. For typical projects it's these files:

633

<filename><package>.types</filename>,

634

<filename><package>-docs.xml</filename> (in the past .sgml),

635

<filename><package>-sections.txt</filename>,

636

<filename>Makefile.am</filename>

637

</para>

638

</sect1>

639

640

641

<title>Integration with plain makefiles or other build systems</title>

642

643

<para>

644

In the case one does not want to use automake and therefore

645

<filename>gtk-doc.mak</filename> one will need to call the gtkdoc tools

646

in the right order in own makefiles (or other build tools).

647

</para>

648

649

<para>

650

<example><title>Documentation build steps</title>

651

652

<![CDATA[

653

DOC_MODULE=meep

654

// sources have changed

655

gtkdoc-scan --module=$(DOC_MODULE) --source-dir=...

656

gtkdoc-scangobj --module=$(DOC_MODULE)

657

gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml

658

// xml files have changed

659

mkdir html

660

cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml

661

gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html

662

]]>

663

</programlisting>

664

</example>

665

</para>

666

667

<para>

668

One will need to look at the <filename>Makefile.am</filename> and

669

<filename>gtk-doc.mak</filename> to pick the extra options needed.

670

</para>

671

</sect1>

672

673

</chapter>

674

675

676

<title>Documenting the code</title>

677

678

<para>

679

GTK-Doc uses source code comment with a special syntax for code documentation.

680

Further it retrieves information about your project structure from other

681

sources. During the next section you will find all information about the

682

syntax of the comments.

683

</para>

684

685

<note>

686

<title>Documentation placement</title>

687

<para>

688

In the past most documentation had to be filled into files residing

689

inside the <filename>tmpl</filename> directory. This has the

690

disadvantages that the information is often not updated and also that

691

the file tend to cause conflicts with version control systems.

692

</para>

693

<para>

694

The avoid the aforementioned problems we suggest putting the

695

documentation inside the sources. This manual will only describe this

696

way of documenting code.

697

</para>

698

</note>

699

700

<para>

701

The scanner can handle the majority of C headers fine. In the case of

702

receiving warnings from the scanner that look like a special case, one can

703

hint GTK-Doc to skip over them.

704

<example><title>GTK-Doc comment block</title>

705

706

<![CDATA[

707

#ifndef __GTK_DOC_IGNORE__

708

/* unparseable code here */

709

#endif

710

]]>

711

</programlisting>

712

</example>

713

</para>

714

715

716

717

718

<title>Documentation comments</title>

719

720

<para>

721

A multiline comment that starts with an additional '*' marks a

722

documentation block that will be processed by the GTK-Doc tools.

723

<example><title>GTK-Doc comment block</title>

724

725

<![CDATA[

726

/**

727

* identifier:

728

* documentation ...

729

*/

730

]]>

731

</programlisting>

732

</example>

733

</para>

734

735

<para>

736

The 'identifier' is one line with the name of the item the comment is

737

related to. The syntax differs a little depending on the item.

738

(TODO add table showing identifiers)

739

</para>

740

741

<para>

742

The 'documentation' block is also different for each symbol type. Symbol

743

types that get parameters such as functions or macros have the parameter

744

description first followed by a blank line (just a '*').

745

Afterwards follows the detailed description. All lines (outside program

746

listings and CDATA sections) just containing a ' *' (blank-asterisk) are

747

converted to paragraph breaks.

748

If you don't want a paragraph break, change that into ' * '

749

(blank-asterisk-blank-blank). This is useful in preformatted text (code

750

listings).

751

</para>

752

753

<tip>

754

<para>

755

When documenting code, describe two aspects:

756

757

758

<para>

759

What it is: The name for a class or function can sometimes

760

be misleading for people coming from a different background.

761

</para>

762

</listitem>

763

764

<para>

765

What it does: Tell about common uses. Put it in relation

766

with the other API.

767

</para>

768

</listitem>

769

</itemizedlist>

770

</para>

771

</tip>

772

773

<para>

774

One advantage of hyper-text over plain-text is the ability to have links

775

in the document. Writing the correct markup for a link can be tedious

776

though. GTK-Doc comes to help by providing several useful abbreviations.

777

778

779

<para>

780

Use function() to refer to functions or macros which take arguments.

781

</para>

782

</listitem>

783

784

<para>

785

Use @param to refer to parameters. Also use this when referring to

786

parameters of other functions, related to the one being described.

787

</para>

788

</listitem>

789

790

<para>

791

Use %constant to refer to a constant, e.g. %G_TRAVERSE_LEAFS.

792

</para>

793

</listitem>

794

795

<para>

796

Use #symbol to refer to other types of symbol, e.g. structs and

797

enums and macros which don't take arguments.

798

</para>

799

</listitem>

800

801

<para>

802

Use #Object::signal to refer to a GObject signal.

803

</para>

804

</listitem>

805

806

<para>

807

Use #Object:property to refer to a GObject property.

808

</para>

809

</listitem>

810

811

<para>

812

Use #Struct.field to refer to a field inside a structure.

813

</para>

814

</listitem>

815

</itemizedlist>

816

</para>

817

818

<tip>

819

<para>

820

If you need to use the special characters '<', '>', '()', '@',

821

'%', or '#' in your documentation without GTK-Doc changing them you

822

can use the XML entities "&lt;", "&gt;", "&lpar;",

823

"&rpar;", "&commat;", "&percnt;" and "&num;"

824

respectively or escape them with a backslash '\'.

825

</para>

826

</tip>

827

828

<para>

829

DocBook can do more than just links. One can also have lists, tables and

830

examples. To enable the usage of docbook SGML/XML tags inside

831

doc-comments you need to have <option>--xml-mode</option> or

832

<option>--sgml-mode</option> in the variable

833

<symbol>MKDB_OPTIONS</symbol> inside <filename>Makefile.am</filename>.

834

</para>

835

836

<para>

837

Since GTK-Doc-1.18 the tool supports a subset or the

838

<ulink url="http://daringfireball.net/projects/markdown/">markdown language</ulink>.

839

One can use it for sub-headings and simple itemized lists. On older

840

GTK-Doc versions the content will be rendered as it (the list items will

841

appear in one line separated by dashes).

842

<example><title>GTK-Doc comment block using markdown</title>

843

844

<![CDATA[

845

/**

846

* identifier:

847

*

848

* documentation ...

849

*

850

* # Sub heading #

851

*

852

* more documentation:

853

* - list item 1

854

* - list item 2

855

*

856

* Even more docs.

857

*/

858

]]>

859

</programlisting>

860

</example>

861

</para>

862

863

<tip>

864

<para>

865

As already mentioned earlier GTK-Doc is for documenting public API. Thus

866

one cannot write documentation for static symbols. Nevertheless it is good

867

to comment those symbols too. This helps other to understand you code.

868

Therefore we recommend to comment these using normal comments (without the

869

2nd '*' in the first line).

870

If later the function needs to be made public, all one needs to do is to

871

add another '*' in the comment block and insert the symbol name at the

872

right place inside the sections file.

873

</para>

874

</tip>

875

</sect1>

876

877

878

<title>Documenting sections</title>

879

880

<para>

881

Each section of the documentation contains information about one class

882

or module. To introduce the component one can write a section block.

883

The short description is also used inside the table of contents.

884

All the @fields are optional.

885

</para>

886

887

<para>

888

<example><title>Section comment block</title>

889

890

<![CDATA[

891

/**

892

* SECTION:meepapp

893

* @short_description: the application class

894

* @title: Meep application

895

* @section_id:

896

* @see_also: #MeepSettings

897

* @stability: Stable

898

* @include: meep/app.h

899

* @image: application.png

900

*

901

* The application class handles ...

902

*/

903

]]>

904

</programlisting>

905

</example>

906

</para>

907

908

909

910

<term>SECTION:<name></term>

911

912

<para>

913

The name links the section documentation to the respective part in

914

the <filename><package>-sections.txt</filename> file. The

915

name give here should match the <FILE> tag in the

916

<filename><package>-sections.txt</filename> file.

917

</para>

918

</listitem>

919

</varlistentry>

920

921

<term>@short_description</term>

922

923

<para>

924

A one line description of the section, that later will appear after

925

the links in the TOC and at the top of the section page.

926

</para>

927

</listitem>

928

</varlistentry>

929

930

<term>@title</term>

931

932

<para>

933

The section title defaults to <name> from the SECTION

934

declaration. It can be overridden with the @title field.

935

</para>

936

</listitem>

937

</varlistentry>

938

939

<term>@section_id</term>

940

941

<para>

942

Overrides the use of title as a section identifier. For GObjects

943

the <title> is used as a section_id and for other sections

944

it is <MODULE>-<title>.

945

</para>

946

</listitem>

947

</varlistentry>

948

949

950

951

<para>

952

A list of symbols that are related to this section.

953

</para>

954

</listitem>

955

</varlistentry>

956

957

<term>@stability</term>

958

959

<para>

960

An informal description of the stability level this API has.

961

We recommend the use of one of these terms:

962

963

964

<para>

965

Stable

966

- The intention of a Stable interface is to enable arbitrary

967

third parties to develop applications to these interfaces,

968

release them, and have confidence that they will run on all

969

minor releases of the product (after the one in which the

970

interface was introduced, and within the same major release).

971

Even at a major release, incompatible changes are expected

972

to be rare, and to have strong justifications.

973

</para>

974

</listitem>

975

976

<para>

977

Unstable

978

- Unstable interfaces are experimental or transitional.

979

They are typically used to give outside developers early

980

access to new or rapidly changing technology, or to provide

981

an interim solution to a problem where a more general

982

solution is anticipated.

983

No claims are made about either source or binary

984

compatibility from one minor release to the next.

985

</para>

986

</listitem>

987

988

<para>

989

Private

990

- An interface that can be used within the GNOME stack

991

itself, but that is not documented for end-users. Such

992

functions should only be used in specified and documented

993

ways.

994

</para>

995

</listitem>

996

997

<para>

998

Internal

999

- An interface that is internal to a module and does not

1000

require end-user documentation. Functions that are

1001

undocumented are assumed to be Internal.

1002

</para>

1003

</listitem>

1004

</itemizedlist>

1005

</para>

1006

</listitem>

1007

</varlistentry>

1008

1009

<term>@include</term>

1010

1011

<para>

1012

The <literal>#include</literal> files to show in the section

1013

synopsis (a comma separated list), overriding the global

1014

value from the <link linkend="metafiles_sections">section

1015

file</link> or command line. This item is optional.

1016

</para>

1017

</listitem>

1018

</varlistentry>

1019

1020

<term>@image</term>

1021

1022

<para>

1023

The image to display at the top of the reference page for this

1024

section. This will often be some sort of a diagram to illustrate

1025

the visual appearance of a class or a diagram of its relationship

1026

to other classes. This item is optional.

1027

</para>

1028

</listitem>

1029

</varlistentry>

1030

</variablelist>

1031

1032

<tip>

1033

<para>

1034

To avoid unnecessary recompilation after doc-changes put the section

1035

docs into the c-source where possible.

1036

</para>

1037

</tip>

1038

1039

</sect1>

1040

1041

1042

<title>Documenting symbols</title>

1043

1044

<para>

1045

Each symbol (function, macro, struct, enum, signal and property) is

1046

documented in a separate block. The block is best placed close to the

1047

definition of the symbols so that it is easy to keep them in sync.

1048

Thus functions are usually documented in the c-source and macros,

1049

structs and enums in the header file.

1050

</para>

1051

1052

<sect2><title>General tags</title>

1053

1054

<para>

1055

You can add versioning information to all documentation elements to tell

1056

when an API was introduced, or when it was deprecated.

1057

</para>

1058

1059

<variablelist><title>Versioning Tags</title>

1060

<varlistentry><term>Since:</term>

1061

1062

<para>

1063

Description since which version of the code the API is available.

1064

</para>

1065

</listitem>

1066

</varlistentry>

1067

<varlistentry><term>Deprecated:</term>

1068

1069

<para>

1070

Paragraph denoting that this function should no be used anymore.

1071

The description should point the reader to the new API.

1072

</para>

1073

</listitem>

1074

</varlistentry>

1075

</variablelist>

1076

1077

<para>

1078

(FIXME : Stability information)

1079

</para>

1080

1081

<example><title>General tags</title>

1082

1083

<![CDATA[

1084

/**

1085

* foo_get_bar:

1086

* @foo: some foo

1087

*

1088

* Retrieves @foo's bar.

1089

*

1090

* Returns: @foo's bar

1091

*

1092

* Since: 2.6

1093

* Deprecated: 2.12: Use foo_baz_get_bar() instead.

1094

*/

1095

Bar *

1096

foo_get_bar(Foo *foo)

1097

{

1098

...

1099

]]>

1100

</programlisting>

1101

</example>

1102

</sect2>

1103

1104

<sect2><title>Function comment block</title>

1105

1106

<para>

1107

Please remember to:

1108

1109

1110

<para>

1111

Document whether returned objects, lists, strings, etc, should be

1112

freed/unrefed/released.

1113

</para>

1114

</listitem>

1115

1116

<para>

1117

Document whether parameters can be NULL, and what happens if they are.

1118

</para>

1119

</listitem>

1120

1121

<para>

1122

Mention interesting pre-conditions and post-conditions where appropriate.

1123

</para>

1124

</listitem>

1125

</itemizedlist>

1126

</para>

1127

1128

<para>

1129

Gtk-doc assumes all symbols (macros, functions) starting with '_' are

1130

private. They are treated like static functions.

1131

</para>

1132

1133

<para>

1134

<!-- FIXME: we should ideally link/describe the gobject introspection

1135

annotation tag -->

1136

Also, take a look at GObject Introspection annotation tags:

1137

http://live.gnome.org/GObjectIntrospection/Annotations

1138

</para>

1139

1140

<example><title>Function comment block</title>

1141

1142

<![CDATA[

1143

/**

1144

* function_name:

1145

* @par1: description of parameter 1. These can extend over more than

1146

* one line.

1147

* @par2: description of parameter 2

1148

* @...: a %NULL-terminated list of bars

1149

*

1150

* The function description goes here. You can use @par1 to refer to parameters

1151

* so that they are highlighted in the output. You can also use %constant

1152

* for constants, function_name2() for functions and #GtkWidget for links to

1153

* other declarations (which may be documented elsewhere).

1154

*

1155

* Returns: an integer.

1156

*

1157

* Since: 2.2

1158

* Deprecated: 2.18: Use other_function() instead.

1159

*/

1160

]]>

1161

</programlisting>

1162

</example>

1163

1164

<variablelist><title>Function tags</title>

1165

<varlistentry><term>Returns:</term>

1166

1167

<para>

1168

Paragraph describing the returned result.

1169

</para>

1170

</listitem>

1171

</varlistentry>

1172

1173

1174

<para>

1175

In case the function has variadic arguments, you should use this

1176

tag (@Varargs: does also work for historic reasons).

1177

</para>

1178

</listitem>

1179

</varlistentry>

1180

</variablelist>

1181

1182

</sect2>

1183

1184

<sect2><title>Property comment block</title>

1185

1186

<example><title>Property comment block</title>

1187

1188

<![CDATA[

1189

/**

1190

* SomeWidget:some-property:

1191

*

1192

* Here you can document a property.

1193

*/

1194

g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);

1195

]]>

1196

</programlisting>

1197

</example>

1198

1199

</sect2>

1200

1201

<sect2><title>Signal comment block</title>

1202

1203

<para>

1204

Please remember to:

1205

1206

1207

<para>

1208

Document when the signal is emitted and whether it is emitted before

1209

or after other signals.

1210

</para>

1211

</listitem>

1212

1213

<para>

1214

Document what an application might do in the signal handler.

1215

</para>

1216

</listitem>

1217

</itemizedlist>

1218

</para>

1219

1220

<example><title>Signal comment block</title>

1221

1222

<![CDATA[

1223

/**

1224

* FooWidget::foobarized:

1225

* @widget: the widget that received the signal

1226

* @foo: some foo

1227

* @bar: some bar

1228

*

1229

* The ::foobarized signal is emitted each time someone tries to foobarize @widget.

1230

*/

1231

foo_signals[FOOBARIZE] =

1232

g_signal_new ("foobarize",

1233

...

1234

]]>

1235

</programlisting>

1236

</example>

1237

1238

</sect2>

1239

1240

<sect2><title>Struct comment block</title>

1241

<example><title>Struct comment block</title>

1242

1243

<![CDATA[

1244

/**

1245

* FooWidget:

1246

* @bar: some #gboolean

1247

*

1248

* This is the best widget, ever.

1249

*/

1250

typedef struct _FooWidget {

1251

/*< private >*/

1252

GtkWidget parent;

1253

1254

/*< public >*/

1255

gboolean bar;

1256

} FooWidget;

1257

]]>

1258

</programlisting>

1259

</example>

1260

1261

<para>

1262

Use <code>/*< private >*/</code> before the private struct fields

1263

you want to hide. Use <code>/*< public >*/</code> for the reverse

1264

behaviour.

1265

</para>

1266

1267

<para>

1268

Struct comment blocks can also be used for GObjects and GObjectClasses.

1269

It is usually a good idea to add a comment block for a class, if it has

1270

vmethods (as this is how they can be documented). For the GObject

1271

itself one can use the related section docs, having a separate block

1272

for the instance struct would be useful if the instance has public

1273

fields. One disadvantage here is that this creates two index entries

1274

of the same name (the structure and the section).

1275

</para>

1276

1277

</sect2>

1278

1279

<sect2><title>Enum comment block</title>

1280

<example><title>Enum comment block</title>

1281

1282

<![CDATA[

1283

/**

1284

* Something:

1285

* @SOMETHING_FOO: something foo

1286

* @SOMETHING_BAR: something bar

1287

*

1288

* Enum values used for the thing, to specify the thing.

1289

*/

1290

typedef enum {

1291

SOMETHING_FOO,

1292

SOMETHING_BAR,

1293

/*< private >*/

1294

SOMETHING_COUNT

1295

} Something;

1296

]]>

1297

</programlisting>

1298

</example>

1299

1300

<para>

1301

Use <code>/*< private >*/</code> before the private enum values

1302

you want to hide. Use <code>/*< public >*/</code> for the reverse

1303

behaviour.

1304

</para>

1305

1306

</sect2>

1307

</sect1>

1308

1309

1310

<title>Useful DocBook tags</title>

1311

1312

<para>

1313

Here are some DocBook tags which are most useful when documenting the

1314

code.

1315

</para>

1316

1317

<para>

1318

To link to another section in the GTK docs:

1319

1320

1321

1322

<![CDATA[

1323

1324

]]>

1325

</programlisting>

1326

</informalexample>

1327

The linkend is the SGML/XML id on the top item of the page you want to link to.

1328

For most pages this is currently the part ("gtk", "gdk", "glib") and then

1329

the page title ("Hash Tables"). For widgets it is just the class name.

1330

Spaces and underscores are converted to '-' to conform to SGML/XML.

1331

</para>

1332

1333

<para>

1334

To refer to an external function, e.g. a standard C function:

1335

1336

1337

<![CDATA[

1338

1339

]]>

1340

</programlisting>

1341

</informalexample>

1342

</para>

1343

1344

<para>

1345

To include example code:

1346

1347

1348

<![CDATA[

1349

1350

<title>Using a GHashTable.</title>

1351

1352

...

1353

</programlisting>

1354

</example>

1355

]]>

1356

</programlisting>

1357

</informalexample>

1358

or possibly this, for very short code fragments which don't need a title:

1359

1360

1361

<![CDATA[

1362

1363

1364

...

1365

</programlisting>

1366

</informalexample>

1367

]]>

1368

</programlisting>

1369

</informalexample>

1370

For the latter GTK-Doc also supports an abbreviation:

1371

<![CDATA[

1372

|[

1373

...

1374

]|

1375

]]>

1376

</para>

1377

1378

<para>

1379

To include bulleted lists:

1380

1381

1382

<![CDATA[

1383

1384

1385

<para>

1386

...

1387

</para>

1388

</listitem>

1389

1390

<para>

1391

...

1392

</para>

1393

</listitem>

1394

</itemizedlist>

1395

]]>

1396

</programlisting>

1397

</informalexample>

1398

</para>

1399

1400

<para>

1401

To include a note which stands out from the text:

1402

1403

1404

<![CDATA[

1405

<note>

1406

<para>

1407

Make sure you free the data after use.

1408

</para>

1409

</note>

1410

]]>

1411

</programlisting>

1412

</informalexample>

1413

</para>

1414

1415

<para>

1416

To refer to a type:

1417

1418

1419

<![CDATA[

1420

<type>unsigned char</type>

1421

]]>

1422

</programlisting>

1423

</informalexample>

1424

</para>

1425

1426

<para>

1427

To refer to an external structure (not one described in the GTK docs):

1428

1429

1430

<![CDATA[

1431

<structname>XFontStruct</structname>

1432

]]>

1433

</programlisting>

1434

</informalexample>

1435

</para>

1436

1437

<para>

1438

To refer to a field of a structure:

1439

1440

1441

<![CDATA[

1442

1443

]]>

1444

</programlisting>

1445

</informalexample>

1446

</para>

1447

1448

<para>

1449

To refer to a class name, we could possibly use:

1450

1451

1452

<![CDATA[

1453

<classname>GtkWidget</classname>

1454

]]>

1455

</programlisting>

1456

</informalexample>

1457

but you'll probably be using #GtkWidget instead (to automatically create

1458

a link to the GtkWidget page - see <link linkend="documenting_syntax">the abbreviations</link>).

1459

</para>

1460

1461

<para>

1462

To emphasize text:

1463

1464

1465

<![CDATA[

1466

<emphasis>This is important</emphasis>

1467

]]>

1468

</programlisting>

1469

</informalexample>

1470

</para>

1471

1472

<para>

1473

For filenames use:

1474

1475

1476

<![CDATA[

1477

<filename>/home/user/documents</filename>

1478

]]>

1479

</programlisting>

1480

</informalexample>

1481

</para>

1482

1483

<para>

1484

To refer to keys use:

1485

1486

1487

<![CDATA[

1488

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

1489

]]>

1490

</programlisting>

1491

</informalexample>

1492

</para>

1493

1494

</sect1>

1495

</chapter>

1496

1497

1498

<title>Filling the extra files</title>

1499

1500

<para>

1501

There are a couple of extra files, that need to be maintained along with

1502

the inline source code comments:

1503

<filename><package>.types</filename>,

1504

<filename><package>-docs.xml</filename> (in the past .sgml),

1505

<filename><package>-sections.txt</filename>.

1506

</para>

1507

1508

1509

<title>Editing the types file</title>

1510

1511

<para>

1512

If your library or application includes GObjects, you want

1513

their signals, arguments/parameters and position in the hierarchy to be

1514

shown in the documentation. All you need to do, is to list the

1515

<function>xxx_get_type</function> functions together with their include

1516

inside the <filename><package>.types</filename> file.

1517

</para>

1518

1519

<para>

1520

<example><title>Example types file snippet</title>

1521

1522

<![CDATA[

1523

#include <gtk/gtk.h>

1524

1525

gtk_accel_label_get_type

1526

gtk_adjustment_get_type

1527

gtk_alignment_get_type

1528

gtk_arrow_get_type

1529

]]>

1530

</programlisting>

1531

</example>

1532

</para>

1533

1534

<para>

1535

Since GTK-Doc 1.8 <application>gtkdoc-scan</application> can generate this list for you.

1536

Just add "--rebuild-types" to SCAN_OPTIONS in <filename>Makefile.am</filename>. If you

1537

use this approach you should not dist the types file nor have it under version control.

1538

</para>

1539

1540

</sect1>

1541

1542

1543

<title>Editing the master document</title>

1544

1545

<para>

1546

GTK-Doc produces documentation in DocBook SGML/XML. When processing the

1547

inline source comments, the GTK-Doc tools generate one documentation

1548

page per class or module as a separate file. The master document

1549

includes them and place them in an order.

1550

</para>

1551

1552

<para>

1553

While GTK-Doc creates a template master document for you, later run will

1554

not touch it again. This means that one can freely structure the

1555

documentation. That includes grouping pages and adding extra pages.

1556

GTK-Doc has now a test suite, where also the master-document is recreated from scratch.

1557

Its a good idea to look at this from time to time to see if there are some new goodies

1558

introduced there.

1559

</para>

1560

1561

<tip>

1562

<para>

1563

Do not create tutorials as extra documents. Just write extra chapters.

1564

The benefit of directly embedding the tutorial for your library into

1565

the API documentation is that it is easy to link for the tutorial to

1566

symbol documentation. Apart chances are higher that the tutorial gets

1567

updates along with the library.

1568

</para>

1569

</tip>

1570

1571

<para>

1572

So what are the things to change inside the master document? For a start

1573

is only a little. There are some placeholders (text in square brackets)

1574

there which you should take care of.

1575

</para>

1576

1577

<para>

1578

<example><title>Master document header</title>

1579

1580

<![CDATA[

1581

1582

<title>MODULENAME Reference Manual</title>

1583

1584

for MODULENAME [VERSION]

1585

The latest version of this documentation can be found on-line at

1586

<ulink role="online-location" url="http://[SERVER]/MODULENAME/index.html">http://[SERVER]/MODULENAME/</ulink>.

1587

</releaseinfo>

1588

</bookinfo>

1589

1590

1591

<title>[Insert title here]</title>

1592

]]>

1593

</programlisting>

1594

</example>

1595

</para>

1596

1597

</sect1>

1598

1599

1600

<title>Editing the section file</title>

1601

1602

<para>

1603

The section file is used to organise the documentation output by

1604

GTK-Doc. Here one specifies which symbol belongs to which module or

1605

class and control the visibility (public or private).

1606

</para>

1607

1608

<para>

1609

The section file is a plain text file with XML-like syntax (using tags).

1610

Blank lines are ignored and lines starting with a '#' are treated as

1611

comment lines.

1612

</para>

1613

1614

<para>

1615

The <FILE> ... </FILE> tag is used to specify the file name,

1616

without any suffix. For example, using '<FILE>gnome-config</FILE>'

1617

will result in the section declarations being output in the template

1618

file <filename>tmpl/gnome-config.sgml</filename>, which will be

1619

converted into the DocBook SGML/XML file <filename>sgml/gnome-config.sgml</filename>

1620

or the DocBook XML file <filename>xml/gnome-config.xml</filename>.

1621

(The name of the HTML file is based on the module name and the section

1622

title, or for GObjects it is based on the GObjects class name converted

1623

to lower case).

1624

</para>

1625

1626

<para>

1627

The <TITLE> ... </TITLE> tag is used to specify the title of

1628

the section. It is only useful before the templates (if used) are

1629

initially created, since the title set in the template file overrides

1630

this. Also if one uses SECTION comment in the sources, this is obsolete.

1631

</para>

1632

1633

<para>

1634

You can group items in the section by using the <SUBSECTION> tag.

1635

Currently it outputs a blank line between subsections in the synopsis

1636

section.

1637

You can also use <SUBSECTION Standard> for standard GObject

1638

declarations (e.g. the functions like g_object_get_type and macros like

1639

G_OBJECT(), G_IS_OBJECT() etc.).

1640

Currently these are left out of the documentation.

1641

You can also use <SUBSECTION Private> for private declarations

1642

which will not be output (it is a handy way to avoid warning messages

1643

about unused declarations).

1644

If your library contains private types which you don't want to appear in

1645

the object hierarchy and the list of implemented or required interfaces,

1646

add them to a Private subsection.

1647

Whether you would place GObject and GObjectClass like structs in public

1648

or Standard section depends if they have public entries (variables,

1649

vmethods).

1650

</para>

1651

1652

<para>

1653

You can also use <INCLUDE> ... </INCLUDE> to specify the

1654

#include files which are shown in the synopsis sections.

1655

It contains a comma-separate list of #include files, without the angle

1656

brackets. If you set it outside of any sections, it acts for all

1657

sections until the end of the file. If you set it within a section, it

1658

only applies to that section.

1659

</para>

1660

1661

</sect1>

1662

1663

</chapter>

1664

1665

1666

<title>Controlling the result</title>

1667

1668

<para>

1669

A GTK-Doc run generates report files inside the documentation directory.

1670

The generated files are named:

1671

<filename><package>-undocumented.txt</filename>,

1672

<filename><package>-undeclared.txt</filename> and

1673

<filename><package>-unused.txt</filename>.

1674

All those are plain text files that can be viewed and postprocessed easily.

1675

</para>

1676

1677

<para>

1678

The <filename><package>-undocumented.txt</filename> file starts with

1679

the documentation coverage summary. Below are two sections divided by

1680

blank lines. The first section lists undocumented or incomplete symbols.

1681

The second section does the same for section docs. Incomplete entries are

1682

those, which have documentation, but where e.g. a new parameter has been

1683

added.

1684

</para>

1685

1686

<para>

1687

The <filename><package>-undeclared.txt</filename> file lists symbols

1688

given in the <filename><package>-sections.txt</filename> but not

1689

found in the sources. Check if they have been removed or if they are

1690

misspelled.

1691

</para>

1692

1693

<para>

1694

The <filename><package>-unused.txt</filename> file lists symbol

1695

names, where the GTK-Doc scanner has found documentation, but does not

1696

know where to put it. This means that the symbol has not yet been added to

1697

the <filename><package>-sections.txt</filename> file.

1698

</para>

1699

1700

<tip>

1701

<para>

1702

Enable or add the <option>TESTS=$(GTKDOC_CHECK)</option> line in Makefile.am.

1703

If at least GTK-Doc 1.9 is installed, this will run sanity checks during

1704

<command>make check</command> run.

1705

</para>

1706

</tip>

1707

1708

<para>

1709

One can also look at the files produced by the source code scanner:

1710

<filename><package>-decl-list.txt</filename> and

1711

<filename><package>-decl.txt</filename>. The first one can be

1712

compared with the section file if that is manually maintained. The second

1713

lists all declarations from the headers. If a symbol is missing one could

1714

check if this file contains it.

1715

</para>

1716

1717

<para>

1718

If the project is GObject based, one can also look into the files produced

1719

by the object scanner:

1720

<filename><package>.args.txt</filename>,

1721

<filename><package>.hierarchy.txt</filename>,

1722

<filename><package>.interfaces.txt</filename>,

1723

<filename><package>.prerequisites.txt</filename> and

1724

<filename><package>.signals.txt</filename>. If there are missing

1725

symbols in any of those, one can ask gtkdoc to keep the intermediate scanner

1726

file for further analysis, by running it as

1727

<command>GTK_DOC_KEEP_INTERMEDIATE=1 make</command>.

1728

</para>

1729

</chapter>

1730

1731

1732

<title>Documenting other interfaces</title>

1733

1734

<para>

1735

So far we have been using GTK-Doc to document the API of code. The next

1736

sections contain suggestions how the tools can be used to document other

1737

interfaces too.

1738

</para>

1739

1740

1741

<title>Command line options and man pages</title>

1742

1743

<para>

1744

As one can generate man pages for a docbook refentry as well, it sounds

1745

like a good idea to use it for that purpose. This way the interface is

1746

part of the reference and one gets the man-page for free.

1747

</para>

1748

1749

1750

<title>Document the tool</title>

1751

1752

<para>

1753

Create one refentry file per tool. Following

1754

1755

<filename>meep/docs/reference/meeper/meep.xml</filename>. For the xml

1756

tags that should be used and can look at generated file in the xml

1757

subdirectory as well as examples e.g. in glib.

1758

</para>

1759

</sect2>

1760

1761

1762

<title>Adding the extra configure check</title>

1763

1764

<para>

1765

<example><title>Extra configure checks</title>

1766

1767

<![CDATA[

1768

AC_ARG_ENABLE(man,

1769

[AC_HELP_STRING([--enable-man],

1770

[regenerate man pages from Docbook [default=no]])],enable_man=yes,

1771

enable_man=no)

1772

1773

AC_PATH_PROG([XSLTPROC], [xsltproc])

1774

AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno)

1775

]]>

1776

</programlisting>

1777

</example>

1778

</para>

1779

</sect2>

1780

1781

1782

<title>Adding the extra makefile rules</title>

1783

1784

<para>

1785

<example><title>Extra configure checks</title>

1786

1787

<![CDATA[

1788

man_MANS = \

1789

meeper.1

1790

1791

if ENABLE_GTK_DOC

1792

if ENABLE_MAN

1793

1794

%.1 : %.xml

1795

@XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<

1796

1797

endif

1798

endif

1799

1800

BUILT_EXTRA_DIST = $(man_MANS)

1801

EXTRA_DIST += meep.xml

1802

]]>

1803

</programlisting>

1804

</example>

1805

</para>

1806

</sect2>

1807

</sect1>

1808

1809

1810

<title>DBus interfaces</title>

1811

1812

<para>

1813

(FIXME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html,

1814

http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus)

1815

</para>

1816

</sect1>

1817

1818

</chapter>

1819

1820

1821

<title>Frequently asked questions</title>

1822

1823

1824

<?dbhtml list-presentation="list"?>

1825

<segtitle>Vprašanje</segtitle>

1826

<segtitle>Odgovor</segtitle>

1827

1828

<seg>No class hierarchy.</seg>

1829

<seg>

1830

The objects <function>xxx_get_type()</function> function has not been

1831

entered into the <filename><package>.types</filename> file.

1832

</seg>

1833

</seglistitem>

1834

1835

<seg>Still no class hierarchy.</seg>

1836

<seg>

1837

Missing or wrong naming in <filename><package>-sections.txt</filename>

1838

file (see <ulink url="http://mail.gnome.org/archives/gtk-doc-list/2003-October/msg00006.html">explanation</ulink>).

1839

</seg>

1840

</seglistitem>

1841

1842

<seg>Damn, I have still no class hierarchy.</seg>

1843

<seg>

1844

Is the object name (name of the instance struct, e.g. <type>GtkWidget</type>)

1845

part of the normal section (don't put this into Standard or Private

1846

subsections).

1847

</seg>

1848

</seglistitem>

1849

1850

<seg>No symbol index.</seg>

1851

<seg>

1852

Does the <filename><package>-docs.{xml,sgml}</filename> contain a

1853

index that xi:includes the generated index?

1854

</seg>

1855

</seglistitem>

1856

1857

<seg>Symbols are not linked to their doc-section.</seg>

1858

<seg>

1859

Is the doc-comment using the correct markup (added #,% or ())?

1860

Check if the gtkdoc-fixxref warns about unresolvable xrefs.

1861

</seg>

1862

</seglistitem>

1863

1864

<seg>A new class does not appear in the docs.</seg>

1865

<seg>

1866

Is the new page xi:included from

1867

<filename><package>-docs.{xml,sgml}</filename>.

1868

</seg>

1869

</seglistitem>

1870

1871

<seg>A new symbol does not appear in the docs.</seg>

1872

<seg>

1873

Is the doc-comment properly formatted. Check for spelling mistakes in

1874

the begin of the comment. Check if the gtkdoc-fixxref warns about

1875

unresolvable xrefs. Check if the symbol is correctly listed in the

1876

<filename><package>-sections.txt</filename> in a public subsection.

1877

</seg>

1878

</seglistitem>

1879

1880

<seg>A type is missing from the class hierarchy.</seg>

1881

<seg>

1882

If the type is listed in <filename><package>.hierarchy</filename>

1883

but not in <filename>xml/tree_index.sgml</filename> then double check

1884

that the type is correctly placed in the <filename><package>-sections.txt</filename>.

1885

If the type instance (e.g. <type>GtkWidget</type>) is not listed or

1886

incidentialy makred private it will not be shown.

1887

</seg>

1888

</seglistitem>

1889

1890

<seg>I get foldoc links for all gobject annotations.</seg>

1891

<seg>

1892

Check that <filename>xml/annotation-glossary.xml</filename> is

1893

xi:included from <filename><package>-docs.{xml,sgml}</filename>.

1894

</seg>

1895

</seglistitem>

1896

1897

1898

1899

<seg>Parameter described in source code comment block but does not exist</seg>

1900

<seg>Check if the prototype in the header has different parameter names as in the source.</seg>

1901

</seglistitem>

1902

1903

1904

1905

<seg>multiple "IDs" for constraint linkend: XYZ</seg>

1906

<seg>Symbol XYZ appears twice in <filename><package>-sections.txt</filename> file.</seg>

1907

</seglistitem>

1908

1909

<seg>Element typename in namespace '' encountered in para, but no template matches.</seg>

1910

<seg/>

1911

</seglistitem>

1912

</segmentedlist>

1913

</chapter>

1914

1915

1916

<title>Tools related to gtk-doc</title>

1917

1918

<para>

1919

GtkDocPlugin - a <ulink url="http://trac-hacks.org/wiki/GtkDocPlugin">Trac GTK-Doc</ulink>

1920

integration plugin, that adds API docs to a trac site and integrates with

1921

the trac search.

1922

</para>

1923

<para>

1924

Gtkdoc-depscan - a tool (part of gtk-doc) to check used API against since

1925

tags in the API to determine the minimum required version.

1926

</para>

1927

1928

</chapter>

1929

1930

1931

<!--

1932

The GNU Free Documentation License 1.1 in DocBook

1933

Markup by Eric Baudais <baudais@okstate.edu>

1934

Maintained by the GNOME Documentation Project

1935

http://developer.gnome.org/projects/gdp

1936

Version: 1.0.1

1937

Last Modified: Nov 16, 2000

1938

-->

1939

1940

1941

1942

1943

Version 1.1, March 2000

1944

</releaseinfo>

1945

1946

<year>2000</year><holder>Free Software Foundation, Inc.</holder>

1947

</copyright>

1948

1949

<para>

1950

<address>Free Software Foundation, Inc. <street>51 Franklin Street,

1951

Suite 330</street>, <city>Boston</city>, <state>MA</state>

1952

1953

Everyone is permitted to copy and distribute verbatim copies of this

1954

license document, but changing it is not allowed.

1955

</para>

1956

</legalnotice>

1957

</appendixinfo>

1958

<title>GNU Free Documentation License</title>

1959

1960

1961

<title>0. PREAMBLE</title>

1962

<para>

1963

The purpose of this License is to make a manual, textbook, or

1964

other written document <quote>free</quote> in the sense of

1965

freedom: to assure everyone the effective freedom to copy and

1966

redistribute it, with or without modifying it, either

1967

commercially or noncommercially. Secondarily, this License

1968

preserves for the author and publisher a way to get credit for

1969

their work, while not being considered responsible for

1970

modifications made by others.

1971

</para>

1972

1973

<para>

1974

This License is a kind of <quote>copyleft</quote>, which means

1975

that derivative works of the document must themselves be free in

1976

the same sense. It complements the GNU General Public License,

1977

which is a copyleft license designed for free software.

1978

</para>

1979

1980

<para>

1981

We have designed this License in order to use it for manuals for

1982

free software, because free software needs free documentation: a

1983

free program should come with manuals providing the same

1984

freedoms that the software does. But this License is not limited

1985

to software manuals; it can be used for any textual work,

1986

regardless of subject matter or whether it is published as a

1987

printed book. We recommend this License principally for works

1988

whose purpose is instruction or reference.

1989

</para>

1990

</sect1>

1991

1992

<title>1. APPLICABILITY AND DEFINITIONS</title>

1993

1994

This License applies to any manual or other work that contains a

1995

notice placed by the copyright holder saying it can be

1996

distributed under the terms of this License. The

1997

<quote>Document</quote>, below, refers to any such manual or

1998

work. Any member of the public is a licensee, and is addressed

1999

as <quote>you</quote>.

2000

</para>

2001

2002

2003

A <quote>Modified Version</quote> of the Document means any work

2004

containing the Document or a portion of it, either copied

2005

verbatim, or with modifications and/or translated into another

2006

language.

2007

</para>

2008

2009

2010

A <quote>Secondary Section</quote> is a named appendix or a

2011

front-matter section of the <link linkend="fdl-document">Document</link> that deals exclusively

2012

with the relationship of the publishers or authors of the

2013

Document to the Document's overall subject (or to related

2014

matters) and contains nothing that could fall directly within

2015

that overall subject. (For example, if the Document is in part a

2016

textbook of mathematics, a Secondary Section may not explain any

2017

mathematics.) The relationship could be a matter of historical

2018

connection with the subject or with related matters, or of

2019

legal, commercial, philosophical, ethical or political position

2020

regarding them.

2021

</para>

2022

2023

2024

The <quote>Invariant Sections</quote> are certain <link linkend="fdl-secondary"> Secondary Sections</link> whose titles

2025

are designated, as being those of Invariant Sections, in the

2026

notice that says that the <link linkend="fdl-document">Document</link> is released under this

2027

License.

2028

</para>

2029

2030

2031

The <quote>Cover Texts</quote> are certain short passages of

2032

text that are listed, as Front-Cover Texts or Back-Cover Texts,

2033

in the notice that says that the <link linkend="fdl-document">Document</link> is released under this

2034

License.

2035

</para>

2036

2037

2038

A <quote>Transparent</quote> copy of the <link linkend="fdl-document"> Document</link> means a machine-readable

2039

copy, represented in a format whose specification is available

2040

to the general public, whose contents can be viewed and edited

2041

directly and straightforwardly with generic text editors or (for

2042

images composed of pixels) generic paint programs or (for

2043

drawings) some widely available drawing editor, and that is

2044

suitable for input to text formatters or for automatic

2045

translation to a variety of formats suitable for input to text

2046

formatters. A copy made in an otherwise Transparent file format

2047

whose markup has been designed to thwart or discourage

2048

subsequent modification by readers is not Transparent. A copy

2049

that is not <quote>Transparent</quote> is called

2050

<quote>Opaque</quote>.

2051

</para>

2052

2053

<para>

2054

Examples of suitable formats for Transparent copies include

2055

plain ASCII without markup, Texinfo input format, LaTeX input

2056

format, SGML or XML using a publicly available DTD, and

2057

standard-conforming simple HTML designed for human

2058

modification. Opaque formats include PostScript, PDF,

2059

proprietary formats that can be read and edited only by

2060

proprietary word processors, SGML or XML for which the DTD

2061

and/or processing tools are not generally available, and the

2062

machine-generated HTML produced by some word processors for

2063

output purposes only.

2064

</para>

2065

2066

2067

The <quote>Title Page</quote> means, for a printed book, the

2068

title page itself, plus such following pages as are needed to

2069

hold, legibly, the material this License requires to appear in

2070

the title page. For works in formats which do not have any title

2071

page as such, <quote>Title Page</quote> means the text near the

2072

most prominent appearance of the work's title, preceding the

2073

beginning of the body of the text.

2074

</para>

2075

</sect1>

2076

2077

2078

<title>2. VERBATIM COPYING</title>

2079

<para>

2080

You may copy and distribute the <link linkend="fdl-document">Document</link> in any medium, either

2081

commercially or noncommercially, provided that this License, the

2082

copyright notices, and the license notice saying this License

2083

applies to the Document are reproduced in all copies, and that

2084

you add no other conditions whatsoever to those of this

2085

License. You may not use technical measures to obstruct or

2086

control the reading or further copying of the copies you make or

2087

distribute. However, you may accept compensation in exchange for

2088

copies. If you distribute a large enough number of copies you

2089

must also follow the conditions in <link linkend="fdl-section3">section 3</link>.

2090

</para>

2091

2092

<para>

2093

You may also lend copies, under the same conditions stated

2094

above, and you may publicly display copies.

2095

</para>

2096

</sect1>

2097

2098

2099

<title>3. COPYING IN QUANTITY</title>

2100

<para>

2101

If you publish printed copies of the <link linkend="fdl-document">Document</link> numbering more than 100,

2102

and the Document's license notice requires <link linkend="fdl-cover-texts">Cover Texts</link>, you must enclose

2103

the copies in covers that carry, clearly and legibly, all these

2104

Cover Texts: Front-Cover Texts on the front cover, and

2105

Back-Cover Texts on the back cover. Both covers must also

2106

clearly and legibly identify you as the publisher of these

2107

copies. The front cover must present the full title with all

2108

words of the title equally prominent and visible. You may add

2109

other material on the covers in addition. Copying with changes

2110

limited to the covers, as long as they preserve the title of the

2111

2112

conditions, can be treated as verbatim copying in other

2113

respects.

2114

</para>

2115

2116

<para>

2117

If the required texts for either cover are too voluminous to fit

2118

legibly, you should put the first ones listed (as many as fit

2119

reasonably) on the actual cover, and continue the rest onto

2120

adjacent pages.

2121

</para>

2122

2123

<para>

2124

If you publish or distribute <link linkend="fdl-transparent">Opaque</link> copies of the <link linkend="fdl-document">Document</link> numbering more than 100,

2125

you must either include a machine-readable <link linkend="fdl-transparent">Transparent</link> copy along with

2126

each Opaque copy, or state in or with each Opaque copy a

2127

publicly-accessible computer-network location containing a

2128

complete Transparent copy of the Document, free of added

2129

material, which the general network-using public has access to

2130

download anonymously at no charge using public-standard network

2131

protocols. If you use the latter option, you must take

2132

reasonably prudent steps, when you begin distribution of Opaque

2133

copies in quantity, to ensure that this Transparent copy will

2134

remain thus accessible at the stated location until at least one

2135

year after the last time you distribute an Opaque copy (directly

2136

or through your agents or retailers) of that edition to the

2137

public.

2138

</para>

2139

2140

<para>

2141

It is requested, but not required, that you contact the authors

2142

of the <link linkend="fdl-document">Document</link> well before

2143

redistributing any large number of copies, to give them a chance

2144

to provide you with an updated version of the Document.

2145

</para>

2146

</sect1>

2147

2148

2149

<title>4. MODIFICATIONS</title>

2150

<para>

2151

You may copy and distribute a <link linkend="fdl-modified">Modified Version</link> of the <link linkend="fdl-document">Document</link> under the conditions of

2152

sections <link linkend="fdl-section2">2</link> and <link linkend="fdl-section3">3</link> above, provided that you release

2153

the Modified Version under precisely this License, with the

2154

Modified Version filling the role of the Document, thus

2155

licensing distribution and modification of the Modified Version

2156

to whoever possesses a copy of it. In addition, you must do

2157

these things in the Modified Version:

2158

</para>

2159

2160

2161

2162

2163

2164

<para>

2165

Use in the <link linkend="fdl-title-page">Title

2166

Page</link> (and on the covers, if any) a title distinct

2167

from that of the <link linkend="fdl-document">Document</link>, and from those of

2168

previous versions (which should, if there were any, be

2169

listed in the History section of the Document). You may

2170

use the same title as a previous version if the original

2171

publisher of that version gives permission.

2172

</para>

2173

</formalpara>

2174

</listitem>

2175

2176

2177

2178

2179

<para>

2180

List on the <link linkend="fdl-title-page">Title

2181

Page</link>, as authors, one or more persons or entities

2182

responsible for authorship of the modifications in the

2183

2184

together with at least five of the principal authors of

2185

the <link linkend="fdl-document">Document</link> (all of

2186

its principal authors, if it has less than five).

2187

</para>

2188

</formalpara>

2189

</listitem>

2190

2191

2192

2193

2194

<para>

2195

State on the <link linkend="fdl-title-page">Title

2196

Page</link> the name of the publisher of the <link linkend="fdl-modified">Modified Version</link>, as the

2197

publisher.

2198

</para>

2199

</formalpara>

2200

</listitem>

2201

2202

2203

2204

2205

<para>

2206

Preserve all the copyright notices of the <link linkend="fdl-document">Document</link>.

2207

</para>

2208

</formalpara>

2209

</listitem>

2210

2211

2212

2213

2214

<para>

2215

Add an appropriate copyright notice for your modifications

2216

adjacent to the other copyright notices.

2217

</para>

2218

</formalpara>

2219

</listitem>

2220

2221

2222

2223

2224

<para>

2225

Include, immediately after the copyright notices, a

2226

license notice giving the public permission to use the

2227

2228

the terms of this License, in the form shown in the

2229

Addendum below.

2230

</para>

2231

</formalpara>

2232

</listitem>

2233

2234

2235

2236

2237

<para>

2238

Preserve in that license notice the full lists of <link linkend="fdl-invariant"> Invariant Sections</link> and

2239

required <link linkend="fdl-cover-texts">Cover

2240

Texts</link> given in the <link linkend="fdl-document">Document's</link> license notice.

2241

</para>

2242

</formalpara>

2243

</listitem>

2244

2245

2246

2247

2248

<para>

2249

Include an unaltered copy of this License.

2250

</para>

2251

</formalpara>

2252

</listitem>

2253

2254

2255

2256

2257

<para>

2258

Preserve the section entitled <quote>History</quote>, and

2259

its title, and add to it an item stating at least the

2260

title, year, new authors, and publisher of the <link linkend="fdl-modified">Modified Version</link> as given on

2261

the <link linkend="fdl-title-page">Title Page</link>. If

2262

there is no section entitled <quote>History</quote> in the

2263

2264

stating the title, year, authors, and publisher of the

2265

Document as given on its Title Page, then add an item

2266

describing the Modified Version as stated in the previous

2267

sentence.

2268

</para>

2269

</formalpara>

2270

</listitem>

2271

2272

2273

2274

2275

<para>

2276

Preserve the network location, if any, given in the <link linkend="fdl-document">Document</link> for public access

2277

to a <link linkend="fdl-transparent">Transparent</link>

2278

copy of the Document, and likewise the network locations

2279

given in the Document for previous versions it was based

2280

on. These may be placed in the <quote>History</quote>

2281

section. You may omit a network location for a work that

2282

was published at least four years before the Document

2283

itself, or if the original publisher of the version it

2284

refers to gives permission.

2285

</para>

2286

</formalpara>

2287

</listitem>

2288

2289

2290

2291

2292

<para>

2293

In any section entitled <quote>Acknowledgements</quote> or

2294

<quote>Dedications</quote>, preserve the section's title,

2295

and preserve in the section all the substance and tone of

2296

each of the contributor acknowledgements and/or

2297

dedications given therein.

2298

</para>

2299

</formalpara>

2300

</listitem>

2301

2302

2303

2304

2305

<para>

2306

Preserve all the <link linkend="fdl-invariant">Invariant

2307

Sections</link> of the <link linkend="fdl-document">Document</link>, unaltered in their

2308

text and in their titles. Section numbers or the

2309

equivalent are not considered part of the section titles.

2310

</para>

2311

</formalpara>

2312

</listitem>

2313

2314

2315

2316

2317

<para>

2318

Delete any section entitled

2319

<quote>Endorsements</quote>. Such a section may not be

2320

included in the <link linkend="fdl-modified">Modified

2321

Version</link>.

2322

</para>

2323

</formalpara>

2324

</listitem>

2325

2326

2327

2328

2329

<para>

2330

Do not retitle any existing section as

2331

<quote>Endorsements</quote> or to conflict in title with

2332

any <link linkend="fdl-invariant">Invariant

2333

Section</link>.

2334

</para>

2335

</formalpara>

2336

</listitem>

2337

</itemizedlist>

2338

2339

<para>

2340

If the <link linkend="fdl-modified">Modified Version</link>

2341

includes new front-matter sections or appendices that qualify as

2342

2343

contain no material copied from the Document, you may at your

2344

option designate some or all of these sections as invariant. To

2345

do this, add their titles to the list of <link linkend="fdl-invariant">Invariant Sections</link> in the

2346

Modified Version's license notice. These titles must be

2347

distinct from any other section titles.

2348

</para>

2349

2350

<para>

2351

You may add a section entitled <quote>Endorsements</quote>,

2352

provided it contains nothing but endorsements of your <link linkend="fdl-modified">Modified Version</link> by various

2353

parties--for example, statements of peer review or that the text

2354

has been approved by an organization as the authoritative

2355

definition of a standard.

2356

</para>

2357

2358

<para>

2359

You may add a passage of up to five words as a <link linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage

2360

of up to 25 words as a <link linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of

2361

the list of <link linkend="fdl-cover-texts">Cover Texts</link>

2362

in the <link linkend="fdl-modified">Modified Version</link>.

2363

Only one passage of Front-Cover Text and one of Back-Cover Text

2364

may be added by (or through arrangements made by) any one

2365

entity. If the <link linkend="fdl-document">Document</link>

2366

already includes a cover text for the same cover, previously

2367

added by you or by arrangement made by the same entity you are

2368

acting on behalf of, you may not add another; but you may

2369

replace the old one, on explicit permission from the previous

2370

publisher that added the old one.

2371

</para>

2372

2373

<para>

2374

The author(s) and publisher(s) of the <link linkend="fdl-document">Document</link> do not by this License

2375

give permission to use their names for publicity for or to

2376

assert or imply endorsement of any <link linkend="fdl-modified">Modified Version </link>.

2377

</para>

2378

</sect1>

2379

2380

2381

<title>5. COMBINING DOCUMENTS</title>

2382

<para>

2383

You may combine the <link linkend="fdl-document">Document</link>

2384

with other documents released under this License, under the

2385

terms defined in <link linkend="fdl-section4">section 4</link>

2386

above for modified versions, provided that you include in the

2387

combination all of the <link linkend="fdl-invariant">Invariant

2388

Sections</link> of all of the original documents, unmodified,

2389

and list them all as Invariant Sections of your combined work in

2390

its license notice.

2391

</para>

2392

2393

<para>

2394

The combined work need only contain one copy of this License,

2395

and multiple identical <link linkend="fdl-invariant">Invariant

2396

Sections</link> may be replaced with a single copy. If there are

2397

multiple Invariant Sections with the same name but different

2398

contents, make the title of each such section unique by adding

2399

at the end of it, in parentheses, the name of the original

2400

author or publisher of that section if known, or else a unique

2401

number. Make the same adjustment to the section titles in the

2402

list of Invariant Sections in the license notice of the combined

2403

work.

2404

</para>

2405

2406

<para>

2407

In the combination, you must combine any sections entitled

2408

<quote>History</quote> in the various original documents,

2409

forming one section entitled <quote>History</quote>; likewise

2410

combine any sections entitled <quote>Acknowledgements</quote>,

2411

and any sections entitled <quote>Dedications</quote>. You must

2412

delete all sections entitled <quote>Endorsements.</quote>

2413

</para>

2414

</sect1>

2415

2416

2417

<title>6. COLLECTIONS OF DOCUMENTS</title>

2418

<para>

2419

You may make a collection consisting of the <link linkend="fdl-document">Document</link> and other documents

2420

released under this License, and replace the individual copies

2421

of this License in the various documents with a single copy that

2422

is included in the collection, provided that you follow the

2423

rules of this License for verbatim copying of each of the

2424

documents in all other respects.

2425

</para>

2426

2427

<para>

2428

You may extract a single document from such a collection, and

2429

dispbibute it individually under this License, provided you

2430

insert a copy of this License into the extracted document, and

2431

follow this License in all other respects regarding verbatim

2432

copying of that document.

2433

</para>

2434

</sect1>

2435

2436

2437

<title>7. AGGREGATION WITH INDEPENDENT WORKS</title>

2438

<para>

2439

A compilation of the <link linkend="fdl-document">Document</link> or its derivatives with

2440

other separate and independent documents or works, in or on a

2441

volume of a storage or distribution medium, does not as a whole

2442

count as a <link linkend="fdl-modified">Modified Version</link>

2443

of the Document, provided no compilation copyright is claimed

2444

for the compilation. Such a compilation is called an

2445

<quote>aggregate</quote>, and this License does not apply to the

2446

other self-contained works thus compiled with the Document , on

2447

account of their being thus compiled, if they are not themselves

2448

derivative works of the Document. If the <link linkend="fdl-cover-texts">Cover Text</link> requirement of <link linkend="fdl-section3">section 3</link> is applicable to these

2449

copies of the Document, then if the Document is less than one

2450

quarter of the entire aggregate, the Document's Cover Texts may

2451

be placed on covers that surround only the Document within the

2452

aggregate. Otherwise they must appear on covers around the whole

2453

aggregate.

2454

</para>

2455

</sect1>

2456

2457

2458

<title>8. TRANSLATION</title>

2459

<para>

2460

Translation is considered a kind of modification, so you may

2461

distribute translations of the <link linkend="fdl-document">Document</link> under the terms of <link linkend="fdl-section4">section 4</link>. Replacing <link linkend="fdl-invariant"> Invariant Sections</link> with

2462

translations requires special permission from their copyright

2463

holders, but you may include translations of some or all

2464

Invariant Sections in addition to the original versions of these

2465

Invariant Sections. You may include a translation of this

2466

License provided that you also include the original English

2467

version of this License. In case of a disagreement between the

2468

translation and the original English version of this License,

2469

the original English version will prevail.

2470

</para>

2471

</sect1>

2472

2473

2474

<title>9. TERMINATION</title>

2475

<para>

2476

You may not copy, modify, sublicense, or distribute the <link linkend="fdl-document">Document</link> except as expressly

2477

provided for under this License. Any other attempt to copy,

2478

modify, sublicense or distribute the Document is void, and will

2479

automatically terminate your rights under this License. However,

2480

parties who have received copies, or rights, from you under this

2481

License will not have their licenses terminated so long as such

2482

parties remain in full compliance.

2483

</para>

2484

</sect1>

2485

2486

2487

<title>10. FUTURE REVISIONS OF THIS LICENSE</title>

2488

<para>

2489

The <ulink type="http" url="http://www.gnu.org/fsf/fsf.html">Free Software

2490

Foundation</ulink> may publish new, revised versions of the GNU

2491

Free Documentation License from time to time. Such new versions

2492

will be similar in spirit to the present version, but may differ

2493

in detail to address new problems or concerns. See <ulink type="http" url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.

2494

</para>

2495

2496

<para>

2497

Each version of the License is given a distinguishing version

2498

number. If the <link linkend="fdl-document">Document</link>

2499

specifies that a particular numbered version of this License

2500

<quote>or any later version</quote> applies to it, you have the

2501

option of following the terms and conditions either of that

2502

specified version or of any later version that has been

2503

published (not as a draft) by the Free Software Foundation. If

2504

the Document does not specify a version number of this License,

2505

you may choose any version ever published (not as a draft) by

2506

the Free Software Foundation.

2507

</para>

2508

</sect1>

2509

2510

2511

<title>Addendum</title>

2512

<para>

2513

To use this License in a document you have written, include a copy of

2514

the License in the document and put the following copyright and

2515

license notices just after the title page:

2516

</para>

2517

2518

2519

<para>

2520

Copyright YEAR YOUR NAME.

2521

</para>

2522

<para>

2523

Permission is granted to copy, distribute and/or modify this

2524

document under the terms of the GNU Free Documentation

2525

License, Version 1.1 or any later version published by the

2526

Free Software Foundation; with the <link linkend="fdl-invariant">Invariant Sections</link> being LIST

2527

THEIR TITLES, with the <link linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST,

2528

and with the <link linkend="fdl-cover-texts">Back-Cover

2529

Texts</link> being LIST. A copy of the license is included in

2530

the section entitled <quote>GNU Free Documentation

2531

License</quote>.

2532

</para>

2533

</blockquote>

2534

2535

<para>

2536

If you have no <link linkend="fdl-invariant">Invariant

2537

Sections</link>, write <quote>with no Invariant Sections</quote>

2538

instead of saying which ones are invariant. If you have no

2539

2540

<quote>no Front-Cover Texts</quote> instead of

2541

<quote>Front-Cover Texts being LIST</quote>; likewise for <link linkend="fdl-cover-texts">Back-Cover Texts</link>.

2542

</para>

2543

2544

<para>

2545

If your document contains nontrivial examples of program code,

2546

we recommend releasing these examples in parallel under your

2547

choice of free software license, such as the <ulink type="http" url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public

2548

License</ulink>, to permit their use in free software.

2549

</para>

2550

</sect1>

2551

</appendix>

2552

2553

2554

2555

2556

2557

2558

2559

2560

</book>